@winkjs/composer 0.0.2 → 0.4.0

package/src/core/utils/node/pause.js

@@ -0,0 +1,11 @@
+/**
+ * Pauses a node — skips update() but still runs publishTo()
+ * @param {Object} state - The node's state object
+ * @returns {boolean} - Always returns true for consistency with control methods
+ */
+const pause = function ( state ) {
+    state.pause = true;
+    return true;
+}; // pause()
+
+export default pause;

package/src/core/utils/node/populate-predicate-inputs.js

@@ -0,0 +1,14 @@
+/**
+ * Populates required fields and prepares projected inputs for predicate
+ * @param {Object} state - Node state containing requires and predicateInput
+ * @param {Object} msg - Message to validate
+ * @returns {string|null} - Name of invalid field or null if all valid
+ */
+const populatePredicateInput = function ( state, msg ) {
+    for ( let i = 0; i < state.requires.length; i += 1 ) {
+        const field = state.requires[ i ];
+        state.predicateInput[ field ] = msg[ field ];
+    }
+}; // copyRequiredFields()
+
+export default populatePredicateInput;

package/src/core/utils/node/publish-nan.js

@@ -0,0 +1,19 @@
+// core/utils/node/publish-nan.js
+
+/**
+ * Publishes NaN for all configured stats. It is needed for per node
+ * based fault isolation based on usage of NaNed parameters.
+ *
+ * Only call this AFTER checking state.inputValidationFailed is true!
+ *
+ * @param {Object} state - Node state containing stats configuration
+ * @param {Object} msg - Message to publish NaN values to
+ */
+const publishNaN = function ( state, msg ) {
+    // eslint-disable-next-line guard-for-in
+    for ( const stat in state.stats ) {
+        msg[ state.stats[ stat ].storeAs ] = NaN;
+    }
+}; // publishNaN()
+
+export default publishNaN;

package/src/core/utils/node/reset-predicate-inputs.js

@@ -0,0 +1,11 @@
+/**
+ * Resets predicateInput object for next message
+ * @param {Object} state - Node state containing requires and predicateInput
+ */
+const resetPredicateInput = function ( state ) {
+    for ( let i = 0; i < state.requires.length; i += 1 ) {
+        state.predicateInput[ state.requires[ i ] ] = undefined;
+    }
+}; // resetPredicateInput()
+
+export default resetPredicateInput;

package/src/core/utils/node/unpause.js

@@ -0,0 +1,11 @@
+/**
+ * Resumes a paused node — update() runs again
+ * @param {Object} state - The node's state object
+ * @returns {boolean} - Always returns true for consistency with control methods
+ */
+const unpause = function ( state ) {
+    state.pause = false;
+    return true;
+}; // unpause()
+
+export default unpause;

package/src/core/utils/node/validate-spec.js

@@ -0,0 +1,22 @@
+import { validateWithSchema } from '../validate/index.js';
+
+/**
+ * Validate a node specification against its DSL metadata schema.
+ * Standard validation for all nodes during initialization.
+ *
+ * @param {Object} spec - Node specification to validate
+ * @param {Function} introspect - Node's introspection module
+ * @throws {TypeError} If validation fails with detailed error messages
+ */
+const validateSpec = function ( spec, introspect ) {
+    const metadata = introspect.getDSLMetadata();
+    const schema = {
+        ...metadata.specSchema,
+        _crossFieldValidators: metadata.crossFieldValidators
+    };
+
+    const validation = validateWithSchema( schema, spec, 'spec' );
+    validation.throwIfInvalid( introspect.getNodeType() );
+};
+
+export default validateSpec;

package/src/core/utils/options/resolve-field-keyed.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Utility for resolving field-keyed options in node init.
+ *
+ * Supports uniform DX where parameters can be specified as either:
+ * - Direct values (same for all expanded fields)
+ * - Field-keyed objects (per-field values, extracted at init time)
+ *
+ * Three resolution patterns:
+ * 1. resolveScalar — for simple values (number, string, boolean, function)
+ * 2. resolveNestedObject — for structured objects (like { min, max })
+ * 3. resolveArray — for array values (like thresholds, categories)
+ *
+ * @example
+ * // Direct scalar
+ * resolveScalar( 20, 'temp' )  // → 20
+ *
+ * // Field-keyed scalar
+ * resolveScalar( { temp: 5, pressure: 20 }, 'temp' )  // → 5
+ *
+ * // Direct nested object
+ * resolveNestedObject( { min: 0, max: 100 }, 'temp', [ 'min', 'max' ] )  // → { min: 0, max: 100 }
+ *
+ * // Field-keyed nested object
+ * resolveNestedObject(
+ *     { temp: { min: -40, max: 85 }, pressure: { min: 0, max: 120 } },
+ *     'temp',
+ *     [ 'min', 'max' ]
+ * )  // → { min: -40, max: 85 }
+ *
+ * // Direct array
+ * resolveArray( [ 10, 50, 90 ], 'temp' )  // → [ 10, 50, 90 ]
+ *
+ * // Field-keyed array
+ * resolveArray( { temp: [ 10, 50, 90 ], pressure: [ 5, 25, 75 ] }, 'temp' )  // → [ 10, 50, 90 ]
+ */
+
+/**
+ * Resolve scalar option (number, string, boolean, function).
+ *
+ * @param {*} option - The option value from spec
+ * @param {string} fieldName - The node's input field (state.x)
+ * @returns {*} Resolved scalar value or undefined
+ */
+export const resolveScalar = function ( option, fieldName ) {
+    // Null/undefined passthrough
+    if ( option === null || option === undefined ) return undefined;
+
+    // Scalar or function — return directly
+    if ( typeof option !== 'object' ) return option;
+
+    // Array — not a scalar, return undefined (use resolveArray instead)
+    if ( Array.isArray( option ) ) return undefined;
+
+    // Object — try field-keyed extraction
+    if ( fieldName in option ) {
+        const value = option[ fieldName ];
+        // Accept scalar or function, reject nested objects (unless function)
+        if ( typeof value !== 'object' || typeof value === 'function' ) {
+            return value;
+        }
+    }
+
+    // Object without field key — not a valid scalar spec
+    return undefined;
+};
+
+/**
+ * Resolve nested object option (like ranges: { min, max }).
+ *
+ * @param {*} option - The option value from spec
+ * @param {string} fieldName - The node's input field (state.x)
+ * @param {string[]} expectedKeys - Keys that identify direct spec (e.g., [ 'min', 'max' ])
+ * @returns {Object|undefined} Resolved object or undefined
+ */
+export const resolveNestedObject = function ( option, fieldName, expectedKeys ) {
+    // Null/undefined/non-object passthrough
+    if ( option === null || option === undefined ) return undefined;
+    if ( typeof option !== 'object' || Array.isArray( option ) ) return undefined;
+
+    // Try field-keyed first: option[fieldName] is object with expected keys
+    const fieldKeyed = option[ fieldName ];
+    if ( fieldKeyed && typeof fieldKeyed === 'object' && !Array.isArray( fieldKeyed ) ) {
+        const hasExpectedKey = expectedKeys.some( ( k ) => k in fieldKeyed );
+        if ( hasExpectedKey ) return fieldKeyed;
+    }
+
+    // Fall back to direct: option itself has expected keys
+    const hasDirect = expectedKeys.some( ( k ) => k in option );
+    if ( hasDirect ) return option;
+
+    return undefined;
+};
+
+/**
+ * Resolve array option (like thresholds, categories, valueList).
+ *
+ * @param {*} option - The option value from spec
+ * @param {string} fieldName - The node's input field (state.x)
+ * @returns {Array|undefined} Resolved array or undefined
+ */
+export const resolveArray = function ( option, fieldName ) {
+    // Null/undefined passthrough
+    if ( option === null || option === undefined ) return undefined;
+
+    // Direct array — return as-is
+    if ( Array.isArray( option ) ) return option;
+
+    // Object — try field-keyed extraction
+    if ( typeof option === 'object' ) {
+        const fieldValue = option[ fieldName ];
+        if ( Array.isArray( fieldValue ) ) return fieldValue;
+    }
+
+    return undefined;
+};

package/src/core/utils/quantize/index.js

@@ -0,0 +1,75 @@
+// core/utils/quantize/index.js
+
+/**
+ * @fileoverview Snap a value to the nearest multiple of a declared
+ * resolution.
+ *
+ * Adapter authors honouring a column's `resolution` (declared in the
+ * semantics layer) need to round values to that resolution's grid before
+ * storing or displaying them. QuestDB does this when it writes float64
+ * columns; the terminal emitter does it when it formats float64 values
+ * for human reading. Both used to carry their own copy of the same
+ * formula; this module is the single source.
+ *
+ * The quantizer pre-computes the inverse resolution and the appropriate
+ * decimal-place count at build time, so the per-message hot path is one
+ * multiply, one round, one multiply, one `toFixed` — no allocation, no
+ * recomputation.
+ *
+ * Decimal places follow the natural rule:
+ * - `resolution = 0.001` → 3 decimal places
+ * - `resolution = 0.01`  → 2 decimal places
+ * - `resolution = 0.1`   → 1 decimal place
+ * - `resolution = 1`     → 0 (returns `null`, signalling passthrough)
+ * - `resolution = 5`     → 0 (whole-number resolution; values still
+ *                          snap to multiples of 5, but no decimals to
+ *                          format)
+ *
+ * The `toFixed` step cleans up floating-point noise — for example,
+ * `Math.round( 10.1 * 10 ) * 0.1` produces `10.100000000001` because
+ * of IEEE-754 rounding, and `toFixed(1)` returns the tidy `"10.1"`
+ * which `Number(...)` parses back to `10.1`.
+ *
+ * Returning `null` for `resolution === 1` (or undefined) is a small but
+ * load-bearing optimisation: the common case is "no resolution declared"
+ * (or `resolution: 1`, which is the schema's default), and callers can
+ * skip a wrapping closure entirely. QDB's `writers.js` uses this to
+ * route to its `QUEST_WRITERS.float64` passthrough writer; terminal's
+ * `formatters.js` uses it to skip per-column quantizer registration.
+ */
+
+/**
+ * Build a quantizer closure that snaps a value to the nearest multiple
+ * of `resolution`. Returns `null` when the resolution does not need
+ * quantization (undefined, or 1) — callers handle the null by treating
+ * the value as passthrough.
+ *
+ * Sample usage:
+ *
+ *     const quantize = buildResolutionQuantizer( 0.1 );
+ *     if ( quantize ) {
+ *         const clean = quantize( 23.456 );  // → 23.5
+ *     }
+ *
+ * @param {number|undefined} resolution - The declared resolution from
+ *   the column's semantics. Must be a positive finite number for
+ *   meaningful quantization; the caller is responsible for asserting
+ *   that (we trust the input here).
+ * @returns {function(number): number|null} A quantizer function, or
+ *   `null` when no quantization is needed.
+ */
+const buildResolutionQuantizer = function ( resolution ) {
+    if ( resolution === undefined || resolution === 1 ) return null;
+
+    const invResolution = 1 / resolution;
+    const decimalPlaces = resolution < 1 ?
+        Math.ceil( -Math.log10( resolution ) ) :
+        0;
+
+    return function ( v ) {
+        const quantized = Math.round( v * invResolution ) * resolution;
+        return Number( quantized.toFixed( decimalPlaces ) );
+    };
+};
+
+export { buildResolutionQuantizer };

package/src/core/utils/stats/formulas.js

@@ -0,0 +1,67 @@
+// core/utils/stats/formulas.js
+
+/**
+ * @fileoverview Pure functions that compute statistics from central moments.
+ *
+ * Shared by digestMoments (converts raw moments to stats) and twStats
+ * (tumbling window stats with deferred computation at publish time).
+ *
+ * All formulas use unnormalized central moments (M2 = sum of squared deviations,
+ * not M2/n) as input, consistent with Pébay's incremental algorithm output.
+ *
+ * @see https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance
+ * @see Pébay, P. (2008). Sandia Report SAND2008-6212.
+ */
+
+/**
+ * Compute sample variance from second central moment.
+ * @param {number} M2 - Second central moment (sum of squared deviations)
+ * @param {number} n - Sample count
+ * @param {boolean} biased - If true, divide by n (population); else by n-1 (sample)
+ * @returns {number} Variance
+ */
+export const computeVariance = function ( M2, n, biased ) {
+    const divisor = biased ? n : ( n - 1 );
+    return M2 / divisor;
+}; // computeVariance()
+
+/**
+ * Compute coefficient of variation.
+ * @param {number} stddev - Standard deviation
+ * @param {number} mean - Arithmetic mean
+ * @param {number} eps - Epsilon for numerical stability
+ * @returns {number} CV or NaN if mean is near zero
+ */
+export const computeCV = function ( stddev, mean, eps ) {
+    return ( Math.abs( mean ) > eps ) ? ( stddev / Math.abs( mean ) ) : NaN;
+}; // computeCV()
+
+/**
+ * Compute skewness: m3 / m2^1.5 (population skewness)
+ * @param {number} M3 - Third central moment
+ * @param {number} n - Sample count
+ * @param {number} m2 - Population variance (M2/n)
+ * @param {number} eps - Epsilon for numerical stability
+ * @returns {number} Skewness or NaN/0 for edge cases
+ */
+export const computeSkew = function ( M3, n, m2, eps ) {
+    if ( !Number.isFinite( M3 ) ) return NaN;
+    const m3 = M3 / n;
+    const denom = Math.pow( m2, 1.5 );
+    return ( denom > eps ) ? ( m3 / denom ) : 0;
+}; // computeSkew()
+
+/**
+ * Compute excess kurtosis: (m4 / m2²) - 3
+ * @param {number} M4 - Fourth central moment
+ * @param {number} n - Sample count
+ * @param {number} m2 - Population variance (M2/n)
+ * @param {number} eps - Epsilon for numerical stability
+ * @returns {number} Excess kurtosis or NaN/-3 for edge cases
+ */
+export const computeKurtosis = function ( M4, n, m2, eps ) {
+    if ( !Number.isFinite( M4 ) ) return NaN;
+    const m4 = M4 / n;
+    const denom = m2 * m2;
+    return ( denom > eps ) ? ( ( m4 / denom ) - 3 ) : -3;
+}; // computeKurtosis()

package/src/core/utils/stats/index.js

@@ -0,0 +1,3 @@
+// core/utils/stats/index.js
+
+export { computeVariance, computeCV, computeSkew, computeKurtosis } from './formulas.js';

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

@@ -0,0 +1,141 @@
+/**
+ * WinkComposer-specific validators
+ * Domain-specific validation functions for streaming analytics nodes
+ */
+
+import { validators } from './validators.js';
+
+/**
+ * Validates node field specification
+ */
+const nodeField = function ( value ) {
+    return typeof value === 'object' &&
+           value !== null &&
+           typeof value.field === 'string' &&
+           value.field.length > 0 &&
+           validators.identifier( value.field );
+}; // nodeField()
+
+/**
+ * Validates trigger specification
+ */
+const trigger = function ( value ) {
+    if ( typeof value !== 'object' || value === null ) return false;
+
+    // Control must be a valid method name
+    if ( typeof value.control !== 'string' || !validators.identifier( value.control ) ) {
+        return false;
+    }
+
+    // Targets must be an array of valid identifiers
+    if ( !Array.isArray( value.targets ) || value.targets.length === 0 ) {
+        return false;
+    }
+
+    return value.targets.every( ( target ) =>
+        typeof target === 'string' && validators.identifier( target )
+    );
+}; // trigger()
+
+/**
+ * Validates statistical output specification
+ */
+const statSpec = function ( value ) {
+    return typeof value === 'object' &&
+           value !== null &&
+           typeof value.storeAs === 'string' &&
+           validators.identifier( value.storeAs );
+}; // statSpec()
+
+/**
+ * Validates predicate function
+ */
+const predicate = function ( value ) {
+    return typeof value === 'function' && value.length === 1;
+}; // predicate()
+
+/**
+ * Validates EWMA alpha parameter
+ */
+const alpha = function ( value ) {
+    return typeof value === 'number' && value > 0 && value < 1;
+}; // alpha()
+
+/**
+ * Validates EWMA half-life parameter
+ */
+const halfLife = function ( value ) {
+    return typeof value === 'number' && value > 0 && value < 999999;
+}; // alpha()
+
+/**
+ * Validates window size
+ */
+const windowSize = function ( value ) {
+    return Number.isInteger( value ) && value > 0;
+}; // windowSize()
+
+/**
+ * Validates decay factor (for exponential decay)
+ */
+const decayFactor = function ( value ) {
+    return typeof value === 'number' && value > 0 && value < 1;
+}; // decayFactor()
+
+/**
+ * Validates threshold specification
+ */
+const threshold = function ( value ) {
+    return typeof value === 'number' && !Number.isNaN( value );
+}; // threshold()
+
+/**
+ * Validates statistical method names
+ */
+const statMethod = function ( value ) {
+    const validMethods = [
+        'mean', 'variance', 'stddev', 'sum', 'count',
+        'min', 'max', 'range', 'skewness', 'kurtosis'
+    ];
+    return typeof value === 'string' && validMethods.includes( value );
+}; // statMethod()
+
+/**
+ * Validates node type specification
+ */
+const nodeType = function ( value ) {
+    return typeof value === 'string' &&
+           value.length > 0 &&
+           value.length <= 50; // Reasonable limit for node type names
+}; // nodeType()
+
+/**
+ * Cross-field validator to prevent self-triggering
+ * Ensures a node doesn't list itself in trigger targets
+ */
+const noSelfTriggers = {
+    fields: [ 'name', 'triggers' ],
+    validator: ( spec ) => {
+        if ( !spec.triggers ) return true;
+        return spec.triggers.every( ( trgr ) =>
+            !trgr.targets.includes( spec.name )
+        );
+    },
+    error: 'composer/validation: Node cannot trigger control methods on itself'
+}; // noSelfTriggers
+
+// Export all composer validators
+export const composerValidators = {
+    nodeField,
+    trigger,
+    statSpec,
+    predicate,
+    alpha,
+    halfLife,
+    windowSize,
+    decayFactor,
+    threshold,
+    statMethod,
+    nodeType,
+    noSelfTriggers
+};