8b28f8969e
Replaces the prior stub/partial wiki with a Home + Reference-{Architecture,
Contracts,Examples,Limitations} + _Sidebar structure. Topic-contract and
data-model sections wrapped in AUTOGEN markers for the future wiki-gen tool.
Source-vs-spec contradictions surfaced and flagged inline (not silently
fixed). Pending-review notes mark sections that need a full node review.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
181 lines
14 KiB
Markdown
181 lines
14 KiB
Markdown
# Reference — Contracts
|
|
|
|
|
|
|
|
> [!NOTE]
|
|
> The full public API surface — one row per export from `require('generalFunctions')`, with source file, stability tag, and contract summary. Source of truth: `index.js` (the barrel). For an intuitive overview, return to [Home](Home).
|
|
>
|
|
> **Stability tags:**
|
|
>
|
|
> - `stable` — API change requires a deprecation cycle and a CONTRACT update.
|
|
> - `experimental` — may change without warning; do not depend on the exact shape in production code paths.
|
|
> - `deprecated` — kept for backwards compatibility, slated for removal.
|
|
|
|
---
|
|
|
|
## Platform base classes
|
|
|
|
| Export | Stability | Source | Contract |
|
|
|:---|:---|:---|:---|
|
|
| `BaseDomain` | stable | `src/domain/BaseDomain.js` | Abstract base class for every `specificClass.js`. Provides `emitter`, `config`, `logger`, `measurements`, `childRegistrationUtils`, `router`. Subclass must declare `static name` (maps to the schema JSON file in `src/configs/`) and implement `configure()`. See [CONTRACTS.md §3](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/CONTRACTS.md). |
|
|
| `BaseNodeAdapter` | stable | `src/nodered/BaseNodeAdapter.js` | Abstract base for every `nodeClass.js`. Wires config build → domain instantiation → registration delay → output strategy → status loop → input dispatch → close handler. Subclass declares `static DomainClass`, `static commands`, `static tickInterval`, `static statusInterval`, and overrides `buildDomainConfig(uiConfig, nodeId)`. See [CONTRACTS.md §2](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/CONTRACTS.md). |
|
|
| `ChildRouter` | stable | `src/domain/ChildRouter.js` | Declarative parent-side child registration. Replaces per-node `registerChild` switch. Chain `.onRegister(softwareType, cb)`, `.onMeasurement(softwareType, filter, cb)`, `.onPrediction(softwareType, filter, cb)`. See [CONTRACTS.md §5](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/CONTRACTS.md). |
|
|
| `CommandRegistry` | stable | `src/nodered/commandRegistry.js` | Class form of the command registry. Accepts array of descriptors `{topic, aliases, payloadSchema, units, description, handler}`. Dispatches by `O(1)` lookup, normalises units before handler runs, warns on alias use. |
|
|
| `createRegistry` | stable | `src/nodered/commandRegistry.js` | Factory: `createRegistry(descriptors, options) → CommandRegistry`. Used by `BaseNodeAdapter`; rarely needed directly. |
|
|
| `UnitPolicy` | stable | `src/domain/UnitPolicy.js` | Declare unit sets: `UnitPolicy.declare({ canonical, output, curve?, requireUnitForTypes? })`. Returns policy with dual method/property access (`policy.canonical('flow')` and `policy.canonical.flow`). Methods: `canonical`, `output`, `curve`, `resolve`, `convert`, `containerOptions`, `setLogger`. See [CONTRACTS.md §6](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/CONTRACTS.md). |
|
|
| `LatestWinsGate` | stable | `src/domain/LatestWinsGate.js` | Serialises async dispatches so only the latest value wins. `fire(value)` — non-blocking. `fireAndWait(value) → Promise` that resolves with dispatch result or `LatestWinsGate.SUPERSEDED`. `drain()` — await idle. See [CONTRACTS.md §8](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/CONTRACTS.md). |
|
|
| `HealthStatus` | stable | `src/domain/HealthStatus.js` | Factory functions for frozen health objects: `HealthStatus.ok(msg, src)`, `HealthStatus.degraded(level, flags, msg, src)`, `HealthStatus.compose(statuses)`. Shape: `{ level: 0..3, flags: string[], message, source }`. See [CONTRACTS.md §9](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/CONTRACTS.md). |
|
|
| `statusBadge` | stable | `src/nodered/statusBadge.js` | Pure-function badge builder. `statusBadge.compose(parts, opts?) → {fill, shape, text}`. `statusBadge.error(msg)`, `statusBadge.idle(label)`. Text clipped to 60 chars. See [CONTRACTS.md §7](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/CONTRACTS.md). |
|
|
| `StatusUpdater` | stable | `src/nodered/statusUpdater.js` | `new StatusUpdater({ node, source, intervalMs, logger })`. `start()`, `stop()`. Calls `source.getStatusBadge()` on interval; catches errors and shows a red badge. Owned by `BaseNodeAdapter` — rarely needed directly. |
|
|
|
|
---
|
|
|
|
## Measurements
|
|
|
|
| Export | Stability | Source | Contract |
|
|
|:---|:---|:---|:---|
|
|
| `MeasurementContainer` | stable | `src/measurements/MeasurementContainer.js` | Chainable measurement store: `.type().variant().position().value(v, ts, srcUnit)`. Query: `getCurrentValue(unit)`, `getAverage(unit)`, `difference({ from, to, unit })`. Introspect: `getFlattenedOutput()` returns 4-segment keyed object (`type.variant.position.childId`). Auto-converts on write to canonical units per the supplied `UnitPolicy`. |
|
|
| `POSITIONS` | stable | `src/constants/positions.js` | Frozen enum: `{ UPSTREAM, DOWNSTREAM, AT_EQUIPMENT, DELTA }`. |
|
|
| `POSITION_VALUES` | stable | `src/constants/positions.js` | `string[]` of all position strings. |
|
|
| `isValidPosition` | stable | `src/constants/positions.js` | `(pos: string) => boolean`. |
|
|
|
|
### 4-segment output key
|
|
|
|
The contractual output of `MeasurementContainer.getFlattenedOutput()` is:
|
|
|
|
```
|
|
<type>.<variant>.<position>.<childId>
|
|
```
|
|
|
|
| Segment | Examples | Notes |
|
|
|:---|:---|:---|
|
|
| `type` | `flow`, `pressure`, `power`, `temperature`, `level`, `efficiency` | Lowercase. |
|
|
| `variant` | `predicted`, `measured`, `setpoint`, `max`, `min` | Lowercase. |
|
|
| `position` | `upstream`, `downstream`, `atequipment`, `delta` | Always lowercase — e.g. `atequipment`, not `atEquipment`. |
|
|
| `childId` | `default`, `<child.general.id>`, `dashboard-sim-upstream`, … | `default` for the node's own predictions; otherwise the registering child's id. |
|
|
|
|
Changing this shape is a forbidden breaking change — see [Reference — Limitations](Reference-Limitations#stability--versioning).
|
|
|
|
---
|
|
|
|
## Output formatting
|
|
|
|
| Export | Stability | Source | Contract |
|
|
|:---|:---|:---|:---|
|
|
| `outputUtils` | stable | `src/helper/outputUtils.js` | Singleton-per-node delta-compression engine. `formatMsg(output, config, format)` returns `msg` only when fields changed, or `undefined`. `format` is `'process'` or `'influxdb'`. Consumers must cache and merge. |
|
|
| `logger` | stable | `src/helper/logger.js` | `new logger(enabled, logLevel, moduleName)`. Methods: `debug`, `info`, `warn`, `error`, `setLogLevel`, `toggleLogging`. Use this instead of `console.log`. |
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
| Export | Stability | Source | Contract |
|
|
|:---|:---|:---|:---|
|
|
| `configManager` | stable | `src/configs/index.js` | `new configManager()`. Methods: `getConfig(name)`, `buildConfig(name, uiConfig, nodeId, domainSlice?)`, `getAvailableConfigs()`, `hasConfig(name)`. Config files live in `src/configs/*.json`. |
|
|
| `configUtils` | stable | `src/helper/configUtils.js` | `new configUtils(defaultConfig)`. `initConfig(userConfig)` validates and merges user values over defaults via `validationUtils`. |
|
|
| `validation` | stable | `src/helper/validationUtils.js` | `new validation(logEnabled, logLevel)`. `validateSchema(config, schema, name)` walks schema, clamps numbers, coerces types, strips unknown keys. |
|
|
| `assertions` | stable | `src/helper/` | Runtime validation primitives. |
|
|
| `assetApiConfig` | stable | `src/configs/assetApiConfig.js` | Asset-registry HTTP backend config. |
|
|
| `MenuManager` | stable | `src/menu/index.js` | `new MenuManager()`. Manages editor dropdown menus (asset, logger, position, aquon). `registerMenu(type, factory)`. Used in node entry files to power Node-RED editor forms. |
|
|
|
|
---
|
|
|
|
## Child registration
|
|
|
|
| Export | Stability | Source | Contract |
|
|
|:---|:---|:---|:---|
|
|
| `childRegistrationUtils` | stable | `src/helper/childRegistrationUtils.js` | `new childRegistrationUtils(parentDomain)`. `registerChild(child, positionVsParent, distance?)` stores child by softwareType/category with alias normalisation. `getChildrenOfType(softwareType, category?)`, `getChildById(id)`, `getAllChildren()`. Normally used via `ChildRouter` — direct use is for advanced cases. |
|
|
|
|
---
|
|
|
|
## Unit conversion + physics
|
|
|
|
| Export | Stability | Source | Contract |
|
|
|:---|:---|:---|:---|
|
|
| `convert` | stable | `src/convert/index.js` | Unit-converter factory. `convert(value).from(unit).to(unit)`. `convert.possibilities(measure)` lists accepted units. Measures: `volumeFlowRate`, `pressure`, `power`, `temperature`, `volume`, `length`, `mass`, `energy`, `reactivePower`, `apparentPower`, `reactiveEnergy`, and more. |
|
|
| `Fysics` | stable | `src/convert/fysics.js` | `new Fysics()`. Physical constants: `air_density`, `g0`; methods for gravity and viscosity calculations. |
|
|
| `gravity` | stable | `src/helper/gravity.js` | Singleton-style `Gravity` instance. `getStandardGravity() → 9.80665 m/s²`. WGS-84 latitude / altitude corrections available. |
|
|
| `coolprop` | stable | `src/coolprop-node/src/index.js` | CoolProp fluid/gas thermodynamic property lookup. Used by nodes that model heat transfer or gas compression. |
|
|
|
|
---
|
|
|
|
## Control & prediction
|
|
|
|
| Export | Stability | Source | Contract |
|
|
|:---|:---|:---|:---|
|
|
| `PIDController` | stable | `src/pid/PIDController.js` | Discrete PID with bumpless auto/manual transfer, anti-windup, derivative filtering, rate limiting, gain scheduling, feedforward. |
|
|
| `CascadePIDController` | stable | `src/pid/PIDController.js` | Outer-inner PID cascade built on `PIDController`. |
|
|
| `createPidController` | stable | `src/pid/index.js` | Factory shorthand: `createPidController(options) → PIDController`. |
|
|
| `createCascadePidController` | stable | `src/pid/index.js` | Factory shorthand for cascade PID. |
|
|
| `predict` | stable | `src/predict/predict_class.js` | `new predict(config, logger)`. Multidimensional characteristic-curve predictor; emits results via internal `EventEmitter`. |
|
|
| `interpolation` | stable | `src/predict/interpolation.js` | Class for 1-D and 2-D curve interpolation (linear, cubic-spline). Used internally by `predict`. |
|
|
| `nrmse` | stable | `src/nrmse/index.js` | `ErrorMetrics` class for normalised-root-mean-squared-error tracking. Multi-metric via `registerMetric(id)`, `update(id, predicted, measured)`. |
|
|
| `stats` | stable | `src/stats/index.js` | Pure functions: `mean(arr)`, `stdDev(arr)`, `median(arr)`. No state; safe to call on any numeric array. |
|
|
| `state` | stable | `src/state/index.js` | `new state(config, logger)`. FSM for valve / machine: `StateManager` (transitions) + `MovementManager` (timed moves). Emits state-change events. |
|
|
|
|
---
|
|
|
|
## Asset registry
|
|
|
|
| Export | Stability | Source | Contract |
|
|
|:---|:---|:---|:---|
|
|
| `assetResolver` | stable | `src/registry/index.js` | Singleton. `.resolve(category, modelId)` — sync, case-insensitive, returns `null` on miss. |
|
|
| `AssetResolver` | stable | `src/registry/index.js` | Resolver class (for testing / alternate backends). |
|
|
| `FileBackend` | stable | `src/registry/` | File-system asset backend. |
|
|
| `HttpBackend` | stable | `src/registry/` | HTTP asset backend. |
|
|
| `loadCurve` | **deprecated** | `index.js` (shim) | Thin shim over `assetResolver.resolve('curves', modelId)`. New code uses the resolver directly. |
|
|
|
|
---
|
|
|
|
## Canonical units (the platform-wide contract)
|
|
|
|
`MeasurementContainer` and all internal processing assume canonical units. Unit conversion happens at system boundaries (input via `CommandRegistry.units` normalisation, output via `UnitPolicy.output` rendering) — never in core logic.
|
|
|
|
| Quantity | Canonical (internal) | Typical output | Typical curve |
|
|
|:---|:---|:---|:---|
|
|
| Pressure | `Pa` | `mbar` | `mbar` |
|
|
| Atmospheric pressure | `Pa` | `Pa` | — |
|
|
| Flow | `m3/s` | `m3/h` | `m3/h` |
|
|
| Power | `W` | `kW` | `kW` |
|
|
| Temperature | `K` | `°C` | — |
|
|
| Control | — | — | `%` |
|
|
|
|
Each node declares its own `UnitPolicy` (typically as `static unitPolicy = UnitPolicy.declare({...})` on the domain class). The policy is passed to `MeasurementContainer` via `unitPolicy.containerOptions()`.
|
|
|
|
---
|
|
|
|
## Output ports (provided by `BaseNodeAdapter`)
|
|
|
|
Every node that extends `BaseNodeAdapter` automatically gets three ports:
|
|
|
|
| Port | Carries | Built by | Notes |
|
|
|:---|:---|:---|:---|
|
|
| 0 (process) | Delta-compressed state snapshot — the `getOutput()` return | `outputUtils.formatMsg(snapshot, config, 'process')` | Emits only when fields change. Consumers must cache and merge. |
|
|
| 1 (telemetry) | InfluxDB line-protocol payload (same fields as Port 0) | `outputUtils.formatMsg(snapshot, config, 'influxdb')` | Tags + fields per the schema. |
|
|
| 2 (register / control) | Parent-child handshake messages | `childRegistrationUtils` via `BaseNodeAdapter` | `child.register` at startup; subsequent `child.measurement` / `child.prediction` events. |
|
|
|
|
---
|
|
|
|
## Adding a new export — the dance
|
|
|
|
See [Reference — Architecture](Reference-Architecture#adding-a-new-export--the-dance) for the full step-by-step. Summary:
|
|
|
|
1. Implement under `src/<concern>/`.
|
|
2. Re-export from `index.js` (alphabetical within concern block).
|
|
3. Add a row to the appropriate table in [`CONTRACT.md`](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/nodes/generalFunctions/CONTRACT.md) with stability tag.
|
|
4. If it's a new platform shape, also update [`.claude/refactor/CONTRACTS.md`](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/CONTRACTS.md).
|
|
5. Add a test under `test/`.
|
|
|
|
---
|
|
|
|
## Related pages
|
|
|
|
| Page | Why |
|
|
|:---|:---|
|
|
| [Home](Home) | Intuitive overview |
|
|
| [Reference — Architecture](Reference-Architecture) | Three-tier rule, `src/` layout, consumer responsibilities |
|
|
| [Reference — Examples](Reference-Examples) | Usage patterns: extending base classes, registering commands, declaring child routes |
|
|
| [Reference — Limitations](Reference-Limitations) | Known issues, deprecations, stability rules |
|
|
| [Platform CONTRACTS.md](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/CONTRACTS.md) | The authoritative platform base-class + protocol spec |
|
|
| [Library CONTRACT.md](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/nodes/generalFunctions/CONTRACT.md) | Per-export source-of-truth with stability tags |
|