@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/sanitize/update.js

@@ -0,0 +1,102 @@
+// Helper: Check value against range
+const checkRange = function ( state, value, rangeSpec ) {
+    if ( !state.hasRange || !rangeSpec ) {
+        return true;  // No range configured, pass through
+    }
+
+    return value >= rangeSpec.min && value <= rangeSpec.max;
+}; // checkRange()
+
+// Helper: Check value against list
+const checkValueList = function ( state, value ) {
+    if ( !state.valueSet ) {
+        return true;  // No list configured, pass through
+    }
+
+    const isInList = state.valueSet.has( value );
+    // If containsValidValues is true, value must be in list (allow list)
+    // If containsValidValues is false, value must NOT be in list (deny list)
+    return state.containsValidValues ? isInList : !isInList;
+}; // checkValueList()
+
+// Helper: Check custom predicate
+const checkPredicate = function ( state, value, msg ) {
+    if ( !state.predicate ) {
+        return true;  // No predicate configured, pass through
+    }
+
+    try {
+        const result = state.predicate( value, msg ) === true;
+        // Recovery: clear log-suppression flag on success
+        if ( state.predicateErrorLogged ) state.predicateErrorLogged = false;
+        return result;
+    } catch ( error ) {
+        // Log first error per episode; suppress subsequent until recovery
+        if ( !state.predicateErrorLogged ) {
+            state.predicateErrorLogged = true;
+            console.error( `WinkComposer/sanitize: predicate threw exception: ${error.message}` );
+        }
+        return false;
+    }
+}; // checkPredicate()
+
+// Main update function
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+
+    const key = state.x;
+    const value = msg[ key ];
+
+    // Use self compare NaN NaN check first and not the Number.isFinite(),
+    // as incoming value may not be number type
+    if ( value !== value ) { // eslint-disable-line no-self-compare
+        // Assume it to be a value related failure!
+        state.failureReason = state.REASON_VALUE_LIST;
+        state.failedValue = value;
+        return state;
+    }
+
+    // Resolve range tunable for this message (if configured)
+    if ( state.rangesFn ) {
+        try {
+            state.resolvedRangeSpec = state.rangesFn( msg );
+            if ( state.tunableErrorLogged ) state.tunableErrorLogged = false;
+        } catch ( error ) {
+            if ( !state.tunableErrorLogged ) {
+                state.tunableErrorLogged = true;
+                console.error( `WinkComposer/${state.nodeType}: tunable threw: ${error.message}` );
+            }
+        }
+    }
+
+    // Check range first (most common validation)
+    if ( !checkRange( state, value, state.resolvedRangeSpec ) ) {
+        state.failureReason = state.REASON_RANGE;
+        state.failedValue = value;
+        msg[ key ] = NaN;
+        return state;
+    }
+
+    // Check value list
+    if ( !checkValueList( state, value ) ) {
+        state.failureReason = state.REASON_VALUE_LIST;
+        state.failedValue = value;
+        msg[ key ] = NaN;
+        return state;
+    }
+
+    // Check predicate
+    if ( !checkPredicate( state, value, msg ) ) {
+        state.failureReason = state.REASON_PREDICATE;
+        state.failedValue = value;
+        msg[ key ] = NaN;
+        return state;
+    }
+
+    // Value is valid, pass through unchanged
+    state.failureReason = null;
+    state.failedValue = null;
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/spike-guard/index.js

@@ -0,0 +1,14 @@
+// nodes/spike-guard/index.js
+
+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/spike-guard/init.js

@@ -0,0 +1,47 @@
+// nodes/spike-guard/init.js
+
+/**
+ * @fileoverview Initialize spikeGuard node state.
+ *
+ * Uses count-sliding ring buffer for 3-sample window.
+ * Unlike failed glitchGuard, stores VALUES not message references.
+ */
+
+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 and threshold
+    state.x = spec.from.x;
+    state.threshold = spec.threshold;
+
+    // Ring buffer for 3 values (reuses count-sliding)
+    state.ring = create( 3 );
+
+    // Config copy for publishTo
+    state.stats = spec.stats;
+
+    // Output state variables
+    state.clean = 0;
+    state.detected = false;
+    state.magnitude = 0;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/spike-guard/introspect.js

@@ -0,0 +1,130 @@
+// nodes/spike-guard/introspect.js
+
+/**
+ * @fileoverview Introspection metadata for spikeGuard node.
+ *
+ * spikeGuard detects single-sample spikes using a 3-sample sliding window.
+ * Core insight: In window [left, middle, right]:
+ * - Spike: middle differs from BOTH left and right by > threshold
+ * - Transition: middle differs from only ONE neighbor
+ *
+ * This elegantly discriminates spikes from transitions without lookahead.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'clean',        // Cleaned value (median of window)
+    'detected',     // Boolean: true when spike detected
+    'magnitude'     // Signed spike magnitude (negative=dip, positive=surge), 0 if no spike
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    clean: 'Cleaned value (median of 3-sample window)',
+    detected: 'Boolean: true when spike detected',
+    magnitude: 'Signed spike magnitude: negative=dip (dropout), positive=surge (noise), 0 if no spike'
+};
+
+/** 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 = 'Spike Guard';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Detects single-sample spikes and outputs cleaned (median) value',
+    features: [
+        'Rolling window of exactly 3 values',
+        'Spike = middle differs from BOTH neighbors by > threshold',
+        'Outputs cleaned value (median) and detection flag',
+        'Zero false positives at state transitions'
+    ]
+};
+
+// 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
+// Pattern: NAME_X_OUTPUTS_OPTIONS -> .spikeGuard( name, x, stats, options )
+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'
+                }
+            }
+        },
+        threshold: {
+            type: 'number',
+            required: true,
+            validator: validators.positive,
+            error: 'Threshold must be a positive number'
+        },
+        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 spikeGuard)
+    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/spike-guard/publish-to.js

@@ -0,0 +1,35 @@
+// nodes/spike-guard/publish-to.js
+
+/**
+ * @fileoverview Publish spikeGuard outputs to message.
+ *
+ * Supports three stats:
+ * - clean: Cleaned value (median of window)
+ * - detected: Boolean indicating spike detected
+ * - magnitude: Spike magnitude (0 if no spike)
+ */
+
+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;
+    }
+
+    // Publish configured stats (only those requested in spec)
+    if ( state.stats.clean ) {
+        msg[ state.stats.clean.storeAs ] = state.clean;
+    }
+    if ( state.stats.detected ) {
+        msg[ state.stats.detected.storeAs ] = state.detected;
+    }
+    if ( state.stats.magnitude ) {
+        msg[ state.stats.magnitude.storeAs ] = state.magnitude;
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/spike-guard/recompute.js

@@ -0,0 +1,14 @@
+// nodes/spike-guard/recompute.js
+
+/**
+ * @fileoverview Recompute for numerical stability.
+ *
+ * spikeGuard has no numerical drift - it only computes medians
+ * and absolute differences. No accumulation that could drift.
+ */
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/spike-guard/reset.js

@@ -0,0 +1,19 @@
+// nodes/spike-guard/reset.js
+
+/**
+ * @fileoverview Reset spikeGuard node state.
+ *
+ * Clears the ring buffer and resets output values.
+ */
+
+import { reset as resetRing } from '../../windowing/count-sliding/index.js';
+
+const reset = function ( state ) {
+    resetRing( state.ring );
+    state.clean = 0;
+    state.detected = false;
+    state.magnitude = 0;
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/spike-guard/update.js

@@ -0,0 +1,89 @@
+// nodes/spike-guard/update.js
+
+/**
+ * @fileoverview Core spike detection algorithm.
+ *
+ * Window: [left, middle, right]  (3-sample sliding window of VALUES)
+ *
+ * On each sample:
+ *   1. Push new value into window
+ *   2. If window full:
+ *      - leftDiff  = |middle - left|
+ *      - rightDiff = |middle - right|
+ *      - detected = (leftDiff > threshold) AND (rightDiff > threshold)
+ *      - clean = median(left, middle, right)
+ *      - magnitude = (middle - avg(left, right)) if detected, else 0
+ *   3. Output: clean, detected, magnitude (signed: negative=dip, positive=surge)
+ *
+ * Why This Works (No False Positives at Transitions):
+ *
+ * | Scenario      | Window           | leftDiff | rightDiff | Both > T? | Result     |
+ * |---------------|------------------|----------|-----------|-----------|------------|
+ * | Spike         | [90, 0.7, 90]    | 89.3     | 89.3      | YES       | DETECTED   |
+ * | Falling edge  | [90, 90, 0.7]    | 0        | 89.3      | NO        | not spike  |
+ * | Falling edge  | [90, 0.7, 0.7]   | 89.3     | 0         | NO        | not spike  |
+ * | Rising edge   | [0.7, 0.7, 90]   | 0        | 89.3      | NO        | not spike  |
+ * | Rising edge   | [0.7, 90, 90]    | 89.3     | 0         | NO        | not spike  |
+ * | Normal        | [89, 91, 90]     | 2        | 1         | NO        | not spike  |
+ */
+
+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 );
+
+    // Need exactly 3 values for spike detection
+    if ( state.ring.used < 3 ) {
+        // Partial window: output current value, no detection
+        state.clean = xVal;
+        state.detected = false;
+        state.magnitude = 0;
+        return state;
+    }
+
+    // Extract window values in chronological order: [oldest, middle, newest]
+    // The ring buffer's head points to the NEXT slot to write (= oldest value)
+    const head = state.ring.head;
+    const left = state.ring.buffer[ head ];              // oldest
+    const middle = state.ring.buffer[ ( head + 1 ) % 3 ]; // middle (potential spike)
+    const right = state.ring.buffer[ ( head + 2 ) % 3 ];  // newest (just pushed)
+
+    // Compute differences from middle to neighbors
+    const leftDiff = Math.abs( middle - left );
+    const rightDiff = Math.abs( middle - right );
+
+    // Spike = middle differs from BOTH neighbors by > threshold
+    state.detected = ( leftDiff > state.threshold ) &&
+                     ( rightDiff > state.threshold );
+
+    // Compute median for clean value (same algorithm as median3)
+    let a = left;
+    let b = middle;
+    let c = right;
+    if ( a > b ) [ a, b ] = [ b, a ];
+    if ( b > c ) [ b, c ] = [ c, b ];
+    state.clean = ( a > b ) ? a : b;
+
+    // Signed magnitude: deviation from expected (interpolated) value
+    // Negative = dip (dropout), Positive = surge (noise)
+    const expectedValue = ( left + right ) / 2;
+    state.magnitude = state.detected ? ( middle - expectedValue ) : 0;
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/sse-emitter/index.js

@@ -0,0 +1,7 @@
+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';
+// Re-export everything from introspection.js
+export * from './introspect.js';

package/src/nodes/sse-emitter/init.js

@@ -0,0 +1,105 @@
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { DATA_PREFIX, MESSAGE_SUFFIX } from './utils/build-message.js';
+import { createSSEHeaders, createConnection, setupConnectionHandlers } from './utils/connection-manager.js';
+import { initializeEndpoints } from './utils/endpoint-initializer.js';
+import { handleHealthCheck } from './utils/health-monitor.js';
+import { broadcastHeartbeat } from './utils/broadcast-heartbeat.js';
+import { createServer } from 'node:http';
+
+// Simple module-level resources
+let server = null;
+let heartbeatInterval = null; // eslint-disable-line no-unused-vars
+
+const handleSSEConnection = function ( state, req, res, endpointName ) {
+    // Check connection limit
+    if ( state.totalConnections >= state.maxConnections ) {
+        res.writeHead( 503, { 'Content-Type': 'text/plain' } );
+        res.end( `Max connections reached (${state.maxConnections})` );
+        return;
+    }
+
+    // Set SSE headers
+    res.writeHead( 200, createSSEHeaders() );
+
+    // Create and register connection
+    const connection = createConnection( state, res, endpointName );
+
+    console.log( `SSE ${endpointName} connected (${state.totalConnections}/${state.maxConnections})` );
+
+    // Send initial message using same format as broadcasts
+    const initData = `{"connected":true,"endpoint":"${endpointName}"}`;
+    const initMessage = `data: ${initData}\n\n`;
+    res.write( initMessage );
+
+    // Setup disconnect handlers
+    setupConnectionHandlers( state, req, connection, endpointName );
+}; // handleSSEConnection()
+
+const routeRequest = function ( state, req, res ) {
+    const url = req.url;
+
+    if ( url === '/health' ) {
+        handleHealthCheck( state, res );
+        return;
+    }
+
+    if ( url.startsWith( '/events/' ) ) {
+        const endpointName = url.slice( 8 ); // Remove '/events/' prefix
+
+        if ( state.connections[ endpointName ] ) {
+            handleSSEConnection( state, req, res, endpointName );
+        } else {
+            res.writeHead( 404, { 'Content-Type': 'text/plain' } );
+            res.end( `Endpoint not configured. Available: ${state.endpointNames.join( ', ' )}` );
+        }
+        return;
+    }
+
+    res.writeHead( 404 );
+    res.end( 'Not found' );
+}; // routeRequest()
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    const state = Object.create( null );
+
+    // 2. Extract and store configuration
+    state.port = spec.port || 3000;
+    state.maxConnections = spec.maxConnections || 4;
+    state.stats = spec.stats;
+    state.nodeType = introspect.getNodeType();
+
+    // 3. Initialize endpoints and connections
+    initializeEndpoints( state );
+
+    // 4. Performance optimization: Pre-allocated buffers and constants
+    state.messageBuffer = Buffer.alloc( 4096 ); // 4KB reusable buffer
+    state.deadConnectionsPool = []; // Reusable arrays for cleanup
+    state.dataPrefix = DATA_PREFIX;
+    state.messageSuffix = MESSAGE_SUFFIX;
+
+    // 5. Initialize statistics tracking
+    state.totalConnections = 0;
+    state.totalSent = 0;
+    state.totalErrors = 0;
+
+    // 6. Create and start HTTP server
+    server = createServer( ( req, res ) => {
+        routeRequest( state, req, res );
+    } );
+
+    server.listen( state.port, () => {
+        console.log( `SSE Emitter listening on port ${state.port}` );
+        console.log( `Configured endpoints: ${state.endpointNames.join( ', ' )}` );
+    } );
+
+    heartbeatInterval = setInterval(() => {
+        broadcastHeartbeat(state);
+    }, 30000);
+
+    return state;
+}; // init()
+
+export default init;