@bytecodealliance/preview3-shim 0.1.2 → 0.2.0

package/dist/nodejs/filesystem/error.d.ts

@@ -0,0 +1,61 @@
+export declare const ERROR_MAP: {
+    EACCES: string;
+    EALREADY: string;
+    EBADF: string;
+    EBUSY: string;
+    EDEADLK: string;
+    EDQUOT: string;
+    EEXIST: string;
+    EFBIG: string;
+    EILSEQ: string;
+    EINPROGRESS: string;
+    EINTR: string;
+    EINVAL: string;
+    EIO: string;
+    EISDIR: string;
+    ELOOP: string;
+    EMLINK: string;
+    EMSGSIZE: string;
+    ENAMETOOLONG: string;
+    ENODEV: string;
+    ENOENT: string;
+    ENOLCK: string;
+    ENOMEM: string;
+    ENOSPC: string;
+    ENOTDIR: string;
+    ERR_FS_EISDIR: string;
+    ENOTEMPTY: string;
+    ENOTRECOVERABLE: string;
+    ENOTSUP: string;
+    ENOTTY: string;
+    ENXIO: string;
+    EOVERFLOW: string;
+    EPERM: string;
+    EPIPE: string;
+    EROFS: string;
+    ESPIPE: string;
+    ETXTBSY: string;
+    EXDEV: string;
+};
+/**
+ * Custom error for File operations with JCO compatible payload.
+ */
+export declare class FSError extends Error {
+    payload: any;
+    /**
+     * @param {string} tag        – machine‐readable error tag
+     * @param {string} [message]  – human‐readable message
+     * @param {any}    [val]      – optional extra data
+     * @param {object} [opts]
+     * @param {Error} [opts.cause]
+     */
+    constructor(tag: any, message?: any, val?: any, opts?: {
+        cause?: unknown;
+    });
+    /**
+     * Create or rewrap an error into FSError
+     * @param {any} err – number, string, Error, or FSError
+     */
+    static from(err: any): FSError;
+}
+export declare function filesystemErrorCode(err: any): any;

package/dist/nodejs/filesystem/error.js

@@ -0,0 +1,86 @@
+export const ERROR_MAP = {
+    EACCES: "access",
+    EALREADY: "already",
+    EBADF: "bad-descriptor",
+    EBUSY: "busy",
+    EDEADLK: "deadlock",
+    EDQUOT: "quota",
+    EEXIST: "exist",
+    EFBIG: "file-too-large",
+    EILSEQ: "illegal-byte-sequence",
+    EINPROGRESS: "in-progress",
+    EINTR: "interrupted",
+    EINVAL: "invalid",
+    EIO: "io",
+    EISDIR: "is-directory",
+    ELOOP: "loop",
+    EMLINK: "too-many-links",
+    EMSGSIZE: "message-size",
+    ENAMETOOLONG: "name-too-long",
+    ENODEV: "no-device",
+    ENOENT: "no-entry",
+    ENOLCK: "no-lock",
+    ENOMEM: "insufficient-memory",
+    ENOSPC: "insufficient-space",
+    ENOTDIR: "not-directory",
+    ERR_FS_EISDIR: "not-directory",
+    ENOTEMPTY: "not-empty",
+    ENOTRECOVERABLE: "not-recoverable",
+    ENOTSUP: "unsupported",
+    ENOTTY: "no-tty",
+    ENXIO: "no-such-device",
+    EOVERFLOW: "overflow",
+    EPERM: "not-permitted",
+    EPIPE: "pipe",
+    EROFS: "read-only",
+    ESPIPE: "invalid-seek",
+    ETXTBSY: "text-file-busy",
+    EXDEV: "cross-device",
+};
+function getErrorTag(e) {
+    if (e.code in ERROR_MAP) {
+        return ERROR_MAP[e.code];
+    }
+    // Windows gives this error for badly structured `//` reads, this seems like
+    // a slightly better error than unknown given that it's a common footgun.
+    if (e.code === -4094 || (e.code === "UNKNOWN" && e.errno === -4094)) {
+        return "no-such-device";
+    }
+    throw e;
+}
+/**
+ * Custom error for File operations with JCO compatible payload.
+ */
+export class FSError extends Error {
+    payload;
+    /**
+     * @param {string} tag        – machine‐readable error tag
+     * @param {string} [message]  – human‐readable message
+     * @param {any}    [val]      – optional extra data
+     * @param {object} [opts]
+     * @param {Error} [opts.cause]
+     */
+    constructor(tag, message = undefined, val = undefined, opts = {}) {
+        super(message ?? `Error: ${tag}`, { cause: opts.cause });
+        this.name = "FSError";
+        this.payload = val !== undefined ? { tag, val } : { tag };
+    }
+    /**
+     * Create or rewrap an error into FSError
+     * @param {any} err – number, string, Error, or FSError
+     */
+    static from(err) {
+        if (err instanceof FSError) {
+            return err;
+        }
+        const tag = getErrorTag(err);
+        const message = err?.message;
+        return new FSError(tag, message, undefined, { cause: err });
+    }
+}
+export function filesystemErrorCode(err) {
+    if (err?.payload?.tag) {
+        return err.payload;
+    }
+    return { tag: getErrorTag(err) };
+}

package/dist/nodejs/filesystem/utils.d.ts

@@ -0,0 +1,8 @@
+/** Map fs.Dirent -> WASI type */
+export declare function wasiTypeFromDirent(obj: any): {
+    tag: string;
+    val?: undefined;
+} | {
+    tag: string;
+    val: any;
+};

package/dist/nodejs/filesystem/utils.js

@@ -0,0 +1,25 @@
+/** Map fs.Dirent -> WASI type */
+export function wasiTypeFromDirent(obj) {
+    if (obj.isFile()) {
+        return { tag: "regular-file" };
+    }
+    else if (obj.isSocket()) {
+        return { tag: "socket" };
+    }
+    else if (obj.isSymbolicLink()) {
+        return { tag: "symbolic-link" };
+    }
+    else if (obj.isFIFO()) {
+        return { tag: "fifo" };
+    }
+    else if (obj.isDirectory()) {
+        return { tag: "directory" };
+    }
+    else if (obj.isCharacterDevice()) {
+        return { tag: "character-device" };
+    }
+    else if (obj.isBlockDevice()) {
+        return { tag: "block-device" };
+    }
+    return { tag: "other", val: undefined };
+}

package/dist/nodejs/filesystem.js

@@ -0,0 +1,2 @@
+export * from "./filesystem/error.js";
+export * from "./filesystem/descriptor.js";

package/dist/nodejs/finalization.d.ts

@@ -0,0 +1,2 @@
+export declare function registerDispose(resource: any, parent: any, id: any, disposeFn: any): () => void;
+export declare function earlyDispose(finalizer: () => void): void;

package/{lib → dist}/nodejs/finalization.js

@@ -1,33 +1,27 @@
 let REGISTRY = null;
-
 function getRegistry() {
-  if (!REGISTRY) {
-    REGISTRY = new FinalizationRegistry((dispose) => dispose());
-  }
-  return REGISTRY;
+    if (!REGISTRY) {
+        REGISTRY = new FinalizationRegistry((dispose) => dispose());
+    }
+    return REGISTRY;
 }
-
 // While strictly speaking all components should handle their disposal,
 // this acts as a last-resort to catch all missed drops through the JS GC.
 // Mainly for two cases - (1) components which are long lived, that get shut
 // down and (2) users that interface with low-level WASI APIs directly in JS
 // for various reasons may end up leaning on JS GC inadvertantly.
-
 export function registerDispose(resource, parent = null, id, disposeFn) {
-  const dummySymbol = Symbol();
-
-  const finalizer = () => {
-    if (parent?.[dummySymbol]) {
-      return;
-    }
-    disposeFn(id);
-  };
-
-  getRegistry().register(resource, finalizer, finalizer);
-  return finalizer;
+    const dummySymbol = Symbol();
+    const finalizer = () => {
+        if (parent?.[dummySymbol]) {
+            return;
+        }
+        disposeFn(id);
+    };
+    getRegistry().register(resource, finalizer, finalizer);
+    return finalizer;
 }
-
 export function earlyDispose(finalizer) {
-  getRegistry().unregister(finalizer);
-  finalizer();
+    getRegistry().unregister(finalizer);
+    finalizer();
 }

package/dist/nodejs/future.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Creates a future with a reader and writer.
+ *
+ * @returns {Object} An object containing:
+ *   - `tx` {FutureWriter}: The writer for the future.
+ *   - `rx` {FutureReader}: The reader for the future.
+ *
+ * @example
+ * // Basic usage - creating a communication channel
+ * const { tx, rx } = future();
+ *
+ * const message = 'Hello world!';
+ * await tx.write(message);
+ *
+ * // first read yields the message
+ * const value = await rx.read();
+ * expect(value).toBe(message);
+ *
+ * // subsequent reads yield null
+ * const noValue = await rx.read();
+ * expect(noValue).toBeNull();
+ */
+export declare function future(): {
+    tx: FutureWriter;
+    rx: FutureReader;
+};
+export declare class FutureReader {
+    #private;
+    /**
+     * Constructs a FutureReader.
+     *
+     * @param {Promise} promise - The promise to be read.
+     * @throws {Error} If the provided argument is not a promise.
+     */
+    constructor(promise: any);
+    /**
+     * Reads the value from the promise. Can only be called once.
+     *
+     * @returns {Promise<any>} Resolves with the value of the promise or null if already consumed.
+     * @throws {Error} If the promise is rejected.
+     */
+    read(): Promise<any>;
+    then(resolve: any, reject: any): Promise<any>;
+    /**
+     * Cancels the future. Not supported for FutureReader.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Closes the reader. No resources are released in this implementation.
+     */
+    close(): void;
+    /**
+     * Converts the reader back into a promise.
+     *
+     * @returns {Promise} The original promise.
+     */
+    intoPromise(): any;
+}
+export declare class FutureWriter {
+    #private;
+    /**
+     * Constructs a FutureWriter.
+     *
+     * @param {Object} deferred - A deferred object with `resolve` and `reject` methods.
+     * @throws {Error} If the deferred object is invalid.
+     */
+    constructor(deferred: any);
+    /**
+     * Resolves the promise with the given value.
+     *
+     * @param {any} value - The value to resolve the promise with.
+     * @throws {Error} If the writer is already closed.
+     */
+    write(value: any): Promise<void>;
+    /**
+     * Rejects the promise with the given reason.
+     *
+     * @param {any} reason - The reason for rejecting the promise.
+     * @throws {Error} If the writer is already closed.
+     */
+    abort(reason: any): Promise<void>;
+    /**
+     * Resolves the promise with null and closes the writer.
+     */
+    close(): Promise<void>;
+    /**
+     * Rejects the promise with the given error and closes the writer.
+     *
+     * @param {Error} error - The error to reject the promise with.
+     */
+    closeWithError(error: any): Promise<void>;
+    /**
+     * Converts the writer back into a promise.
+     *
+     * @returns {Promise} The original promise.
+     */
+    intoPromise(): any;
+}

package/dist/nodejs/future.js

@@ -0,0 +1,176 @@
+/**
+ * Creates a future with a reader and writer.
+ *
+ * @returns {Object} An object containing:
+ *   - `tx` {FutureWriter}: The writer for the future.
+ *   - `rx` {FutureReader}: The reader for the future.
+ *
+ * @example
+ * // Basic usage - creating a communication channel
+ * const { tx, rx } = future();
+ *
+ * const message = 'Hello world!';
+ * await tx.write(message);
+ *
+ * // first read yields the message
+ * const value = await rx.read();
+ * expect(value).toBe(message);
+ *
+ * // subsequent reads yield null
+ * const noValue = await rx.read();
+ * expect(noValue).toBeNull();
+ */
+export function future() {
+    const def = deferred();
+    const tx = new FutureWriter(def);
+    const rx = new FutureReader(def.promise);
+    return { tx, rx };
+}
+function deferred() {
+    let resolve, reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+export class FutureReader {
+    /** The underlying Promise to read from */
+    #promise;
+    /** Tracks if read() has been called (prevents multiple reads) */
+    #consumed = false;
+    /**
+     * Constructs a FutureReader.
+     *
+     * @param {Promise} promise - The promise to be read.
+     * @throws {Error} If the provided argument is not a promise.
+     */
+    constructor(promise) {
+        if (!promise || typeof promise.then !== "function") {
+            throw new Error("Provided future must be a Promise");
+        }
+        if (promise instanceof Promise) {
+            promise.catch(() => { });
+        }
+        this.#promise = promise;
+    }
+    /**
+     * Reads the value from the promise. Can only be called once.
+     *
+     * @returns {Promise<any>} Resolves with the value of the promise or null if already consumed.
+     * @throws {Error} If the promise is rejected.
+     */
+    async read() {
+        if (this.#consumed) {
+            return null;
+        }
+        try {
+            return await this.#promise;
+        }
+        catch (err) {
+            throw err;
+        }
+        finally {
+            this.#consumed = true;
+        }
+    }
+    then(resolve, reject) {
+        return this.read().then(resolve, reject);
+    }
+    /**
+     * Cancels the future. Not supported for FutureReader.
+     */
+    async cancel() {
+        throw new Error("FutureReader does not support cancel");
+    }
+    /**
+     * Closes the reader. No resources are released in this implementation.
+     */
+    close() {
+        // Nothing to release.
+    }
+    /**
+     * Converts the reader back into a promise.
+     *
+     * @returns {Promise} The original promise.
+     */
+    intoPromise() {
+        const promise = this.#promise;
+        this.#promise = null;
+        return promise;
+    }
+}
+export class FutureWriter {
+    /** Deferred object with resolve/reject methods for controlling promise state */
+    #deferred;
+    /** Tracks if writer has been used */
+    #written = false;
+    /**
+     * Constructs a FutureWriter.
+     *
+     * @param {Object} deferred - A deferred object with `resolve` and `reject` methods.
+     * @throws {Error} If the deferred object is invalid.
+     */
+    constructor(deferred) {
+        if (!deferred || typeof deferred.resolve !== "function") {
+            throw new Error("Provided deferred object must have a resolve method");
+        }
+        this.#deferred = deferred;
+    }
+    /**
+     * Resolves the promise with the given value.
+     *
+     * @param {any} value - The value to resolve the promise with.
+     * @throws {Error} If the writer is already closed.
+     */
+    async write(value) {
+        this.#ensureState();
+        this.#written = true;
+        this.#deferred.resolve(value);
+    }
+    /**
+     * Rejects the promise with the given reason.
+     *
+     * @param {any} reason - The reason for rejecting the promise.
+     * @throws {Error} If the writer is already closed.
+     */
+    async abort(reason) {
+        this.#ensureState();
+        this.#written = true;
+        this.#deferred.reject(reason);
+    }
+    /**
+     * Resolves the promise with null and closes the writer.
+     */
+    async close() {
+        this.#ensureState();
+        this.#written = true;
+        this.#deferred.resolve(null);
+    }
+    /**
+     * Rejects the promise with the given error and closes the writer.
+     *
+     * @param {Error} error - The error to reject the promise with.
+     */
+    async closeWithError(error) {
+        this.#ensureState();
+        this.#written = true;
+        this.#deferred.reject(error);
+    }
+    /**
+     * Converts the writer back into a promise.
+     *
+     * @returns {Promise} The original promise.
+     */
+    intoPromise() {
+        this.close();
+        const promise = this.#deferred.promise;
+        this.#deferred = null;
+        return promise;
+    }
+    #ensureState() {
+        if (this.#written) {
+            throw new Error("FutureWriter is closed (already written)");
+        }
+    }
+}

package/dist/nodejs/http/client.d.ts

@@ -0,0 +1,22 @@
+import { Response } from "./response.js";
+/**
+ * HTTP client interface.
+ *
+ * WIT:
+ * ```
+ * interface client {
+ *   use types.{request, response, error-code};
+ *   send: async func(request) -> result<response, error-code>;
+ * }
+ * ```
+ */
+export declare const client: {
+    /**
+     * Send an HTTP request and return a response.
+     *
+     * @param {Request} req
+     * @returns {Promise<Response>}
+     * @throws {HttpError}
+     */
+    send(req: any): Promise<Response>;
+};

package/dist/nodejs/http/client.js

@@ -0,0 +1,138 @@
+import { MessageChannel } from "node:worker_threads";
+import { ResourceWorker } from "../workers/resource-worker.js";
+import { StreamReader, readableByteStreamFromReader } from "../stream.js";
+import { FutureReader, future } from "../future.js";
+import { HttpError } from "./error.js";
+import { _schemeToString, Request } from "./request.js";
+import { Response } from "./response.js";
+import { _fieldsFromEntriesChecked, _readTrailersForTransport, _trailerResultFromEntries, } from "./fields.js";
+let WORKER = null;
+function worker() {
+    return (WORKER ??= new ResourceWorker(new URL("../workers/http-worker.js", import.meta.url)));
+}
+/**
+ * HTTP client interface.
+ *
+ * WIT:
+ * ```
+ * interface client {
+ *   use types.{request, response, error-code};
+ *   send: async func(request) -> result<response, error-code>;
+ * }
+ * ```
+ */
+export const client = {
+    /**
+     * Send an HTTP request and return a response.
+     *
+     * @param {Request} req
+     * @returns {Promise<Response>}
+     * @throws {HttpError}
+     */
+    async send(req) {
+        const scheme = _schemeToString(req.getScheme()) ?? "http";
+        const authority = req.getAuthority();
+        if (!authority) {
+            const err = new HttpError("internal-error", "Request.authority must be set for client.send");
+            req._resolve({ tag: "err", val: err.payload });
+            throw err;
+        }
+        const path = req.getPathWithQuery();
+        if (path == null) {
+            const err = new HttpError("HTTP-request-URI-invalid", "Request.pathWithQuery must be set");
+            req._resolve({ tag: "err", val: err.payload });
+            throw err;
+        }
+        const url = `${scheme}://${authority}${path}`;
+        const opts = req.getOptions();
+        const connectTimeoutNs = opts?.getConnectTimeout() ?? null;
+        const firstByteTimeoutNs = opts?.getFirstByteTimeout() ?? null;
+        const betweenBytesTimeoutNs = opts?.getBetweenBytesTimeout() ?? null;
+        const { rx: resRx } = future();
+        const [body, trailers] = Request.consumeBody(req, resRx);
+        const { port1: tx, port2: rx } = new MessageChannel();
+        const { port1: transmitRx, port2: transmitTx } = new MessageChannel();
+        const transfer = [rx, transmitTx];
+        const stream = body ? readableByteStreamFromReader(body, { name: "request body" }) : undefined;
+        if (stream) {
+            transfer.unshift(stream);
+        }
+        let transmitSettled = false;
+        const settleTransmit = (result) => {
+            if (transmitSettled) {
+                return;
+            }
+            transmitSettled = true;
+            transmitRx.close();
+            req._resolve(result);
+        };
+        transmitRx.once("message", ({ val, err }) => {
+            if (err) {
+                settleTransmit({ tag: "err", val: err });
+            }
+            else {
+                settleTransmit({ tag: "ok", val });
+            }
+        });
+        _readTrailersForTransport(trailers)
+            .then((val) => tx.postMessage({ val }))
+            .catch((err) => tx.postMessage({ err: HttpError.from(err).payload }))
+            .finally(() => tx.close());
+        try {
+            const method = req.getMethod();
+            const parts = await worker().run({
+                op: "client-request",
+                url,
+                method: method.tag === "other" ? method.val : method.tag,
+                headers: req.getHeaders().copyAll(),
+                timeouts: {
+                    connectTimeoutNs,
+                    firstByteTimeoutNs,
+                    betweenBytesTimeoutNs,
+                },
+                trailers: rx,
+                transmit: transmitTx,
+                body: stream,
+            }, transfer);
+            return responseFromParts(parts);
+        }
+        catch (e) {
+            const err = HttpError.from(e);
+            settleTransmit({ tag: "err", val: err.payload });
+            throw err;
+        }
+    },
+};
+const responseFromParts = (parts) => {
+    const { headers, body, trailers, statusCode } = parts;
+    // Create a promise that resolves when the worker sends a message with trailers
+    const promise = new Promise((resolve, reject) => {
+        trailers.once("message", ({ val, err }) => {
+            trailers.close();
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve(val);
+            }
+        });
+    });
+    const future = new TrailerFutureReader(promise.then(_trailerResultFromEntries), trailers);
+    const contents = new StreamReader(body);
+    const fields = _fieldsFromEntriesChecked(headers);
+    const [res] = Response.new(fields, contents, future);
+    res.setStatusCode(statusCode);
+    return res;
+};
+class TrailerFutureReader extends FutureReader {
+    #trailers;
+    constructor(promise, trailers) {
+        super(promise);
+        this.#trailers = trailers;
+    }
+    close() {
+        this.#trailers?.close();
+        this.#trailers = null;
+        super.close();
+    }
+}

package/dist/nodejs/http/error.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Custom error class for WASI http interface that properly formats payload for Jco compatibility
+ *
+ * https://bytecodealliance.github.io/jco/wit-type-representations.html#result-considerations-idiomatic-js-errors-for-host-implementations
+ */
+export declare class HttpError extends Error {
+    payload: any;
+    /**
+     * Create a new WASI http error
+     * @param {string} tag - The error tag/type
+     * @param {string} [message] - Human-readable error message
+     * @param {any} [val] - Optional value/data for the error
+     */
+    constructor(tag: any, message?: any, val?: any, opts?: {
+        cause?: unknown;
+    });
+    static from(err: any): HttpError;
+}