@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/ratio/introspect.js

@@ -0,0 +1,155 @@
+// nodes/ratio/introspect.js
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+  'ratio'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    ratio: 'Ratio of x to y (x/y), optionally scaled or in decibels'
+};
+
+/** 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 = 'Ratio';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+   description: 'Computes the ratio of two numeric fields with optional logarithmic scale',
+    features: [
+        'Linear ratio computation (x/y)',
+        'Linear scaling of ratio output (x/y × k) for unit conversion',
+        'Decibel scale output (20*log₁₀(x/y)) for SNR and gain measurements',
+        'Numerically stable logarithm implementation',
+        'Division-by-zero protection with configurable minimum threshold',
+        'NaN propagation for invalid inputs'
+    ]
+};
+
+// 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 = {
+    logScale: false,
+    minY: 1e-10,
+    scaleBy: 1
+};
+
+// 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'
+                }
+            }
+        },
+        logScale: {
+            type: 'boolean',
+            required: false,
+            default: false
+        },
+        minY: {
+            type: 'number',
+            required: false,
+            default: 1e-10,  // Prevents division by extremely small numbers
+            validator: (value) => value >= 0,
+            error: 'minY must be non-negative'
+        },
+        scaleBy: {
+            type: 'number',
+            required: false,
+            default: 1,
+            validator: ( value ) => value > 0,
+            error: 'scaleBy must be a positive 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'
+                    }
+                }
+            }
+        }
+    },
+
+    // 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'
+        },
+        {
+            fields: [ 'logScale', 'scaleBy' ],
+            validator: ( spec ) => {
+                const hasLogScale = spec.logScale === true;
+                const hasScaleBy = spec.scaleBy !== undefined;
+                return !( hasLogScale && hasScaleBy );
+            },
+            error: 'logScale and scaleBy are mutually exclusive'
+        }
+    ],
+
+    // How to build the spec from DSL params
+    // Pattern: NAME_X_Y_OUTPUTS_OPTIONS -> (name, x, y, stats, options)
+    buildSpec: ( name, x, y, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x, y },
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

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

@@ -0,0 +1,15 @@
+// nodes/ratio/publish-to.js
+
+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.ratio.storeAs ] = state.ratio;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/ratio/recompute.js

@@ -0,0 +1,7 @@
+// nodes/ratio/recompute.js
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/ratio/reset.js

@@ -0,0 +1,7 @@
+// nodes/ratio/reset.js
+
+const reset = function () {
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/ratio/update.js

@@ -0,0 +1,47 @@
+// nodes/ratio/update.js
+
+const LN_TO_DB = 20 / Math.LN10;  // ≈ 8.6858896380650365
+
+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;
+    }
+
+    // Protection against division by zero or very small numbers.
+    // Returns NaN to signal invalid computation - downstream nodes
+    // can detect and handle this appropriately.
+    if ( Math.abs( yVal ) < state.minY ) {
+        state.ratio = NaN;  // Signal invalid ratio
+        return state;
+    }
+
+    // For log scale, both values must be positive.
+    // Log of non-positive numbers is undefined.
+    if ( state.logScale && ( xVal <= 0 || yVal <= 0 ) ) {
+        state.ratio = NaN;  // log of non-positive is undefined
+        return state;
+    }
+
+    state.ratio = ( state.logScale ) ?
+            ( Math.log( xVal ) - Math.log( yVal ) ) * LN_TO_DB :
+            ( xVal / yVal ) * state.scaleBy;
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/sanitize/index.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Sanitize Node - Universal data validation gate
+ *
+ * Validates data through configurable checks and maps invalid values to NaN.
+ * This provides a universal invalid marker that downstream nodes can detect
+ * with the fast check: value !== value
+ *
+ * Features:
+ * - Range validation with per-parameter bounds
+ * - Value list validation with allow/deny modes
+ * - Custom predicate validation
+ * - Works with both numeric and categorical data
+ *
+ * Configuration:
+ * - ranges: Object mapping field names to {min, max} bounds
+ * - valueList: Array of values to check against
+ * - containsValidValues: false = deny list (default), true = allow list
+ * - predicate: Optional function(value, msg) returning boolean
+ *
+ * Usage Examples:
+ *
+ * // Range validation (single field)
+ * .sanitize('temperature', {
+ *     ranges: {
+ *         temperature: { min: -40, max: 150 }
+ *     }
+ * })
+ *
+ * // Multi-field with apply pattern
+ * .sanitize('sensors', ['temperature', 'pressure', 'flow'], ['sanitized'], {
+ *     ranges: {
+ *         temperature: { min: -40, max: 150 },
+ *         pressure: { min: 0, max: 200 },
+ *         flow: { min: 0, max: 1000 }
+ *     }
+ * })
+ *
+ * // Deny list (blacklist) - common error codes
+ * .sanitize('signal', {
+ *     valueList: [32767, -9999, "ERROR", "N/A"],
+ *     containsValidValues: false
+ * })
+ *
+ * // Allow list (whitelist) - valid states only
+ * .sanitize('state', {
+ *     valueList: ["RUNNING", "IDLE", "STOPPED"],
+ *     containsValidValues: true
+ * })
+ *
+ * // Custom validation with predicate
+ * .sanitize('reading', {
+ *     predicate: (value, msg) => value > msg.ambient
+ * })
+ *
+ * // Combined validation (checks in order: range, valueList, predicate)
+ * .sanitize('sensor', {
+ *     ranges: {
+ *         sensor: { min: 0, max: 100 }
+ *     },
+ *     valueList: [32767, -9999],
+ *     containsValidValues: false,
+ *     predicate: (value, msg) => value !== msg.lastValue
+ * })
+ *
+ * Failure Reporting:
+ * - failureReason: 'range' | 'valueList' | 'predicate' | null
+ * - failedValue: The value that failed validation
+ *
+ */
+
+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/sanitize/init.js

@@ -0,0 +1,82 @@
+import { validateWithSchema } from '../../core/utils/validate/index.js';
+import { getDSLMetadata, getNodeType, DEFAULT_OPTIONS } from './introspect.js';
+import { resolveNestedObject, resolveArray } from '../../core/utils/options/resolve-field-keyed.js';
+import { asTunable } from '../../core/tunable/index.js';
+
+const init = function ( spec ) {
+    // Validate specification
+    const metadata = getDSLMetadata();
+    const validation = validateWithSchema(
+        {
+            ...metadata.specSchema,
+            _crossFieldValidators: metadata.crossFieldValidators
+        },
+        spec,
+        'spec'
+    );
+    validation.throwIfInvalid( getNodeType() );
+
+    // Create state after validation passes
+    const state = Object.create( null );
+
+    // Ensure node is enabled by default
+    state.disable = false;
+    state.pause = false;
+
+    // Core configuration
+    state.x = spec.from.x;
+    state.stats = spec.stats;
+
+    // Pre-allocate failure reason strings (no allocations in hot path)
+    state.REASON_RANGE = 'range';
+    state.REASON_VALUE_LIST = 'valueList';
+    state.REASON_PREDICATE = 'predicate';
+
+    // Range configuration. Three shapes, all resolved by resolveNestedObject:
+    //   Direct:      { ranges: { min: -40, max: 85 } }
+    //   Field-keyed: { ranges: { temp: { min: -40, max: 85 } } }
+    //   Tunable:     { ranges: lookupByField('shift', { day: {...}, night: {...} }, {...}) }
+    if ( typeof spec.ranges === 'function' ) {
+        // Dynamic ranges (tunable) - resolve at runtime
+        state.rangesFn = spec.ranges;
+        state.resolvedRangeSpec = null;  // Not yet resolved
+        state.hasRange = true;
+    } else {
+        // Static ranges - resolve field-keying at init time
+        const rangeSpec = resolveNestedObject( spec.ranges, state.x, [ 'min', 'max' ] );
+        if ( rangeSpec ) {
+            state.rangesFn = asTunable( rangeSpec );
+            state.resolvedRangeSpec = rangeSpec;  // Known at init
+            state.hasRange = true;
+        } else {
+            state.hasRange = false;
+            state.rangesFn = null;
+            state.resolvedRangeSpec = null;
+        }
+    }
+    state.tunableErrorLogged = false;
+
+    // Value list configuration (use Set for O(1) lookups)
+    // Supports both direct: { valueList: [1, 2, 3] }
+    // and field-keyed: { valueList: { temp: [1, 2], pressure: [3, 4] } }
+    const valueListSpec = resolveArray( spec.valueList, state.x );
+    const hasValueList = valueListSpec?.length > 0;
+    state.valueSet = hasValueList ? new Set( valueListSpec ) : null;
+    state.containsValidValues = spec.containsValidValues ?? DEFAULT_OPTIONS.containsValidValues;
+
+    // Custom predicate
+    state.predicate = spec.predicate || null;
+    // Log suppression: one log per error episode; reset on recovery.
+    state.predicateErrorLogged = false;
+
+    // Node metadata
+    state.nodeType = getNodeType();
+
+    // Initialize stats (null = no failure)
+    state.failureReason = null;
+    state.failedValue = null;
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/sanitize/introspect.js

@@ -0,0 +1,194 @@
+import { validators } from '../../core/utils/validate/index.js';
+import { resolveNestedObject, resolveArray } from '../../core/utils/options/resolve-field-keyed.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'failureReason',
+    'failedValue'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    failureReason: 'Type of validation failure: "range", "valueList", or "predicate" (null if valid)',
+    failedValue: 'The value that failed validation (null if valid)'
+};
+
+/** 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 = 'Sanitize';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Universal data validation gate mapping invalid values to NaN',
+    features: [
+        'Range-based validation with per-parameter bounds',
+        'Value list validation with allow/deny modes',
+        'Custom predicate validation',
+        'Works with numeric and categorical data',
+        'Universal NaN invalid marker for downstream checking'
+    ]
+};
+
+// 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() } );
+
+// Spec default values
+export const DEFAULT_OPTIONS = {
+    valueList: [],
+    containsValidValues: false  // false = deny list, true = allow list
+};
+
+/** Parameters that support tunable (dynamic) values */
+export const TUNABLE_PARAMS = [ 'ranges' ];
+
+// DSL Metadata for transpilation
+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: 'string',
+                    required: true,
+                    validator: validators.noSpaces,
+                    error: 'Field name cannot contain spaces'
+                }
+            }
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        },
+        ranges: {
+            type: 'nestedObjectOrFunctionOrFieldKeyed',
+            required: false,
+            // Accepts three shapes the runtime resolver already handles:
+            //   direct       { min: 0, max: 100 }
+            //   field-keyed  { temp: { min: -40, max: 85 }, ... }
+            //   tunable      (msg) => ({ min: msg.lo, max: msg.hi })
+            // The inner shape below (both bounds required, numeric) is read by
+            // the type validator; min <= max is checked in a cross-field rule.
+            properties: {
+                min: { type: 'number', required: true },
+                max: { type: 'number', required: true }
+            }
+        },
+        valueList: {
+            type: 'arrayOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.valueList,
+            itemSchema: {
+                type: 'any'  // Can be numbers, strings, booleans, etc.
+            },
+            // eslint-disable-next-line no-self-compare
+            validator: ( arr ) => !Array.isArray( arr ) || arr.every( ( x ) => x === x ) // reject NaN
+        },
+        containsValidValues: {
+            type: 'boolean',
+            required: false,
+            default: DEFAULT_OPTIONS.containsValidValues
+        },
+        predicate: {
+            type: 'function',
+            required: false,
+            arity: 2,
+            error: 'Predicate must accept (value, msg) parameters'
+        }
+    },
+
+    crossFieldValidators: [
+        {
+            fields: [ 'ranges', 'valueList', 'predicate' ],
+            validator: ( spec ) => {
+                // ranges can be a function (tunable) or object (direct or field-keyed)
+                const hasRanges = typeof spec.ranges === 'function' ||
+                    ( spec.ranges && Object.keys( spec.ranges ).length > 0 );
+                // Resolve valueList for the node's field so a direct array and a
+                // field-keyed map both count as "a method was provided".
+                const valueList = resolveArray( spec.valueList, spec.from?.x );
+                const hasValueList = Array.isArray( valueList ) && valueList.length > 0;
+                const hasPredicate = typeof spec.predicate === 'function';
+                return hasRanges || hasValueList || hasPredicate;
+            },
+            error: 'Must provide at least one validation method: ranges, valueList, or predicate'
+        },
+        {
+            fields: [ 'from.x', 'ranges' ],
+            validator: ( spec ) => {
+                // If ranges is a function, validation deferred to runtime
+                if ( typeof spec.ranges === 'function' ) return true;
+                // No ranges specified — nothing to check here
+                if ( !spec.ranges || Object.keys( spec.ranges ).length === 0 ) {
+                    return true;
+                }
+                // A direct range resolves for this field; a field-keyed map must
+                // carry an entry for it. Use the same resolver the runtime uses
+                // so validation and runtime agree on what "resolves" means.
+                return resolveNestedObject( spec.ranges, spec.from.x, [ 'min', 'max' ] ) !== undefined;
+            },
+            error: 'Ranges must be a direct { min, max } or a per-field map that includes the field this node reads'
+        },
+        {
+            fields: [ 'ranges' ],
+            validator: ( spec ) => {
+                // If ranges is a function, validation deferred to runtime
+                if ( typeof spec.ranges === 'function' ) return true;
+                if ( !spec.ranges ) return true;
+                // A direct range carries min/max itself; a field-keyed map carries
+                // one range per field. Check min <= max on whichever shape was given.
+                const isDirect = ( 'min' in spec.ranges ) || ( 'max' in spec.ranges );
+                const ranges = isDirect ? [ spec.ranges ] : Object.values( spec.ranges );
+                return ranges.every( ( range ) => range.min <= range.max );
+            },
+            error: 'Range min must be less than or equal to max'
+        }
+    ],
+
+    buildSpec: ( name, x, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x },
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

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

@@ -0,0 +1,15 @@
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+
+    // Publish failure information if present
+    if ( state.failureReason ) {
+        if ( state.stats.failureReason ) {
+            msg[ state.stats.failureReason.storeAs ] = state.failureReason;
+        }
+        if ( state.stats.failedValue ) {
+            msg[ state.stats.failedValue.storeAs ] = state.failedValue;
+        }
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/sanitize/recompute.js

@@ -0,0 +1,8 @@
+const recompute = function ( _state ) {
+    // No long-running accumulations
+    // Validation is stateless per sample
+
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/sanitize/reset.js

@@ -0,0 +1,14 @@
+const reset = function ( state ) {
+    // Stateless validation node - nothing to reset
+    // Failure status is per-message, not accumulated
+
+    state.failureReason = null;
+    state.failedValue = null;
+    // Clear error suppression so next error episode is logged
+    state.predicateErrorLogged = false;
+    state.tunableErrorLogged = false;
+
+    return state;
+}; // reset()
+
+export default reset;