Node

Node provides declaration edits, current results, runtime forcings, and statistics for one node. Obtain a handle from simulation.nodes.get(id).

See the user guide for configuration workflows, runtime forcings, and collecting results and statistics.

Node

Owner-bound node handle obtained with simulation.nodes.get(id).

The constructor is private. Use NodeConfiguration.kind to distinguish junctions, storage nodes, outfalls, and dividers; there are no public subtype classes. Reads return detached, frozen records. Mutations require explicit methods, not assignments to those records.

Operations reject when the owner is closed or failed, or the requested operation is invalid for its lifecycle state or node kind. Wrong-kind calls do not mutate the model. Read statistics before ending the run; hydraulic and quality reads remain available in ended.

Properties

id

readonly id: string;

Canonical configured node ID.

Methods

results()

results(): Promise<NodeResults>;

Read current hydraulics in running, complete, or ended.

Returns

Promise<NodeResults>

A detached NodeResults record in project units, not a time series.

configuration()

configuration(): Promise<NodeConfiguration>;

Read common and kind-specific declarations in any healthy owner state.

Returns

Promise<NodeConfiguration>

A detached NodeConfiguration; non-applicable subtype fields are null.

configure()

configure(patch: NodePatch): Promise<void>;

Atomically update declarations in open or ended. An accepted edit in ended returns the owner to open.

Parameters

Parameter	Type	Description
`patch`	`NodePatch`	Sparse NodePatch. Omitted top-level fields retain their values.

Returns

Promise<void>

Resolves after the complete patch is accepted.

Throws

Rejects for an invalid patch, wrong node kind, or invalid lifecycle state; no part of a rejected patch is applied.

Example

import type { Node } from "@swmmrs/swmmrs";
declare const node: Node;
await node.configure({ fullDepth: 4.5, initialDepth: 0.25 });

externalInflow()

externalInflow(): Promise<number>;

Read the persistent additive API inflow in any healthy owner state.

Returns

Promise<number>

Inflow in project flow units, excluding other inflow sources.

setExternalInflow()

setExternalInflow(flow: number): Promise<void>;

Set persistent additive API inflow in open, running, or ended.

Parameters

Parameter	Type	Description
`flow`	`number`	Inflow in project flow units. Zero removes the API contribution.

Returns

Promise<void>

Resolves after the forcing is updated.

setOutfallStage()

setOutfallStage(stage: number): Promise<void>;

Set a persistent fixed-stage override in open, running, or ended. This runtime forcing is separate from NodePatch.boundary.

Parameters

Parameter	Type	Description
`stage`	`number`	Outfall boundary elevation in project length units (ft or m).

Returns

Promise<void>

Resolves after the forcing is updated.

Throws

Rejects for a non-outfall node or an invalid stage or lifecycle state.

fixedStage()

fixedStage(): Promise<number | null>;

Read the effective fixed stage in any healthy owner state; outfalls only.

Returns

Promise<number | null>

Runtime override if set, otherwise the declared fixed stage, in project length units; null when neither supplies a fixed stage.

Throws

Rejects for a non-outfall node.

quality()

quality(): Promise<NodeQuality>;

Read current pollutant concentrations in running, complete, or ended.

Returns

Promise<NodeQuality>

Detached NodeQuality arrays aligned with their pollutant IDs.

overridePollutantConcentrations()

overridePollutantConcentrations(values: PollutantValues): Promise<void>;

Queue concentration overrides for the next quality-routing step; requires running. The override expires after that step rather than becoming a persistent forcing.

Parameters

Parameter	Type	Description
`values`	`PollutantValues`	Sparse pollutant-ID map of nonnegative concentrations in each pollutant's configured concentration units.

Returns

Promise<void>

Resolves after the overrides are queued.

Throws

Rejects invalid IDs, concentrations, or lifecycle states.

externalPollutantMassFlux()

externalPollutantMassFlux(): Promise<Readonly<Record<string, number>>>;

Read persistent external pollutant mass fluxes in open, running, or ended.

Returns

Promise<Readonly<Record<string, number>>>

A detached PollutantValues map in configured pollutant mass-flux units.

externalPollutantMassFluxValue()

externalPollutantMassFluxValue(pollutantId: string): Promise<number>;

Read one persistent external mass flux in open, running, or ended.

Parameters

Parameter	Type	Description
`pollutantId`	`string`	Configured pollutant ID.

Returns

Promise<number>

The pollutant's external mass flux in its configured mass-flux units.

Throws

Rejects an unknown pollutant ID or invalid lifecycle state.

updateExternalPollutantMassFlux()

updateExternalPollutantMassFlux(values: PollutantValues, replace?: boolean): Promise<void>;

Update persistent external pollutant mass fluxes in open, running, or ended.

Parameters

Parameter	Type	Default value	Description
`values`	`PollutantValues`	`undefined`	Sparse pollutant-ID map in configured pollutant mass-flux units.
`replace`	`boolean`	`false`	Defaults to `false`: merge supplied IDs. With `true`, replace the complete mapping and reset omitted pollutants to zero.

Returns

Promise<void>

Resolves after the atomic update.

Throws

Rejects invalid pollutant IDs, values, or lifecycle states.

clearExternalPollutantMassFlux()

clearExternalPollutantMassFlux(): Promise<void>;

Reset all persistent external pollutant mass fluxes to zero. Requires open, running, or ended; equivalent to updateExternalPollutantMassFlux({}, true).

Returns

Promise<void>

Resolves after the complete mapping is cleared.

statistics()

statistics(): Promise<NodeStatistics>;

Read cumulative node statistics in running or complete, before ending the run.

Returns

Promise<NodeStatistics>

A detached NodeStatistics record for the current run.

storageStatistics()

storageStatistics(): Promise<StorageStatistics>;

Read storage-only statistics in running or complete.

Returns

Promise<StorageStatistics>

A detached StorageStatistics record for the current run.

Throws

Rejects for a non-storage node or invalid lifecycle state.

outfallStatistics()

outfallStatistics(): Promise<OutfallStatistics>;

Read outfall-only statistics in running or complete.

Returns

Promise<OutfallStatistics>

A detached OutfallStatistics record for the current run.

Throws

Rejects for a non-outfall node or invalid lifecycle state.

totalInflowVolume()

totalInflowVolume(): Promise<number>;

Read cumulative total inflow volume in running or complete.

Returns

Promise<number>

Volume in project volume units (ft³ or m³), not a flow rate.

StorageShape

Canonical storage-shape declaration returned by Node.configuration.

Properties

Property	Modifier	Type	Description
`kind`	`readonly`	`StorageShapeKind`	Functional, tabular, or geometric shape selector.
`coefficients`	`readonly`	readonly [`number`, `number`, `number`]	Three canonical shape coefficients; interpretation depends on kind.
`curve`	`readonly`	`string` \| `null`	Canonical storage-curve ID for a tabular shape; otherwise `null`.

StorageShapePatch

Replacement storage shape supplied through NodePatch.shape.

Properties

Property	Modifier	Type	Description
`kind`	`readonly`	`StorageShapeKind`	Shape to install; required even when only coefficients change.
`coefficients?`	`readonly`	readonly [`number`, `number`, `number`]	Shape coefficients, defaulting to `[0, 0, 0]`. Must be zero for a tabular shape.
`curve?`	`readonly`	`string` \| `null`	Storage-curve ID, required for a tabular shape.

StorageExfiltration

Storage seepage or Green-Ampt exfiltration parameters.

Properties

Property	Modifier	Type	Description
`conductivity`	`readonly`	`number`	Saturated hydraulic conductivity in project infiltration-rate units (in/h or mm/h).
`suctionHead`	`readonly`	`number`	Suction head in project rainfall-depth units (in or mm).
`moistureDeficit`	`readonly`	`number`	Initial moisture deficit as a dimensionless fraction.

StorageExfiltrationPatch

Replacement exfiltration parameters; zero suction and deficit select seepage.

Properties

Property	Modifier	Type	Description
`conductivity`	`readonly`	`number`	Saturated hydraulic conductivity in project infiltration-rate units (in/h or mm/h).
`suctionHead?`	`readonly`	`number`	Suction head in in or mm; defaults to zero.
`moistureDeficit?`	`readonly`	`number`	Initial moisture-deficit fraction; defaults to zero.

OutfallBoundary

Outfall boundary declaration, not the current runtime override.

Properties

Property	Modifier	Type	Description
`kind`	`readonly`	`OutfallBoundaryKind`	Boundary model.
`stage`	`readonly`	`number`	Fixed-stage elevation in project length units.
`reference`	`readonly`	`string` \| `null`	Canonical tidal-curve or time-series ID; `null` for other boundary kinds.

OutfallBoundaryPatch

Replacement outfall boundary supplied through NodePatch.boundary.

Properties

Property	Modifier	Type	Description
`kind`	`readonly`	`OutfallBoundaryKind`	Boundary model to install.
`stage?`	`readonly`	`number`	Fixed-stage elevation in project length units; defaults to zero for `fixed`.
`reference?`	`readonly`	`string` \| `null`	Required curve ID for `tidal`, or time-series ID for `timeseries`.

DividerRule

Canonical divider declaration returned by Node.configuration.

Properties

Property	Modifier	Type	Description
`kind`	`readonly`	`DividerRuleKind`	Flow-diversion rule.
`values`	`readonly`	readonly [`number`, `number`, `number`]	Minimum flow, maximum head, and discharge coefficient; applicability depends on the rule.
`curve`	`readonly`	`string` \| `null`	Canonical diversion-curve ID for `tabular`; otherwise `null`.

DividerRulePatch

Replacement divider rule supplied through NodePatch.rule.

Properties

Property	Modifier	Type	Description
`kind`	`readonly`	`DividerRuleKind`	Flow-diversion rule to install.
`values?`	`readonly`	readonly [`number`, `number`, `number`]	Rule values, defaulting to zeros. `cutoff` accepts only minimum flow; `tabular` requires zeros.
`curve?`	`readonly`	`string` \| `null`	Diversion-curve ID, required for `tabular`.

NodePatch

Sparse, atomic declaration update accepted by Node.configure.

Omitted top-level fields retain their values. Nested shape, exfiltration, boundary, and rule records replace that declaration rather than merging it. Kind-specific fields require the corresponding node kind. Runtime forcings, results, and the node ID are not accepted here.

Properties

Property	Modifier	Type	Description
`tag?`	`readonly`	`string`	Object tag.
`invertElevation?`	`readonly`	`number`	Invert elevation in project length units (ft or m).
`fullDepth?`	`readonly`	`number`	Full depth above the invert in project length units.
`surchargeDepth?`	`readonly`	`number`	Additional surcharge depth in project length units.
`pondedArea?`	`readonly`	`number`	Ponding area in project length squared (ft² or m²).
`initialDepth?`	`readonly`	`number`	Initial water depth in project length units.
`includedInReport?`	`readonly`	`boolean`	Whether this node is selected for detailed reporting.
`shape?`	`readonly`	`StorageShapePatch`	Replacement storage area/depth relationship; storage nodes only.
`evaporationFraction?`	`readonly`	`number`	Storage evaporation fraction; storage nodes only.
`exfiltration?`	`readonly`	`StorageExfiltrationPatch` \| `null`	Replacement storage exfiltration parameters; `null` disables exfiltration.
`boundary?`	`readonly`	`OutfallBoundaryPatch`	Replacement declared boundary; outfalls only.
`hasFlapGate?`	`readonly`	`boolean`	Whether reverse flow is blocked; outfalls only.
`routeToSubcatchment?`	`readonly`	`string` \| `null`	Receiving subcatchment ID for an outfall; `null` clears the relation.
`rule?`	`readonly`	`DividerRulePatch`	Replacement flow-diversion rule; dividers only.
`divertedLink?`	`readonly`	`string` \| `null`	Diverted link ID for a divider; `null` clears the relation.

NodeConfiguration

Detached, read-only node declarations returned by Node.configuration. Subtype fields are null when they do not apply to this node kind.

Properties

Property	Modifier	Type	Description
`kind`	`readonly`	`NodeKind`	Configured node kind; handles do not have public subtype subclasses.
`tag`	`readonly`	`string`	Object tag.
`invertElevation`	`readonly`	`number`	Invert elevation in project length units (ft or m).
`fullDepth`	`readonly`	`number`	Full depth above the invert in project length units.
`surchargeDepth`	`readonly`	`number`	Additional surcharge depth in project length units.
`pondedArea`	`readonly`	`number`	Ponding area in project length squared (ft² or m²).
`initialDepth`	`readonly`	`number`	Initial water depth in project length units.
`includedInReport`	`readonly`	`boolean`	Whether this node is selected for detailed reporting.
`externalInflow`	`readonly`	`number`	Persistent additive API inflow in project flow units; set with Node.setExternalInflow.
`shape`	`readonly`	`StorageShape` \| `null`	Storage area/depth relationship; `null` for other node kinds.
`evaporationFraction`	`readonly`	`number` \| `null`	Storage evaporation fraction; `null` for other node kinds.
`exfiltration`	`readonly`	`StorageExfiltration` \| `null`	Storage exfiltration parameters; `null` when absent or not applicable.
`boundary`	`readonly`	`OutfallBoundary` \| `null`	Declared outfall boundary; `null` for other node kinds.
`hasFlapGate`	`readonly`	`boolean` \| `null`	Outfall reverse-flow flap gate; `null` for other node kinds.
`routeToSubcatchment`	`readonly`	`string` \| `null`	Canonical receiving-subcatchment ID for an outfall; `null` when unset or not applicable.
`rule`	`readonly`	`DividerRule` \| `null`	Divider flow-diversion rule; `null` for other node kinds.
`divertedLink`	`readonly`	`string` \| `null`	Canonical diverted-link ID for a divider; `null` when unset or not applicable.

NodeQuality

Detached current concentrations, in each pollutant's configured concentration units.

Properties

Property	Modifier	Type	Description
`pollutantIds`	`readonly`	readonly `string`[]	Canonical pollutant IDs defining the order of every concentration array.
`concentrations`	`readonly`	readonly `number`[]	Current node concentrations, aligned with pollutantIds.
`inflowConcentrations`	`readonly`	readonly `number`[]	Current inflow concentrations, aligned with pollutantIds.
`reactorConcentrations`	`readonly`	readonly `number`[]	Current reactor concentrations, aligned with pollutantIds.

NodeQualitySnapshot

Detached quality snapshot returned by simulation.nodes.qualitySnapshot(ids). Matrices are pollutant-major: [pollutantIndex][objectIndex]. Concentrations use each pollutant's configured concentration units.

Properties

Property	Modifier	Type	Description
`objectIds`	`readonly`	readonly `string`[]	Canonical node IDs in selection order, defining each matrix's inner dimension.
`pollutantIds`	`readonly`	readonly `string`[]	Canonical pollutant IDs defining each matrix's outer dimension.
`concentrations`	`readonly`	readonly (readonly `number`[])[]	Current node concentrations.
`inflowConcentrations`	`readonly`	readonly (readonly `number`[])[]	Current inflow concentrations.
`reactorConcentrations`	`readonly`	readonly (readonly `number`[])[]	Current reactor concentrations.

NodeStatistics

Detached cumulative statistics for the current run, read with Node.statistics.

Properties

Property	Modifier	Type	Description
`averageDepth`	`readonly`	`number`	Average reported depth in project length units; zero before reporting samples exist.
`maximumDepth`	`readonly`	`number`	Maximum depth in project length units.
`maximumDepthTime`	`readonly`	`string`	Model calendar time of maximum depth, without a timezone.
`maximumReportedDepth`	`readonly`	`number`	Maximum reported depth in project length units.
`floodedVolume`	`readonly`	`number`	Cumulative flooded volume in project volume units (ft³ or m³).
`timeFloodedSeconds`	`readonly`	`number`	Cumulative time flooded, in seconds.
`timeSurchargedSeconds`	`readonly`	`number`	Cumulative time surcharged, in seconds.
`timeCourantCriticalSeconds`	`readonly`	`number`	Cumulative time Courant-critical, in seconds.
`totalLateralInflow`	`readonly`	`number`	Cumulative lateral inflow volume in project volume units, not a flow rate.
`maximumLateralInflow`	`readonly`	`number`	Maximum lateral inflow in project flow units.
`maximumInflow`	`readonly`	`number`	Maximum total inflow in project flow units.
`maximumOverflow`	`readonly`	`number`	Maximum overflow in project flow units.
`maximumPondedVolume`	`readonly`	`number`	Maximum ponded volume in project volume units.
`nonconvergedCount`	`readonly`	`number`	Number of nonconverged routing steps.
`maximumInflowTime`	`readonly`	`string`	Model calendar time of maximum inflow, without a timezone.
`maximumOverflowTime`	`readonly`	`string`	Model calendar time of maximum overflow, without a timezone.

StorageStatistics

Detached storage-only cumulative statistics, read with Node.storageStatistics.

Properties

Property	Modifier	Type	Description
`initialVolume`	`readonly`	`number`	Initial stored volume in project volume units (ft³ or m³).
`averageVolume`	`readonly`	`number`	Average reported volume in project volume units; zero before reporting samples exist.
`maximumVolume`	`readonly`	`number`	Maximum stored volume in project volume units.
`maximumInflow`	`readonly`	`number`	Maximum inflow in project flow units.
`evaporationLosses`	`readonly`	`number`	Cumulative evaporated volume in project volume units.
`exfiltrationLosses`	`readonly`	`number`	Cumulative exfiltrated volume in project volume units.
`maximumVolumeTime`	`readonly`	`string`	Model calendar time of maximum volume, without a timezone.

OutfallStatistics

Detached outfall-only cumulative statistics, read with Node.outfallStatistics.

Properties

Property	Modifier	Type	Description
`averageFlow`	`readonly`	`number`	Average discharge in project flow units; zero before discharge periods exist.
`maximumFlow`	`readonly`	`number`	Maximum discharge in project flow units.
`pollutantLoads`	`readonly`	`Readonly`<`Record`<`string`, `number`>>	Cumulative discharged loads keyed by canonical pollutant ID, in configured load units.
`periodCount`	`readonly`	`number`	Number of discharge periods used for the average.

NodeStatisticsSnapshot

Detached cumulative statistics from simulation.nodes.statisticsSnapshot(ids). Every column follows objectIds; values and units match NodeStatistics.

Properties

Property	Modifier	Type	Description
`objectIds`	`readonly`	readonly `string`[]	Canonical node IDs in selection order.
`averageDepth`	`readonly`	readonly `number`[]	Average reported depth in project length units; zero before reporting samples exist.
`maximumDepth`	`readonly`	readonly `number`[]	Maximum depth in project length units.
`maximumDepthTime`	`readonly`	readonly `string`[]	Model calendar time of maximum depth, without a timezone.
`maximumReportedDepth`	`readonly`	readonly `number`[]	Maximum reported depth in project length units.
`floodedVolume`	`readonly`	readonly `number`[]	Cumulative flooded volume in project volume units (ft³ or m³).
`timeFloodedSeconds`	`readonly`	readonly `number`[]	Cumulative time flooded, in seconds.
`timeSurchargedSeconds`	`readonly`	readonly `number`[]	Cumulative time surcharged, in seconds.
`timeCourantCriticalSeconds`	`readonly`	readonly `number`[]	Cumulative time Courant-critical, in seconds.
`totalLateralInflow`	`readonly`	readonly `number`[]	Cumulative lateral inflow volume in project volume units, not a flow rate.
`maximumLateralInflow`	`readonly`	readonly `number`[]	Maximum lateral inflow in project flow units.
`maximumInflow`	`readonly`	readonly `number`[]	Maximum total inflow in project flow units.
`maximumOverflow`	`readonly`	readonly `number`[]	Maximum overflow in project flow units.
`maximumPondedVolume`	`readonly`	readonly `number`[]	Maximum ponded volume in project volume units.
`nonconvergedCount`	`readonly`	readonly `number`[]	Number of nonconverged routing steps.
`maximumInflowTime`	`readonly`	readonly `string`[]	Model calendar time of maximum inflow, without a timezone.
`maximumOverflowTime`	`readonly`	readonly `string`[]	Model calendar time of maximum overflow, without a timezone.

NodeResults

Detached current node hydraulics returned by node.results(). Values are frozen copies, not live worker views or report-period time series.

Properties

Property	Modifier	Type	Description
`depth`	`readonly`	`number`	Water depth above the invert in project length units (ft or m).
`head`	`readonly`	`number`	Hydraulic head in project elevation units (ft or m).
`volume`	`readonly`	`number`	Stored water volume in project volume units (ft³ or m³).
`lateralInflow`	`readonly`	`number`	Current lateral inflow in project flow units.
`totalInflow`	`readonly`	`number`	Current total inflow in project flow units.
`totalOutflow`	`readonly`	`number`	Current total outflow in project flow units.
`losses`	`readonly`	`number`	Current loss rate in project flow units.
`flooding`	`readonly`	`number`	Current flooding rate in project flow units.
`hydraulicRetentionSeconds`	`readonly`	`number` \| `null`	Storage-node hydraulic retention time in seconds; `null` for other node kinds.

StorageShapeKind

type StorageShapeKind = 
  | "functional"
  | "tabular"
  | "cylindrical"
  | "conical"
  | "paraboloid"
  | "pyramidal";

Storage area/depth relationship represented by StorageShape.

OutfallBoundaryKind

type OutfallBoundaryKind = "free" | "normal" | "fixed" | "tidal" | "timeseries";

Declared outfall boundary model; separate from a runtime stage override.

DividerRuleKind

type DividerRuleKind = "overflow" | "cutoff" | "tabular" | "weir";

Flow-diversion rule used by a divider node.

PollutantValues

type PollutantValues = Readonly<Record<string, number>>;

Pollutant-ID-to-value mapping. Concentration overrides use configured concentration units; external mass fluxes use configured pollutant mass per project time units. Inputs may be sparse. Returned mappings are detached and read-only.