@necpp-engine/wasm 0.1.0

package/dist/worker-protocol.js

@@ -0,0 +1,257 @@
+import { NecConditioningError, NecError, NecGeometryError, NecInputError, NecPortError, NecRuntimeError, NecSolverError, NecStateError, } from "./errors.js";
+export function isNodeRuntime() {
+    const runtime = globalThis;
+    return typeof runtime.process === "object"
+        && runtime.process !== null
+        && typeof runtime.process.versions === "object"
+        && runtime.process.versions !== null
+        && typeof runtime.process.versions.node === "string"
+        && typeof runtime.window === "undefined";
+}
+export function isWorkerResponse(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const kind = value.kind;
+    return kind === "ok"
+        || kind === "error"
+        || kind === "crash"
+        || kind === "progress";
+}
+function isArrayBuffer(value) {
+    return Object.prototype.toString.call(value) === "[object ArrayBuffer]";
+}
+function visitTransferables(value, buffers) {
+    if (value === null || value === undefined) {
+        return;
+    }
+    if (isArrayBuffer(value)) {
+        if (value.byteLength > 0) {
+            buffers.add(value);
+        }
+        return;
+    }
+    if (ArrayBuffer.isView(value)) {
+        const buffer = value.buffer;
+        if (isArrayBuffer(buffer) && buffer.byteLength > 0) {
+            buffers.add(buffer);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            visitTransferables(item, buffers);
+        }
+        return;
+    }
+    if (typeof value === "object") {
+        for (const item of Object.values(value)) {
+            visitTransferables(item, buffers);
+        }
+    }
+}
+/** Collect unique, non-empty ArrayBuffers owned by a structured-cloneable result. */
+export function collectTransferables(value) {
+    const buffers = new Set();
+    visitTransferables(value, buffers);
+    return [...buffers];
+}
+function errorOptions(details) {
+    return details === undefined ? {} : { details };
+}
+export function serializeError(error) {
+    if (error instanceof NecStateError) {
+        const serialized = {
+            name: error.name,
+            code: error.code,
+            message: error.message,
+            operation: error.operation,
+            state: error.state,
+        };
+        return error.details === undefined
+            ? serialized
+            : { ...serialized, details: error.details };
+    }
+    if (error instanceof NecError) {
+        const serialized = {
+            name: error.name,
+            code: error.code,
+            message: error.message,
+        };
+        return error.details === undefined
+            ? serialized
+            : { ...serialized, details: error.details };
+    }
+    if (error instanceof Error) {
+        return {
+            name: "NecRuntimeError",
+            code: "NEC_RUNTIME",
+            message: error.message,
+        };
+    }
+    return {
+        name: "NecRuntimeError",
+        code: "NEC_RUNTIME",
+        message: String(error),
+    };
+}
+export function reviveError(serialized) {
+    switch (serialized.code) {
+        case "NEC_STATE":
+            return new NecStateError(serialized.operation ?? "unknown", serialized.state ?? "disposed", serialized.message);
+        case "NEC_INPUT":
+            return new NecInputError(serialized.message, errorOptions(serialized.details));
+        case "NEC_GEOMETRY":
+            return new NecGeometryError(serialized.message, errorOptions(serialized.details));
+        case "NEC_PORT":
+            return new NecPortError(serialized.message, errorOptions(serialized.details));
+        case "NEC_CONDITIONING":
+            return new NecConditioningError(serialized.message, errorOptions(serialized.details));
+        case "NEC_SOLVER":
+            return new NecSolverError(serialized.message, errorOptions(serialized.details));
+        default:
+            return new NecRuntimeError(serialized.message, errorOptions(serialized.details));
+    }
+}
+export function snapshotPorts(ports) {
+    return Object.freeze(ports.map((port) => Object.freeze(port.name === undefined
+        ? { tag: port.tag, segment: port.segment }
+        : { tag: port.tag, segment: port.segment, name: port.name })));
+}
+function copyFloat64(value, name) {
+    if (Object.prototype.toString.call(value) !== "[object Float64Array]") {
+        throw new NecRuntimeError(`Worker result ${name} is not a Float64Array`);
+    }
+    return value;
+}
+export function revivePortSolution(value) {
+    const record = value;
+    return {
+        drive: record.drive,
+        frequencyMHz: record.frequencyMHz,
+        ports: snapshotPorts(record.ports),
+        requested: {
+            real: copyFloat64(record.requested.real, "requested.real"),
+            imag: copyFloat64(record.requested.imag, "requested.imag"),
+        },
+        voltages: {
+            real: copyFloat64(record.voltages.real, "voltages.real"),
+            imag: copyFloat64(record.voltages.imag, "voltages.imag"),
+        },
+        currents: {
+            real: copyFloat64(record.currents.real, "currents.real"),
+            imag: copyFloat64(record.currents.imag, "currents.imag"),
+        },
+        activeImpedances: {
+            real: copyFloat64(record.activeImpedances.real, "activeImpedances.real"),
+            imag: copyFloat64(record.activeImpedances.imag, "activeImpedances.imag"),
+        },
+        powersW: copyFloat64(record.powersW, "powersW"),
+        factorizationGeneration: record.factorizationGeneration,
+        solveGeneration: record.solveGeneration,
+    };
+}
+export function reviveImpedanceResult(value) {
+    const record = value;
+    const result = {
+        impedance: {
+            rows: record.impedance.rows,
+            columns: record.impedance.columns,
+            order: "row-major",
+            real: copyFloat64(record.impedance.real, "impedance.real"),
+            imag: copyFloat64(record.impedance.imag, "impedance.imag"),
+        },
+        admittance: {
+            rows: record.admittance.rows,
+            columns: record.admittance.columns,
+            order: "row-major",
+            real: copyFloat64(record.admittance.real, "admittance.real"),
+            imag: copyFloat64(record.admittance.imag, "admittance.imag"),
+        },
+        frequencyMHz: record.frequencyMHz,
+        factorizationGeneration: record.factorizationGeneration,
+    };
+    if (record.conditionEstimate !== undefined) {
+        return { ...result, conditionEstimate: record.conditionEstimate };
+    }
+    return result;
+}
+export function reviveFarFieldResult(value) {
+    const record = value;
+    return {
+        radiusM: record.radiusM,
+        frequencyMHz: record.frequencyMHz,
+        thetaDeg: copyFloat64(record.thetaDeg, "thetaDeg"),
+        phiDeg: copyFloat64(record.phiDeg, "phiDeg"),
+        eThetaReal: copyFloat64(record.eThetaReal, "eThetaReal"),
+        eThetaImag: copyFloat64(record.eThetaImag, "eThetaImag"),
+        ePhiReal: copyFloat64(record.ePhiReal, "ePhiReal"),
+        ePhiImag: copyFloat64(record.ePhiImag, "ePhiImag"),
+    };
+}
+export function reviveEmbeddedFarFieldResult(value) {
+    const record = value;
+    const field = reviveFarFieldResult(record);
+    const normalization = record.normalization.kind === "unit-current"
+        ? Object.freeze({ kind: "unit-current", valueA: 1 })
+        : Object.freeze({ kind: "unit-voltage", valueV: 1 });
+    return {
+        ...field,
+        ports: snapshotPorts(record.ports),
+        normalization,
+        samplesPerPort: record.samplesPerPort,
+    };
+}
+export function cloneFloat64(source) {
+    return Float64Array.from(source);
+}
+export function serializeCreateOptions(options) {
+    if (options === undefined) {
+        return { transfer: [] };
+    }
+    const payload = {};
+    const transfer = [];
+    if (options.wasmUrl !== undefined && options.wasmBinary !== undefined) {
+        throw new NecInputError("wasmUrl and wasmBinary cannot both be supplied");
+    }
+    if (options.wasmUrl !== undefined) {
+        payload.wasmUrl = options.wasmUrl instanceof URL
+            ? options.wasmUrl.href
+            : options.wasmUrl;
+    }
+    if (options.wasmBinary !== undefined) {
+        let bytes;
+        try {
+            if (options.wasmBinary instanceof Uint8Array) {
+                bytes = Uint8Array.from(options.wasmBinary);
+            }
+            else if (options.wasmBinary instanceof ArrayBuffer) {
+                bytes = new Uint8Array(options.wasmBinary.slice(0));
+            }
+            else {
+                throw new TypeError("wasmBinary is not an ArrayBuffer or Uint8Array");
+            }
+        }
+        catch (cause) {
+            throw new NecInputError("wasmBinary must be an ArrayBuffer or Uint8Array with readable WASM bytes", { cause });
+        }
+        payload.wasmBinary = bytes.buffer;
+        transfer.push(bytes.buffer);
+    }
+    if (payload.wasmUrl === undefined && payload.wasmBinary === undefined) {
+        return { transfer };
+    }
+    return { payload, transfer };
+}
+export function toCreateNecModelOptions(options) {
+    if (options === undefined) {
+        return undefined;
+    }
+    if (options.wasmBinary !== undefined) {
+        return { wasmBinary: options.wasmBinary };
+    }
+    if (options.wasmUrl !== undefined) {
+        return { wasmUrl: options.wasmUrl };
+    }
+    return undefined;
+}

package/dist/worker-runtime.d.ts

@@ -0,0 +1,14 @@
+import type { CreateNecModelOptions, NecModel, NecWorkerProgressEvent } from "./types.js";
+import { type WorkerRequest, type WorkerResponse } from "./worker-protocol.js";
+export interface WorkerSession {
+    model: NecModel | undefined;
+}
+export type ModelFactory = (options?: CreateNecModelOptions) => Promise<NecModel>;
+export interface WorkerRuntimeDependencies {
+    readonly createModel: ModelFactory;
+    readonly emitProgress: (event: NecWorkerProgressEvent) => void;
+}
+export declare function handleWorkerRequest(session: WorkerSession, request: WorkerRequest, deps: WorkerRuntimeDependencies): Promise<{
+    response: WorkerResponse;
+    transfer: ArrayBuffer[];
+}>;

package/dist/worker-runtime.js

@@ -0,0 +1,130 @@
+import { NecRuntimeError, NecStateError } from "./errors.js";
+import { collectTransferables, serializeError, toCreateNecModelOptions, } from "./worker-protocol.js";
+function invokeModel(model, method, args) {
+    switch (method) {
+        case "addWire":
+            model.addWire(args[0]);
+            return undefined;
+        case "completeGeometry":
+            model.completeGeometry(args[0]);
+            return undefined;
+        case "definePorts":
+            model.definePorts(args[0]);
+            return undefined;
+        case "addLoad":
+            model.addLoad(args[0]);
+            return undefined;
+        case "clearLoads":
+            model.clearLoads();
+            return undefined;
+        case "setGround":
+            model.setGround(args[0]);
+            return undefined;
+        case "prepare":
+            model.prepare(args[0]);
+            return undefined;
+        case "computeImpedanceMatrix":
+            return model.computeImpedanceMatrix();
+        case "solveVoltages":
+            return model.solveVoltages(args[0]);
+        case "solveCurrents":
+            return model.solveCurrents(args[0]);
+        case "computeFarField":
+            return model.computeFarField(args[0]);
+        case "computeEmbeddedFarFields":
+            return model.computeEmbeddedFarFields(args[0], args[1]);
+        case "dispose":
+            model.dispose();
+            return undefined;
+        default: {
+            const unexpected = method;
+            throw new NecRuntimeError(`Unsupported worker method ${String(unexpected)}`);
+        }
+    }
+}
+async function withProgress(emitProgress, operation, body) {
+    emitProgress({ operation, phase: "start" });
+    try {
+        return await body();
+    }
+    finally {
+        emitProgress({ operation, phase: "complete" });
+    }
+}
+export async function handleWorkerRequest(session, request, deps) {
+    if (request.kind === "create") {
+        if (session.model !== undefined) {
+            return {
+                response: {
+                    id: request.id,
+                    kind: "error",
+                    state: session.model.state,
+                    error: serializeError(new NecRuntimeError("The worker model has already been created")),
+                },
+                transfer: [],
+            };
+        }
+        try {
+            const model = await withProgress(deps.emitProgress, "create", () => deps.createModel(toCreateNecModelOptions(request.options)));
+            session.model = model;
+            return {
+                response: {
+                    id: request.id,
+                    kind: "ok",
+                    state: model.state,
+                    transferredBufferCount: 0,
+                },
+                transfer: [],
+            };
+        }
+        catch (error) {
+            return {
+                response: {
+                    id: request.id,
+                    kind: "error",
+                    error: serializeError(error),
+                },
+                transfer: [],
+            };
+        }
+    }
+    const model = session.model;
+    if (model === undefined) {
+        return {
+            response: {
+                id: request.id,
+                kind: "error",
+                error: serializeError(new NecStateError(request.method, "disposed", "The worker model is not created")),
+            },
+            transfer: [],
+        };
+    }
+    try {
+        const result = await withProgress(deps.emitProgress, request.method, () => invokeModel(model, request.method, request.args));
+        if (request.method === "dispose") {
+            session.model = undefined;
+        }
+        const transfer = collectTransferables(result);
+        return {
+            response: {
+                id: request.id,
+                kind: "ok",
+                state: request.method === "dispose" ? "disposed" : model.state,
+                result,
+                transferredBufferCount: transfer.length,
+            },
+            transfer,
+        };
+    }
+    catch (error) {
+        return {
+            response: {
+                id: request.id,
+                kind: "error",
+                state: model.state,
+                error: serializeError(error),
+            },
+            transfer: [],
+        };
+    }
+}

package/dist/worker.d.ts

@@ -0,0 +1,5 @@
+export { NecConditioningError, NecError, NecGeometryError, NecInputError, NecPortError, NecRuntimeError, NecSolverError, NecStateError, } from "./errors.js";
+export { abiVersion, engineVersion, packageVersion } from "./versions.js";
+export type { NecErrorCode, NecErrorOptions } from "./errors.js";
+export { createNecWorkerModel } from "./worker-client.js";
+export type { AngleSweep, CartesianPointM, CompleteGeometryOptions, ComplexMatrix, ComplexVector, ConductivityLoad, CreateNecModelOptions, CreateNecWorkerModelOptions, DistributedParallelRlcLoad, DistributedSeriesRlcLoad, EmbeddedFarFieldResult, EmbeddedFieldNormalization, FarFieldRequest, FarFieldResult, FiniteGround, FreeSpaceGround, GroundConnection, GroundModel, ImpedanceLoad, ImpedanceResult, LoadDefinition, NecModelState, NecWorkerModel, NecWorkerOperation, NecWorkerProgressEvent, NecWorkerProgressListener, ParallelRlcLoad, PerfectGround, PortDefinition, PortSolution, PrepareOptions, SegmentSelection, SeriesRlcLoad, WireDefinition, } from "./types.js";

package/dist/worker.js

@@ -0,0 +1,3 @@
+export { NecConditioningError, NecError, NecGeometryError, NecInputError, NecPortError, NecRuntimeError, NecSolverError, NecStateError, } from "./errors.js";
+export { abiVersion, engineVersion, packageVersion } from "./versions.js";
+export { createNecWorkerModel } from "./worker-client.js";

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@necpp-engine/wasm",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Stateful NEC2++ electromagnetic solver for Node and the browser",
+  "keywords": [
+    "antenna",
+    "electromagnetics",
+    "nec2",
+    "simulation",
+    "typescript",
+    "wasm",
+    "webassembly"
+  ],
+  "license": "GPL-2.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrekuehne/necpp.git",
+    "directory": "packages/necpp-wasm"
+  },
+  "homepage": "https://github.com/andrekuehne/necpp#readme",
+  "bugs": {
+    "url": "https://github.com/andrekuehne/necpp/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js",
+      "default": "./dist/worker.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "COPYING"
+  ],
+  "scripts": {
+    "build": "node scripts/build-dist.mjs",
+    "prepack": "npm run build",
+    "build:test": "node test/build.mjs",
+    "test": "npm run build:test && node --test test/*.test.mjs && npm run typecheck",
+    "test:wasm": "node test/require-wasm.mjs && npm test && npm run test:pack",
+    "test:pack": "node test/require-wasm.mjs && node --test --test-timeout=180000 --test-concurrency=1 test/pack/manifest.test.mjs test/pack/consumer.test.mjs",
+    "test:browser": "node test/browser-integration.mjs",
+    "pack:release": "node scripts/pack-release.mjs",
+    "typecheck": "tsc --project tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "playwright": "1.62.1",
+    "typescript": "5.8.3",
+    "yaml": "2.9.0"
+  }
+}