@clementine-solutions/jane-io 1.0.0 → 1.0.1

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/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/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-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.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/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/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/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/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;

package/dist/core/validators/array/no-empty-string-items.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | No Empty String Items
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not contain empty string items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array does not contain empty string items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - No element in the array is an empty string ("")
+ *
+ * Emits:
+ * - array.not.array
+ * - array.has.empty-strings
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const noEmptyStringItems: ValidationRule;

package/dist/core/validators/array/no-null-items.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | No Null Items
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not contain null items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array does not contain null items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - No element in the array is strictly equal to null
+ *
+ * Emits:
+ * - array.not.array
+ * - array.has.null-items
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const noNullItems: ValidationRule;

package/dist/core/validators/array/no-undefined-items.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | No Undefined Items
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not contain undefined items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array does not contain undefined items.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - No element in the array is strictly equal to undefined
+ *
+ * Emits:
+ * - array.not.array
+ * - array.has.undefined-items
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const noUndefinedItems: ValidationRule;

package/dist/core/validators/array/non-empty-array.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Non-Empty Array
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array is not empty.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array is not empty.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - The array contains at least one item
+ *
+ * Emits:
+ * - array.not.array
+ * - array.is.empty
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const nonEmptyArray: ValidationRule;

package/dist/core/validators/array/not-sparse.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Not Sparse
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not contain empty (sparse)
+ *                  slots.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validate that an array does not contain empty (sparse) slots.
+ *
+ * This rule checks:
+ * - The value is structurally an array
+ * - Every index from 0 to length - 1 exists (no holes)
+ *
+ * Emits:
+ * - array.not.array
+ * - array.is.sparse
+ *
+ * This rule is async-compatible and returns a readonly array of JaneEvent objects.
+ */
+export declare const notSparse: ValidationRule;

package/dist/core/validators/bigint/bigint-equals.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint Equals
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates that the value is a string representing a BigInt
+ *                  equal to `target`.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validates that the value is a string representing a BigInt equal to `target`.
+ *
+ * - Non‑string values emit `bigint.not.string`.
+ * - Strings that cannot be parsed as BigInt emit `bigint.not.bigint`.
+ * - Parsed BigInt values that do not equal `target` emit `bigint.not.equal`.
+ * - Returns an empty array when the value is valid.
+ *
+ * This rule is pure, total, async‑compatible, and returns a readonly array of
+ * JaneEvent objects. It preserves the provided path and supports userMessage
+ * overrides applied at the pipeline level.
+ */
+export declare const bigintEquals: (target: bigint) => ValidationRule;

package/dist/core/validators/bigint/bigint-max.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint Maximum (Bigint Max)
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates that the value is a string representing a BigInt
+ *                  less than or equal to the provided `max`.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Validates that the value is a string representing a BigInt less than or
+ * equal to the provided `max`.
+ *
+ * - Non‑string values emit `bigint.not.string`.
+ * - Empty strings and non‑parseable strings emit `bigint.not.bigint`.
+ * - Parsed BigInt values greater than `max` emit `bigint.too.large`.
+ * - Returns an empty array when the value is valid.
+ *
+ * This rule is pure, total, async‑compatible, and returns a readonly array of
+ * JaneEvent objects. It preserves the provided path and supports userMessage
+ * overrides applied at the pipeline level.
+ */
+export declare const bigintMax: (max: bigint) => ValidationRule;

package/dist/core/validators/bigint/bigint-min.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint Minimum (Bigint Min)
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a string representing a BigInt that is
+ *                  greater than or equal to the provided `min` value.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Ensures the input is a string representing a BigInt that is
+ * greater than or equal to the provided `min` value.
+ *
+ * This validator follows Jane’s standard BigInt conventions:
+ * - The input must be a string. Non‑string values emit `bigint.not.string`.
+ * - Empty strings and non‑parseable strings emit `bigint.not.bigint`.
+ * - Parsed BigInt values smaller than `min` emit `bigint.too.small`.
+ *
+ * The rule is pure, total, async‑compatible, and preserves the
+ * provided path. It also supports userMessage overrides applied
+ * at the pipeline level.
+ */
+export declare const bigintMin: (min: bigint) => ValidationRule;

package/dist/core/validators/bigint/bigint-negative.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint Negative
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a string representing a negative
+ *                  BigInt value.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Ensures the input is a string representing a negative BigInt value.
+ *
+ * This validator follows Jane’s standard BigInt conventions:
+ * - The input must be a string. Non‑string values emit `bigint.not.string`.
+ * - Empty strings and non‑parseable strings emit `bigint.not.bigint`.
+ * - Parsed BigInt values greater than or equal to 0 emit `bigint.not.negative`.
+ *
+ * The rule is pure, total, async‑compatible, and preserves the provided path.
+ * It also supports userMessage overrides applied at the pipeline level.
+ */
+export declare const bigintNegative: ValidationRule;

package/dist/core/validators/bigint/bigint-non-negative.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint Non-Negative
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a string representing a BigInt that is
+ *                  greater than or equal to zero.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Ensures the input is a string representing a BigInt that is greater than or
+ * equal to zero.
+ *
+ * - Non-string values emit `bigint.not.string`.
+ * - Empty strings and non-parseable strings emit `bigint.not.bigint`.
+ * - Parsed BigInt values < 0 emit `bigint.not.non-negative`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export declare const bigintNonNegative: ValidationRule;

package/dist/core/validators/bigint/bigint-non-positive.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint Non-Positive
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a string representing a BigInt that is
+ *                  less than or equal to zero.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Ensures the input is a string representing a BigInt that is less than or
+ * equal to zero.
+ *
+ * - Non-string values emit `bigint.not.string`.
+ * - Empty strings and non-parseable strings emit `bigint.not.bigint`.
+ * - Parsed BigInt values > 0 emit `bigint.not.non-positive`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export declare const bigintNonPositive: ValidationRule;