generalFunctions/wiki/Reference-Contracts.md

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.

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.
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.
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.
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.
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.
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.
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.
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.

---

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 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 with stability tag.
4. If it's a new platform shape, also update .claude/refactor/CONTRACTS.md.
5. Add a test under test/.

---

Related pages

Page	Why
Home	Intuitive overview
Reference — Architecture	Three-tier rule, src/ layout, consumer responsibilities
Reference — Examples	Usage patterns: extending base classes, registering commands, declaring child routes
Reference — Limitations	Known issues, deprecations, stability rules
Platform CONTRACTS.md	The authoritative platform base-class + protocol spec
Library CONTRACT.md	Per-export source-of-truth with stability tags