@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/dist/core/field-path/format.js

@@ -0,0 +1,154 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Format
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Converts FieldPath structures into stable, user‑facing
+ *                  string forms.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { escapeKey, isDangerousKey, isSafeKey, setFieldPath, setIndex, setKey } from '.';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Array To Field Path                                                       *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Converts a list of raw parts into a FieldPath.
+ *
+ * Maps numbers to index segments and strings to key segments, producing a
+ * canonical FieldPath suitable for formatting, traversal, or boundary work.
+ */
+export function arrayToFieldPath(parts) {
+    return setFieldPath(...parts.map((part) => (typeof part === 'number' ? setIndex(part) : setKey(part))));
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Field Path To Array                                                       *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Converts a FieldPath into its raw parts.
+ *
+ * Extracts each segment’s key or index in order, producing a simple array
+ * representation suitable for serialization or comparison.
+ */
+export function fieldPathToArray(path) {
+    return path.segments.map((segment) => (segment.kind === 'index' ? segment.index : segment.key));
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Field Path To User                                                        *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Converts a FieldPath into a user‑facing string.
+ *
+ * Uses dotted notation for safe keys and bracket notation for indexes or
+ * keys requiring escaping. Produces a stable, readable form for logs,
+ * errors, and policy messages.
+ */
+export function fieldPathToUser(path) {
+    if (path.segments.length === 0)
+        return '$';
+    let out = '$';
+    for (const segment of path.segments) {
+        if (segment.kind === 'index') {
+            out += `[${segment.index}]`;
+            continue;
+        }
+        const key = segment.key;
+        if (isSafeKey(key) && !isDangerousKey(key)) {
+            out += `.${key}`;
+        }
+        else {
+            out += `[${escapeKey(key)}]`;
+        }
+    }
+    return out;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* User To Field Path                                                        *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses a user‑facing path string into a FieldPath.
+ *
+ * Supports dotted keys, bracketed indexes, and quoted/escaped keys. Normalizes
+ * the "$" root form and walks the string character‑by‑character to build a
+ * canonical segment list suitable for traversal and boundary evaluation.
+ */
+export function userToFieldPath(user) {
+    if (!user || !user.trim() || user === '$') {
+        return setFieldPath();
+    }
+    let u = user;
+    if (u.startsWith('$')) {
+        u = u.slice(1);
+        if (u.startsWith('.')) {
+            u = u.slice(1);
+        }
+    }
+    const segments = [];
+    let i = 0;
+    while (i < u.length) {
+        const ch = u[i];
+        if (ch === '.') {
+            i++;
+            let key = '';
+            while (i < u.length && /[A-Za-z0-9_$]/.test(u[i])) {
+                key += u[i];
+                i++;
+            }
+            if (key.length > 0)
+                segments.push(setKey(key));
+            continue;
+        }
+        if (ch === '[') {
+            i++;
+            if (u[i] === '"') {
+                const start = i + 1;
+                let j = start;
+                while (j < u.length) {
+                    const c = u[j];
+                    if (c === '\\') {
+                        j += 2;
+                        continue;
+                    }
+                    if (c === '"')
+                        break;
+                    j++;
+                }
+                const rawInner = u.slice(start, j);
+                let key;
+                try {
+                    key = JSON.parse('"' + rawInner + '"');
+                }
+                catch {
+                    key = rawInner;
+                }
+                i = j + 1;
+                if (u[i] === ']')
+                    i++;
+                segments.push(setKey(key));
+                continue;
+            }
+            let num = '';
+            while (i < u.length && /[0-9]/.test(u[i])) {
+                num += u[i];
+                i++;
+            }
+            if (u[i] === ']')
+                i++;
+            if (num.length > 0)
+                segments.push(setIndex(Number(num)));
+            continue;
+        }
+        if (/[A-Za-z_$]/.test(ch)) {
+            let key = '';
+            while (i < u.length && /[A-Za-z0-9_$]/.test(u[i])) {
+                key += u[i];
+                i++;
+            }
+            if (key.length > 0)
+                segments.push(setKey(key));
+            continue;
+        }
+        i++;
+    }
+    return { segments };
+}

package/dist/core/field-path/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports the Field Path modules to provide a unified
+ *                  public surface.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export { appendSegment, cloneContainer, clonePath, makeFieldPath, rootPath, setAtPath, setFieldPath, setIndex, setKey, } from './construct';
+export { arrayToFieldPath, fieldPathToArray, fieldPathToUser, userToFieldPath } from './format';
+export { DANGEROUS_KEYS, escapeKey, isDangerousKey, isRoot, isSafeKey, lastSegment, parentPath, pathEquals, pathStartsWith, segmentsEqual, } from './utilities';
+export { walk, walkArray, walkObject } from './walk';

package/dist/core/field-path/index.js

@@ -0,0 +1,26 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports the Field Path modules to provide a unified
+ *                  public surface.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Construct                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { appendSegment, cloneContainer, clonePath, makeFieldPath, rootPath, setAtPath, setFieldPath, setIndex, setKey, } from './construct';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Format                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { arrayToFieldPath, fieldPathToArray, fieldPathToUser, userToFieldPath } from './format';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Utilities                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { DANGEROUS_KEYS, escapeKey, isDangerousKey, isRoot, isSafeKey, lastSegment, parentPath, pathEquals, pathStartsWith, segmentsEqual, } from './utilities';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Walk                                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { walk, walkArray, walkObject } from './walk';

package/dist/core/field-path/utilities.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Utilities
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Small helper functions supporting FieldPath construction,
+ *                  parsing, and formatting.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath, FieldPathSegment } from '../shapes';
+/**
+ * Keys that must never appear in dotted notation.
+ *
+ * These properties interact with JavaScript’s prototype chain and are always
+ * forced into bracket‑notation to prevent prototype‑pollution vectors in
+ * formatting, parsing, and boundary evaluation.
+ */
+export declare const DANGEROUS_KEYS: Set<string>;
+/**
+ * Escapes a key for bracket notation.
+ *
+ * Uses JSON string rules to preserve all characters exactly, ensuring keys
+ * round‑trip cleanly through user‑facing formatting and parsing.
+ */
+export declare function escapeKey(key: string): string;
+/**
+ * Checks whether a key is unsafe for dotted notation.
+ *
+ * Identifies prototype‑chain properties that must always be emitted in
+ * bracket‑notation to avoid prototype‑pollution vectors.
+ */
+export declare function isDangerousKey(key: string): boolean;
+/**
+ * Checks whether a FieldPath refers to the root.
+ *
+ * A path is the root when it contains no segments, representing the top‑level
+ * position in traversal, formatting, and boundary evaluation.
+ */
+export declare const isRoot: (path: FieldPath) => boolean;
+/**
+ * Checks whether a key is safe for dotted notation.
+ *
+ * Rejects prototype‑chain properties and ensures the key matches JavaScript
+ * identifier rules, allowing it to appear unescaped in user‑facing paths.
+ */
+export declare function isSafeKey(key: string): boolean;
+/**
+ * Returns the final segment of a FieldPath.
+ *
+ * Useful when validators, scanners, or boundary logic need to inspect the
+ * current traversal position without mutating the path.
+ */
+export declare const lastSegment: (path: FieldPath) => FieldPathSegment | undefined;
+/**
+ * Returns the parent of a FieldPath.
+ *
+ * Removes the final segment to move one level up in traversal. Root paths
+ * remain stable—slicing an empty path yields another empty path.
+ */
+export declare function parentPath(path: FieldPath): FieldPath;
+/**
+ * Checks whether two FieldPaths are structurally identical.
+ *
+ * Paths are equal only when they contain the same number of segments and each
+ * corresponding segment matches, ensuring deterministic behavior in diff,
+ * explain, and boundary evaluation.
+ */
+export declare function pathEquals(a: FieldPath, b: FieldPath): boolean;
+/**
+ * Checks whether one FieldPath is a prefix of another.
+ *
+ * Path **a** starts with **b** when b has no more segments than a and each
+ * corresponding segment matches. Used by diff, explain, and boundary logic
+ * to determine whether a rule or change applies to a nested position.
+ */
+export declare function pathStartsWith(a: FieldPath, b: FieldPath): boolean;
+/**
+ * Checks whether two segments are structurally identical.
+ *
+ * Segments must share the same kind, and their key or index values must
+ * match exactly. This is the atomic comparison used by all path‑level
+ * equality and prefix checks.
+ */
+export declare const segmentsEqual: (a: FieldPathSegment, b: FieldPathSegment) => boolean;

package/dist/core/field-path/utilities.js

@@ -0,0 +1,138 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Utilities
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Small helper functions supporting FieldPath construction,
+ *                  parsing, and formatting.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Dangerous Keys                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Keys that must never appear in dotted notation.
+ *
+ * These properties interact with JavaScript’s prototype chain and are always
+ * forced into bracket‑notation to prevent prototype‑pollution vectors in
+ * formatting, parsing, and boundary evaluation.
+ */
+export const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Escape Key                                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Escapes a key for bracket notation.
+ *
+ * Uses JSON string rules to preserve all characters exactly, ensuring keys
+ * round‑trip cleanly through user‑facing formatting and parsing.
+ */
+export function escapeKey(key) {
+    return JSON.stringify(key);
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Is Dangerous Key                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks whether a key is unsafe for dotted notation.
+ *
+ * Identifies prototype‑chain properties that must always be emitted in
+ * bracket‑notation to avoid prototype‑pollution vectors.
+ */
+export function isDangerousKey(key) {
+    return DANGEROUS_KEYS.has(key);
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Is Root                                                                   *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks whether a FieldPath refers to the root.
+ *
+ * A path is the root when it contains no segments, representing the top‑level
+ * position in traversal, formatting, and boundary evaluation.
+ */
+export const isRoot = (path) => path.segments.length === 0;
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Is Safe Key                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks whether a key is safe for dotted notation.
+ *
+ * Rejects prototype‑chain properties and ensures the key matches JavaScript
+ * identifier rules, allowing it to appear unescaped in user‑facing paths.
+ */
+export function isSafeKey(key) {
+    if (DANGEROUS_KEYS.has(key))
+        return false;
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key);
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Last Segment                                                              *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Returns the final segment of a FieldPath.
+ *
+ * Useful when validators, scanners, or boundary logic need to inspect the
+ * current traversal position without mutating the path.
+ */
+export const lastSegment = (path) => path.segments[path.segments.length - 1];
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Parent Path                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Returns the parent of a FieldPath.
+ *
+ * Removes the final segment to move one level up in traversal. Root paths
+ * remain stable—slicing an empty path yields another empty path.
+ */
+export function parentPath(path) {
+    return { segments: path.segments.slice(0, -1) };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Path Equals                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks whether two FieldPaths are structurally identical.
+ *
+ * Paths are equal only when they contain the same number of segments and each
+ * corresponding segment matches, ensuring deterministic behavior in diff,
+ * explain, and boundary evaluation.
+ */
+export function pathEquals(a, b) {
+    if (a.segments.length !== b.segments.length)
+        return false;
+    return a.segments.every((segment, i) => segmentsEqual(segment, b.segments[i]));
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Path Starts With                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks whether one FieldPath is a prefix of another.
+ *
+ * Path **a** starts with **b** when b has no more segments than a and each
+ * corresponding segment matches. Used by diff, explain, and boundary logic
+ * to determine whether a rule or change applies to a nested position.
+ */
+export function pathStartsWith(a, b) {
+    if (b.segments.length > a.segments.length)
+        return false;
+    return b.segments.every((segment, i) => segmentsEqual(segment, a.segments[i]));
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Segments Equal                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks whether two segments are structurally identical.
+ *
+ * Segments must share the same kind, and their key or index values must
+ * match exactly. This is the atomic comparison used by all path‑level
+ * equality and prefix checks.
+ */
+export const segmentsEqual = (a, b) => {
+    if (a.kind !== b.kind)
+        return false;
+    return a.kind === 'index'
+        ? a.index === b.index
+        : a.key === b.key;
+};

package/dist/core/field-path/walk.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Walk
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Traversal helpers that walk JSON‑like data with FieldPath
+ *                  context.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath } from '../shapes';
+/**
+ * Recursively walks a JSON‑like value with FieldPath context.
+ *
+ * Visits the current node, then descends into arrays and plain objects,
+ * constructing child paths segment‑by‑segment. Prototype‑chain keys are
+ * skipped to avoid unsafe traversal during validation, scanning, and
+ * boundary evaluation.
+ */
+export declare function walk(value: unknown, path: FieldPath, visit: (value: unknown, path: FieldPath) => Promise<void>): Promise<void>;
+/**
+ * Visits each element of an array with FieldPath context.
+ *
+ * Emits a child path for every index and invokes the visitor without
+ * descending further. Used internally by higher‑level walkers that
+ * control recursion and traversal strategy.
+ */
+export declare function walkArray(value: readonly unknown[], path: FieldPath, visit: (child: unknown, childPath: FieldPath) => Promise<void>): Promise<void>;
+/**
+ * Visits each own property of an object with FieldPath context.
+ *
+ * Emits a child path for every safe key and invokes the visitor without
+ * descending further. Prototype‑chain keys are skipped to avoid unsafe
+ * traversal during validation, scanning, and boundary evaluation.
+ */
+export declare function walkObject(value: Record<string, unknown>, path: FieldPath, visit: (child: unknown, childPath: FieldPath) => Promise<void>): Promise<void>;

package/dist/core/field-path/walk.js

@@ -0,0 +1,80 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Walk
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Traversal helpers that walk JSON‑like data with FieldPath
+ *                  context.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { appendSegment, setIndex, setKey } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Walk                                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Recursively walks a JSON‑like value with FieldPath context.
+ *
+ * Visits the current node, then descends into arrays and plain objects,
+ * constructing child paths segment‑by‑segment. Prototype‑chain keys are
+ * skipped to avoid unsafe traversal during validation, scanning, and
+ * boundary evaluation.
+ */
+export async function walk(value, path, visit) {
+    await visit(value, path);
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const child = value[i];
+            const childPath = appendSegment(path, setIndex(i));
+            await walk(child, childPath, visit);
+        }
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        for (const key of Object.keys(record)) {
+            if (!Object.prototype.hasOwnProperty.call(record, key))
+                continue;
+            if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+                continue;
+            const child = record[key];
+            const childPath = appendSegment(path, setKey(key));
+            await walk(child, childPath, visit);
+        }
+        return;
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Walk Array                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Visits each element of an array with FieldPath context.
+ *
+ * Emits a child path for every index and invokes the visitor without
+ * descending further. Used internally by higher‑level walkers that
+ * control recursion and traversal strategy.
+ */
+export async function walkArray(value, path, visit) {
+    for (let index = 0; index < value.length; index++) {
+        await visit(value[index], appendSegment(path, setIndex(index)));
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Walk Object                                                              *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Visits each own property of an object with FieldPath context.
+ *
+ * Emits a child path for every safe key and invokes the visitor without
+ * descending further. Prototype‑chain keys are skipped to avoid unsafe
+ * traversal during validation, scanning, and boundary evaluation.
+ */
+export async function walkObject(value, path, visit) {
+    for (const [key, child] of Object.entries(value)) {
+        if (!Object.prototype.hasOwnProperty.call(value, key))
+            continue;
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+            continue;
+        await visit(child, appendSegment(path, setKey(key)));
+    }
+}