@swmmrs/swmmrs 0.1.0

package/src/swmmrs/objects/collections.ts

@@ -0,0 +1,153 @@
+import { ObjectNotFoundError } from "../exceptions.js";
+import type { Call } from "../protocol.js";
+import type { NodeSnapshot, LinkSnapshot, SubcatchmentSnapshot } from "../snapshots.js";
+import { Node, type NodeQualitySnapshot, type NodeStatisticsSnapshot } from "./nodes.js";
+import { Link, type LinkQualitySnapshot, type LinkStatisticsSnapshot } from "./links.js";
+import { Subcatchment, RainGage, type SubcatchmentQualitySnapshot, type SubcatchmentStatisticsSnapshot } from "./subcatchments.js";
+
+/**
+ * Configured-order handles with synchronous, case-insensitive ID lookup and stable identity.
+ * Obtain simulation collections from the owner rather than constructing a replacement view.
+ * All access checks the owner lifecycle; no access is valid after close.
+ * @typeParam T - Handle type returned by lookup and iteration.
+ */
+export class ObjectCollection<T> implements Iterable<T> {
+  readonly #ids: readonly string[];
+  readonly #byId: Map<string, string>;
+  readonly #views = new Map<string, T>();
+  readonly #create: (id: string) => T;
+  readonly #assertOpen: () => void;
+
+  /** Construct the shared collection implementation.
+   * @param ids - Canonical IDs in configured order; copied on construction.
+   * @param create - Factory called once per looked-up canonical ID.
+   * @param assertOpen - Lifecycle guard called before collection access.
+   */
+  constructor(ids: readonly string[], create: (id: string) => T, assertOpen: () => void) {
+    this.#ids = Object.freeze([...ids]);
+    this.#byId = new Map(ids.map((id) => [id.toLowerCase(), id]));
+    this.#create = create;
+    this.#assertOpen = assertOpen;
+  }
+  /** Canonical IDs in configured order; a frozen array. */
+  get ids(): readonly string[] { this.#assertOpen(); return this.#ids; }
+  /** Number of configured objects. */
+  get size(): number { this.#assertOpen(); return this.#ids.length; }
+  /** Test membership synchronously.
+   * @param id - Case-insensitive object ID.
+   * @returns Whether the ID is configured.
+   */
+  has(id: string): boolean { this.#assertOpen(); return this.#byId.has(id.toLowerCase()); }
+  /** Look up a stable handle synchronously.
+   * @param id - Case-insensitive object ID.
+   * @returns The same handle instance for repeated lookups of one canonical ID.
+   * @throws ObjectNotFoundError for an unknown ID; lifecycle errors after close.
+   */
+  get(id: string): T {
+    this.#assertOpen();
+    const canonical = this.#byId.get(id.toLowerCase());
+    if (canonical === undefined) throw new ObjectNotFoundError({ message: `Unknown object: ${id}`, code: 505, operation: "lookup" });
+    let view = this.#views.get(canonical);
+    if (view === undefined) { view = this.#create(canonical); this.#views.set(canonical, view); }
+    return view;
+  }
+  /** Look up a configured-order handle synchronously.
+   * @param index - Zero-based integer index; negative and fractional values are invalid.
+   * @returns The stable handle at the index.
+   * @throws RangeError for an out-of-range or noninteger index.
+   */
+  at(index: number): T {
+    this.#assertOpen();
+    const id = this.#ids[index];
+    if (!Number.isInteger(index) || id === undefined) throw new RangeError(`Object index out of range: ${index}`);
+    return this.get(id);
+  }
+  /** Iterate handles in configured order.
+   * @returns Synchronous iterator, checking the owner on each lookup.
+   */
+  *[Symbol.iterator](): IterableIterator<T> {
+    this.#assertOpen();
+    for (const id of this.#ids) yield this.get(id);
+  }
+}
+
+/** Owner-bound node handles. Snapshot selections preserve requested order; omit IDs for all nodes. */
+export class NodeCollection extends ObjectCollection<Node> {
+  readonly #call: Call;
+  private constructor(ids: readonly string[], call: Call, assertOpen: () => void) {
+    super(ids, (id) => Node.create(id, call), assertOpen); this.#call = call;
+  }
+  /** @internal */
+  static create(ids: readonly string[], call: Call, assertOpen: () => void): NodeCollection { return new NodeCollection(ids, call, assertOpen); }
+  /** Read node hydraulics in `running`, `complete`, or `ended`.
+   * @param ids - Ordered selection; omit for all, use [] for empty columns. Unknown or case-insensitive duplicate IDs reject.
+   * @returns Detached columns aligned with canonical `objectIds`, without a timestamp.
+   */
+  snapshot(ids?: readonly string[]): Promise<NodeSnapshot> { return this.#call("nodes", ids); }
+  /** Read node quality in `running`, `complete`, or `ended`.
+   * @param ids - Ordered IDs; omit for all or use [] for none. Unknown/duplicate IDs reject.
+   * @returns Detached pollutant-major matrices; inner rows follow `objectIds`.
+   */
+  qualitySnapshot(ids?: readonly string[]): Promise<NodeQualitySnapshot> { return this.#call("nodeQualitySnapshot", ids); }
+  /** Read cumulative node statistics in `running` or `complete`, before ending the run.
+   * @param ids - Ordered IDs; omit for all or use [] for none. Unknown/duplicate IDs reject.
+   * @returns Detached statistics columns aligned with canonical `objectIds`.
+   */
+  statisticsSnapshot(ids?: readonly string[]): Promise<NodeStatisticsSnapshot> { return this.#call("nodeStatisticsSnapshot", ids); }
+}
+/** Owner-bound link handles. Snapshot selections preserve requested order; omit IDs for all links. */
+export class LinkCollection extends ObjectCollection<Link> {
+  readonly #call: Call;
+  private constructor(ids: readonly string[], call: Call, assertOpen: () => void) {
+    super(ids, (id) => Link.create(id, call), assertOpen); this.#call = call;
+  }
+  /** @internal */
+  static create(ids: readonly string[], call: Call, assertOpen: () => void): LinkCollection { return new LinkCollection(ids, call, assertOpen); }
+  /** Read link hydraulics in `running`, `complete`, or `ended`.
+   * @param ids - Ordered IDs; omit for all or use [] for none. Unknown/duplicate IDs reject, including case-only duplicates.
+   * @returns Detached hydraulic columns aligned with canonical `objectIds`, without a timestamp.
+   */
+  snapshot(ids?: readonly string[]): Promise<LinkSnapshot> { return this.#call("links", ids); }
+  /** Read link quality in `running`, `complete`, or `ended`.
+   * @param ids - Ordered IDs; omit for all or use [] for none. Unknown/duplicate IDs reject.
+   * @returns Detached pollutant-major matrices; inner rows follow `objectIds`.
+   */
+  qualitySnapshot(ids?: readonly string[]): Promise<LinkQualitySnapshot> { return this.#call("linkQualitySnapshot", ids); }
+  /** Read cumulative link statistics in `running` or `complete`.
+   * @param ids - Ordered IDs; omit for all or use [] for none. Unknown/duplicate IDs reject.
+   * @returns Detached scalar columns; flow-class durations have one seven-value row per link.
+   */
+  statisticsSnapshot(ids?: readonly string[]): Promise<LinkStatisticsSnapshot> { return this.#call("linkStatisticsSnapshot", ids); }
+}
+/** Owner-bound subcatchment handles and aligned hydraulic, quality, and statistics reads. */
+export class SubcatchmentCollection extends ObjectCollection<Subcatchment> {
+  readonly #call: Call;
+  private constructor(ids: readonly string[], call: Call, assertOpen: () => void) {
+    super(ids, (id) => Subcatchment.create(id, call), assertOpen); this.#call = call;
+  }
+  /** @internal */
+  static create(ids: readonly string[], call: Call, assertOpen: () => void): SubcatchmentCollection { return new SubcatchmentCollection(ids, call, assertOpen); }
+  /** Read runoff results in `running`, `complete`, or `ended`.
+   * @param ids - Ordered IDs; omit for all or use [] for none. Unknown/duplicate IDs reject, including case-only duplicates.
+   * @returns Detached runoff columns aligned with canonical `objectIds`, without a timestamp.
+   */
+  snapshot(ids?: readonly string[]): Promise<SubcatchmentSnapshot> { return this.#call("subcatchments", ids); }
+  /** Read subcatchment quality in `running`, `complete`, or `ended`.
+   * @param ids - Ordered IDs; omit for all or use [] for none. Unknown/duplicate IDs reject.
+   * @returns Detached pollutant-major matrices; inner rows follow `objectIds`.
+   */
+  qualitySnapshot(ids?: readonly string[]): Promise<SubcatchmentQualitySnapshot> { return this.#call("subcatchmentQualitySnapshot", ids); }
+  /** Read cumulative runoff statistics in `running` or `complete`.
+   * @param ids - Ordered IDs; omit for all or use [] for none. Unknown/duplicate IDs reject.
+   * @returns Detached statistics columns aligned with canonical `objectIds`.
+   */
+  statisticsSnapshot(ids?: readonly string[]): Promise<SubcatchmentStatisticsSnapshot> { return this.#call("subcatchmentStatisticsSnapshot", ids); }
+}
+/** Owner-bound rain-gage handles. Rain gages provide per-object results, not collection snapshots. */
+export class RainGageCollection extends ObjectCollection<RainGage> {
+  private constructor(ids: readonly string[], call: Call, assertOpen: () => void) {
+    super(ids, (id) => RainGage.create(id, call), assertOpen);
+  }
+  /** @internal */
+  static create(ids: readonly string[], call: Call, assertOpen: () => void): RainGageCollection { return new RainGageCollection(ids, call, assertOpen); }
+}

package/src/swmmrs/objects/definitions.ts

@@ -0,0 +1,246 @@
+import type { Call } from "../protocol.js";
+
+/** Operations used by definition handles. Main extends the worker protocol with these entries. */
+export interface DefinitionOperations {
+  aquiferConfiguration: { args: [string]; result: AquiferConfiguration };
+  configureAquifer: { args: [string, AquiferPatch]; result: void };
+  snowmeltConfiguration: { args: [string]; result: SnowmeltParameterSetConfiguration };
+  configureSnowmelt: { args: [string, SnowmeltParameterSetPatch]; result: void };
+  snowmeltSurfaceConfiguration: { args: [string, SnowmeltSurfaceName]; result: SnowmeltSurfaceConfiguration };
+  configureSnowmeltSurface: {
+    args: [string, SnowmeltSurfaceName, SnowmeltSurfacePatch];
+    result: void;
+  };
+}
+
+/** Read-only identity for a configured definition. Generic handles do not expose editable curve/time-series data. */
+export class Definition {
+  /** Canonical configured definition ID. */
+  readonly id: string;
+  protected readonly call: Call;
+
+  protected constructor(id: string, call: Call) {
+    this.id = id;
+    this.call = call;
+    Object.freeze(this);
+  }
+
+  /** @internal */
+  static create(id: string, call: Call): Definition { return new Definition(id, call); }
+}
+
+/** Read-only pollutant identity handle. */
+export type Pollutant = Definition;
+/** Read-only land-use identity handle. */
+export type LandUse = Definition;
+/** Read-only time-pattern identity handle. */
+export type TimePattern = Definition;
+/** Read-only curve identity handle. */
+export type Curve = Definition;
+/** Read-only time-series identity handle. */
+export type TimeSeries = Definition;
+/** Read-only control-rule identity handle. */
+export type ControlRule = Definition;
+/** Read-only transect identity handle. */
+export type Transect = Definition;
+/** Read-only custom-shape identity handle. */
+export type CustomShape = Definition;
+/** Read-only street identity handle. */
+export type Street = Definition;
+/** Read-only inlet-design identity handle. */
+export type InletDesign = Definition;
+
+/** Detached aquifer declarations in configured project units. */
+export interface AquiferConfiguration {
+  /** Soil porosity fraction. */
+  readonly porosity: number;
+  /** Wilting-point moisture fraction. */
+  readonly wiltingPoint: number;
+  /** Field-capacity moisture fraction. */
+  readonly fieldCapacity: number;
+  /** Saturated hydraulic conductivity in project rainfall-rate units. */
+  readonly hydraulicConductivity: number;
+  /** Native conductivity-response slope. */
+  readonly conductivitySlope: number;
+  /** Tension-response slope in project length units (ft or m). */
+  readonly tensionSlope: number;
+  /** Fraction of evaporation drawn from the upper zone. */
+  readonly upperEvaporationFraction: number;
+  /** Lower-zone evaporation depth in project length units. */
+  readonly lowerEvaporationDepth: number;
+  /** Lower-zone loss coefficient in in/h or mm/h. */
+  readonly lowerLossCoefficient: number;
+  /** Aquifer bottom elevation in ft or m. */
+  readonly bottomElevation: number;
+  /** Initial water-table elevation in ft or m. */
+  readonly waterTableElevation: number;
+  /** Initial upper-zone moisture fraction. */
+  readonly upperMoisture: number;
+  /** Canonical upper-evaporation time-pattern ID, or null. */
+  readonly upperEvaporationPattern: string | null;
+}
+
+/** Sparse aquifer update; omitted fields retain their values. */
+export interface AquiferPatch {
+  /** {@inheritDoc AquiferConfiguration.porosity} */
+  porosity?: number;
+  /** {@inheritDoc AquiferConfiguration.wiltingPoint} */
+  wiltingPoint?: number;
+  /** {@inheritDoc AquiferConfiguration.fieldCapacity} */
+  fieldCapacity?: number;
+  /** {@inheritDoc AquiferConfiguration.hydraulicConductivity} */
+  hydraulicConductivity?: number;
+  /** {@inheritDoc AquiferConfiguration.conductivitySlope} */
+  conductivitySlope?: number;
+  /** {@inheritDoc AquiferConfiguration.tensionSlope} */
+  tensionSlope?: number;
+  /** {@inheritDoc AquiferConfiguration.upperEvaporationFraction} */
+  upperEvaporationFraction?: number;
+  /** {@inheritDoc AquiferConfiguration.lowerEvaporationDepth} */
+  lowerEvaporationDepth?: number;
+  /** {@inheritDoc AquiferConfiguration.lowerLossCoefficient} */
+  lowerLossCoefficient?: number;
+  /** {@inheritDoc AquiferConfiguration.bottomElevation} */
+  bottomElevation?: number;
+  /** {@inheritDoc AquiferConfiguration.waterTableElevation} */
+  waterTableElevation?: number;
+  /** {@inheritDoc AquiferConfiguration.upperMoisture} */
+  upperMoisture?: number;
+  /** Clear with null; omission retains the current relationship. */
+  upperEvaporationPattern?: string | null;
+}
+
+/** Editable aquifer handle obtained from `simulation.aquifers`. */
+export class Aquifer extends Definition {
+  private constructor(id: string, call: Call) { super(id, call); }
+
+  /** @internal */
+  static create(id: string, call: Call): Aquifer { return new Aquifer(id, call); }
+
+  /** Read aquifer declarations in any healthy owner state.
+   * @returns Detached aquifer configuration in project units.
+   */
+  configuration(): Promise<AquiferConfiguration> {
+    return this.call("aquiferConfiguration", this.id);
+  }
+
+  /** Atomically update aquifer declarations in `open` or `ended`; accepted edits return the owner to `open`.
+   * @param patch - Sparse field values; null clears the optional time-pattern relationship.
+   * @returns Resolves after all fields are accepted.
+   */
+  configure(patch: AquiferPatch): Promise<void> {
+    return this.call("configureAquifer", this.id, patch);
+  }
+}
+
+/** Snowmelt surface selector within a parameter set. */
+export type SnowmeltSurfaceName = "plowable" | "impervious" | "pervious";
+
+/** Detached snowmelt-surface declarations. */
+export interface SnowmeltSurfaceConfiguration {
+  /** Minimum melt coefficient in in/(h·°F) for US projects or mm/(h·°C) for SI projects. */
+  readonly minimumMeltCoefficient: number;
+  /** Maximum melt coefficient in in/(h·°F) for US projects or mm/(h·°C) for SI projects. */
+  readonly maximumMeltCoefficient: number;
+  /** Base melt temperature in °F for US projects or °C for SI projects. */
+  readonly baseTemperature: number;
+  /** Free-water holding-capacity fraction. */
+  readonly freeWaterFraction: number;
+  /** Initial snow water-equivalent depth in in or mm. */
+  readonly initialSnowDepth: number;
+  /** Initial free-water depth in in or mm. */
+  readonly initialFreeWater: number;
+  /** Snow water-equivalent depth for full coverage in in or mm. */
+  readonly snowDepthForFullCoverage: number;
+}
+
+/** Sparse snowmelt-surface update; omission retains a field. */
+export interface SnowmeltSurfacePatch {
+  /** {@inheritDoc SnowmeltSurfaceConfiguration.minimumMeltCoefficient} */
+  minimumMeltCoefficient?: number;
+  /** {@inheritDoc SnowmeltSurfaceConfiguration.maximumMeltCoefficient} */
+  maximumMeltCoefficient?: number;
+  /** {@inheritDoc SnowmeltSurfaceConfiguration.baseTemperature} */
+  baseTemperature?: number;
+  /** {@inheritDoc SnowmeltSurfaceConfiguration.freeWaterFraction} */
+  freeWaterFraction?: number;
+  /** {@inheritDoc SnowmeltSurfaceConfiguration.initialSnowDepth} */
+  initialSnowDepth?: number;
+  /** {@inheritDoc SnowmeltSurfaceConfiguration.initialFreeWater} */
+  initialFreeWater?: number;
+  /** {@inheritDoc SnowmeltSurfaceConfiguration.snowDepthForFullCoverage} */
+  snowDepthForFullCoverage?: number;
+}
+
+/** Detached snowmelt parameter set with all three surface records. */
+export interface SnowmeltParameterSetConfiguration {
+  /** Plowable fraction of impervious area. */
+  readonly plowableFraction: number;
+  /** Plowable-surface melt parameters. */
+  readonly plowable: SnowmeltSurfaceConfiguration;
+  /** Impervious-surface melt parameters. */
+  readonly impervious: SnowmeltSurfaceConfiguration;
+  /** Pervious-surface melt parameters. */
+  readonly pervious: SnowmeltSurfaceConfiguration;
+  /** Snow water-equivalent depth triggering plowing, in in or mm. */
+  readonly plowDepth: number;
+  /** Five removal fractions in native solver destination order. */
+  readonly removalFractions: readonly [number, number, number, number, number];
+  /** Canonical receiving subcatchment ID, or null. */
+  readonly removalSubcatchment: string | null;
+}
+
+/** Sparse parameter-set update; use `configureSurface` for individual surface parameters. */
+export interface SnowmeltParameterSetPatch {
+  /** {@inheritDoc SnowmeltParameterSetConfiguration.plowableFraction} */
+  plowableFraction?: number;
+  /** {@inheritDoc SnowmeltParameterSetConfiguration.plowDepth} */
+  plowDepth?: number;
+  /** {@inheritDoc SnowmeltParameterSetConfiguration.removalFractions} */
+  removalFractions?: readonly [number, number, number, number, number];
+  /** Clear with null; omission retains the current relationship. */
+  removalSubcatchment?: string | null;
+}
+
+/** Editable snowmelt parameter-set identity handle. */
+export class SnowmeltParameterSet extends Definition {
+  private constructor(id: string, call: Call) { super(id, call); }
+
+  /** @internal */
+  static create(id: string, call: Call): SnowmeltParameterSet {
+    return new SnowmeltParameterSet(id, call);
+  }
+
+  /** Read all parameter-set declarations in a healthy owner state.
+   * @returns Detached parameter set with three surface records.
+   */
+  configuration(): Promise<SnowmeltParameterSetConfiguration> {
+    return this.call("snowmeltConfiguration", this.id);
+  }
+
+  /** Atomically update set-level declarations in `open` or `ended`; accepted edits return the owner to `open`.
+   * @param patch - Sparse set fields; null clears the optional receiving-subcatchment relation.
+   * @returns Resolves after the update is accepted.
+   */
+  configure(patch: SnowmeltParameterSetPatch): Promise<void> {
+    return this.call("configureSnowmelt", this.id, patch);
+  }
+
+  /** Read one surface in a healthy owner state.
+   * @param surface - Plowable, impervious, or pervious surface selector.
+   * @returns Detached surface parameters.
+   */
+  surfaceConfiguration(surface: SnowmeltSurfaceName): Promise<SnowmeltSurfaceConfiguration> {
+    return this.call("snowmeltSurfaceConfiguration", this.id, surface);
+  }
+
+  /** Atomically update one surface in `open` or `ended`; accepted edits return the owner to `open`.
+   * @param surface - Surface to update.
+   * @param patch - Sparse surface values; omitted fields retain their values.
+   * @returns Resolves after all supplied fields are accepted.
+   */
+  configureSurface(surface: SnowmeltSurfaceName, patch: SnowmeltSurfacePatch): Promise<void> {
+    return this.call("configureSnowmeltSurface", this.id, surface, patch);
+  }
+}
+