@clementine-solutions/jane-io 1.0.0 → 1.0.2

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

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.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 type { ValidationRule } from '../../shapes';
+/**
+ * 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 declare const bigintPositive: ValidationRule;

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 [];
+};

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

@@ -0,0 +1,25 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint Safe
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a string representing a BigInt that
+ *                  falls within JavaScript’s safe integer range.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Ensures the input is a string representing a BigInt that falls
+ * within JavaScript’s safe integer range (Number.MIN_SAFE_INTEGER
+ * through Number.MAX_SAFE_INTEGER).
+ *
+ * - Non-string values emit `bigint.not.string`.
+ * - Empty strings and non-parseable strings emit `bigint.not.bigint`.
+ * - Parsed BigInt values outside the safe range emit `bigint.not.safe`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export declare const bigintSafe: ValidationRule;

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

@@ -0,0 +1,75 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint Safe
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a string representing a BigInt that
+ *                  falls within JavaScript’s safe integer range.
+ * @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 falls
+ * within JavaScript’s safe integer range (Number.MIN_SAFE_INTEGER
+ * through Number.MAX_SAFE_INTEGER).
+ *
+ * - Non-string values emit `bigint.not.string`.
+ * - Empty strings and non-parseable strings emit `bigint.not.bigint`.
+ * - Parsed BigInt values outside the safe range emit `bigint.not.safe`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const bigintSafe = 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 }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Safe-range check — ensure MIN_SAFE ≤ parsed ≤ MAX_SAFE.
+    // ------------------------------------------------------------
+    const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+    const minSafe = BigInt(Number.MIN_SAFE_INTEGER);
+    if (parsed > maxSafe || parsed < minSafe) {
+        return [
+            validationEvent('error', 'bigint.not.safe', path, `${safeStringify(value)} exceeds JavaScript’s safe integer range.`, `Please provide a bigint within safe bounds.`, { value, expected: `${minSafe}–${maxSafe}`, actual: parsed }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid — return an empty array to indicate success.
+    // ------------------------------------------------------------
+    return [];
+};

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

@@ -0,0 +1,20 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a native JavaScript BigInt value.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ValidationRule } from '../../shapes';
+/**
+ * Ensures the input is a native JavaScript BigInt value.
+ *
+ * - Non-bigint values emit `bigint.not.bigint`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export declare const bigint: ValidationRule;

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

@@ -0,0 +1,38 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Bigint
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures the input is a native JavaScript BigInt value.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures the input is a native JavaScript BigInt value.
+ *
+ * - Non-bigint values emit `bigint.not.bigint`.
+ *
+ * This rule is pure, total, async-compatible, and preserves the
+ * provided path. It supports userMessage overrides applied at the
+ * pipeline level.
+ */
+export const bigint = (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check — the input must be a native BigInt.
+    // ------------------------------------------------------------
+    if (typeof value !== 'string') {
+        return [
+            validationEvent('error', 'bigint.not.string', path, `Expected 'bigint' but received '${structuralType}'.`, `Please provide a valid bigint.`, { value, expected: 'bigint', actual: structuralType }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid — return an empty array to indicate success.
+    // ------------------------------------------------------------
+    return [];
+};