@oliphaunt/wasix-ts 0.1.0

package/lib/worker-rpc.js

@@ -0,0 +1,422 @@
+import { WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES, WasixDatabaseImpl, createWasixDeferred, normalizeWasixDatabaseIdentity, } from './database.js';
+import { serializeOpenConfig } from './client-common.js';
+import { toUint8Array } from './query.js';
+import { deserializeWorkerError } from './rpc.js';
+const STREAM_ACK = 0;
+const STREAM_FAILED = 1;
+/** @internal Open through a package-owned isolated host without burdening the direct graph. */
+export async function openWasixWithWorker(createWorker, openOptions, validate, transferAssets = true) {
+    validate?.(openOptions);
+    return openWorkerDatabase(createWorker(openOptions), openOptions, transferAssets ? assetTransfers(openOptions) : []);
+}
+/** @internal Restore through a temporary package-owned isolated host. */
+export async function restoreWasixWithWorker(createWorker, storage, bytes, validate) {
+    if (storage === undefined)
+        throw new TypeError('WASIX restore requires persistent storage');
+    const openOptions = serializeOpenConfig({ storage });
+    validate?.(openOptions);
+    const input = toUint8Array(bytes).slice();
+    const rpc = new WorkerRpc(createWorker(openOptions));
+    try {
+        await rpc.request({ method: 'restore', storage: openOptions.storage, bytes: input }, [
+            input.buffer,
+        ]);
+    }
+    catch (error) {
+        return rethrowAfterWorkerTermination(rpc, error, 'Oliphaunt WASIX worker restore and termination both failed');
+    }
+    await rpc.terminate();
+}
+/** @internal Correlates worker requests and fails them as one unit if the worker exits. */
+export class WorkerRpc {
+    terminalState;
+    #worker;
+    #terminalState = new WorkerTerminalState();
+    #pending = new Map();
+    #nextId = 1;
+    #fatal;
+    #terminationRequested = false;
+    #termination;
+    constructor(worker) {
+        this.#worker = worker;
+        this.terminalState = this.#terminalState;
+        worker.onMessage((message) => {
+            const pending = this.#pending.get(message.id);
+            if (pending === undefined) {
+                return;
+            }
+            if ('kind' in message) {
+                if (pending.control === undefined || Atomics.load(pending.control, STREAM_FAILED) === 0) {
+                    try {
+                        pending.onChunk?.(message.value);
+                    }
+                    catch {
+                        if (pending.control !== undefined) {
+                            Atomics.store(pending.control, STREAM_FAILED, 1);
+                        }
+                    }
+                }
+                if (pending.control !== undefined) {
+                    Atomics.store(pending.control, STREAM_ACK, message.sequence);
+                    Atomics.notify(pending.control, STREAM_ACK);
+                }
+                return;
+            }
+            this.#pending.delete(message.id);
+            if (message.ok) {
+                if (pending.stream) {
+                    if (!('streamOutcome' in message)) {
+                        pending.reject(new Error('Oliphaunt WASIX worker omitted its protocol stream outcome'));
+                        return;
+                    }
+                    pending.resolve(message.streamOutcome);
+                }
+                else if ('streamOutcome' in message) {
+                    pending.reject(new Error('Oliphaunt WASIX worker returned a stream outcome for a non-stream request'));
+                }
+                else {
+                    pending.resolve(message.value);
+                }
+            }
+            else {
+                pending.reject(deserializeWorkerError(message.error));
+            }
+        });
+        worker.onFatal((error) => this.#fail(error));
+    }
+    get supportsSharedMemory() {
+        return this.#worker.supportsSharedMemory !== false;
+    }
+    request(request, transfer = []) {
+        if (this.#fatal !== undefined) {
+            return Promise.reject(this.#fatal);
+        }
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject });
+            try {
+                this.#worker.postMessage({ ...request, id }, transfer);
+            }
+            catch (error) {
+                this.#pending.delete(id);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    stream(input, persistence, onChunk) {
+        if (this.#fatal !== undefined) {
+            return Promise.reject(this.#fatal);
+        }
+        const id = this.#nextId++;
+        const control = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 2));
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, {
+                resolve: (value) => {
+                    if (value === 'complete' || value === 'callbackAborted') {
+                        resolve(value);
+                    }
+                    else {
+                        reject(new Error('Oliphaunt WASIX worker returned an invalid protocol stream outcome'));
+                    }
+                },
+                reject,
+                onChunk,
+                control,
+                stream: true,
+            });
+            const request = {
+                id,
+                method: 'execStream',
+                input,
+                persistence,
+                control: control.buffer,
+            };
+            try {
+                this.#worker.postMessage(request, [input.buffer]);
+            }
+            catch (error) {
+                this.#pending.delete(id);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    terminate() {
+        this.#stop(this.#fatal ?? new Error('Oliphaunt WASIX worker was terminated'));
+        return this.#termination ?? Promise.resolve();
+    }
+    expectSelfExit() {
+        if (this.#fatal !== undefined)
+            return Promise.reject(this.#fatal);
+        try {
+            return this.#worker.expectSelfExit?.();
+        }
+        catch (error) {
+            return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    #fail(error) {
+        // A package-requested terminate is expected ownership teardown, not an
+        // independently observed crash. The public close state remains governed
+        // by its memoized close attempt in that case.
+        if (!this.#terminationRequested) {
+            this.#terminalState.fail(error);
+        }
+        this.#stop(error);
+    }
+    #stop(error) {
+        if (this.#fatal === undefined) {
+            this.#fatal = error;
+            this.#rejectAll(error);
+        }
+        if (this.#termination !== undefined) {
+            return;
+        }
+        this.#terminationRequested = true;
+        try {
+            this.#termination = Promise.resolve(this.#worker.terminate());
+        }
+        catch (terminationError) {
+            this.#termination = Promise.reject(terminationError instanceof Error ? terminationError : new Error(String(terminationError)));
+        }
+        // Fatal-event cleanup has no awaiting caller. Keep the original promise
+        // available to close/open while preventing an unhandled rejection.
+        void this.#termination.catch(() => undefined);
+    }
+    #rejectAll(error) {
+        for (const pending of this.#pending.values()) {
+            pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+}
+/** @internal Opens exactly one database and guarantees worker cleanup on failure. */
+export async function openWorkerDatabase(worker, options, transfer = []) {
+    const rpc = new WorkerRpc(worker);
+    try {
+        await rpc.request({ method: 'open', options }, transfer);
+        return new WasixDatabaseImpl(new WorkerDatabaseSession(rpc, options));
+    }
+    catch (error) {
+        return rethrowAfterWorkerTermination(rpc, error, 'Oliphaunt WASIX worker open and termination both failed');
+    }
+}
+async function rethrowAfterWorkerTermination(rpc, primaryFailure, aggregateMessage) {
+    try {
+        await rpc.terminate();
+    }
+    catch (terminationFailure) {
+        throw new AggregateError([primaryFailure, terminationFailure], aggregateMessage);
+    }
+    throw primaryFailure;
+}
+function assetTransfers(options) {
+    const transfer = [];
+    const seen = new Set();
+    appendAssetTransfer(options.runtime.runtimeArchive.source, transfer, seen);
+    appendAssetTransfer(options.runtime.manifest.source, transfer, seen);
+    if (options.icu !== undefined) {
+        appendAssetTransfer(options.icu.dataArchive.source, transfer, seen);
+        appendAssetTransfer(options.icu.clusterSeedArchive.source, transfer, seen);
+        appendAssetTransfer(options.icu.clusterSeedManifest.source, transfer, seen);
+    }
+    else {
+        appendAssetTransfer(options.runtime.standardSeedArchive.source, transfer, seen);
+        appendAssetTransfer(options.runtime.standardSeedManifest.source, transfer, seen);
+    }
+    for (const carrier of Object.values(options.extensionCarriers)) {
+        appendAssetTransfer(carrier.source, transfer, seen);
+    }
+    return transfer;
+}
+function appendAssetTransfer(source, transfer, seen) {
+    if (!(source instanceof Uint8Array) || !(source.buffer instanceof ArrayBuffer)) {
+        return;
+    }
+    if (!seen.has(source.buffer)) {
+        seen.add(source.buffer);
+        transfer.push(source.buffer);
+    }
+}
+class WorkerDatabaseSession {
+    supportsProtocolConnections;
+    identity;
+    terminalState;
+    #rpc;
+    #closed = false;
+    #closeAttempt;
+    constructor(rpc, options) {
+        this.#rpc = rpc;
+        this.supportsProtocolConnections = rpc.supportsSharedMemory;
+        this.terminalState = rpc.terminalState;
+        this.identity = normalizeWasixDatabaseIdentity(options.username, options.database);
+    }
+    async exec(input, persistence = 'sync') {
+        this.#assertOpen();
+        const response = await this.#rpc.request({ method: 'exec', input, persistence }, [
+            input.buffer,
+        ]);
+        if (!(response instanceof Uint8Array)) {
+            throw new Error('Oliphaunt WASIX worker returned an invalid protocol response');
+        }
+        return response;
+    }
+    execStream(input, onChunk, persistence = 'sync') {
+        this.#assertOpen();
+        if (!this.#rpc.supportsSharedMemory) {
+            return this.#execBufferedStream(input, onChunk, persistence);
+        }
+        return this.#rpc.stream(input, persistence, onChunk);
+    }
+    async #execBufferedStream(input, onChunk, persistence) {
+        const response = await this.exec(input, persistence);
+        try {
+            for (let offset = 0; offset < response.length; offset += WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES) {
+                onChunk(response.slice(offset, offset + WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES));
+            }
+            return 'complete';
+        }
+        catch {
+            // The complete response is already owned by the parent, so stopping
+            // callback delivery cannot leave the database protocol state unknown.
+            return 'callbackAborted';
+        }
+    }
+    async sync(boundary) {
+        this.#assertOpen();
+        await this.#rpc.request({ method: 'sync', boundary });
+    }
+    async backup() {
+        this.#assertOpen();
+        const response = await this.#rpc.request({ method: 'backup' });
+        if (!(response instanceof Uint8Array)) {
+            throw new Error('Oliphaunt WASIX worker returned an invalid physical archive');
+        }
+        return response;
+    }
+    async runPgDump(options) {
+        this.#assertOpen();
+        const response = await this.#rpc.request({
+            method: 'runPgDump',
+            tool: options.tool,
+            args: [...options.args],
+        });
+        if (!isWasixToolProcessResult(response)) {
+            throw new Error('Oliphaunt WASIX worker returned an invalid pg_dump result');
+        }
+        return response;
+    }
+    async runTool(options) {
+        this.#assertOpen();
+        const stdin = options.stdin;
+        const transferableStdin = stdin !== undefined &&
+            stdin.buffer instanceof ArrayBuffer &&
+            stdin.byteOffset === 0 &&
+            stdin.byteLength === stdin.buffer.byteLength;
+        const response = await this.#rpc.request({
+            method: 'runTool',
+            options: {
+                ...options,
+                // The release addon owns the verified tool payload. Preserve only
+                // the descriptor identity across the Worker boundary.
+                tool: { ...options.tool, source: 'oliphaunt:wasix-napi-embedded' },
+                args: [...options.args],
+                ...(stdin === undefined ? {} : { stdin }),
+            },
+        }, transferableStdin && stdin !== undefined ? [stdin.buffer] : []);
+        if (!isWasixToolProcessResult(response)) {
+            throw new Error('Oliphaunt WASIX worker returned an invalid native tool result');
+        }
+        return response;
+    }
+    async serve(connection, mode) {
+        this.#assertOpen();
+        if (!this.#rpc.supportsSharedMemory) {
+            throw new Error('Oliphaunt WASIX worker execution does not support shared-memory protocol connections');
+        }
+        await this.#rpc.request({ method: 'serve', connection, mode });
+    }
+    close() {
+        if (this.#closeAttempt !== undefined)
+            return this.#closeAttempt;
+        this.#closed = true;
+        const attempt = createWasixDeferred();
+        this.#closeAttempt = attempt.promise;
+        void this.#closeOrderly().then(attempt.resolve, attempt.reject);
+        return attempt.promise;
+    }
+    async #closeOrderly() {
+        const selfExit = this.#rpc.expectSelfExit();
+        // An early Worker failure can reject this before the close reply rejects.
+        // Observe it immediately, then preserve the same rejection for the ordered
+        // aggregation below.
+        void selfExit?.catch(() => undefined);
+        let requestFailed = false;
+        let requestFailure;
+        try {
+            await this.#rpc.request({ method: 'close' });
+        }
+        catch (error) {
+            requestFailed = true;
+            requestFailure = error;
+        }
+        let terminationFailed = false;
+        let terminationFailure;
+        try {
+            if (selfExit !== undefined) {
+                // A Node-compatible Worker acknowledges close only by exiting itself
+                // after the dispatcher has unwound and released its direct native
+                // handle. Wait for that full quiescence even when native close reports
+                // an error; the error response alone is not permission to terminate a
+                // Worker which may still be finishing Node-API cleanup. The observed
+                // exit is the completed host teardown contract; Bun does not settle a
+                // redundant terminate() after that event.
+                await selfExit;
+            }
+            else {
+                // Browser Workers retain their existing post-close termination path.
+                await this.#rpc.terminate();
+            }
+        }
+        catch (error) {
+            terminationFailed = true;
+            terminationFailure = error;
+        }
+        if (requestFailed && terminationFailed) {
+            if (requestFailure === terminationFailure) {
+                throw requestFailure;
+            }
+            throw new AggregateError([requestFailure, terminationFailure], 'Oliphaunt WASIX worker close and termination both failed');
+        }
+        if (requestFailed) {
+            throw requestFailure;
+        }
+        if (terminationFailed) {
+            throw terminationFailure;
+        }
+    }
+    #assertOpen() {
+        if (this.#closed) {
+            throw new Error('Oliphaunt WASIX worker session is closed');
+        }
+    }
+}
+class WorkerTerminalState {
+    #failure;
+    get terminal() {
+        return this.#failure !== undefined;
+    }
+    get failure() {
+        return this.#failure;
+    }
+    fail(error) {
+        this.#failure ??= error;
+    }
+}
+function isWasixToolProcessResult(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !(value instanceof Uint8Array) &&
+        Number.isSafeInteger(value.exitCode) &&
+        value.stdout instanceof Uint8Array &&
+        value.stderr instanceof Uint8Array);
+}

package/lib/worker-transfer.d.ts

@@ -0,0 +1,6 @@
+export type TransferableBytes = Readonly<{
+    value: Uint8Array;
+    transfer: readonly ArrayBuffer[];
+}>;
+/** @internal Never transfer unrelated bytes from a larger backing buffer. */
+export declare function prepareTransferableBytes(value: Uint8Array): TransferableBytes;

package/lib/worker-transfer.js

@@ -0,0 +1,11 @@
+/** @internal Never transfer unrelated bytes from a larger backing buffer. */
+export function prepareTransferableBytes(value) {
+    if (!(value.buffer instanceof ArrayBuffer)) {
+        return { value, transfer: [] };
+    }
+    if (value.byteOffset === 0 && value.byteLength === value.buffer.byteLength) {
+        return { value, transfer: [value.buffer] };
+    }
+    const exact = value.slice();
+    return { value: exact, transfer: [exact.buffer] };
+}

package/lib/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/worker.js

@@ -0,0 +1,21 @@
+/// <reference lib="webworker" />
+import * as host from './host/index.mjs';
+import { openBrowserWorkerSession } from './direct-client-common.js';
+import { createWorkerSessionDispatcher } from './worker-dispatch.js';
+const scope = globalThis;
+const directHost = {
+    Directory: host.Directory,
+    init: host.init,
+    instantiateOliphauntDirect: host.instantiateOliphauntDirect,
+    prepareOliphauntTool: host.prepareOliphauntTool,
+    runOliphauntToolDirect: host.runOliphauntToolDirect,
+};
+// This package worker is the isolation boundary. Opening the direct session
+// here keeps PostgreSQL and synchronous OPFS handles in the same realm.
+const dispatch = createWorkerSessionDispatcher((options) => openBrowserWorkerSession(options, directHost), respond);
+scope.addEventListener('message', (event) => {
+    void dispatch(event.data);
+});
+function respond(response, transfer = []) {
+    scope.postMessage(response, [...transfer]);
+}

package/lib/zstd.d.ts

@@ -0,0 +1,4 @@
+export type ZstdDecompressor = (bytes: Uint8Array) => Uint8Array;
+/** @internal Installed by a host realm when it has a native implementation. */
+export declare function installZstdDecompressor(decompressor: ZstdDecompressor): void;
+export declare function decompressZstd(bytes: Uint8Array): Uint8Array;

package/lib/zstd.js

@@ -0,0 +1,12 @@
+import { decompress as decompressWithFzstd } from 'fzstd';
+let hostZstdDecompressor;
+/** @internal Installed by a host realm when it has a native implementation. */
+export function installZstdDecompressor(decompressor) {
+    if (hostZstdDecompressor !== undefined) {
+        throw new Error('Oliphaunt WASIX zstd decompressor is already installed');
+    }
+    hostZstdDecompressor = decompressor;
+}
+export function decompressZstd(bytes) {
+    return (hostZstdDecompressor ?? decompressWithFzstd)(bytes);
+}

package/node_modules/@oliphaunt/js-core/README.md

@@ -0,0 +1,7 @@
+# Shared JavaScript Core
+
+Canonical TypeScript helpers shared by the JavaScript, React Native, and WASIX
+TypeScript SDKs through the private `@oliphaunt/js-core` workspace package.
+
+Moon builds its ESM and CommonJS exports once. Published SDKs bundle that
+minimal private package so registry consumers do not need another dependency.

package/node_modules/@oliphaunt/js-core/dist/commonjs/protocol.d.ts

@@ -0,0 +1 @@
+export declare function simpleQuery(sql: string): Uint8Array;

package/node_modules/@oliphaunt/js-core/dist/commonjs/protocol.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simpleQuery = simpleQuery;
+const encoder = new TextEncoder();
+function simpleQuery(sql) {
+    if (sql.includes('\0')) {
+        throw new Error('simple query SQL must not contain NUL bytes');
+    }
+    const body = encoder.encode(sql);
+    const packet = new Uint8Array(body.length + 6);
+    packet[0] = 'Q'.charCodeAt(0);
+    writeI32(packet, 1, body.length + 5);
+    packet.set(body, 5);
+    packet[packet.length - 1] = 0;
+    return packet;
+}
+function writeI32(bytes, offset, value) {
+    bytes[offset] = (value >>> 24) & 0xff;
+    bytes[offset + 1] = (value >>> 16) & 0xff;
+    bytes[offset + 2] = (value >>> 8) & 0xff;
+    bytes[offset + 3] = value & 0xff;
+}