@openmbee/opensysml 0.9.2 → 0.10.0

package/dist/node/index.d.ts

@@ -1,12 +1,15 @@
 import { Connection } from "../core/connection.js";
+import { Conversion, Migration } from "../core/conversion.js";
 import type { TransportOptions } from "../core/connection.js";
 import { Model } from "../core/model.js";
 import type { ParseOptions } from "../core/model.js";
 export * from "../core/index.js";
 export { ALLOW_UNPINNED_ENV, API_BASE_URL, BINARY_ENV, BinaryNotFoundError, DEFAULT_GITHUB_REPO, NETWORK_TIMEOUT_MS, PINNED_SHA256, RELEASES_BASE_URL, REPO_ENV, VERSION_ENV, binaryName, cachedBinaryPath, cachedRelease, defaultGithubRepo, downloadBinary, expectedDigest, metadataPath, pinnedDigest, platformPackage, releaseAssetName, releaseDownloadUrl, resolveBinary, resolveLatestVersion, signedManifestDigest, staleCacheReason, unpinnedDownloadsAllowed, verifyChecksum, writeMetadata, } from "./binary.js";
-export type { Binary, CacheMetadata, DownloadOptions, PinnedDigests } from "./binary.js";
+export type { Binary, CacheMetadata, DownloadOptions, PinnedDigests, } from "./binary.js";
 export { BUNDLE_ASSET, MANIFEST_ASSET, ReleaseSigner, SIGNED_MANIFEST_SIGNERS, manifestDigest, signerFor, verifiedManifestDigest, verifyManifest, } from "./signing.js";
 export { PrivateService, currentPrivateService } from "./service.js";
+export { connectWasm } from "./wasm.js";
+export type { WasmConnectOptions } from "./wasm.js";
 /** Names a service to connect to instead of starting one. */
 export declare const SERVICE_ENV = "OPENSYSML_SERVICE";
 /** How this process connects. Without an address it starts a private child. */
@@ -15,6 +18,13 @@ export interface ConnectOptions extends TransportOptions {
     httpVersion?: "1.1" | "2";
     /** Wire protocol. Connect by default; gRPC needs HTTP/2 and a service that serves it. */
     protocol?: "connect" | "grpc";
+    /**
+     * Release tag the service must report, or 'latest'; $OPENSYSML_GRPC_VERSION
+     * when omitted. A mismatch refuses the connection with a StaleServiceError.
+     */
+    version?: string;
+    /** Capabilities the service must report for the connection to be returned. */
+    requireCapabilities?: readonly string[];
 }
 /**
  * Connects to a sysml-grpc service.
@@ -25,7 +35,24 @@ export interface ConnectOptions extends TransportOptions {
  * closing the connection leaves that service running.
  */
 export declare function connect(options?: ConnectOptions): Promise<Connection>;
-/** Parses a file over a connection of its own, which the model closes. */
+/**
+ * Writes `target` to `path`: a model converted in the format its extension
+ * names, a conversion's content written as the service returned it, or a
+ * migration's content with its image files beside it, at the relative paths
+ * the migrated model refers to them with, as `sysml -migrate -o` writes them.
+ * A migration that would replace the v1 model it was read from, or land an
+ * image outside `path`'s directory, over the model or through a symbolic link
+ * at its path, is refused with a `RangeError` before anything is written.
+ * Images are then written without following a link at their path, so one put
+ * there after the check is not followed; a directory on the way replaced
+ * while the write is under way is not guarded against, as `sysml -migrate -o`
+ * does not either.
+ */
+export declare function save(target: Migration, path: string): Promise<Migration>;
+export declare function save(target: Model | Conversion, path: string, options?: {
+    toFormat?: string;
+    tolerateSyntaxErrors?: boolean;
+}): Promise<Conversion>;
 export declare function load(path: string, options?: ConnectOptions & ParseOptions): Promise<Model>;
 /** Parses inline source over a connection of its own, which the model closes. */
 export declare function loads(source: string, options?: ConnectOptions & ParseOptions): Promise<Model>;

package/dist/node/index.js

@@ -1,14 +1,20 @@
 // Node entry point: everything the core does, plus the private-child lifecycle.
-import { createConnectTransport, createGrpcTransport } from "@connectrpc/connect-node";
+import { constants } from "node:fs";
+import { lstat, mkdir, readlink, realpath, stat, writeFile, } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+import { createConnectTransport, createGrpcTransport, } from "@connectrpc/connect-node";
 import { Connection } from "../core/connection.js";
+import { Conversion, Migration, formatOfPath } from "../core/conversion.js";
 import { OpenSysMLError } from "../core/errors.js";
 import { Model } from "../core/model.js";
-import { baseUrl, encodingOf, interceptors, timeoutOf } from "../core/transport.js";
+import { baseUrl, encodingOf, interceptors, timeoutOf, } from "../core/transport.js";
+import { resolveLatestVersion, VERSION_ENV } from "./binary.js";
 import { acquirePrivateService } from "./service.js";
 export * from "../core/index.js";
 export { ALLOW_UNPINNED_ENV, API_BASE_URL, BINARY_ENV, BinaryNotFoundError, DEFAULT_GITHUB_REPO, NETWORK_TIMEOUT_MS, PINNED_SHA256, RELEASES_BASE_URL, REPO_ENV, VERSION_ENV, binaryName, cachedBinaryPath, cachedRelease, defaultGithubRepo, downloadBinary, expectedDigest, metadataPath, pinnedDigest, platformPackage, releaseAssetName, releaseDownloadUrl, resolveBinary, resolveLatestVersion, signedManifestDigest, staleCacheReason, unpinnedDownloadsAllowed, verifyChecksum, writeMetadata, } from "./binary.js";
 export { BUNDLE_ASSET, MANIFEST_ASSET, ReleaseSigner, SIGNED_MANIFEST_SIGNERS, manifestDigest, signerFor, verifiedManifestDigest, verifyManifest, } from "./signing.js";
 export { PrivateService, currentPrivateService } from "./service.js";
+export { connectWasm } from "./wasm.js";
 /** Names a service to connect to instead of starting one. */
 export const SERVICE_ENV = "OPENSYSML_SERVICE";
 /**
@@ -26,7 +32,147 @@ export async function connect(options = {}) {
     }
     return connectPrivate(options);
 }
+export async function save(target, path, options = {}) {
+    if (target instanceof Migration) {
+        const files = await migrationFiles(target, path);
+        await writeFile(path, target.content, "utf8");
+        await files.reduce((previous, [file, data]) => previous.then(() => writeImage(file, data)), Promise.resolve());
+        return target;
+    }
+    const conversion = target instanceof Conversion
+        ? target
+        : await target.convert(options.toFormat ?? formatOfPath(path), {
+            ...(options.tolerateSyntaxErrors === undefined
+                ? {}
+                : { tolerateSyntaxErrors: options.tolerateSyntaxErrors }),
+        });
+    await writeFile(path, conversion.content, "utf8");
+    return conversion;
+}
 /** Parses a file over a connection of its own, which the model closes. */
+/**
+ * Where a migration's image files land when its model is written to `path`,
+ * refusing any that would escape the model's directory or replace the model
+ * or the v1 source, and refusing `path` itself when it is the source. A source
+ * no longer at its path protects nothing: nothing of it would be replaced.
+ */
+async function migrationFiles(migration, path) {
+    const source = (await exists(migration.sourcePath))
+        ? migration.sourcePath
+        : "";
+    if (source !== "" && (await samePath(path, source))) {
+        throw new RangeError(`${path} names the model being migrated; the v1 model would be replaced by its migration`);
+    }
+    const base = resolve(dirname(path));
+    const landedBase = await landing(base);
+    const guarded = [path, source].filter((candidate) => candidate !== "");
+    return Promise.all([...migration.files].map(async ([name, data]) => {
+        const file = await imageFile(name, base, landedBase, guarded);
+        return [file, data];
+    }));
+}
+/**
+ * Where the image `name` lands under `base`, refusing one that would escape
+ * `base`, replace a guarded path, or be written through a symbolic link.
+ */
+async function imageFile(name, base, landedBase, guarded) {
+    const segments = name.split("/");
+    const file = resolve(base, ...segments);
+    if (segments.some((segment) => segment === "" ||
+        segment === "." ||
+        segment === ".." ||
+        segment.includes("\\")) ||
+        !within(base, file) ||
+        !within(landedBase, await landing(file))) {
+        throw new RangeError(`the migration's image ${name} would land outside ${base}`);
+    }
+    const replaced = await Promise.all(guarded.map((candidate) => samePath(file, candidate)));
+    const replacing = guarded.find((_, index) => replaced[index]);
+    if (replacing !== undefined) {
+        throw new RangeError(`the migration's image ${name} would replace ${replacing}`);
+    }
+    if (await isSymbolicLink(file)) {
+        throw new RangeError(`the migration's image ${name} would be written through a symbolic link at ${file}`);
+    }
+    return file;
+}
+/** Writes one image, creating its directory. */
+async function writeImage(file, data) {
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, data, { flag: IMAGE_FLAGS });
+}
+/**
+ * How an image is written: created or truncated in place, never through a link
+ * at its path. Windows has no O_NOFOLLOW; the bitwise or reads its absence as 0.
+ */
+const IMAGE_FLAGS = constants.O_WRONLY |
+    constants.O_CREAT |
+    constants.O_TRUNC |
+    constants.O_NOFOLLOW;
+/** Whether `path` is itself a symbolic link, wherever it points. */
+function isSymbolicLink(path) {
+    return lstat(path).then((status) => status.isSymbolicLink(), () => false);
+}
+/** Whether `path` names something: an empty path, or one that is gone, does not. */
+async function exists(path) {
+    return (path !== "" &&
+        (await stat(path).then(() => true, () => false)));
+}
+/** Whether `file` lies strictly below the directory `base`, both absolute. */
+function within(base, file) {
+    const below = relative(base, file);
+    return (below !== "" &&
+        !isAbsolute(below) &&
+        below !== ".." &&
+        !below.startsWith(".." + sep));
+}
+/** Whether a write to `a` lands on `b`: the same file when both exist, else the same resolved path. */
+async function samePath(a, b) {
+    const [statA, statB] = await Promise.all([
+        stat(a, { bigint: true }).catch(() => undefined),
+        stat(b, { bigint: true }).catch(() => undefined),
+    ]);
+    if (statA !== undefined &&
+        statB !== undefined &&
+        statA.ino !== 0n &&
+        statB.ino !== 0n) {
+        return statA.dev === statB.dev && statA.ino === statB.ino;
+    }
+    return (await landing(a)) === (await landing(b));
+}
+/**
+ * The absolute path a write to `path` lands on: every symbolic link on the way
+ * followed, a dangling one included, through the deepest ancestor that exists,
+ * whatever below it does not.
+ */
+async function landing(path) {
+    let head = resolve(path);
+    const tail = [];
+    let hops = 0;
+    for (;;) {
+        try {
+            return join(await realpath(head), ...tail);
+        }
+        catch {
+            const target = await readlink(head).catch(() => undefined);
+            if (target !== undefined) {
+                if (++hops >= MAX_SYMLINK_HOPS) {
+                    throw new RangeError(`${path}: too many levels of symbolic links`);
+                }
+                head = resolve(dirname(head), target);
+                continue;
+            }
+            const parent = dirname(head);
+            if (parent === head) {
+                return join(head, ...tail);
+            }
+            tail.unshift(basename(head));
+            head = parent;
+        }
+    }
+}
+/** Dangling symbolic links followed before a path is judged to loop, as the kernel's limit. */
+const MAX_SYMLINK_HOPS = 40;
 export async function load(path, options = {}) {
     const connection = await connect(options);
     try {
@@ -48,31 +194,69 @@ export async function loads(source, options = {}) {
         throw error;
     }
 }
+// The release a connection requires, 'latest' resolved to the tag it names.
+async function requiredRelease(options) {
+    const asked = options.version ?? process.env[VERSION_ENV];
+    if (asked === undefined || asked === "") {
+        return undefined;
+    }
+    if (asked === "latest") {
+        try {
+            return await resolveLatestVersion();
+        }
+        catch {
+            // A release that cannot be resolved is not required, as ensure_binary reads it.
+            return undefined;
+        }
+    }
+    return asked;
+}
 async function connectPrivate(options) {
     // Checked before a child is started, so a bad option costs no process.
     const encoding = encodingOf(options);
     const timeoutMs = timeoutOf(options);
-    const service = await acquirePrivateService();
+    const required = await requiredRelease(options);
+    const service = await acquirePrivateService(required);
     const backend = {
         origin: `${service.binary.path}, started by this client`,
         release: () => service.release(),
+        warn: (message, type) => {
+            process.emitWarning(message, type);
+        },
+        resolvePath: (path) => resolve(path),
     };
+    // The open owns release from here on: a failure inside Connection.open
+    // releases exactly once, so a refusal cannot drop another connection's hold.
+    let transport;
     try {
-        return await Connection.open({
-            transport: transportFor(baseUrl(service.address), options),
-            encoding,
-            backend,
-            timeoutMs,
-        });
+        transport = transportFor(baseUrl(service.address), options);
     }
     catch (error) {
         await service.release();
         throw error;
     }
+    return Connection.open({
+        transport,
+        encoding,
+        backend,
+        timeoutMs,
+        ...(required === undefined ? {} : { requiredVersion: required }),
+        ...(options.requireCapabilities === undefined
+            ? {}
+            : { requiredCapabilities: options.requireCapabilities }),
+        stale: {
+            address: service.address,
+            remedy: `the binary this client started, ${service.binary.path}, is not ` +
+                `${required ?? "the release asked for"}: make that release available (its ` +
+                `download is cached under ~/.opensysml/bin), or accept what is installed ` +
+                `by passing version: undefined and unsetting $${VERSION_ENV}`,
+        },
+    });
 }
 async function connectExternal(address, options) {
     const url = baseUrl(address);
     const timeoutMs = timeoutOf(options);
+    const required = await requiredRelease(options);
     return Connection.open({
         transport: transportFor(url, options),
         encoding: encodingOf(options),
@@ -80,8 +264,22 @@ async function connectExternal(address, options) {
             origin: `${url}, which this client did not start`,
             // A service this client did not start is never stopped by it.
             release: () => Promise.resolve(),
+            warn: (message, type) => {
+                process.emitWarning(message, type);
+            },
+            resolvePath: (path) => resolve(path),
         },
         timeoutMs,
+        ...(required === undefined ? {} : { requiredVersion: required }),
+        ...(options.requireCapabilities === undefined
+            ? {}
+            : { requiredCapabilities: options.requireCapabilities }),
+        stale: {
+            address: url,
+            remedy: `stop the service listening on ${url} yourself and let this client start ` +
+                `a ${required ?? "matching"} one, or accept what is running by passing ` +
+                `version: undefined and unsetting $${VERSION_ENV}`,
+        },
     });
 }
 function transportFor(url, options) {
@@ -90,7 +288,10 @@ function transportFor(url, options) {
         if (!binary) {
             throw new OpenSysMLError("the gRPC protocol carries protobuf bodies; JSON needs the Connect protocol");
         }
-        return createGrpcTransport({ baseUrl: url, interceptors: interceptors(options) });
+        return createGrpcTransport({
+            baseUrl: url,
+            interceptors: interceptors(options),
+        });
     }
     return createConnectTransport({
         baseUrl: url,

package/dist/node/service.d.ts

@@ -8,6 +8,8 @@ export declare class PrivateService {
     private readonly child;
     private readonly stderr;
     private ended;
+    /** The release key {@link acquirePrivateService} filed this child under. */
+    key: string;
     private constructor();
     /** The process id of the child, which the orphan-safety test reads. */
     get pid(): number | undefined;
@@ -23,9 +25,9 @@ export declare class PrivateService {
      */
     stop(): Promise<void>;
     /** Starts a child and waits for the address it bound. */
-    static start(): Promise<PrivateService>;
+    static start(version?: string): Promise<PrivateService>;
 }
-/** Takes a hold on this thread's private child, starting one when there is none. */
-export declare function acquirePrivateService(): Promise<PrivateService>;
+/** Takes a hold on the private child for `version`, starting one when there is none. */
+export declare function acquirePrivateService(version?: string): Promise<PrivateService>;
 /** The private child this thread holds, for tests and diagnostics. */
 export declare function currentPrivateService(): PrivateService | undefined;

package/dist/node/service.js

@@ -7,10 +7,10 @@ import { resolveBinary } from "./binary.js";
 const START_TIMEOUT_MS = 10_000;
 const STOP_TIMEOUT_MS = 5_000;
 const STDERR_LINES_KEPT = 20;
-/** The one private child of this thread, and the connections holding it. */
-let shared;
-/** A start in flight, so concurrent connect() calls share one child. */
-let starting;
+/** The private children of this thread, one per release asked for, keyed by tag. */
+const shared = new Map();
+/** Starts in flight, so concurrent connect() calls share one child per release. */
+const starting = new Map();
 /** A sysml-grpc child of this process, shared by every connection that needs one. */
 export class PrivateService {
     address;
@@ -20,6 +20,8 @@ export class PrivateService {
     child;
     stderr;
     ended;
+    /** The release key {@link acquirePrivateService} filed this child under. */
+    key = "";
     constructor(init) {
         this.child = init.child;
         this.binary = init.binary;
@@ -48,8 +50,8 @@ export class PrivateService {
         if (this.refs > 0) {
             return;
         }
-        if (shared === this) {
-            shared = undefined;
+        if (shared.get(this.key) === this) {
+            shared.delete(this.key);
         }
         await this.stop();
     }
@@ -82,8 +84,8 @@ export class PrivateService {
         this.child.stdin.destroy();
     }
     /** Starts a child and waits for the address it bound. */
-    static async start() {
-        const binary = await resolveBinary();
+    static async start(version) {
+        const binary = await resolveBinary(version === undefined ? {} : { version });
         const child = spawn(binary.path, ["-port", "0", "-health-port", "0", "-report-address", "-exit-with-parent"], {
             stdio: ["pipe", "pipe", "pipe"],
             // A new session (a new process group on Windows), so a Ctrl-C meant for
@@ -118,28 +120,32 @@ export class PrivateService {
         });
     }
 }
-/** Takes a hold on this thread's private child, starting one when there is none. */
-export async function acquirePrivateService() {
-    for (;;) {
-        const existing = shared;
-        if (existing?.alive) {
-            existing.refs += 1;
-            return existing;
-        }
-        starting ??= PrivateService.start()
-            .then((service) => {
-            shared = service;
-            return service;
-        })
-            .finally(() => {
-            starting = undefined;
-        });
-        await starting;
+/** Takes a hold on the private child for `version`, starting one when there is none. */
+export async function acquirePrivateService(version) {
+    const key = version ?? "";
+    const existing = shared.get(key);
+    if (existing?.alive) {
+        existing.refs += 1;
+        return existing;
     }
+    let pending = starting.get(key);
+    pending ??= PrivateService.start(version)
+        .then((service) => {
+        service.key = key;
+        shared.set(key, service);
+        return service;
+    })
+        .finally(() => {
+        starting.delete(key);
+    });
+    starting.set(key, pending);
+    await pending;
+    // The child just started is taken by the same path as one found alive.
+    return acquirePrivateService(version);
 }
 /** The private child this thread holds, for tests and diagnostics. */
 export function currentPrivateService() {
-    return shared;
+    return [...shared.values()].find((service) => service.refs > 0) ?? [...shared.values()][0];
 }
 function startFailure(binary, stderr, cause) {
     const why = cause instanceof Error ? cause.message : String(cause);

package/dist/node/wasm-source.d.ts

@@ -0,0 +1,18 @@
+import type { WorkerWasmSource } from "../core/wasm.js";
+export interface NodeWasmSourceOptions {
+    wasm?: string | URL | Uint8Array;
+    wasmExec?: string | URL;
+}
+export interface ResolvedNodeWasmSources {
+    wasm: string | URL | Uint8Array;
+    wasmExec: string | URL;
+}
+export type PackageJsonResolver = (specifier: string) => string;
+export declare function loadNodeWasm(source: WorkerWasmSource | URL): Promise<BufferSource | WebAssembly.Module>;
+export declare function resolveWasmSources(options: NodeWasmSourceOptions, resolvePackageJson?: PackageJsonResolver): ResolvedNodeWasmSources;
+export declare function resolveWasmPackage(resolvePackageJson?: PackageJsonResolver): {
+    wasm: string;
+    wasmExec: string;
+};
+export declare function moduleSpecifier(source: string | URL): string;
+export declare function parseUrl(source: string): URL | undefined;

package/dist/node/wasm-source.js

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { OpenSysMLError } from "../core/errors.js";
+import { PACKAGE_NAME, WASM_PACKAGE } from "../core/package.js";
+export async function loadNodeWasm(source) {
+    if (source instanceof WebAssembly.Module ||
+        source instanceof ArrayBuffer ||
+        ArrayBuffer.isView(source)) {
+        return source;
+    }
+    const url = source instanceof URL ? source : parseUrl(source);
+    if (url?.protocol === "file:") {
+        return readFile(url);
+    }
+    if (url !== undefined) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`could not fetch the WebAssembly module: ${response.status}`);
+        }
+        return response.arrayBuffer();
+    }
+    if (typeof source === "string") {
+        return readFile(isAbsolute(source) ? source : resolve(source));
+    }
+    return readFile(source);
+}
+export function resolveWasmSources(options, resolvePackageJson = createRequire(import.meta.url).resolve) {
+    if (options.wasm !== undefined) {
+        if (options.wasmExec === undefined) {
+            throw new OpenSysMLError("connectWasm needs the wasmExec option when wasm is provided");
+        }
+        return { wasm: options.wasm, wasmExec: options.wasmExec };
+    }
+    const assets = resolveWasmPackage(resolvePackageJson);
+    return {
+        wasm: assets.wasm,
+        wasmExec: options.wasmExec ?? assets.wasmExec,
+    };
+}
+export function resolveWasmPackage(resolvePackageJson = createRequire(import.meta.url).resolve) {
+    let packageJson;
+    try {
+        packageJson = resolvePackageJson(`${WASM_PACKAGE}/package.json`);
+    }
+    catch (cause) {
+        throw new OpenSysMLError(`connectWasm needs sysml-wasm.wasm: install ${WASM_PACKAGE} at ${clientVersion()}, or pass wasm and wasmExec`, { cause });
+    }
+    const packageDirectory = dirname(packageJson);
+    return {
+        wasm: join(packageDirectory, "sysml-wasm.wasm"),
+        wasmExec: join(packageDirectory, "wasm_exec.js"),
+    };
+}
+export function moduleSpecifier(source) {
+    if (source instanceof URL) {
+        return source.href;
+    }
+    if (!/^[A-Za-z]:[\\/]/.test(source)) {
+        try {
+            return new URL(source).href;
+        }
+        catch {
+            // Resolve filesystem paths relative to the current working directory.
+        }
+    }
+    return pathToFileURL(isAbsolute(source) ? source : resolve(source)).href;
+}
+export function parseUrl(source) {
+    if (/^[A-Za-z]:[\\/]/.test(source)) {
+        return undefined;
+    }
+    try {
+        return new URL(source);
+    }
+    catch {
+        return undefined;
+    }
+}
+function clientVersion() {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const packageJson = join(directory, "package.json");
+        if (existsSync(packageJson)) {
+            const metadata = JSON.parse(readFileSync(packageJson, "utf8"));
+            if (typeof metadata === "object" &&
+                metadata !== null &&
+                "name" in metadata &&
+                metadata.name === PACKAGE_NAME &&
+                "version" in metadata &&
+                typeof metadata.version === "string") {
+                return metadata.version;
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            throw new OpenSysMLError("the OpenSysML Node package version could not be found");
+        }
+        directory = parent;
+    }
+}

package/dist/node/wasm-worker.d.ts

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

package/dist/node/wasm-worker.js

@@ -0,0 +1,10 @@
+import { parentPort } from "node:worker_threads";
+import { loadGoConstructor, serveWasmPort, } from "../core/wasm.js";
+import { loadNodeWasm, moduleSpecifier } from "./wasm-source.js";
+if (parentPort === null) {
+    throw new Error("the sysml-wasm worker must run in a worker thread");
+}
+serveWasmPort(parentPort, {
+    loadWasm: loadNodeWasm,
+    loadGo: (wasmExec) => loadGoConstructor(wasmExec === undefined ? undefined : moduleSpecifier(wasmExec)),
+});

package/dist/node/wasm.d.ts

@@ -0,0 +1,17 @@
+import { Connection } from "../core/connection.js";
+import type { TransportOptions } from "../core/connection.js";
+/** Options for connecting to a Go WebAssembly module from Node. */
+export interface WasmConnectOptions extends TransportOptions {
+    /** Path, file URL, HTTP URL, or bytes of sysml-wasm.wasm. */
+    wasm?: string | URL | Uint8Array;
+    /** wasm_exec.js from the Go toolchain that built the module. */
+    wasmExec?: string | URL;
+    /** Run the module in a worker thread (default) or this thread. */
+    thread?: "worker" | "inline";
+    version?: string;
+    requireCapabilities?: readonly string[];
+}
+/**
+ * Connects to sysml-wasm, in a worker by default or inline when requested.
+ */
+export declare function connectWasm(options?: WasmConnectOptions): Promise<Connection>;

package/dist/node/wasm.js

@@ -0,0 +1,63 @@
+import { Worker } from "node:worker_threads";
+import { Connection } from "../core/connection.js";
+import { connectWasmHost, instantiateInline, loadGoConstructor, WorkerWasmHost, } from "../core/wasm.js";
+import { loadNodeWasm, moduleSpecifier, resolveWasmSources } from "./wasm-source.js";
+/**
+ * Connects to sysml-wasm, in a worker by default or inline when requested.
+ */
+export async function connectWasm(options = {}) {
+    const sources = resolveWasmSources(options);
+    const wasmExec = moduleSpecifier(sources.wasmExec);
+    let host;
+    if (options.thread === "inline") {
+        const module = await loadNodeWasm(sources.wasm);
+        const Go = await loadGoConstructor(wasmExec);
+        host = await instantiateInline(module, Go);
+    }
+    else {
+        host = await startWorker(sources.wasm, wasmExec);
+    }
+    return connectWasmHost(host, options);
+}
+async function startWorker(wasm, wasmExec) {
+    const worker = new Worker(new URL("./wasm-worker.js", import.meta.url));
+    const host = new WorkerWasmHost(nodeWorkerEndpoint(worker));
+    const { source, transfer } = workerSource(wasm);
+    try {
+        return await host.start({ type: "init", wasm: source, wasmExec }, transfer);
+    }
+    catch (error) {
+        await host.close();
+        throw error;
+    }
+}
+function workerSource(wasm) {
+    if (wasm instanceof Uint8Array) {
+        const bytes = Uint8Array.from(wasm);
+        return { source: bytes.buffer, transfer: [bytes.buffer] };
+    }
+    return { source: wasm instanceof URL ? wasm.href : wasm, transfer: [] };
+}
+function nodeWorkerEndpoint(worker) {
+    let closed = false;
+    return {
+        post(message, transfer) {
+            worker.postMessage(message, [...transfer]);
+        },
+        onMessage(listener) {
+            worker.on("message", listener);
+        },
+        onFailure(listener) {
+            worker.on("error", listener);
+            worker.on("exit", (code) => {
+                if (!closed) {
+                    listener(new Error(`the sysml-wasm worker exited with code ${code}`));
+                }
+            });
+        },
+        async terminate() {
+            closed = true;
+            await worker.terminate();
+        },
+    };
+}