knitting 0.1.51 → 0.1.53

package/src/runtime/tx-queue.d.ts

@@ -1,4 +1,4 @@
-import { type Task, type Lock2 } from "../memory/lock.js";
+import { type Lock2, type Task } from "../memory/lock.js";
 import type { AbortSignalOption, TaskTimeout } from "../types.js";
 import { type SignalAbortStore } from "../shared/abortSignal.js";
 type RawArguments = unknown;
@@ -9,10 +9,11 @@ type CreateHostTxQueueArgs = {
     max?: number;
     lock: Lock2;
     returnLock: Lock2;
+    releaseBufferReferenceReturn?: (token: bigint) => void;
     abortSignals?: Pick<SignalAbortStore, "getSignal" | "setSignal" | "resetSignal" | "closeNow">;
     now?: () => number;
 };
-export declare function createHostTxQueue({ max, lock, returnLock, abortSignals, now, }: CreateHostTxQueueArgs): {
+export declare function createHostTxQueue({ max, lock, returnLock, releaseBufferReferenceReturn, abortSignals, now, }: CreateHostTxQueueArgs): {
     rejectAll: (reason: string) => void;
     hasPendingFrames: () => boolean;
     txIdle: () => boolean;

package/src/runtime/tx-queue.js

@@ -1,6 +1,7 @@
-import { makeTask, resetTaskLocalFlags, TaskIndex, } from "../memory/lock.js";
+import { makeTask, resetTaskLocalFlags, runTaskFinalizers, TaskIndex, } from "../memory/lock.js";
 import { withResolvers } from "../common/with-resolvers.js";
 import { AbortSignalPoolExhausted, OneShotDeferred, } from "../shared/abortSignal.js";
+import { withBufferReferenceReturnReleaser } from "../connections/buffer-reference.js";
 const SLOT_INDEX_MASK = 31;
 const SLOT_META_MASK = 0x07ffffff;
 const SLOT_META_SHIFT = 5;
@@ -10,7 +11,7 @@ const FUNCTION_META_SHIFT = 16;
 const ABORT_SIGNAL_META_OFFSET = 1;
 const NO_ABORT_SIGNAL = -1;
 const p_now = performance.now.bind(performance);
-export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, }) {
+export function createHostTxQueue({ max, lock, returnLock, releaseBufferReferenceReturn, abortSignals, now, }) {
     const PLACE_HOLDER = (_) => {
         throw ("UNREACHABLE FROM PLACE HOLDER (main)");
     };
@@ -26,7 +27,6 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
     const initialSize = max ?? 10;
     const queue = Array.from({ length: initialSize }, (_, index) => newSlot(index));
     const freeSockets = Array.from({ length: initialSize }, (_, i) => i);
-    // Local count
     const freePush = (id) => freeSockets.push(id);
     const freePop = () => freeSockets.pop();
     const queuePush = (task) => queue.push(task);
@@ -40,13 +40,16 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
         onResolved: (task) => {
             inUsed = (inUsed - 1) | 0;
             resetTaskLocalFlags(task);
+            runTaskFinalizers(task);
             task.value = null;
             task.resolve = PLACE_HOLDER;
             task.reject = PLACE_HOLDER;
             freePush(task[TaskIndex.ID]);
         },
     });
-    // Helpers
+    const completeFrame = releaseBufferReferenceReturn === undefined
+        ? resolveReturn
+        : () => withBufferReferenceReturnReleaser(releaseBufferReferenceReturn, resolveReturn);
     const txIdle = () => getPendingFrameCount() === 0 && inUsed === getPendingPromiseCount();
     const rejectAll = (reason) => {
         for (let index = 0; index < queue.length; index++) {
@@ -57,6 +60,7 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
                 }
                 catch {
                 }
+                runTaskFinalizers(slot);
                 slot.resolve = PLACE_HOLDER;
                 slot.reject = PLACE_HOLDER;
                 queue[index] = newSlot(index);
@@ -73,13 +77,13 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
         rejectAll,
         hasPendingFrames,
         txIdle,
-        completeFrame: resolveReturn,
+        completeFrame,
         enqueue: (functionID, timeout, abortSignal) => {
             const HAS_TIMER = timeout !== undefined;
             const functionIDMasked = functionID & FUNCTION_ID_MASK;
-            const USE_SIGNAL = abortSignal !== undefined && abortSignals !== undefined;
+            const USE_SIGNAL = abortSignal !== undefined &&
+                abortSignals !== undefined;
             return (rawArgs) => {
-                // Expanding size if needed
                 if (inUsed === queue.length) {
                     const newSize = inUsed + 32;
                     let current = queue.length;
@@ -101,19 +105,19 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
                     new OneShotDeferred(deferred, () => resetSignal(maybeSignal), () => {
                         abortSignals.setSignal(maybeSignal);
                     });
-                    const encodedSignalMeta = ((maybeSignal + ABORT_SIGNAL_META_OFFSET) & FUNCTION_META_MASK) >>> 0;
+                    const encodedSignalMeta = ((maybeSignal + ABORT_SIGNAL_META_OFFSET) & FUNCTION_META_MASK) >>>
+                        0;
                     slot[TaskIndex.FunctionID] =
-                        ((encodedSignalMeta << FUNCTION_META_SHIFT) | functionIDMasked) >>> 0;
+                        ((encodedSignalMeta << FUNCTION_META_SHIFT) | functionIDMasked) >>>
+                            0;
                 }
-                // Set info
                 slot.value = rawArgs;
                 slot[TaskIndex.ID] = index;
                 slot.resolve = deferred.resolve;
                 slot.reject = deferred.reject;
                 if (HAS_TIMER) {
-                    slot[TaskIndex.slotBuffer] =
-                        ((slot[TaskIndex.slotBuffer] & SLOT_INDEX_MASK) |
-                            ((((nowTime() >>> 0) & SLOT_META_MASK) << SLOT_META_SHIFT) >>> 0)) >>> 0;
+                    slot[TaskIndex.slotBuffer] = ((slot[TaskIndex.slotBuffer] & SLOT_INDEX_MASK) |
+                        ((((nowTime() >>> 0) & SLOT_META_MASK) << SLOT_META_SHIFT) >>> 0)) >>> 0;
                 }
                 void publish(slot);
                 inUsed = (inUsed + 1) | 0;
@@ -132,6 +136,7 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
                 catch {
                 }
                 resetTaskLocalFlags(task);
+                runTaskFinalizers(task);
                 task.value = null;
                 task.resolve = PLACE_HOLDER;
                 task.reject = PLACE_HOLDER;

package/src/types.d.ts

@@ -1,5 +1,5 @@
 import { endpointSymbol } from "./common/task-symbol.js";
-import type { Envelope } from "./common/envelope.js";
+import type { Envelope, EnvelopeBody, EnvelopeHeader } from "./common/envelope.js";
 import type { LockBufferTextCompat, SharedBufferTextCompat } from "./common/shared-buffer-text.js";
 import type { SharedBufferRegion, SharedBufferSource } from "./common/shared-buffer-region.js";
 import type { PayloadBufferMode, PayloadBufferOptions } from "./memory/payload-config.js";
@@ -32,8 +32,18 @@ type WorkerData = {
     lock: LockBuffers;
     returnLock: LockBuffers;
     payloadConfig?: PayloadBufferOptions;
+    bufferReferenceReturn?: "copy" | "borrow";
     permission?: ResolvedPermissionProtocol;
 };
+type UnsafeOptions = {
+    /**
+     * Experimental `BufferReference` return lifetime.
+     *
+     * `"copy"` is safe after worker release. `"borrow"` skips the Deno/Bun copy,
+     * but must be released before producer shutdown and must not outlive its ref.
+     */
+    BufferReferenceReturn?: "copy" | "borrow";
+};
 type LockBuffers = {
     headers: SharedBufferSource;
     headerSlotStrideU32?: number;
@@ -49,11 +59,14 @@ interface JSONObject {
 interface JSONArray extends Array<JSONValue> {
 }
 type Serializable = string | object | number | boolean | bigint;
-type ValidInput = bigint | void | JSONValue | symbol | ArrayBuffer | Uint8Array | Int32Array | Float64Array | BigInt64Array | BigUint64Array | DataView | Error | Date | Envelope;
+type ValidInput = bigint | void | JSONValue | symbol | ArrayBuffer | Uint8Array | Int32Array | Float64Array | BigInt64Array | BigUint64Array | DataView | Error | Date | Envelope<EnvelopeHeader, EnvelopeBody>;
 type Args = ValidInput | Serializable;
 type MaybePromise<T> = T | Promise<T>;
+/** Blob payloads are not supported; pass ArrayBuffer/typed arrays instead. */
 type NoBlob<T> = T extends Blob ? never : T;
+/** Task input may be a direct value or native Promise; thenables are plain values. */
 type TaskInput = NoBlob<Args> | Promise<NoBlob<Args>>;
+/** Per-call timeout. A number is milliseconds; object form can return a default. */
 type TaskTimeout = number | {
     time: number;
     maybe?: true;
@@ -66,6 +79,7 @@ type BivariantCallback<Args extends unknown[], R> = {
 type AbortSignalConfig = {
     readonly hasAborted: true;
 };
+/** `true` or config injects an abort toolkit as the task's second parameter. */
 type AbortSignalOption = true | AbortSignalConfig | undefined;
 type AbortSignalMethods<AS extends AbortSignalOption> = AS extends undefined ? never : {
     hasAborted: () => boolean;
@@ -88,13 +102,16 @@ type tasks = Record<string, Composed<any, any, AbortSignalOption> | TaskFunction
 type ComposedWithKey = Composed<any, any, AbortSignalOption> & {
     name: string;
 };
-type PromiseWrapped<F extends (...args: any[]) => any, AS extends AbortSignalOption = undefined> = (...args: PromisifyCallArgs<F, AS>) => (AS extends undefined ? Promise<Awaited<ReturnType<F>>> : PromiseWithMaybeReject<Awaited<ReturnType<F>>>);
+type PromiseWrapped<F extends (...args: any[]) => any, AS extends AbortSignalOption = undefined> = (...args: PromisifyCallArgs<F, AS>) => AS extends undefined ? Promise<Awaited<ReturnType<F>>> : PromiseWithMaybeReject<Awaited<ReturnType<F>>>;
 type PromiseInput<T> = T | Promise<T>;
 type PromisifyArgs<T extends unknown[]> = {
     [K in keyof T]: PromiseInput<T[K]>;
 };
 type NormalizeUndefinedSingleArg<T extends unknown[]> = T extends [undefined] ? [] | [undefined] : T;
-type AbortAwareCallArgs<T extends unknown[]> = T extends [...infer Head, AbortSignalToolkit<any>] ? NormalizeUndefinedSingleArg<Head> : NormalizeUndefinedSingleArg<T>;
+type AbortAwareCallArgs<T extends unknown[]> = T extends [
+    ...infer Head,
+    AbortSignalToolkit<any>
+] ? NormalizeUndefinedSingleArg<Head> : NormalizeUndefinedSingleArg<T>;
 type HostCallArgs<F extends (...args: any[]) => any, AS extends AbortSignalOption> = AS extends undefined ? Parameters<F> : AbortAwareCallArgs<Parameters<F>>;
 type PromisifyCallArgs<F extends (...args: any[]) => any, AS extends AbortSignalOption> = HostCallArgs<F, AS> extends infer T ? T extends unknown[] ? PromisifyArgs<T> : never : never;
 type TaskCallable<T> = T extends TaskLike<any> ? T["f"] : T extends TaskFunctionLike ? T : never;
@@ -105,7 +122,9 @@ type FunctionMapType<T extends Record<string, TaskLike<any> | TaskFunctionLike>>
     [K in keyof T]: PromiseWrapped<TaskCallable<T[K]>, AbortSignalOfTask<T[K]>>;
 };
 interface FixPointBase<A extends TaskInput, B extends Args, AS extends AbortSignalOption = undefined> {
+    /** Worker function. It receives one value; use a tuple/object for many inputs. */
     readonly f: TaskFn<A, B, AS>;
+    /** Soft call timeout. Use `worker.hardTimeoutMs` for runaway CPU walls. */
     readonly timeout?: TaskTimeout;
 }
 type FixPoint<A extends TaskInput, B extends Args, AS extends AbortSignalOption = undefined> = FixPointBase<A, B, AS> & (AS extends undefined ? {
@@ -114,37 +133,39 @@ type FixPoint<A extends TaskInput, B extends Args, AS extends AbortSignalOption
     readonly abortSignal: AS;
 });
 type ImportTaskOptions<A extends TaskInput = void, B extends Args = void, AS extends AbortSignalOption = undefined> = Omit<FixPoint<A, B, AS>, "f"> & {
+    /** Module imported by the worker only. Relative paths resolve from caller. */
     readonly href: string;
+    /** Plain function export name. Defaults to `"default"`; do not target `task()`. */
     readonly name?: string;
 };
 type SecondPart = {
     readonly [endpointSymbol]: true;
     readonly id: number;
-    /**
-     * IMPORTANT: `at` helps to create a `createPool` because we dont know
-     * the name of the variable at runtime, so basically this gets the logical order
-     * of the exported file, so no matter the name the worker can track which ` task `
-     * to track
-     */
+    /** Logical export order used to match worker tasks before names are known. */
     readonly at: number;
     readonly importedFrom: string;
     /**
-     * Marks a task whose worker-side function is imported dynamically (via
-     * `importTask`). Such tasks must never run on the host inliner lane: their
-     * module import is meant to happen inside the worker so worker permission
-     * policies apply. The pool routes them to worker lanes only, even when the
-     * inliner is enabled for other tasks.
+     * Imported tasks stay on worker lanes so imports run under worker permissions.
      */
     readonly imported?: boolean;
 };
 type SingleTaskPool<A extends TaskInput = Args, B extends Args = Args, AS extends AbortSignalOption = undefined> = {
+    /** Invoke the single task. Arguments may be native Promises. */
     call: PromiseWrapped<TaskFn<A, B, AS>, AS>;
+    /** Await worker teardown now. `using` disposes at scope exit without awaiting. */
     shutdown: (delayMs?: number) => Promise<void>;
+    /** Starts shutdown at scope exit. Use `shutdown()` when you must await it. */
     [Symbol.dispose]: () => void;
 };
 type Pool<T extends Record<string, TaskLike<any> | TaskFunctionLike>> = {
+    /** Await worker teardown now. `using` disposes at scope exit without awaiting. */
     shutdown: (delayMs?: number) => Promise<void>;
+    /** Starts shutdown at scope exit. Use `shutdown()` when you must await it. */
     [Symbol.dispose]: () => void;
+    /**
+     * Typed task callers. Each call accepts the task input or a native Promise.
+     * Thrown errors/rejections reject here as Error objects with cause chains.
+     */
     call: FunctionMapType<T>;
 };
 type ReturnFixed<A extends TaskInput = undefined, B extends Args = undefined, AS extends AbortSignalOption = undefined> = FixPoint<A, B, AS> & SecondPart & {
@@ -171,12 +192,13 @@ type Balancer = BalancerStrategy | {
      */
     strategy?: BalancerStrategy;
 };
-type DebugOptions = {
-    extras?: boolean;
-    logMain?: boolean;
-    logHref?: boolean;
-    logImportedUrl?: boolean;
+/** Debug namespaces for host setup, worker state, imports, globals, and lifecycle. */
+type DebugNamespace = "host" | "globals" | "signals" | "imports" | "lifecycle";
+type DebugFlags = {
+    [Namespace in DebugNamespace]?: boolean;
 };
+/** Pass `true` for all debug, or enable namespaces by name. */
+type DebugOptions = boolean | DebugFlags;
 type WorkerBootstrapContext = {
     readonly thread: number;
     readonly totalNumberOfThread: number;
@@ -208,7 +230,7 @@ type WorkerSettings = {
     /**
      * Experimental worker runtime.
      * "thread" uses Worker/worker_threads. "process" spawns another JavaScript
-     * runtime and shares one inherited fd-backed memory mapping.
+     * runtime, useful for process isolation, bwrap, and containers.
      */
     runtime?: "thread" | "process";
     /**
@@ -276,38 +298,21 @@ type DispatcherSettings = {
     maxBackoffMs?: number;
 };
 type CreatePool = {
+    /** Number of workers. Default: 1. */
     threads?: number;
-    /**
-   * @deprecated Too risky with processes, need to rewrite or delete.
-   */
+    /** Add a host inline lane for regular tasks. Imported tasks still use workers. */
     inliner?: Inliner;
     balancer?: Balancer;
     worker?: WorkerSettings;
     /**
-     * Payload transport settings.
+     * Payload transport settings. Default dynamic payload cap is about 8 MiB
+     * (`payloadMaxByteLength >> 3`, with a 64 MiB growth cap).
      */
     payload?: PayloadBufferOptions;
     /**
-     * Initial payload SharedArrayBuffer size (bytes) per worker direction.
-     * Defaults to 4 MiB when growable SAB is available, otherwise defaults to
-     * `payloadMaxBytes`.
-     * @deprecated Use `payload.payloadInitialBytes`.
+     * Experimental unsafe options.
      */
-    payloadInitialBytes?: number;
-    /**
-     * Maximum payload SharedArrayBuffer size (bytes) per worker direction.
-     * Defaults to 64 MiB.
-     * @deprecated Use `payload.payloadMaxByteLength`.
-     */
-    payloadMaxBytes?: number;
-    /**
-     * @deprecated Use `payload.mode`.
-     */
-    bufferMode?: PayloadBufferMode;
-    /**
-     * @deprecated Use `payload.maxPayloadBytes`.
-     */
-    maxPayloadBytes?: number;
+    unsafe?: UnsafeOptions;
     /**
      * Abort-aware signal pool capacity.
      * Defaults to `258`.
@@ -324,19 +329,18 @@ type CreatePool = {
     workerExecArgv?: string[];
     /**
      * Runtime permission protocol.
-     * Omit to use strict defaults with `allowImport: true`.
+     * Omit to use strict defaults with `allowImport: true`; worker console is
+     * quiet unless `permission: { console: true }`.
+     *
+     * Task code cannot terminate the host: process/Deno exit APIs are blocked.
      * Use `"strict"` (default for object mode) or `"unsafe"`.
      * Accepts object form for fine-grained permission controls.
      */
     permission?: PermissionProtocolInput;
-    /**
-     * @deprecated Use `host` instead.
-     */
-    dispatcher?: DispatcherSettings;
     debug?: DebugOptions;
     source?: string;
 };
-export type { WorkerCall as WorkerCall, WorkerInvoke as WorkerInvoke, WorkerContext as WorkerContext, CreateContext as CreateContext, WorkerData as WorkerData, LockBuffers as LockBuffers, ValidInput as ValidInput, Args as Args, MaybePromise as MaybePromise, TaskInput as TaskInput, TaskTimeout as TaskTimeout, TaskFn as TaskFn, AbortSignalConfig as AbortSignalConfig, AbortSignalOption as AbortSignalOption, AbortSignalMethods as AbortSignalMethods, AbortSignalToolkit as AbortSignalToolkit, Composed as Composed, tasks as tasks, ComposedWithKey as ComposedWithKey, FunctionMapType as FunctionMapType, FixPoint as FixPoint, ImportTaskOptions as ImportTaskOptions, SecondPart as SecondPart, SingleTaskPool as SingleTaskPool, Pool as Pool, ReturnFixed as ReturnFixed, External as External, Inliner as Inliner, BalancerStrategy as BalancerStrategy, Balancer as Balancer, DebugOptions as DebugOptions, WorkerBootstrapContext as WorkerBootstrapContext, WorkerBootstrapFunction as WorkerBootstrapFunction, WorkerBootstrapOptions as WorkerBootstrapOptions, WorkerSettings as WorkerSettings, ProcessSharedMemoryMode as ProcessSharedMemoryMode, ProcessSharedMemorySettings as ProcessSharedMemorySettings, WorkerTimers as WorkerTimers, DispatcherSettings as DispatcherSettings, CreatePool as CreatePool, PayloadBufferMode as PayloadBufferMode, PayloadBufferOptions as PayloadBufferOptions, PermissionProtocol as PermissionProtocol, PermissionProtocolInput as PermissionProtocolInput, ResolvedPermissionProtocol as ResolvedPermissionProtocol, Envelope as Envelope, SharedBufferTextCompat as SharedBufferTextCompat, LockBufferTextCompat as LockBufferTextCompat, SharedBufferRegion as SharedBufferRegion, SharedBufferSource as SharedBufferSource, };
+export type { AbortSignalConfig as AbortSignalConfig, AbortSignalMethods as AbortSignalMethods, AbortSignalOption as AbortSignalOption, AbortSignalToolkit as AbortSignalToolkit, Args as Args, Balancer as Balancer, BalancerStrategy as BalancerStrategy, Composed as Composed, ComposedWithKey as ComposedWithKey, CreateContext as CreateContext, CreatePool as CreatePool, DebugNamespace as DebugNamespace, DebugOptions as DebugOptions, DispatcherSettings as DispatcherSettings, Envelope as Envelope, EnvelopeBody as EnvelopeBody, EnvelopeHeader as EnvelopeHeader, External as External, FixPoint as FixPoint, FunctionMapType as FunctionMapType, ImportTaskOptions as ImportTaskOptions, Inliner as Inliner, LockBuffers as LockBuffers, LockBufferTextCompat as LockBufferTextCompat, MaybePromise as MaybePromise, PayloadBufferMode as PayloadBufferMode, PayloadBufferOptions as PayloadBufferOptions, PermissionProtocol as PermissionProtocol, PermissionProtocolInput as PermissionProtocolInput, Pool as Pool, ProcessSharedMemoryMode as ProcessSharedMemoryMode, ProcessSharedMemorySettings as ProcessSharedMemorySettings, ResolvedPermissionProtocol as ResolvedPermissionProtocol, ReturnFixed as ReturnFixed, SecondPart as SecondPart, SharedBufferRegion as SharedBufferRegion, SharedBufferSource as SharedBufferSource, SharedBufferTextCompat as SharedBufferTextCompat, SingleTaskPool as SingleTaskPool, TaskFn as TaskFn, TaskInput as TaskInput, tasks as tasks, TaskTimeout as TaskTimeout, ValidInput as ValidInput, WorkerBootstrapContext as WorkerBootstrapContext, WorkerBootstrapFunction as WorkerBootstrapFunction, WorkerBootstrapOptions as WorkerBootstrapOptions, WorkerCall as WorkerCall, WorkerContext as WorkerContext, WorkerData as WorkerData, WorkerInvoke as WorkerInvoke, WorkerSettings as WorkerSettings, WorkerTimers as WorkerTimers, };
 export type { Task as Task } from "./memory/lock.js";
 export { LockBound as LockBound, PayloadBuffer as PayloadBuffer, PayloadSignal as PayloadSignal, TaskIndex as TaskIndex, } from "./memory/lock.js";
 export type { RegisterMalloc as RegisterMalloc } from "./memory/regionRegistry.js";

package/src/utils/http.d.ts

@@ -0,0 +1,29 @@
+export type BufferLike = ArrayBuffer | SharedArrayBuffer | ArrayBufferView;
+export type NumberFormat = "f64" | "f32" | "i32";
+export type NumberBufferOptions = {
+    format?: NumberFormat;
+};
+/** View ArrayBuffer/SharedArrayBuffer/typed-array bytes as Uint8Array. */
+export declare const bufferToBytes: (source: BufferLike) => Uint8Array;
+/** Copy bytes into a SharedArrayBuffer for zero-copy worker inputs. */
+export declare const bytesToBuffer: (source: BufferLike) => SharedArrayBuffer;
+/** Decode UTF-8 bytes from ArrayBuffer/SharedArrayBuffer/typed-array input. */
+export declare const bufferToString: (source: BufferLike) => string;
+/** Encode UTF-8 text into a SharedArrayBuffer. */
+export declare const stringToBuffer: (text: string) => SharedArrayBuffer;
+/** Decode JSON from UTF-8 bytes. */
+export declare const bufferToJson: <T = unknown>(source: BufferLike) => T;
+/** Encode JSON into a SharedArrayBuffer. */
+export declare const jsonToBuffer: (value: unknown) => SharedArrayBuffer;
+/** Encode numbers into a SharedArrayBuffer (`f64` by default). */
+export declare const numbersToBuffer: (numbers: ArrayLike<number>, options?: NumberBufferOptions) => SharedArrayBuffer;
+/** Decode numeric typed-array views from worker-friendly byte buffers. */
+export declare function bufferToNumbers(source: BufferLike, options?: {
+    format?: "f64";
+}): Float64Array;
+export declare function bufferToNumbers(source: BufferLike, options: {
+    format: "f32";
+}): Float32Array;
+export declare function bufferToNumbers(source: BufferLike, options: {
+    format: "i32";
+}): Int32Array;

package/src/utils/http.js

@@ -0,0 +1,100 @@
+const nodeBuffer = globalThis.Buffer;
+const hasNodeBuffer = typeof nodeBuffer?.from === "function" &&
+    typeof nodeBuffer?.byteLength === "function";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+const hasSharedArrayBuffer = typeof SharedArrayBuffer === "function";
+const isSharedArrayBuffer = (value) => hasSharedArrayBuffer && value instanceof SharedArrayBuffer;
+const BYTES_PER_ELEMENT = {
+    f64: 8,
+    f32: 4,
+    i32: 4,
+};
+const toBytes = (source) => {
+    if (source instanceof Uint8Array)
+        return source;
+    if (ArrayBuffer.isView(source)) {
+        return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+    }
+    if (source instanceof ArrayBuffer || isSharedArrayBuffer(source)) {
+        return new Uint8Array(source);
+    }
+    throw new TypeError("Expected an ArrayBuffer, SharedArrayBuffer, or typed-array view.");
+};
+/** View ArrayBuffer/SharedArrayBuffer/typed-array bytes as Uint8Array. */
+export const bufferToBytes = (source) => toBytes(source);
+/** Copy bytes into a SharedArrayBuffer for zero-copy worker inputs. */
+export const bytesToBuffer = (source) => {
+    const bytes = toBytes(source);
+    const sab = new SharedArrayBuffer(bytes.byteLength);
+    new Uint8Array(sab).set(bytes);
+    return sab;
+};
+const makeNumberView = (format, buffer, byteOffset, length) => {
+    switch (format) {
+        case "f64":
+            return new Float64Array(buffer, byteOffset, length);
+        case "f32":
+            return new Float32Array(buffer, byteOffset, length);
+        case "i32":
+            return new Int32Array(buffer, byteOffset, length);
+    }
+};
+/** Decode UTF-8 bytes from ArrayBuffer/SharedArrayBuffer/typed-array input. */
+export const bufferToString = (source) => {
+    const bytes = toBytes(source);
+    if (hasNodeBuffer) {
+        return nodeBuffer
+            .from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+            .toString("utf8");
+    }
+    return textDecoder.decode(bytes);
+};
+/** Encode UTF-8 text into a SharedArrayBuffer. */
+export const stringToBuffer = (text) => {
+    if (typeof text !== "string") {
+        throw new TypeError("stringToBuffer expects a string.");
+    }
+    if (hasNodeBuffer) {
+        const byteLength = nodeBuffer.byteLength(text, "utf8");
+        const sab = new SharedArrayBuffer(byteLength);
+        nodeBuffer.from(sab).write(text, "utf8");
+        return sab;
+    }
+    const encoded = textEncoder.encode(text);
+    const sab = new SharedArrayBuffer(encoded.byteLength);
+    new Uint8Array(sab).set(encoded);
+    return sab;
+};
+/** Decode JSON from UTF-8 bytes. */
+export const bufferToJson = (source) => JSON.parse(bufferToString(source));
+/** Encode JSON into a SharedArrayBuffer. */
+export const jsonToBuffer = (value) => {
+    const text = JSON.stringify(value);
+    if (typeof text !== "string") {
+        throw new TypeError("jsonToBuffer: value is not JSON-serializable (stringify returned undefined).");
+    }
+    return stringToBuffer(text);
+};
+/** Encode numbers into a SharedArrayBuffer (`f64` by default). */
+export const numbersToBuffer = (numbers, options) => {
+    const format = options?.format ?? "f64";
+    const sab = new SharedArrayBuffer(numbers.length * BYTES_PER_ELEMENT[format]);
+    makeNumberView(format, sab, 0, numbers.length).set(numbers);
+    return sab;
+};
+export function bufferToNumbers(source, options) {
+    const format = options?.format ?? "f64";
+    const bytesPer = BYTES_PER_ELEMENT[format];
+    const bytes = toBytes(source);
+    if (bytes.byteLength % bytesPer !== 0) {
+        throw new RangeError(`bufferToNumbers: byte length ${bytes.byteLength} is not a multiple of ` +
+            `${bytesPer} for format "${format}".`);
+    }
+    const length = bytes.byteLength / bytesPer;
+    if (bytes.byteOffset % bytesPer === 0) {
+        return makeNumberView(format, bytes.buffer, bytes.byteOffset, length);
+    }
+    const copy = bytes.slice();
+    return makeNumberView(format, copy.buffer, 0, length);
+}