@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/lag/publish-to.js

@@ -0,0 +1,64 @@
+// nodes/lag/publish-to.js
+
+/**
+ * @fileoverview Publishes computed lag statistics to the output message.
+ *
+ * Only publishes requested stats. Uses publishNaN for fault isolation
+ * when input validation has failed. Follows ADR-004 patterns.
+ *
+ * @see ADR-004
+ */
+
+import { publishNaN } from '../../core/utils/node/index.js';
+
+/**
+ * Copies computed statistics to the output message.
+ *
+ * @param {Object} state - Node state from update()
+ * @param {Object} msg - Output message to enrich
+ */
+const publishTo = function ( state, msg ) {
+    // Guard: skip if disabled
+    if ( state.disable ) return;
+
+    // Fault isolation: propagate NaN if input validation failed
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        // cumDelta preserves its value (accumulation skipped, but sum is valid)
+        if ( state.hasCumDelta ) {
+            msg[ state.stats.cumDelta.storeAs ] = state.cumDelta;
+        }
+        return;
+    }
+
+    // Publish only requested stats
+    if ( state.hasXLag ) {
+        msg[ state.stats.xLag.storeAs ] = state.xLag;
+    }
+
+    if ( state.hasDelta ) {
+        msg[ state.stats.delta.storeAs ] = state.delta;
+    }
+
+    if ( state.hasRatio ) {
+        msg[ state.stats.ratio.storeAs ] = state.ratio;
+    }
+
+    if ( state.hasRoc ) {
+        msg[ state.stats.roc.storeAs ] = state.roc;
+    }
+
+    if ( state.hasSlope ) {
+        msg[ state.stats.slope.storeAs ] = state.slope;
+    }
+
+    if ( state.hasLogReturn ) {
+        msg[ state.stats.logReturn.storeAs ] = state.logReturn;
+    }
+
+    if ( state.hasCumDelta ) {
+        msg[ state.stats.cumDelta.storeAs ] = state.cumDelta;
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/lag/recompute.js

@@ -0,0 +1,33 @@
+// nodes/lag/recompute.js
+
+/**
+ * @fileoverview Numerical stability handler for the lag node.
+ *
+ * Five of six stats (delta, ratio, roc, slope, logReturn) are inherently
+ * stable — each is computed fresh from (xVal, xLag) with no accumulated
+ * state, so no recomputation is needed.
+ *
+ * cumDelta is the exception: it maintains an unbounded running sum
+ * (`state.cumDelta += (xVal - xLag)`) subject to O(n * machineEpsilon)
+ * floating-point drift over n messages. In practice, drift is bounded by
+ * periodic reset signals from the controller node; recompute remains a
+ * no-op under this assumption. If long-term accumulation without periodic
+ * reset is ever required, switch cumDelta to Kahan compensated summation
+ * in update.js.
+ *
+ * @see ADR-004
+ */
+
+/**
+ * Recomputes internal state for numerical stability.
+ *
+ * No-op: five instantaneous stats have no drift; cumDelta drift is bounded
+ * by periodic controller resets (see fileoverview).
+ *
+ * @returns {boolean} Always returns true (no action needed)
+ */
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/lag/reset.js

@@ -0,0 +1,49 @@
+// nodes/lag/reset.js
+
+/**
+ * @fileoverview Resets the lag node state to initial conditions.
+ *
+ * Resets computed values to NaN. Without `hasCumDelta`, also clears the
+ * ring buffer(s), which must refill before stats become valid. With
+ * `hasCumDelta`, the ring buffer is preserved (ADR-008) so the first
+ * post-reset delta bridges the reset without losing one interval.
+ *
+ * @see ADR-004
+ */
+
+import { reset as resetRing } from '../../windowing/count-sliding/index.js';
+
+/**
+ * Resets the node to its initial state.
+ *
+ * @param {Object} state - Node state to reset
+ * @returns {boolean} Always returns true (success)
+ */
+const reset = function ( state ) {
+    // ADR-008: cumDelta integrates a continuous signal; the ring buffer
+    // is the reference point. Clearing it loses one delta per reset
+    // (~1-3% systematic error in metered signals). Preserve the buffer
+    // so the first post-reset delta bridges the boundary gap-free.
+    // Without cumDelta, instantaneous stats (delta, ratio, roc, slope,
+    // logReturn) need a clean startup to avoid cross-boundary artifacts.
+    if ( !state.hasCumDelta ) {
+        resetRing( state.ringX );
+        if ( state.ringT !== null ) {
+            resetRing( state.ringT );
+        }
+    }
+
+    // Reset computed values to NaN (startup state)
+    state.delta = NaN;
+    state.ratio = NaN;
+    state.roc = NaN;
+    state.slope = NaN;
+    state.logReturn = NaN;
+    state.xLag = NaN;
+    // cumDelta resets to 0 (new integration lower limit)
+    state.cumDelta = 0;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/lag/update.js

@@ -0,0 +1,133 @@
+// nodes/lag/update.js
+/* eslint-disable complexity */
+
+/**
+ * @fileoverview Hot path for lag node message processing.
+ *
+ * Computes lag-based statistics with zero allocation. Only requested stats
+ * are computed, using pre-computed flags from init(). Follows ADR-004.
+ *
+ * Complexity is disabled for this file because the five conditional stat
+ * computations are inherently complex but cannot be refactored without
+ * adding function call overhead to the hot path.
+ *
+ * @see ADR-004
+ */
+
+import { push } from '../../windowing/count-sliding/index.js';
+
+/**
+ * Processes a message and computes lag-based statistics.
+ *
+ * Algorithm:
+ * 1. Push x value to ring buffer, receive evicted x_lag
+ * 2. If slope requested, push timestamp, receive evicted t_lag
+ * 3. If buffer not full (xLag undefined), all stats are NaN
+ * 4. Otherwise, compute only requested stats
+ *
+ * Division by zero protection:
+ * - ratio, roc: return NaN if x_lag === 0
+ * - slope: return NaN if t - t_lag === 0
+ * - logReturn: return NaN if x <= 0 or x_lag <= 0
+ *
+ * @param {Object} state - Node state from init()
+ * @param {Object} msg - Incoming message with field values
+ * @returns {Object} Updated state
+ */
+const update = function ( state, msg ) {
+    // Guard: skip if disabled
+    if ( state.disable || state.pause ) return state;
+
+    // Extract input value
+    const xVal = msg[ state.x ];
+
+    // Reset health flag
+    state.inputValidationFailed = false;
+
+    // Validate x input (catches NaN, Infinity, undefined)
+    if ( !Number.isFinite( xVal ) ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Handle timestamp if slope is requested
+    let tVal;
+    if ( state.hasSlope ) {
+        tVal = msg[ state.timestamp ];
+        if ( !Number.isFinite( tVal ) ) {
+            state.inputValidationFailed = true;
+            return state;
+        }
+    }
+
+    // Push x to ring buffer, get evicted x_lag (undefined during startup)
+    const xLag = push( state.ringX, xVal );
+
+    // Push timestamp if slope is needed
+    let tLag;
+    if ( state.hasSlope ) {
+        tLag = push( state.ringT, tVal );
+    }
+
+    // Check if buffer is full (xLag is finite when evicted value exists)
+    const hasLag = Number.isFinite( xLag );
+
+    // Compute only requested stats
+    if ( hasLag ) {
+        // ── xLag: the lagged input value itself ────────────────────────
+        if ( state.hasXLag ) {
+            state.xLag = xLag;
+        }
+
+        // ── delta: x - x_lag ───────────────────────────────────────────
+        if ( state.hasDelta ) {
+            state.delta = xVal - xLag;
+            if ( state.absolute ) {
+                state.delta = Math.abs( state.delta );
+            }
+        }
+
+        // ── ratio: x / x_lag ───────────────────────────────────────────
+        if ( state.hasRatio ) {
+            state.ratio = ( xLag === 0 ) ? NaN : ( xVal / xLag );
+        }
+
+        // ── roc: (x - x_lag) / x_lag ───────────────────────────────────
+        if ( state.hasRoc ) {
+            state.roc = ( xLag === 0 ) ? NaN : ( ( xVal - xLag ) / xLag );
+        }
+
+        // ── slope: (x - x_lag) / (t - t_lag) ───────────────────────────
+        if ( state.hasSlope ) {
+            const tDiff = tVal - tLag;
+            state.slope = ( tDiff === 0 ) ? NaN : ( ( xVal - xLag ) / tDiff );
+            if ( state.absolute && Number.isFinite( state.slope ) ) {
+                state.slope = Math.abs( state.slope );
+            }
+        }
+
+        // ── logReturn: ln(x / x_lag) ───────────────────────────────────
+        if ( state.hasLogReturn ) {
+            state.logReturn = ( xVal > 0 && xLag > 0 ) ?
+                Math.log( xVal / xLag ) :
+                NaN;
+        }
+
+        // ── cumDelta: Σ(x - x_lag) ──────────────────────────────────────
+        if ( state.hasCumDelta ) {
+            state.cumDelta += ( xVal - xLag );
+        }
+    } else {
+        // Startup period: buffer not full, all requested stats are NaN
+        if ( state.hasXLag ) state.xLag = NaN;
+        if ( state.hasDelta ) state.delta = NaN;
+        if ( state.hasRatio ) state.ratio = NaN;
+        if ( state.hasRoc ) state.roc = NaN;
+        if ( state.hasSlope ) state.slope = NaN;
+        if ( state.hasLogReturn ) state.logReturn = NaN;
+    }
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/median3/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Entry point for median3 node.
+ *
+ * Re-exports all lifecycle functions (init, update, publishTo, reset, recompute),
+ * shared control signals (disable, enable, pause, unpause), and introspection metadata.
+ */
+
+export { default as init } from './init.js';
+export { default as update } from './update.js';
+export { default as reset } from './reset.js';
+export { default as recompute } from './recompute.js';
+export { default as publishTo } from './publish-to.js';
+// Direct imports for common control functions
+export { default as disable } from '../../core/utils/node/disable.js';
+export { default as enable } from '../../core/utils/node/enable.js';
+export { default as pause } from '../../core/utils/node/pause.js';
+export { default as unpause } from '../../core/utils/node/unpause.js';
+// Re-export everything from introspection.js
+export * from './introspect.js';

package/src/nodes/median3/init.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Initialization for median3 node.
+ *
+ * Validates the spec, creates state with a 3-element ring buffer,
+ * and returns the fully initialized state object.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { create } from '../../windowing/count-sliding/index.js';
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    // Create state after validation passes
+    const state = Object.create( null );
+    // Standard input parameter health flag during update: false means healthy
+    state.inputValidationFailed = false;
+    // Ensure node is enabled by default
+    state.disable = false;
+    state.pause = false;
+
+    // Extract field name
+    state.x = spec.from.x;
+
+    // Underlying ring buffer storing the last 3 values
+    state.ring = create( 3 );
+
+    // Config copy
+    state.stats = spec.stats;
+
+    // State variables
+    state.median3 = 0;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/median3/introspect.js

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Introspection metadata for median3 node.
+ *
+ * Defines supported stats, control methods, capabilities, DSL schema,
+ * and default options. All getters return defensive copies.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'median3'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    median3: 'Fast median filter over last 3 values'
+};
+
+/** Control methods available for triggers */
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'Clears accumulated state and restarts computation',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses node processing while keeping state visible',
+    unpause: 'Resumes node processing after pause'
+};
+
+/** The type of this node */
+const NODE_TYPE = 'Median3';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Computes the median of the last 3 values for noise reduction',
+    features: [
+        'Rolling window of exactly 3 values',
+        'Efficient sorting algorithm for small fixed window',
+        'Handles partial windows gracefully (1-2 values)',
+        'Ideal for removing spike noise from sensor data'
+    ]
+};
+
+/** Default options — median3 has no optional parameters */
+export const DEFAULT_OPTIONS = {};
+
+// Export functions for accessing metadata
+export const getSupportedStats = () => SUPPORTED_STATS.slice();
+export const getStatDescriptions = () => ( { ...STAT_DESCRIPTIONS } );
+export const getSupportedControlMethods = () => ( { ...SUPPORTED_CONTROL_METHODS } );
+export const getNodeType = () => NODE_TYPE;
+export const getCapabilities = () => ( { ...CAPABILITIES, features: CAPABILITIES.features.slice() } );
+
+// DSL Metadata for transpilation
+const DSL_METADATA = {
+    // Spec schema for validation
+    specSchema: {
+        nodeType: {
+            type: 'string',
+            required: true,
+            value: NODE_TYPE
+        },
+        name: {
+            type: 'string',
+            required: true,
+            validator: validators.identifier,
+            error: 'Name must be a valid identifier'
+        },
+        from: {
+            type: 'object',
+            required: true,
+            properties: {
+                x: {
+                    type: 'string',
+                    required: true,
+                    validator: validators.noSpaces,
+                    error: 'Field name cannot contain spaces'
+                }
+            }
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                required: true,
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        minLength: 1,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    // Cross-field validators (none needed for median3)
+    crossFieldValidators: [],
+
+    // How to build the spec from DSL params
+    // Pattern: NAME_X_OUTPUTS_OPTIONS -> (name, x, stats, options)
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/median3/publish-to.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Publish function for median3 node.
+ *
+ * Copies the computed median value to the output message, or propagates
+ * NaN if the last input was invalid. Skipped entirely when disabled.
+ */
+
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    // Propagate NaN if unhealthy
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+
+    msg[ state.stats.median3.storeAs ] = state.median3;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/median3/recompute.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Recompute for median3 node.
+ *
+ * No-op: median is computed fresh from the raw ring buffer values on every
+ * update — there is no accumulated state that can drift over time.
+ */
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/median3/reset.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Reset median3 node state.
+ *
+ * Clears the ring buffer and resets the computed median value.
+ */
+
+import { reset as resetRing } from '../../windowing/count-sliding/index.js';
+
+const reset = function ( state ) {
+    resetRing( state.ring );
+    state.median3 = 0;
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/median3/update.js

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Update function for median3 node.
+ *
+ * Computes the median of the last 3 values using a 3-element sorting network.
+ * For partial windows: 1 value returns itself, 2 values return their average.
+ *
+ * Algorithm: compare-swap (a,b), compare-swap (b,c), then max(a,b) yields
+ * the median. This is a standard 3-element sorting network requiring exactly
+ * 3 comparisons. Reference: Knuth, TAOCP Vol. 3, Section 5.3.4.
+ */
+
+import { push } from '../../windowing/count-sliding/index.js';
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    const xVal = msg[ state.x ];
+    // Reset on each update
+    state.inputValidationFailed = false;
+    // Handle faults gracefully: ensure their isolation
+    if ( !Number.isFinite( xVal ) ) {
+        // Signals publishing NaN for all demanded `stats` in publishTo.
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    push( state.ring, xVal );
+
+    let a = state.ring.buffer[ 0 ];
+    let b = state.ring.buffer[ 1 ];
+    let c = state.ring.buffer[ 2 ];
+
+    if ( state.ring.used > 2 ) {
+        let tmp;
+        if ( a > b ) {
+            tmp = a;
+            a = b;
+            b = tmp;
+        }
+        if ( b > c ) {
+            tmp = b;
+            b = c;
+            c = tmp;
+        }
+        state.median3 = ( a > b ) ? a : b;
+        return state;
+    }
+
+    if ( state.ring.used === 2 ) {
+        state.median3 = ( a + b ) / 2;
+        return state;
+    }
+
+    state.median3 = xVal;
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/moments-digest/copy-from.js

@@ -0,0 +1,12 @@
+// nodes/moments-digest/copy-from.js
+
+export const copyFrom = function ( source, destination ) {
+    destination.n   = source.n;
+    destination.M1  = source.M1;
+    destination.M2  = source.M2;
+    destination.M3  = source.M3;
+    destination.M4  = source.M4;
+    destination.min = source.min;
+    destination.max = source.max;
+    return destination;
+};

package/src/nodes/moments-digest/flush.js

@@ -0,0 +1,17 @@
+// Forces publication of incomplete window.
+// Used for graceful shutdown or event driven snapshots.
+const flush = function ( state ) {
+    // Cascade nodes cannot be directly flushed
+    if ( state.isCascading ) {
+        return false;
+    }
+    // Set flush true so that during publish, the stats will be
+    // published even if window is incomplete. Note, the publishTo()
+    // method calls reset in the end resetting everything including
+    // the `state.flush` to `false`.
+    state.flushLatched = true;
+
+    return true;
+}; // reset()
+
+export default flush;