docs: JS-PDK interface description #16
Conversation
chrisdickinson
left a comment
chrisdickinson
left a comment
There was a problem hiding this comment.
Forgive the all-over-the-place review!
This looks really good; introspecting TypeScript definitions feels like a natural control surface for JS devs to use. Awesome work getting this going!
| ```typescript | ||
| // all extism exports have type () -> i32 | ||
| interface Exports { | ||
| myExport(): I32; | ||
| } | ||
|
|
||
| // this interface is optional and types are defined by you | ||
| // to match your host functions | ||
| interface Imports { | ||
| myHostFunc1(p: I64, q: I32): I64; | ||
| myHostFunc2(p: I64): I64; | ||
| } | ||
| ``` |
There was a problem hiding this comment.
| ```typescript | |
| // all extism exports have type () -> i32 | |
| interface Exports { | |
| myExport(): I32; | |
| } | |
| // this interface is optional and types are defined by you | |
| // to match your host functions | |
| interface Imports { | |
| myHostFunc1(p: I64, q: I32): I64; | |
| myHostFunc2(p: I64): I64; | |
| } | |
| ``` | |
| ```typescript | |
| // modules named like WIT-style packages ("extism:host") declare host function imports | |
| declare module 'extism:host' { // namespace | |
| interface user { | |
| export myHostFunction1(p: I32, q: I32): I32; | |
| export myHostFunction2(p: I32): I64; | |
| } // which tees us up to implement "import { user } from 'extism:host'" | |
| } | |
| // The "main" module declares exports | |
| declare module 'main' { | |
| // all extism exports have type () -> i32 | |
| export function greet(): I32; | |
| } |
| local.get 0 | ||
| (call_indirect (type $int2int) (i32.const 0)) | ||
| ) | ||
| (export "__invokeHostFunc" (func $callHostFunc)) |
There was a problem hiding this comment.
(We talked offline a bit about this, but noting it here for posterity) dispatching based on the different host import type signatures might be a little tricky (but not insurmountable!)
|
|
||
| It exposes this indirect call with __invokeHostFunc which can be used by the | ||
| core quickjs engine module and invoked from javascript. | ||
|
|
There was a problem hiding this comment.
(Another note from offline conversation, saved here for posterity!) There'll be an interesting middle step as we have to partially evaluate the module using Wizer while disabling the host function calls.
(This is probably retreading ground you've already walked, but it'd be interesting to consider whether or not users would want to "stub in" host fn calls made during this partial evaluation – as you noted, Wizer is able to implement stub functions.)
|
|
||
| The programmer will define their interface in a typescript file `interface.d.ts`: | ||
|
|
||
| ```typescript |
There was a problem hiding this comment.
Re: the imports and exports: it might be worth gesturing at future work here – noting that we might do basic mapping of higher-level types like string / Record and that we're leaving it at F32, I32, & friends for now.
|
With Zach's change to support different arities i think this is done extism/js-pdk#48 |
Co-authored-by: Chris Dickinson <chris@neversaw.us>
Co-authored-by: Chris Dickinson <chris@neversaw.us>
Rendered: https://github.com/extism/proposals/blob/js-pdk-host-functions/EIP-009-js-pdk-interface-definition.md