@clementine-solutions/jane-io 1.0.1 → 1.0.2

package/dist/core/pipeline/contain.js

@@ -0,0 +1,339 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Contain
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Enforces structural limits and produces a safe, cycle‑free
+ *                  representation of input.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { appendSegment, rootPath, setIndex, setKey } from '../field-path';
+import { defaultPolicy } from '../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Containment Sentinel                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Sentinel markers used when a value cannot be safely contained.
+ *
+ * These appear when encountering cycles, excessive depth or size, unsafe
+ * structures, or disallowed types such as functions, symbols, and proxies.
+ */
+export const ContainmentSentinel = {
+    Circular: '[Circular]',
+    TooDeep: '[TooDeep]',
+    TooLarge: '[TooLarge]',
+    Proxy: '[Proxy]',
+    Getter: '[Getter]',
+    Function: '[Function]',
+    Symbol: '[Symbol]',
+    BigInt: '[BigInt]',
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Contain Array                                                             *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Contains an array by applying depth and length limits.
+ *
+ * Recursively contains each element, records the container for cycle
+ * detection, and appends a TooLarge sentinel when the array exceeds
+ * the configured maximum length.
+ */
+export function containArray(value, path, context, depth) {
+    const limit = context.options.maxArrayLength;
+    const length = value.length;
+    const out = [];
+    context.seen.set(value, out);
+    const max = Math.min(length, limit);
+    for (let index = 0; index < max; index++) {
+        const child = value[index];
+        const childPath = appendSegment(path, setIndex(index));
+        out.push(containRecursive(child, childPath, context, depth));
+    }
+    if (length > limit) {
+        out.push(ContainmentSentinel.TooLarge);
+    }
+    return out;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Contain Bigint                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Represents a bigint value in a safe, JSON‑compatible form.
+ *
+ * Used only when bigint is explicitly allowed by policy; otherwise
+ * containment falls back to the BigInt sentinel.
+ */
+export function containBigInt(value) {
+    return {
+        kind: 'bigint',
+        asString: value.toString(),
+    };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Contain Object                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Contains a plain object by enforcing key limits and safe property access.
+ *
+ * Skips prototype‑pollution vectors, replaces getters/setters with a
+ * Getter sentinel, and recursively contains each value. Adds a TooLarge
+ * sentinel entry when the object exceeds the configured key limit.
+ */
+export function containObject(value, path, ctx, depth) {
+    const out = Object.create(null);
+    // 1. Get keys safely
+    const rawKeys = safeObjectKeys(value);
+    // 2. Filter dangerous keys BEFORE doing anything else
+    const keys = rawKeys.filter((k) => k !== '__proto__' && k !== 'constructor' && k !== 'prototype');
+    const limit = ctx.options.maxObjectKeys;
+    const max = Math.min(keys.length, limit);
+    for (let i = 0; i < max; i++) {
+        const key = keys[i];
+        const desc = safePropertyDescriptor(value, key);
+        const childPath = appendSegment(path, setKey(key));
+        // 3. Getter/setter detection ALWAYS runs now
+        if (!desc || typeof desc.get === 'function' || typeof desc.set === 'function') {
+            out[key] = ContainmentSentinel.Getter;
+            continue;
+        }
+        out[key] = containRecursive(desc.value, childPath, ctx, depth);
+    }
+    if (keys.length > limit) {
+        out['[TooLarge]'] = ContainmentSentinel.TooLarge;
+    }
+    return out;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Contain Recursive                                                         *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Recursively contains any value into a safe, JSON‑like structure.
+ *
+ * Enforces depth limits, detects cycles, handles primitives directly,
+ * applies policy‑controlled exceptions (e.g., bigint), and replaces
+ * unsafe or non‑plain objects with appropriate sentinels.
+ */
+export function containRecursive(value, path, context, depth) {
+    if (depth > context.options.maxDepth) {
+        return ContainmentSentinel.TooDeep;
+    }
+    if (value === null)
+        return null;
+    const type = typeof value;
+    if (type === 'number' || type === 'string' || type === 'boolean') {
+        return value;
+    }
+    if (type === 'undefined') {
+        return null;
+    }
+    if (type === 'bigint') {
+        if (context.policy.exception?.bigint) {
+            return containBigInt(value);
+        }
+        return ContainmentSentinel.BigInt;
+    }
+    if (type === 'symbol')
+        return ContainmentSentinel.Symbol;
+    if (type === 'function')
+        return ContainmentSentinel.Function;
+    if (typeof value === 'object') {
+        const object = value;
+        const existing = context.seen.get(object);
+        if (existing !== undefined) {
+            return ContainmentSentinel.Circular;
+        }
+        if (Array.isArray(object)) {
+            const container = [];
+            context.seen.set(object, container);
+            return containArray(object, path, context, depth + 1);
+        }
+        if (object instanceof Date) {
+            return new Date(object.getTime()).toISOString();
+        }
+        const proto = Object.getPrototypeOf(object);
+        const isPlain = proto === Object.prototype || proto === null;
+        if (!isPlain) {
+            return ContainmentSentinel.Proxy;
+        }
+        const container = Object.create(null);
+        context.seen.set(object, container);
+        return containObject(object, path, context, depth + 1);
+    }
+    return ContainmentSentinel.Proxy;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Contain Value                                                             *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Entry point for containment.
+ *
+ * Creates a fresh containment context and produces a safe representation
+ * of the input value. Falls back to the Proxy sentinel if containment
+ * fails unexpectedly.
+ */
+export function containValue(value, path = rootPath(), options = defaultContainmentOptions, policy = defaultPolicy) {
+    const context = createContainmentContext(options, policy);
+    try {
+        return containRecursive(value, path, context, 0);
+    }
+    catch {
+        return ContainmentSentinel.Proxy;
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Create Containment Context                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Constructs a containment context with structural limits, policy,
+ * and a fresh cycle‑detection map.
+ */
+export function createContainmentContext(options, policy) {
+    return {
+        options,
+        policy,
+        seen: new WeakMap(),
+    };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Deep Clone                                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Produces a deep, acyclic clone of an internal JSON value.
+ *
+ * Preserves primitives, arrays, plain objects, and Date instances while
+ * tracking references to avoid infinite recursion. Used to safely copy
+ * containment output without re‑running containment.
+ */
+export function deepClone(input, seen = new WeakMap()) {
+    if (input === null || typeof input !== 'object') {
+        return input;
+    }
+    if (seen.has(input)) {
+        return seen.get(input);
+    }
+    if (input instanceof Date) {
+        return new Date(input.getTime());
+    }
+    if (Array.isArray(input)) {
+        const clone = new Array(input.length);
+        seen.set(input, clone);
+        for (let i = 0; i < input.length; i++) {
+            if (i in input) {
+                clone[i] = deepClone(input[i], seen);
+            }
+        }
+        return clone;
+    }
+    const clone = {};
+    seen.set(input, clone);
+    for (const key of Object.keys(input)) {
+        const value = input[key];
+        clone[key] = deepClone(value, seen); // ← FIXED
+    }
+    return clone;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Default Containment Options                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Default structural limits applied during containment.
+ *
+ * These bounds prevent excessive recursion and traversal by capping depth,
+ * array length, and object key count.
+ */
+export const defaultContainmentOptions = {
+    maxDepth: 10,
+    maxArrayLength: 1,
+    maxObjectKeys: 5,
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Is Sentinel                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Determines whether a value is a containment sentinel.
+ *
+ * Sentinels represent structural hazards or disallowed types encountered
+ * during containment and are encoded as well‑known string markers.
+ */
+export function isSentinel(value) {
+    if (typeof value !== 'string')
+        return false;
+    switch (value) {
+        case '[Circular]':
+        case '[TooDeep]':
+        case '[TooLarge]':
+        case '[Proxy]':
+        case '[Getter]':
+        case '[Function]':
+        case '[Symbol]':
+        case '[BigInt]':
+            return true;
+        default:
+            return false;
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Safe Object Keys                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Safely retrieves an object's own enumerable keys.
+ *
+ * Returns an empty array if key enumeration fails, protecting containment
+ * from objects with hostile or unusual prototypes.
+ */
+export function safeObjectKeys(value) {
+    try {
+        return Object.keys(value);
+    }
+    catch {
+        return [];
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Safe Property Descriptor                                                  *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Safely retrieves a property descriptor.
+ *
+ * Returns undefined if descriptor access throws, allowing containment to
+ * gracefully handle objects with unsafe or non‑standard behavior.
+ */
+export function safePropertyDescriptor(value, key) {
+    try {
+        return Object.getOwnPropertyDescriptor(value, key);
+    }
+    catch {
+        return undefined;
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Sentinel Event                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Maps a containment sentinel to its corresponding event.
+ *
+ * Used to surface structural hazards—such as cycles, excessive depth,
+ * unsafe objects, or disallowed types—as typed events during scanning
+ * and policy evaluation.
+ */
+export function sentinelEvent(kind) {
+    switch (kind) {
+        case ContainmentSentinel.Circular:
+            return { code: 'contain.circular', severity: 'fatal' };
+        case ContainmentSentinel.TooDeep:
+            return { code: 'contain.too.deep', severity: 'warn' };
+        case ContainmentSentinel.TooLarge:
+            return { code: 'contain.too.large', severity: 'warn' };
+        case ContainmentSentinel.Proxy:
+            return { code: 'contain.proxy', severity: 'info' };
+        case ContainmentSentinel.Getter:
+            return { code: 'contain.getter', severity: 'info' };
+        case ContainmentSentinel.Function:
+            return { code: 'contain.function', severity: 'info' };
+        case ContainmentSentinel.Symbol:
+            return { code: 'contain.symbol', severity: 'info' };
+        case ContainmentSentinel.BigInt:
+            return { code: 'contain.bigint', severity: 'info' };
+    }
+}

package/dist/core/pipeline/index.js

@@ -0,0 +1,37 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Boundary                                                                  *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { boundaryRunner, decideBoundary } from './boundary';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Contain                                                                   *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { ContainmentSentinel, containArray, containBigInt, containObject, containRecursive, containValue, createContainmentContext, deepClone, defaultContainmentOptions, isSentinel, safeObjectKeys, safePropertyDescriptor, sentinelEvent, } from './contain';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Normalize                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { normalizationEvent, normalizationRunner, selectNormalizationRules } from './normalize';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Parse                                                                     *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { isFluentParser, isParseFactory, parseEvent, parseRunner } from './parse';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Pipeline                                                                  *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { createPipeline, pipelineRunner } from './pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Scan                                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { detectStructuralType, measureDepth, scanEvent, scanRunner, selectScanRules } from './scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Validate                                                                  *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { isFluentValidator, isValidationFactory, validationEvent, validationRunner, } from './validate';

package/dist/core/pipeline/normalize.js

@@ -0,0 +1,76 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Normalize
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Applies mode‑aware transformations to the safe value
+ *                  before validation.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { createEvent } from '../common';
+import { rootPath } from '../field-path';
+import { normalizationRuleRegistry } from '../normalizers';
+import { detectStructuralType } from './scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Normalization Event                                                       *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates a normalization‑stage event.
+ *
+ * Wraps createEvent with the 'normalize' stage tag, producing structured
+ * messages emitted during value‑shaping operations.
+ */
+export const normalizationEvent = (kind, code, path, message, userMessage, meta) => createEvent('normalize', kind, code, path, message, userMessage, meta);
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Normalization Runner                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Executes the normalization stage.
+ *
+ * Applies each normalization rule in sequence, collects emitted events,
+ * and updates the working value according to the active mode. Lossy
+ * transformations are skipped in moderate mode, with a corresponding
+ * warning event recorded.
+ */
+export const normalizationRunner = async (input) => {
+    const { safe, path: inputPath, rules, mode } = input;
+    const path = inputPath ?? rootPath();
+    let current = safe;
+    const events = [];
+    for (const rule of rules) {
+        let results;
+        try {
+            results = await rule(current, mode, path);
+        }
+        catch (err) {
+            events.push(createEvent('normalize', 'fatal', 'error.while.normalizing', path, String(err)));
+            continue;
+        }
+        for (const result of results) {
+            if (result.events) {
+                events.push(...result.events);
+            }
+            if (mode === 'moderate' && result.lossy === 'lossy') {
+                const warn = createEvent('normalize', 'warn', 'policy.is.moderate', path, 'A lossy normalization step was skipped in moderate mode.', undefined, { attempted: result.nextValue, mode });
+                events.push(warn);
+                continue;
+            }
+            current = result.nextValue;
+        }
+    }
+    return { events, normalized: current };
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Select Normalization Rules                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Selects normalization rules based on the structural type of the value.
+ *
+ * Uses detectStructuralType to choose the appropriate rule set from the
+ * registry, ensuring predictable and type‑specific normalization behavior.
+ */
+export function selectNormalizationRules(value) {
+    const type = detectStructuralType(value);
+    return normalizationRuleRegistry[type] ?? [];
+}

package/dist/core/pipeline/parse.js

@@ -0,0 +1,91 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Parse
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Converts raw input into typed values using registered parse
+ *                  rules.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { rootPath } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Parse Event                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates a parse‑stage event.
+ *
+ * Produces a structured event tagged with the 'parse' phase, used to
+ * surface observations or errors encountered while interpreting input.
+ */
+export function parseEvent(kind, code, message, path, userMessage, metadata) {
+    return {
+        phase: 'parse',
+        kind,
+        code,
+        message,
+        userMessage,
+        path,
+        metadata,
+    };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Is Parse Factory                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Determines whether a fluent parser entry is a factory.
+ *
+ * Factories accept arbitrary parameters and return a ParseRule, while
+ * fluent parsers expose a fixed two‑argument rule signature.
+ */
+export function isParseFactory(fn) {
+    return fn.length !== 2;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Is Fluent Parser                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Determines whether a fluent parser entry is a direct parse rule.
+ *
+ * Fluent rules always accept exactly two parameters—value and path—
+ * distinguishing them from parameterized factories.
+ */
+export function isFluentParser(fn) {
+    return typeof fn === 'function' && fn.length === 2;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Parse Runner                                                              *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Executes the parse stage.
+ *
+ * Applies each parse rule in sequence, collects emitted events, and
+ * updates the working value as rules propose transformations. Errors
+ * thrown by rules are captured as fatal parse events.
+ */
+export async function parseRunner(ctx) {
+    const { value, path = rootPath(), rules } = ctx;
+    let current = value;
+    const events = [];
+    for (const rule of rules) {
+        try {
+            const results = await rule(current, path);
+            if (!results || results.length === 0) {
+                continue;
+            }
+            for (const r of results) {
+                if (r.events) {
+                    events.push(...r.events);
+                }
+                current = r.nextValue;
+            }
+        }
+        catch (err) {
+            events.push(parseEvent('fatal', 'error.while.parsing', String(err), path));
+        }
+    }
+    return {
+        parsed: current,
+        events,
+    };
+}