@rybosome/tspice 0.0.3 → 0.0.8

package/dist/transport/caching/withCaching.js

@@ -0,0 +1,335 @@
+import { createCachePolicy } from "./policy.js";
+export const MAX_KEY_SCAN = 10_000;
+export const MAX_KEY_LENGTH = 8192;
+export const MAX_KEY_STRING_LENGTH = 2048;
+const cachingTransportBrand = new WeakSet();
+const defaultOnWarning = (message) => {
+    if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(message);
+    }
+};
+/**
+ * Type guard for narrowing a transport returned by `withCaching()`.
+ */
+export function isCachingTransport(t) {
+    if (typeof t !== "object" || t === null)
+        return false;
+    if (!cachingTransportBrand.has(t))
+        return false;
+    const v = t;
+    return (typeof v.request === "function" &&
+        typeof v.clear === "function" &&
+        typeof v.dispose === "function");
+}
+function tryUnrefTimer(timer) {
+    let unref;
+    try {
+        unref = timer.unref;
+    }
+    catch {
+        return;
+    }
+    if (typeof unref !== "function")
+        return;
+    try {
+        unref.call(timer);
+    }
+    catch {
+        // Ignore. Some runtimes / shims may throw for `unref` even when present.
+    }
+}
+function isPlainObject(x) {
+    if (x === null || typeof x !== "object")
+        return false;
+    let proto;
+    try {
+        proto = Object.getPrototypeOf(x);
+    }
+    catch {
+        return false;
+    }
+    return proto === Object.prototype || proto === null;
+}
+function containsBinaryLikeData(value, seen, budget) {
+    if (value == null)
+        return false;
+    const g = globalThis;
+    // Node: Buffer
+    if (g.Buffer?.isBuffer?.(value))
+        return true;
+    // ArrayBuffer / TypedArrays / DataView
+    if (typeof ArrayBuffer !== "undefined") {
+        if (value instanceof ArrayBuffer)
+            return true;
+        if (ArrayBuffer.isView(value))
+            return true;
+    }
+    // SharedArrayBuffer (when available)
+    if (g.SharedArrayBuffer && value instanceof g.SharedArrayBuffer)
+        return true;
+    // Blob / File (when available)
+    if (typeof Blob !== "undefined" && value instanceof Blob)
+        return true;
+    if (typeof File !== "undefined" && value instanceof File)
+        return true;
+    if (typeof value === "string") {
+        // Treat very large strings like binary payloads: they produce huge keys and
+        // are often effectively opaque.
+        return value.length > MAX_KEY_STRING_LENGTH;
+    }
+    const t = typeof value;
+    if (t === "function")
+        return true;
+    if (t !== "object")
+        return false;
+    const obj = value;
+    if (seen.has(obj))
+        return false;
+    seen.add(obj);
+    // Only traverse JSON-like containers: arrays and plain objects with enumerable
+    // data properties. Everything else fails closed (disable caching).
+    if (Array.isArray(value)) {
+        let len;
+        try {
+            len = value.length;
+        }
+        catch {
+            return true;
+        }
+        // Scan budget is a *total* budget across args; treat large arrays as
+        // non-cacheable (fail closed) rather than doing excessive descriptor work.
+        if (len > budget.remaining)
+            return true;
+        for (let i = 0; i < len; i++) {
+            if (budget.remaining-- <= 0)
+                return true;
+            // Detect holes (sparse arrays). JSON.stringify normalizes these to `null`,
+            // which can lead to key collisions. Fail closed.
+            if (!Object.prototype.hasOwnProperty.call(value, i))
+                return true;
+            let desc;
+            try {
+                desc = Object.getOwnPropertyDescriptor(value, i);
+            }
+            catch {
+                return true;
+            }
+            // Should be impossible after hasOwnProperty, but fail closed just in case
+            // (e.g. Proxies).
+            if (!desc)
+                return true;
+            if (desc.get || desc.set)
+                return true;
+            if (containsBinaryLikeData(desc.value, seen, budget))
+                return true;
+        }
+        return false;
+    }
+    if (!isPlainObject(value))
+        return true;
+    // Avoid Object.getOwnPropertyDescriptors(value) (bulk descriptor allocation).
+    // Scan incrementally and bail early if we hit the global scan budget.
+    for (const key of Object.keys(value)) {
+        if (budget.remaining-- <= 0)
+            return true;
+        let desc;
+        try {
+            desc = Object.getOwnPropertyDescriptor(value, key);
+        }
+        catch {
+            return true;
+        }
+        if (!desc)
+            return true;
+        // `for...in` only enumerates enumerable properties, but keep this as a
+        // defensive guardrail.
+        if (!desc.enumerable)
+            continue;
+        if (desc.get || desc.set)
+            return true;
+        if (containsBinaryLikeData(desc.value, seen, budget))
+            return true;
+    }
+    return false;
+}
+/**
+ * Default cache key function used by `withCaching()`.
+ *
+ * Note: for plain objects, cache key stability (and hit rate) depends on object
+ * key insertion order, since this uses `JSON.stringify` and does not sort
+ * keys.
+ */
+export function defaultSpiceCacheKey(op, args) {
+    try {
+        // Normalize certain ops for better cache hit rates.
+        //
+        // - `kit.getState({ target, observer, ... })` accepts `string | number` body
+        //   refs, but downstream SPICE expects strings. Normalize to strings for
+        //   cache keys so `1` and "1" don't diverge.
+        const normalizedArgs = op === "kit.getState" &&
+            args.length === 1 &&
+            isPlainObject(args[0]) &&
+            (typeof args[0].target === "string" ||
+                typeof args[0].target === "number") &&
+            (typeof args[0].observer === "string" ||
+                typeof args[0].observer === "number")
+            ? [
+                {
+                    ...args[0],
+                    target: String(args[0].target),
+                    observer: String(args[0].observer),
+                },
+            ]
+            : args;
+        const seen = new WeakSet();
+        const budget = { remaining: MAX_KEY_SCAN };
+        for (const arg of normalizedArgs) {
+            if (containsBinaryLikeData(arg, seen, budget))
+                return null;
+        }
+        const key = JSON.stringify([op, normalizedArgs]);
+        if (key.length > MAX_KEY_LENGTH)
+            return null;
+        return key;
+    }
+    catch {
+        // Safer failure mode: if we can't build a stable key, don't cache.
+        return null;
+    }
+}
+/**
+ * Add a cache layer to a transport.
+ *
+ * Note: cached values are returned by reference. If a caller mutates the
+ * returned object/array, subsequent cache hits will observe that mutation.
+ * Treat results as immutable (or clone them yourself) when caching is enabled.
+ */
+export function withCaching(base, opts) {
+    const rawMaxEntries = opts?.maxEntries;
+    const maxEntries = rawMaxEntries ?? 1000;
+    const maxEntriesLimit = maxEntries === Infinity
+        ? undefined
+        : Number.isFinite(maxEntries)
+            ? maxEntries
+            : 0;
+    const rawTtlMs = opts?.ttlMs;
+    const ttlMs = rawTtlMs == null ? undefined : rawTtlMs;
+    const cachingEnabled = (ttlMs === undefined || ttlMs > 0) &&
+        (maxEntriesLimit === undefined || maxEntriesLimit > 0);
+    // True no-op mode: preserve the input object identity and avoid allocating
+    // any wrapper state when caching is disabled.
+    if (!cachingEnabled)
+        return base;
+    // Only pick defaults after the no-op early return so disabled caching pays
+    // ~0 overhead.
+    const now = opts?.now ?? Date.now;
+    const onWarning = opts?.onWarning ?? defaultOnWarning;
+    const keyFn = opts?.key ?? defaultSpiceCacheKey;
+    const policyByOp = opts?.policy;
+    const allowUnsafePolicyOverrides = opts?.allowUnsafePolicyOverrides === true;
+    const allowBroadNoStorePrefixes = opts?.allowBroadNoStorePrefixes === true;
+    const getPolicy = createCachePolicy({
+        wrapperName: "withCaching()",
+        onWarning,
+        policyByOp,
+        noStorePrefixes: opts?.noStorePrefixes,
+        allowBroadNoStorePrefixes,
+        allowUnsafePolicyOverrides,
+    });
+    const cache = new Map();
+    let sweepTimer;
+    const isExpired = (entry, now) => entry.expiresAt !== undefined && entry.expiresAt <= now;
+    const cleanupExpired = (now) => {
+        // TTL eviction is optional. When ttlMs is undefined, the cache is “forever”
+        // (still LRU-bounded by maxEntries).
+        if (ttlMs === undefined || ttlMs <= 0)
+            return;
+        for (const [k, entry] of cache) {
+            if (isExpired(entry, now))
+                cache.delete(k);
+        }
+    };
+    if (cachingEnabled && ttlMs !== undefined && ttlMs > 0) {
+        const sweepIntervalMs = opts?.sweepIntervalMs;
+        if (sweepIntervalMs !== undefined && sweepIntervalMs > 0) {
+            sweepTimer = setInterval(() => cleanupExpired(now()), sweepIntervalMs);
+            // In Node, interval timers keep the event loop alive by default. `unref()`
+            // prevents this from pinning test runners / CLIs. Browsers return a
+            // numeric id (no-op).
+            tryUnrefTimer(sweepTimer);
+        }
+    }
+    const clear = () => {
+        cache.clear();
+    };
+    const dispose = () => {
+        if (sweepTimer !== undefined) {
+            clearInterval(sweepTimer);
+            sweepTimer = undefined;
+        }
+        cache.clear();
+    };
+    const touch = (k, entry) => {
+        cache.delete(k);
+        cache.set(k, entry);
+    };
+    const enforceMaxEntries = () => {
+        if (maxEntriesLimit === undefined)
+            return;
+        while (cache.size > maxEntriesLimit) {
+            const oldestKey = cache.keys().next().value;
+            if (oldestKey === undefined)
+                return;
+            cache.delete(oldestKey);
+        }
+    };
+    const request = (op, args) => {
+        // Per-method cache policy. When bypassing, skip *all* cache work (no key
+        // computation, no reads/writes, no TTL sweeps).
+        if (getPolicy(op) === "no-store")
+            return base.request(op, args);
+        const k = keyFn(op, args);
+        if (k == null)
+            return base.request(op, args);
+        const nowMs = now();
+        cleanupExpired(nowMs);
+        const existing = cache.get(k);
+        if (existing && !isExpired(existing, nowMs)) {
+            // LRU touch on access. TTL remains absolute (does not refresh on access).
+            touch(k, existing);
+            return existing.promise;
+        }
+        if (existing)
+            cache.delete(k);
+        // Cache the in-flight promise to dedupe concurrent callers.
+        let promise;
+        promise = base.request(op, args).then((value) => {
+            if (ttlMs !== undefined && ttlMs > 0) {
+                const current = cache.get(k);
+                if (current?.promise === promise) {
+                    current.expiresAt = now() + ttlMs;
+                }
+            }
+            return value;
+        }, (err) => {
+            // Never cache rejections.
+            const current = cache.get(k);
+            if (current?.promise === promise)
+                cache.delete(k);
+            throw err;
+        });
+        cache.set(k, { promise });
+        enforceMaxEntries();
+        return promise;
+    };
+    const transport = { request, clear, dispose };
+    // Preserve any extra properties on the base transport (e.g. testing hooks)
+    // while still allowing us to override the core methods.
+    //
+    // This also keeps `instanceof`/prototype checks (if any) behaving as users
+    // might expect.
+    const transportWithProto = Object.assign(Object.create(base), transport);
+    cachingTransportBrand.add(transportWithProto);
+    return transportWithProto;
+}
+//# sourceMappingURL=withCaching.js.map

package/dist/transport/caching/withCachingSync.d.ts

@@ -0,0 +1,24 @@
+import type { SpiceTransportSync } from "../types.js";
+import { type WithCachingOptions } from "./withCaching.js";
+export type CachingTransportSync = SpiceTransportSync & {
+    /**
+     * Clear all cached entries.
+     *
+     * Notes:
+     * - This does not cancel in-flight requests; it just drops references so
+     *   results won't be reused.
+     * - This does not stop the optional TTL sweep timer. Use `dispose()` to stop
+     *   timers and clear cache.
+     */
+    clear(): void;
+    /** Stop any sweep timers and clear all cached entries. */
+    dispose(): void;
+};
+export type WithCachingSyncResult = SpiceTransportSync | CachingTransportSync;
+/**
+ * Type guard for narrowing a transport returned by `withCachingSync()`.
+ */
+export declare function isCachingTransportSync(t: unknown): t is CachingTransportSync;
+/** Wrap a sync transport with an in-memory response cache (LRU-ish + optional TTL). */
+export declare function withCachingSync(base: SpiceTransportSync, opts?: WithCachingOptions): WithCachingSyncResult;
+//# sourceMappingURL=withCachingSync.d.ts.map

package/dist/transport/caching/withCachingSync.js

@@ -0,0 +1,161 @@
+import { createCachePolicy } from "./policy.js";
+import { defaultSpiceCacheKey, } from "./withCaching.js";
+const cachingTransportBrand = new WeakSet();
+const defaultOnWarning = (message) => {
+    if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(message);
+    }
+};
+/**
+ * Type guard for narrowing a transport returned by `withCachingSync()`.
+ */
+export function isCachingTransportSync(t) {
+    if (typeof t !== "object" || t === null)
+        return false;
+    if (!cachingTransportBrand.has(t))
+        return false;
+    const v = t;
+    return (typeof v.request === "function" &&
+        typeof v.clear === "function" &&
+        typeof v.dispose === "function");
+}
+function tryUnrefTimer(timer) {
+    let unref;
+    try {
+        unref = timer.unref;
+    }
+    catch {
+        return;
+    }
+    if (typeof unref !== "function")
+        return;
+    try {
+        unref.call(timer);
+    }
+    catch {
+        // Ignore. Some runtimes / shims may throw for `unref` even when present.
+    }
+}
+/** Wrap a sync transport with an in-memory response cache (LRU-ish + optional TTL). */
+export function withCachingSync(base, opts) {
+    // Note: cached values are returned by reference. If a caller mutates the
+    // returned object/array, subsequent cache hits will observe that mutation.
+    // Treat results as immutable (or clone them yourself) when caching is enabled.
+    const rawMaxEntries = opts?.maxEntries;
+    const maxEntries = rawMaxEntries ?? 1000;
+    const maxEntriesLimit = maxEntries === Infinity
+        ? undefined
+        : Number.isFinite(maxEntries)
+            ? maxEntries
+            : 0;
+    const rawTtlMs = opts?.ttlMs;
+    const ttlMs = rawTtlMs == null ? undefined : rawTtlMs;
+    const cachingEnabled = (ttlMs === undefined || ttlMs > 0) &&
+        (maxEntriesLimit === undefined || maxEntriesLimit > 0);
+    // True no-op mode: preserve the input object identity and avoid allocating
+    // any wrapper state when caching is disabled.
+    if (!cachingEnabled)
+        return base;
+    // Only pick defaults after the no-op early return so disabled caching pays
+    // ~0 overhead.
+    const now = opts?.now ?? Date.now;
+    const onWarning = opts?.onWarning ?? defaultOnWarning;
+    const keyFn = opts?.key ?? defaultSpiceCacheKey;
+    const policyByOp = opts?.policy;
+    const allowUnsafePolicyOverrides = opts?.allowUnsafePolicyOverrides === true;
+    const allowBroadNoStorePrefixes = opts?.allowBroadNoStorePrefixes === true;
+    const getPolicy = createCachePolicy({
+        wrapperName: "withCachingSync()",
+        onWarning,
+        policyByOp,
+        noStorePrefixes: opts?.noStorePrefixes,
+        allowBroadNoStorePrefixes,
+        allowUnsafePolicyOverrides,
+    });
+    const cache = new Map();
+    let sweepTimer;
+    const isExpired = (entry, now) => entry.expiresAt !== undefined && entry.expiresAt <= now;
+    const cleanupExpired = (now) => {
+        // TTL eviction is optional. When ttlMs is undefined, the cache is “forever”
+        // (still LRU-bounded by maxEntries).
+        if (ttlMs === undefined || ttlMs <= 0)
+            return;
+        for (const [k, entry] of cache) {
+            if (isExpired(entry, now))
+                cache.delete(k);
+        }
+    };
+    if (cachingEnabled && ttlMs !== undefined && ttlMs > 0) {
+        const sweepIntervalMs = opts?.sweepIntervalMs;
+        if (sweepIntervalMs !== undefined && sweepIntervalMs > 0) {
+            sweepTimer = setInterval(() => cleanupExpired(now()), sweepIntervalMs);
+            // In Node, interval timers keep the event loop alive by default. `unref()`
+            // prevents this from pinning test runners / CLIs. Browsers return a
+            // numeric id (no-op).
+            tryUnrefTimer(sweepTimer);
+        }
+    }
+    const clear = () => {
+        cache.clear();
+    };
+    const dispose = () => {
+        if (sweepTimer !== undefined) {
+            clearInterval(sweepTimer);
+            sweepTimer = undefined;
+        }
+        cache.clear();
+    };
+    const touch = (k, entry) => {
+        cache.delete(k);
+        cache.set(k, entry);
+    };
+    const enforceMaxEntries = () => {
+        if (maxEntriesLimit === undefined)
+            return;
+        while (cache.size > maxEntriesLimit) {
+            const oldestKey = cache.keys().next().value;
+            if (oldestKey === undefined)
+                return;
+            cache.delete(oldestKey);
+        }
+    };
+    const request = (op, args) => {
+        // Per-method cache policy. When bypassing, skip *all* cache work (no key
+        // computation, no reads/writes, no TTL sweeps).
+        if (getPolicy(op) === "no-store")
+            return base.request(op, args);
+        const k = keyFn(op, args);
+        if (k == null)
+            return base.request(op, args);
+        const nowMs = now();
+        cleanupExpired(nowMs);
+        const existing = cache.get(k);
+        if (existing && !isExpired(existing, nowMs)) {
+            // LRU touch on access. TTL remains absolute (does not refresh on access).
+            touch(k, existing);
+            return existing.value;
+        }
+        if (existing)
+            cache.delete(k);
+        // Only cache successful responses.
+        let value;
+        try {
+            value = base.request(op, args);
+        }
+        catch (err) {
+            cache.delete(k);
+            throw err;
+        }
+        const entry = { value };
+        if (ttlMs !== undefined && ttlMs > 0) {
+            entry.expiresAt = now() + ttlMs;
+        }
+        cache.set(k, entry);
+        enforceMaxEntries();
+        return value;
+    };
+    const transport = { request, clear, dispose };
+    cachingTransportBrand.add(transport);
+    return transport;
+}
+//# sourceMappingURL=withCachingSync.js.map

package/dist/transport/rpc/protocol.d.ts

@@ -0,0 +1,35 @@
+export declare const tspiceRpcRequestType: "tspice:request";
+export declare const tspiceRpcResponseType: "tspice:response";
+export declare const tspiceRpcDisposeType: "tspice:dispose";
+export type RpcRequest = {
+    type: typeof tspiceRpcRequestType;
+    id: number;
+    op: string;
+    args: unknown[];
+};
+export type RpcDispose = {
+    type: typeof tspiceRpcDisposeType;
+};
+export type SerializedError = {
+    message: string;
+    name?: string;
+    stack?: string;
+};
+export type RpcResponse = {
+    type: typeof tspiceRpcResponseType;
+    id: number;
+    ok: true;
+    value: unknown;
+} | {
+    type: typeof tspiceRpcResponseType;
+    id: number;
+    ok: false;
+    error: SerializedError;
+};
+export type RpcMessageFromMain = RpcRequest | RpcDispose;
+export type RpcMessageFromWorker = RpcResponse;
+/** Serialize an unknown error into a structured, transferable shape for RPC. */
+export declare function serializeError(err: unknown): SerializedError;
+/** Deserialize an RPC-transferred error shape back into an {@link Error}. */
+export declare function deserializeError(err: unknown): Error;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/transport/rpc/protocol.js

@@ -0,0 +1,56 @@
+export const tspiceRpcRequestType = "tspice:request";
+export const tspiceRpcResponseType = "tspice:response";
+export const tspiceRpcDisposeType = "tspice:dispose";
+/** Serialize an unknown error into a structured, transferable shape for RPC. */
+export function serializeError(err) {
+    const defaultMessage = "Worker request failed";
+    const readStringProp = (obj, key) => {
+        if (!obj || typeof obj !== "object")
+            return undefined;
+        const v = obj[key];
+        return typeof v === "string" ? v : undefined;
+    };
+    if (err instanceof Error) {
+        const out = { message: err.message || defaultMessage };
+        if (typeof err.name === "string" && err.name)
+            out.name = err.name;
+        if (typeof err.stack === "string")
+            out.stack = err.stack;
+        return out;
+    }
+    if (typeof err === "string") {
+        return { message: err };
+    }
+    if (err && typeof err === "object") {
+        const message = readStringProp(err, "message") ?? defaultMessage;
+        const name = readStringProp(err, "name");
+        const stack = readStringProp(err, "stack");
+        const out = { message };
+        if (typeof name === "string" && name)
+            out.name = name;
+        if (typeof stack === "string")
+            out.stack = stack;
+        return out;
+    }
+    // Only stringify primitives (avoid calling an arbitrary `.toString()` on objects).
+    if (typeof err === "number" ||
+        typeof err === "boolean" ||
+        typeof err === "bigint") {
+        return { message: String(err) };
+    }
+    return { message: defaultMessage };
+}
+/** Deserialize an RPC-transferred error shape back into an {@link Error}. */
+export function deserializeError(err) {
+    if (err && typeof err === "object") {
+        const e = err;
+        const out = new Error(typeof e.message === "string" ? e.message : "Worker request failed");
+        if (typeof e.name === "string")
+            out.name = e.name;
+        if (typeof e.stack === "string")
+            out.stack = e.stack;
+        return out;
+    }
+    return new Error(typeof err === "string" ? err : "Worker request failed");
+}
+//# sourceMappingURL=protocol.js.map

package/dist/transport/rpc/taskScheduling.d.ts

@@ -0,0 +1,20 @@
+export type QueueMacrotaskOptions = {
+    /**
+     * When no macrotask scheduler exists (no `MessageChannel` and no `setTimeout`),
+     * there is no way to create a real task boundary.
+     *
+     * - `true` (default): invoke `fn()` synchronously as a best-effort fallback.
+     * - `false`: do not call `fn()` and return `false`.
+     */
+    allowSyncFallback?: boolean;
+};
+/**
+ * Probe whether a true macrotask scheduler is available in the current runtime
+ * (without actually scheduling a task).
+ */
+export declare function canQueueMacrotask(): boolean;
+/** Queue `fn` on the next macrotask (MessageChannel preferred; setTimeout fallback). */
+export declare function queueMacrotask(fn: () => void, opts?: QueueMacrotaskOptions): boolean;
+/** Return a promise that resolves on the next macrotask boundary (rejects if unavailable). */
+export declare function nextMacrotask(): Promise<void>;
+//# sourceMappingURL=taskScheduling.d.ts.map