@clementine-solutions/jane-io 1.0.1 → 1.0.2

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

package/dist/core/validators/boolean/boolean.js

@@ -0,0 +1,39 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Boolean
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates that the value is a boolean.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates that the value is a boolean.
+ *
+ * - Non‑boolean values emit `boolean.not.boolean`.
+ * - Returns an empty array when the value is a valid boolean.
+ *
+ * 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 boolean = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check
+    // ------------------------------------------------------------
+    if (typeof value !== 'boolean') {
+        return [
+            validationEvent('error', 'boolean.not.boolean', path, `Expected 'boolean' but received '${structuralType}'.`, `Please enter true or false.`, { value, expected: 'boolean', actual: structuralType }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid
+    // ------------------------------------------------------------
+    return [];
+};

package/dist/core/validators/boolean/is-false.js

@@ -0,0 +1,48 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is False
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates that the value is the boolean literal `false`.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates that the value is the boolean literal `false`.
+ *
+ * - Non‑boolean values emit `boolean.not.boolean`.
+ * - The boolean literal `true` emits `boolean.not.false`.
+ * - Returns an empty array when the value is exactly `false`.
+ *
+ * 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 isFalse = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check
+    // ------------------------------------------------------------
+    if (typeof value !== 'boolean') {
+        return [
+            validationEvent('error', 'boolean.not.boolean', path, `Expected 'boolean' but received '${structuralType}'.`, `Please enter true or false.`, { value, expected: 'boolean', actual: structuralType }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Literal false check
+    // ------------------------------------------------------------
+    if (value !== false) {
+        return [
+            validationEvent('error', 'boolean.not.false', path, `Value must be false.`, `Please enter false.`, { value, expected: false, actual: value }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid
+    // ------------------------------------------------------------
+    return [];
+};

package/dist/core/validators/boolean/is-true.js

@@ -0,0 +1,48 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is True
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates that the value is the boolean literal `true`.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates that the value is the boolean literal `true`.
+ *
+ * - Non‑boolean values emit `boolean.not.boolean`.
+ * - The boolean literal `false` emits `boolean.not.true`.
+ * - Returns an empty array when the value is exactly `true`.
+ *
+ * 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 isTrue = async (value, path) => {
+    const structuralType = detectStructuralType(value);
+    // ------------------------------------------------------------
+    // Type check
+    // ------------------------------------------------------------
+    if (typeof value !== 'boolean') {
+        return [
+            validationEvent('error', 'boolean.not.boolean', path, `Expected 'boolean' but received '${structuralType}'.`, `Please enter true or false.`, { value, expected: 'boolean', actual: structuralType }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Literal true check
+    // ------------------------------------------------------------
+    if (value !== true) {
+        return [
+            validationEvent('error', 'boolean.not.true', path, `Value must be true.`, `Please enter true.`, { value, expected: true, actual: value }),
+        ];
+    }
+    // ------------------------------------------------------------
+    // Valid
+    // ------------------------------------------------------------
+    return [];
+};

package/dist/core/validators/common/is-country-code.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Country Code
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates ISO‑3166‑1 alpha‑2 country codes.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates ISO‑3166‑1 alpha‑2 country codes.
+ *
+ * Country codes must be exactly two uppercase letters. This helps ensure
+ * consistent, standards‑aligned identifiers for geographic data.
+ */
+export const isCountryCode = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'string' but received '${type}'.`, `Please provide a valid country code.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    const re = /^[A-Z]{2}$/;
+    if (!re.test(value)) {
+        return [
+            validationEvent('error', 'string.not.country-code', path, `${safeStringify(value)} is not a valid ISO-3166-1 alpha-2 code.`, `Please provide a valid country code.`, { value }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/common/is-currency-code.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Country Code
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates ISO‑4217 currency codes.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+import { safeStringify } from '../../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates ISO‑4217 currency codes.
+ *
+ * Currency codes must be three uppercase letters. This prevents malformed or
+ * non‑standard currency identifiers from entering downstream systems.
+ */
+export const isCurrencyCode = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'string' but received '${type}'.`, `Please provide a valid currency code.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    const re = /^[A-Z]{3}$/;
+    if (!re.test(value)) {
+        return [
+            validationEvent('error', 'string.not.currency-code', path, `${safeStringify(value)} is not a valid ISO‑4217 currency code.`, `Please provide a valid currency code.`, { value }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/common/is-email-strict.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Email Strict
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates strict RFC‑style email addresses.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates strict RFC‑style email addresses.
+ *
+ * Enforces a detailed pattern for both the local part and domain, catching
+ * malformed or ambiguous email strings before they propagate further.
+ */
+export const isEmailStrict = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'string' but received '${type}'.`, `Please provide a valid email address.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    const re = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)+$/;
+    if (!re.test(value)) {
+        return [
+            validationEvent('error', 'string.not.strict-email', path, `${safeStringify(value)} is not a valid RFC‑style email address.`, `Please provide a valid email address.`, { value }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/common/is-email.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Email
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates general‑purpose email addresses.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates general‑purpose email addresses.
+ *
+ * Uses a permissive but reliable pattern suitable for everyday user input,
+ * ensuring the value resembles a conventional email address.
+ */
+export const isEmail = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'string' but received '${type}'.`, `Please provide a valid email address.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    const re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!re.test(value)) {
+        return [
+            validationEvent('error', 'string.not.email', path, `${safeStringify(value)} is not a valid email address.`, `Please provide a valid email address.`, { value }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/common/is-ip.js

@@ -0,0 +1,37 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is IP (v4 and v6)
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates IPv4 and IPv6 addresses.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates IPv4 and IPv6 addresses.
+ *
+ * Ensures the string matches canonical patterns for either protocol, helping
+ * prevent malformed network identifiers from entering the system.
+ */
+export const isIp = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'string' but received '${type}'.`, `Please provide a valid IP address.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    const ipv4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+    const ipv6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|::1|::)$/;
+    if (!ipv4.test(value) && !ipv6.test(value)) {
+        return [
+            validationEvent('error', 'string.not.ip', path, `${safeStringify(value)} is not a valid IPv4 or IPv6 address.`, `Please provide a valid IP address.`, { value }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/common/is-phone-strict.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Phone Strict
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates strict E.164 international phone numbers.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates strict E.164 international phone numbers.
+ *
+ * Requires a leading plus sign and 8–15 digits, ensuring globally portable,
+ * unambiguous phone identifiers.
+ */
+export const isPhoneStrict = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'string' but received '${type}'.`, `Please provide a valid phone number.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    const re = /^\+[1-9]\d{7,14}$/;
+    if (!re.test(value)) {
+        return [
+            validationEvent('error', 'string.not.strict-phone', path, `${safeStringify(value)} is not a valid E.164 phone number.`, `Please provide a valid international phone number.`, { value }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/common/is-phone.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Phone
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates loosely formatted phone numbers.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates loosely formatted phone numbers.
+ *
+ * Extracts digits and enforces a minimum length, providing a flexible check
+ * suitable for user‑entered phone fields.
+ */
+export const isPhone = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'string' but received '${type}'.`, `Please provide a valid phone number.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    const digits = value.replace(/\D/g, '');
+    if (digits.length < 7) {
+        return [
+            validationEvent('error', 'string.not.phone', path, `${safeStringify(value)} is not a valid phone number.`, `Please provide a valid phone number.`, { value }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/common/is-port.js

@@ -0,0 +1,35 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Port
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates TCP/UDP port numbers.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates TCP/UDP port numbers.
+ *
+ * Ports must be integers between 0 and 65535. This prevents invalid or
+ * out‑of‑range port values from being accepted.
+ */
+export const isPort = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'number') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'number' but received '${type}'.`, `Please provide a valid port number.`, { value, expected: 'number', actual: type }),
+        ];
+    }
+    const n = value;
+    if (!Number.isInteger(n) || n < 0 || n > 65535) {
+        return [
+            validationEvent('error', 'number.not.in-port-range', path, `Port must be an integer between 0 and 65535.`, `Please provide a valid port number.`, { value, min: 0, max: 65535 }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/common/is-postal-code.js

@@ -0,0 +1,36 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is Postal Code
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates alphanumeric postal codes.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates alphanumeric postal codes.
+ *
+ * Accepts letters, digits, spaces, and hyphens within a reasonable length
+ * range, supporting a wide variety of international postal formats.
+ */
+export const isPostalCode = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'type.not.valid', path, `Expected 'string' but received '${type}'.`, `Please provide a valid postal code.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    const re = /^[A-Za-z0-9 \\-]{3,12}$/;
+    if (!re.test(value)) {
+        return [
+            validationEvent('error', 'string.not.postal-code', path, `${safeStringify(value)} is not a valid postal code.`, `Please provide a valid postal code.`, { value }),
+        ];
+    }
+    return [];
+};

package/dist/core/validators/common/is-url.js

@@ -0,0 +1,38 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Validators | Is URL
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates URLs using the WHATWG URL parser.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { validationEvent } from '../../pipeline';
+import { safeStringify } from '../../common';
+import { detectStructuralType } from '../../pipeline/scan';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates URLs using the WHATWG URL parser.
+ *
+ * Ensures the string is a syntactically valid absolute URL, preventing malformed
+ * or incomplete URL values from being accepted.
+ */
+export const isUrl = async (value, path) => {
+    const type = detectStructuralType(value);
+    if (type !== 'string') {
+        return [
+            validationEvent('error', 'string.not.string', path, `Expected 'string' but received '${type}'.`, `Please provide a valid URL.`, { value, expected: 'string', actual: type }),
+        ];
+    }
+    try {
+        new URL(value);
+        return [];
+    }
+    catch {
+        return [
+            validationEvent('error', 'string.not.url', path, `${safeStringify(value)} is not a valid URL.`, `Please provide a valid URL.`, { value }),
+        ];
+    }
+};