@winkjs/composer 0.0.2 → 0.4.1

package/src/nodes/diff/introspect.js

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Introspection metadata for diff node.
+ *
+ * Defines supported stats, control methods, capabilities, DSL schema,
+ * and default options. All getters return defensive copies.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'diff'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    diff: 'Difference between two message values (x - y)',
+};
+
+/** 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 = 'Diff';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Computes the difference between two numeric fields in a message',
+    features: [
+        'Simple arithmetic difference (x - y)',
+        'Optional absolute value mode |x - y|',
+        'Useful for computing spreads, or deviations'
+    ]
+};
+
+// Attach static metadata once, from our constants by making a shallow copy.
+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 DEFAULT_OPTIONS = {
+    absolute: false
+};
+
+// 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'
+                },
+                y: {
+                    type: 'string',
+                    required: true,
+                    validator: validators.noSpaces,
+                    error: 'Field name cannot contain spaces'
+                }
+            }
+        },
+        absolute: {
+            type: 'boolean',
+            required: false,
+            default: false
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            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'
+                    }
+                }
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'from.x', 'from.y' ],
+            validator: ( spec ) => spec.from.x !== spec.from.y,
+            error: 'from.x and from.y must be different fields'
+        }
+    ],
+
+    // How to build the spec from DSL params
+    buildSpec: ( name, x, y, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x, y },
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );
+

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

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Publish function for diff node.
+ *
+ * Copies the computed difference to the output message, or propagates
+ * NaN if the last input was invalid. Skipped entirely when 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;
+    }
+
+    msg[ state.stats.diff.storeAs ] = state.diff;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/diff/recompute.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Recompute for diff node.
+ *
+ * No-op: difference is computed fresh from raw input values on every
+ * update — there is no accumulated state that can drift over time.
+ */
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/diff/reset.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Reset diff node state.
+ *
+ * Clears the computed difference value.
+ */
+
+const reset = function ( state ) {
+    state.diff = 0;
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/diff/update.js

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Update function for diff node.
+ *
+ * Computes the difference between two numeric message fields (x - y),
+ * with optional absolute value mode.
+ */
+
+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;
+    }
+
+    const yVal = msg[ state.y ];
+    // Handle faults gracefully: ensure their isolation
+    if ( !Number.isFinite( yVal ) ) {
+        // Signals publishing NaN for all demanded `stats` in publishTo.
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Compute difference
+    const difference = xVal - yVal;
+
+    // Apply absolute if configured
+    state.diff = state.absolute ? Math.abs( difference ) : difference;
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/digest-moments/formulas.js

@@ -0,0 +1,12 @@
+// nodes/digest-moments/formulas.js
+
+/**
+ * @fileoverview Re-exports shared statistical formulas.
+ *
+ * The canonical implementations live in core/utils/stats/formulas.js.
+ * This re-export preserves the local import path used by digest-moments/update.js.
+ *
+ * @see core/utils/stats/formulas.js
+ */
+
+export { computeVariance, computeCV, computeSkew, computeKurtosis } from '../../core/utils/stats/formulas.js';

package/src/nodes/digest-moments/index.js

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

@@ -0,0 +1,67 @@
+// nodes/digest-moments/init.js
+
+/**
+ * @fileoverview Initialization for digestMoments node.
+ *
+ * Creates state with pre-computed input field names for zero-allocation
+ * hot path. The node is stateless (no accumulation), but needs state for
+ * computed values and configuration.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    // Create state after validation passes
+    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;
+    // Preserve node's name
+    state.name = spec.name;
+
+    // Input field prefix (from.x contains the prefix, e.g., 'vibSD')
+    const prefix = spec.from.x;
+
+    // Pre-compute input field names (zero allocation in update)
+    // These are the output field names from upstream momentsDigest
+    state.fields = Object.create( null );
+    state.fields.n   = prefix + '_n';
+    state.fields.M1  = prefix + '_M1';
+    state.fields.M2  = prefix + '_M2';
+    state.fields.M3  = prefix + '_M3';
+    state.fields.M4  = prefix + '_M4';
+    state.fields.min = prefix + '_min';
+    state.fields.max = prefix + '_max';
+
+    // Apply defaults from introspect (validation doesn't enforce them)
+    // Boolean defaults use || (since default is false)
+    // Numeric defaults use ?? (to preserve explicit zero)
+    state.biased = spec.biased || introspect.DEFAULT_OPTIONS.biased;
+    state.epsilon = spec.epsilon ?? introspect.DEFAULT_OPTIONS.epsilon;
+
+    // Store stats config for publish-to
+    state.stats = Object.assign( Object.create( null ), spec.stats );
+
+    // Output values (reused each update to avoid allocations)
+    // Only allocate slots for requested stats
+    state.n = state.stats.n ? NaN : undefined;
+    state.mean = state.stats.mean ? NaN : undefined;
+    state.variance = state.stats.variance ? NaN : undefined;
+    state.stddev = state.stats.stddev ? NaN : undefined;
+    state.cv = state.stats.cv ? NaN : undefined;
+    state.skew = state.stats.skew ? NaN : undefined;
+    state.kurtosis = state.stats.kurtosis ? NaN : undefined;
+    state.min = state.stats.min ? NaN : undefined;
+    state.max = state.stats.max ? NaN : undefined;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/digest-moments/introspect.js

@@ -0,0 +1,154 @@
+// nodes/digest-moments/introspect.js
+
+/**
+ * @fileoverview Introspection module for digestMoments node.
+ *
+ * Converts raw moments (n, M1-M4, min, max) from momentsDigest into
+ * displayable statistics (mean, variance, stddev, skew, kurtosis, cv, min, max).
+ *
+ * Skewness and kurtosis use population moments (m3/m2^1.5 and m4/m2^2 - 3).
+ * Variance uses Bessel's correction by default (M2/(n-1)).
+ * Epsilon threshold ensures numerical stability in division operations.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what statistics this node can compute */
+const SUPPORTED_STATS = [
+    'n',         // Sample count (pass-through)
+    'mean',      // Arithmetic mean (M1)
+    'variance',  // Sample variance (unbiased by default)
+    'stddev',    // Sample standard deviation
+    'skew',      // Population skewness: m3 / m2^1.5
+    'kurtosis',  // Excess kurtosis
+    'cv',        // Coefficient of variation
+    'min',       // Minimum (pass-through)
+    'max'        // Maximum (pass-through)
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    n: 'Sample count (pass-through from moments)',
+    mean: 'Arithmetic mean (M1)',
+    variance: 'Sample variance: M2 / (n - 1) for unbiased, M2 / n for biased',
+    stddev: 'Sample standard deviation: sqrt(variance)',
+    skew: 'Population skewness: m3 / m2^1.5 (requires n >= 3)',
+    kurtosis: 'Population excess kurtosis: m4 / m2^2 - 3 (requires n >= 4)',
+    cv: 'Coefficient of variation: stddev / |mean|',
+    min: 'Minimum value (pass-through from moments)',
+    max: 'Maximum value (pass-through from moments)'
+};
+
+/** Control methods available for triggers */
+const SUPPORTED_CONTROL_METHODS = {
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses node processing while keeping state visible',
+    unpause: 'Resumes node processing after pause'
+};
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Stateless node that converts raw moments into displayable statistics',
+    features: [
+        'Computes n, mean, variance, stddev, skew, kurtosis, cv, min, max',
+        'Population skewness and excess kurtosis from central moments',
+        'Configurable biased/unbiased variance (sample vs population)',
+        'Epsilon threshold for numerical stability in divisions',
+        'Graceful NaN handling for edge cases (n < 2, variance ≈ 0, mean ≈ 0)',
+        'Zero allocations in hot path',
+        'Stateless design - no reset/recompute needed'
+    ]
+};
+
+/** The type of this node */
+const NODE_TYPE = 'Digest Moments';
+
+// Attach static metadata once, from our constants by making a shallow copy.
+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 DEFAULT_OPTIONS = {
+    biased: false,    // Use sample (unbiased) statistics by default
+    epsilon: 1e-12    // Numerical stability threshold for division
+};
+
+// 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: 'Prefix (from upstream momentsDigest) cannot contain spaces'
+                }
+            }
+        },
+        biased: {
+            type: 'boolean',
+            required: false,
+            default: DEFAULT_OPTIONS.biased
+        },
+        epsilon: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.epsilon,
+            min: 0,
+            error: 'Epsilon must be a non-negative number'
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            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'
+                    }
+                }
+            },
+            error: `stats keys must be one of: ${SUPPORTED_STATS.join( ', ' )}`
+        }
+    },
+
+    // Cross-field validators (none needed for digestMoments)
+    crossFieldValidators: [],
+
+    // How to build the spec from DSL params
+    // DSL: .digestMoments( 'myStats', 'vibSD', { mean: {...} }, options )
+    // Pattern: nameXOutputsOptions
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...options
+    } )
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/digest-moments/publish-to.js

@@ -0,0 +1,34 @@
+// nodes/digest-moments/publish-to.js
+
+/**
+ * @fileoverview Publish function for digestMoments node.
+ *
+ * Publishes computed statistics to the message object.
+ * Uses publishNaN for graceful fault isolation when inputValidationFailed.
+ */
+
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+
+    // Propagate NaN if unhealthy (fault isolation)
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+
+    // Publish only requested stats
+    const stats = state.stats;
+    if ( stats.n ) msg[ stats.n.storeAs ] = state.n;
+    if ( stats.mean ) msg[ stats.mean.storeAs ] = state.mean;
+    if ( stats.variance ) msg[ stats.variance.storeAs ] = state.variance;
+    if ( stats.stddev ) msg[ stats.stddev.storeAs ] = state.stddev;
+    if ( stats.cv ) msg[ stats.cv.storeAs ] = state.cv;
+    if ( stats.skew ) msg[ stats.skew.storeAs ] = state.skew;
+    if ( stats.kurtosis ) msg[ stats.kurtosis.storeAs ] = state.kurtosis;
+    if ( stats.min ) msg[ stats.min.storeAs ] = state.min;
+    if ( stats.max ) msg[ stats.max.storeAs ] = state.max;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/digest-moments/recompute.js

@@ -0,0 +1,14 @@
+// nodes/digest-moments/recompute.js
+
+/**
+ * @fileoverview Recompute function for digestMoments node.
+ *
+ * This is a stateless node (no accumulation), so recompute is a no-op.
+ * Returns true to indicate the node can continue processing.
+ */
+
+const recompute = function ( _state ) {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/digest-moments/reset.js

@@ -0,0 +1,14 @@
+// nodes/digest-moments/reset.js
+
+/**
+ * @fileoverview Reset function for digestMoments node.
+ *
+ * This is a stateless node (no accumulation), so reset is a no-op.
+ * Returns true to indicate the node can continue processing.
+ */
+
+const reset = function ( _state ) {
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/digest-moments/update.js

@@ -0,0 +1,120 @@
+// nodes/digest-moments/update.js
+
+/**
+ * @fileoverview Update function for digestMoments node.
+ *
+ * Converts raw moments (n, M1-M4, min, max) into displayable statistics.
+ * Only computes stats that were requested in the spec.
+ */
+
+import { computeVariance, computeCV, computeSkew, computeKurtosis } from './formulas.js';
+
+/**
+ * Set all variance-dependent stats to NaN.
+ * @param {Object} state - Node state
+ * @param {Object} stats - Requested stats config
+ */
+const setVarianceStatsNaN = function ( state, stats ) {
+    if ( stats.variance ) state.variance = NaN;
+    if ( stats.stddev ) state.stddev = NaN;
+    if ( stats.cv ) state.cv = NaN;
+    if ( stats.skew ) state.skew = NaN;
+    if ( stats.kurtosis ) state.kurtosis = NaN;
+}; // setVarianceStatsNaN()
+
+/**
+ * Compute and store min/max pass-through stats.
+ * @param {Object} state - Node state
+ * @param {Object} stats - Requested stats config
+ * @param {Object} msg - Message with moment fields
+ */
+const computeMinMax = function ( state, stats, msg ) {
+    if ( stats.min ) {
+        const min = msg[ state.fields.min ];
+        state.min = Number.isFinite( min ) ? min : NaN;
+    }
+    if ( stats.max ) {
+        const max = msg[ state.fields.max ];
+        state.max = Number.isFinite( max ) ? max : NaN;
+    }
+}; // computeMinMax()
+
+/**
+ * Compute and store variance-dependent stats.
+ * @param {Object} state - Node state
+ * @param {Object} stats - Requested stats config
+ * @param {Object} msg - Message with moment fields
+ * @param {number} M1 - Mean
+ * @param {number} M2 - Second central moment
+ * @param {number} n - Sample count
+ * @param {number} m2 - Population variance (M2/n)
+ * @param {number} eps - Epsilon for numerical stability
+ */
+const computeVarianceStats = function ( state, stats, msg, M1, M2, n, m2, eps ) {
+    const variance = computeVariance( M2, n, state.biased );
+    const stddev = Math.sqrt( variance );
+
+    if ( stats.variance ) state.variance = variance;
+    if ( stats.stddev ) state.stddev = stddev;
+    if ( stats.cv ) state.cv = computeCV( stddev, M1, eps );
+    if ( stats.skew ) state.skew = computeSkew( msg[ state.fields.M3 ], n, m2, eps );
+    if ( stats.kurtosis ) state.kurtosis = computeKurtosis( msg[ state.fields.M4 ], n, m2, eps );
+}; // computeVarianceStats()
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+
+    state.inputValidationFailed = false;
+
+    // Read required moment fields from upstream momentsDigest
+    const n   = msg[ state.fields.n ];
+    const M1  = msg[ state.fields.M1 ];
+    const M2  = msg[ state.fields.M2 ];
+
+    // Validate required inputs (n, M1, M2 are always needed)
+    if ( !Number.isFinite( n ) || !Number.isFinite( M1 ) || !Number.isFinite( M2 ) ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    const eps = state.epsilon;
+    const stats = state.stats;
+
+    // n is pass-through (already validated as finite)
+    if ( stats.n ) state.n = n;
+
+    // Mean is always M1
+    if ( stats.mean ) state.mean = M1;
+
+    // Min/max are pass-through
+    computeMinMax( state, stats, msg );
+
+    // Check if any variance-dependent stats requested
+    const needsVariance = stats.variance || stats.stddev || stats.cv || stats.skew || stats.kurtosis;
+    if ( !needsVariance ) return state;
+
+    // Variance-dependent stats require n >= 2
+    if ( n < 2 ) {
+        setVarianceStatsNaN( state, stats );
+        return state;
+    }
+
+    // Population variance (M2/n) used for skew/kurtosis denominators
+    const m2 = M2 / n;
+
+    // When m2 < eps: variance/stddev are 0, cv/skew/kurtosis are NaN
+    if ( m2 < eps ) {
+        if ( stats.variance ) state.variance = 0;
+        if ( stats.stddev ) state.stddev = 0;
+        if ( stats.cv ) state.cv = NaN;
+        if ( stats.skew ) state.skew = NaN;
+        if ( stats.kurtosis ) state.kurtosis = NaN;
+        return state;
+    }
+
+    computeVarianceStats( state, stats, msg, M1, M2, n, m2, eps );
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/dwell-time-tracker/index.js

@@ -0,0 +1,14 @@
+// nodes/dwell-time-tracker/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';