@winkjs/composer 0.0.2 → 0.4.1

package/src/core/emitter-manager/terminal/formatters.js

@@ -0,0 +1,160 @@
+// core/emitter-manager/terminal/formatters.js
+
+/**
+ * @fileoverview Per-column value formatters for the terminal emitter.
+ *
+ * Same role for terminal as `questdb/writers.js` plays for QDB: takes
+ * an asset-class column slice at startup and returns a value-formatter
+ * closure pre-resolved to the per-column quantization. Hot path is a
+ * lookup + a quantizer call, no per-message allocation.
+ *
+ * Quantization is delegated to the shared `core/utils/quantize` helper
+ * — the same one QDB's `writers.js` consumes. Both sinks compute
+ * identical rounded values for the same input; cross-sink alignment is
+ * structural, not coincidental.
+ *
+ * What this file does NOT do: validate the column slice. Validation
+ * lives in `assert-columns.js` and runs once at startup before the
+ * formatter is built. By the time these helpers see the columns map,
+ * every `resolution` is known to be a positive finite number (or
+ * absent, in which case the column falls through to global precision).
+ *
+ * @see ./assert-columns.js (defensive validation that runs first)
+ * @see ../../utils/quantize/index.js (shared quantizer used here and by QDB)
+ * @see ../../storage-manager/questdb/writers.js (sister consumer)
+ */
+
+import { buildResolutionQuantizer } from '../../utils/quantize/index.js';
+
+/**
+ * Build a column-name → quantizer-closure map at startup from the asset
+ * class column slice. Only float64 columns with a defined positive
+ * resolution contribute; everything else falls through to the global
+ * precision at format time.
+ *
+ * Each quantizer applies the same formula QDB's `createFloat64Writer`
+ * uses, so a value declared with `resolution: R` produces the same
+ * rounded number in both sinks:
+ *
+ *     quantized = Math.round( value * invResolution ) * resolution
+ *     clean     = +quantized.toFixed( decimalPlaces )
+ *
+ * `Math.round(v / r) * r` snaps the value to the nearest multiple of
+ * `r` (the resolution grid). Then `toFixed( decimalPlaces )` cleans up
+ * floating-point noise like `10.100000000001` → `10.1`. The closure
+ * pre-resolves `invResolution` and `decimalPlaces` at startup so the
+ * per-message hot path is one multiply, one round, one multiply, one
+ * `toFixed` — no allocations, no recomputation.
+ *
+ * The per-column quantizer takes precedence over the integer-passthrough
+ * check in the formatter — when a column declares `resolution: 5`, an
+ * input value of `1234` gets quantized to `1235` (the nearest multiple
+ * of 5), regardless of the value's `Number.isInteger` shape. This
+ * matches QDB's behaviour: the asset class declared the resolution,
+ * the data MUST be aligned to it, integer-shaped or not.
+ *
+ * Decimal places follow the same rule as QDB writers:
+ * - `resolution = 0.1`   → 1 decimal place
+ * - `resolution = 0.01`  → 2 decimal places
+ * - `resolution = 0.001` → 3 decimal places
+ * - `resolution = 5`     → 0 decimal places (whole-number resolution)
+ * - `resolution = 1`     → 0 decimal places (effectively passthrough)
+ *
+ * Returns `Object.create(null)` so per-column lookups never accidentally
+ * hit `Object.prototype` keys (e.g., a column literally named
+ * `'toString'` or `'hasOwnProperty'`). The keys are runtime-supplied
+ * column names — exactly the case the rule says use a prototype-less
+ * dictionary for.
+ *
+ * @param {Object} columns - the columns map from the asset class slice
+ *   (typically `config.assetClass.columns` post wire-semantics injection)
+ * @returns {Object} prototype-less map of column name → `(v) → number`
+ */
+const buildColumnQuantizers = function ( columns ) {
+    const map = Object.create( null );
+
+    if ( !columns || typeof columns !== 'object' ) {
+        return map;
+    }
+
+    const colNames = Object.keys( columns );
+    for ( let i = 0; i < colNames.length; i += 1 ) {
+        const colName = colNames[ i ];
+        const colSpec = columns[ colName ];
+        if ( colSpec && colSpec.type === 'float64' ) {
+            // Delegate to the shared quantizer. Returns null when the
+            // column does not need quantization (no resolution declared
+            // or resolution = 1); we simply skip those columns and
+            // they fall back to the global precision at format time.
+            const quantize = buildResolutionQuantizer( colSpec.resolution );
+            if ( quantize ) {
+                map[ colName ] = quantize;
+            }
+        }
+    }
+
+    return map;
+};
+
+/**
+ * Build a value formatter closure that uses each column's quantizer
+ * (when one was registered for the column name) and the global
+ * `precision` config otherwise. Receives `(key, v)` so it can look up
+ * the column-specific quantizer by name.
+ *
+ * Branch order in the returned formatter:
+ * 1. null → `'null'`
+ * 2. boolean → as-is
+ * 3. string → as-is
+ * 4. non-number (object, undefined, etc.) → `String( v )`
+ * 5. **per-column quantizer** if the column registered one (this fires
+ *    even for integer values, because the column declared a resolution
+ *    and the data MUST be on the resolution grid)
+ * 6. integer → as-is (only reached when no per-column quantizer
+ *    applies; preserves the original behaviour for non-resolution columns)
+ * 7. very small non-zero (`|v| < 0.001`) → exponential notation
+ *    using the **global** precision (intentionally; see note below)
+ * 8. normal decimal → `+v.toFixed( precision )` (global fallback)
+ *
+ * **Why the exponential branch keeps using global precision.** Resolution
+ * describes the meaningful step size on the absolute scale. For values
+ * below that step — say `resolution: 0.1` and `v = 0.0003` — the
+ * "correctly rounded" value is `0`, but printing `0` for a non-zero
+ * value loses diagnostic information. Terminal is a debugging tool;
+ * the exponential form (`3e-4`) is more useful to a human eye than
+ * `0`. This is an intentional carve-out, not a bug. Note that this
+ * branch only fires for columns WITHOUT a per-column quantizer; columns
+ * with one always go through the quantizer path (step 5).
+ *
+ * @param {number} precision - Default decimal places when no per-column
+ *   quantizer is registered
+ * @param {Object} columnQuantizers - Map produced by
+ *   `buildColumnQuantizers`. Pass an empty `Object.create(null)` if no
+ *   asset class was supplied — the formatter then falls back to global
+ *   precision for every column.
+ * @returns {function(string, *): *} Formatter function `(key, v) → out`
+ */
+const createValueFormatter = function ( precision, columnQuantizers ) {
+    return function ( key, v ) {
+        if ( v === null ) return 'null';
+        if ( typeof v === 'boolean' ) return v;
+        if ( typeof v === 'string' ) return v;
+        if ( typeof v !== 'number' ) return String( v );
+
+        // Per-column quantizer takes precedence over every other rule:
+        // the column declared a resolution, the value MUST snap to the
+        // grid (matching what QDB will store). This is the cross-sink
+        // alignment guarantee. Fires for integers too — e.g.,
+        // resolution=5 with value=1234 quantizes to 1235.
+        const quantizer = columnQuantizers[ key ];
+        if ( quantizer ) return quantizer( v );
+
+        // No per-column quantizer beyond this point — the original
+        // behaviour for non-resolution columns is preserved exactly.
+        if ( Number.isInteger( v ) ) return v;
+        if ( v !== 0 && Math.abs( v ) < 0.001 ) return v.toExponential( precision );
+        return Number( v.toFixed( precision ) );
+    };
+};
+
+export { buildColumnQuantizers, createValueFormatter };

package/src/core/emitter-manager/terminal/index.js

@@ -0,0 +1,341 @@
+// core/emitter-manager/terminal/index.js
+
+/**
+ * @fileoverview Terminal Emitter for debugging and testing.
+ *
+ * Outputs emitted messages to stdout with smart formatting:
+ * - Shows all fields (no filtering — emitIf already gates what's emitted)
+ * - Formats numbers with configurable precision (default: 2 decimal places)
+ * - Compact key=value format, verbose mode for full JSON
+ *
+ * Adapter contract (ADR-018, stream sink):
+ * - Module-level exports per the ADR's module surface: `id`,
+ *   `configSchema`, `createEmitter`, `durabilityClass`,
+ *   `semanticsRequirement`, and the default aggregate
+ *   referencing the same constants.
+ * - Durability class: `'best-effort'` — nothing is buffered beyond the
+ *   stdout write; there is no queue for a crash to lose, and no recovery
+ *   commitment either.
+ * - `publishNow(topic, msg)` returns `{ ok: true }` synchronously. Terminal cannot
+ *   fail (stdout is always available); the contract still requires the return shape.
+ * - `getPressure()` returns `0` — Terminal has no observable buffer (stdout drains
+ *   to the kernel); a trivial sink meets the pressure obligation with a
+ *   constant 0 (ADR-018).
+ * - `getHealth()` returns `{ status: 'green', connected: true, pressure: 0 }` —
+ *   Terminal is always healthy and always "connected" to stdout (there is no
+ *   connection to lose). Uniform semantics with MQTT emitter / QuestDB.
+ * - `err.code` vocabulary:
+ *     - Setup-time (per the ADR-018 error vocabulary):
+ *       `INVALID_CONFIG` — a float64 column in the supplied asset class
+ *       declares a malformed `resolution` (zero, negative, NaN, Infinity,
+ *       non-number). Thrown by `assertColumnFacts` at `createEmitter`
+ *       time; see the column-internal facts section below.
+ *     - Runtime: none today. Terminal has no failure modes that surface
+ *       through `publishNow`. Future runtime codes (e.g., `STDOUT_CLOSED`)
+ *       will be documented here when introduced.
+ *
+ * Column-internal facts consumed (per ADR-018's adapter–semantics
+ * alignment):
+ *
+ * Terminal's top-level dependency on the asset class is declared in the
+ * `semanticsRequirement` export above: just `columns`. Inside `columns`,
+ * terminal additionally reads ONE field per column:
+ *
+ * - `columns.*.resolution` — read by `formatters.js` (passed to the
+ *   shared `buildResolutionQuantizer` helper in `core/utils/quantize`).
+ *   Asserted at startup by `assert-columns.js`: when present on a
+ *   `float64` column, must be a positive finite number; absent is fine
+ *   (column falls back to the global `precision` config). Throws
+ *   `INVALID_CONFIG` otherwise.
+ *
+ * Terminal does NOT require columns to declare a `type` field — it
+ * handles every JS value at runtime via the formatter's branch chain.
+ * `type === 'float64'` is checked only as a precondition for honouring
+ * `resolution`; non-float64 columns ignore `resolution` as dead weight.
+ *
+ * Cross-sink alignment with QuestDB: both adapters consume `resolution`
+ * via the same shared quantizer (`core/utils/quantize`). For the same
+ * input value and the same declared resolution, terminal's formatted
+ * number and QDB's stored number are guaranteed identical. Verified
+ * by the cross-sink consistency tests in `terminal-emitter.specs.js`.
+ *
+ * @example
+ * import { flow, csv, terminal } from '@winkjs/composer';
+ *
+ * flow('debug')
+ *     .sanitize(...)
+ *     .emitIf('log', () => true, { target: 'terminal' })
+ *     .source(csv, { path: './data.csv' })
+ *     .emitter(terminal)
+ *     .run();
+ */
+
+import { validators } from '../../utils/validate/index.js';
+import { assertColumnFacts } from './assert-columns.js';
+import { buildColumnQuantizers, createValueFormatter } from './formatters.js';
+
+/**
+ * Emitter identifier - must match target in emitIf specs.
+ * @type {string}
+ */
+export const id = 'terminal';
+
+/**
+ * Crash-survival class per ADR-018. Terminal buffers nothing beyond
+ * the stdout write — no queue to lose, no recovery promised.
+ * @type {string}
+ */
+export const durabilityClass = 'best-effort';
+
+/**
+ * Capability declaration per ADR-018's adapter–semantics alignment.
+ *
+ * Terminal opts in *optionally* to receiving the asset class. When a flow
+ * supplies one via `.assetClass()`, the wiring layer slices it down to
+ * the requested fields and injects the result as `config.assetClass`.
+ * With `fields: [ 'columns' ]`, terminal receives `config.assetClass`
+ * containing just the `columns` map — the column metadata is always
+ * nested under the asset class container per the semantics module's
+ * structure (a column map cannot exist standalone; it lives inside an
+ * asset class).
+ *
+ * Terminal uses each column's declared `resolution` to format float
+ * values to the intended number of decimal places — so a value declared
+ * with `resolution: 0.001` prints as `23.456` instead of `23.46` (which
+ * is what the global `precision: 2` default would produce). Without an
+ * asset class, terminal falls back to the global `precision` config —
+ * exactly the original global-precision behaviour.
+ *
+ * `required: false` because terminal is the simplest sink and is useful
+ * for debugging flows that have no semantics (e.g., a quick csv →
+ * terminal sanity check). The capability is purely additive when
+ * supplied.
+ *
+ * `fields: [ 'columns' ]` because terminal only reads the columns map;
+ * the other top-level asset class fields (name, description,
+ * insightTypes) carry no formatting-relevant facts.
+ */
+export const semanticsRequirement = {
+    assetClass: {
+        required: false,
+        fields: [ 'columns' ]
+    }
+};
+
+/**
+ * Singleton success result reused on every publish. Hot-path zero allocation
+ * per ADR-013 / ADR-004 — `{ ok: true }` would otherwise allocate per call.
+ * Not frozen: V8 hot paths handle plain objects more predictably, and no
+ * caller mutates this.
+ * @type {{ok: true}}
+ */
+const RESULT_OK = { ok: true };
+
+/**
+ * Singleton health snapshot reused on every getHealth() call. Terminal's
+ * health is constant (no transport state to track), so a single object
+ * suffices. Same rationale as RESULT_OK above. `pressure: 0` completes
+ * the ADR-018 health floor: stdout has no observable buffer, matching
+ * what getPressure() reports.
+ * @type {{status: 'green', connected: true, pressure: 0}}
+ */
+const HEALTH_GREEN = { status: 'green', connected: true, pressure: 0 };
+
+/**
+ * Configuration schema for terminal emitter validation.
+ * Used by flow.emitter() to validate config at DSL time.
+ *
+ * `_propertyNames` lists every accepted key — unknown keys throw at
+ * DSL time (the validator's only unknown-key mechanism).
+ * `assetClass` is deliberately absent: wire-emitters injects it from
+ * the flow's `.assetClass()` after DSL validation, so a user-supplied
+ * value would be silently overwritten — rejecting it loudly is the
+ * point.
+ *
+ * @type {Object}
+ */
+export const configSchema = {
+    _propertyNames: [ 'verbose', 'prefix', 'precision' ],
+    verbose: {
+        type: 'boolean',
+        required: false,
+        error: 'verbose must be a boolean'
+    },
+    prefix: {
+        type: 'string',
+        required: false,
+        error: 'prefix must be a string'
+    },
+    precision: {
+        type: 'number',
+        required: false,
+        validator: validators.nonNegative,
+        error: 'precision must be a non-negative number'
+    }
+};
+
+
+/**
+ * Formats a message for compact display.
+ *
+ * Passes the field name to `formatValue` so the formatter can look up
+ * per-column decimal places when the column has a declared
+ * `resolution`. Backward compatible — formatters that ignore the key
+ * (none today) would still work.
+ *
+ * @param {Object} msg - Message to format
+ * @param {function(string, *): *} formatValue - Value formatter
+ * @returns {string} Formatted message string
+ */
+const formatCompact = function ( msg, formatValue ) {
+    const parts = [];
+
+    for ( const [ key, value ] of Object.entries( msg ) ) {
+        parts.push( `${key}=${formatValue( key, value )}` );
+    }
+
+    return parts.join( '  ' );
+};
+
+/**
+ * Formats a message as pretty JSON with number formatting.
+ *
+ * @param {Object} msg - Message to format
+ * @param {function(string, *): *} formatValue - Value formatter
+ * @returns {string} Pretty JSON string
+ */
+const formatVerbose = function ( msg, formatValue ) {
+    const formatted = Object.create( null );
+
+    for ( const [ key, value ] of Object.entries( msg ) ) {
+        // Always pass through the formatter so per-column quantizers
+        // get a chance to round integer-shaped values too — e.g., when
+        // a column declares `resolution: 5`, an integer input of 1234
+        // must quantize to 1235 (the nearest multiple of 5), matching
+        // QDB's storage. The formatter handles every JS type internally
+        // and returns non-numbers as-is, so this is safe to call
+        // unconditionally.
+        formatted[ key ] = formatValue( key, value );
+    }
+
+    return JSON.stringify( formatted, null, 2 );
+};
+
+/**
+ * Creates a terminal emitter instance.
+ *
+ * @param {Object} [config={}] - Emitter configuration
+ * @param {boolean} [config.verbose=false] - Use pretty JSON format
+ * @param {string} [config.prefix=''] - Optional prefix for output lines
+ * @param {number} [config.precision=2] - Default decimal places for floats
+ *   that have no per-column resolution declared
+ * @param {Object} [config.assetClass] - Asset class slice injected by
+ *   wire-emitters when the flow supplies one via `.assetClass()`. Per
+ *   terminal's `semanticsRequirement`, this contains just the `columns`
+ *   field. Each `float64` column with a declared `resolution` formats
+ *   to its own decimal places; columns without resolution fall back to
+ *   the global `precision` config. Without an asset class entirely,
+ *   every column falls back — the original global-precision behaviour,
+ *   unchanged.
+ * @returns {Object} Emitter instance with publishNow, getPressure, getHealth, shutdown
+ */
+export const createEmitter = function ( config = {} ) {
+    const {
+        verbose = false,
+        prefix = '',
+        precision = 2,
+        assetClass = null
+    } = config;
+
+    // Defensive validation per ADR-018's adapter–semantics alignment:
+    // any resolution declared on a float64 column must be a positive
+    // finite number. Throws INVALID_CONFIG with a diagnostic message
+    // before the emitter is built, so a misconfigured flow fails at
+    // startup rather than producing garbage formatting later.
+    const columns = assetClass && assetClass.columns;
+    assertColumnFacts( columns );
+
+    // Pre-compute the per-column quantizer map at startup. Each entry
+    // is a closure built by the shared `buildResolutionQuantizer` helper
+    // (in core/utils/quantize) — same closure shape QDB's writers use,
+    // so terminal and QDB compute identical rounded values for the same
+    // input. An empty prototype-less map is returned when no asset
+    // class was supplied; the formatter then falls back to the global
+    // `precision` for every column. Hot path is one O(1) lookup per
+    // value, no allocation.
+    const columnQuantizers = buildColumnQuantizers( columns );
+
+    const linePrefix = prefix ? `${prefix} ` : '';
+    const formatValue = createValueFormatter( precision, columnQuantizers );
+
+    return {
+
+        /**
+         * Publishes a message to terminal.
+         *
+         * @param {string} topic - Message topic
+         * @param {Object} msg - Message payload
+         * @returns {{ok: true}} Contract return per ADR-018.
+         */
+        publishNow: function ( topic, msg ) {
+            const ts = new Date().toLocaleTimeString();
+            const header = `${linePrefix}── ${ts} ── ${topic} ──`;
+
+            console.log( header );
+
+            if ( verbose ) {
+                console.log( formatVerbose( msg, formatValue ) );
+            } else {
+                console.log( formatCompact( msg, formatValue ) );
+            }
+
+            console.log();  // Blank line for readability
+
+            return RESULT_OK;
+        },
+
+        /**
+         * Backpressure metric for the partition manager. Terminal has no
+         * observable buffer (stdout drains to the kernel), so always 0.
+         * Sync, O(1), allocation-free per ADR-018.
+         *
+         * @returns {number} 0
+         */
+        getPressure: function () {
+            return 0;
+        },
+
+        /**
+         * Health snapshot for operator monitoring. Terminal is always healthy
+         * and always "connected" to stdout — there is no transport state to
+         * lose. Returns the singleton HEALTH_GREEN.
+         *
+         * Uniform semantics with MQTT emitter / QuestDB:
+         * - `status: 'green'` — operational
+         * - `connected: true` — transport active (Terminal exception: always true)
+         * - `pressure: 0` — no observable buffer (the ADR-018 health floor)
+         *
+         * @returns {{status: 'green', connected: true, pressure: 0}}
+         */
+        getHealth: function () {
+            return HEALTH_GREEN;
+        },
+
+        /**
+         * No-op shutdown for terminal emitter.
+         *
+         * Accepts the ADR-018 shutdown-contract shape `{ timeout }`. Terminal has
+         * no body to time out (stdout drains to the kernel without our help),
+         * so the value is intentionally unused — the leading `_` on the
+         * destructured name signals that to readers and to ESLint.
+         *
+         * @param {{timeout?: number}} [_options]
+         * @returns {Promise<void>}
+         */
+        shutdown: async function ( { timeout: _timeout = 0 } = {} ) {
+            // Nothing to clean up.
+        }
+    };
+};
+
+export default { id, configSchema, durabilityClass, semanticsRequirement, createEmitter };