@necpp-engine/wasm 0.1.0

package/dist/worker-client.d.ts

@@ -0,0 +1,11 @@
+import type { CreateNecWorkerModelOptions, NecWorkerModel } from "./types.js";
+export interface WorkerHost {
+    postMessage(data: unknown, transfer?: readonly ArrayBuffer[]): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    subscribeError(listener: (error: unknown) => void): () => void;
+    subscribeExit?(listener: (code: number) => void): () => void;
+    terminate(): void;
+}
+export declare function createNecWorkerModelFromHost(host: WorkerHost, options?: CreateNecWorkerModelOptions): Promise<NecWorkerModel>;
+/** Create a stateful NEC model that runs inside a dedicated worker. */
+export declare function createNecWorkerModel(options?: CreateNecWorkerModelOptions): Promise<NecWorkerModel>;

package/dist/worker-client.js

@@ -0,0 +1,325 @@
+import { NecInputError, NecRuntimeError, NecStateError } from "./errors.js";
+import { cloneFloat64, isNodeRuntime, isWorkerResponse, reviveEmbeddedFarFieldResult, reviveError, reviveFarFieldResult, reviveImpedanceResult, revivePortSolution, serializeCreateOptions, } from "./worker-protocol.js";
+function createWebWorker() {
+    return new Worker(new URL("./worker-entry.js", import.meta.url), {
+        type: "module",
+    });
+}
+async function openWorkerHost() {
+    if (isNodeRuntime()) {
+        const { Worker: NodeWorker } = await import("node:worker_threads");
+        const worker = new NodeWorker(new URL("./worker-entry.js", import.meta.url));
+        return {
+            postMessage(data, transfer = []) {
+                worker.postMessage(data, transfer);
+            },
+            subscribe(listener) {
+                const handler = (value) => {
+                    listener(value);
+                };
+                worker.on("message", handler);
+                return () => {
+                    worker.off("message", handler);
+                };
+            },
+            subscribeError(listener) {
+                const handler = (error) => {
+                    listener(error);
+                };
+                worker.on("error", handler);
+                return () => {
+                    worker.off("error", handler);
+                };
+            },
+            subscribeExit(listener) {
+                const handler = (code) => {
+                    listener(code);
+                };
+                worker.on("exit", handler);
+                return () => {
+                    worker.off("exit", handler);
+                };
+            },
+            terminate() {
+                void worker.terminate();
+            },
+        };
+    }
+    const worker = createWebWorker();
+    return {
+        postMessage(data, transfer = []) {
+            worker.postMessage(data, transfer);
+        },
+        subscribe(listener) {
+            const handler = (event) => {
+                listener(event.data);
+            };
+            worker.addEventListener("message", handler);
+            return () => {
+                worker.removeEventListener("message", handler);
+            };
+        },
+        subscribeError(listener) {
+            const errorHandler = (event) => {
+                listener(event.error ?? event.message);
+            };
+            const messageErrorHandler = () => {
+                listener(new Error("The NEC worker could not deserialize a message"));
+            };
+            worker.addEventListener("error", errorHandler);
+            worker.addEventListener("messageerror", messageErrorHandler);
+            return () => {
+                worker.removeEventListener("error", errorHandler);
+                worker.removeEventListener("messageerror", messageErrorHandler);
+            };
+        },
+        terminate() {
+            worker.terminate();
+        },
+    };
+}
+function cloneComplexVector(vector) {
+    const real = cloneFloat64(vector.real);
+    const imag = cloneFloat64(vector.imag);
+    return {
+        vector: { real, imag },
+        transfer: [real.buffer, imag.buffer],
+    };
+}
+class WorkerNecModel {
+    #host;
+    #state = "empty";
+    #terminated = false;
+    #nextId = 1;
+    #tail = Promise.resolve();
+    #pending = new Map();
+    #listeners = new Set();
+    #unsubscribeMessage;
+    #unsubscribeError;
+    #unsubscribeExit;
+    constructor(host, onProgress) {
+        this.#host = host;
+        if (onProgress !== undefined) {
+            this.#listeners.add(onProgress);
+        }
+        this.#unsubscribeMessage = host.subscribe((data) => {
+            this.#onMessage(data);
+        });
+        this.#unsubscribeError = host.subscribeError((error) => {
+            this.#failAll(new NecRuntimeError("The NEC worker failed", { cause: error }));
+        });
+        this.#unsubscribeExit = host.subscribeExit?.((code) => {
+            if (!this.#terminated) {
+                this.#failAll(new NecRuntimeError(`The NEC worker exited unexpectedly with code ${code}`, { details: { exitCode: code } }));
+            }
+        }) ?? (() => undefined);
+    }
+    get state() {
+        return this.#state;
+    }
+    subscribeProgress(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    async initialize(options) {
+        const serialized = serializeCreateOptions(options);
+        await this.#request(serialized.payload === undefined
+            ? { kind: "create" }
+            : { kind: "create", options: serialized.payload }, serialized.transfer);
+    }
+    addWire(wire) {
+        return this.#invokeVoid("addWire", [wire]);
+    }
+    completeGeometry(options) {
+        return this.#invokeVoid("completeGeometry", options === undefined ? [] : [options]);
+    }
+    definePorts(ports) {
+        return this.#invokeVoid("definePorts", [ports]);
+    }
+    addLoad(load) {
+        return this.#invokeVoid("addLoad", [load]);
+    }
+    clearLoads() {
+        return this.#invokeVoid("clearLoads", []);
+    }
+    setGround(ground) {
+        return this.#invokeVoid("setGround", [ground]);
+    }
+    prepare(options) {
+        return this.#invokeVoid("prepare", [options]);
+    }
+    async computeImpedanceMatrix() {
+        return reviveImpedanceResult(await this.#invoke("computeImpedanceMatrix", []));
+    }
+    async solveVoltages(voltages) {
+        const cloned = cloneComplexVector(voltages);
+        return revivePortSolution(await this.#invoke("solveVoltages", [cloned.vector], cloned.transfer));
+    }
+    async solveCurrents(currents) {
+        const cloned = cloneComplexVector(currents);
+        return revivePortSolution(await this.#invoke("solveCurrents", [cloned.vector], cloned.transfer));
+    }
+    async computeFarField(request) {
+        return reviveFarFieldResult(await this.#invoke("computeFarField", [request]));
+    }
+    async computeEmbeddedFarFields(request, normalization) {
+        const args = normalization === undefined ? [request] : [request, normalization];
+        return reviveEmbeddedFarFieldResult(await this.#invoke("computeEmbeddedFarFields", args));
+    }
+    async dispose() {
+        if (this.#terminated || this.#state === "disposed") {
+            this.#state = "disposed";
+            this.terminate();
+            return;
+        }
+        try {
+            await this.#invoke("dispose", []);
+        }
+        finally {
+            this.terminate();
+        }
+    }
+    terminate() {
+        if (this.#terminated) {
+            return;
+        }
+        this.#terminated = true;
+        this.#state = "disposed";
+        this.#unsubscribeMessage();
+        this.#unsubscribeError();
+        this.#unsubscribeExit();
+        const error = new NecRuntimeError("The NEC worker was terminated");
+        for (const pending of this.#pending.values()) {
+            pending.reject(error);
+        }
+        this.#pending.clear();
+        try {
+            this.#host.terminate();
+        }
+        catch {
+            // Termination is best-effort once outstanding work has been rejected.
+        }
+    }
+    #notify(listenerEvent) {
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(listenerEvent);
+            }
+            catch {
+                // Progress listeners must not break the worker client.
+            }
+        }
+    }
+    #failAll(error) {
+        if (this.#terminated) {
+            return;
+        }
+        this.#terminated = true;
+        this.#state = "disposed";
+        this.#unsubscribeMessage();
+        this.#unsubscribeError();
+        this.#unsubscribeExit();
+        for (const pending of this.#pending.values()) {
+            pending.reject(error);
+        }
+        this.#pending.clear();
+        try {
+            this.#host.terminate();
+        }
+        catch {
+            // The host is already failing.
+        }
+    }
+    #onMessage(data) {
+        if (!isWorkerResponse(data)) {
+            this.#failAll(new NecRuntimeError("The NEC worker returned a malformed message"));
+            return;
+        }
+        if (data.kind === "progress") {
+            this.#notify(data);
+            return;
+        }
+        if (data.kind === "crash") {
+            this.#failAll(new NecRuntimeError(data.error.message, data.error.details === undefined ? {} : { details: data.error.details }));
+            return;
+        }
+        const pending = this.#pending.get(data.id);
+        if (pending === undefined) {
+            return;
+        }
+        this.#pending.delete(data.id);
+        if (data.state !== undefined) {
+            this.#state = data.state;
+        }
+        if (data.kind === "ok") {
+            pending.resolve(data.result);
+            return;
+        }
+        pending.reject(reviveError(data.error));
+    }
+    #assertCallable(method) {
+        if (this.#terminated || this.#state === "disposed") {
+            if (method === "dispose") {
+                return;
+            }
+            throw new NecStateError(method, "disposed");
+        }
+    }
+    #request(body, transfer = []) {
+        this.#assertCallable(body.kind === "create" ? "create" : body.method);
+        const run = this.#tail.then(() => {
+            if (this.#terminated) {
+                throw new NecRuntimeError("The NEC worker was terminated");
+            }
+            return new Promise((resolve, reject) => {
+                const id = this.#nextId;
+                this.#nextId += 1;
+                this.#pending.set(id, { resolve, reject });
+                try {
+                    this.#host.postMessage({ ...body, id }, transfer);
+                }
+                catch (cause) {
+                    this.#pending.delete(id);
+                    reject(new NecRuntimeError("Failed to post a NEC worker request", {
+                        cause,
+                    }));
+                }
+            });
+        });
+        this.#tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    #invokeVoid(method, args, transfer = []) {
+        return this.#invoke(method, args, transfer).then(() => undefined);
+    }
+    async #invoke(method, args, transfer = []) {
+        if (method !== "dispose") {
+            this.#assertCallable(method);
+        }
+        else if (this.#terminated || this.#state === "disposed") {
+            return undefined;
+        }
+        return this.#request({ kind: "invoke", method, args }, transfer);
+    }
+}
+export async function createNecWorkerModelFromHost(host, options) {
+    const model = new WorkerNecModel(host, options?.onProgress);
+    try {
+        await model.initialize(options);
+        return model;
+    }
+    catch (error) {
+        model.terminate();
+        throw error;
+    }
+}
+/** Create a stateful NEC model that runs inside a dedicated worker. */
+export async function createNecWorkerModel(options) {
+    if (options !== undefined && (typeof options !== "object" || options === null)) {
+        throw new NecInputError("WASM loading options must be an object");
+    }
+    const host = await openWorkerHost();
+    return createNecWorkerModelFromHost(host, options);
+}

package/dist/worker-entry.d.ts

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

package/dist/worker-entry.js

@@ -0,0 +1,93 @@
+import { createNecModel } from "./index.js";
+import { NecRuntimeError } from "./errors.js";
+import { isNodeRuntime, isWorkerResponse, serializeError, } from "./worker-protocol.js";
+import { handleWorkerRequest } from "./worker-runtime.js";
+async function connectParent() {
+    if (typeof document !== "undefined") {
+        throw new NecRuntimeError("NEC worker entry must run inside a worker");
+    }
+    if (isNodeRuntime()) {
+        const { parentPort } = await import("node:worker_threads");
+        if (parentPort === null) {
+            throw new NecRuntimeError("NEC worker entry must run inside a worker");
+        }
+        return {
+            postMessage(value, transfer = []) {
+                parentPort.postMessage(value, transfer);
+            },
+            onMessage(listener) {
+                parentPort.on("message", listener);
+            },
+        };
+    }
+    const scope = globalThis;
+    if (typeof scope.postMessage !== "function") {
+        throw new NecRuntimeError("NEC worker entry must run inside a worker");
+    }
+    return {
+        postMessage(value, transfer = []) {
+            scope.postMessage(value, transfer);
+        },
+        onMessage(listener) {
+            scope.addEventListener("message", (event) => {
+                listener(event.data);
+            });
+        },
+    };
+}
+function isWorkerRequest(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return typeof record.id === "number"
+        && (record.kind === "create" || record.kind === "invoke");
+}
+void startWorker();
+async function startWorker() {
+    const parent = await connectParent();
+    const session = { model: undefined };
+    let queue = Promise.resolve();
+    function post(response, transfer = []) {
+        parent.postMessage(response, transfer);
+    }
+    parent.onMessage((value) => {
+        queue = queue.then(async () => {
+            if (!isWorkerRequest(value)) {
+                post({
+                    kind: "crash",
+                    error: serializeError(new NecRuntimeError("The NEC worker received a malformed request")),
+                });
+                return;
+            }
+            try {
+                const { response, transfer } = await handleWorkerRequest(session, value, {
+                    createModel: createNecModel,
+                    emitProgress(event) {
+                        post({
+                            kind: "progress",
+                            operation: event.operation,
+                            phase: event.phase,
+                        });
+                    },
+                });
+                if (!isWorkerResponse(response)) {
+                    post({
+                        id: value.id,
+                        kind: "error",
+                        error: serializeError(new NecRuntimeError("The NEC worker produced an invalid response")),
+                    });
+                    return;
+                }
+                post(response, transfer);
+            }
+            catch (error) {
+                post({
+                    id: value.id,
+                    kind: "error",
+                    error: serializeError(error),
+                });
+            }
+        }, () => undefined);
+    });
+}

package/dist/worker-protocol.d.ts

@@ -0,0 +1,62 @@
+import { NecError, type NecErrorCode } from "./errors.js";
+import type { CreateNecModelOptions, CreateNecWorkerModelOptions, EmbeddedFarFieldResult, FarFieldResult, ImpedanceResult, NecModelState, NecWorkerOperation, PortDefinition, PortSolution } from "./types.js";
+export declare function isNodeRuntime(): boolean;
+export type WorkerMethod = Exclude<NecWorkerOperation, "create">;
+export interface SerializedCreateOptions {
+    readonly wasmUrl?: string;
+    readonly wasmBinary?: ArrayBuffer;
+}
+export type WorkerRequest = {
+    readonly id: number;
+    readonly kind: "create";
+    readonly options?: SerializedCreateOptions;
+} | {
+    readonly id: number;
+    readonly kind: "invoke";
+    readonly method: WorkerMethod;
+    readonly args: readonly unknown[];
+};
+export interface SerializedNecError {
+    readonly name: string;
+    readonly code: NecErrorCode;
+    readonly message: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly operation?: string;
+    readonly state?: NecModelState;
+}
+export type WorkerProgressMessage = {
+    readonly kind: "progress";
+    readonly operation: NecWorkerOperation;
+    readonly phase: "start" | "complete";
+};
+export type WorkerResponse = {
+    readonly id: number;
+    readonly kind: "ok";
+    readonly state: NecModelState;
+    readonly result?: unknown;
+    readonly transferredBufferCount: number;
+} | {
+    readonly id: number;
+    readonly kind: "error";
+    readonly state?: NecModelState;
+    readonly error: SerializedNecError;
+} | {
+    readonly kind: "crash";
+    readonly error: SerializedNecError;
+} | WorkerProgressMessage;
+export declare function isWorkerResponse(value: unknown): value is WorkerResponse;
+/** Collect unique, non-empty ArrayBuffers owned by a structured-cloneable result. */
+export declare function collectTransferables(value: unknown): ArrayBuffer[];
+export declare function serializeError(error: unknown): SerializedNecError;
+export declare function reviveError(serialized: SerializedNecError): NecError;
+export declare function snapshotPorts(ports: readonly PortDefinition[]): readonly PortDefinition[];
+export declare function revivePortSolution(value: unknown): PortSolution;
+export declare function reviveImpedanceResult(value: unknown): ImpedanceResult;
+export declare function reviveFarFieldResult(value: unknown): FarFieldResult;
+export declare function reviveEmbeddedFarFieldResult(value: unknown): EmbeddedFarFieldResult;
+export declare function cloneFloat64(source: Float64Array): Float64Array<ArrayBuffer>;
+export declare function serializeCreateOptions(options: CreateNecWorkerModelOptions | undefined): {
+    readonly payload?: SerializedCreateOptions;
+    readonly transfer: ArrayBuffer[];
+};
+export declare function toCreateNecModelOptions(options: SerializedCreateOptions | undefined): CreateNecModelOptions | undefined;