@winkjs/composer 0.0.2 → 0.4.1

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

@@ -0,0 +1,59 @@
+// nodes/dwell-time-tracker/init.js
+
+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;
+
+    // Extract configuration
+    state.predicate = spec.predicate;
+    state.timestampField = spec.timestampField || null;
+
+    // Config copy
+    state.stats = spec.stats;
+
+    // Track if we need duration tracking
+    state.needsDurationTracking = Boolean(
+        spec.stats.dwellTime ||
+        spec.stats.dwellSamples ||
+        spec.stats.dutyCycle
+    );
+
+    // State variables - clear boolean semantics
+    state.active = false;       // Current state
+    state.wasActive = false;    // Previous state (for edge detection)
+
+    // Duration tracking state
+    state.stateEnteredAt = null;  // When current state was entered (milliseconds)
+    state.dwellTime = null;          // Duration of previous state (milliseconds)
+    state.dwellSamples = null;       // Samples in the previous state
+    state.sampleCount = 0;
+    // Duty cycle tracking mechanism
+    state.dutyCycleTracker = Object.create( null );
+    // It is indexed by `wasActive` state as dwellTime is always for wasActive state (see update.js)
+    state.dutyCycleTracker.true = null;
+    state.dutyCycleTracker.false = null;
+    state.dutyCycle = null;         // Used for publish duty cycle
+
+    // First message flag
+    state.hasSeenFirstValue = false;
+
+    state.nodeType = introspect.getNodeType();
+    state.inControlPhase = false;
+
+    // Log suppression: one log per error episode; reset on recovery.
+    state.predicateErrorLogged = false;
+
+    return state;
+}; // init()
+
+export default init;

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

@@ -0,0 +1,137 @@
+// nodes/dwell-time-tracker/introspect.js
+
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'active',        // Current boolean state (passthrough)
+    'dwellTime',     // Duration of previous state (milliseconds)
+    'dwellSamples',  // Number of samples in previous state
+    'dutyCycle'      // Duty cycle ( active / ( active + inactive ) )
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    active: 'Current boolean state of the tracked predicate condition.',
+    dwellTime: 'Duration in milliseconds for which the previous state was maintained; populated only at the moment of state transition, otherwise null.',
+    dwellSamples: 'Number of samples processed while in the previous state; populated only at the moment of state transition, otherwise null.',
+     dutyCycle: 'Fraction of time spent in true state over one complete cycle (true time / total time); populated after completing a full cycle (two consecutive transitions), otherwise null.'
+};
+
+
+/** 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 = 'Dwell Time Tracker';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Tracks boolean state transitions with edge detection and dwell time measurement.',
+    features: [
+        'Evaluates a predicate function to detect state changes based on user-defined logic.',
+        'Measures dwell time in the previous state (in milliseconds).',
+        'Counts dwell samples in the previous state.',
+        'Identifies rising and falling edges using `dwellTime !== null` or `dwellSamples !== null` checks.',
+        'Enables easy computation of the previous toggle time via `timestamp - dwellTime`.',
+        'Supports both message timestamps and system time for flexible timing sources.'
+    ]
+};
+
+
+/** Spec default values */
+export const DEFAULT_OPTIONS = {
+    // No defaults needed for this node
+};
+
+// 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()
+} );
+
+// 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'
+        },
+        predicate: {
+            type: 'function',
+            required: true,
+            arity: 1,
+            validator: composerValidators.predicate,
+            error: 'Predicate must be a function accepting one parameter (msg)'
+        },
+        timestampField: {
+            type: 'string',
+            required: false,
+            validator: validators.noSpaces,
+            error: 'Timestamp field name cannot contain spaces'
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            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'
+                    }
+                }
+            }
+        },
+        triggers: {
+            type: 'array',
+            required: false,
+            itemSchema: {
+                type: 'object',
+                validator: composerValidators.trigger,
+                error: 'Invalid trigger specification'
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        composerValidators.noSelfTriggers
+    ],
+
+    // How to build the spec from DSL params
+    buildSpec: ( name, predicate, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            predicate,
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/dwell-time-tracker/publish-to.js

@@ -0,0 +1,22 @@
+// nodes/dwell-time-tracker/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;
+    }
+
+    // Iterate only over configured stats
+    const stats = state.stats;
+    for ( const statName in stats ) {
+        if ( Object.prototype.hasOwnProperty.call(stats,  statName ) ) {
+            msg[ stats[ statName ].storeAs ] = state[ statName ];
+        }
+    }
+}; // publishTo()
+
+export default publishTo;

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

@@ -0,0 +1,8 @@
+// nodes/dwell-time-tracker/recompute.js
+
+const recompute = function () {
+    // Nothing to recompute - dwell time tracker is stateless except for timing memory
+    return true;
+}; // recompute()
+
+export default recompute;

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

@@ -0,0 +1,23 @@
+// nodes/dwell-time-tracker/reset.js
+
+const reset = function ( state ) {
+    // Reset to initial conditions
+    state.active = false;
+    state.wasActive = false;
+    state.hasSeenFirstValue = false;
+    state.stateEnteredAt = null;
+    state.dwellTime = null;
+    state.dwellSamples = null;
+    state.sampleCount = 0;
+
+    state.dutyCycleTracker.true = null;
+    state.dutyCycleTracker.false = null;
+    state.dutyCycle = null;
+
+    // Clear error suppression so next error episode is logged
+    state.predicateErrorLogged = false;
+
+    return true;
+}; // reset()
+
+export default reset;

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

@@ -0,0 +1,103 @@
+// nodes/dwell-time-tracker/update.js
+
+import { executeTriggers } from '../../core/utils/node/index.js';
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    // Reset on each update
+    state.inputValidationFailed = false;
+
+    // Evaluate the predicate to compute the value
+    let value;
+
+    try {
+        value = state.predicate( msg );
+        // Recovery: clear log-suppression flag on success
+        if ( state.predicateErrorLogged ) state.predicateErrorLogged = false;
+    } catch ( error ) {
+        // Signals publishing NaN for all demanded `stats` in publishTo.
+        state.inputValidationFailed = true;
+        // Log first error per episode; suppress subsequent until recovery
+        if ( !state.predicateErrorLogged ) {
+            state.predicateErrorLogged = true;
+            console.error( `WinkComposer/dwellTimeTracker: predicate threw exception: ${error.message}` );
+        }
+        return state;
+    }
+    // Skip if not a valid boolean
+    if ( typeof value !== 'boolean' ) {
+        // Signals publishing NaN for all demanded `stats` in publishTo.
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Get timestamp (from message or current time)
+    const now = state.timestampField ? msg[ state.timestampField ] : Date.now();
+    // Handle time related faults gracefully: ensure their isolation
+    if ( !Number.isFinite( now ) ) {
+        // Signals publishing NaN for all demanded `stats` in publishTo.
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Remember previous state for edge detection
+    state.wasActive = state.active;
+
+    // Clear edge flags (they're momentary - true for one cycle only)
+    state.dwellTime = null;        // Clear duration (only set on state change)
+    state.dwellSamples = null;     // Clear samples.
+    state.dutyCycle = null;        // Clear duty cycle
+
+    // Update active state (passthrough)
+    if ( state.hasSeenFirstValue ) {
+        state.active = value;
+    } else {
+        // First value - set initial state
+        state.active = value;
+        state.hasSeenFirstValue = true;
+        state.sampleCount = 1; // Seeing the very first sample
+        // Initialize state entry time ONLY for first value so that
+        // on change the first known value of time can be published
+        if ( state.needsDurationTracking ) {
+            state.stateEnteredAt = now;
+        }
+        // Since this is the first message, no need to check transition: simply return.
+        return state;
+    }
+
+    // Detect edges and calculate duration
+    if ( state.active !== state.wasActive ) { // eslint-disable-line no-negated-condition
+        // Calculate duration and save entry timestamp
+        if ( state.needsDurationTracking ) {
+            if ( state.stateEnteredAt !== null ) {
+                state.dwellTime = now - state.stateEnteredAt;
+                if ( state.dwellTime < 0 ) state.dwellTime = 0;
+                // Save for publishing
+                state.dwellSamples = state.sampleCount;
+
+                // Store current dwell time FIRST: Update the tracker by `wasActive` index.
+                state.dutyCycleTracker[ state.wasActive ] = state.dwellTime;
+
+                if ( state.dutyCycleTracker.true !== null && state.dutyCycleTracker.false !== null ) {
+                    // Both on and off times accumulated - compute duty cycle for complete cycle
+                    const totalDuration = state.dutyCycleTracker.true + state.dutyCycleTracker.false;
+                    // Guard: zero total duration (identical timestamps) — NaN signals invalid computation
+                    state.dutyCycle = ( totalDuration > 0 ) ? ( state.dutyCycleTracker.true / totalDuration ) : NaN;
+                    // Reset tracker
+                    state.dutyCycleTracker.true = null;
+                    state.dutyCycleTracker.false = null;
+                }
+            }
+            state.stateEnteredAt = now;  // Update for new state
+        }
+
+        // First sample in the changed state
+        state.sampleCount = 1;
+        // Trigger controls on state change
+        executeTriggers( state );
+    } else state.sampleCount += 1; // Count samples as long as state is unchanged
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/emit-if/helpers.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Helper functions for emitIf node
+ *
+ * Status signal emission for predicate error state transitions, and the
+ * shared publish-failure recording used by both the data path (update.js)
+ * and the status-signal path below.
+ */
+
+/**
+ * Static fallback error the framework substitutes when an adapter breaks
+ * the return contract — no result object at all, or `{ ok: false }` with
+ * no `error` (ADR-018 error vocabulary). A module-level singleton, so the
+ * hot path allocates nothing. Mirrors persist-if.
+ */
+const MALFORMED_RESULT_ERROR = {
+    code: 'MALFORMED_RESULT',
+    message: 'emitter returned a malformed publish result (expected { ok, error? })'
+};
+
+/**
+ * Throws when an annotate return is not a plain object — arrays pass a
+ * bare typeof check but are just as wrong. A flow-authoring bug surfaces
+ * in the node's own error episode (the predicate/annotate try in
+ * update.js), never downstream where it would masquerade as an adapter
+ * failure. Mirrors persist-if.
+ *
+ * @param {*} record - The annotate return value
+ * @throws {Error} Naming the offending type
+ */
+const assertAnnotateReturn = function ( record ) {
+    const got = record === null ? 'null' :
+        ( Array.isArray( record ) ? 'array' : typeof record );
+    if ( got === 'object' ) {
+        return;
+    }
+    throw new Error( `annotate must return an object, got ${got}` );
+}; // assertAnnotateReturn()
+
+/**
+ * Records a failed publish into the node's failure episode: updates the
+ * last* fields, and on the first failure of an episode captures the first*
+ * fields and logs one console.error (repeats stay quiet until a successful
+ * publish closes the episode — see update.js).
+ *
+ * @param {Object} state - Node state
+ * @param {Object} error - The `{ code, message }` from the emitter's
+ *   `{ ok: false }` return (ADR-018 sink return contract)
+ */
+const recordEmissionFailure = function ( state, error ) {
+    state.emissionErrors += 1;
+    state.lastEmissionError = error.message;
+    state.lastEmissionErrorCode = error.code;
+    if ( !state.emitErrorLogged ) {
+        state.emitErrorLogged = true;
+        state.firstEmissionError = error.message;
+        state.firstEmissionErrorCode = error.code;
+        console.error( state.emitErrorLogPrefix + error.code + '): ' + error.message );
+    }
+}; // recordEmissionFailure()
+
+/**
+ * Emits disable/enable status signal to the wired emitter. Published
+ * unconditionally (no connectivity pre-check per ADR-018 — during a
+ * disconnect the signal is still accepted into the emitter's in-process
+ * buffer); a failed publish rides the same failure episode as data
+ * emissions.
+ *
+ * @param {Object} state - Node state containing emitter and topic
+ * @param {boolean} disable - Whether to disable (true) or enable (false)
+ * @param {string} reason - Reason for disable
+ */
+const emitStatusSignal = function ( state, disable, reason ) {
+    if ( !state.emitter ) {
+        return;
+    }
+
+    const signal = {
+        $disable: disable,
+        $reason: reason,
+        $timestamp: Date.now()
+    };
+
+    // Guarded read: this path runs inside update()'s catch block, so a
+    // TypeError here would escape update() and kill the pipeline. A
+    // malformed result counts as a failure with the static fallback
+    // error instead.
+    const result = state.emitter.publishNow( state.topic, signal );
+    if ( result && result.ok ) {
+        return;
+    }
+    recordEmissionFailure( state, ( result && result.error ) || MALFORMED_RESULT_ERROR );
+}; // emitStatusSignal()
+
+export { assertAnnotateReturn, emitStatusSignal, recordEmissionFailure, MALFORMED_RESULT_ERROR };

package/src/nodes/emit-if/index.js

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Public API for emitIf node
+ */
+
+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';
+// Re-export everything from introspection
+export * from './introspect.js';
+
+// Note: Control signals (disable/enable/pause/unpause) are intentionally
+// not exported. emitIf is a side-effect terminal node — it should always
+// process when the pipeline runs. Use predicate logic for conditional
+// emission. Consistent with persist-if (peer terminal node).

package/src/nodes/emit-if/init.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Initialization for emitIf node
+ *
+ * Validates specification and creates initial state for conditional
+ * emission to external systems (MQTT, GPIO, terminal).
+ */
+
+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 );
+
+    // Core configuration
+    state.nodeType = introspect.getNodeType();
+    state.name = spec.name;
+    state.requires = spec.requires;
+    state.predicate = spec.predicate;
+    state.target = spec.target;
+    state.emitter = spec.emitter;
+    state.annotate = spec.annotate || null;
+    state.insightType = spec.insightType;
+    // state.topic is injected by the partition manager during partition
+    // creation (not per-message). The topic encodes partition-scoped
+    // identity: edgeDeviceId/partitionId/specialization/insightType.
+    // This is an acceptable exception to "state shape fixed at init"
+    // because the partition ID is unknown until the first message arrives.
+    // See: partition-manager/update.js — MQTT TOPIC INJECTION block.
+    // Used by: update.js (emitter.publishNow) and helpers.js (status signals).
+
+    // State transition tracking (semantic — controls status signals)
+    state.inErrorState = false;
+    // Log suppression: one log per error episode; reset on recovery.
+    state.predicateErrorLogged = false;
+
+    // Statistics for observability
+    state.emissionCount = 0;
+    state.passCount = 0;
+    state.lastEmissionTime = null;
+
+    // Error tracking
+    state.emissionErrors = 0;
+    state.lastEmissionError = null;
+    // Mirrors persistIf: the code from the emitter's { ok: false, error:
+    // { code, message } } return; null when the error came from a predicate
+    // exception (predicate failures are not classified by the contract).
+    state.lastEmissionErrorCode = null;
+    // Publish-failure episode (mirrors persistIf's write-failure episode):
+    // one console.error per episode; a successful publish closes it. The
+    // first* fields keep the episode-opening error — in a cascade the LAST
+    // error is the symptom and the FIRST is the cause. They survive
+    // recovery for post-mortem reads and are overwritten only when the
+    // next episode opens.
+    state.emitErrorLogged = false;
+    state.firstEmissionError = null;
+    state.firstEmissionErrorCode = null;
+    // Static log prefix pre-built here per ADR-004 (no string building in
+    // update beyond the two runtime fields, and only once per episode).
+    state.emitErrorLogPrefix = `WinkComposer/emitIf: publish failed (node=${state.name}, insightType=${state.insightType}, code=`;
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/emit-if/introspect.js

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Introspection metadata for emitIf node
+ *
+ * Single source of truth for DSL metadata, validation schema,
+ * and node capabilities. Used by flow transpiler and documentation.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+const SUPPORTED_STATS = [];  // Pass-through node, no stats to publish
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {};  // No stats, no descriptions
+
+/** Control methods available for triggers (none - side-effect only node) */
+const SUPPORTED_CONTROL_METHODS = {};
+
+/** The type of this node */
+const NODE_TYPE = 'Emit If';
+
+/** Node capabilities for documentation (kept accurate to shipping code) */
+const CAPABILITIES = {
+    description: 'Conditionally emits messages to external targets (MQTT, terminal) without disrupting pipeline flow',
+    features: [
+        'Pure pass-through behavior - messages continue unchanged',
+        'Conditional emission based on predicate function',
+        'Publishes through the emitter handle\'s publishNow and reads its classified { ok, error } result',
+        'Optional annotate hook shapes the emitted payload; a non-object return is rejected into the node\'s error episode',
+        'Status signals ($disable / $reason) on predicate error episodes and on recovery',
+        'Publish failures open a loud error episode (one console.error per episode); the pipeline never stops',
+        'Zero overhead when predicate evaluates to false'
+    ]
+};
+
+// 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() } );
+export const DEFAULT_OPTIONS = {};
+
+// DSL Metadata for transpilation
+const DSL_METADATA = {
+    // Validation schema
+    specSchema: {
+        nodeType: {
+            type: 'string',
+            required: true,
+            value: NODE_TYPE
+        },
+        name: {
+            type: 'string',
+            required: true,
+            validator: validators.identifier,
+            error: 'Name must be a valid JavaScript identifier'
+        },
+        predicate: {
+            type: 'function',
+            required: true,
+            arity: 1,
+            error: 'Predicate must be a function with exactly one parameter (inputs)'
+        },
+        target: {
+            type: 'string',
+            required: true,
+            validator: validators.oneOf( [ 'mqtt', 'gpio', 'terminal' ] ),
+            error: 'Target type must be "mqtt", "gpio", or "terminal"'
+        },
+        insightType: {
+            type: 'string',
+            required: true,
+            error: 'Insight type must be specified for topic construction'
+        },
+        annotate: {
+            type: 'function',
+            required: false,
+            arity: 1,
+            error: 'Annotate must be a function with exactly one parameter (msg)'
+        },
+        stats: {
+            type: 'object',
+            required: false,
+            propertyNames: [],  // No stats for pass-through node
+            error: 'EmitIf is a pass-through node and does not support stats'
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+    ],
+
+    // Build spec from DSL
+    buildSpec: ( name, predicate, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        predicate,
+        ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/emit-if/publish-to.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview PublishTo function for emitIf node
+ *
+ * Pass-through node — message continues unchanged.
+ * No fields are added to the outgoing message.
+ */
+
+const publishTo = function ( _state, _msg ) {
+    // Pure pass-through node - message continues unchanged
+    // No fields are added to the message
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/emit-if/recompute.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Recompute function for emitIf node
+ *
+ * No numerical computation to stabilize.
+ */
+
+const recompute = function ( _state ) {
+    // No numerical computation to stabilize
+    return true;
+}; // recompute()
+
+export default recompute;