Binary output

Source-generated reference for the standalone output reader, metadata, selectors, and report-period series. See Read binary output for workflows and Exceptions for simulation errors.

OutputName

Lossless stored output name, retaining bytes even when UTF-8 decoding fails.

Constructors

Constructor

new OutputName(raw: ArrayLike<number>): OutputName;

Copy an exact stored name byte sequence.

Parameters

Parameter	Type	Description
`raw`	`ArrayLike`<`number`>	Byte values copied into owned storage.

Returns

OutputName

Properties

text

readonly text: string | null;

Decoded UTF-8 text, or null for invalid UTF-8. A leading byte-order mark is preserved.

Accessors

raw

Get Signature

get raw(): Uint8Array;

Return a defensive copy of the exact stored name bytes.

Returns

Uint8Array

ReportTiming

Fixed report schedule and available complete-period count.

Constructors

Constructor

new ReportTiming(
   reportScheduleOrigin: number, 
   reportStepSeconds: number, 
   periodCount: number
): ReportTiming;

Construct report timing, normally obtained from reader metadata.

Parameters

Parameter	Type	Description
`reportScheduleOrigin`	`number`	SWMM serial-day schedule origin.
`reportStepSeconds`	`number`	Report interval in seconds.
`periodCount`	`number`	Available complete-period count.

Returns

ReportTiming

Properties

reportScheduleOrigin

readonly reportScheduleOrigin: number;

Nominal schedule origin in SWMM serial days, not an epoch-millisecond timestamp.

reportStepSeconds

readonly reportStepSeconds: number;

Fixed interval between report periods in seconds.

periodCount

readonly periodCount: number;

Number of available complete periods.

Methods

nominalDate()

nominalDate(period: number): string | null;

Return the rounded timezone-free nominal date, not the exact stored serial-day value.

Parameters

Parameter	Type	Description
`period`	`number`	Zero-based integer period index; period zero is one report step after the origin.

Returns

string | null

Nominal date, or null if the integer is outside the available range.

Throws

TypeError when the index is not an integer.

BulkSeriesResult

Immutable column-oriented result for an ordered bulk request.

Constructors

Constructor

new BulkSeriesResult(times: readonly string[], series: readonly OutputValueSeries[]): BulkSeriesResult;

Copy the outer axis and column arrays; normally constructed by the reader with immutable, aligned columns.

Parameters

Parameter	Type	Description
`times`	readonly `string`[]	Shared nominal date axis.
`series`	readonly `OutputValueSeries`[]	Selection-labelled columns aligned to that axis.

Returns

BulkSeriesResult

Properties

times

readonly times: readonly string[];

Shared rounded nominal dates for the selected period range.

series

readonly series: readonly OutputValueSeries[];

Columns in requested selection order, including duplicates.

Methods

value()

value(periodOffset: number, selectionOffset: number): number;

Read one value using offsets local to this result, not absolute file periods.

Parameters

Parameter	Type	Description
`periodOffset`	`number`	Zero-based offset into `times`.
`selectionOffset`	`number`	Zero-based offset into `series`.

Returns

number

Selected value in stored output units.

Throws

RangeError if either offset is non-integral or out of range.

OutputError

Structured output-reader failure preserved across the worker boundary.

Extends

Error

Constructors

Constructor

new OutputError(
   category: string, 
   message: string, 
   operation?: string
): OutputError;

Construct a structured reader error.

Parameters

Parameter	Type	Description
`category`	`string`	Failure classification.
`message`	`string`	Human-readable diagnostic.
`operation?`	`string`	Optional operation context; omitted when unavailable.

Returns

OutputError

Overrides

Error.constructor

Properties

operation

readonly operation: string | undefined;

Failing reader operation when available.

cause?

optional cause?: unknown;

Inherited from

Error.cause

name

name: string;

Inherited from

Error.name

message

message: string;

Inherited from

Error.message

stack?

optional stack?: string;

Inherited from

Error.stack

OutputReader

Byte-owned standalone output reader with its own worker, independent of Simulation. Always await close(); copied results and metadata remain usable afterward.

Implements

AsyncDisposable

Properties

metadata

readonly metadata: OutputMetadata;

Immutable parsed metadata, available without another worker query.

Accessors

isFinalized

Get Signature

get isFinalized(): boolean;

True when the opened bytes contained a valid finalized trailer.

Returns

boolean

times

Get Signature

get times(): readonly string[];

Lazily derive the shared nominal report-date axis from validated metadata.

Returns

readonly string[]

Methods

open()

static open(input: FileContents, options?: OutputReaderOptions): Promise<OutputReader>;

Open finalized or incomplete SWMM output in an independent worker.

Parameters

Parameter	Type	Description
`input`	`FileContents`	File contents, never a host path. In Node, pass bytes from `fs.readFile`.
`options`	`OutputReaderOptions`	Worker asset override; defaults to the bundled worker.

Returns

Promise<OutputReader>

Reader with immutable validated metadata and available complete periods.

Throws

OutputError for invalid output; a worker created during a failed open is stopped.

readBulkSeries()

readBulkSeries(selections: readonly SeriesSelection[], options?: OutputReadOptions): Promise<BulkSeriesResult>;

Read ordered selections; duplicates remain repeated columns and empty dimensions are preserved.

Parameters

Parameter	Type	Description
`selections`	readonly `SeriesSelection`[]	Family-compatible element/attribute selections in desired column order.
`options`	`OutputReadOptions`	Half-open range and I/O strategy; defaults to all periods and whole-period reads.

Returns

Promise<BulkSeriesResult>

Detached immutable columns sharing one nominal date axis.

Throws

OutputError for missing/ambiguous elements, absent attributes, or invalid ranges; TypeError/RangeError for malformed selectors. Reads after close reject with LifecycleError.

Example

import type { OutputReader } from "@swmmrs/swmmrs";
declare const reader: OutputReader;
const result = await reader.readBulkSeries([
  { elementType: "node", element: "J1", attribute: "hydraulic_head" },
], { start: 0, end: 24, lowMemory: true });
console.log(result.times, result.series[0]?.values);

subcatchmentSeries()

subcatchmentSeries(
   element: OutputElementSelector, 
   attribute: 
  | ResultAttributeCode
  | PollutantAttribute
  | SubcatchmentResultAttribute, 
   options?: OutputReadOptions
): Promise<OutputTimeSeries>;

Read one subcatchment column with the validation and lifecycle contract of readBulkSeries.

Parameters

Parameter	Type	Description
`element`	`OutputElementSelector`	Zero-based index or exact stored name selector.
`attribute`	\| `ResultAttributeCode` \| `PollutantAttribute` \| `SubcatchmentResultAttribute`	Subcatchment attribute, pollutant, or stored result code.
`options`	`OutputReadOptions`	Half-open range and I/O strategy; defaults to all periods and whole-period reads.

Returns

Promise<OutputTimeSeries>

Immutable selection, nominal dates, and aligned values.

nodeSeries()

nodeSeries(
   element: OutputElementSelector, 
   attribute: 
  | ResultAttributeCode
  | PollutantAttribute
  | NodeResultAttribute, 
   options?: OutputReadOptions
): Promise<OutputTimeSeries>;

Read one node column with the validation and lifecycle contract of readBulkSeries.

Parameters

Parameter	Type	Description
`element`	`OutputElementSelector`	Zero-based index or exact stored name selector.
`attribute`	\| `ResultAttributeCode` \| `PollutantAttribute` \| `NodeResultAttribute`	Node attribute, pollutant, or stored result code.
`options`	`OutputReadOptions`	Half-open range and I/O strategy; defaults to all periods and whole-period reads.

Returns

Promise<OutputTimeSeries>

Immutable selection, nominal dates, and aligned values.

linkSeries()

linkSeries(
   element: OutputElementSelector, 
   attribute: 
  | ResultAttributeCode
  | PollutantAttribute
  | LinkResultAttribute, 
   options?: OutputReadOptions
): Promise<OutputTimeSeries>;

Read one link column with the validation and lifecycle contract of readBulkSeries.

Parameters

Parameter	Type	Description
`element`	`OutputElementSelector`	Zero-based index or exact stored name selector.
`attribute`	\| `ResultAttributeCode` \| `PollutantAttribute` \| `LinkResultAttribute`	Link attribute, pollutant, or stored result code.
`options`	`OutputReadOptions`	Half-open range and I/O strategy; defaults to all periods and whole-period reads.

Returns

Promise<OutputTimeSeries>

Immutable selection, nominal dates, and aligned values.

systemSeries()

systemSeries(attribute: 
  | ResultAttributeCode
  | SystemResultAttribute, options?: OutputReadOptions): Promise<OutputTimeSeries>;

Read one system column with the validation and lifecycle contract of readBulkSeries.

Parameters

Parameter	Type	Description
`attribute`	\| `ResultAttributeCode` \| `SystemResultAttribute`	System attribute or stored result code; pollutants are not supported.
`options`	`OutputReadOptions`	Half-open range and I/O strategy; defaults to all periods and whole-period reads.

Returns

Promise<OutputTimeSeries>

Immutable selection with null element, nominal dates, and aligned values.

readStoredDates()

readStoredDates(options?: OutputRange): Promise<readonly number[]>;

Read exact stored report dates rather than the rounded nominal date axis; requires an open reader.

Parameters

Parameter	Type	Description
`options`	`OutputRange`	Half-open period/date bounds; defaults to all complete periods.

Returns

Promise<readonly number[]>

Immutable SWMM serial-day values read from the output bytes.

Throws

OutputError for invalid ranges or unreadable output; LifecycleError after close.

close()

close(): Promise<void>;

Release the reader worker. Repeated calls share one cleanup request; future reads reject.

Returns

Promise<void>

Resolves after cleanup. Previously copied metadata/results remain usable.

[asyncDispose]()

asyncDispose: Promise<void>;

Delegate asynchronous disposal to close().

Returns

Promise<void>

Reader cleanup completion.

Implementation of

AsyncDisposable.[asyncDispose]

UnknownCode

Preserve one unknown signed 32-bit categorical code.

Properties

Property	Modifier	Type	Description
`code`	`readonly`	`number`	Unrecognized signed 32-bit value, retained without interpretation.

ResultAttributeCode

Select one unknown result attribute by its stored signed code.

Properties

Property	Modifier	Type	Description
`code`	`readonly`	`number`	Stored signed 32-bit result code; must be present in the selected family schema.

PollutantAttribute

Select one pollutant column by index, exact text, bytes, or metadata name.

Properties

Property	Modifier	Type	Description
`selector`	`readonly`	`OutputElementSelector`	Exact configured output pollutant selector; not supported for system results.

SeriesSelection

Ordered family, element, and result-attribute selection.

Properties

Property	Modifier	Type	Description
`elementType`	`readonly`	`ResultElementType`	Result family whose schema is queried.
`element`	`readonly`	`OutputElementSelector` \| `null`	Required element selector for object families; must be null for system results.
`attribute`	`readonly`	`OutputAttribute`	Family-compatible built-in attribute, pollutant selector, or stored result code.

RunStatus

Finalized status code, or null when no output trailer was present.

Properties

Property	Modifier	Type	Description
`code`	`readonly`	`number` \| `null`	Trailer status code, or null for incomplete output without a trailer.
`isFinalized`	`readonly`	`boolean`	Whether a valid finalized trailer was present.
`isSuccess`	`readonly`	`boolean`	Whether the finalized status code is zero.

SubcatchmentMetadata

Stored subcatchment identity and static area.

Properties

Property	Modifier	Type	Description
`index`	`readonly`	`number`	Zero-based stored subcatchment index.
`name`	`readonly`	`OutputName`	Exact stored name.
`area`	`readonly`	`number`	Stored area in acres or hectares, according to header units.

NodeMetadata

Stored node identity and static properties.

Properties

Property	Modifier	Type	Description
`index`	`readonly`	`number`	Zero-based stored node index.
`name`	`readonly`	`OutputName`	Exact stored name.
`kind`	`readonly`	`NodeKind` \| `UnknownCode`	Recognized node subtype or unrecognized stored code.
`invertElevation`	`readonly`	`number`	Invert elevation in ft or m, according to header units.
`maximumDepth`	`readonly`	`number`	Maximum depth in ft or m.

LinkMetadata

Stored link identity and static properties.

Properties

Property	Modifier	Type	Description
`index`	`readonly`	`number`	Zero-based stored link index.
`name`	`readonly`	`OutputName`	Exact stored name.
`kind`	`readonly`	`LinkKind` \| `UnknownCode`	Recognized link subtype or unrecognized stored code.
`inletOffset`	`readonly`	`number`	Inlet offset in ft or m, according to header units.
`outletOffset`	`readonly`	`number`	Outlet offset in ft or m.
`maximumDepth`	`readonly`	`number`	Maximum depth in ft or m.
`length`	`readonly`	`number`	Stored link length in ft or m.

PollutantMetadata

Stored pollutant identity, name, and concentration units.

Properties

Property	Modifier	Type	Description
`index`	`readonly`	`number`	Zero-based stored pollutant index.
`name`	`readonly`	`OutputName`	Exact stored name.
`concentrationUnits`	`readonly`	\| `ConcentrationUnits` \| `UnknownCode`	Recognized concentration units or an unrecognized stored code.

ResultSchema

Ordered physical result schemas for every output family.

Properties

Property	Modifier	Type	Description
`subcatchment`	`readonly`	readonly `SubcatchmentSchemaEntry`[]	Subcatchment columns in stored order.
`node`	`readonly`	readonly `NodeSchemaEntry`[]	Node columns in stored order.
`link`	`readonly`	readonly `LinkSchemaEntry`[]	Link columns in stored order.
`system`	`readonly`	readonly `SystemSchemaEntry`[]	System columns in stored order.

OutputMetadata

Immutable metadata parsed from one output byte buffer.

Properties

Property	Modifier	Type	Description
`solverRelease`	`readonly`	`number`	Stored numeric solver release identifier.
`runStatus`	`readonly`	`RunStatus`	Trailer finalization and success status.
`flowUnits`	`readonly`	`OutputFlowUnits` \| `UnknownCode`	Recognized flow units or an unrecognized header code.
`unitSystem`	`readonly`	`OutputUnitSystem` \| `null`	Unit system inferred from recognized flow units; null otherwise.
`reportTiming`	`readonly`	`ReportTiming`	Validated nominal report schedule and complete-period count.
`subcatchments`	`readonly`	readonly `SubcatchmentMetadata`[]	Subcatchment metadata in stored order.
`nodes`	`readonly`	readonly `NodeMetadata`[]	Node metadata in stored order.
`links`	`readonly`	readonly `LinkMetadata`[]	Link metadata in stored order.
`pollutants`	`readonly`	readonly `PollutantMetadata`[]	Pollutant metadata in stored order.
`resultSchema`	`readonly`	`ResultSchema`	Physical column schemas, including unknown codes.

OutputValueSeries

Immutable selection-labelled values aligned to a bulk result axis.

Properties

Property	Modifier	Type	Description
`selection`	`readonly`	`SeriesSelection`	Resolved selection, with numeric element/pollutant indices.
`values`	`readonly`	readonly `number`[]	Values aligned to the enclosing result's time axis, in stored output units.

OutputTimeSeries

Immutable values and nominal dates for one selected series.

Properties

Property	Modifier	Type	Description
`selection`	`readonly`	`SeriesSelection`	Resolved selection, with numeric element/pollutant indices.
`times`	`readonly`	readonly `string`[]	Rounded nominal dates for the selected period range.
`values`	`readonly`	readonly `number`[]	Values aligned to `times`, in stored output units.

OutputReadOptions

Range and I/O strategy for output queries. Bounds are half-open.

Properties

Property	Modifier	Type	Description
`start?`	`readonly`	`string` \| `number` \| `null`	Inclusive integer period offset or timezone-free date; null/omission starts at zero. Dates resolve to the first nominal period at or after the bound.
`end?`	`readonly`	`string` \| `number` \| `null`	Exclusive integer period offset or timezone-free date; null/omission ends at periodCount. Integer bounds must lie within 0…periodCount; reversed ranges reject.
`lowMemory?`	`readonly`	`boolean`	Defaults to false (whole-period reads). True uses selective adjacent-run reads to reduce working memory without changing values.

OutputReaderOptions

Worker override for one standalone reader.

Properties

Property	Modifier	Type	Description
`workerUrl?`	`readonly`	`string` \| `URL`	Override the bundled worker asset location; resolved by the runtime when opening the reader.

ResultElementType

type ResultElementType = "subcatchment" | "node" | "link" | "system";

Supported result families in a binary output file.

ConcentrationUnits

type ConcentrationUnits = "milligrams_per_liter" | "micrograms_per_liter" | "counts_per_liter";

Concentration units recorded for one pollutant.

OutputFlowUnits

type OutputFlowUnits = "cfs" | "gpm" | "mgd" | "cms" | "lps" | "mld";

Flow units recorded in an output header.

OutputUnitSystem

type OutputUnitSystem = "us" | "si";

Unit system inferred from recognized output flow units.

SubcatchmentResultAttribute

type SubcatchmentResultAttribute = 
  | "rainfall"
  | "snow_depth"
  | "evap_loss"
  | "infil_loss"
  | "runoff_rate"
  | "gw_outflow_rate"
  | "gw_table_elev"
  | "soil_moisture";

Known subcatchment columns. Rainfall/infiltration use in/h or mm/h; evaporation uses in/day or mm/day; snow depth uses in or mm; runoff and groundwater outflow use header flow units; groundwater elevation uses ft or m; soil moisture is a fraction.

NodeResultAttribute

type NodeResultAttribute = 
  | "invert_depth"
  | "hydraulic_head"
  | "ponded_volume"
  | "lateral_inflow"
  | "total_inflow"
  | "flooding_losses";

Known node columns. Depth/head use ft or m; ponded volume uses ft³ or m³; lateral/total inflow and flooding losses use header flow units.

LinkResultAttribute

type LinkResultAttribute = 
  | "flow_rate"
  | "flow_depth"
  | "flow_velocity"
  | "flow_volume"
  | "capacity";

Known link columns. Flow uses header flow units; depth uses ft or m; velocity uses ft/s or m/s; volume uses ft³ or m³; capacity is dimensionless.

SystemResultAttribute

type SystemResultAttribute = 
  | "air_temp"
  | "rainfall"
  | "snow_depth"
  | "evap_infil_loss"
  | "runoff_flow"
  | "dry_weather_inflow"
  | "gw_inflow"
  | "rdii_inflow"
  | "direct_inflow"
  | "total_lateral_inflow"
  | "flood_losses"
  | "outfall_flows"
  | "volume_stored"
  | "evap_rate"
  | "ptnl_evap_rate";

Known system columns. Temperature uses °F or °C; rainfall and evap_infil_loss use in/h or mm/h; evap_rate and ptnl_evap_rate use in/day or mm/day; snow depth uses in or mm; stored volume uses ft³ or m³; runoff and inflow/outflow/loss columns use header flow units.

SubcatchmentSchemaEntry

type SubcatchmentSchemaEntry = 
  | SubcatchmentResultAttribute
  | PollutantAttribute
  | ResultAttributeCode;

One subcatchment schema column, including pollutant and unknown codes.

NodeSchemaEntry

type NodeSchemaEntry = 
  | NodeResultAttribute
  | PollutantAttribute
  | ResultAttributeCode;

One node schema column, including pollutant and unknown codes.

LinkSchemaEntry

type LinkSchemaEntry = 
  | LinkResultAttribute
  | PollutantAttribute
  | ResultAttributeCode;

One link schema column, including pollutant and unknown codes.

SystemSchemaEntry

type SystemSchemaEntry = 
  | SystemResultAttribute
  | ResultAttributeCode;

One system schema column; system results have no pollutant columns.

OutputAttribute

type OutputAttribute = 
  | SubcatchmentSchemaEntry
  | NodeSchemaEntry
  | LinkSchemaEntry
  | SystemSchemaEntry;

Result-column selector; the attribute must belong to the selected element family.

OutputElementSelector

type OutputElementSelector = number | string | Uint8Array | OutputName;

Zero-based integer index or exact stored name. Text is UTF-8 encoded; byte/name comparisons are case-sensitive, unlike Simulation collection lookups. Missing or ambiguous names reject.

OutputRange

type OutputRange = Omit<OutputReadOptions, "lowMemory">;

Alias for callers that only need period/date bounds.