@bytecodealliance/preview2-shim 0.17.2 → 0.17.3

package/lib/synckit/index.js

@@ -23,105 +23,114 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
-import path from "node:path";
+import path from 'node:path';
 import {
-  MessageChannel,
-  Worker,
-  receiveMessageOnPort,
-  workerData,
-  parentPort,
-} from "node:worker_threads";
+    MessageChannel,
+    Worker,
+    receiveMessageOnPort,
+    workerData,
+    parentPort,
+} from 'node:worker_threads';
 
 const DEFAULT_WORKER_BUFFER_SIZE = 1024;
 
 function extractProperties(object) {
-  if (object && typeof object === "object") {
-    const properties = {};
-    for (const key in object) {
-      properties[key] = object[key];
+    if (object && typeof object === 'object') {
+        const properties = {};
+        for (const key in object) {
+            properties[key] = object[key];
+        }
+        return properties;
     }
-    return properties;
-  }
 }
 
 const CALL_TIMEOUT = undefined;
 
 export function createSyncFn(workerPath, debug, callbackHandler) {
-  if (!path.isAbsolute(workerPath)) {
-    throw new Error("`workerPath` must be absolute");
-  }
-  const { port1: mainPort, port2: workerPort } = new MessageChannel();
-  const worker = new Worker(workerPath, {
-    workerData: { workerPort, debug },
-    transferList: [workerPort],
-    execArgv: []
-  });
-  worker.on('message', ({ type, id, payload }) => {
-    if (!type)
-      throw new Error('Internal error: Expected a type of a worker callback');
-    callbackHandler(type, id, payload);
-  });
-  let nextID = 0;
-  const syncFn = (...args) => {
-    const cid = nextID++;
-    const sharedBuffer = new SharedArrayBuffer(DEFAULT_WORKER_BUFFER_SIZE);
-    const sharedBufferView = new Int32Array(sharedBuffer);
-    const msg = { sharedBuffer, cid, args };
-    worker.postMessage(msg);
-    const status = Atomics.wait(sharedBufferView, 0, 0, CALL_TIMEOUT);
-    if (!["ok", "not-equal"].includes(status)) {
-      throw new Error("Internal error: Atomics.wait() failed: " + status);
-    }
-    const {
-      cid: cid2,
-      result,
-      error,
-      properties,
-    } = receiveMessageOnPort(mainPort).message;
-    if (cid !== cid2) {
-      throw new Error(`Internal error: Expected id ${cid} but got id ${cid2}`);
+    if (!path.isAbsolute(workerPath)) {
+        throw new Error('`workerPath` must be absolute');
     }
-    if (error) {
-      if (error instanceof Error) throw Object.assign(error, properties);
-      throw error;
+    const { port1: mainPort, port2: workerPort } = new MessageChannel();
+    const worker = new Worker(workerPath, {
+        workerData: { workerPort, debug },
+        transferList: [workerPort],
+        execArgv: [],
+    });
+    worker.on('message', ({ type, id, payload }) => {
+        if (!type) {
+            throw new Error(
+                'Internal error: Expected a type of a worker callback'
+            );
+        }
+        callbackHandler(type, id, payload);
+    });
+    let nextID = 0;
+    const syncFn = (...args) => {
+        const cid = nextID++;
+        const sharedBuffer = new SharedArrayBuffer(DEFAULT_WORKER_BUFFER_SIZE);
+        const sharedBufferView = new Int32Array(sharedBuffer);
+        const msg = { sharedBuffer, cid, args };
+        worker.postMessage(msg);
+        const status = Atomics.wait(sharedBufferView, 0, 0, CALL_TIMEOUT);
+        if (!['ok', 'not-equal'].includes(status)) {
+            throw new Error('Internal error: Atomics.wait() failed: ' + status);
+        }
+        const {
+            cid: cid2,
+            result,
+            error,
+            properties,
+        } = receiveMessageOnPort(mainPort).message;
+        if (cid !== cid2) {
+            throw new Error(
+                `Internal error: Expected id ${cid} but got id ${cid2}`
+            );
+        }
+        if (error) {
+            if (error instanceof Error) {
+                throw Object.assign(error, properties);
+            }
+            throw error;
+        }
+        return result;
+    };
+    if (worker.unref) {
+        worker.unref();
     }
-    return result;
-  };
-  if (worker.unref) worker.unref();
-  return syncFn;
+    return syncFn;
 }
 
 export function runAsWorker(fn) {
-  if (!workerData) {
-    return;
-  }
-  const { workerPort, debug } = workerData;
-  try {
-    parentPort.on("message", ({ sharedBuffer, cid, args }) => {
-      (async () => {
-        const sharedBufferView = new Int32Array(sharedBuffer);
-        let msg;
-        try {
-          msg = { cid, result: await fn(...args) };
-        } catch (error) {
-          msg = { cid, error, properties: extractProperties(error) };
-        }
-        workerPort.postMessage(msg);
-        Atomics.add(sharedBufferView, 0, 1);
-        Atomics.notify(sharedBufferView, 0);
-      })();
-    });
-  } catch (error) {
-    parentPort.on("message", ({ sharedBuffer, cid }) => {
-      const sharedBufferView = new Int32Array(sharedBuffer);
-      workerPort.postMessage({
-        cid,
-        error,
-        properties: extractProperties(error),
-      });
-      Atomics.add(sharedBufferView, 0, 1);
-      Atomics.notify(sharedBufferView, 0);
-    });
-  }
-  return debug;
+    if (!workerData) {
+        return;
+    }
+    const { workerPort, debug } = workerData;
+    try {
+        parentPort.on('message', ({ sharedBuffer, cid, args }) => {
+            (async () => {
+                const sharedBufferView = new Int32Array(sharedBuffer);
+                let msg;
+                try {
+                    msg = { cid, result: await fn(...args) };
+                } catch (error) {
+                    msg = { cid, error, properties: extractProperties(error) };
+                }
+                workerPort.postMessage(msg);
+                Atomics.add(sharedBufferView, 0, 1);
+                Atomics.notify(sharedBufferView, 0);
+            })();
+        });
+    } catch (error) {
+        parentPort.on('message', ({ sharedBuffer, cid }) => {
+            const sharedBufferView = new Int32Array(sharedBuffer);
+            workerPort.postMessage({
+                cid,
+                error,
+                properties: extractProperties(error),
+            });
+            Atomics.add(sharedBufferView, 0, 1);
+            Atomics.notify(sharedBufferView, 0);
+        });
+    }
+    return debug;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytecodealliance/preview2-shim",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "WASI Preview2 shim for JS environments",
   "author": "Guy Bedford, Eduardo Rodrigues<16357187+eduardomourar@users.noreply.github.com>",
   "type": "module",
@@ -15,18 +15,22 @@
       "types": "./types/*.d.ts",
       "node": "./lib/nodejs/*.js",
       "default": "./lib/browser/*.js"
+    },
+    "./instantiation": {
+      "types": "./types/instantiation.d.ts",
+      "node": "./lib/common/instantiation.js",
+      "default": "./lib/common/instantiation.js"
     }
   },
   "scripts": {
-    "test": "node --expose-gc ../../node_modules/mocha/bin/mocha.js -u tdd test/test.js --timeout 30000"
+    "lint": "eslint -c ../../eslint.config.mjs ./lib/**/*.js",
+    "lint:fix": "npm run lint -- --fix",
+    "test": "vitest run -c test/vitest.ts"
   },
   "files": [
     "types",
     "lib"
   ],
-  "devDependencies": {
-    "mocha": "^10.2.0"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bytecodealliance/jco.git"

package/types/index.d.ts

@@ -2,6 +2,5 @@ export type * as cli from "./cli.d.ts";
 export type * as clocks from './clocks.d.ts';
 export type * as filesystem from './filesystem.d.ts';
 export type * as http from "./http.d.ts";
-export type * as io from "./io.d.ts";
 export type * as random from "./random.d.ts";
 export type * as sockets from "./sockets.d.ts";

package/types/instantiation.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Type alias that represents the kind of imports that the average
+ * transpiled Jco component will require.
+ *
+ * For example, `wasi:http/types` and `wasi:http/outgoing-handler` are present due to
+ * the ability for a component to call `fetch()` at any point in time.
+ *
+ * While the feature can be disabled when building with `jco componentize` or `componentize-js`,
+ * by default it is enabled, and as such included here (practically, the implementations can be no-ops).
+ */
+type WASIImportObject = {
+    'wasi:cli/environment': typeof import('./interfaces/wasi-cli-environment.d.ts');
+    'wasi:cli/exit': typeof import('./interfaces/wasi-cli-exit.d.ts');
+    'wasi:cli/stderr': typeof import('./interfaces/wasi-cli-stderr.d.ts');
+    'wasi:cli/stdin': typeof import('./interfaces/wasi-cli-stdin.d.ts');
+    'wasi:cli/stdout': typeof import('./interfaces/wasi-cli-stdout.d.ts');
+    'wasi:cli/terminal-input': typeof import('./interfaces/wasi-cli-terminal-input.d.ts');
+    'wasi:cli/terminal-output': typeof import('./interfaces/wasi-cli-terminal-output.d.ts');
+    'wasi:cli/terminal-stderr': typeof import('./interfaces/wasi-cli-terminal-stderr.d.ts');
+    'wasi:cli/terminal-stdin': typeof import('./interfaces/wasi-cli-terminal-stdin.d.ts');
+    'wasi:cli/terminal-stdout': typeof import('./interfaces/wasi-cli-terminal-stdout.d.ts');
+
+    'wasi:sockets/instance-network': typeof import('./interfaces/wasi-sockets-instance-network.d.ts');
+    'wasi:sockets/ip-name-lookup': typeof import('./interfaces/wasi-sockets-ip-name-lookup.d.ts');
+    'wasi:sockets/network': typeof import('./interfaces/wasi-sockets-network.d.ts');
+    'wasi:sockets/tcp': typeof import('./interfaces/wasi-sockets-tcp.d.ts');
+    'wasi:sockets/tcp-create-socket': typeof import('./interfaces/wasi-sockets-tcp-create-socket.d.ts');
+    'wasi:sockets/udp': typeof import('./interfaces/wasi-sockets-udp.d.ts');
+    'wasi:sockets/udp-create-socket': typeof import('./interfaces/wasi-sockets-udp-create-socket.d.ts');
+
+    'wasi:filesystem/preopens': typeof import('./interfaces/wasi-filesystem-preopens.d.ts');
+    'wasi:filesystem/types': typeof import('./interfaces/wasi-filesystem-types.d.ts');
+
+    'wasi:io/error': typeof import('./interfaces/wasi-io-error.d.ts');
+    'wasi:io/poll': typeof import('./interfaces/wasi-io-poll.d.ts');
+    'wasi:io/streams': typeof import('./interfaces/wasi-io-streams.d.ts');
+
+    'wasi:random/random': typeof import('./interfaces/wasi-random-random.d.ts');
+    'wasi:random/insecure': typeof import('./interfaces/wasi-random-insecure.d.ts');
+    'wasi:random/insecure-seed': typeof import('./interfaces/wasi-random-insecure-seed.d.ts');
+
+    'wasi:clocks/monotonic-clock': typeof import('./interfaces/wasi-clocks-monotonic-clock.d.ts');
+    'wasi:clocks/timezone': typeof import('./interfaces/wasi-clocks-timezone.d.ts');
+    'wasi:clocks/wall-clock': typeof import('./interfaces/wasi-clocks-wall-clock.d.ts');
+
+    'wasi:http/types': typeof import('./interfaces/wasi-http-types.d.ts');
+    'wasi:http/outgoing-handler': typeof import('./interfaces/wasi-http-outgoing-handler.d.ts');
+};
+
+/**
+ * (EXPERIMENTAL) A class that holds WASI shims and can be used to configure
+ * an instantiation of a WebAssembly component transpiled with jco
+ * (i.e. via `jco transpile`).
+ *
+ * Normally, transpiled components contain mapping for WASI interfaces
+ * and/or imports that import the relevant packages (ex. `@bytecodealliance/preview2-shim/clocks`)
+ * from the right sources.
+ *
+ * This function makes use of the `WASIShim` object to provide an object that can be easily
+ * fed to the `instantiate` function produced by a transpiled component:
+ *
+ * ```js
+ * import { WASIShim } from "@bytecodealliance/preview2-shim/instantiation"
+ * // ...
+ * import { instantiate } from "path/to/transpiled/component.js"
+ * // ...
+ * const component = await instantiate(null, new WASIShim().getImportObject())
+ * ```
+ *
+ * You can also replace imports that you'd like to override with custom implementations,
+ * by using the `WASIShim` object directly:
+ *
+ * ```js
+ * import { random } from "@bytecodealliance/preview2-shim"
+ * import { WASIShim } from "@bytecodealliance/preview2-shim/instantiation"
+ * // ...
+ * import { instantiate } from "path/to/transpiled/component.js"
+ * // ...
+ * const customWASIShim = new WASIShim({
+ *     random: {
+ *         // For these two interfaces we re-use the default provided shim
+ *         random: random.random,
+ *         insecure-seed: random.insecureSeed,
+ *         // For insecure, we can supply our own custom implementation
+ *         insecure: {
+ *             ...
+ *         }
+ *     }
+ * });
+ *
+ * const component = await instantiate(null, customWASIShim.getImportObject())
+ * ```
+ *
+ * Note that this object is similar but not identical to the Node `WASI` object --
+ * it is solely concerned with shimming of preview2 when dealing with a WebAssembly
+ * component transpiled by Jco. While this object *does* work with Node (and the browser)
+ * semantics are not the same as Node's `WASI` object.
+ *
+ * @class WASIShim
+ */
+export class WASIShim {
+    constructor(shims?: Partial<WASIImportObject>);
+
+    /**
+     * Generate an import object for the shim that can be used with
+     * functions like `instantiate` that are exposed from a transpiled
+     * WebAssembly component.
+     *
+     * @returns {object}
+     */
+    getImportObject(): WASIImportObject;
+}