@versionzero/schema 1.0.0

package/src/constants.js

@@ -0,0 +1 @@
+export const EMPTY = Symbol('EMPTY');

package/src/core-library/index.js

@@ -0,0 +1,32 @@
+import { ANY_SCHEMA } from './schemas/any-schema.js';
+import { STRING_SCHEMA } from './schemas/string-schema.js';
+import { NUMBER_SCHEMA } from './schemas/number-schema.js';
+import { BOOLEAN_SCHEMA } from './schemas/boolean-schema.js';
+import { OBJECT_SCHEMA } from './schemas/object-schema.js';
+import { ARRAY_SCHEMA } from './schemas/array-schema.js';
+import { DATE_SCHEMA } from './schemas/date-schema.js';
+import { FUNCTION_SCHEMA } from './schemas/function-schema.js';
+import { ROOT_SCHEMA } from './schemas/root-schema.js';
+import { getBuiltinProcessors } from './processors/index.js';
+
+/** @import { SchemaResolver } from '../schema-resolver.js' */
+
+/**
+ * @param {SchemaResolver} resolver
+ * @param {object} options
+ */
+export default function coreLibrary(resolver, options) {
+  resolver.registerSchema('root-schema', ROOT_SCHEMA);
+  resolver.registerSchema('any', ANY_SCHEMA);
+  resolver.registerSchema('string', STRING_SCHEMA);
+  resolver.registerSchema('number', NUMBER_SCHEMA);
+  resolver.registerSchema('boolean', BOOLEAN_SCHEMA);
+  resolver.registerSchema('object', OBJECT_SCHEMA);
+  resolver.registerSchema('array', ARRAY_SCHEMA);
+  resolver.registerSchema('date', DATE_SCHEMA);
+  resolver.registerSchema('function', FUNCTION_SCHEMA);
+
+  for (const definition of getBuiltinProcessors()) {
+    resolver.registerValueProcessorDefinition(definition);
+  }
+}

package/src/core-library/processors/aggregation-operators.js

@@ -0,0 +1,75 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $sum
+ *
+ * Returns the sum of an array of numbers. Returns `0` for an empty array.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const SUM_OPERATOR = {
+  keyword: 'sum',
+
+  process: (value, _target, location) => {
+    if (!Array.isArray(value)) {
+      throw new ConstraintError(`$sum requires an array, got ${formatValue(value)}`, {location});
+    }
+    let sum = 0;
+    for (let i = 0; i < value.length; i++) {
+      if (typeof value[i] !== 'number' || !Number.isFinite(value[i])) {
+        throw new ConstraintError(`$sum requires an array of finite numbers, got ${formatValue(value[i])} at index ${i}`, {location});
+      }
+      sum += value[i];
+    }
+    return sum;
+  }
+};
+
+/**
+ * ## $min
+ *
+ * Returns the minimum value from an array of numbers. Returns `undefined` for an empty array.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const MIN_OPERATOR = {
+  keyword: 'min',
+
+  process: (value, _target, location) => {
+    if (!Array.isArray(value)) {
+      throw new ConstraintError(`$min requires an array, got ${formatValue(value)}`, {location});
+    }
+    if (value.length === 0) return undefined;
+    for (let i = 0; i < value.length; i++) {
+      if (typeof value[i] !== 'number' || !Number.isFinite(value[i])) {
+        throw new ConstraintError(`$min requires an array of finite numbers, got ${formatValue(value[i])} at index ${i}`, {location});
+      }
+    }
+    return Math.min(...value);
+  }
+};
+
+/**
+ * ## $max
+ *
+ * Returns the maximum value from an array of numbers. Returns `undefined` for an empty array.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const MAX_OPERATOR = {
+  keyword: 'max',
+
+  process: (value, _target, location) => {
+    if (!Array.isArray(value)) {
+      throw new ConstraintError(`$max requires an array, got ${formatValue(value)}`, {location});
+    }
+    if (value.length === 0) return undefined;
+    for (let i = 0; i < value.length; i++) {
+      if (typeof value[i] !== 'number' || !Number.isFinite(value[i])) {
+        throw new ConstraintError(`$max requires an array of finite numbers, got ${formatValue(value[i])} at index ${i}`, {location});
+      }
+    }
+    return Math.max(...value);
+  }
+};

package/src/core-library/processors/alpha-constraint.js

@@ -0,0 +1,20 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $alpha
+ *
+ * Validates that a string contains only alphabetic characters (a-z, A-Z).
+ * No spaces, numbers, punctuation, or special characters are allowed.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const ALPHA_CONSTRAINT = {
+  keyword: 'alpha',
+  process: (value) => {
+    const alphaRegex = /^[a-zA-Z]+$/;
+    if (!alphaRegex.test(value)) {
+      throw new ConstraintError('Must contain only letters');
+    }
+    return value;
+  }
+};

package/src/core-library/processors/alphanum-constraint.js

@@ -0,0 +1,20 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $alphanum
+ *
+ * Validates that a string contains only alphanumeric characters (A-Z, a-z, 0-9).
+ * No spaces, punctuation, or special characters are allowed.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const ALPHANUM_CONSTRAINT = {
+  keyword: 'alphanum',
+  process: (value) => {
+    const alphanumRegex = /^[a-zA-Z0-9]+$/;
+    if (!alphanumRegex.test(value)) {
+      throw new ConstraintError('Must contain only alphanumeric characters');
+    }
+    return value;
+  }
+};

package/src/core-library/processors/array-operator.js

@@ -0,0 +1,51 @@
+import { parse } from '../../helpers/stringify.js';
+import { EMPTY } from '../../constants.js';
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $array
+ *
+ * Attempt to normalize the input value as an array.
+ *
+ * If the input value is "*", the array will expand to the "values" option defined in the current schema.
+ *
+ * See `$is-array` for strict array validation.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const ARRAY_OPERATOR = {
+  keyword: 'array',
+
+  process: (value, _, location) => {
+    if (value === EMPTY) {
+      value = [];
+    }
+    else if (value === '*') {
+      const values = location?.schema.getPropertySchema('*')?.values;
+      if (values !== undefined) {
+        value = [...values];
+      }
+      else {
+        throw new ConstraintError('Schema must define values in order to expand wildcard array');
+      }
+    }
+    if (typeof value === 'string') {
+      value = value.trim();
+      if (value.length > 0 && value[0] === '[' && value[value.length - 1] === ']') {
+        try {
+          value = parse(value);
+        }
+        catch (error) {
+          throw new ConstraintError(`Invalid input string for array: ${value}`);
+        }
+      }
+      else {
+        value = value.split(',').map(s => s.trim()).filter(s => s.length > 0);
+      }
+    }
+    if (Array.isArray(value)) {
+      return value;
+    }
+    throw new ConstraintError(`Invalid input for array: ${value}`)
+  }
+};

package/src/core-library/processors/assert-constraint.js

@@ -0,0 +1,75 @@
+
+import { ValueProcessor } from "../../value-processor/value-processor.js";
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { ConditionalExecutor } from '../../executor/conditional-executor.js';
+import { Executor } from '../../executor/executor.js';
+import { ConstraintError, SchemaError } from '../../errors.js';
+
+/**
+ * ## $assert
+ *
+ * Require that the provided processor returns a truthy value; return original input.
+ * Throws a constraint exception if not truthy.
+ *
+ * May be used inline in a pipeline without parameters, or can have a single processor argument.
+ *
+ * ### Parameters
+ * - `processor` (ProcessorSpec, optional): Processor specification to check for truthiness.
+ *   If omitted, the input value itself is checked.
+ *
+ * ### Example
+ * ```js
+ * // Require the input value itself to be truthy
+ * new Schema('any').validator('$assert')
+ *
+ * // Assert that a referenced sibling field has a truthy value
+ * new Schema('object', {
+ *   enabled: new Schema('boolean'),
+ *   config: new Schema('object').validator({$assert: {$reference: 'enabled'}}),
+ * })
+ *
+ * // Assert that a custom function returns true
+ * new Schema('string').validator({$assert: (value) => value.startsWith('https://')})
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const ASSERT_CONSTRAINT = {
+  keyword: 'assert',
+  build: (args) => {
+
+    /** @type {ValueProcessor|undefined} */
+    let processor;
+    if (Array.isArray(args)) {
+      if (args.length === 1) {
+        processor = args[0];
+      }
+      else if (args.length === 0) {
+        processor = new ComposedValueProcessor(new Executor(), []);
+      }
+      else {
+        throw new SchemaError('$assert requires a single processor argument');
+      }
+    }
+    else if (typeof args === 'object') {
+      processor = args.processor;
+    }
+    if (!(processor instanceof ValueProcessor)) {
+      throw new SchemaError('$assert requires a processor argument');
+    }
+
+    const spec = args.length === 0? '$assert' : {'$assert': processor.spec};
+    const description = processor.description;
+
+    return new ComposedValueProcessor(
+      new ConditionalExecutor(processor,
+        { failure: (error) => {
+          if (error instanceof ConstraintError) {
+            throw error;
+          }
+          throw new ConstraintError('Processed value was not truthy', {cause: error}); } },
+        [ConditionalExecutor.CHECK_TRUTHY, ConditionalExecutor.PASS_ERROR]
+      ),
+      spec, description);
+  }
+};

package/src/core-library/processors/base64-constraint.js

@@ -0,0 +1,26 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $base64
+ *
+ * Validates that a string is properly formatted Base64 encoded data.
+ * Checks for valid Base64 character set (A-Z, a-z, 0-9, +, /) and proper
+ * padding with equals signs. If padding is present, the total length must
+ * be a multiple of 4.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const BASE64_CONSTRAINT = {
+  keyword: 'base64',
+  process: (value) => {
+    const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+    if (!base64Regex.test(value)) {
+      throw new ConstraintError('Invalid base64 format');
+    }
+    // If there's padding, length must be multiple of 4
+    if (value.includes('=') && value.length % 4 !== 0) {
+      throw new ConstraintError('Invalid base64 format');
+    }
+    return value;
+  }
+};

package/src/core-library/processors/camel-case-operator.js

@@ -0,0 +1,24 @@
+import { toCamelCase } from '../../helpers/case.js';
+
+/**
+ * ## $camel-case
+ *
+ * Converts a string value to camelCase format. Words are identified by spaces,
+ * hyphens, underscores, or case changes. The first letter is lowercased, and
+ * subsequent words are capitalized with no separators.
+ * Safe to use in normalize phase (non-throwing).
+ *
+ * **Input examples**:
+ * - `"hello world"` → **Output**: `"helloWorld"`
+ * - `"foo-bar-baz"` → **Output**: `"fooBarBaz"`
+ * - `"user_name_id"` → **Output**: `"userNameId"`
+ * - `"HTTPSConnection"` → **Output**: `"httpsConnection"`
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const CAMEL_CASE_OPERATOR = {
+  keyword: 'camel-case',
+  process: (value) => {
+    return toCamelCase(String(value));
+  }
+};

package/src/core-library/processors/capitalize-operator.js

@@ -0,0 +1,16 @@
+import { toCapitalize } from '../../helpers/case.js';
+
+/**
+ * ## $capitalize
+ *
+ * Capitalizes the first letter of each word, separated by spaces. Words are split on
+ * non-alphanumeric boundaries (spaces, hyphens, underscores, camelCase transitions, etc.).
+ * Every word is capitalized unconditionally — see `$title-case` for proper title casing
+ * that respects articles and conjunctions.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const CAPITALIZE_OPERATOR = {
+  keyword: 'capitalize',
+  process: (value) => toCapitalize(String(value))
+};

package/src/core-library/processors/cardnum-constraint.js

@@ -0,0 +1,193 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * IIN (Issuer Identification Number) network definitions.
+ * Used for output formatting only — detection does not affect validation.
+ * Ordered from most specific prefix to least specific to avoid false matches.
+ */
+const CARD_NETWORKS = [
+  {
+    name: 'amex',
+    match: (d) => d.startsWith('34') || d.startsWith('37'),
+    groups: [4, 6, 5],
+  },
+  {
+    name: 'diners',
+    match: (d) => {
+      const p3 = +d.slice(0, 3);
+      return (p3 >= 300 && p3 <= 305) || d.startsWith('36') || d.startsWith('38');
+    },
+    groups: [4, 6, 4],
+  },
+  {
+    name: 'jcb',
+    match: (d) => {
+      const p4 = +d.slice(0, 4);
+      return p4 >= 3528 && p4 <= 3589;
+    },
+    groups: [4, 4, 4, 4],
+  },
+  {
+    name: 'discover',
+    match: (d) => {
+      const p3 = +d.slice(0, 3);
+      const p6 = +d.slice(0, 6);
+      return d.startsWith('6011') || d.startsWith('65')
+        || (p3 >= 644 && p3 <= 649)
+        || (p6 >= 622126 && p6 <= 622925);
+    },
+    groups: [4, 4, 4, 4],
+  },
+  {
+    name: 'mastercard',
+    match: (d) => {
+      const p2 = +d.slice(0, 2);
+      const p4 = +d.slice(0, 4);
+      return (p2 >= 51 && p2 <= 55) || (p4 >= 2221 && p4 <= 2720);
+    },
+    groups: [4, 4, 4, 4],
+  },
+  {
+    name: 'visa',
+    match: (d) => d.startsWith('4'),
+    groups: [4, 4, 4, 4],
+  },
+];
+
+const DEFAULT_GROUPS = [4, 4, 4, 4];
+
+/**
+ * Luhn checksum validation.
+ * @param {string} digits
+ * @returns {boolean}
+ */
+function luhnCheck(digits) {
+  let sum = 0;
+  let double = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = +digits[i];
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}
+
+/**
+ * Format a character sequence using group sizes, with overflow in an extra group.
+ * @param {string} chars
+ * @param {number[]} groups
+ * @returns {string}
+ */
+function formatWithGroups(chars, groups) {
+  const parts = [];
+  let pos = 0;
+  for (const size of groups) {
+    if (pos >= chars.length) break;
+    parts.push(chars.slice(pos, pos + size));
+    pos += size;
+  }
+  if (pos < chars.length) {
+    parts.push(chars.slice(pos));
+  }
+  return parts.join(' ');
+}
+
+/**
+ * ## $cardnum
+ *
+ * Validates a payment card number (PAN) using the Luhn algorithm and normalizes
+ * its formatting based on the detected card network.
+ *
+ * **Processing steps:**
+ * 1. Strip formatting characters (spaces, dashes, dots)
+ * 2. Validate: digits only, length 12–19 (ISO 7812), Luhn checksum
+ * 3. Detect card network from IIN (Issuer Identification Number) prefix
+ * 4. Format with network-appropriate digit grouping
+ *
+ * **Recognized networks and their grouping:**
+ * - **Amex** (34, 37): `#### ###### #####`
+ * - **Diners Club** (300–305, 36, 38): `#### ###### ####`
+ * - **JCB** (3528–3589): `#### #### #### ####`
+ * - **Discover** (6011, 65, 644–649, 622126–622925): `#### #### #### ####`
+ * - **Mastercard** (51–55, 2221–2720): `#### #### #### ####`
+ * - **Visa** (4): `#### #### #### ####`
+ * - **Unrecognized**: `#### #### #### ####` (default grouping)
+ *
+ * Network detection is best-effort and does not affect validation — any number
+ * that passes the Luhn check with a valid length is accepted. Unrecognized
+ * prefixes receive default 4-4-4-4 grouping.
+ *
+ * ### Parameters
+ * - `mask` (boolean or string, default `false`): When truthy, replaces leading
+ *   digits with a mask character, revealing only the trailing digits.
+ *   `true` uses `'•'`; a string value uses its first character.
+ * - `reveal` (number, default `4`): Number of trailing digits to leave visible
+ *   when `mask` is enabled.
+ *
+ * ### Example
+ * ```js
+ * // Validate and format
+ * new Schema('string').validator('$cardnum')
+ * // '4111111111111111' → '4111 1111 1111 1111'
+ * // '378282246310005'  → '3782 822463 10005'
+ *
+ * // Masked for output (serializer — masking is a lossy presentation transform)
+ * new Schema('string').serializer({'$cardnum': {mask: true}})
+ * // '4111111111111111' → '•••• •••• •••• 1111'
+ *
+ * // Custom mask character, reveal 6 digits
+ * new Schema('string').serializer({'$cardnum': {mask: '*', reveal: 6}})
+ * // '4111111111111111' → '**** **** **11 1111'
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const CARDNUM_CONSTRAINT = {
+  keyword: 'cardnum',
+  parameters: [
+    { parameter: 'mask', default: false },
+    { parameter: 'reveal', default: 4 },
+  ],
+
+  process: (value, _target, _location, options) => {
+    const { mask, reveal } = options.args;
+
+    // Strip formatting
+    const digits = value.replace(/[\s\-.]/g, '');
+
+    if (!/^\d+$/.test(digits)) {
+      throw new ConstraintError('Invalid card number format');
+    }
+
+    if (digits.length < 12 || digits.length > 19) {
+      throw new ConstraintError('Invalid card number length');
+    }
+
+    if (!luhnCheck(digits)) {
+      throw new ConstraintError('Invalid card number (checksum failed)');
+    }
+
+    // Detect network for formatting (best-effort, does not gate validation)
+    let groups = DEFAULT_GROUPS;
+    for (const network of CARD_NETWORKS) {
+      if (network.match(digits)) {
+        groups = network.groups;
+        break;
+      }
+    }
+
+    // Apply masking
+    if (mask) {
+      const maskChar = (typeof mask === 'string' ? mask[0] : null) || '\u2022';
+      const visible = Math.min(Math.max(0, reveal), digits.length);
+      const masked = maskChar.repeat(digits.length - visible) + digits.slice(digits.length - visible);
+      return formatWithGroups(masked, groups);
+    }
+
+    return formatWithGroups(digits, groups);
+  }
+};

package/src/core-library/processors/ceil-operator.js

@@ -0,0 +1,44 @@
+
+/** @import {ValueProcessorDefinition} from '../../value-processor/value-processor.js' */
+
+/**
+ * ## $ceil
+ *
+ * Rounds a numeric value up to the nearest integer or specified decimal precision.
+ * Non-numeric values are passed through unchanged. Safe to use in normalize phase (non-throwing).
+ *
+ * ### Parameters
+ * - `precision` (number, optional): Number of decimal places to preserve. Defaults to 0 (round to integer).
+ *
+ * ### Example
+ * ```js
+ * // Round up to the nearest integer
+ * new Schema('number').transformer('$ceil')
+ * // 3.14 → 4, 9.01 → 10
+ *
+ * // Round up to 2 decimal places
+ * new Schema('number').transformer({$ceil: {precision: 2}})
+ * // 3.14159 → 3.15
+ *
+ * // Round up memory usage to the nearest MB boundary
+ * new Schema('object', {
+ *   memoryMB: new Schema('number').transformer({$ceil: {precision: 0}}),
+ * })
+ * ```
+ *
+ * @type {ValueProcessorDefinition}
+ */
+export const CEIL_OPERATOR = {
+  keyword: 'ceil',
+  parameters: [ { parameter: 'precision', default: 0 } ],
+
+  process: (value, _target, _location, options) => {
+    const num = Number(value);
+    if (!Number.isFinite(num)) {
+      return value; // Pass through non-numeric values unchanged
+    }
+    const precision = options.args['precision'];
+    const multiplier = Math.pow(10, precision);
+    return Math.ceil(num * multiplier) / multiplier;
+  }
+}

package/src/core-library/processors/collapse-operator.js

@@ -0,0 +1,29 @@
+/**
+ * ## $collapse
+ *
+ * Collapses runs of whitespace within a string to a single space, and trims
+ * leading and trailing whitespace. Useful for normalizing messy user input
+ * from forms, textareas, and configuration values.
+ *
+ * Compared to `$trim` (edges only) and `$compact` (removes all formatting),
+ * `$collapse` preserves word boundaries while normalizing irregular spacing.
+ *
+ * ### Example
+ * ```js
+ * // Clean up messy form input
+ * new Schema('string').normalizer('$collapse')
+ * // '  hello   world\n' → 'hello world'
+ *
+ * // Normalize a multi-line address to single line
+ * new Schema('string').normalizer('$collapse')
+ * // '123 Main St\n  Apt 4\n' → '123 Main St Apt 4'
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const COLLAPSE_OPERATOR = {
+  keyword: 'collapse',
+  process: (value) => {
+    return String(value).replace(/\s+/g, ' ').trim();
+  }
+};

package/src/core-library/processors/compact-operator.js

@@ -0,0 +1,34 @@
+/**
+ * ## $compact
+ *
+ * Strips common formatting characters from a string: whitespace, hyphens,
+ * dots, parentheses, and forward slashes. Useful for producing storage-ready
+ * representations of formatted values like phone numbers and card numbers.
+ *
+ * Characters removed: `\\s`, `-`, `.`, `(`, `)`, `/`
+ *
+ * Characters preserved: `+`, digits, letters, and all other characters.
+ *
+ * ### Example
+ * ```js
+ * // Compact a formatted phone number for storage
+ * new Schema('string').normalizer(['$phone', '$compact'])
+ * // '(212) 555-1234' → '2125551234'
+ *
+ * // Compact an international phone number (preserves +)
+ * new Schema('string').normalizer([{'$phone': {international: true}}, '$compact'])
+ * // '+1 212 555 1234' → '+12125551234'
+ *
+ * // Compact a card number for storage
+ * new Schema('string').normalizer(['$cardnum', '$compact'])
+ * // '4111 1111 1111 1111' → '4111111111111111'
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const COMPACT_OPERATOR = {
+  keyword: 'compact',
+  process: (value) => {
+    return String(value).replace(/[\s()\-./]/g, '');
+  }
+};