@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/README.md

@@ -1 +1,132 @@
-# Meet Jane
+# Jane IO
+
+[![pipeline status](https://gitlab.com/clementine-solution/open-source/jane-io/badges/main/pipeline.svg)](https://gitlab.com/clementine-solution/open-source/jane-io/-/commits/main)
+[![coverage report](https://gitlab.com/clementine-solution/open-source/jane-io/badges/main/coverage.svg)](https://gitlab.com/clementine-solution/open-source/jane-io/-/commits/main)
+[![npm version](https://img.shields.io/npm/v/@clementine-solutions/jane-io.svg)](https://www.npmjs.com/package/@clementine-solutions/jane-io)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+> A clarity-first boundary system for shaping, validating, and transforming data with full introspection and policy control.
+
+Jane IO is a TypeScript-first data validation library that emphasizes **explicit design**, **runtime safety**, and **comprehensive observability**. Unlike traditional validators, Jane treats data processing as a multi-stage pipeline with policy-driven decision making.
+
+## Key Features
+
+- **Security-First**: Built-in protection against prototype pollution, circular references, and unsafe Unicode
+- **Type-Safe**: Full TypeScript coverage with immutable, composable APIs
+- **Observable**: Rich telemetry, diff tracking, and audit trails
+- **Configurable**: Policy-driven behavior with multiple validation modes
+- **Performant**: Lazy evaluation and efficient data structures
+- **Extensible**: Plugin architecture for custom validators and parsers
+
+## Installation
+
+```bash
+npm install @clementine-solutions/jane-io
+```
+
+```bash
+yarn add @clementine-solutions/jane-io
+```
+
+```bash
+pnpm add @clementine-solutions/jane-io
+```
+
+## Quick Start
+
+```typescript
+import { jane } from '@clementine-solutions/jane-io';
+
+// Simple validation
+const result = await jane.value("hello@example.com")
+  .parse("string")
+  .matches(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
+  .run();
+
+if (result.ok) {
+  console.log("Valid email:", result.value);
+} else {
+  console.log("Issues:", result.issues);
+}
+```
+
+## Documentation
+
+- [Getting Started Guide](https://jane-io.com/docs/getting-started/introduction)
+- [Conceptual Overview](https://jane-io.clementine.solutions/concepts/introduction/)
+
+## Use Cases
+
+Jane excels at:
+
+- **API Data Validation**: Secure processing of external inputs.
+- **Configuration Management**: Structured config validation with audit trails.
+- **Data Transformation Pipelines**: ETL workflows with error tracking.
+- **Form Validation**: Complex multi-field validation scenarios.
+- **Data Import/Export**: Safe handling of structured data.
+
+## Architecture
+
+Jane's pipeline processes data through distinct stages:
+
+```mermaid
+graph LR
+    A[Raw Input] --> B[Contain]
+    B --> C[Scan]
+    C --> D[Normalize]
+    D --> E[Parse]
+    E --> F[Validate]
+    F --> G[Policy]
+    G --> H[Result]
+```
+
+- **Contain**: Structural safety and sanitization.
+- **Scan**: Analysis and hazard detection.
+- **Normalize**: Data hygiene and standardization.
+- **Parse**: Semantic interpretation.
+- **Validate**: Business rule enforcement.
+- **Policy**: Decision-making and observability.
+
+## Security Features
+
+- **Structural Hazard Detection**: Identifies circular references, excessive depth, and unsafe structures.
+- **Unicode Safety**: Detects and handles bidirectional control characters.
+- **Prototype Pollution Prevention**: Safe property access and key filtering.
+- **Containment Sentinels**: Safe representation of dangerous values.
+- **Immutable Processing**: No side effects or data mutation.
+
+## Observability
+
+Jane provides comprehensive introspection:
+
+```typescript
+const result = await jane.value(data)
+  .withDiff()      // Track changes
+  .withExplain()   // Explain decisions
+  .withReplay()    // Reconstruct transformations
+  .withTelemetry(sink) // Custom telemetry
+  .run();
+
+// Access detailed metadata
+console.log(result.metadata);
+console.log(result.diff);
+console.log(result.explain);
+```
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+Jane IO is built with care for the developer experience and runtime safety. Special thanks to the TypeScript community and the broader JavaScript ecosystem for inspiration and tooling.
+
+## Support
+
+- **Issues**: [GitLab Issues](https://gitlab.com/clementine-solution/open-source/jane-io/issues)
+- **Discussions**: [GitLab Discussions](https://gitlab.com/clementine-solution/open-source/jane-io/discussions)
+- **Documentation**: [Jane IO Docs](https://jane-io.com/)
+
+---
+
+**Jane IO** - Data validation with clarity and confidence.

package/dist/core/analysis/diff.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Diff
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Structural diff utilities used to compare safe and
+ *                  normalized values.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { DiffEntry, DiffFunction, FieldPath, JsonValue, PipelineBuilder } from '../shapes';
+/**
+ * Computes a structural diff between two JSON‑compatible values.
+ *
+ * Delegates all traversal to `walkDiff`, collecting every change into a flat
+ * list of diff entries rooted at the top‑level path. Always returns a stable
+ * `{ entries }` object with no filtering or interpretation.
+ */
+export declare const diff: DiffFunction;
+/**
+ * Recursively walks two JSON‑compatible values and records structural changes.
+ *
+ * Compares primitives, arrays, and plain objects by shape and content, emitting
+ * diff entries at each divergent path. Keys and indices are traversed in a
+ * stable order, and non‑object mismatches are treated as direct value changes.
+ * All entries are appended to `out`; no filtering or interpretation occurs here.
+ */
+export declare function walkDiff(before: JsonValue | undefined, after: JsonValue | undefined, path: FieldPath, out: DiffEntry[]): void;
+/**
+ * Runs the pipeline and returns its computed diff.
+ *
+ * Delegates execution to the provided builder and exposes only the diff
+ * portion of the result. No additional processing or filtering occurs here.
+ */
+export declare function runDiff<T>(builder: PipelineBuilder): Promise<import("../shapes").DiffResult | undefined>;

package/dist/core/analysis/diff.js

@@ -0,0 +1,88 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Diff
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Structural diff utilities used to compare safe and
+ *                  normalized values.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { isObject, isPlainObject } from '../common';
+import { appendSegment, rootPath, setIndex, setKey } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Diff                                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Computes a structural diff between two JSON‑compatible values.
+ *
+ * Delegates all traversal to `walkDiff`, collecting every change into a flat
+ * list of diff entries rooted at the top‑level path. Always returns a stable
+ * `{ entries }` object with no filtering or interpretation.
+ */
+export const diff = (before, after) => {
+    const entries = [];
+    walkDiff(before, after, rootPath(), entries);
+    return { entries };
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Walk Diff                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Recursively walks two JSON‑compatible values and records structural changes.
+ *
+ * Compares primitives, arrays, and plain objects by shape and content, emitting
+ * diff entries at each divergent path. Keys and indices are traversed in a
+ * stable order, and non‑object mismatches are treated as direct value changes.
+ * All entries are appended to `out`; no filtering or interpretation occurs here.
+ */
+export function walkDiff(before, after, path, out) {
+    if (before === after)
+        return;
+    if (!isObject(before) || !isObject(after)) {
+        out.push({
+            path,
+            kind: before === undefined ? 'added' : after === undefined ? 'removed' : 'changed',
+            before,
+            after,
+        });
+        return;
+    }
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const max = Math.max(before.length, after.length);
+        for (let i = 0; i < max; i++) {
+            const childPath = appendSegment(path, setIndex(i));
+            walkDiff(before[i], after[i], childPath, out);
+        }
+        return;
+    }
+    if (isPlainObject(before) && isPlainObject(after)) {
+        const beforeKeys = Object.keys(before);
+        const afterKeys = Object.keys(after);
+        const allKeys = new Set([...beforeKeys, ...afterKeys]);
+        for (const key of allKeys) {
+            const childPath = appendSegment(path, setKey(key));
+            walkDiff(before[key], after[key], childPath, out);
+        }
+        return;
+    }
+    out.push({
+        path,
+        kind: 'changed',
+        before,
+        after,
+    });
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Run Diff                                                                  *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Runs the pipeline and returns its computed diff.
+ *
+ * Delegates execution to the provided builder and exposes only the diff
+ * portion of the result. No additional processing or filtering occurs here.
+ */
+export async function runDiff(builder) {
+    const result = await builder.run();
+    return result.diff;
+}

package/dist/core/analysis/explain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Explain
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Builds a human‑readable narrative of all pipeline events in
+ *                  order.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ExplainFunction, PipelineBuilder } from '../shapes';
+/**
+ * Builds a linear explanation of all pipeline events.
+ *
+ * Emits scan hazards, normalization events, diff entries, parse changes, and
+ * validation errors in pipeline order. Each event is mapped to a stable
+ * ExplainStep with its path, stage, kind, code, and message. No filtering or
+ * interpretation occurs; this is a direct narrative of what the pipeline saw.
+ */
+export declare const explain: ExplainFunction;
+/**
+ * Formats a value for human‑readable explain output.
+ *
+ * Produces stable string representations for primitives and falls back to
+ * compact JSON for objects. Never throws; errors during formatting degrade
+ * gracefully to `String(value)`.
+ */
+export declare function format(value: unknown): string;
+/**
+ * Runs the pipeline and returns its explain output.
+ *
+ * Delegates execution to the provided builder and exposes only the explain
+ * portion of the result. No additional processing or reshaping occurs here.
+ */
+export declare function runExplain<T>(builder: PipelineBuilder): Promise<import("../shapes").ExplainResult | undefined>;

package/dist/core/analysis/explain.js

@@ -0,0 +1,117 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Explain
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Builds a human‑readable narrative of all pipeline events in
+ *                  order.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Explain                                                                   *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Builds a linear explanation of all pipeline events.
+ *
+ * Emits scan hazards, normalization events, diff entries, parse changes, and
+ * validation errors in pipeline order. Each event is mapped to a stable
+ * ExplainStep with its path, stage, kind, code, and message. No filtering or
+ * interpretation occurs; this is a direct narrative of what the pipeline saw.
+ */
+export const explain = ({ scanEvents, normalizationEvents, parseEvents, validationEvents, diff, }) => {
+    const steps = [];
+    for (const ev of scanEvents) {
+        steps.push({
+            path: ev.path,
+            stage: 'scan',
+            kind: 'hazard',
+            code: ev.code,
+            message: ev.message,
+        });
+    }
+    for (const ev of normalizationEvents) {
+        steps.push({
+            path: ev.path,
+            stage: 'normalize',
+            kind: ev.kind === 'fatal' ? 'hazard' : 'change',
+            code: ev.code,
+            message: ev.message,
+        });
+    }
+    if (diff) {
+        for (const entry of diff.entries) {
+            const message = entry.kind === 'added'
+                ? `Added value: ${format(entry.after)}`
+                : entry.kind === 'removed'
+                    ? `Removed value: ${format(entry.before)}`
+                    : `Changed from ${format(entry.before)} to ${format(entry.after)}`;
+            steps.push({
+                path: entry.path,
+                stage: 'normalize',
+                kind: 'change',
+                code: `normalize.${entry.kind}`,
+                message,
+            });
+        }
+    }
+    for (const ev of parseEvents) {
+        steps.push({
+            path: ev.path,
+            stage: 'parse',
+            kind: 'change',
+            code: ev.code,
+            message: ev.message,
+        });
+    }
+    for (const ev of validationEvents) {
+        steps.push({
+            path: ev.path,
+            stage: 'validate',
+            kind: 'error',
+            code: ev.code,
+            message: ev.message,
+        });
+    }
+    return { steps };
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Format                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Formats a value for human‑readable explain output.
+ *
+ * Produces stable string representations for primitives and falls back to
+ * compact JSON for objects. Never throws; errors during formatting degrade
+ * gracefully to `String(value)`.
+ */
+export function format(value) {
+    try {
+        if (value === undefined)
+            return 'undefined';
+        if (value === null)
+            return 'null';
+        if (typeof value === 'string')
+            return JSON.stringify(value);
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return String(value);
+        }
+        return JSON.stringify(value, null, 0);
+    }
+    catch {
+        return String(value);
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Run Explain                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Runs the pipeline and returns its explain output.
+ *
+ * Delegates execution to the provided builder and exposes only the explain
+ * portion of the result. No additional processing or reshaping occurs here.
+ */
+export async function runExplain(builder) {
+    const result = await builder.run();
+    return result.explain;
+}

package/dist/core/analysis/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports the public Analysis modules (Diff, Explain,
+ *                  Replay, Telemetry).
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export { diff, walkDiff, runDiff } from './diff';
+export { explain, format, runExplain } from './explain';
+export { applyEntry, replay, runReplay } from './replay';
+export { runTelemetry, telemetry } from './telemetry';

package/dist/core/analysis/index.js

@@ -0,0 +1,26 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports the public Analysis modules (Diff, Explain,
+ *                  Replay, Telemetry).
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Diff                                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { diff, walkDiff, runDiff } from './diff';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Explain                                                                   *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { explain, format, runExplain } from './explain';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Replay                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { applyEntry, replay, runReplay } from './replay';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Telemetry                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { runTelemetry, telemetry } from './telemetry';

package/dist/core/analysis/replay.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Replay
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Reconstructs intermediate states by applying diff entries
+ *                  in order.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { DiffEntry, InternalJsonValue, PipelineBuilder, ReplayFunction } from '../shapes';
+/**
+ * Applies a single diff entry to an internal JSON value.
+ *
+ * Clones the current state, then sets or clears the value at the entry’s path
+ * according to its kind. Used by Replay to advance state one change at a time.
+ * Never mutates the original state.
+ */
+export declare function applyEntry(state: InternalJsonValue, entry: DiffEntry): InternalJsonValue;
+/**
+ * Replays a diff step‑by‑step to reconstruct intermediate states.
+ *
+ * Clones the initial value, applies each diff entry in order, and records a
+ * snapshot after every application. Produces a stable sequence of ReplayStep
+ * objects with index, entry, and resulting state. Never mutates inputs.
+ */
+export declare const replay: ReplayFunction;
+/**
+ * Runs the pipeline and returns its replay output.
+ *
+ * Delegates execution to the provided builder and exposes only the replay
+ * portion of the result. No additional processing or transformation occurs.
+ */
+export declare function runReplay<T>(builder: PipelineBuilder): Promise<import("../shapes").ReplayResult | undefined>;

package/dist/core/analysis/replay.js

@@ -0,0 +1,68 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Replay
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Reconstructs intermediate states by applying diff entries
+ *                  in order.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { setAtPath } from '../field-path';
+import { deepClone } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Apply Entry                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Applies a single diff entry to an internal JSON value.
+ *
+ * Clones the current state, then sets or clears the value at the entry’s path
+ * according to its kind. Used by Replay to advance state one change at a time.
+ * Never mutates the original state.
+ */
+export function applyEntry(state, entry) {
+    const clone = deepClone(state);
+    switch (entry.kind) {
+        case 'added':
+        case 'changed':
+            return setAtPath(clone, entry.path, entry.after);
+        case 'removed':
+            return setAtPath(clone, entry.path, undefined);
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Replay                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Replays a diff step‑by‑step to reconstruct intermediate states.
+ *
+ * Clones the initial value, applies each diff entry in order, and records a
+ * snapshot after every application. Produces a stable sequence of ReplayStep
+ * objects with index, entry, and resulting state. Never mutates inputs.
+ */
+export const replay = ({ before, diff }) => {
+    const steps = [];
+    let current = deepClone(before);
+    diff.forEach((entry, index) => {
+        current = applyEntry(current, entry);
+        steps.push({
+            index,
+            entry,
+            state: deepClone(current),
+        });
+    });
+    return { steps };
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Run Replay                                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Runs the pipeline and returns its replay output.
+ *
+ * Delegates execution to the provided builder and exposes only the replay
+ * portion of the result. No additional processing or transformation occurs.
+ */
+export async function runReplay(builder) {
+    const result = await builder.run();
+    return result.replay;
+}

package/dist/core/analysis/telemetry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Telemetry
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Emits structured records for each pipeline stage for
+ *                  auditing and observability.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { PipelineBuilder, PipelineResult, TelemetryContext, TelemetryResult, TelemetrySink } from '../shapes';
+/**
+ * Collects flat telemetry records for each pipeline stage.
+ *
+ * Emits one record per stage with boundary, pipeline, timestamp, and the
+ * stage‑specific payload (events, diff, explain, replay). Stages are reported
+ * in pipeline order, and a final `decide` record captures the policy outcome.
+ * No aggregation, filtering, or interpretation occurs here.
+ */
+export declare function telemetry<T>(ctx: TelemetryContext<T>): TelemetryResult;
+/**
+ * Runs the pipeline and emits telemetry if enabled by policy.
+ *
+ * Delegates execution to the builder, collects stage records through the
+ * telemetry helper, and forwards them to the provided sink. Returns the full
+ * pipeline result unchanged.
+ */
+export declare function runTelemetry<T>(builder: PipelineBuilder, sink: TelemetrySink): Promise<PipelineResult<T>>;