@rybosome/tspice 0.0.3 → 0.0.8

package/dist/transport/rpc/taskScheduling.js

@@ -0,0 +1,98 @@
+/**
+ * Probe whether a true macrotask scheduler is available in the current runtime
+ * (without actually scheduling a task).
+ */
+export function canQueueMacrotask() {
+    // Prefer MessageChannel when available.
+    //
+    // Important: if MessageChannel exists but is broken (e.g. constructible but
+    // `postMessage` throws), we fall through to `setTimeout` rather than failing
+    // closed. This matches `queueMacrotask()` behavior.
+    if (typeof MessageChannel !== "undefined") {
+        try {
+            const { port1, port2 } = new MessageChannel();
+            try {
+                // Probe that `postMessage` works (some polyfills allow construction but
+                // throw on `postMessage`, which would otherwise deadlock queueing).
+                port2.postMessage(undefined);
+                return true;
+            }
+            finally {
+                // Always close ports so they don't keep the event loop alive in Node.
+                // Be defensive: some polyfills/test environments may not implement `close()`.
+                try {
+                    port1.close?.();
+                }
+                catch {
+                    // ignore
+                }
+                try {
+                    port2.close?.();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        catch {
+            // Ignore and fall back to setTimeout.
+        }
+    }
+    return typeof setTimeout === "function";
+}
+/** Queue `fn` on the next macrotask (MessageChannel preferred; setTimeout fallback). */
+export function queueMacrotask(fn, opts) {
+    const allowSyncFallback = opts?.allowSyncFallback ?? true;
+    // Prefer MessageChannel when available. This schedules a real task boundary
+    // without relying on timers, which makes it friendlier to fake-timer test
+    // environments.
+    try {
+        if (typeof MessageChannel !== "undefined") {
+            const { port1, port2 } = new MessageChannel();
+            const port1WithOnMessage = port1;
+            port1WithOnMessage.onmessage = () => {
+                port1WithOnMessage.onmessage = null;
+                // Close ports so this doesn't keep the event loop alive in Node.
+                // Be defensive: some polyfills/test environments may not implement
+                // `close()`.
+                try {
+                    port1.close?.();
+                }
+                catch {
+                    // ignore
+                }
+                try {
+                    port2.close?.();
+                }
+                catch {
+                    // ignore
+                }
+                fn();
+            };
+            port2.postMessage(undefined);
+            return true;
+        }
+    }
+    catch {
+        // Ignore and fall back to setTimeout.
+    }
+    // Next preference: a real macrotask via setTimeout.
+    if (typeof setTimeout === "function") {
+        setTimeout(fn, 0);
+        return true;
+    }
+    // No macrotask scheduler available in this runtime.
+    if (allowSyncFallback)
+        fn();
+    return false;
+}
+/** Return a promise that resolves on the next macrotask boundary (rejects if unavailable). */
+export function nextMacrotask() {
+    return new Promise((resolve, reject) => {
+        const ok = queueMacrotask(resolve, { allowSyncFallback: false });
+        if (!ok) {
+            reject(new Error("nextMacrotask(): no macrotask scheduler available (MessageChannel/setTimeout missing)"));
+        }
+    });
+}
+//# sourceMappingURL=taskScheduling.js.map

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

@@ -0,0 +1,5 @@
+/** Encode an arbitrary value into a structured-clone-safe shape. */
+export declare function encodeRpcValue(value: unknown): unknown;
+/** Decode a value that was encoded by {@link encodeRpcValue}. */
+export declare function decodeRpcValue(value: unknown): unknown;
+//# sourceMappingURL=valueCodec.d.ts.map

package/dist/transport/rpc/valueCodec.js

@@ -0,0 +1,106 @@
+import { Mat3 } from "../../kit/math/mat3.js";
+/**
+ * Values sent across the worker boundary must be structured-clone-safe.
+ *
+ * This codec provides a minimal, extensible tagged encoding for non-plain
+ * objects (e.g. `Mat3`) used by the tspice API.
+ */
+const tspiceRpcTagKey = "__tspiceRpcTag";
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+function isTaggedRecord(value) {
+    return isRecord(value) && tspiceRpcTagKey in value;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isMat3RowMajorData(value) {
+    return (Array.isArray(value) && value.length === 9 && value.every(isFiniteNumber));
+}
+/** Encode an arbitrary value into a structured-clone-safe shape. */
+export function encodeRpcValue(value) {
+    if (value instanceof Mat3) {
+        const data = Array.from(value.rowMajor);
+        return {
+            [tspiceRpcTagKey]: "Mat3",
+            layout: "rowMajor",
+            data,
+        };
+    }
+    if (Array.isArray(value)) {
+        return value.map(encodeRpcValue);
+    }
+    // Fast-path: ArrayBuffer + views (TypedArrays/DataView) are structured-clone-
+    // safe and should pass through unchanged. This is important for transferring
+    // kernel bytes (e.g. Uint8Array) into a worker.
+    if (value instanceof ArrayBuffer)
+        return value;
+    if (ArrayBuffer.isView(value))
+        return value;
+    // SharedArrayBuffer exists in some environments (Node, some browsers) but is
+    // gated by cross-origin isolation in browsers. Allow it when present.
+    if (typeof SharedArrayBuffer !== "undefined" &&
+        value instanceof SharedArrayBuffer) {
+        return value;
+    }
+    if (isRecord(value)) {
+        // Allow byte buffers/typed arrays to cross the worker boundary.
+        // These are structured-clone-safe and commonly used for kernel outputs.
+        if (value instanceof ArrayBuffer)
+            return value;
+        if (ArrayBuffer.isView(value))
+            return value;
+        if (typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer) {
+            return value;
+        }
+        // Preserve Date/Map/Set/etc as-is? No: those are not guaranteed to be
+        // structured-clone-safe across all targets. For now, we only support plain
+        // object literals.
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            const ctorName = value.constructor?.name ??
+                proto.constructor?.name;
+            throw new Error("encodeRpcValue(): unsupported non-plain object for worker RPC " +
+                `(constructor=${String(ctorName)}). ` +
+                "Pass plain objects/arrays/primitives or extend the codec.");
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = encodeRpcValue(v);
+        }
+        return out;
+    }
+    return value;
+}
+/** Decode a value that was encoded by {@link encodeRpcValue}. */
+export function decodeRpcValue(value) {
+    if (isTaggedRecord(value)) {
+        const tag = value[tspiceRpcTagKey];
+        if (tag === "Mat3") {
+            const layout = value.layout;
+            const data = value.data;
+            if (layout === "rowMajor" && isMat3RowMajorData(data)) {
+                // Mat3.fromRowMajor expects a branded Mat3RowMajor type. We validated
+                // the runtime shape here, so the cast is safe.
+                return Mat3.fromRowMajor(data);
+            }
+        }
+    }
+    if (Array.isArray(value)) {
+        return value.map(decodeRpcValue);
+    }
+    if (isRecord(value)) {
+        // Preserve non-plain objects (e.g. TypedArrays) as-is.
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null)
+            return value;
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = decodeRpcValue(v);
+        }
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=valueCodec.js.map

package/dist/transport/types.d.ts

@@ -0,0 +1,7 @@
+export type SpiceTransport = {
+    request(op: string, args: unknown[]): Promise<unknown>;
+};
+export type SpiceTransportSync = {
+    request(op: string, args: unknown[]): unknown;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/transport/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.d.ts

@@ -9,25 +9,16 @@ export type Vec6 = readonly [
     number,
     number
 ];
-/** 3x3 matrix, row-major. */
-export type Mat3 = readonly [
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number
-];
 /** SPICE frame name (e.g. "J2000", "IAU_EARTH"). */
 export type FrameName = string;
+/** Canonical inertial reference frame. */
+export declare const J2000: "J2000";
 /** Aberration correction string accepted by `spkezr`. */
 export type AberrationCorrection = "NONE" | "LT" | "LT+S" | "CN" | "CN+S" | "XLT" | "XLT+S" | "XCN" | "XCN+S";
-export type SpiceTime = number & {
-    readonly __tspiceBrand: "SpiceTime";
-};
+/** Seconds past J2000 (ET). */
+export type SpiceTime = number;
+/** Body identifier accepted by kit APIs (name or NAIF id). */
+export type BodyRef = string | number;
 export type StateVector = {
     /** Seconds past J2000 (ET). */
     et: SpiceTime;
@@ -45,8 +36,8 @@ export type StateVector = {
     lightTime: number;
 };
 export type GetStateArgs = {
-    target: string;
-    observer: string;
+    target: BodyRef;
+    observer: BodyRef;
     at: SpiceTime;
     frame?: FrameName;
     aberration?: AberrationCorrection;

package/dist/types.js

@@ -1,2 +1,3 @@
-export {};
+/** Canonical inertial reference frame. */
+export const J2000 = "J2000";
 //# sourceMappingURL=types.js.map

package/dist/worker/browser/createSpiceWorker.d.ts

@@ -0,0 +1,22 @@
+import type { WorkerLike } from "../transport/createWorkerTransport.js";
+export type CreateSpiceWorkerOptions = {
+    /** Override the worker entrypoint (advanced). */
+    url?: string | URL;
+    /**
+     * Override the WASM binary URL used by the default inline worker.
+     *
+     * When omitted, `createSpiceWorker()` will resolve the WASM binary URL
+     * relative to the published package layout.
+     */
+    wasmUrl?: string | URL;
+    /**
+     * Options passed through to the `Worker` constructor.
+     *
+     * Typed loosely on purpose so this package doesn't require `lib.dom` types
+     * (and so it can be consumed in non-DOM TS configs).
+     */
+    workerOptions?: Record<string, unknown>;
+};
+/** Create a Web Worker instance for the tspice worker entrypoint (inline by default). */
+export declare function createSpiceWorker(opts?: CreateSpiceWorkerOptions): WorkerLike;
+//# sourceMappingURL=createSpiceWorker.d.ts.map

package/dist/worker/browser/createSpiceWorker.js

@@ -0,0 +1,41 @@
+import { SPICE_WORKER_INLINE_SOURCE } from "./spiceWorkerInlineSource.js";
+/** Create a Web Worker instance for the tspice worker entrypoint (inline by default). */
+export function createSpiceWorker(opts = {}) {
+    const WorkerCtor = globalThis.Worker;
+    if (typeof WorkerCtor !== "function") {
+        throw new Error("createSpiceWorker() requires Web Worker support in the current runtime");
+    }
+    // Default to module workers since this package is ESM and relies on
+    // ESM-only dependencies.
+    const workerOptions = {
+        type: "module",
+        ...(opts.workerOptions ?? {}),
+    };
+    if (opts.url != null) {
+        return new WorkerCtor(opts.url, workerOptions);
+    }
+    // Inline (blob) worker by default.
+    //
+    // This avoids requiring consumers to separately bundle/host a worker JS asset
+    // URL. It also means the worker entry cannot use `import.meta.url` to locate
+    // assets, since the entrypoint URL will be `blob:`.
+    if (workerOptions.type !== "module") {
+        throw new Error('createSpiceWorker() inline worker requires a module worker (workerOptions.type="module")');
+    }
+    const wasmUrl = opts.wasmUrl?.toString() ??
+        // Published package layout (and what `build:dist-publish` produces):
+        //   dist/worker/browser/createSpiceWorker.js
+        //   backend-wasm/dist/tspice_backend_wasm.wasm
+        new URL("../../../backend-wasm/dist/tspice_backend_wasm.wasm", import.meta.url).href;
+    const workerSource = `globalThis.__TSPICE_WORKER_CONFIG__ = ${JSON.stringify({ wasmUrl })};\n` +
+        SPICE_WORKER_INLINE_SOURCE;
+    const blob = new Blob([workerSource], { type: "text/javascript" });
+    const blobUrl = URL.createObjectURL(blob);
+    try {
+        return new WorkerCtor(blobUrl, workerOptions);
+    }
+    finally {
+        URL.revokeObjectURL(blobUrl);
+    }
+}
+//# sourceMappingURL=createSpiceWorker.js.map

package/dist/worker/browser/createSpiceWorkerClient.d.ts

@@ -0,0 +1,40 @@
+import type { SpiceAsync } from "../../kit/types/spice-types.js";
+import type { SpiceTransport } from "../../transport/types.js";
+import { type WorkerLike, type WorkerTransport } from "../transport/createWorkerTransport.js";
+export type SpiceWorkerClient<TTransport extends SpiceTransport = WorkerTransport> = {
+    worker: WorkerLike;
+    /** The underlying request/response RPC transport (always a WorkerTransport). */
+    baseTransport: WorkerTransport;
+    /** The transport after applying `wrapTransport` (e.g. `withCaching`). */
+    transport: TTransport;
+    /** A `SpiceAsync` client backed by `transport`. */
+    spice: SpiceAsync;
+    /** Dispose wrapper transport (if any) and the worker transport. */
+    dispose: () => void;
+    /**
+     * Async dispose variant that awaits wrapper transport cleanup (if any) before
+     * disposing the underlying worker transport.
+     */
+    disposeAsync: () => Promise<void>;
+};
+export type CreateSpiceWorkerClientOptions<TTransport extends SpiceTransport = WorkerTransport> = {
+    /**
+     * Pass an existing Worker or a factory to create one.
+     *
+     * Defaults to `() => createSpiceWorker()`.
+     */
+    worker?: WorkerLike | (() => WorkerLike);
+    /** Default request timeout forwarded to `createWorkerTransport`. */
+    timeoutMs?: number;
+    /** Forwarded to `createWorkerTransport`. Defaults to `true` when `worker` is a factory. */
+    terminateOnDispose?: boolean;
+    /** Forwarded to `createWorkerTransport`. Defaults to `terminateOnDispose`. */
+    signalDispose?: boolean;
+    /** Optional transport wrapper (e.g. `withCaching`). */
+    wrapTransport?: (t: WorkerTransport) => TTransport;
+    /** Called if `disposeAsync()` rejects when invoked via fire-and-forget `dispose()`. */
+    onDisposeError?: (err: unknown) => void;
+};
+/** Create a {@link SpiceWorkerClient} that communicates with a tspice Web Worker via RPC. */
+export declare function createSpiceWorkerClient<TTransport extends SpiceTransport = WorkerTransport>(opts?: CreateSpiceWorkerClientOptions<TTransport>): SpiceWorkerClient<TTransport>;
+//# sourceMappingURL=createSpiceWorkerClient.d.ts.map

package/dist/worker/browser/createSpiceWorkerClient.js

@@ -0,0 +1,99 @@
+import { createSpiceAsyncFromTransport } from "../../clients/createSpiceAsyncFromTransport.js";
+import { createWorkerTransport, } from "../transport/createWorkerTransport.js";
+import { createSpiceWorker } from "./createSpiceWorker.js";
+function getDisposeFn(value) {
+    if (value === null)
+        return undefined;
+    const t = typeof value;
+    if (t !== "object" && t !== "function")
+        return undefined;
+    const dispose = value.dispose;
+    return typeof dispose === "function" ? dispose : undefined;
+}
+function isPromiseLike(value) {
+    if (value === null)
+        return false;
+    const t = typeof value;
+    if (t !== "object" && t !== "function")
+        return false;
+    return typeof value.then === "function";
+}
+/** Create a {@link SpiceWorkerClient} that communicates with a tspice Web Worker via RPC. */
+export function createSpiceWorkerClient(opts) {
+    const workerInput = opts?.worker ?? (() => createSpiceWorker());
+    const worker = typeof workerInput === "function" ? workerInput() : workerInput;
+    const terminateOnDispose = opts?.terminateOnDispose ??
+        (typeof workerInput === "function" ? true : false);
+    const baseTransport = createWorkerTransport({
+        worker,
+        ...(opts?.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+        terminateOnDispose,
+        ...(opts?.signalDispose === undefined
+            ? {}
+            : { signalDispose: opts.signalDispose }),
+    });
+    const transport = opts?.wrapTransport
+        ? opts.wrapTransport(baseTransport)
+        : baseTransport;
+    const spice = createSpiceAsyncFromTransport(transport);
+    let disposePromise;
+    const disposeAsync = () => {
+        if (disposePromise)
+            return disposePromise;
+        disposePromise = (async () => {
+            try {
+                // If a wrapper transport supports cleanup, run it before disposing the
+                // underlying worker transport.
+                if (transport !== baseTransport) {
+                    const wrapperDispose = getDisposeFn(transport);
+                    if (wrapperDispose) {
+                        const result = wrapperDispose.call(transport);
+                        if (isPromiseLike(result))
+                            await result;
+                    }
+                }
+            }
+            finally {
+                baseTransport.dispose();
+            }
+        })();
+        return disposePromise;
+    };
+    const dispose = () => {
+        // Fire-and-forget. Ensure we don't surface unhandled rejections if wrapper
+        // cleanup fails.
+        void disposeAsync().catch((err) => {
+            try {
+                opts?.onDisposeError?.(err);
+            }
+            catch (callbackErr) {
+                if (typeof console !== "undefined" &&
+                    typeof console.error === "function") {
+                    // Log both: the original disposal failure and the error thrown by the
+                    // error callback.
+                    try {
+                        console.error("createSpiceWorkerClient.dispose(): disposeAsync() failed", err);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    try {
+                        console.error("createSpiceWorkerClient.dispose(): onDisposeError threw", callbackErr);
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+        });
+    };
+    return {
+        worker,
+        baseTransport,
+        transport,
+        spice,
+        dispose,
+        disposeAsync,
+    };
+}
+//# sourceMappingURL=createSpiceWorkerClient.js.map

package/dist/worker/browser/spiceWorkerEntry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spiceWorkerEntry.d.ts.map

package/dist/worker/browser/spiceWorkerEntry.js

@@ -0,0 +1,129 @@
+import { createSpiceAsync } from "../../spice.js";
+import { exposeTransportToWorker } from "../transport/exposeTransportToWorker.js";
+const getWorkerConfig = () => {
+    const cfg = globalThis
+        .__TSPICE_WORKER_CONFIG__;
+    if (!cfg || typeof cfg !== "object")
+        return undefined;
+    return cfg;
+};
+const blockedStringKeys = new Set([
+    // Promise / thenable
+    "then",
+    // Prototype / constructor escapes
+    "__proto__",
+    "prototype",
+    "constructor",
+    // Common stringification / inspection hooks
+    "toJSON",
+    "inspect",
+    // Object.prototype keys (avoid accidental RPC calls during introspection)
+    "toString",
+    "valueOf",
+    "toLocaleString",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+    "__defineGetter__",
+    "__defineSetter__",
+    "__lookupGetter__",
+    "__lookupSetter__",
+]);
+const isSafeRpcKey = (key) => /^[A-Za-z_$][\w$]*$/.test(key);
+const allowedKitMethodList = [
+    "loadKernel",
+    "unloadKernel",
+    "kclear",
+    "toolkitVersion",
+    "utcToEt",
+    "etToUtc",
+    "frameTransform",
+    "getState",
+];
+const defaultAllowlist = {
+    // NOTE: `kit` is deliberately allowlisted because it's a small, curated API.
+    // `raw` is intentionally not allowlisted here (see module comment below).
+    kit: new Set(allowedKitMethodList),
+};
+function createSpiceTransportFromSpiceAsync(spice, opts) {
+    const allowlist = opts?.allowlist ?? defaultAllowlist;
+    return {
+        request: async (op, args) => {
+            const dot = op.indexOf(".");
+            if (dot <= 0 || dot === op.length - 1) {
+                throw new Error(`Invalid op: ${op}`);
+            }
+            const namespace = op.slice(0, dot);
+            const method = op.slice(dot + 1);
+            if (namespace !== "raw" && namespace !== "kit") {
+                throw new Error(`Unknown namespace: ${namespace}`);
+            }
+            if (!isSafeRpcKey(method) || blockedStringKeys.has(method)) {
+                throw new Error(`Invalid method name: ${method}`);
+            }
+            const ns = namespace;
+            const nsAllowlist = allowlist[ns];
+            if (nsAllowlist && !nsAllowlist.has(method)) {
+                throw new Error(`Disallowed op: ${op}`);
+            }
+            const target = spice[ns];
+            const fn = target[method];
+            if (typeof fn !== "function") {
+                throw new Error(`Unknown op: ${op}`);
+            }
+            // `spice.raw` and `spice.kit` are proxies that return bound/wrapped
+            // functions, but use Reflect.apply to be defensive about `this`.
+            return await Reflect.apply(fn, target, args);
+        },
+    };
+}
+// NOTE: This file is meant to be loaded as a Web Worker module.
+// It intentionally has no exports and runs as a side-effect.
+//
+// Security/design note:
+// - This worker entry is intended for internal workspace use.
+// - By default, it exposes:
+//   - `kit.*` as a small, curated allowlist (see `allowedKitMethodList`), and
+//   - `raw.*` without an allowlist (subject to the blocked key checks above).
+// - If you need a tighter RPC capability set (especially for `raw.*`), create
+//   a custom worker entry and provide an explicit allowlist.
+//
+// IMPORTANT: `exposeTransportToWorker()` must run synchronously so the worker's
+// `message` handler is installed immediately. Otherwise, early RPC messages from
+// the main thread can be dropped while the WASM backend is still initializing.
+let spicePromise;
+let transportPromise;
+const getSpicePromise = () => {
+    if (spicePromise)
+        return spicePromise;
+    const config = getWorkerConfig();
+    const wasmUrl = config?.wasmUrl;
+    spicePromise = createSpiceAsync({
+        backend: "wasm",
+        ...(wasmUrl === undefined ? {} : { wasmUrl }),
+    });
+    return spicePromise;
+};
+const getTransportPromise = () => (transportPromise ??= getSpicePromise().then((spice) => createSpiceTransportFromSpiceAsync(spice)));
+exposeTransportToWorker({
+    transport: {
+        request: async (op, args) => (await getTransportPromise()).request(op, args),
+    },
+    onDispose: async () => {
+        // Best-effort cleanup. Worker termination also releases resources, but this
+        // helps callers who keep the worker alive.
+        if (!spicePromise) {
+            return;
+        }
+        try {
+            const spice = await getSpicePromise();
+            await spice.raw.kclear();
+        }
+        catch {
+            // ignore
+        }
+    },
+});
+// Kick off init after the `message` handler has been installed.
+void getTransportPromise();
+//# sourceMappingURL=spiceWorkerEntry.js.map

package/dist/worker/browser/spiceWorkerInlineSource.d.ts

@@ -0,0 +1,2 @@
+export declare const SPICE_WORKER_INLINE_SOURCE: string;
+//# sourceMappingURL=spiceWorkerInlineSource.d.ts.map