@winkjs/composer 0.0.2 → 0.4.0

package/src/core/utils/validate/validators.js

@@ -0,0 +1,177 @@
+/**
+ * General-purpose validators
+ * Reusable validation functions for common patterns
+ */
+
+/**
+ * Validates JavaScript identifiers
+ */
+const identifier = function ( value ) {
+    return typeof value === 'string' && ( /^[a-zA-Z_$][a-zA-Z0-9_$]*$/ ).test( value );
+}; // identifier()
+
+/**
+ * Validates non-empty string with no whitespace characters.
+ * Rejects empty strings and strings containing spaces, tabs, or newlines.
+ */
+const noSpaces = function ( value ) {
+    return typeof value === 'string' && value.length > 0 && !( /\s/ ).test( value );
+}; // noSpaces()
+
+/**
+ * Creates a range validator
+ */
+const inRange = function ( min, max ) {
+    return function ( value ) {
+        return typeof value === 'number' && value >= min && value <= max;
+    };
+}; // inRange()
+
+/**
+ * Creates an enum validator
+ */
+const oneOf = function ( options ) {
+    return function ( value ) {
+        return options.includes( value );
+    };
+}; // oneOf()
+
+/**
+ * Creates a pattern validator
+ */
+const matches = function ( pattern ) {
+    return function ( value ) {
+        return typeof value === 'string' && pattern.test( value );
+    };
+}; // matches()
+
+/**
+ * Validates positive numbers
+ */
+const positive = function ( value ) {
+    return typeof value === 'number' && value > 0;
+}; // positive()
+
+/**
+ * Validates non-negative numbers
+ */
+const nonNegative = function ( value ) {
+    return typeof value === 'number' && value >= 0;
+}; // nonNegative()
+
+/**
+ * Validates non-negative finite numbers (rejects NaN, Infinity).
+ */
+const nonNegativeFinite = function ( value ) {
+    return typeof value === 'number' && Number.isFinite( value ) && value >= 0;
+}; // nonNegativeFinite()
+
+/**
+ * Validates integers
+ */
+const integer = function ( value ) {
+    return Number.isInteger( value );
+}; // integer()
+
+/**
+ * Validates positive integers
+ */
+const positiveInteger = function ( value ) {
+    return Number.isInteger( value ) && value > 0;
+}; // positiveInteger()
+
+/**
+ * Validates value is a finite number (not NaN, not Infinity).
+ */
+const isFinite = function ( value ) {
+    return typeof value === 'number' && Number.isFinite( value );
+}; // isFinite()
+
+/**
+ * Validates non-negative finite numbers OR functions (for tunable support).
+ */
+const nonNegativeOrFunction = function ( value ) {
+    if ( typeof value === 'function' ) return true;
+    return typeof value === 'number' && Number.isFinite( value ) && value >= 0;
+}; // nonNegativeOrFunction()
+
+/**
+ * Validates positive finite numbers OR functions (for tunable support).
+ */
+const positiveOrFunction = function ( value ) {
+    if ( typeof value === 'function' ) return true;
+    return typeof value === 'number' && Number.isFinite( value ) && value > 0;
+}; // positiveOrFunction()
+
+/**
+ * Validates nonzero numbers
+ */
+const nonZero = function ( value ) {
+    return typeof value === 'number' && value !== 0;
+}; // nonZero()
+
+/**
+ * Validates non-empty strings
+ */
+const nonEmptyString = function ( value ) {
+    return typeof value === 'string' && value.length > 0;
+}; // nonEmptyString()
+
+/**
+ * Validates string representations of non-negative integers ("0", "1", "123")
+ * Used for enum keys which must be numeric string indices.
+ * Rejects leading zeros (e.g., "01", "007") to enforce canonical representation.
+ */
+const integerString = function ( value ) {
+    if ( typeof value !== 'string' ) return false;
+    if ( value.length === 0 ) return false;
+    // Must be digits only
+    if ( !( /^\d+$/ ).test( value ) ) return false;
+    // No leading zeros except for "0" itself
+    if ( value.length > 1 && value[ 0 ] === '0' ) return false;
+    return true;
+}; // integerString()
+
+/**
+ * Validates string representations of finite numbers.
+ * Accepts: "0", "-1", "3.14", "-2.5"
+ * Rejects: "", "NaN", "Infinity", "3.14.5", "abc"
+ * Uses roundtrip validation: String(Number(value)) === value
+ */
+const numericString = function ( value ) {
+    if ( typeof value !== 'string' || value.length === 0 ) return false;
+    const num = Number( value );
+    if ( !Number.isFinite( num ) ) return false;
+    // Roundtrip validation ensures canonical form
+    return String( num ) === value;
+}; // numericString()
+
+/**
+ * Validates boolean string literals.
+ * Accepts: exactly "true" or "false"
+ */
+const booleanString = function ( value ) {
+    return value === 'true' || value === 'false';
+}; // booleanString()
+
+// Export all validators
+export const validators = {
+    identifier,
+    noSpaces,
+    inRange,
+    oneOf,
+    matches,
+    positive,
+    nonNegative,
+    nonNegativeFinite,
+    integer,
+    positiveInteger,
+    nonZero,
+    isFinite,
+    nonNegativeOrFunction,
+    positiveOrFunction,
+    nonEmptyString,
+    integerString,
+    numericString,
+    booleanString
+};

package/src/core/wiring/assert-handle.js

@@ -0,0 +1,57 @@
+// core/wiring/assert-handle.js
+
+/**
+ * @fileoverview Checks that a sink (emitter or storage) gives back a handle
+ * with all the methods we need, at the moment the flow starts up.
+ *
+ * Each sink's factory returns an object — the "handle" — that the flow uses
+ * later to publish or write messages. The contract (ADR-018) lists
+ * which methods that handle must have. This helper checks the list at
+ * startup and throws a clear error if anything is missing.
+ *
+ * Why check at startup instead of when messages start flowing:
+ * - If a method is missing, the alternative is a confusing crash later
+ *   ("X is not a function") deep inside the per-message code path. By
+ *   checking at startup, the error points straight at the misconfigured
+ *   adapter and says exactly which method is missing.
+ * - Startup runs once per flow; the check costs nothing at runtime.
+ *
+ * Error message format (same across sinks):
+ *   `WinkComposer/adapter: '<adapterId>' missing required method '<name>'`
+ *
+ * @see ADR-018 (sink method surface)
+ */
+
+/**
+ * Throws if `handle` is not an object or if any of the listed methods are
+ * missing / non-function. Used by wire-emitters and wire-storages just
+ * after the factory's return is awaited.
+ *
+ * @param {string} adapterId - identifier used in the error message (the
+ *   adapter's registry key — emit-target name, storage name)
+ * @param {*} handle - the value returned from the factory
+ * @param {string[]} requiredMethods - method names that must be functions
+ *   on the handle (e.g., [ 'publishNow', 'shutdown', 'getHealth' ])
+ * @throws {Error} `WinkComposer/adapter: '<adapterId>' factory returned non-object handle`
+ *   if `handle` is null/undefined/non-object.
+ * @throws {Error} `WinkComposer/adapter: '<adapterId>' missing required method '<name>'`
+ *   on the first missing or non-function method (fails fast — does not
+ *   enumerate every gap, since one is enough to abort wiring).
+ */
+const assertHandle = function ( adapterId, handle, requiredMethods ) {
+    if ( !handle || typeof handle !== 'object' ) {
+        throw new Error(
+            `WinkComposer/adapter: '${adapterId}' factory returned non-object handle`
+        );
+    }
+    for ( let i = 0; i < requiredMethods.length; i += 1 ) {
+        const name = requiredMethods[ i ];
+        if ( typeof handle[ name ] !== 'function' ) {
+            throw new Error(
+                `WinkComposer/adapter: '${adapterId}' missing required method '${name}'`
+            );
+        }
+    }
+}; // assertHandle()
+
+export { assertHandle };

package/src/core/wiring/assert-module.js

@@ -0,0 +1,63 @@
+// core/wiring/assert-module.js
+
+/**
+ * @fileoverview Checks that an adapter module declares its durability
+ * class, at the moment the flow wires it up.
+ *
+ * Every adapter module must export `durabilityClass` — one word saying
+ * what happens to data it has accepted but not yet delivered if the
+ * process crashes (ADR-018 defines the export and its four values). For
+ * a source the same word describes the input it can recover after a
+ * disconnect.
+ *
+ * Why check at wire time: an adapter without the export still moves
+ * messages perfectly well — the gap only surfaces when an operator asks
+ * "what does a crash cost here" and nobody can answer from the module.
+ * Failing at startup keeps the declaration from silently eroding as
+ * adapters are added (the ADR-018 module-surface gate). The companion
+ * data-driven test over all shipped adapters is
+ * `src/core/test/adapter-module-surface.specs.js`.
+ *
+ * Error message format (same shape as assert-handle.js):
+ *   `WinkComposer/adapter: '<adapterId>' module missing valid
+ *    'durabilityClass' export — got <value>; expected one of ...`
+ *
+ * @see ADR-018 (module surface, durability)
+ */
+
+/**
+ * The four crash-survival classes ADR-018 defines. Anything else in a
+ * module's `durabilityClass` export is a typo or an invented class, and
+ * both should fail loudly at wire time.
+ * @type {string[]}
+ */
+const DURABILITY_CLASSES = [ 'in-memory', 'wal-backed', 'broker-queue', 'best-effort' ];
+
+/**
+ * Throws if `module.durabilityClass` is not one of the four contract
+ * values. Used by wire-emitters, wire-storages, and the flow runtime's
+ * source start path, just before each adapter's factory is invoked.
+ *
+ * @param {string} adapterId - identifier used in the error message (the
+ *   adapter's registry key or its `id` export)
+ * @param {Object} module - the adapter module (named exports or the
+ *   default aggregate — both carry `durabilityClass` per ADR-018)
+ * @throws {Error} with `err.code = 'INVALID_ADAPTER'` when the export is
+ *   missing, non-string, or not one of the four values.
+ */
+const assertModuleDurability = function ( adapterId, module ) {
+    const value = module && module.durabilityClass;
+    if ( DURABILITY_CLASSES.includes( value ) ) {
+        return;
+    }
+    const got = ( typeof value === 'string' ) ? `'${value}'` : String( value );
+    const err = new Error(
+        `WinkComposer/adapter: '${adapterId}' module missing valid 'durabilityClass' export ` +
+        `(ADR-018) — got ${got}; expected one of ` +
+        `${DURABILITY_CLASSES.map( ( c ) => `'${c}'` ).join( ' | ' )}`
+    );
+    err.code = 'INVALID_ADAPTER';
+    throw err;
+}; // assertModuleDurability()
+
+export { assertModuleDurability, DURABILITY_CLASSES };

package/src/core/wiring/index.js

@@ -0,0 +1,5 @@
+export { default as wireNode } from './wire-node.js';
+export { default as wireLinearGraph } from './wire-linear-graph.js';
+export { default as emitters } from  './wire-emitters.js';
+export { default as storages } from './wire-storages.js';
+export { assertModuleDurability } from './assert-module.js';

package/src/core/wiring/node-type-to-module.js

@@ -0,0 +1,17 @@
+const nodeTypeToModule = function ( nodeType ) {
+    // Trim to handle any whitespace issues
+    const trimmed = nodeType.trim();
+
+    // Handle acronyms and simple names
+    if ( trimmed === trimmed.toUpperCase() ) {
+        return trimmed.toLowerCase();
+    }
+
+    // Handle multi-word names: 'Page Hinkley' → 'pageHinkley'
+    return trimmed
+        .split(' ')
+        .map( ( word, i ) => ( i === 0 ? word.toLowerCase() : word ) )
+        .join('');
+};
+
+export default nodeTypeToModule;

package/src/core/wiring/wire-emitters.js

@@ -0,0 +1,256 @@
+// core/wiring/wire-emitters.js
+
+/**
+ * @fileoverview Holds the running emitter instances for a flow and creates
+ * them on demand from the spec.
+ *
+ * An "emitter" is the thing that publishes messages out (MQTT broker,
+ * terminal/stdout, etc.). One emitter per target name is enough — many
+ * partitions can share it — so we keep them in a small registry keyed by
+ * target name and only build a new one if we haven't seen that name before.
+ *
+ * This file is responsible for four things:
+ * - Building each emitter at flow startup, by calling its module's
+ *   `createEmitter(config)` factory and storing the returned handle.
+ * - Calling `applySemanticsRequirement` (from `wire-semantics.js`) on each
+ *   emitter so adapters that declare `semanticsRequirement` get the
+ *   requested slice of `assetClass` injected before their factory is
+ *   called (capability-indexed injection per ADR-018).
+ *   No current emitter declares one; the parity machinery is plumbed
+ *   for future emitters that will opt in
+ *   without further wiring changes. `runtime.assetClass` is threaded in
+ *   via a new `assetClass` parameter on `wire()` (default null preserves
+ *   any caller that does not pass it).
+ * - Checking, the moment we get the handle back, that it has the methods
+ *   the rest of the framework will call later (fail loudly at startup
+ *   rather than crash deep in the per-message hot path). See
+ *   `assert-handle.js` for the check helper and the error format.
+ * - Telling the partition manager which emitters expose `getPressure()` so
+ *   the pressure-aware yield decision (ADR-020, Draft) can poll them. The
+ *   list is exposed via `getBackpressureAwareSinks()` and assembled by
+ *   `flow/run.js` after the flow's partition state is set up.
+ *
+ * Restart safety: `shutdown()` clears the registry after stopping every
+ * emitter, so a follow-up `wire()` call on the same process gets a fresh
+ * set of handles. (Mirrors `wire-storages.js`; an earlier version cleared
+ * only the storage registry.)
+ *
+ * The IIFE around the registry hides it from outside callers; only the
+ * exported methods can read or change it.
+ *
+ * @see ADR-018 (sink method surface)
+ * @see ADR-020 (backpressure-aware-sinks collection; Draft)
+ */
+
+import { assertHandle } from './assert-handle.js';
+import { assertModuleDurability } from './assert-module.js';
+import { applySemanticsRequirement } from './wire-semantics.js';
+
+/**
+ * Methods the framework calls on an emitter handle later, so they have to
+ * be present at wire time per ADR-018.
+ * Note `getStats` was previously here and was later removed from the
+ * contract's method surface.
+ * `getPressure` is optional — its presence decides whether the handle is
+ * collected into `backpressureAwareSinks`, not whether the wire succeeds.
+ */
+const REQUIRED_EMITTER_METHODS = [ 'publishNow', 'shutdown', 'getHealth' ];
+
+/**
+ * Serializes a rejection's `dropped` payload for the shutdown log. A
+ * third-party adapter can reject with anything — including structures
+ * JSON.stringify throws on (circular references). The log line must never
+ * throw: a throw here used to skip the registry clear that followed it.
+ * Mirrors `wire-storages.js`.
+ *
+ * @param {*} dropped - the rejection's dropped payload
+ * @returns {string} JSON, or a fallback marker when unserializable
+ */
+const describeDropped = function ( dropped ) {
+    try {
+        return JSON.stringify( dropped );
+    } catch {
+        return '[unserializable]';
+    }
+}; // describeDropped()
+
+const emitters = ( function () {
+    // ========================================================================
+    // PRIVATE STATE: Singleton Registry
+    // ========================================================================
+    // Holds one emitter per target name. Object.create(null) avoids
+    // prototype-pollution surprises since target names come from runtime
+    // config (DSL `.emitter()` calls).
+    const singletons = Object.create( null );
+
+    // ========================================================================
+    // WIRE: Discover and Create Emitter Singletons
+    // ========================================================================
+    /**
+     * Scans node specs for Emit-If targets, creates the emitter for each
+     * unseen target via its module's `createEmitter(config)` factory,
+     * verifies the returned handle has the required methods, and stores
+     * it. Idempotent — running `wire()` twice on the same target reuses
+     * the existing handle and skips the factory call.
+     *
+     * `assetClass` is the runtime asset class from `flow.assetClass()`,
+     * passed through so emitters that declare `semanticsRequirement` can
+     * receive their requested slice (capability-indexed injection per
+     * ADR-018). No current emitter declares one; the parameter is
+     * plumbed for future emitters (e.g., a structured-MQTT emitter that
+     * publishes to `${assetClass}/...` topics) that will opt in without
+     * further wiring changes.
+     *
+     * @param {Array} specs - flow node specs (filtered for Emit If)
+     * @param {Object} targetConfigs - map from target name to user config
+     * @param {Object} emitterModules - map from target name to adapter module
+     * @param {Object|null} [assetClass] - runtime asset class from `flow.assetClass()`,
+     *   or null if the flow author did not call it. Default null preserves
+     *   backward compatibility for any caller that does not pass it.
+     */
+    const wire = async function ( specs, targetConfigs, emitterModules, assetClass = null ) {
+        for ( const spec of specs ) {
+            if ( spec.nodeType !== 'Emit If' || !spec.target ) {
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+
+            const target = spec.target;
+
+            if ( !singletons[ target ] ) {
+                const module = emitterModules[ target ];
+                const factory = module && module.createEmitter;
+                if ( typeof factory !== 'function' ) {
+                    throw new Error( `composer: Invalid emitter module: ${target}` );
+                }
+
+                // ADR-018 module-surface check: the module must say what
+                // a crash costs — before the factory runs.
+                assertModuleDurability( target, module );
+
+                // Build effective config; capability-indexed injection per
+                // ADR-018 if the adapter declared `semanticsRequirement`.
+                // No current emitter declares one, so for today's adapters
+                // this is a no-op spread of user config. Future emitters
+                // opt in by exporting a declaration; no further wiring
+                // changes needed.
+                const effectiveConfig = { ...( targetConfigs[ target ] || {} ) };
+                applySemanticsRequirement( target, module, assetClass, effectiveConfig );
+
+                // Await per ADR-018 — sync factories are unaffected (await on
+                // a non-Promise resolves immediately); async factories that
+                // need real init time (e.g., a future Kafka emitter) are
+                // supported transparently.
+                // eslint-disable-next-line no-await-in-loop
+                const handle = await factory( effectiveConfig );
+
+                // Wire-time shape check (ADR-018). Fails fast with a
+                // descriptive error instead of letting a missing method
+                // crash the per-message hot path later.
+                assertHandle( target, handle, REQUIRED_EMITTER_METHODS );
+
+                singletons[ target ] = handle;
+            }
+
+            spec.emitter = singletons[ target ];
+        }
+    }; // wire()
+
+    // ========================================================================
+    // GET BACKPRESSURE-AWARE SINKS
+    // ========================================================================
+    /**
+     * Returns the subset of wired emitters that expose `getPressure()`.
+     * Keys are namespaced as `emitter:<target>` so a debug log at the
+     * call site (the pressure-aware yield decision, ADR-020) immediately
+     * tells the operator which sink crossed the threshold. See
+     * `flow/run.js` for the assembly into
+     * `composerState.partitionState.backpressureAwareSinks`.
+     */
+    const getBackpressureAwareSinks = function () {
+        const map = Object.create( null );
+        for ( const [ target, handle ] of Object.entries( singletons ) ) {
+            if ( typeof handle.getPressure === 'function' ) {
+                map[ `emitter:${target}` ] = handle;
+            }
+        }
+        return map;
+    }; // getBackpressureAwareSinks()
+
+    // ========================================================================
+    // GET: Retrieve All Singletons (Defensive Copy)
+    // ========================================================================
+    // Returns a shallow copy so external callers can inspect the registry
+    // without being able to mutate the private one. Used for health
+    // monitoring and debugging.
+    const get = function () {
+        return { ...singletons };
+    }; // get()
+
+    // ========================================================================
+    // SHUTDOWN: Graceful Termination of All Emitters
+    // ========================================================================
+    /**
+     * Stops every emitter in parallel via `Promise.allSettled`, so one
+     * stuck shutdown does not block the others. Then clears the registry
+     * — that way a follow-up `wire()` on the same process (e.g., a test
+     * tearing down and bringing the flow back up) gets fresh handles
+     * instead of stale, already-stopped ones. Mirrors `wire-storages.js`.
+     */
+    // Per ADR-018, each emitter's own shutdown takes `{ timeout }`.
+    // We pass it through so the flow's per-stage time budget (set in
+    // flow/run.js) reaches every emitter the same way.
+    const shutdown = async function ( { timeout } = {} ) {
+        const opts = ( timeout === undefined ) ? undefined : { timeout };
+        const names = Object.keys( singletons );
+        const results = await Promise.allSettled(
+            names.map( ( name ) => {
+                // A non-conforming adapter may THROW from shutdown()
+                // instead of rejecting. Convert the throw into this
+                // adapter's own rejection slot — escaping here would
+                // skip the siblings' drain and the registry clear.
+                try {
+                    return opts ? singletons[ name ].shutdown( opts ) : singletons[ name ].shutdown();
+                } catch ( err ) {
+                    return Promise.reject( err );
+                }
+            } )
+        );
+        // Restart safety FIRST: drop stale handles so the next wire()
+        // rebuilds them. This must not depend on the logging below — a
+        // hostile rejection payload used to throw mid-log and leave the
+        // stale handles behind.
+        for ( const key of names ) {
+            delete singletons[ key ];
+        }
+        // A rejected drain must reach a human (ADR-018's two-party
+        // rule). allSettled keeps one failing emitter from blocking its
+        // siblings' drain — but the swallowed rejection is a data loss
+        // that would otherwise be visible only to callers inspecting the
+        // settled results. Log each one, classified, naming the adapter.
+        // String( err ) rather than interpolation: a Symbol rejection
+        // reason throws inside a template literal.
+        results.forEach( ( result, i ) => {
+            if ( result.status === 'rejected' ) {
+                const err = result.reason || {};
+                const dropped = err.dropped ? ` dropped=${describeDropped( err.dropped )}` : '';
+                console.error(
+                    `WinkComposer/wiring: emitter '${names[ i ]}' shutdown failed [${err.code || 'UNKNOWN'}]: ${err.message || String( err )}${dropped}`
+                );
+            }
+        } );
+        return results;
+    }; // shutdown()
+
+    // ========================================================================
+    // PUBLIC API
+    // ========================================================================
+    return {
+        wire,
+        get,
+        getBackpressureAwareSinks,
+        shutdown
+    };
+}() ); // emitters()
+
+export default emitters;

package/src/core/wiring/wire-linear-graph.js

@@ -0,0 +1,25 @@
+import wireNode from './wire-node.js';
+import nodeTypeToModule from './node-type-to-module.js';
+
+const wireLinearGraph = function ( specs, nodeModules, options = {} ) {
+    let nextHop = null;
+
+    // Wire in reverse - terminal to root
+    for ( let i = specs.length - 1; i >= 0; i -= 1 ) {
+        const spec = specs[ i ];
+        const moduleName = nodeTypeToModule( spec.nodeType );
+        const nodeModule = nodeModules[ moduleName ];
+
+        if (!nodeModule) {
+            throw new Error( `composer/wireGraph: Node module '${moduleName}' not found for nodeType '${spec.nodeType}'` );
+        }
+
+        const nextHops = nextHop ? [ nextHop ] : [];
+        nextHop = wireNode( nodeModule, i, nextHops, options );
+    }
+
+    // After loop, nextHop is the root node
+    return nextHop;
+};
+
+export default wireLinearGraph;