@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/dist/core/shapes/scan.d.ts

@@ -0,0 +1,126 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Scan
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define how raw input is inspected and converted
+ *                  into safe JSON‑like form.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath, JaneEvent, Policy } from '.';
+/**
+ * Execution context for containment.
+ *
+ * Holds structural limits, a cycle‑detection map, and the active policy.
+ * Used by containment routines to enforce depth and size limits while
+ * producing safe, JSON‑like representations of arbitrary input.
+ */
+export interface ContainmentContext {
+    readonly options: ContainmentOptions;
+    readonly seen: WeakMap<object, unknown>;
+    readonly policy: Policy;
+}
+/**
+ * Structural limits applied during containment.
+ *
+ * These bounds prevent unbounded recursion and excessive traversal by
+ * capping depth, array length, and object key count.
+ */
+export interface ContainmentOptions {
+    readonly maxDepth: number;
+    readonly maxArrayLength: number;
+    readonly maxObjectKeys: number;
+}
+/**
+ * A JSON‑like object used internally during containment.
+ *
+ * Keys are plain strings and values are restricted to InternalJsonValue,
+ * ensuring the structure is safe, serializable, and cycle‑free.
+ */
+export type InternalJsonObject = {
+    [key: string]: InternalJsonValue;
+};
+/**
+ * A JSON‑like array used internally during containment.
+ *
+ * Elements are restricted to InternalJsonValue to guarantee safe,
+ * serializable structure throughout the pipeline.
+ */
+export type InternalJsonArray = InternalJsonValue[];
+/**
+ * The full set of values allowed inside internal JSON structures.
+ *
+ * Extends standard JSON with `undefined` to support partial containment
+ * and sentinel values during scanning and normalization.
+ */
+export type InternalJsonValue = string | number | boolean | null | InternalJsonArray | InternalJsonObject | undefined;
+/**
+ * A strict JSON‑serializable value.
+ *
+ * Used for public surfaces and output shapes where only standard JSON
+ * types are permitted.
+ */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * A function that executes the scan stage.
+ *
+ * Receives a ScanStageContext and returns a ScanStageOutput, allowing
+ * pipelines to plug in custom scanning behavior.
+ */
+export type ScanRule = (raw: unknown, path: FieldPath) => readonly JaneEvent[];
+/**
+ * Groups scan rules by structural type.
+ *
+ * The scanner selects rules from these buckets based on the detected
+ * StructuralType, while `all` contains rules applied universally.
+ */
+export interface ScanRuleSet {
+    readonly all: readonly ScanRule[];
+    readonly string: readonly ScanRule[];
+    readonly number: readonly ScanRule[];
+    readonly boolean: readonly ScanRule[];
+    readonly array: readonly ScanRule[];
+    readonly object: readonly ScanRule[];
+    readonly date: readonly ScanRule[];
+    readonly unknown: readonly ScanRule[];
+    readonly bigint: readonly ScanRule[];
+}
+/**
+ * Executes the scan stage.
+ *
+ * Accepts a ScanStageContext and returns a ScanStageOutput, allowing
+ * pipelines to plug in custom scanning behavior.
+ */
+export type ScanRunner = (input: ScanStageContext) => Promise<ScanStageOutput>;
+/**
+ * Input to a scan stage execution.
+ *
+ * Provides the raw value, its current path, the active scan rules,
+ * and the policy controlling how events are interpreted.
+ */
+export interface ScanStageContext {
+    readonly raw: unknown;
+    readonly path?: FieldPath;
+    readonly rules: readonly ScanRule[];
+    readonly policy: Policy;
+}
+/**
+ * Output produced by the scan stage.
+ *
+ * Contains all emitted scan events and the safe, JSON‑like value
+ * derived from the raw input.
+ */
+export interface ScanStageOutput {
+    readonly events: readonly JaneEvent[];
+    readonly safe: InternalJsonValue;
+}
+/**
+ * The structural categories recognized by the scanner.
+ *
+ * Used to select scan rules and classify raw input without relying
+ * on user‑defined types or schema information.
+ */
+export type StructuralType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date' | 'bigint' | 'unknown';

package/dist/core/shapes/scan.js

@@ -0,0 +1,11 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Scan
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define how raw input is inspected and converted
+ *                  into safe JSON‑like form.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

package/dist/core/shapes/validate.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Validate
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define rule‑driven correctness checks during
+ *                  validation.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath, JaneEvent, PipelineBuilder } from '.';
+import type { janeRegistry } from '../fluent-registry';
+/**
+ * A factory that produces a validation rule.
+ *
+ * Used by registry‑backed fluent APIs to create parameterized validators
+ * from user‑supplied arguments.
+ */
+export type ValidatorFactory = (...args: unknown[]) => ValidationRule;
+/**
+ * A fluent validator entry for a named validator in the registry.
+ *
+ * If the registry entry is a factory, exposes its parameters and returns
+ * a PipelineBuilder. Otherwise, returns a PipelineBuilder directly.
+ */
+export type ValidatorFactoryRule<Name extends ValidatorName> = (typeof janeRegistry.validators)[Name] extends ValidatorFactory ? (...args: Parameters<(typeof janeRegistry.validators)[Name]>) => PipelineBuilder : PipelineBuilder;
+/**
+ * The fluent rule type for any validator registered in Jane.
+ *
+ * Represents either a zero‑argument validator or a parameterized factory,
+ * depending on the registry entry.
+ */
+export type ValidatorFluentRule = (typeof janeRegistry.validators)[ValidatorName];
+/**
+ * The set of validator names registered in Jane.
+ *
+ * Used to index validator factories and fluent rules in the registry.
+ */
+export type ValidatorName = keyof typeof janeRegistry.validators;
+/**
+ * A validation rule that inspects a value and emits correctness events.
+ *
+ * Rules return zero or more JaneEvent entries describing issues found at
+ * the given path.
+ */
+export type ValidationRule = (value: unknown, path: FieldPath) => readonly JaneEvent[] | Promise<readonly JaneEvent[]>;
+/**
+ * Input to a validation stage execution.
+ *
+ * Provides the normalized value, its current path, and the active
+ * validation rules.
+ */
+export interface ValidationStageContext {
+    readonly value: unknown;
+    readonly path?: FieldPath;
+    readonly rules: readonly ValidationRule[];
+}
+/**
+ * Output produced by the validation stage.
+ *
+ * Contains all correctness‑related events emitted by the active rules.
+ */
+export interface ValidationStageOutput {
+    readonly events: readonly JaneEvent[];
+}

package/dist/core/shapes/validate.js

@@ -0,0 +1,11 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Validate
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define rule‑driven correctness checks during
+ *                  validation.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

package/dist/core/validators/array/array-max-items.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Array Maximum Items (Array Max Items)
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not exceed a maximum number of
+ *                  items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array does not exceed a maximum number of items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array length is less than or equal to the provided maximum
+ *
+ * Emits:
+ * - array.not.array
+ * - array.too.long
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const arrayMaxItems: (max: number) => ValidationRule;

package/dist/core/validators/array/array-max-items.js

@@ -0,0 +1,42 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Array Maximum Items (Array Max Items)
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not exceed a maximum number of
+ *                  items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validate that an array does not exceed a maximum number of items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array length is less than or equal to the provided maximum
+ *
+ * Emits:
+ * - array.not.array
+ * - array.too.long
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export const arrayMaxItems = (max) => async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (!Array.isArray(value)) {
+        return [
+            validationEvent('error', 'array.not.array', path, `Expected 'array' but received '${structuralType}'.`, `Please provide a valid array.`, { value, expected: 'array', actual: structuralType }),
+        ];
+    }
+    if (value.length > max) {
+        return [
+            validationEvent('error', 'array.too.long', path, `Array length ${value.length} must be ≤ ${max}.`, `Please provide no more than ${max} items.`, { value, expected: `≤ ${max}`, actual: value.length }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/array/array-min-items.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Array Minimum Items (Array Min Items)
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array contains at least a minimum number of
+ *                  items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array contains at least a minimum number of items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array length is greater than or equal to the provided minimum
+ *
+ * Emits:
+ * - array.not.array
+ * - array.too.short
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const arrayMinItems: (min: number) => ValidationRule;

package/dist/core/validators/array/array-min-items.js

@@ -0,0 +1,42 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Array Minimum Items (Array Min Items)
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array contains at least a minimum number of
+ *                  items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validate that an array contains at least a minimum number of items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array length is greater than or equal to the provided minimum
+ *
+ * Emits:
+ * - array.not.array
+ * - array.too.short
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export const arrayMinItems = (min) => async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (!Array.isArray(value)) {
+        return [
+            validationEvent('error', 'array.not.array', path, `Expected 'array' but received '${structuralType}'.`, `Please provide a valid array.`, { value, expected: 'array', actual: structuralType }),
+        ];
+    }
+    if (value.length < min) {
+        return [
+            validationEvent('error', 'array.too.short', path, `Array length ${value.length} must be ≥ ${min}.`, `Please provide at least ${min} items.`, { value, expected: `≥ ${min}`, actual: value.length }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/array/array.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Array
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that a value is structurally an array.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that a value is structurally an array.
+ *
+ * This rule checks:
+ * - The value is an array according to JavaScript semantics
+ *
+ * Emits:
+ * - array.not.array
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const array: ValidationRule;

package/dist/core/validators/array/array.js

@@ -0,0 +1,34 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Array
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that a value is structurally an array.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validate that a value is structurally an array.
+ *
+ * This rule checks:
+ * - The value is an array according to JavaScript semantics
+ *
+ * Emits:
+ * - array.not.array
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export const array = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (!Array.isArray(value)) {
+        return [
+            validationEvent('error', 'array.not.array', path, `Expected 'array' but received '${structuralType}'.`, `Please provide a valid array.`, { value, expected: 'array', actual: structuralType }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/array/excludes.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Excludes
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not include a specific
+ *                  disallowed item.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array does not include a specific disallowed item.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array does not contain the provided item (using Array.prototype.includes)
+ *
+ * Emits:
+ * - array.not.array
+ * - array.has.invalid-value
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const excludes: (item: unknown) => ValidationRule;

package/dist/core/validators/array/excludes.js

@@ -0,0 +1,47 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Excludes
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not include a specific
+ *                  disallowed item.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validate that an array does not include a specific disallowed item.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array does not contain the provided item (using Array.prototype.includes)
+ *
+ * Emits:
+ * - array.not.array
+ * - array.has.invalid-value
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export const excludes = (item) => async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (!Array.isArray(value)) {
+        return [
+            validationEvent('error', 'array.not.array', path, `Expected 'array' but received '${structuralType}'.`, `Please provide a valid array.`, { value, expected: 'array', actual: structuralType }),
+        ];
+    }
+    if (value.includes(item)) {
+        return [
+            validationEvent('error', 'array.has.invalid-value', path, `Array must not include ${safeStringify(item)}.`, `Please remove the disallowed item.`, {
+                value,
+                expected: `exclude ${safeStringify(item)}`,
+                actual: value,
+            }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/array/has-unique-items.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Has Unique Items
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array contains only unique items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array contains only unique items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array does not contain duplicate items (using reference and value equality via Set)
+ *
+ * Emits:
+ * - array.not.array
+ * - array.not.unique
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const hasUniqueItems: ValidationRule;

package/dist/core/validators/array/has-unique-items.js

@@ -0,0 +1,46 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Has Unique Items
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array contains only unique items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validate that an array contains only unique items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array does not contain duplicate items (using reference and value equality via Set)
+ *
+ * Emits:
+ * - array.not.array
+ * - array.not.unique
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export const hasUniqueItems = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (!Array.isArray(value)) {
+        return [
+            validationEvent('error', 'array.not.array', path, `Expected 'array' but received '${structuralType}'.`, `Please provide a valid array.`, { value, expected: 'array', actual: structuralType }),
+        ];
+    }
+    const uniqueSet = new Set(value);
+    if (uniqueSet.size !== value.length) {
+        return [
+            validationEvent('error', 'array.not.unique', path, `Array must contain only unique items.`, `Please remove duplicate items.`, {
+                value,
+                expected: 'unique items',
+                actual: 'duplicates found',
+            }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/array/includes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Includes
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array includes a specific required item.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array includes a specific required item.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array contains the provided item (using Array.prototype.includes)
+ *
+ * Emits:
+ * - array.not.array
+ * - array.is.missing-value
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const includes: (item: unknown) => ValidationRule;

package/dist/core/validators/array/includes.js

@@ -0,0 +1,46 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Includes
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array includes a specific required item.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validate that an array includes a specific required item.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array contains the provided item (using Array.prototype.includes)
+ *
+ * Emits:
+ * - array.not.array
+ * - array.is.missing-value
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export const includes = (item) => async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (!Array.isArray(value)) {
+        return [
+            validationEvent('error', 'array.not.array', path, `Expected 'array' but received '${structuralType}'.`, `Please provide a valid array.`, { value, expected: 'array', actual: structuralType }),
+        ];
+    }
+    if (!value.includes(item)) {
+        return [
+            validationEvent('error', 'array.is.missing-value', path, `Array must include ${safeStringify(item)}.`, `Please include the required item.`, {
+                value,
+                expected: `includes ${safeStringify(item)}`,
+                actual: value,
+            }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/array/items-equal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Items Equal
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array contains exactly the specified
+ *                  number of items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array contains exactly the specified number of items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array length matches the exact required count
+ *
+ * Emits:
+ * - array.not.array
+ * - array.has.invalid-length
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const itemsEqual: (exact: number) => ValidationRule;