@clementine-solutions/jane-io 1.0.1 → 1.0.3

package/dist/core/parsers/parse-date-string.js

@@ -0,0 +1,30 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse ISO Date String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses strict ISO‑8601 date strings into `Date` objects,
+ *                  rejecting malformed or non‑standard formats.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses strict ISO‑8601 date strings into `Date` objects, rejecting malformed
+ * or non‑standard formats and ensuring the resulting timestamp is valid.
+ */
+export const parseIsoDateString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    const iso = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})?)?$/;
+    if (!iso.test(value))
+        return [];
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime()))
+        return [];
+    const event = parseEvent('info', 'string.now.date', `String parsed into Date ${parsed.toISOString()}.`, path, 'Converted text into a date.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-duration-string.js

@@ -0,0 +1,37 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Duration String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses duration strings of the form `<number><unit>` (s, m,
+ *                  h, d) into structured duration objects.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses duration strings of the form `<number><unit>` (s, m, h, d) into
+ * structured duration objects, rejecting ambiguous or partial formats.
+ */
+export const parseDurationString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    // Strict: number + unit (s, m, h, d)
+    const match = /^(-?\d+)([smhd])$/.exec(value);
+    if (!match)
+        return [];
+    const amount = Number(match[1]);
+    const unit = match[2];
+    const parsed = unit === 's'
+        ? { seconds: amount }
+        : unit === 'm'
+            ? { minutes: amount }
+            : unit === 'h'
+                ? { hours: amount }
+                : { days: amount };
+    const event = parseEvent('info', 'string.now.duration', `String parsed into duration object (${JSON.stringify(parsed)}).`, path, 'Converted text into a time duration.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-hex-string.js

@@ -0,0 +1,29 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Hex String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses hexadecimal string literals (0x…) into `bigint`
+ *                  values, enforcing canonical formatting.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses hexadecimal string literals (`0x…`) into numeric values, rejecting
+ * malformed or non‑hexadecimal input.
+ */
+export const parseHexString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    if (!/^0x[0-9a-fA-F]+$/.test(value))
+        return [];
+    const parsed = Number(value);
+    if (Number.isNaN(parsed))
+        return [];
+    const event = parseEvent('info', 'string.now.hex', `Hex string parsed into number ${parsed}.`, path, 'Converted hexadecimal text into a number.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-integer-string.js

@@ -0,0 +1,30 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Integer String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses strict integer strings into numeric values, rejecting
+ *                  floats, scientific notation, and ambiguous formats.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses strict integer strings into numeric values, rejecting floats,
+ * scientific notation, and any non‑digit characters.
+ */
+export const parseIntegerString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    // Strict integer: optional leading minus, digits only
+    if (!/^-?\d+$/.test(value))
+        return [];
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        return [];
+    const event = parseEvent('info', 'string.now.integer', `String parsed into integer ${parsed}.`, path, 'Converted text into a whole number.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-json-string.js

@@ -0,0 +1,35 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse JSON String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses JSON‑compatible strings into structured data,
+ *                  accepting only valid objects, arrays, or quoted strings.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses JSON‑compatible strings into structured data, accepting only objects,
+ * arrays, or quoted strings and rejecting anything that cannot be parsed
+ * safely.
+ */
+export const parseJsonString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    const first = value.trim()[0];
+    if (first !== '{' && first !== '[' && first !== '"')
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return [];
+    }
+    const event = parseEvent('info', 'string.now.json', 'String parsed as JSON.', path, 'Converted text into structured data.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-numeric-string.js

@@ -0,0 +1,29 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Numeric String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses strict numeric strings into numbers, supporting
+ *                  optional decimals while rejecting ambiguous formats.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses strict numeric strings into JavaScript numbers, supporting optional
+ * decimals while rejecting scientific notation and non‑numeric characters.
+ */
+export const parseNumericString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    if (!/^-?\d+(\.\d+)?$/.test(value))
+        return [];
+    const parsed = Number(value);
+    if (Number.isNaN(parsed))
+        return [];
+    const event = parseEvent('info', 'string.now.number', `String parsed into number ${parsed}.`, path, 'Converted text into a number.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-object-string.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Object String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses JSON object strings into plain objects, rejecting
+ *                  arrays, null, and non‑object structures.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses JSON object strings into plain objects, rejecting arrays, null, and
+ * any non‑object structures.
+ */
+export const parseObjectString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('{') || !trimmed.endsWith('}'))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return [];
+    const event = parseEvent('info', 'string.now.object', 'String parsed into JSON object.', path, 'Converted text into an object.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-octal-string.js

@@ -0,0 +1,33 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Octal String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses octal string literals (`0o…`) into `bigint` values,
+ *                  enforcing strict base‑8 formatting.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses octal string literals (`0o…`) into `bigint` values, validating format
+ * and rejecting malformed or non‑octal input.
+ */
+export const parseOctalString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    if (!/^0o[0-7]+$/.test(value))
+        return [];
+    let parsed;
+    try {
+        parsed = BigInt(value);
+    }
+    catch {
+        return [];
+    }
+    const event = parseEvent('info', 'string.now.octal', `Octal string parsed into bigint ${parsed}.`, path, 'Converted octal text into a number.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-scientific-notation-string.js

@@ -0,0 +1,30 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse Scientific Notation String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses strict scientific‑notation strings into numbers,
+ *                  validating both mantissa and exponent format.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses strict scientific‑notation strings into numbers, enforcing canonical
+ * formatting for both mantissa and exponent.
+ */
+export const parseScientificNotationString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    // Strict scientific notation: digits, optional decimal, 'e' or 'E', signed exponent
+    if (!/^-?\d+(\.\d+)?[eE][+-]?\d+$/.test(value))
+        return [];
+    const parsed = Number(value);
+    if (Number.isNaN(parsed))
+        return [];
+    const event = parseEvent('info', 'string.now.scientific', `String parsed into number ${parsed} using scientific notation.`, path, 'Converted scientific notation into a number.', { before: value, after: parsed });
+    return [{ path, nextValue: parsed, events: [event] }];
+};

package/dist/core/parsers/parse-url-string.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Parsers | Parse URL String
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Parses URL strings into normalized URL values, ensuring the
+ *                  text represents a valid, fully qualified URL.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { parseEvent } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Parses URL strings into normalized URL values, ensuring the text represents
+ * a syntactically valid and fully qualified URL.
+ */
+export const parseUrlString = (value, path) => {
+    if (typeof value !== 'string')
+        return [];
+    try {
+        const normalized = new URL(value).toString();
+        const event = parseEvent('info', 'string.now.url', `String parsed into URL (${normalized}).`, path, 'Converted text into a URL.', { before: value, after: normalized });
+        return [
+            {
+                path,
+                nextValue: normalized,
+                events: [event],
+            },
+        ];
+    }
+    catch {
+        return [];
+    }
+};

package/dist/core/pipeline/boundary.js

@@ -0,0 +1,256 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Boundary
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Aggregates field results and applies boundary‑level policy
+ *                  to produce a final decision.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { applyEscalate, applyOverride, defaultPolicy, generateRunId, matchesWildcard, resolveLevel, } from '../common';
+import { boundaryPolicyDefault } from '../common/policy';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Boundary Rule Registry                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Holds all registered boundary‑level rules.
+ *
+ * Provides a central lookup for rule names used in boundary policies,
+ * allowing contributors to extend or customize boundary evaluation
+ * without modifying the core engine.
+ */
+export const boundaryRuleRegistry = {};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Boundary Runner                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Executes boundary evaluation across all field results.
+ *
+ * Aggregates issues and events from each pipeline result, applies
+ * boundary‑level rules, shapes values and metadata according to policy,
+ * and produces the final boundary result used for acceptance decisions.
+ */
+export async function boundaryRunner(input) {
+    const startedAt = new Date();
+    const runId = generateRunId();
+    const { policy = defaultPolicy, fields } = input;
+    const boundary = policy.boundary ?? boundaryPolicyDefault;
+    const allIssues = [];
+    const allEvents = [];
+    const metadata = {};
+    const value = {};
+    for (const key of Object.keys(fields)) {
+        const result = fields[key];
+        metadata[key] = {
+            raw: result.raw,
+            safe: result.safe,
+            final: result.final,
+            path: result.path,
+            rawType: result.rawType,
+            finalType: result.finalType,
+            startedAt: result.metadata.startedAt,
+            finishedAt: result.metadata.finishedAt,
+            durationMs: result.metadata.durationMs,
+            inputName: result.metadata.inputName,
+        };
+        if (result.decision?.code === 'accept') {
+            value[key] = result.final;
+        }
+        const events = result.events ?? [];
+        const issues = events.filter((e) => (e.kind === 'error' || e.kind === 'fatal') &&
+            typeof e.code === 'string' &&
+            e.code.trim().length > 0);
+        allIssues.push(...issues);
+        allEvents.push(...events);
+    }
+    if (boundary?.rules && boundary.rules.length > 0) {
+        for (const rule of boundary.rules) {
+            const ctx = {
+                policy,
+                fields,
+                events: allEvents,
+                issues: allIssues,
+                values: value,
+            };
+            try {
+                const result = await rule(ctx);
+                if (!result)
+                    continue;
+                if (result.events)
+                    allEvents.push(...result.events);
+                if (result.issues)
+                    allIssues.push(...result.issues);
+            }
+            catch (error) {
+                allEvents.push({
+                    phase: 'decide',
+                    kind: 'fatal',
+                    code: 'boundary.fatal.error',
+                    message: error?.message ?? 'Unknown error',
+                });
+            }
+        }
+    }
+    const finishedAt = new Date();
+    const decision = await decideBoundary({
+        policy,
+        fields,
+        issues: allIssues,
+        events: allEvents,
+        values: value,
+    });
+    let shapedValues = { ...value };
+    if (boundary?.values?.includeRejected) {
+        for (const key of Object.keys(fields)) {
+            const r = fields[key];
+            if (r.decision?.code !== 'accept') {
+                shapedValues[key] = r.final;
+            }
+        }
+    }
+    if (boundary?.values?.includeUndefined) {
+        for (const key of Object.keys(fields)) {
+            if (!(key in shapedValues)) {
+                shapedValues[key] = undefined;
+            }
+        }
+    }
+    if (boundary?.values?.transform) {
+        shapedValues = boundary.values.transform(shapedValues);
+    }
+    let shapedMetadata = {
+        runId,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        fields: metadata,
+        boundaryName: policy.boundaryName,
+        pipelineName: policy.pipelineName,
+        analysis: {
+            diff: policy.analysis?.diff,
+            explain: policy.analysis?.explain,
+            replay: policy.analysis?.replay,
+            telemetry: policy.analysis?.telemetry,
+        },
+    };
+    if (boundary?.metadata) {
+        const m = boundary.metadata;
+        if (m.includeFields === false) {
+            shapedMetadata = { ...shapedMetadata, fields: {} };
+        }
+        if (m.includeTimestamps === false) {
+            shapedMetadata = {
+                ...shapedMetadata,
+                startedAt: undefined,
+                finishedAt: undefined,
+                durationMs: undefined,
+            };
+        }
+        if (m.includeRunId === false) {
+            shapedMetadata = { ...shapedMetadata, runId: undefined };
+        }
+    }
+    return {
+        ok: decision.ok,
+        issues: decision.issues ?? (allIssues.length > 0 ? allIssues : undefined),
+        events: decision.events ?? (allEvents.length > 0 ? allEvents : undefined),
+        values: decision.values ?? shapedValues,
+        fields,
+        metadata: decision.metadata ?? shapedMetadata,
+    };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Decide Boundary                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Applies boundary decision logic to the aggregated context.
+ *
+ * Shapes events and issues through ignore, override, escalate, and
+ * visibility rules, evaluates acceptance modes, and optionally invokes
+ * a reducer to refine or override the final decision.
+ */
+export async function decideBoundary(context) {
+    const { policy, fields } = context;
+    const boundary = policy.boundary;
+    let shapedEvents = [...context.events];
+    if (boundary?.ignore) {
+        shapedEvents = shapedEvents.filter((ev) => !matchesWildcard(ev.code, boundary.ignore));
+    }
+    if (boundary?.override) {
+        shapedEvents = shapedEvents.map((ev) => {
+            const level = resolveLevel(ev.code, boundary.override);
+            return level === undefined ? ev : { ...ev, kind: applyOverride(ev.kind, level) };
+        });
+    }
+    if (boundary?.escalate) {
+        shapedEvents = shapedEvents.map((ev) => {
+            const level = resolveLevel(ev.code, boundary.escalate);
+            return level === undefined ? ev : { ...ev, kind: applyEscalate(ev.kind, level) };
+        });
+    }
+    if (boundary?.hideEvents) {
+        shapedEvents = shapedEvents.filter((ev) => !matchesWildcard(ev.code, boundary.hideEvents));
+    }
+    let shapedIssues = shapedEvents.filter((ev) => (ev.kind === 'error' || ev.kind === 'fatal') &&
+        typeof ev.code === 'string' &&
+        ev.code.trim().length > 0);
+    if (boundary?.hideIssues) {
+        shapedIssues = shapedIssues.filter((ev) => !matchesWildcard(ev.code, boundary.hideIssues));
+    }
+    const rejectPatterns = boundary?.reject ?? policy.decide?.reject ?? [];
+    const reviewPatterns = boundary?.review ?? policy.decide?.review ?? [];
+    let hasReject = false;
+    let hasReview = false;
+    for (const ev of shapedEvents) {
+        if (ev.kind === 'fatal') {
+            hasReject = true;
+            continue;
+        }
+        if (matchesWildcard(ev.code, rejectPatterns)) {
+            hasReject = true;
+            continue;
+        }
+        if (matchesWildcard(ev.code, reviewPatterns)) {
+            hasReview = true;
+        }
+    }
+    const acceptMode = boundary?.accept ?? 'all';
+    let ok;
+    switch (acceptMode) {
+        case 'strict':
+            ok = !hasReject && !hasReview && shapedIssues.length === 0;
+            break;
+        case 'any':
+            ok = !hasReject && Object.values(fields).some((r) => r.decision?.code === 'accept');
+            break;
+        case 'partial':
+            ok = !hasReject;
+            break;
+        case 'all':
+        default:
+            ok =
+                !hasReject &&
+                    shapedIssues.length === 0 &&
+                    Object.values(fields).every((r) => r.decision?.code === 'accept');
+            break;
+    }
+    const shapedContext = {
+        ...context,
+        events: shapedEvents,
+        issues: shapedIssues,
+    };
+    if (boundary?.reducer) {
+        const result = await boundary.reducer(shapedContext);
+        if (result !== undefined) {
+            if ('ok' in result && typeof result.ok === 'boolean') {
+                return result;
+            }
+            return {
+                ok,
+                ...result,
+            };
+        }
+    }
+    return { ok };
+}