@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/tally/index.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Entry point for the tally node. Re-exports lifecycle functions,
+ * the shared control signals, 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';
+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';
+export * from './introspect.js';

package/src/nodes/tally/init.js

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Initializes tally node state from a validated spec. Pre-resolves
+ * the field-name list and keeps state.stats so publishTo() / publishNaN() can
+ * target every configured output. Stateless: no buffers, no temporal state.
+ */
+
+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 );
+    state.inputValidationFailed = false;
+    state.disable = false;
+    state.pause = false;
+
+    state.fields = spec.from.x.slice( 0 );
+    state.n = state.fields.length;
+    state.stats = spec.stats;
+
+    // Computed outputs (fixed shape, overwritten each tick).
+    state.any = false;
+    state.all = false;
+    state.count = 0;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/tally/introspect.js

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Single source of truth for the tally node — supported stats,
+ * capabilities, control methods, and the DSL/validation schema. All getters
+ * return defensive copies. `tally` is the logical member of the cross-field
+ * family: it reduces N flag fields of one message to a single logical answer —
+ * is any flag true (`any`), are all flags true (`all`), how many are true
+ * (`count`). Flags are read by truthiness; a `NaN` flag is the one fault and
+ * propagates as NaN to every output. `ratio` (two numeric fields) and
+ * `unbalance` (N numeric fields, spread) are the numeric members of the family.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+const SUPPORTED_STATS = [
+    'any',
+    'all',
+    'count'
+];
+
+const STAT_DESCRIPTIONS = {
+    any: 'True if at least one input flag is truthy',
+    all: 'True only if every input flag is truthy',
+    count: 'How many input flags are truthy'
+};
+
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'No-op (stateless node)',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses update() while keeping last values visible via publishTo()',
+    unpause: 'Resumes update() after pause'
+};
+
+const NODE_TYPE = 'Tally';
+
+const CAPABILITIES = {
+    description: 'Instantaneous logical reduce over N flag fields in one message — any / all / count',
+    features: [
+        'Stateless and allocation-free',
+        'Domain-agnostic (any boolean or truthy/falsy flag fields)',
+        'Reads flags by truthiness; null / undefined / false / 0 count as not-true',
+        'NaN propagation for fault isolation (a NaN flag -> every output NaN)',
+        'Single pass: the count of truthy flags drives any (count >= 1) and all (count === N)'
+    ]
+};
+
+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() } );
+
+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 identifier'
+        },
+        from: {
+            type: 'object',
+            required: true,
+            properties: {
+                x: {
+                    type: 'array',
+                    required: true,
+                    minItems: 1,
+                    itemSchema: {
+                        type: 'string',
+                        validator: validators.noSpaces,
+                        error: 'field names 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'
+                    }
+                }
+            }
+        }
+    },
+
+    crossFieldValidators: [
+        {
+            fields: [ 'from.x' ],
+            validator: ( spec ) => ( new Set( spec.from.x ).size === spec.from.x.length ),
+            error: 'field names must be unique'
+        }
+    ],
+
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...options
+    } )
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

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

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Copies the computed tally reductions onto the message, or
+ * propagates NaN to every configured output when the last input was a NaN flag.
+ * Skipped when disabled; still runs when paused so last values stay visible.
+ */
+
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+
+    const stats = state.stats;
+    if ( stats.any ) {
+        msg[ stats.any.storeAs ] = state.any;
+    }
+    if ( stats.all ) {
+        msg[ stats.all.storeAs ] = state.all;
+    }
+    if ( stats.count ) {
+        msg[ stats.count.storeAs ] = state.count;
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/tally/recompute.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Recompute for the tally node. The reduction is exact and
+ * stateless — there is no incremental drift to correct — so recompute is a no-op.
+ */
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/tally/reset.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Reset for the tally node. Nothing accumulates — every output is
+ * recomputed from scratch each tick — so reset is a no-op.
+ */
+
+const reset = function () {
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/tally/update.js

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Hot path for the tally node.
+ *
+ * One linear pass reads each flag field by truthiness and counts the truthy
+ * flags. The three reductions follow from that count with no second pass:
+ * count is the number itself, any is ( count > 0 ), all is ( count === n ).
+ *
+ * Fault handling: a flag is read by truthiness, so null, undefined, false and 0
+ * are not-true ( in composer null/undefined mean "no value this tick", not bad
+ * data ). The one fault is NaN — a flag goes NaN only when its own producer
+ * faulted — which marks the tick invalid so publishTo writes NaN to every output.
+ * This is why the guard is Number.isNaN, not the numeric Number.isFinite.
+ */
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    state.inputValidationFailed = false;
+
+    const fields = state.fields;
+    const n = state.n;
+
+    let trueCount = 0;
+    let i = 0;
+
+    while ( i < n ) {
+        const v = msg[ fields[ i ] ];
+        if ( Number.isNaN( v ) ) {
+            state.inputValidationFailed = true;
+            return state;
+        }
+        if ( v ) {
+            trueCount += 1;
+        }
+        i += 1;
+    }
+
+    state.count = trueCount;
+    state.any = ( trueCount > 0 );
+    state.all = ( trueCount === n );
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/threshold/index.js

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

@@ -0,0 +1,121 @@
+// nodes/threshold/init.js
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+import { asTunable } from '../../core/tunable/index.js';
+
+// Mode handler functions - pure functions for threshold checking
+const MODE_HANDLERS = {
+    above: function (value, state) {
+        if (state.hasHysteresis) {
+            // With hysteresis: different thresholds for activation/deactivation
+            return state.active ?
+                value >= (state.threshold - state.hysteresis) :   // Stay active until below reset point (inclusive)
+                value >= state.threshold;                       // Activate at threshold
+        }
+        // Simple threshold
+        return value >= state.threshold;
+    },
+
+    below: function (value, state) {
+        if (state.hasHysteresis) {
+            // With hysteresis: opposite direction from 'above'
+            return state.active ?
+                value <= (state.threshold + state.hysteresis) : // Stay active until above reset point (inclusive)
+                value <= state.threshold;                       // Activate at threshold
+        }
+        // Simple threshold
+        return value <= state.threshold;
+    },
+
+    outside: function (value, state) {
+        if (state.hasHysteresis) {
+            // With hysteresis: need to come further inside to deactivate
+            if (state.active) {
+                // Currently active (outside) - need to come well inside to deactivate
+                return value <= (state.min + state.hysteresis) || value >= (state.max - state.hysteresis);
+            }
+            // Currently inactive (inside) - activate when going outside original bounds
+            return value < state.min || value > state.max;
+        }
+        // Simple range check
+        return value < state.min || value > state.max;
+    },
+
+    inside: function (value, state) {
+        if (state.hasHysteresis) {
+            // With hysteresis: expand range for deactivation
+            return state.active ?
+                value >= (state.min - state.hysteresis) && value <= (state.max + state.hysteresis) :
+                value >= state.min && value <= state.max;
+        }
+        // Simple range check
+        return value >= state.min && value <= state.max;
+    }
+};
+
+const init = function (spec) {
+    validateSpec( spec, introspect );
+
+    // Create state after validation passes
+    const state = Object.create(null);
+    // Ensure node is enabled by default
+    state.disable = false;
+    state.pause = false;
+
+    // Extract common configuration
+    state.x = spec.from.x;
+    state.mode = spec.mode;
+
+    // Apply defaults from introspect (validation doesn't enforce them)
+    // Supports direct, field-keyed, and tunable specification
+    const hysteresisSpec = resolveScalar( spec.hysteresis, state.x );
+    state.hysteresisFn = asTunable( hysteresisSpec ?? introspect.DEFAULT_OPTIONS.hysteresis );
+
+    // Store mode-specific parameters (supports field-keying and tunables)
+    if ( spec.mode === 'above' || spec.mode === 'below' ) {
+        const thresholdSpec = resolveScalar( spec.threshold, state.x );
+        state.thresholdFn = asTunable( thresholdSpec );
+    } else {
+        const minSpec = resolveScalar( spec.min, state.x );
+        const maxSpec = resolveScalar( spec.max, state.x );
+        state.minFn = asTunable( minSpec );
+        state.maxFn = asTunable( maxSpec );
+    }
+
+    // Seed tunable state fields — overwritten on every successful update().
+    // hysteresis has a DEFAULT_OPTIONS entry; threshold/min/max are required
+    // user values with no defaults — undefined keeps node inactive until
+    // first successful resolve (value >= undefined → false in all modes).
+    state.hysteresis = introspect.DEFAULT_OPTIONS.hysteresis;
+    state.hasHysteresis = false;
+    if ( spec.mode === 'above' || spec.mode === 'below' ) {
+        state.threshold = undefined;
+    } else {
+        state.min = undefined;
+        state.max = undefined;
+    }
+    // Log suppression: one log per error episode; reset on recovery.
+    state.tunableErrorLogged = false;
+
+    // Config copy
+    state.stats = spec.stats;
+
+    // State variables - clear boolean semantics
+    state.active = false;       // Current state
+    state.wasActive = false;    // Previous state (for trigger detection)
+
+    // For hysteresis, we need to know if we've seen any values yet
+    state.hasSeenValue = false;
+
+    // Assign the appropriate handler function based on mode (no allocation, just reference)
+    state.checkActive = MODE_HANDLERS[spec.mode];
+
+    state.nodeType = introspect.getNodeType();
+    state.inControlPhase = false;
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/threshold/introspect.js

@@ -0,0 +1,192 @@
+// nodes/threshold/introspect.js
+
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'active'       // Current state - the only output
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    active: 'Boolean state indicating if threshold condition is currently met'
+};
+
+/** Supported threshold modes */
+const THRESHOLD_MODES = [ 'above', 'below', 'inside', 'outside' ];
+
+/** 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 = 'Threshold';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Multi-mode threshold detection with optional hysteresis for stable state transitions',
+    features: [
+        'Mode: above - Activates when value exceeds threshold',
+        'Mode: below - Activates when value falls below threshold',
+        'Mode: inside - Activates when value is within range',
+        'Mode: outside - Activates when value is outside range',
+        'Hysteresis support for chatter-free operation'
+    ]
+};
+
+// 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() } );
+export const getThresholdModes = () => THRESHOLD_MODES.slice();
+
+export const DEFAULT_OPTIONS = {
+    hysteresis: 0
+};
+
+/** Parameters that support tunable (dynamic) values */
+export const TUNABLE_PARAMS = [ 'threshold', 'min', 'max', 'hysteresis' ];
+
+// 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'
+                }
+            }
+        },
+        mode: {
+            type: 'string',
+            required: true,
+            validator: validators.oneOf(THRESHOLD_MODES),
+            error: `Mode must be one of: ${THRESHOLD_MODES.join(', ')}`
+        },
+        // For 'above' and 'below' modes (supports tunable for adaptive thresholds)
+        threshold: {
+            type: 'numberOrFunctionOrFieldKeyed',
+            required: false,  // Validated by cross-field validator
+            validator: ( value ) => typeof value === 'function' || ( !isNaN( value ) && isFinite( value ) ),
+            error: 'Threshold must be a finite number or function'
+        },
+        // For 'inside' and 'outside' modes (supports tunable for adaptive ranges)
+        min: {
+            type: 'numberOrFunctionOrFieldKeyed',
+            required: false,  // Validated by cross-field validator
+            validator: ( value ) => typeof value === 'function' || ( !isNaN( value ) && isFinite( value ) ),
+            error: 'Min must be a finite number or function'
+        },
+        max: {
+            type: 'numberOrFunctionOrFieldKeyed',
+            required: false,  // Validated by cross-field validator
+            validator: ( value ) => typeof value === 'function' || ( !isNaN( value ) && isFinite( value ) ),
+            error: 'Max must be a finite number or function'
+        },
+        // Optional hysteresis for all modes (supports tunable for adaptive hysteresis)
+        hysteresis: {
+            type: 'numberOrFunctionOrFieldKeyed',
+            required: false,
+            default: 0,
+            validator: validators.nonNegativeOrFunction,
+            error: 'Hysteresis must be a non-negative finite number or function'
+        },
+        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'
+                    }
+                }
+            }
+        },
+        triggers: {
+            type: 'array',
+            required: false,
+            itemSchema: {
+                type: 'object',
+                validator: composerValidators.trigger,
+                error: 'Invalid trigger specification'
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'mode', 'threshold', 'min', 'max' ],
+            validator: ( spec ) => {
+                // For 'above' and 'below' modes, require threshold
+                if ( spec.mode === 'above' || spec.mode === 'below' ) {
+                    if ( spec.threshold === undefined ) return false;
+                    // These modes should not have min/max
+                    if ( spec.min !== undefined || spec.max !== undefined ) return false;
+                }
+                // For 'inside' and 'outside' modes, require min and max
+                if ( spec.mode === 'inside' || spec.mode === 'outside' ) {
+                    if ( spec.min === undefined || spec.max === undefined ) return false;
+                    // These modes should not have threshold
+                    if ( spec.threshold !== undefined ) return false;
+                    // Resolve for the node's field so a direct value and a field-keyed
+                    // map are compared the same way; min must be less than max
+                    // (skip the comparison when either resolves to a function).
+                    const min = resolveScalar( spec.min, spec.from?.x );
+                    const max = resolveScalar( spec.max, spec.from?.x );
+                    if ( typeof min !== 'function' && typeof max !== 'function' ) {
+                        if ( min >= max ) return false;
+                    }
+                }
+                return true;
+            },
+            error: 'Invalid parameters for mode. Above/below need threshold. Inside/outside need min and max (min < max).'
+        },
+        composerValidators.noSelfTriggers
+    ],
+
+    // 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/threshold/publish-to.js

@@ -0,0 +1,11 @@
+// nodes/threshold/publish-to.js
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    // Only publish active stat
+    if ( state.stats.active ) {
+        msg[ state.stats.active.storeAs ] = state.active;
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/threshold/recompute.js

@@ -0,0 +1,8 @@
+// nodes/threshold/recompute.js
+
+const recompute = function () {
+    // Nothing to recompute - threshold is stateless except for hysteresis memory
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/threshold/reset.js

@@ -0,0 +1,14 @@
+// nodes/threshold/reset.js
+
+const reset = function ( state ) {
+    // Reset to initial conditions
+    state.active = false;
+    state.wasActive = false;
+    state.hasSeenValue = false;
+    // Clear error suppression so next error episode is logged
+    state.tunableErrorLogged = false;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/threshold/update.js

@@ -0,0 +1,54 @@
+// nodes/threshold/update.js
+
+import { executeTriggers } from '../../core/utils/node/index.js';
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    // Extract value using field name
+    const xVal = msg[ state.x ];
+
+    // Skip if not a valid number (different from regular NaN publishing)
+    if ( !Number.isFinite( xVal ) ) return state;
+
+    // Guard tunable resolve — on throw, state retains previous good value
+    // (JS: RHS evaluated first; failed RHS ⇒ assignment never executes).
+    try {
+        state.hysteresis = state.hysteresisFn( msg );
+        state.hasHysteresis = state.hysteresis > 0;
+        if ( state.thresholdFn ) {
+            state.threshold = state.thresholdFn( msg );
+        } else {
+            state.min = state.minFn( msg );
+            state.max = state.maxFn( msg );
+        }
+        // Recovery: clear log-suppression flag on success
+        if ( state.tunableErrorLogged ) state.tunableErrorLogged = false;
+    } catch ( error ) {
+        // Log first error per episode; suppress subsequent until recovery
+        if ( !state.tunableErrorLogged ) {
+            state.tunableErrorLogged = true;
+            console.error( `WinkComposer/${state.nodeType}: tunable threw: ${error.message}` );
+        }
+    }
+
+    // Remember previous state for trigger detection
+    state.wasActive = state.active;
+
+    // Update threshold state using mode-specific handler
+    if ( state.hasSeenValue ) {
+        state.active = state.checkActive( xVal, state );
+    } else {
+        // First value - compute initial state
+        state.active = state.checkActive( xVal, state );
+        state.hasSeenValue = true;
+    }
+
+    // Trigger controls on activation if configured (rising edge only)
+    if ( state.active && !state.wasActive ) {
+        executeTriggers( state );
+    }
+
+    return state;
+}; // update()
+
+export default update;