@clementine-solutions/jane-io 1.0.1 → 1.0.2

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

@@ -0,0 +1,87 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const bigintMin = (min) => {
+    // The returned function is the actual validator. We attach a
+    // factory marker below so Jane preserves the closure and does
+    // not attempt to serialize the `min` bigint.
+    const rule = async (value, path) => {
+        const structuralType = detectStructuralType(value);
+        // ------------------------------------------------------------
+        // Type check — the input must be a string.
+        // ------------------------------------------------------------
+        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 }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Empty-string check — BigInt("") parses as 0n, which is
+        // rarely what users intend. We treat empty strings as invalid.
+        // ------------------------------------------------------------
+        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 }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Parse check — attempt to convert the string into a BigInt.
+        // Any failure (invalid characters, formatting, etc.) results
+        // in a `bigint.not.bigint` event.
+        // ------------------------------------------------------------
+        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 }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Minimum check — ensure the parsed value is ≥ the provided `min`.
+        // ------------------------------------------------------------
+        if (parsed < min) {
+            return [
+                validationEvent('error', 'bigint.too.small', path, `${safeStringify(value)} must be ≥ ${min}.`, `Please provide a bigint at least ${min}.`, { value, expected: `≥ ${min}`, actual: parsed }),
+            ];
+        }
+        // ------------------------------------------------------------
+        // Valid — return an empty array to indicate success.
+        // ------------------------------------------------------------
+        return [];
+    };
+    // ------------------------------------------------------------
+    // Factory marker — prevents Jane from serializing the rule and
+    // losing the `min` bigint. This ensures the closure is preserved.
+    // ------------------------------------------------------------
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rule.__janeFactory = true;
+    return rule;
+};

package/dist/core/validators/bigint/bigint-negative.js

@@ -0,0 +1,73 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const bigintNegative = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check — the input must be a string.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Empty-string check — BigInt("") parses as 0n, which is
+    // rarely what users intend. We treat empty strings as invalid.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Parse check — attempt to convert the string into a BigInt.
+    // Any failure (invalid characters, formatting, etc.) results
+    // in a `bigint.not.bigint` event.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Negativity check — ensure the parsed value is strictly < 0.
+    // ------------------------------------------------------------
+    if (parsed >= 0n) {
+        return [
+            validationEvent('error', 'bigint.not.negative', path, `${safeStringify(value)} must be < 0.`, `Please provide a negative bigint.`, { value, expected: '< 0', actual: parsed }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid — return an empty array to indicate success.
+    // ------------------------------------------------------------
+    return [];
+};

package/dist/core/validators/bigint/bigint-non-negative.js

@@ -0,0 +1,72 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const bigintNonNegative = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check — the input must be a string.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Empty-string check — BigInt("") parses as 0n, which is
+    // rarely what users intend. We treat empty strings as invalid.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Parse check — attempt to convert the string into a BigInt.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Non-negative check — ensure the parsed value is ≥ 0.
+    // ------------------------------------------------------------
+    if (parsed < 0n) {
+        return [
+            validationEvent('error', 'bigint.not.non-negative', path, `${safeStringify(value)} must be ≥ 0.`, `Please provide zero or a positive bigint.`, { value, expected: '≥ 0', actual: parsed }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid — return an empty array to indicate success.
+    // ------------------------------------------------------------
+    return [];
+};

package/dist/core/validators/bigint/bigint-non-positive.js

@@ -0,0 +1,72 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * 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 const bigintNonPositive = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check — the input must be a string.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Empty-string check — BigInt("") parses as 0n, which is
+    // rarely what users intend. We treat empty strings as invalid.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Parse check — attempt to convert the string into a BigInt.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Non-positive check — ensure the parsed value is ≤ 0.
+    // ------------------------------------------------------------
+    if (parsed > 0n) {
+        return [
+            validationEvent('error', 'bigint.not.non-positive', path, `${safeStringify(value)} must be ≤ 0.`, `Please provide zero or a negative bigint.`, { value, expected: '≤ 0', actual: parsed }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid — return an empty array to indicate success.
+    // ------------------------------------------------------------
+    return [];
+};

package/dist/core/validators/bigint/bigint-positive.js

@@ -0,0 +1,72 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint Positive
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a string representing a BigInt that is
+ *                  strictly greater than zero.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a string representing a BigInt that is strictly greater
+ * than 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.positive`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const bigintPositive = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check — the input must be a string.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Empty-string check — BigInt("") parses as 0n, which is
+    // rarely what users intend. We treat empty strings as invalid.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Parse check — attempt to convert the string into a BigInt.
+    // ------------------------------------------------------------
+    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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Positivity check — ensure the parsed value is strictly > 0.
+    // ------------------------------------------------------------
+    if (parsed <= 0n) {
+        return [
+            validationEvent('error', 'bigint.not.positive', path, `${safeStringify(value)} must be > 0.`, `Please provide a positive bigint.`, { value, expected: '> 0', actual: parsed }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid — return an empty array to indicate success.
+    // ------------------------------------------------------------
+    return [];
+};