@swmmrs/swmmrs 0.1.0

package/src/swmmrs/protocol.ts

@@ -0,0 +1,62 @@
+import type { SimulationState, ModelTime } from "./enums.js";
+import type { ErrorDetails } from "./exceptions.js";
+import type { NodeConfiguration, NodePatch, NodeOperations } from "./objects/nodes.js";
+import type { LinkConfiguration, LinkPatch, LinkOperations } from "./objects/links.js";
+import type { SubcatchmentConfiguration, SubcatchmentPatch, SubcatchmentOperations } from "./objects/subcatchments.js";
+import type { ModelOptions, ModelOptionsPatch, OptionsOperations } from "./objects/options.js";
+import type { DefinitionOperations } from "./objects/definitions.js";
+import type { AmmOperations } from "./objects/amm.js";
+import type { RtkOperations } from "./objects/rtk.js";
+import type { LidOperations } from "./objects/lids.js";
+import type { OutputOperations } from "./output.js";
+import type { ScenarioOperations } from "./scenarios.js";
+import type { NodeResults, LinkResults, NodeSnapshot, LinkSnapshot, SubcatchmentResults, SubcatchmentSnapshot, RainGageResults, SimulationStatistics } from "./snapshots.js";
+import type { SimulationInfo, SimulationStatus, RunResults } from "./types.js";
+
+type Operation<A extends unknown[], R> = { args: A; result: R };
+export interface Operations extends NodeOperations, LinkOperations, SubcatchmentOperations, OptionsOperations, DefinitionOperations, AmmOperations, RtkOperations, LidOperations, OutputOperations, ScenarioOperations {
+  open: Operation<[Uint8Array, Record<string, Uint8Array>, number], SimulationInfo>;
+  state: Operation<[], SimulationState>;
+  info: Operation<[], SimulationInfo>;
+  status: Operation<[], SimulationStatus>;
+  start: Operation<[boolean], void>;
+  step: Operation<[], ModelTime | null>;
+  stride: Operation<[number, boolean], ModelTime | null>;
+  node: Operation<[string], NodeResults>;
+  link: Operation<[string], LinkResults>;
+  nodes: Operation<[readonly string[] | undefined], NodeSnapshot>;
+  links: Operation<[readonly string[] | undefined], LinkSnapshot>;
+  subcatchment: Operation<[string], SubcatchmentResults>;
+  subcatchments: Operation<[readonly string[] | undefined], SubcatchmentSnapshot>;
+  rainGage: Operation<[string], RainGageResults>;
+  nodeConfiguration: Operation<[string], NodeConfiguration>;
+  linkConfiguration: Operation<[string], LinkConfiguration>;
+  subcatchmentConfiguration: Operation<[string], SubcatchmentConfiguration>;
+  configureNode: Operation<[string, NodePatch], void>;
+  configureLink: Operation<[string, LinkPatch], void>;
+  configureSubcatchment: Operation<[string, SubcatchmentPatch], void>;
+  setNodeExternalInflow: Operation<[string, number], void>;
+  setLinkTargetSetting: Operation<[string, number], void>;
+  setOutfallStage: Operation<[string, number], void>;
+  setRainGagePrecipitation: Operation<[string, number], void>;
+  setRainGageRainfallOverride: Operation<[string, number | null], void>;
+  options: Operation<[], ModelOptions>;
+  configureOptions: Operation<[ModelOptionsPatch], void>;
+  statistics: Operation<[], SimulationStatistics>;
+  finish: Operation<[], RunResults>;
+  run: Operation<[boolean], RunResults>;
+  end: Operation<[], void>;
+  finalizeReport: Operation<[], void>;
+  report: Operation<[], void>;
+  resetSolver: Operation<[], void>;
+  sleepWorkers: Operation<[], void>;
+  readFile: Operation<[string], Uint8Array>;
+  close: Operation<[], void>;
+}
+export type Method = keyof Operations;
+export type Args<K extends Method> = Operations[K]["args"];
+export type Result<K extends Method> = Operations[K]["result"];
+export type Call = <K extends Method>(method: K, ...args: Args<K>) => Promise<Result<K>>;
+export type Request = { [K in Method]: { id: number; method: K; args: Args<K> } }[Method];
+export type Response = { id: number; ok: true; result: unknown } |
+  { id: number; ok: false; error: ErrorDetails; fatal: boolean };

package/src/swmmrs/runtime.ts

@@ -0,0 +1,188 @@
+import type { FileContents } from "./types.js";
+
+const encoder = new TextEncoder();
+
+type NodeProcess = {
+  versions?: { node?: unknown };
+  getBuiltinModule?: (specifier: string) => unknown;
+};
+type NodeOsModule = { availableParallelism?: () => number };
+type RuntimeGlobal = typeof globalThis & {
+  process?: NodeProcess;
+  navigator?: { hardwareConcurrency?: number };
+};
+
+const runtimeGlobal = globalThis as RuntimeGlobal;
+
+/** True when this module is running in Node rather than a browser page/worker. */
+export const isNodeRuntime = typeof runtimeGlobal.process?.versions?.node === "string";
+
+function hardwareConcurrency(): number {
+  const browserValue = runtimeGlobal.navigator?.hardwareConcurrency;
+  if (typeof browserValue === "number" && Number.isFinite(browserValue) && browserValue > 0) return Math.floor(browserValue);
+  const os = runtimeGlobal.process?.getBuiltinModule?.("node:os") as NodeOsModule | undefined;
+  const nodeValue = os?.availableParallelism?.();
+  return typeof nodeValue === "number" && Number.isFinite(nodeValue) && nodeValue > 0 ? Math.floor(nodeValue) : 1;
+}
+
+const hostThreadCapacity = hardwareConcurrency();
+
+export interface RuntimeInfo {
+  readonly maxThreads: number;
+  readonly defaultThreads: number;
+  readonly parallel: boolean;
+}
+
+async function runtimeCapacity(): Promise<number> {
+  if (!isNodeRuntime || runtimeGlobal.navigator?.hardwareConcurrency !== undefined || hostThreadCapacity > 1) {
+    return hostThreadCapacity;
+  }
+  const os = await dynamicImport("node:os") as NodeOsModule;
+  const value = os.availableParallelism?.();
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : hostThreadCapacity;
+}
+
+/** Return host solver capacity without requiring browser globals in Node. */
+export async function runtimeInfo(): Promise<RuntimeInfo> {
+  const parallel = isNodeRuntime || Boolean(runtimeGlobal.crossOriginIsolated);
+  const maxThreads = await runtimeCapacity();
+  return {
+    maxThreads,
+    defaultThreads: isNodeRuntime ? 1 : parallel ? maxThreads : 1,
+    parallel,
+  };
+}
+
+export interface WorkerCreationOptions {
+  workerUrl?: string | URL;
+}
+
+type NodeWorkerPort = {
+  on(event: "message", listener: (value: unknown) => void): NodeWorkerPort;
+  on(event: "messageerror" | "error", listener: (error: unknown) => void): NodeWorkerPort;
+  on(event: "exit", listener: (code: number) => void): NodeWorkerPort;
+  postMessage(value: unknown, transferList?: readonly ArrayBuffer[]): void;
+  terminate(): Promise<number>;
+};
+type NodeWorkerConstructor = new (
+  filename: string | URL,
+  options?: { type?: "module"; workerData?: unknown },
+) => NodeWorkerPort;
+type NodeWorkerModule = { Worker?: NodeWorkerConstructor };
+type NodeFsModule = { readFile(path: string | URL): Promise<Uint8Array> };
+
+async function dynamicImport(specifier: string): Promise<unknown> {
+  return import(specifier);
+}
+
+function messageError(reason: unknown): Error {
+  return reason instanceof Error ? reason : new Error(String(reason));
+}
+
+/** DOM-shaped adapter around node:worker_threads.Worker. */
+class NodeWorkerAdapter {
+  #worker: NodeWorkerPort;
+  #terminated = false;
+  #failed = false;
+  #pendingError: Error | undefined;
+  #onerror: ((event: ErrorEvent) => void) | null = null;
+
+  onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
+  onmessageerror: ((event: MessageEvent<unknown>) => void) | null = null;
+
+  get onerror(): ((event: ErrorEvent) => void) | null {
+    return this.#onerror;
+  }
+
+  set onerror(handler: ((event: ErrorEvent) => void) | null) {
+    this.#onerror = handler;
+    const pending = this.#pendingError;
+    if (handler && pending) {
+      this.#pendingError = undefined;
+      queueMicrotask(() => handler(this.#errorEvent(pending)));
+    }
+  }
+
+  constructor(worker: NodeWorkerPort) {
+    this.#worker = worker;
+    worker.on("message", (data) => this.onmessage?.({ data } as MessageEvent<unknown>));
+    worker.on("messageerror", (error) => this.onmessageerror?.({ data: error } as MessageEvent<unknown>));
+    worker.on("error", (error) => this.#reportError(error));
+    worker.on("exit", (code) => {
+      if (!this.#terminated && code !== 0) this.#reportError(new Error(`SWMM worker exited with code ${code}`));
+      else if (!this.#terminated && code === 0) this.#reportError(new Error("SWMM worker exited unexpectedly"));
+    });
+  }
+
+  postMessage(message: unknown, transfer?: Transferable[]): void {
+    this.#worker.postMessage(message, transfer as readonly ArrayBuffer[] | undefined);
+  }
+
+  terminate(): void {
+    this.#terminated = true;
+    void this.#worker.terminate();
+  }
+
+  #errorEvent(error: Error): ErrorEvent {
+    return { message: error.message, error, preventDefault() {} } as ErrorEvent;
+  }
+
+  #reportError(reason: unknown): void {
+    if (this.#terminated || this.#failed) return;
+    this.#failed = true;
+    const error = messageError(reason);
+    if (this.#onerror) this.#onerror(this.#errorEvent(error));
+    else this.#pendingError = error;
+  }
+}
+
+/** Convert supported model input values to bytes without requiring browser globals. */
+export async function bytes(value: FileContents): Promise<Uint8Array> {
+  if (typeof value === "string") return encoder.encode(value);
+  if (typeof Blob !== "undefined" && value instanceof Blob) return new Uint8Array(await value.arrayBuffer());
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  throw new TypeError("SWMM files must be strings, Blobs, ArrayBuffers, or typed arrays");
+}
+
+function wasmInitializer(bindings: unknown): (input?: unknown) => Promise<unknown> {
+  if (!bindings || typeof bindings !== "object" || !("default" in bindings)) {
+    throw new TypeError("WASM bindings must export a default initializer");
+  }
+  const initializer = bindings.default;
+  if (typeof initializer !== "function") throw new TypeError("WASM bindings must export a default initializer");
+  return initializer as (input?: unknown) => Promise<unknown>;
+}
+
+/** Read a generated wasm file from disk in Node. Browser callers should use loadWasm. */
+export async function wasmInput(url: string | URL): Promise<Uint8Array> {
+  if (!isNodeRuntime) throw new Error("wasmInput is only available in Node");
+  const fs = await dynamicImport("node:fs/promises") as NodeFsModule;
+  const value = await fs.readFile(url);
+  return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}
+/** Initialize generated wasm with file bytes in Node and its normal URL loader in browsers. */
+export async function loadWasm(bindings: unknown, moduleUrl: string | URL): Promise<unknown> {
+  const initializer = wasmInitializer(bindings);
+  if (!isNodeRuntime) return initializer();
+  return initializer({ module_or_path: await wasmInput(new URL("./swmmrs_bg.wasm", moduleUrl)) });
+}
+
+/** Create one isolated worker using browser Worker or node:worker_threads. */
+export async function createWorker(options: WorkerCreationOptions = {}): Promise<Worker> {
+  if (!isNodeRuntime) {
+    const WorkerConstructor = runtimeGlobal.Worker;
+    if (typeof WorkerConstructor !== "function") throw new Error("SWMM needs browser workers");
+    const url = options.workerUrl ?? new URL("./worker.js", import.meta.url);
+    return new WorkerConstructor(url, { type: "module" });
+  }
+
+  const { Worker: NodeWorker } = await dynamicImport("node:worker_threads") as NodeWorkerModule;
+  if (!NodeWorker) throw new Error("Node worker_threads are unavailable");
+  const target = options.workerUrl ?? new URL("./worker.js", import.meta.url);
+  const bootstrap = new URL("../../worker-node.js", import.meta.url);
+  return new NodeWorkerAdapter(new NodeWorker(bootstrap, {
+    type: "module",
+    workerData: { target: target instanceof URL ? target.href : target, name: "" },
+  })) as unknown as Worker;
+}

package/src/swmmrs/scenarios.ts

@@ -0,0 +1,40 @@
+import type { SimulationInfo } from "./types.js";
+
+/** Transferable bytes and files captured at one quiescent simulation boundary. */
+export interface CheckpointBundle {
+  /** Bundle format identifier. */
+  readonly format: "swmmrs.checkpoint.bundle";
+  /** Supported bundle format version. */
+  readonly version: 1;
+  /** Isolated solver root used for manifest paths; never use it as a host path. */
+  readonly root: string;
+  /** Manifest path relative to `root`. */
+  readonly manifestPath: string;
+  /** Canonical core checkpoint JSON, untouched by the binding. */
+  readonly manifest: Uint8Array;
+  /** Manifest sidecars and validated external dependencies, keyed relative to `root`. */
+  readonly files: Readonly<Record<string, Uint8Array>>;
+}
+
+type Operation<Args extends unknown[], Result> = { args: Args; result: Result };
+
+/** Worker protocol additions for hotstarts, checkpoints, resume, and state load. */
+export interface ScenarioOperations {
+  useHotstart: Operation<[Uint8Array | null], void>;
+  saveHotstart: Operation<[], Uint8Array>;
+  exportCheckpoint: Operation<[], CheckpointBundle>;
+  loadCheckpointState: Operation<[CheckpointBundle], void>;
+  /** The thread count is the final argument, matching the ordinary open operation. */
+  resumeCheckpoint: Operation<[CheckpointBundle, number], SimulationInfo>;
+}
+
+/** Low-level scenario operation names; prefer the methods on `Simulation` for execution. */
+export type ScenarioMethod = keyof ScenarioOperations;
+/** Argument tuple for a low-level scenario operation.
+ * @typeParam K - Scenario operation name.
+ */
+export type ScenarioArgs<K extends ScenarioMethod> = ScenarioOperations[K]["args"];
+/** Resolved result type for a low-level scenario operation.
+ * @typeParam K - Scenario operation name.
+ */
+export type ScenarioResult<K extends ScenarioMethod> = ScenarioOperations[K]["result"];