@clementine-solutions/jane-io 1.0.0 → 1.0.2

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

@@ -0,0 +1,42 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const itemsEqual = (exact) => 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 !== exact) {
+        return [
+            validationEvent('error', 'array.has.invalid-length', path, `Array length ${value.length} must be exactly ${exact}.`, `Please provide exactly ${exact} items.`, { value, expected: exact, actual: value.length }),
+        ];
+    }
+    return [];
+};

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-empty-string-items.js

@@ -0,0 +1,46 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const noEmptyStringItems = 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 containsEmptyString = value.some((item) => item === '');
+    if (containsEmptyString) {
+        return [
+            validationEvent('error', 'array.has.empty-strings', path, `Array must not contain empty strings.`, `Please remove empty string items.`, {
+                value,
+                expected: 'no empty strings',
+                actual: 'contains empty string',
+            }),
+        ];
+    }
+    return [];
+};

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-null-items.js

@@ -0,0 +1,46 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | No Null Items
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not contain null items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const noNullItems = 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 containsNull = value.some((item) => item === null);
+    if (containsNull) {
+        return [
+            validationEvent('error', 'array.has.null-items', path, `Array must not contain null values.`, `Please remove null items.`, {
+                value,
+                expected: 'no null items',
+                actual: 'contains null',
+            }),
+        ];
+    }
+    return [];
+};

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/no-undefined-items.js

@@ -0,0 +1,45 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | No Undefined Items
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not contain undefined items.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const noUndefinedItems = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (!Array.isArray(value)) {
+        return [
+            validationEvent('error', 'array.not.array', path, `Expected 'array' but received '${type}'.`, `Please provide a valid array.`, { value, expected: 'array', actual: type }),
+        ];
+    }
+    for (let i = 0; i < value.length; i++) {
+        const isHole = !(i in value);
+        const isUndefined = value[i] === undefined;
+        if (isHole || isUndefined) {
+            return [
+                validationEvent('error', 'array.has.undefined-items', path, `Array must not contain undefined values.`, `Please remove undefined items.`, { value, expected: 'no undefined items', actual: 'contains undefined' }),
+            ];
+        }
+    }
+    return [];
+};

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/non-empty-array.js

@@ -0,0 +1,45 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Non-Empty Array
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array is not empty.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const nonEmptyArray = 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 === 0) {
+        return [
+            validationEvent('error', 'array.is.empty', path, `Array must not be empty.`, `Please provide at least one item.`, {
+                value,
+                expected: 'non-empty array',
+                actual: value.length,
+            }),
+        ];
+    }
+    return [];
+};

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/array/not-sparse.js

@@ -0,0 +1,44 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Not Sparse
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validate that an array does not contain empty (sparse)
+ *                  slots.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const notSparse = 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 }),
+        ];
+    }
+    for (let index = 0; index < value.length; index++) {
+        if (!(index in value)) {
+            return [
+                validationEvent('error', 'array.is.sparse', path, `Array must not contain empty slots.`, `Please remove empty array positions.`, { value, expected: 'no holes', actual: 'sparse array' }),
+            ];
+        }
+    }
+    return [];
+};

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-equals.js

@@ -0,0 +1,57 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const bigintEquals = (target) => async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    if (typeof value !== 'string') {
+        return [
+            validationEvent('error', 'bigint.not.string', path, `Expected 'string' but received '${structuralType}'.`, `Please provide a valid bigint string.`, { value, expected: 'string', actual: structuralType }),
+        ];
+    }
+    // Explicit empty-string check
+    if (value.length === 0) {
+        return [
+            validationEvent('error', 'bigint.not.bigint', path, `${safeStringify(value)} is not a valid bigint literal.`, `Please provide a valid bigint string.`, { value, expected: 'bigint literal', actual: value }),
+        ];
+    }
+    let parsed;
+    try {
+        parsed = BigInt(value);
+    }
+    catch {
+        return [
+            validationEvent('error', 'bigint.not.bigint', path, `${safeStringify(value)} is not a valid bigint literal.`, `Please provide a valid bigint string.`, { value, expected: 'bigint literal', actual: value }),
+        ];
+    }
+    if (parsed !== target) {
+        return [
+            validationEvent('error', 'bigint.not.equal', path, `${safeStringify(value)} must equal ${target}.`, `Please provide the correct bigint value.`, { value, expected: target, actual: parsed }),
+        ];
+    }
+    return [];
+};

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-max.js

@@ -0,0 +1,63 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const bigintMax = (max) => {
+    const rule = async (value, path) => {
+        const structuralType = detectStructuralType(value);
+        if (typeof value !== 'string') {
+            return [
+                validationEvent('error', 'bigint.not.string', path, `Expected 'string' but received '${structuralType}'.`, `Please provide a valid bigint string.`, { value, expected: 'string', actual: structuralType }),
+            ];
+        }
+        if (value.length === 0) {
+            return [
+                validationEvent('error', 'bigint.not.bigint', path, `${safeStringify(value)} is not a valid bigint literal.`, `Please provide a valid bigint string.`, { value, expected: 'bigint literal', actual: value }),
+            ];
+        }
+        let parsed;
+        try {
+            parsed = BigInt(value);
+        }
+        catch {
+            return [
+                validationEvent('error', 'bigint.not.bigint', path, `${safeStringify(value)} is not a valid bigint literal.`, `Please provide a valid bigint string.`, { value, expected: 'bigint literal', actual: value }),
+            ];
+        }
+        if (parsed > max) {
+            return [
+                validationEvent('error', 'bigint.too.large', path, `${safeStringify(value)} must be ≤ ${max}.`, `Please provide a value less than or equal to ${max}.`, { max, actual: parsed }),
+            ];
+        }
+        return [];
+    };
+    // Prevent Jane from serializing the rule and losing the bigint
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rule.__janeFactory = true;
+    return rule;
+};

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;