@winkjs/composer 0.0.2 → 0.4.0

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

@@ -0,0 +1,134 @@
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this node can do */
+const SUPPORTED_STATS = [
+    'dashboard',
+    'alerts',
+    'database',
+    'monitoring'
+];
+
+/** QoS level constants for performance (numeric comparison in hot path) */
+export const QOS_FIRE_AND_FORGET = 0;
+export const QOS_BEST_EFFORT = 1;
+export const QOS_RELIABLE = 2;
+
+/** Human-readable descriptions */
+const STAT_DESCRIPTIONS = {
+    dashboard: 'Real-time dashboard connections',
+    alerts: 'Alert system connections',
+    database: 'Database sink connections',
+    monitoring: 'System monitoring connections'
+};
+
+/** QoS level descriptions */
+const QOS_DESCRIPTIONS = {
+    [ QOS_FIRE_AND_FORGET ]: 'Fire-and-forget: No queuing, drop on backpressure (fastest)',
+    [ QOS_BEST_EFFORT ]: 'Best-effort: Small queue, drop oldest on overflow (balanced)',
+    [ QOS_RELIABLE ]: 'Reliable: Large queue, backpressure monitoring (most reliable)'
+};
+
+/** The type of this node */
+const NODE_TYPE = 'SSE Emitter';
+
+/** Node capabilities */
+const CAPABILITIES = {
+    description: 'Broadcasts entire messages via Server-Sent Events with configurable QoS levels',
+    features: [
+        'Terminal node - broadcasts complete pipeline messages',
+        'Four endpoint types: dashboard, alerts, database, monitoring',
+        'Numeric QoS levels: 0 (fire-and-forget), 1 (best-effort), 2 (reliable)',
+        'High-performance broadcasting with buffer reuse',
+        'Production-ready connection management'
+    ]
+};
+
+// Export functions for accessing metadata
+export const getSupportedStats = () => SUPPORTED_STATS.slice();
+export const getStatDescriptions = () => ( { ...STAT_DESCRIPTIONS } );
+export const getNodeType = () => NODE_TYPE;
+export const getCapabilities = () => ( { ...CAPABILITIES } );
+export const getQoSDescriptions = () => ( { ...QOS_DESCRIPTIONS } );
+
+// DSL Metadata
+const DSL_METADATA = {
+    // Validation schema
+    specSchema: {
+        nodeType: {
+            type: 'string',
+            required: true,
+            value: NODE_TYPE,
+            validator: composerValidators.nodeType,
+            error: 'Invalid node type'
+        },
+        name: {
+            type: 'string',
+            required: true,
+            validator: validators.identifier,
+            error: 'Name must be a valid JavaScript identifier'
+        },
+        // Note: No 'from' field - terminal node broadcasts entire message
+        port: {
+            type: 'number',
+            required: false,
+            default: 3000,  // Documentation only!
+            min: 1024,
+            max: 65535,
+            integer: true,
+            error: 'Port must be between 1024 and 65535'
+        },
+        maxConnections: {
+            type: 'number',
+            required: false,
+            default: 4,  // Documentation only!
+            min: 1,
+            max: 10,
+            integer: true,
+            validator: validators.positiveInteger,
+            error: 'Max connections must be between 1 and 10'
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,  // Array of allowed endpoint names
+            propertySchema: {
+                type: 'object',
+                required: true,
+                validator: composerValidators.statSpec,  // Using composerValidator!
+                properties: {
+                    qos: {
+                        type: 'number',
+                        required: false,
+                        default: 0,  // Documentation only!
+                        integer: true,
+                        validator: validators.oneOf( [ 0, 1, 2 ] ),
+                        error: 'QoS must be 0 (fire-and-forget), 1 (best-effort), or 2 (reliable)'
+                    }
+                }
+            },
+            error: 'Stats must define at least one endpoint with valid configuration'
+        }
+    },
+
+    // 3. Cross-field validators - none needed for SSE Emitter
+    crossFieldValidators: [],
+
+    // 4. Build spec from DSL
+    buildSpec: function ( port = 3000, maxConnections = 4 ) {
+        return {
+            nodeType: NODE_TYPE,
+            name: '{{AUTO_NAME}}',
+            port,
+            maxConnections,
+            stats: {
+                dashboard: { storeAs: 'dashConnected', qos: 0 },  // Default fire-and-forget
+                database: { storeAs: 'dbConnected', qos: 2 }      // Default reliable
+            }
+        };
+    },
+
+    acceptsSpecObject: true
+};
+
+export const getDSLMetadata = () => ({ ...DSL_METADATA });

package/src/nodes/sse-emitter/publish-to.js

@@ -0,0 +1,6 @@
+const publishTo = function ( _state, _msg ) {
+    // Terminal node - nothing to publish for downstream
+    // Connection counts are already added in update() before broadcasting
+}; // publishTo()
+
+export default publishTo;

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

@@ -0,0 +1,16 @@
+const recompute = function ( state ) {
+    // Recompute total connection count from all endpoints
+    let totalConnections = 0;
+
+    for ( let i = 0; i < state.endpointNames.length; i += 1 ) {
+        const endpointName = state.endpointNames[i];
+        totalConnections += state.connections[endpointName].length;
+    }
+
+    state.totalConnections = totalConnections;
+
+    console.log( `composer/sseEmitter: Recomputed ${state.totalConnections} active connections across ${state.endpointNames.length} endpoints` );
+    return true;
+};
+
+export default  recompute;

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

@@ -0,0 +1,19 @@
+const reset = function ( state ) {
+    // Reset statistics only (keep connections active)
+    state.totalSent = 0;
+    state.totalErrors = 0;
+
+    // Reset per-connection message counts
+    for ( let i = 0; i < state.endpointNames.length; i += 1 ) {
+        const endpointName = state.endpointNames[ i ];
+        const connections = state.connections[ endpointName ];
+
+        for ( let j = 0; j < connections.length; j += 1 ) {
+            connections[ j ].messagesSent = 0;
+        }
+    }
+
+    return true;
+};
+
+export default reset;

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

@@ -0,0 +1,69 @@
+import { buildMessage } from './utils/build-message.js';
+import { QOS_HANDLERS } from './utils/qos-handler.js';
+
+const cleanupDeadConnections = function ( state, connections, deadConnections ) {
+    // Remove dead connections in reverse order to maintain indices
+    for ( let i = deadConnections.length - 1; i >= 0; i -= 1 ) {
+        connections.splice( deadConnections[ i ], 1 );
+        state.totalConnections -= 1;
+    }
+
+    // Return array to pool for reuse
+    state.deadConnectionsPool.push( deadConnections );
+}; // cleanupDeadConnections()
+
+const broadcastToEndpoint = function ( state, connections, message, endpointName ) {
+    // Get reusable dead connections array
+    const deadConnections = state.deadConnectionsPool.pop() || [];
+    deadConnections.length = 0;
+
+    // Fast iteration with minimal nesting
+    for ( let i = 0; i < connections.length; i += 1 ) {
+        const connection = connections[ i ];
+
+        if ( !connection.response.writable ) {
+            deadConnections.push( i );
+            continue; // eslint-disable-line no-continue
+        }
+
+        try {
+            // O(1) QoS handler dispatch - no switch statement nesting
+            const qosHandler = QOS_HANDLERS[ connection.qos ] || QOS_HANDLERS[ 0 ];
+            qosHandler( connection, message, state, endpointName );
+        } catch {
+            deadConnections.push( i );
+            state.totalErrors += 1;
+        }
+    }
+
+    cleanupDeadConnections( state, connections, deadConnections );
+}; // broadcastToEndpoint()
+
+// High-performance broadcast with zero allocations
+const update = function ( state, msg ) {
+    // Fast path: no connections
+    if ( state.totalConnections === 0 ) return;
+
+    // Add connection counts directly to the message
+    for ( let i = 0; i < state.endpointNames.length; i += 1 ) {
+        const endpointName = state.endpointNames[ i ];
+        const storeAs = state.stats[ endpointName ].storeAs;
+        msg[ storeAs ] = state.connections[ endpointName ].length;
+    }
+
+    // Serialize entire message (only unavoidable allocation)
+    const jsonString = JSON.stringify( msg );
+    const messageToSend = buildMessage( state, jsonString );
+
+    // Broadcast to all configured endpoints
+    for ( let i = 0; i < state.endpointNames.length; i += 1 ) {
+        const endpointName = state.endpointNames[ i ];
+        const connections = state.connections[ endpointName ];
+
+        if ( connections.length > 0 ) {
+            broadcastToEndpoint( state, connections, messageToSend, endpointName );
+        }
+    }
+}; // update()
+
+export default update;

package/src/nodes/sse-emitter/utils/broadcast-heartbeat.js

@@ -0,0 +1,36 @@
+// utils/broadcast-heartbeat.js
+
+const HEARTBEAT_MESSAGE = Buffer.from(':heartbeat\n\n');
+
+export const broadcastHeartbeat = function (state) {
+    // SSE comment format (`:` prefix) keeps connection alive without triggering client events
+
+    for (let i = 0; i < state.endpointNames.length; i += 1) {
+        const endpointName = state.endpointNames[i];
+        const connections = state.connections[endpointName];
+
+        // Track dead connections
+        const deadIndices = [];
+
+        for (let j = 0; j < connections.length; j += 1) {
+            const connection = connections[j];
+
+            try {
+                if (connection.response.writable) {
+                    connection.response.write(HEARTBEAT_MESSAGE);
+                } else {
+                    deadIndices.push(j);
+                }
+            } catch ( error ) {
+                console.error(`composer/emitter: Write error on ${endpointName}:`, error.message);
+                deadIndices.push(j);
+            }
+        }
+
+        // Clean up dead connections
+        for (let k = deadIndices.length - 1; k >= 0; k -= 1) {
+            connections.splice(deadIndices[k], 1);
+            state.totalConnections -= 1;
+        }
+    }
+};

package/src/nodes/sse-emitter/utils/build-message.js

@@ -0,0 +1,31 @@
+// utils/build-message.js
+
+const DATA_PREFIX = Buffer.from( 'data: ' );
+const MESSAGE_SUFFIX = Buffer.from( '\n\n' );
+
+const buildMessage = function ( state, jsonString ) {
+    const { messageBuffer, dataPrefix, messageSuffix } = state;
+    const jsonBuffer = Buffer.from( jsonString, 'utf8' );
+    const totalSize = dataPrefix.length + jsonBuffer.length + messageSuffix.length;
+
+    // Use reusable buffer for small messages
+    if ( totalSize <= messageBuffer.length ) {
+        let offset = 0;
+
+        dataPrefix.copy( messageBuffer, offset );
+        offset += dataPrefix.length;
+
+        jsonBuffer.copy( messageBuffer, offset );
+        offset += jsonBuffer.length;
+
+        messageSuffix.copy( messageBuffer, offset );
+        offset += messageSuffix.length;
+
+        return messageBuffer.subarray( 0, offset );
+    }
+
+    // Fallback for large messages
+    return Buffer.concat( [ dataPrefix, jsonBuffer, messageSuffix ] );
+}; // buildSSEMessage()
+
+export { buildMessage, DATA_PREFIX, MESSAGE_SUFFIX };

package/src/nodes/sse-emitter/utils/connection-manager.js

@@ -0,0 +1,45 @@
+// utils/connection-manager.js
+
+const createSSEHeaders = function () {
+    return {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        // eslint-disable-next-line no-warning-comments
+        // TODO: Remove next line in production - dashboard served from same port
+        'Access-Control-Allow-Origin': '*'
+    };
+}; // createSSEHeaders()
+
+const createConnection = function ( state, res, endpointName ) {
+    const connection = {
+        response: res,
+        endpoint: endpointName,
+        qos: state.endpointQoS[ endpointName ],
+        createdAt: Date.now(),
+        messagesSent: 0
+    };
+
+    state.connections[ endpointName ].push( connection );
+    state.totalConnections += 1;
+
+    return connection;
+}; // createConnection()
+
+const removeConnection = function ( state, connection, endpointName ) {
+    const connections = state.connections[ endpointName ];
+    const index = connections.indexOf( connection );
+    if ( index !== -1 ) {
+        connections.splice( index, 1 );
+        state.totalConnections -= 1;
+        console.log( `SSE ${endpointName} disconnected (${state.totalConnections}/${state.maxConnections})` );
+    }
+}; // removeConnection()
+
+const setupConnectionHandlers = function ( state, req, connection, endpointName ) {
+    const cleanup = () => removeConnection( state, connection, endpointName );
+    req.on( 'close', cleanup );
+    req.on( 'error', cleanup );
+}; // setupConnectionHandlers()
+
+export { createSSEHeaders, createConnection, removeConnection, setupConnectionHandlers };

package/src/nodes/sse-emitter/utils/endpoint-initializer.js

@@ -0,0 +1,20 @@
+// utils/endpoint-initializer.js
+
+const initializeEndpoints = function ( state ) {
+    state.endpointNames = Object.keys( state.stats );
+    state.connections = Object.create( null );
+    state.endpointQoS = Object.create( null );
+
+    // Create connection arrays and store QoS levels
+    for ( let i = 0; i < state.endpointNames.length; i += 1 ) {
+        const endpointName = state.endpointNames[ i ];
+        state.connections[ endpointName ] = [];
+
+        // Apply QoS defaults: dashboard=0, database=2, others=1
+        const defaultQoS = endpointName === 'dashboard' ? 0 :
+                          endpointName === 'database' ? 2 : 1;
+        state.endpointQoS[ endpointName ] = state.stats[ endpointName ].qos || defaultQoS;
+    }
+}; // initializeEndpoints()
+
+export { initializeEndpoints };

package/src/nodes/sse-emitter/utils/health-monitor.js

@@ -0,0 +1,38 @@
+// utils/health-monitor.js
+
+const buildHealthResponse = function ( state ) {
+    const endpointStats = Object.create( null );
+    for ( let i = 0; i < state.endpointNames.length; i += 1 ) {
+        const endpointName = state.endpointNames[ i ];
+        endpointStats[ endpointName ] = state.connections[ endpointName ].length;
+    }
+
+    return {
+        nodeType: state.nodeType,
+        connections: {
+            total: state.totalConnections,
+            byEndpoint: endpointStats
+        },
+        stats: {
+            sent: state.totalSent,
+            errors: state.totalErrors
+        },
+        endpoints: state.endpointNames,
+        timestamp: Date.now()
+    };
+}; // buildHealthResponse()
+
+const handleHealthCheck = function ( state, res ) {
+    const healthData = buildHealthResponse( state );
+    res.writeHead( 200, {
+        'Content-Type': 'application/json',
+        // eslint-disable-next-line no-warning-comments
+        // TODO: Remove next 3 lines in production - dashboard served from same port
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET',
+        'Access-Control-Allow-Headers': 'Content-Type'
+    } );
+    res.end( JSON.stringify( healthData ) );
+}; // handleHealthCheck()
+
+export { buildHealthResponse, handleHealthCheck };

package/src/nodes/sse-emitter/utils/qos-handler.js

@@ -0,0 +1,41 @@
+// utils/qos-handler.js
+
+import { QOS_FIRE_AND_FORGET, QOS_BEST_EFFORT, QOS_RELIABLE } from '../introspect.js';
+
+const fireAndForgetSend = function ( connection, message, state ) {
+    connection.response.write( message );
+    connection.messagesSent += 1;
+    state.totalSent += 1;
+}; // fireAndForgetSend()
+
+const bestEffortSend = function ( connection, message, state, endpointName ) {
+    const success = connection.response.write( message );
+    if ( success ) {
+        connection.messagesSent += 1;
+        state.totalSent += 1;
+    } else {
+        console.warn( `${endpointName} client backpressure - best effort` );
+        state.totalSent += 1; // Count as sent for metrics
+    }
+}; // bestEffortSend()
+
+const reliableSend = function ( connection, message, state, endpointName ) {
+    const success = connection.response.write( message );
+    if ( success ) {
+        connection.messagesSent += 1;
+        state.totalSent += 1;
+    } else {
+        console.warn( `${endpointName} client backpressure - reliable mode` );
+        // TO DO: Implement proper queuing for reliable delivery
+        state.totalSent += 1; // Count as sent for now
+    }
+}; // reliableSend()
+
+// O(1) QoS handler dispatch table
+const QOS_HANDLERS = {
+    [ QOS_FIRE_AND_FORGET ]: fireAndForgetSend,
+    [ QOS_BEST_EFFORT ]: bestEffortSend,
+    [ QOS_RELIABLE ]: reliableSend
+};
+
+export { QOS_HANDLERS };

package/src/nodes/state-change-detector/helpers.js

@@ -0,0 +1,35 @@
+/**
+ * Validate that all required fields exist in message and contain categorical values
+ *
+ * @param {Object} msg - Message to validate
+ * @param {string[]} fieldNames - Array of required field names
+ * @param {number} fieldCount - Number of fields to validate
+ * @returns {boolean} True if all fields are present and categorical
+ */
+const validateCategoricalFields = function ( msg, fieldNames, fieldCount ) {
+    for ( let i = 0; i < fieldCount; i += 1 ) {
+        const field = fieldNames[ i ];
+        const value = msg[ field ];
+
+        // Missing field
+        if ( value === undefined ) {
+            return false;
+        }
+
+        // Check if categorical (string, number, or boolean)
+        const valueType = typeof value;
+        const isCategorical = (
+            valueType === 'string' ||
+            valueType === 'number' ||
+            valueType === 'boolean'
+        );
+
+        if ( !isCategorical ) {
+            return false;
+        }
+    }
+
+    return true;
+}; // validateCategoricalFields()
+
+export { validateCategoricalFields };

package/src/nodes/state-change-detector/index.js

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

package/src/nodes/state-change-detector/init.js

@@ -0,0 +1,56 @@
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    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 names and count
+    state.fieldNames = spec.from.x;
+    state.fieldCount = state.fieldNames.length;
+
+    // Guards (apply defaults from introspect)
+    const defaults = introspect.DEFAULT_OPTIONS;
+    state.debounce = spec.debounce ?? defaults.debounce;
+
+    // Change detection mode (store as boolean for performance)
+    const changeMode = spec.changeMode ?? defaults.changeMode;
+    state.changeMode = ( changeMode === 'all' );  // true='all', false='any'
+
+    // Timestamp handling
+    state.useTimestampField = spec.timestampField !== undefined;
+    state.timestampField = spec.timestampField || null;
+
+    // Stats configuration
+    state.stats = spec.stats;
+
+    // Pre-allocate state tracking (NO allocations in hot path)
+    state.prevValues = Object.create( null );
+    for ( let i = 0; i < state.fieldCount; i += 1 ) {
+        const field = state.fieldNames[ i ];
+        state.prevValues[ field ] = null;
+    }
+
+    // Debounce and timing state
+    state.debounceCount = 0;
+    state.stateStartTime = null;
+    state.samplesInState = 0;
+
+    // stats to be published
+    state.dwellTime = null;
+    state.dwellSamples = null;
+
+    // Node metadata
+    state.nodeType = introspect.getNodeType();
+    state.resolvedTriggers = [];
+
+    return state;
+}; // init()
+
+export default init;