@winkjs/composer 0.0.2 → 0.4.0

package/src/flow/check-output-collisions.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Build-time guard against output-field overwrites.
+ *
+ * Two nodes on the same runtime path must not write the same message field. If they
+ * did, the second node's `publishTo` would overwrite the first node's value silently.
+ * This module finds such collisions at build time so the flow fails loudly instead.
+ *
+ * A flow has these runtime paths: a flow with no `.switch()`/`.groupBy()` is one
+ * linear path (every node runs on every message); a switched flow is one path per
+ * case (only one case runs per message), and `.switch()`/`.groupBy()` forbid any node
+ * before the switch, so a case has no shared prefix to merge in. So uniqueness is
+ * checked within each path, never across paths: the same field written by two sibling
+ * cases is fine, because only one of those cases runs for a given message.
+ *
+ * Scope: this checks declared outputs - the `storeAs` names in a spec's `stats`. That
+ * is exactly what the fan naming rule (`${field}_${label}`) produces. It does not
+ * cover a node that derives its output field names from its input field at init time
+ * (for example `momentsDigest`, which writes `${field}_M1`, `${field}_mean`, and so
+ * on, with no `stats` in its spec). Catching those needs each node to declare the
+ * fields it writes; that is tracked as a separate follow-up.
+ *
+ * @see flow.js - build()/run()/validate() call these before producing or running a flow
+ */
+
+/**
+ * Record one spec's declared outputs against the path's owner map, appending an error
+ * for any field a previous node on this path already writes.
+ *
+ * @param {Object} spec - A built spec with a `stats` object
+ * @param {Object} owner - Map of storeAs -> first node name that writes it (mutated)
+ * @param {string[]} errors - Collision messages (mutated)
+ * @param {string} scopeLabel - Text appended to the field name in the error
+ */
+const recordSpecOutputs = function ( spec, owner, errors, scopeLabel ) {
+    // eslint-disable-next-line guard-for-in
+    for ( const stat in spec.stats ) {
+        const storeAs = spec.stats[ stat ].storeAs;
+        if ( owner[ storeAs ] === undefined ) {
+            owner[ storeAs ] = spec.name;
+        } else {
+            errors.push(
+                `output field '${storeAs}'${scopeLabel} is written by two nodes on the ` +
+                `same path: '${owner[ storeAs ]}' and '${spec.name}'. The second write would ` +
+                'overwrite the first. Give them distinct output labels.'
+            );
+        }
+    }
+}; // recordSpecOutputs()
+
+/**
+ * Find duplicate output fields within one path's specs.
+ *
+ * @param {Array} specs - The specs on one runtime path (linear flow or one case)
+ * @param {string} scopeLabel - Text appended to the field name in the error (for
+ *                              example ` in case 'idle'`); empty for a linear flow
+ * @returns {string[]} One message per collision; empty when the path is clean
+ */
+export const findOutputCollisions = function ( specs, scopeLabel ) {
+    const owner = Object.create( null );  // storeAs -> name of the node that writes it
+    const errors = [];
+
+    for ( let i = 0; i < specs.length; i += 1 ) {
+        const spec = specs[ i ];
+        if ( spec.stats ) {
+            recordSpecOutputs( spec, owner, errors, scopeLabel );
+        }
+    }
+
+    return errors;
+}; // findOutputCollisions()
+
+/**
+ * Find output-field collisions across a whole flow, one path at a time.
+ *
+ * @param {Object} switchState - The flow's switch/case state
+ * @param {Array} flowDefinition - The linear flow's specs (used when not switched)
+ * @returns {string[]} One message per collision across all paths; empty when clean
+ */
+export const collectFlowOutputCollisions = function ( switchState, flowDefinition ) {
+    if ( switchState.active ) {
+        const errors = [];
+        for ( let i = 0; i < switchState.caseOrder.length; i += 1 ) {
+            const key = switchState.caseOrder[ i ];
+            const caseErrors = findOutputCollisions( switchState.caseSpecs[ key ], ` in case '${key}'` );
+            for ( let j = 0; j < caseErrors.length; j += 1 ) {
+                errors.push( caseErrors[ j ] );
+            }
+        }
+        return errors;
+    }
+
+    return findOutputCollisions( flowDefinition, '' );
+}; // collectFlowOutputCollisions()

package/src/flow/consts.js

@@ -0,0 +1,9 @@
+export const SIGNATURE_PATTERNS = Object.create( null );
+SIGNATURE_PATTERNS.nameLogic = 'NAME_LOGIC';
+SIGNATURE_PATTERNS.namePredicateOutputsOptions = 'NAME_PREDICATE_OUTPUTS_OPTIONS';
+SIGNATURE_PATTERNS.namePredicateOptions = 'NAME_PREDICATE_OPTIONS';
+SIGNATURE_PATTERNS.nameXOutputsOptions = 'NAME_X_OUTPUTS_OPTIONS';
+SIGNATURE_PATTERNS.nameXYOutputsOptions = 'NAME_X_Y_OUTPUTS_OPTIONS';
+SIGNATURE_PATTERNS.nameSugarOutputsOptions = 'NAME_SUGAR_OUTPUTS_OPTIONS';
+SIGNATURE_PATTERNS.nameXOptions = 'NAME_X_OPTIONS';
+SIGNATURE_PATTERNS.unknown = 'UNK_PATTERN';

package/src/flow/deep-clone-spec.js

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Deep clone utility for groupBy template expansion.
+ *
+ * Clones spec objects while preserving:
+ * - Functions (predicates, tunables) - kept by reference
+ * - RegExp objects - properly cloned
+ * - undefined values - preserved
+ * - Nested objects/arrays - recursively cloned
+ *
+ * Used during `.endGroup()` to create independent spec copies for each
+ * group value without sharing mutable state.
+ */
+
+/**
+ * Deep clones a value, preserving functions by reference.
+ *
+ * @param {*} value - Value to clone
+ * @returns {*} Cloned value (functions returned by reference)
+ */
+const deepCloneValue = function ( value ) {
+    // Null and undefined pass through
+    if ( value === null || value === undefined ) {
+        return value;
+    }
+
+    const type = typeof value;
+
+    // Functions - keep reference (tunables, predicates)
+    if ( type === 'function' ) {
+        return value;
+    }
+
+    // Primitives (string, number, boolean, symbol, bigint)
+    if ( type !== 'object' ) {
+        return value;
+    }
+
+    // RegExp - clone properly
+    if ( value instanceof RegExp ) {
+        // eslint-disable-next-line security/detect-non-literal-regexp -- cloning an existing RegExp; source/flags come from the object being cloned, not user input
+        return new RegExp( value.source, value.flags );
+    }
+
+    // Arrays - recurse
+    if ( Array.isArray( value ) ) {
+        const result = [];
+        for ( let i = 0; i < value.length; i += 1 ) {
+            result.push( deepCloneValue( value[ i ] ) );
+        }
+        return result;
+    }
+
+    // Objects - use null prototype for safety
+    const result = Object.create( null );
+    const keys = Object.keys( value );
+    for ( let i = 0; i < keys.length; i += 1 ) {
+        const key = keys[ i ];
+        result[ key ] = deepCloneValue( value[ key ] );
+    }
+
+    return result;
+};
+
+export { deepCloneValue };

package/src/flow/driver.js

@@ -0,0 +1,171 @@
+// flow/driver.js
+
+/**
+ * @fileoverview Headless-flow driver.
+ *
+ * A driver feeds a running flow that has no source. It plays the role a source
+ * adapter plays: it calls `handle.processMessage( msg )` once per message. It
+ * exists so callers get that contract right in one place — the sync-first call
+ * (ADR-013), awaiting only on the rare yield tick, and routing a node fault to a
+ * handler so one bad message cannot stop the loop.
+ *
+ * Hot-path allocation: none. A successful message allocates nothing. `feedOne`
+ * returns `undefined` (it is not an async function, so no Promise wrapper).
+ * `feedAll` keeps primitive counters and iterates a sync source with `for...of`
+ * (no per-item await). Faults route to a callback rather than a per-message
+ * result object. Promises are allocated only on the rare yield tick (ADR-013,
+ * ADR-024) and on faults — never on the success path (ADR-004 zero-allocation
+ * hot path). The yield-tick Promise arrives AFTER the message is fully
+ * processed (ADR-024 process-then-breathe), so ignoring it never delays or
+ * reorders a message; awaiting it is purely the event-loop breath.
+ *
+ * What it does NOT do: detect a silently dropped message. A message dropped for
+ * an over-cap asset id, or a missing assetId field, returns nothing from
+ * `processMessage`, exactly as a success does — so `feedAll` counts it as
+ * processed. See `docs/handbook/headless-flow.md`.
+ *
+ * @see docs/handbook/headless-flow.md
+ */
+
+/**
+ * Default fault handler. Surfaces every fault so none is silent. Allocates only
+ * when a fault occurs (rare), never on the success path. Provide your own
+ * `onError` to route or throttle in production.
+ *
+ * @param {Error} error - The node fault (wrapped: `error.nodeModule`,
+ *   `error.cause`).
+ * @returns {void}
+ */
+const logFault = function ( error ) {
+    console.error( `composer/headlessDriver: a message failed — ${error.message}` );
+}; // logFault()
+
+/**
+ * Create a driver bound to one headless flow handle.
+ *
+ * @param {Object} handle - Handle returned by `flow(...).run()`. Must expose a
+ *   `processMessage` function.
+ * @param {Object} [opts={}] - Options.
+ * @param {function(Error, Object): void} [opts.onError] - Called as
+ *   `onError( error, msg )` for every message that faults, in both `feedOne` and
+ *   `feedAll`. Defaults to logging the fault to the console.
+ * @returns {{feedOne: function, feedAll: function}} The driver.
+ * @throws {TypeError} When `handle` has no `processMessage`, or `onError` is
+ *   given but is not a function.
+ */
+const headlessDriver = function ( handle, opts = {} ) {
+    if ( !handle || typeof handle.processMessage !== 'function' ) {
+        throw new TypeError(
+            'composer/headlessDriver: handle must be the object returned by ' +
+            'flow(...).run() — it has no processMessage() function'
+        );
+    }
+
+    const onError = opts.onError === undefined ? logFault : opts.onError;
+    if ( typeof onError !== 'function' ) {
+        throw new TypeError(
+            'composer/headlessDriver: onError must be a function'
+        );
+    }
+
+    /**
+     * Feed one message. Use this for push sources, where an event hands you a
+     * message and there is no loop to own.
+     *
+     * Zero allocation on the success path: returns `undefined` synchronously. A
+     * fault is routed to `onError`, never thrown, so the caller's event handler
+     * is never interrupted. On the rare yield tick it returns a Promise you MAY
+     * await for backpressure; that Promise never rejects (a yield-path fault
+     * still routes to `onError`).
+     *
+     * @param {Object} msg - The message to feed.
+     * @returns {(undefined|Promise<void>)} `undefined` on the hot path; a Promise
+     *   on the yield tick.
+     */
+    const feedOne = function ( msg ) {
+        let pending;
+        try {
+            pending = handle.processMessage( msg );
+        } catch ( error ) {
+            onError( error, msg );
+            return undefined;
+        }
+        if ( pending instanceof Promise ) {
+            return pending.catch( function ( error ) {
+                onError( error, msg );
+            } );
+        }
+        return undefined;
+    }; // feedOne()
+
+    /**
+     * Feed every message from a source, in order. Use this for pull sources,
+     * where you iterate the data.
+     *
+     * Consumes any sync or async iterable — an array, a generator, an async
+     * generator, or a Node object-mode stream. A sync source is iterated with
+     * `for...of`, so it allocates nothing per message; an async source is pulled
+     * with `for await`, where a Promise per item is inherent. Each message is
+     * processed and awaited before the next begins, so the flow sees one message
+     * at a time and an async source throttles itself. A faulting message does
+     * not stop the stream: it is counted in `failed` and routed to `onError`.
+     *
+     * A failure of the source iterator itself (a stream that errors mid-read) is
+     * not caught here — it rejects the returned Promise for the caller to handle.
+     *
+     * @param {Iterable|AsyncIterable} source - Messages to feed, in order.
+     * @returns {Promise<{processed: number, failed: number}>} Counts taken after
+     *   the source is exhausted.
+     * @throws {TypeError} When `source` is not a sync or async iterable.
+     */
+    const feedAll = async function ( source ) {
+        const isAsync = typeof source?.[ Symbol.asyncIterator ] === 'function';
+        const isSync = typeof source?.[ Symbol.iterator ] === 'function';
+        if ( !isAsync && !isSync ) {
+            throw new TypeError(
+                'composer/headlessDriver.feedAll: source must be a sync or async ' +
+                'iterable (an array, a generator, or a stream)'
+            );
+        }
+
+        let processed = 0;
+        let failed = 0;
+
+        // Two loops on purpose: `for await` over a sync source would allocate a
+        // Promise per item (it awaits each value). The sync branch uses `for...of`
+        // and awaits only on the rare yield tick, keeping the hot path alloc-free.
+        if ( isAsync ) {
+            for await ( const msg of source ) {
+                try {
+                    const pending = handle.processMessage( msg );
+                    if ( pending instanceof Promise ) {
+                        await pending;
+                    }
+                    processed += 1;
+                } catch ( error ) {
+                    failed += 1;
+                    onError( error, msg );
+                }
+            }
+        } else {
+            for ( const msg of source ) {
+                try {
+                    const pending = handle.processMessage( msg );
+                    if ( pending instanceof Promise ) {
+                        await pending; // eslint-disable-line no-await-in-loop
+                    }
+                    processed += 1;
+                } catch ( error ) {
+                    failed += 1;
+                    onError( error, msg );
+                }
+            }
+        }
+
+        return { processed, failed };
+    }; // feedAll()
+
+    return { feedOne, feedAll };
+}; // headlessDriver()
+
+export { headlessDriver };

package/src/flow/expand-single-input-array.js

@@ -0,0 +1,76 @@
+import { SIGNATURE_PATTERNS } from './consts.js';
+
+const expandXOutputsOptions = function ( meta, nodeArgs, flowState ) {
+    const { isNodeNameDuplicate } = flowState;
+    const specs = [];
+    const seenX = Object.create( null );
+    const [ baseName, inputs, outputs, ...balanceArgs ] = nodeArgs;
+    // const inputs = args[ 1 ];
+    // const outputs = args[ 2 ]
+
+    for ( let i = 0; i < inputs.length; i += 1 ) {
+        const param = inputs[ i ];
+
+        if ( seenX[ param ] === 1 ) {
+            throw new Error( `WinkComposer/flow: duplicate input found: '${param}'.` );
+        }
+        seenX[ param ] = 1;
+
+        const instName = `${baseName}_${param}`;
+        if ( isNodeNameDuplicate( instName ) ) throw Error( `WinkComposer/flow: duplicate node ${instName} found.` );
+        const stats = Object.create( null );
+        for ( const st in outputs ) {
+            if (Object.prototype.hasOwnProperty.call( outputs, st ) ) {
+                const stName = outputs[ st ];
+                stats[ st ] = Object.create( null );
+                // Fixed fan naming: ${field}_${label}. The same rule forEach uses, so
+                // array sugar and forEach name outputs identically. (Overwrites on one
+                // path are caught by the build-time guard, check-output-collisions.js.)
+                stats[ st ].storeAs = `${param}_${stName}`;
+            }
+        }
+
+        const spec = meta.buildSpec( instName, param, stats, ...balanceArgs );
+        specs.push( spec );
+    }
+
+    return specs;
+}; // expandXOutputsOptions()
+
+const expandXOptions = function ( meta, nodeArgs, flowState ) {
+    const { isNodeNameDuplicate } = flowState;
+    const specs = [];
+    const seenX = Object.create( null );
+    const [ baseName, inputs, ...balanceArgs ] = nodeArgs;
+
+    for ( let i = 0; i < inputs.length; i += 1 ) {
+        const param = inputs[ i ];
+
+        if ( seenX[ param ] === 1 ) {
+            throw new Error( `WinkComposer/flow: duplicate input found: '${param}'.` );
+        }
+        seenX[ param ] = 1;
+
+        const instName = `${baseName}_${param}`;
+        if ( isNodeNameDuplicate( instName ) ) throw Error( `WinkComposer/flow: duplicate node ${instName} found.` );
+
+        const spec = meta.buildSpec( instName, param, ...balanceArgs );
+        specs.push( spec );
+    }
+
+    return specs;
+}; // expandXOptions()
+
+/**
+ * Expand array sugar for single-input nodes into multiple canonical calls.
+ * Assumes canonical signature: buildSpec( name, x, storeAs, options )
+ * - name is made unique per input as `${baseName}_${param}`
+ * - storeAs follows the fixed fan rule `${param}_${stat}` (same as forEach)
+ * Returns an array of per-input specs (throws on invalid inputs).
+ *
+ * nodeArgs: baseName, inputs, outputs, balance stuff
+ */
+export const expandSingleInputArraySugar = function ( meta, nodeArgs, flowState, pattern ) {
+    if ( pattern === SIGNATURE_PATTERNS.nameXOptions ) return expandXOptions( meta, nodeArgs, flowState );
+    return expandXOutputsOptions( meta, nodeArgs, flowState );
+}; // expandSingleInputArraySugar()

package/src/flow/expand-template-spec.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Template spec expansion for groupBy construct.
+ *
+ * Expands a template spec for a specific group value by:
+ * 1. Deep cloning the template (preserving functions)
+ * 2. Prefixing the node name with group value
+ * 3. Resolving matching tunables to concrete values
+ * 4. Prefixing trigger targets with group value
+ *
+ * Note: storeAs values are NOT prefixed. Output field names remain the same
+ * across all groups since each case is an isolated pipeline path.
+ *
+ * @see ADR-007: groupBy DSL Construct
+ */
+
+import { deepCloneValue } from './deep-clone-spec.js';
+import { resolveTunablesInValue } from './resolve-tunables.js';
+
+/**
+ * Prefixes trigger target names with the group value.
+ *
+ * Handles:
+ * - Direct triggers: spec.triggers[].targets
+ * - Controller logic triggers: spec.logic[].triggers[].targets
+ *
+ * @param {Object} spec - The spec to process (mutated in place)
+ * @param {string|number} groupValue - Prefix to add
+ */
+const prefixTriggerTargets = function ( spec, groupValue ) {
+    const prefixTargets = function ( triggers ) {
+        if ( !Array.isArray( triggers ) ) {
+            return;
+        }
+
+        for ( let i = 0; i < triggers.length; i += 1 ) {
+            const trigger = triggers[ i ];
+            if ( Array.isArray( trigger.targets ) ) {
+                trigger.targets = trigger.targets.map(
+                    ( target ) => `${groupValue}_${target}`
+                );
+            }
+        }
+    };
+
+    // Direct triggers on the spec
+    prefixTargets( spec.triggers );
+
+    // Controller node logic triggers
+    if ( Array.isArray( spec.logic ) ) {
+        for ( let j = 0; j < spec.logic.length; j += 1 ) {
+            prefixTargets( spec.logic[ j ].triggers );
+        }
+    }
+};
+
+/**
+ * Expands a template spec for a specific group value.
+ *
+ * Performs:
+ * 1. Deep clone (preserves functions by reference)
+ * 2. Prefix node name: 'corr' → 'idle_corr'
+ * 3. Resolve matching tunables: lookupByField('rpmBand', {idle: 3.4}) → 3.4
+ * 4. Prefix trigger targets: ['corr', 'ph'] → ['idle_corr', 'idle_ph']
+ *
+ * Note: storeAs values are NOT prefixed. Each group writes to the same
+ * output field names since they run in isolated pipeline paths.
+ *
+ * @param {Object} templateSpec - Original template spec
+ * @param {string|number} groupValue - Group value for this expansion
+ * @param {string} groupByField - The field used for grouping
+ * @returns {Object} Expanded spec ready for the group's case
+ */
+const expandTemplateSpec = function ( templateSpec, groupValue, groupByField ) {
+    // Step 1: Deep clone (preserves functions by reference)
+    const spec = deepCloneValue( templateSpec );
+
+    // Step 2: Prefix node name
+    spec.name = `${groupValue}_${spec.name}`;
+
+    // Step 3: Resolve tunables (returns new object with resolved values)
+    const resolved = resolveTunablesInValue( spec, groupByField, groupValue );
+
+    // Step 4: Prefix trigger targets (mutates in place)
+    prefixTriggerTargets( resolved, groupValue );
+
+    // Note: storeAs values are intentionally NOT prefixed
+    // Each group outputs to the same field names (e.g., 'r2', 'shiftDetected')
+    // This is correct because each case is an isolated pipeline path
+
+    return resolved;
+};
+
+export { expandTemplateSpec, prefixTriggerTargets };