@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/categorize/introspect.js

@@ -0,0 +1,177 @@
+/**
+ * @fileoverview Introspection metadata for categorize node.
+ *
+ * Defines supported stats (category, index), control methods, capabilities,
+ * DSL schema with cross-field validators, and tunable params (thresholds).
+ * All getters return defensive copies.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+import { resolveArray } from '../../core/utils/options/resolve-field-keyed.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'category',  // Assigned category name (string)
+    'index'      // Category index (number: 0, 1, 2, ...)
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    category: 'Assigned category name based on threshold comparison',
+    index: 'Zero-based index of the assigned category for efficient comparisons'
+};
+
+/** 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 = 'Categorize';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Assigns numeric values to discrete categories using threshold boundaries',
+    features: [
+        'Deterministic threshold-based categorization',
+        'Outputs both category name and numeric index',
+        'O(n) linear search for typical threshold counts',
+        'Validates threshold ordering at initialization',
+        'Handles out-of-range values gracefully'
+    ]
+};
+
+/** Spec default values */
+export const DEFAULT_OPTIONS = {
+    // No defaults needed for this node
+};
+
+/** Parameters that support tunable (dynamic) values */
+export const TUNABLE_PARAMS = [ 'thresholds' ];
+
+// 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'
+                }
+            }
+        },
+        thresholds: {
+            type: 'arrayOrFunctionOrFieldKeyed',
+            required: true,
+            minItems: 1,
+            // Supports tunable for shift/mode-based category boundaries
+            itemSchema: {
+                type: 'number',
+                validator: validators.isFinite,
+                error: 'Threshold values must be finite numbers'
+            }
+        },
+        categories: {
+            type: 'arrayOrFieldKeyed',
+            required: true,
+            minItems: 2,
+            itemSchema: {
+                type: 'string',
+                minLength: 1,
+                error: 'Category names must be non-empty strings'
+            }
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                required: true,
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'thresholds', 'categories' ],
+            // Must have exactly n+1 categories for n thresholds (skip if thresholds is function).
+            // Resolve both for the node's field the way the runtime does, so a direct
+            // array and a field-keyed map are checked the same way.
+            validator: ( spec ) => {
+                if ( typeof spec.thresholds === 'function' ) return true;
+                const t = resolveArray( spec.thresholds, spec.from?.x );
+                const c = resolveArray( spec.categories, spec.from?.x );
+                if ( !Array.isArray( t ) || !Array.isArray( c ) ) return false;
+                return c.length === ( t.length + 1 );
+            },
+            error: 'Categories array must have exactly one more element than thresholds array'
+        },
+        {
+            fields: [ 'thresholds' ],
+            validator: ( spec ) => {
+                // If thresholds is a function, validation deferred to runtime
+                if ( typeof spec.thresholds === 'function' ) return true;
+                // Resolve for the node's field; the count validator owns the
+                // "did not resolve to an array" error, so defer here.
+                const t = resolveArray( spec.thresholds, spec.from?.x );
+                if ( !Array.isArray( t ) ) return true;
+                // Thresholds must be in strictly ascending order
+                for ( let i = 1; i < t.length; i += 1 ) {
+                    if ( t[ i ] <= t[ i - 1 ] ) return false;
+                }
+                return true;
+            },
+            error: 'Thresholds must be in strictly ascending order with no duplicates'
+        }
+    ],
+
+    // How to build the spec from DSL params
+    buildSpec: ( name, x, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x },
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

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

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Publish function for categorize node.
+ *
+ * Copies the assigned category name and/or index to the output message.
+ * Propagates NaN via publishNaN when the last input was invalid.
+ * Skipped entirely when the node is 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;
+    }
+
+    // Publish requested stats
+    if ( state.stats.category ) {
+        msg[ state.stats.category.storeAs ] = state.category;
+    }
+
+    if ( state.stats.index ) {
+        msg[ state.stats.index.storeAs ] = state.categoryIndex;
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/categorize/recompute.js

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Recompute for categorize node.
+ *
+ * No-op: categorization is computed fresh from the input value on every
+ * update — there is no accumulated state that can drift over time.
+ */
+
+const recompute = function () {
+    // Nothing to recompute - categorization is stateless
+    // No accumulations or numerical drift possible
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/categorize/reset.js

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Reset categorize node state.
+ *
+ * Restores categorization to init-time defaults: first category, cleared
+ * error flags, and reset tunable error suppression.
+ */
+
+const reset = function ( state ) {
+    state.inputValidationFailed = false;
+    state.categoryIndex = 0;
+    state.category = state.categories[ 0 ];
+    state.tunableErrorLogged = false;
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/categorize/update.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Update function for categorize node.
+ *
+ * Extracts the input value, resolves tunable thresholds for the current
+ * message, and finds the matching category via linear search. For typical
+ * threshold counts (3–5), linear search outperforms binary search.
+ */
+
+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;
+    }
+
+    // Resolve thresholds tunable for this message
+    try {
+        state.resolvedThresholds = state.thresholdsFn( msg );
+        if ( state.tunableErrorLogged ) state.tunableErrorLogged = false;
+    } catch ( error ) {
+        if ( !state.tunableErrorLogged ) {
+            state.tunableErrorLogged = true;
+            console.error( `WinkComposer/${state.nodeType}: tunable threw: ${error.message}` );
+        }
+    }
+
+    if ( !state.resolvedThresholds ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Find category using linear search
+    // For typical threshold counts (3-5), this is faster than binary search
+    // Convention: value >= threshold belongs to upper category
+    let categoryIndex = 0;
+
+    for ( categoryIndex = 0; categoryIndex < state.resolvedThresholds.length; categoryIndex += 1 ) {
+        if ( xVal < state.resolvedThresholds[ categoryIndex ] ) break;
+    }
+
+    // Update state
+    state.categoryIndex = categoryIndex;
+    state.category = state.categories[ categoryIndex ];
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/controller/index.js

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

package/src/nodes/controller/init.js

@@ -0,0 +1,55 @@
+// nodes/controller/init.js
+
+import { validateWithSchema } from '../../core/utils/validate/index.js';
+import { getDSLMetadata, getNodeType } from './introspect.js';
+
+const init = function ( spec ) {
+    // Get validation schema from introspect
+    const metadata = getDSLMetadata();
+    const schema = {
+        ...metadata.specSchema,
+        _crossFieldValidators: metadata.crossFieldValidators
+    };
+
+    // Validate spec
+    const validation = validateWithSchema( schema, spec, 'spec' );
+    validation.throwIfInvalid( getNodeType() );
+
+    // Create state after validation passes
+    const state = Object.create( null );
+
+    // Copy logic array with structure as the placeholder resolved triggers,
+    // computed during the partition time.
+    state.logic = [];
+    for ( let i = 0; i < spec.logic.length; i += 1 ) {
+        const condition = Object.create( null );
+        condition.when = spec.logic[ i ].when;
+        // Keep spec for partition manager
+        condition.triggers = spec.logic[ i ].triggers;
+        // PLACEHOLDER: will be resolved by partition manager
+        condition.resolvedTriggers = null;
+        state.logic.push( condition );
+    }
+
+    // Controller metadata
+    state.name = spec.name;
+    state.nodeType = getNodeType();
+
+    // Observability fields
+    state.lastMatchedCondition = -1;
+    state.matchCount = 0;
+    state.errorCount = 0;
+    state.lastError = null;
+
+    // Log suppression: one log per error episode; reset on recovery.
+    state.predicateErrorLogged = false;
+
+    // Control phase tracking (executeTriggers re-entrancy guard)
+    state.inControlPhase = false;
+    // Points to the matched condition's triggers during execution
+    state.resolvedTriggers = null;
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/controller/introspect.js

@@ -0,0 +1,91 @@
+// nodes/controller/introspect.js
+
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this node can do */
+const SUPPORTED_STATS = [];  // Controller doesn't publish stats
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {};  // No stats, no descriptions
+
+/** Control methods available for triggers (none - pure orchestrator) */
+const SUPPORTED_CONTROL_METHODS = {};
+
+/** Default options (none for this node) */
+const DEFAULT_OPTIONS = {};
+
+/** The type of this node */
+const NODE_TYPE = 'Controller';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Pure orchestration node that monitors messages and coordinates other nodes without modifying data',
+    features: [
+        'Multi-condition state machine support',
+        'First-match-wins execution model',
+        'Re-entrancy protected trigger execution',
+        'No data transformation - pure control flow'
+    ]
+};
+
+// 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 and validation
+const DSL_METADATA = {
+    specSchema: {
+        nodeType: {
+            type: 'string',
+            required: true,
+            value: NODE_TYPE
+        },
+        name: {
+            type: 'string',
+            required: true,
+            validator: validators.identifier,
+            error: 'Name must be a valid JavaScript identifier'
+        },
+        logic: {
+            type: 'array',
+            required: true,
+            minItems: 1,
+            itemSchema: {
+                type: 'object',
+                properties: {
+                    when: {
+                        type: 'function',
+                        required: true,
+                        arity: 1,
+                        error: 'when must be a predicate function with one parameter'
+                    },
+                    triggers: {
+                        type: 'array',
+                        required: true,
+                        minItems: 1,
+                        itemSchema: {
+                            type: 'object',
+                            validator: composerValidators.trigger,
+                            error: 'Invalid trigger specification'
+                        }
+                    }
+                }
+            }
+        }
+    },
+
+    crossFieldValidators: [],  // No cross-field validation needed
+
+    buildSpec: ( name, logic ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            logic
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );
+export { DEFAULT_OPTIONS };

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

@@ -0,0 +1,8 @@
+// nodes/controller/publish-to.js
+
+const publishTo = function ( _state, _msg ) {
+    // Controller is pure orchestration - it doesn't publish any data
+    // Messages pass through unchanged
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/controller/recompute.js

@@ -0,0 +1,9 @@
+// nodes/controller/recompute.js
+
+const recompute = function ( _state ) {
+    // Controller has no numerical state to recompute
+    // All state is discrete (counters, flags)
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/controller/reset.js

@@ -0,0 +1,17 @@
+// nodes/controller/reset.js
+
+const reset = function ( state ) {
+    // Reset observability counters
+    state.lastMatchedCondition = -1;
+    state.matchCount = 0;
+    state.errorCount = 0;
+    state.lastError = null;
+    // Clear error suppression so next error episode is logged
+    state.predicateErrorLogged = false;
+
+    // Note: We don't reset logic or resolvedTriggers
+    // as they are structural, not runtime state
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/controller/update.js

@@ -0,0 +1,63 @@
+// nodes/controller/update.js
+
+import { executeTriggers } from '../../core/utils/node/index.js';
+
+const update = function ( state, msg ) {
+    // Track whether any predicate threw during this pass
+    let anyError = false;
+
+    // Iterate through conditions in order
+    for ( let i = 0; i < state.logic.length; i += 1 ) {
+        const condition = state.logic[ i ];
+
+        // Evaluate predicate with error handling
+        let predicateResult = false;
+        try {
+            predicateResult = condition.when( msg );
+        } catch ( error ) {
+            anyError = true;
+            // Track predicate errors
+            state.errorCount += 1;
+            state.lastError = error.message;
+            // Log first error per episode; suppress subsequent until recovery
+            if ( !state.predicateErrorLogged ) {
+                state.predicateErrorLogged = true;
+                console.error( `WinkComposer/controller: predicate threw exception: ${error.message}` );
+            }
+            // Skip to next condition
+            continue;  // eslint-disable-line no-continue
+        }
+
+        // Check if condition matches
+        if ( predicateResult === true ) {
+            // Recovery: clear flag only when entire pass is exception-free
+            if ( !anyError && state.predicateErrorLogged ) state.predicateErrorLogged = false;
+
+            // Update observability
+            state.lastMatchedCondition = i;
+            state.matchCount += 1;
+
+            // Check for resolved triggers
+            if ( !condition.resolvedTriggers || condition.resolvedTriggers.length === 0 ) {
+                return state;  // No triggers to execute
+            }
+
+            // Point to this condition's triggers; it is an executeTriggers' requirement.
+            state.resolvedTriggers = condition.resolvedTriggers;
+
+            // Execute triggers with re-entrancy protection
+            executeTriggers( state );
+
+            // First match wins - stop processing
+            return state;
+        }
+    }
+
+    // Recovery: clear flag only when entire pass is exception-free
+    if ( !anyError && state.predicateErrorLogged ) state.predicateErrorLogged = false;
+
+    // No conditions matched
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/diff/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Entry point for diff 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/diff/init.js

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Initialization for diff node.
+ *
+ * Validates the spec, extracts field names and the absolute option,
+ * and returns the fully initialized state object.
+ */
+
+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 name & option.
+    state.x = spec.from.x;
+    state.y = spec.from.y;
+    state.absolute = spec.absolute ?? introspect.DEFAULT_OPTIONS.absolute;
+
+    // Config copy.
+    state.stats = spec.stats;
+
+    // State variables.
+    state.diff = 0;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;