@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/dist/core/common/utilities.js

@@ -0,0 +1,177 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Common | Utilities
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shared low‑level helpers used across Jane’s core subsystems.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Deep Equal                                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Performs structural deep equality on contained values.
+ *
+ * Primitives are compared by value, arrays and plain objects by shape and
+ * recursively by content, and Date objects by timestamp. Non‑plain objects
+ * are rejected. Cycle detection ensures safe comparison of recursive
+ * structures. This function defines the structural equality model used
+ * throughout Jane’s containment and diff logic.
+ */
+export function deepEqual(a, b, seen = new WeakMap()) {
+    if (a === b)
+        return true;
+    if (typeof a === 'number' && typeof b === 'number') {
+        return Number.isNaN(a) && Number.isNaN(b);
+    }
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    if (seen.has(a))
+        return seen.get(a) === b;
+    seen.set(a, b);
+    if (a instanceof Date && b instanceof Date) {
+        return a.getTime() === b.getTime();
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEqual(a[i], b[i], seen))
+                return false;
+        }
+        return true;
+    }
+    if (!isPlainObject(a) || !isPlainObject(b))
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const key of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(b, key))
+            return false;
+        if (!deepEqual(a[key], b[key], seen)) {
+            return false;
+        }
+    }
+    return true;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Generate Run Id                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Generates a unique run identifier.
+ *
+ * Uses `crypto.randomUUID` when available for strong, collision‑resistant IDs.
+ * Falls back to a timestamp + entropy string in environments without UUID
+ * support. Always returns a stable string suitable for pipeline metadata.
+ */
+export function generateRunId() {
+    if (typeof crypto?.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // Fallback: time + entropy
+    return `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Is Object                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks for non‑null object values.
+ *
+ * Used as a minimal guard before structural checks. Functions, arrays, and
+ * plain objects all satisfy this test; it only excludes `null` and primitives.
+ */
+export function isObject(v) {
+    return v !== null && typeof v === 'object';
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Is Plain Object                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks whether a value is a strict plain object.
+ *
+ * Excludes arrays, null, and objects with custom or null prototypes. Only
+ * `{}`‑shaped values created by `Object` with `Object.prototype` qualify.
+ * Used wherever structural rules require predictable, JSON‑compatible objects.
+ */
+export function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype && value.constructor === Object;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Is Primitive                                                              *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks whether a value is a JavaScript primitive.
+ *
+ * Includes all scalar literals plus `null` and `undefined`. Anything that is
+ * not an object and not a function qualifies. Used as a fast‑path guard before
+ * structural or container‑level checks.
+ */
+export function isPrimitive(value) {
+    return value === null || (typeof value !== 'object' && typeof value !== 'function');
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Safe Stringify                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Safely stringifies arbitrary values for use in messages and telemetry.
+ *
+ * Primitives are returned directly, strings are truncated with JSON quoting,
+ * functions and symbols are rendered as descriptive sentinels, and objects are
+ * JSON‑encoded with circular‑reference protection. Output is always bounded by
+ * `maxLength` to prevent runaway logs or unreadable diagnostics.
+ */
+export function safeStringify(value, maxLength = 80) {
+    try {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        const t = typeof value;
+        if (t === 'string') {
+            const s = value;
+            return s.length > maxLength
+                ? JSON.stringify(s.slice(0, maxLength)) + '…"'
+                : JSON.stringify(s);
+        }
+        if (t === 'number' || t === 'boolean' || t === 'bigint') {
+            return String(value);
+        }
+        if (t === 'symbol') {
+            return value.toString();
+        }
+        if (t === 'function') {
+            const _fn = value;
+            const name = value.name || 'anonymous';
+            return `[Function ${name}]`;
+        }
+        if (t === 'object') {
+            const seen = new WeakSet();
+            const json = JSON.stringify(value, (key, val) => {
+                if (typeof val === 'object' && val !== null) {
+                    if (seen.has(val))
+                        return '[Circular]';
+                    seen.add(val);
+                }
+                return val;
+            }, 2);
+            if (!json)
+                return String(value);
+            return json.length > maxLength ? json.slice(0, maxLength) + '…' : json;
+        }
+        return String(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/core/common/wildcard.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Common | Wildcard
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Wildcard pattern helpers used for event‑code matching in policy rules.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { EventCode } from '../shapes';
+/**
+ * Compiles a wildcard pattern into a safe, anchored regular expression.
+ *
+ * Escapes all regex metacharacters except `*`, which expands to `.*`. The
+ * result matches the entire string, ensuring predictable event‑code pattern
+ * checks in policy rules.
+ */
+export declare function compileWildcard(pattern: string): RegExp;
+export declare function getCompiledWildcard(pattern: string): RegExp;
+/**
+ * Checks whether an event code matches any literal or wildcard pattern.
+ *
+ * Exact string matches take priority. Wildcard patterns are resolved through
+ * cached compiled expressions and tested in order. Returns `true` on the first
+ * match, otherwise `false`.
+ */
+export declare function matchesWildcard(code: EventCode, patterns: readonly string[]): boolean;

package/dist/core/common/wildcard.js

@@ -0,0 +1,63 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Common | Wildcard
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Wildcard pattern helpers used for event‑code matching in policy rules.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Compile Wildcard                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Compiles a wildcard pattern into a safe, anchored regular expression.
+ *
+ * Escapes all regex metacharacters except `*`, which expands to `.*`. The
+ * result matches the entire string, ensuring predictable event‑code pattern
+ * checks in policy rules.
+ */
+export function compileWildcard(pattern) {
+    const escaped = pattern.replace(/[-/\\^$+?.()|[\]{}]/g, '\\$&');
+    return new RegExp('^' + escaped.replace(/\*/g, '.*') + '$');
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Get Compiled Wildcard                                                     *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Returns a cached compiled wildcard, compiling on first use.
+ *
+ * Ensures each pattern is compiled once for consistent, fast matching across
+ * policy lookups. Cache entries are stable for the lifetime of the process.
+ */
+const wildcardCache = new Map();
+export function getCompiledWildcard(pattern) {
+    const cached = wildcardCache.get(pattern);
+    if (cached)
+        return cached;
+    const compiled = compileWildcard(pattern);
+    wildcardCache.set(pattern, compiled);
+    return compiled;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Matches Wildcard                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Checks whether an event code matches any literal or wildcard pattern.
+ *
+ * Exact string matches take priority. Wildcard patterns are resolved through
+ * cached compiled expressions and tested in order. Returns `true` on the first
+ * match, otherwise `false`.
+ */
+export function matchesWildcard(code, patterns) {
+    for (const p of patterns) {
+        if (p === code)
+            return true;
+        if (p.includes('*')) {
+            const re = getCompiledWildcard(p);
+            if (re.test(code))
+                return true;
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,77 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Construct
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Constructors for creating canonical, immutable FieldPath
+ *                  objects.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath, FieldPathSegment, InternalJsonValue, SegmentIndex, SegmentKey } from '../shapes';
+/**
+ * Appends a segment to an existing FieldPath.
+ *
+ * Produces a new canonical FieldPath by extending the current path’s segment
+ * list. Never mutates the original path.
+ */
+export declare function appendSegment(path: FieldPath, segment: FieldPathSegment): FieldPath;
+/**
+ * Produces a deep clone of an InternalJsonValue.
+ *
+ * Recursively copies arrays and plain objects while returning primitives,
+ * null, and undefined unchanged. Never mutates the input and never preserves
+ * references, ensuring safe use in diff, replay, and boundary evaluation.
+ */
+export declare function cloneContainer(value: InternalJsonValue): InternalJsonValue;
+/**
+ * Creates a shallow clone of a FieldPath.
+ *
+ * Copies the segment list into a new canonical FieldPath, ensuring callers
+ * never share mutable path state.
+ */
+export declare function clonePath(path: FieldPath): FieldPath;
+/**
+ * Creates a canonical FieldPath from a list of segments.
+ *
+ * Wraps the segment array with a stable toString() implementation and optional
+ * inputName. Produces a new immutable path object without modifying callers’
+ * data.
+ */
+export declare function makeFieldPath(segments: FieldPathSegment[], inputName?: string): FieldPath;
+/**
+ * Creates the root FieldPath.
+ *
+ * Produces an empty canonical path with an optional inputName. Used as the
+ * starting point for all path construction and never carries any segments.
+ */
+export declare const rootPath: (inputName?: string) => FieldPath;
+/**
+ * Sets a value at the given FieldPath.
+ *
+ * If the path is empty, returns the value directly. Otherwise delegates to the
+ * recursive setter, producing a new InternalJsonValue without mutating the
+ * original root.
+ */
+export declare function setAtPath(root: InternalJsonValue, path: FieldPath, value: InternalJsonValue): InternalJsonValue;
+/**
+ * Builds a FieldPath from the provided segments.
+ *
+ * Wraps the segment list in a canonical FieldPath object, ensuring callers
+ * always work with an immutable, well‑formed path representation.
+ */
+export declare const setFieldPath: (...segments: FieldPathSegment[]) => FieldPath;
+/**
+ * Creates an index segment.
+ *
+ * Wraps the numeric index in a canonical SegmentIndex object for use in
+ * FieldPath construction.
+ */
+export declare const setIndex: (index: number) => SegmentIndex;
+/**
+ * Creates a key segment.
+ *
+ * Wraps the string key in a canonical SegmentKey object for use in
+ * FieldPath construction.
+ */
+export declare const setKey: (key: string) => SegmentKey;

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

@@ -0,0 +1,189 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Construct
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Constructors for creating canonical, immutable FieldPath
+ *                  objects.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Internal Modules                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+import { deepClone } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Append Segment                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Appends a segment to an existing FieldPath.
+ *
+ * Produces a new canonical FieldPath by extending the current path’s segment
+ * list. Never mutates the original path.
+ */
+export function appendSegment(path, segment) {
+    return makeFieldPath([...path.segments, segment]);
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Clone Container                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Produces a deep clone of an InternalJsonValue.
+ *
+ * Recursively copies arrays and plain objects while returning primitives,
+ * null, and undefined unchanged. Never mutates the input and never preserves
+ * references, ensuring safe use in diff, replay, and boundary evaluation.
+ */
+export function cloneContainer(value) {
+    if (Array.isArray(value)) {
+        const array = value;
+        return array.map((v) => cloneContainer(v));
+    }
+    if (value !== null && typeof value === 'object') {
+        const obj = value;
+        const clone = {};
+        for (const key of Object.keys(obj)) {
+            clone[key] = cloneContainer(obj[key]);
+        }
+        return clone;
+    }
+    return value;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Clone Path                                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates a shallow clone of a FieldPath.
+ *
+ * Copies the segment list into a new canonical FieldPath, ensuring callers
+ * never share mutable path state.
+ */
+export function clonePath(path) {
+    return makeFieldPath([...path.segments]);
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Make Field Path                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates a canonical FieldPath from a list of segments.
+ *
+ * Wraps the segment array with a stable toString() implementation and optional
+ * inputName. Produces a new immutable path object without modifying callers’
+ * data.
+ */
+export function makeFieldPath(segments, inputName) {
+    return {
+        segments,
+        inputName,
+        toString() {
+            if (segments.length === 0)
+                return inputName ? inputName : '/';
+            return ('/' + segments.map((s) => (s.kind === 'key' ? s.key : String(s.index))).join('/'));
+        },
+    };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Root Path                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates the root FieldPath.
+ *
+ * Produces an empty canonical path with an optional inputName. Used as the
+ * starting point for all path construction and never carries any segments.
+ */
+export const rootPath = (inputName) => makeFieldPath([], inputName);
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Set At Path                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Sets a value at the given FieldPath.
+ *
+ * If the path is empty, returns the value directly. Otherwise delegates to the
+ * recursive setter, producing a new InternalJsonValue without mutating the
+ * original root.
+ */
+export function setAtPath(root, path, value) {
+    const { segments } = path;
+    if (segments.length === 0) {
+        return value;
+    }
+    return setAtPathRecursive(root, segments, 0, value);
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Set At Path Recursive                                                     *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Recursively sets a value at a nested FieldPath segment.
+ *
+ * Clones arrays and objects as it descends, ensuring each level is rebuilt
+ * without mutating the original structure. When the final segment is reached,
+ * assigns the value and returns the newly constructed container.
+ */
+function setAtPathRecursive(current, segments, index, value) {
+    const seg = segments[index];
+    const isLast = index === segments.length - 1;
+    if (seg.kind === 'index') {
+        const idx = seg.index;
+        const baseArray = Array.isArray(current)
+            ? current
+            : [];
+        const nextArray = baseArray.slice();
+        if (isLast) {
+            nextArray[idx] = value;
+            return nextArray;
+        }
+        const child = baseArray[idx] === undefined ? undefined : deepClone(baseArray[idx]);
+        const updatedChild = setAtPathRecursive(child, segments, index + 1, value);
+        nextArray[idx] = updatedChild;
+        return nextArray;
+    }
+    const key = seg.key;
+    const baseObject = current !== null && typeof current === 'object' && !Array.isArray(current)
+        ? current
+        : {};
+    const nextObject = { ...baseObject };
+    if (isLast) {
+        nextObject[key] = value;
+        return nextObject;
+    }
+    const child = baseObject[key] === undefined ? undefined : deepClone(baseObject[key]);
+    const updatedChild = setAtPathRecursive(child, segments, index + 1, value);
+    nextObject[key] = updatedChild;
+    return nextObject;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Set Field Path                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Builds a FieldPath from the provided segments.
+ *
+ * Wraps the segment list in a canonical FieldPath object, ensuring callers
+ * always work with an immutable, well‑formed path representation.
+ */
+export const setFieldPath = (...segments) => makeFieldPath([...segments]);
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Set Index                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates an index segment.
+ *
+ * Wraps the numeric index in a canonical SegmentIndex object for use in
+ * FieldPath construction.
+ */
+export const setIndex = (index) => ({
+    kind: 'index',
+    index,
+});
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Set Key                                                                   *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates a key segment.
+ *
+ * Wraps the string key in a canonical SegmentKey object for use in
+ * FieldPath construction.
+ */
+export const setKey = (key) => ({
+    kind: 'key',
+    key,
+});

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

@@ -0,0 +1,41 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Field Path | Format
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Converts FieldPath structures into stable, user‑facing
+ *                  string forms.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath } from '../shapes';
+/**
+ * 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 declare function arrayToFieldPath(parts: (string | number)[]): FieldPath;
+/**
+ * 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 declare function fieldPathToArray(path: FieldPath): (string | number)[];
+/**
+ * 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 declare function fieldPathToUser(path: FieldPath): string;
+/**
+ * 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 declare function userToFieldPath(user?: string): FieldPath;