@winkjs/composer 0.5.0 → 0.6.0

package/src/nodes/archive/csv/test.js

@@ -1,173 +0,0 @@
-// nodes/csv-source/test.js
-import * as csvSource from './index.js';
-import loadCSV from './load.js';
-
-// Sample CSV data for testing
-const sampleCSV = `timestamp,temperature,pressure,humidity,location
-2024-01-01T00:00:00,23.5,1013.25,65,sensor_01
-2024-01-01T00:00:10,23.7,1013.20,64,sensor_01
-2024-01-01T00:00:20,24.1,1013.15,63,sensor_01
-2024-01-01T00:00:30,24.5,1013.10,62,sensor_01
-2024-01-01T00:00:40,25.2,1013.05,61,sensor_01`;
-
-// Test 1: Basic initialization and loading
-console.log('=== Test 1: Basic CSV Loading ===');
-const basicSpec = {
-    source: sampleCSV,  // Embedded CSV data
-    mode: 'batch',      // Get all at once
-    parseOptions: {
-        header: true,
-        dynamicTyping: true,
-        skipEmptyLines: true
-    }
-};
-
-const basicState = csvSource.init( basicSpec );
-console.log( 'Initial state:', {
-    mode: basicState.mode,
-    isLoaded: basicState.isLoaded,
-    currentIndex: basicState.currentIndex
-});
-
-// Load the CSV data
-await loadCSV( basicState );
-console.log( `Loaded ${basicState.data.length} rows` );
-console.log( 'First row:', basicState.data[0] );
-console.log( 'Data types:', Object.entries( basicState.data[0] ).map(
-    ([ k, v ]) => `${k}: ${typeof v}`
-));
-
-// Test 2: Message generation
-console.log( '\n=== Test 2: Message Generation ===');
-const msg1 = csvSource.update( basicState, {} );
-console.log( 'Message 1:', msg1 );
-
-const msg2 = csvSource.update( basicState, {} );
-console.log( 'Message 2:', msg2 );
-
-// Test 3: Stream mode with rate limiting
-console.log( '\n=== Test 3: Stream Mode ===');
-const streamSpec = {
-    source: sampleCSV,
-    mode: 'stream',
-    rate: 100,  // 100 messages per second
-    loop: true,
-    parseOptions: {
-        header: true,
-        dynamicTyping: true
-    }
-};
-
-const streamState = csvSource.init( streamSpec );
-await loadCSV( streamState );
-
-// Simulate rapid updates - should be rate limited
-const startTime = Date.now();
-let messageCount = 0;
-
-for ( let i = 0; i < 10; i += 1 ) {
-    const msg = csvSource.update( streamState, {} );
-    if ( msg ) {
-        messageCount += 1;
-        console.log( `Stream message ${messageCount}:`, msg._source );
-    }
-    // Small delay to show rate limiting
-    await new Promise( (resolve) => setTimeout( resolve, 5 ) );
-}
-
-const elapsed = Date.now() - startTime;
-console.log( `Generated ${messageCount} messages in ${elapsed}ms` );
-console.log( `Effective rate: ${(messageCount / elapsed * 1000).toFixed(1)} msg/sec` );
-
-// Test 4: Loop behavior
-console.log( '\n=== Test 4: Loop Behavior ===');
-const loopState = csvSource.init({
-    source: sampleCSV,
-    mode: 'batch',
-    loop: true
-});
-await loadCSV( loopState );
-
-// Read all messages twice to test looping
-console.log( 'First pass:' );
-for ( let i = 0; i < 5; i += 1 ) {
-    const msg = csvSource.update( loopState, {} );
-    console.log( `  Row ${i + 1}: temp=${msg.temperature}°C` );
-}
-
-console.log( 'Second pass (should loop):' );
-for ( let i = 0; i < 3; i += 1 ) {
-    const msg = csvSource.update( loopState, {} );
-    console.log( `  Row ${i + 1}: temp=${msg.temperature}°C` );
-}
-
-// Test 5: Column mapping
-console.log( '\n=== Test 5: Column Mapping ===');
-const mappedState = csvSource.init({
-    source: sampleCSV,
-    columns: {
-        'temperature': 'temp',
-        'pressure': 'press',
-        'location': 'id'
-    }
-});
-await loadCSV( mappedState );
-
-const mappedMsg = csvSource.update( mappedState, {} );
-console.log( 'Mapped message:', mappedMsg );
-console.log( 'Should have: temp, press, id fields' );
-
-// Test 6: CSV with different delimiter
-console.log( '\n=== Test 6: Tab-Delimited CSV ===');
-const tabCSV = `name	age	score
-John Doe	30	95.5
-Jane Smith	25	87.3`;
-
-const tabState = csvSource.init({
-    source: tabCSV,
-    parseOptions: {
-        delimiter: '\t',
-        header: true,
-        dynamicTyping: true
-    }
-});
-await loadCSV( tabState );
-
-const tabMsg = csvSource.update( tabState, {} );
-console.log( 'Tab-delimited data:', tabMsg );
-
-// Test 7: File loading simulation (Node.js only)
-if ( typeof process === 'object' ) {
-    console.log( '\n=== Test 7: File Loading (Node.js) ===');
-
-    // Create a temporary CSV file
-    const fs = await import( 'fs/promises' );
-    const tempFile = './test-data.csv';
-    await fs.writeFile( tempFile, sampleCSV );
-
-    const fileState = csvSource.init({
-        source: tempFile,
-        mode: 'batch'
-    });
-
-    await loadCSV( fileState );
-    console.log( `Loaded ${fileState.data.length} rows from file` );
-
-    // Clean up
-    await fs.unlink( tempFile );
-}
-
-// Test 8: Reset functionality
-console.log( '\n=== Test 8: Reset ===');
-console.log( 'Before reset:', {
-    currentIndex: basicState.currentIndex,
-    isLoaded: basicState.isLoaded
-});
-
-csvSource.reset( basicState );
-console.log( 'After reset:', {
-    currentIndex: basicState.currentIndex,
-    isLoaded: basicState.isLoaded
-});
-
-console.log( '\n✅ All tests completed!' );

package/src/nodes/archive/csv/update.js

@@ -1,63 +0,0 @@
-// nodes/csv-source/update.js
-const update = function ( state, msg ) {
-    // Source nodes are special - they generate messages
-    // The msg parameter here is typically a trigger/timer signal
-
-    if ( !state.isLoaded || state.isPaused ) {
-        return null;  // Nothing to emit
-    }
-
-    if ( state.currentIndex >= state.data.length ) {
-        if ( state.loop ) {
-            state.currentIndex = 0;  // Reset to beginning
-        } else {
-            state.isPaused = true;  // Stop emitting
-            return null;
-        }
-    }
-
-    // Rate limiting for stream mode
-    if ( state.mode === 'stream' ) {
-        const now = Date.now();
-        const timeSinceLastEmit = now - state.lastEmitTime;
-        const minInterval = 1000 / state.rate;
-
-        if ( timeSinceLastEmit < minInterval ) {
-            return null;  // Too soon, skip this update
-        }
-
-        state.lastEmitTime = now;
-    }
-
-    // Get next row
-    const row = state.data[ state.currentIndex ];
-    state.currentIndex += 1;
-
-    // Create output message
-    const output = Object.create( null );
-
-    // Add metadata
-    output._source = {
-        type: 'csv',
-        index: state.currentIndex - 1,
-        total: state.data.length,
-        timestamp: Date.now()
-    };
-
-    // Map columns
-    if ( state.columns === 'auto' ) {
-        // Use all columns as-is
-        Object.assign( output, row );
-    } else {
-        // Custom column mapping
-        for ( const [ csvCol, msgField ] of Object.entries( state.columns ) ) {
-            if ( row.hasOwnProperty( csvCol ) ) {
-                output[ msgField ] = row[ csvCol ];
-            }
-        }
-    }
-
-    return output;  // This will be the new message
-}; // update()
-
-export default update;

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

@@ -1,7 +0,0 @@
-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

@@ -1,105 +0,0 @@
-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;

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

@@ -1,134 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,69 +0,0 @@
-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

@@ -1,36 +0,0 @@
-// 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

@@ -1,31 +0,0 @@
-// 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 };