Skip to content

Latest commit

 

History

History
234 lines (172 loc) · 7.68 KB

README.md

File metadata and controls

234 lines (172 loc) · 7.68 KB
Raw

Extism JS SDK

This is a universal JavaScript SDK for Extism. It works in all the major JavaScript runtimes:

  • Browsers (Firefox, Chrome, WebKit)
  • Node
  • Deno
  • Bun
  • Cloudflare Workers
  • interested in others? Let us know!

Instead of using FFI and the libextism shared object, this library uses whatever Wasm runtime is already available with the JavaScript runtime.

Installation

Install via npm:

$ npm install @extism/extism

Note: Keep in mind we will possibly have breaking changes b/w rc versions until we hit 1.0.

Compatibility

  • Node.js: v18+ (with --experimental-global-webcrypto); v20 with no additional flags
  • Deno: v1.36+
  • Bun: Tested on v1.0.7; Bun partially implements WASI.

Browser tests are run using playwright's defaults. In browsers, background thread support requires SharedArrayBuffer and Atomic support. This is only available in crossOriginIsolated contexts.

Reference Docs

Reference docs can be found at https://extism.github.io/js-sdk/.

Getting Started

This guide should walk you through some of the concepts in Extism and this JS library.

First you should import createPlugin from Extism:

// CommonJS
const createPlugin = require("@extism/extism")

// ES Modules/Typescript
import createPlugin from '@extism/extism';

// Deno
import createPlugin from "jsr:@extism/extism";

Creating A Plug-in

The primary concept in Extism is the plug-in. You can think of a plug-in as a code module stored in a .wasm file.

Plug-in code can come from a file on disk, object storage or any number of places. Since you may not have one handy let's load a demo plug-in from the web:

const plugin = await createPlugin(
    'https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm',
    { useWasi: true }
);

Note: Plug-ins can be loaded in a variety of ways. See the reference docs for createPlugin and read about the manifest.

Calling A Plug-in's Exports

We're using a plug-in, count_vowels, which was compiled from Rust. count_vowels plug-in does one thing: it counts vowels in a string. As such, it exposes one "export" function: count_vowels. We can call exports using Plugin.call:

let out = await plugin.call("count_vowels", input);
console.log(out.text())

// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

All plug-in exports have a simple interface of optional bytes in, and optional bytes out. This plug-in happens to take a string and return a JSON encoded string with a report of results.

Plug-in State

Plug-ins may be stateful or stateless. Plug-ins can maintain state between calls by the use of variables. Our count_vowels plug-in remembers the total number of vowels it's ever counted in the total key in the result. You can see this by making subsequent calls to the export:

let out = await plugin.call("count_vowels", "Hello, World!");
console.log(out.text())
// => {"count": 3, "total": 9, "vowels": "aeiouAEIOU"}

out = await plugin.call("count_vowels", "Hello, World!");
console.log(out.json())
// => {"count": 3, "total": 9, "vowels": "aeiouAEIOU"}

These variables will persist until you call await plugin.reset(). Variables are not shared between plugin instances.

Configuration

Plug-ins may optionally take a configuration object. This is a static way to configure the plug-in. Our count-vowels plugin takes an optional configuration to change out which characters are considered vowels. Example:

const wasm = {
    url: 'https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm'
}

let plugin = await createPlugin(wasm, {
    useWasi: true,
});

let out = await plugin.call("count_vowels", "Yellow, World!");
console.log(out.text())
// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

plugin = await createPlugin(wasm, {
    useWasi: true,
    config: { "vowels": "aeiouyAEIOUY" }
});

out = await plugin.call("count_vowels", "Yellow, World!");
console.log(out.text())
// => {"count": 4, "total": 4, "vowels": "aeiouAEIOUY"}

Host Functions

Let's extend our count-vowels example a little bit: Instead of storing the total in an ephemeral plug-in var, let's store it in a persistent key-value store!

Wasm can't use our KV store on it's own. This is where Host Functions come in.

Host functions allow us to grant new capabilities to our plug-ins from our application. They are simply some JS functions you write which can be passed down and invoked from any language inside the plug-in.

Let's load the manifest like usual but load up this count_vowels_kvstore plug-in:

const wasm = {
    url: "https://github.com/extism/plugins/releases/latest/download/count_vowels_kvstore.wasm"
}

Note: The source code for this is here and is written in Rust, but it could be written in any of our PDK languages.

Unlike our previous plug-in, this plug-in expects you to provide host functions that satisfy our its import interface for a KV store.

We want to expose two functions to our plugin, kv_write(key: string, value: Uint8Array) which writes a bytes value to a key and kv_read(key: string): Uint8Array which reads the bytes at the given key.

// pretend this is Redis or something :)
let kvStore = new Map();

const options = {
    useWasi: true,
    functions: {
        "extism:host/user": {
            // NOTE: the first argument is always a CurrentPlugin
            kv_read(cp: CurrentPlugin, offs: bigint) {
                const key = cp.read(offs).text();
                let value = kvStore.get(key) ?? new Uint8Array([0, 0, 0, 0]);
                console.log(`Read ${new DataView(value.buffer).getUint32(0, true)} from key=${key}`);
                return cp.store(value);
            },
            kv_write(cp: CurrentPlugin, kOffs: bigint, vOffs: bigint) {
                const key = cp.read(kOffs).text();

                // Value is a PluginOutput, which subclasses DataView. Along
                // with the `text()` and `json()` methods we've seen, we also
                // get DataView methods, such as `getUint32`.
                const value = cp.read(vOffs);
                console.log(`Writing value=${new value.getUint32(0, true)} from key=${key}`);

                kvStore.set(key, value.bytes());
            }
        }
    }
};

Note: In order to write host functions you should get familiar with the methods on the CurrentPlugin type.

We need to pass these imports to the plug-in to create them. All imports of a plug-in must be satisfied for it to be initialized:

const plugin = await createPlugin(wasm, options);

Now we can invoke the event:

let out = await plugin.call("count_vowels", "Hello World!");
console.log(out.text())
// => Read from key=count-vowels"
// => Writing value=3 from key=count-vowels"
// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

out = await plugin.call("count_vowels", "Hello World!");
console.log(out.text())
// => Read from key=count-vowels"
// => Writing value=6 from key=count-vowels"
// => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}

Run Examples:

npm run build

node --experimental-wasi-unstable-preview1 ./examples/node.js wasm/config.wasm

deno run -A ./examples/deno.ts ./wasm/config.wasm

bun run ./examples/node.js wasm/config.wasm