@versionzero/schema 1.0.0

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

@@ -0,0 +1,235 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * Built-in country rules. Each entry maps a country calling code to:
+ * - `lengths` — accepted subscriber digit counts (after country code)
+ * - `validate` — optional regex applied to subscriber digits
+ * - `national` — `#`-template for national formatting
+ * - `international` — `#`-template for international formatting (after `+CC `)
+ *
+ * Users can extend via the `countries` parameter; custom entries are merged
+ * over these defaults (allowing override). Custom entries do not require
+ * `validate` — only `lengths` and templates are needed.
+ */
+const DEFAULT_COUNTRY_RULES = {
+  // NANP: area code (NPA) and exchange (NXX) cannot start with 0 or 1
+  '1': {
+    lengths: [10],
+    validate: /^[2-9]\d{2}[2-9]\d{6}$/,
+    national: '(###) ###-####',
+    international: '### ### ####',
+  },
+};
+
+/**
+ * Strip characters commonly used as phone number formatting.
+ * Preserves digits and a leading `+`.
+ * @param {string} value
+ * @returns {string}
+ */
+function stripFormatting(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('+')) {
+    return '+' + trimmed.slice(1).replace(/\D/g, '');
+  }
+  return trimmed.replace(/\D/g, '');
+}
+
+/**
+ * Replace each `#` in a template with the next digit from `digits`.
+ * @param {string} digits
+ * @param {string} template
+ * @returns {string}
+ */
+function applyTemplate(digits, template) {
+  let i = 0;
+  return template.replace(/#/g, () => digits[i++] ?? '');
+}
+
+/**
+ * ## $phone
+ *
+ * Validates and normalizes a phone number string.
+ *
+ * Strips common formatting (spaces, dashes, dots, parentheses, slashes) and
+ * validates the remaining digits against country-specific rules when available,
+ * or generic E.164 length rules otherwise.
+ *
+ * **Output format** is controlled by the `international` parameter:
+ * - When `false` (default): national format for the default country
+ *   (e.g. `(212) 555-1234` for country code `1`).
+ * - When `true`: international format with country code prefix
+ *   (e.g. `+1 212 555 1234`).
+ *
+ * Numbers without a `+` prefix are assumed to belong to the default `country`.
+ * A leading country code without `+` is recognized when it produces a valid
+ * subscriber length (e.g. `12125551234` is treated as `+1 2125551234`).
+ *
+ * **NANP validation (country code `1`):** area codes and exchanges must not
+ * start with `0` or `1`, matching North American Numbering Plan rules.
+ *
+ * **Not supported:** extensions, vanity letters (1-800-FLOWERS), international
+ * dialing prefixes (`00`, `011`), short codes, or emergency numbers. This
+ * processor targets typical subscriber phone numbers as entered in forms or
+ * configuration files.
+ *
+ * ### Parameters
+ * - `international` (boolean, default `false`): When `false`, only numbers
+ *   matching the default `country` code are accepted, and output uses the
+ *   national format. When `true`, any valid international number is accepted,
+ *   and output uses the international format with `+CC` prefix.
+ * - `country` (string, default `'1'`): Default country calling code applied
+ *   to numbers entered without a `+` prefix.
+ * - `countries` (object, default `null`): Optional map of country calling
+ *   codes to rule objects, merged over the built-in rules.  Each rule object
+ *   may contain:
+ *   - `lengths` (number[]) — accepted subscriber digit counts
+ *   - `validate` (RegExp, optional) — pattern the subscriber digits must match
+ *   - `national` (string) — `#`-template for national formatting
+ *   - `international` (string) — `#`-template for international formatting
+ *
+ * ### Example
+ * ```js
+ * // Basic US number validation and national formatting
+ * new Schema('string').validator('$phone')
+ *
+ * // Accept international numbers
+ * new Schema('string').validator({'$phone': {international: true}})
+ *
+ * // Default to UK numbers
+ * new Schema('string').validator({'$phone': {
+ *   country: '44',
+ *   countries: {
+ *     '44': {lengths: [10], national: '#### ### ####', international: '#### ### ####'}
+ *   }
+ * }})
+ *
+ * // Compact storage: compose with space/punctuation stripping
+ * new Schema('string').normalizer({$pipeline: ['$trim', '$phone']})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const PHONE_CONSTRAINT = {
+  keyword: 'phone',
+  parameters: [
+    { parameter: 'international', type: 'boolean', default: false },
+    { parameter: 'country', default: '1' },
+    { parameter: 'countries', default: null },
+  ],
+
+  process: (value, _target, _location, options) => {
+    const { international, country, countries: customCountries } = options.args;
+    const rules = customCountries
+      ? { ...DEFAULT_COUNTRY_RULES, ...customCountries }
+      : DEFAULT_COUNTRY_RULES;
+
+    const stripped = stripFormatting(value);
+
+    // After stripping, must be digits with optional leading +
+    if (!stripped || !/^\+?\d+$/.test(stripped)) {
+      throw new ConstraintError('Invalid phone number format');
+    }
+
+    let countryCode;
+    let subscriber = '';
+
+    if (stripped.startsWith('+')) {
+      const digits = stripped.slice(1);
+
+      // Match known country codes (ITU codes are prefix-free, 1-3 digits)
+      let matched = false;
+      for (const len of [1, 2, 3]) {
+        if (len > digits.length) break;
+        const candidate = digits.slice(0, len);
+        if (rules[candidate]) {
+          countryCode = candidate;
+          subscriber = digits.slice(len);
+          matched = true;
+          break;
+        }
+      }
+
+      if (!matched) {
+        if (!international) {
+          throw new ConstraintError(
+            `Phone number country code does not match +${country}`
+          );
+        }
+        // Unknown country — generic E.164 validation (total 7-15 digits)
+        if (digits.length < 7 || digits.length > 15) {
+          throw new ConstraintError('Invalid phone number length');
+        }
+        return '+' + digits;
+      }
+    }
+    else {
+      // No + prefix — match against default country
+      const countryRules = rules[country];
+      countryCode = country;
+
+      if (countryRules) {
+        const withCC = countryRules.lengths.map(l => l + country.length);
+        if (withCC.includes(stripped.length) && stripped.startsWith(country)) {
+          // Leading country code without + (e.g. 12125551234)
+          subscriber = stripped.slice(country.length);
+        }
+        else if (countryRules.lengths.includes(stripped.length)) {
+          // National number (e.g. 2125551234)
+          subscriber = stripped;
+        }
+        else {
+          throw new ConstraintError(
+            `Invalid phone number length for country code +${country}`
+          );
+        }
+      }
+      else {
+        // No rules for default country — accept digits as subscriber
+        subscriber = stripped;
+      }
+    }
+
+    // Reject international numbers when not accepted
+    if (!international && countryCode !== country) {
+      throw new ConstraintError(
+        `International numbers not accepted; expected country code +${country}`
+      );
+    }
+
+    // Country-specific validation
+    const countryRules = rules[countryCode];
+    if (countryRules) {
+      if (!countryRules.lengths.includes(subscriber.length)) {
+        throw new ConstraintError(
+          `Invalid phone number length for country code +${countryCode}`
+        );
+      }
+      if (countryRules.validate && !countryRules.validate.test(subscriber)) {
+        throw new ConstraintError(
+          `Invalid phone number for country code +${countryCode}`
+        );
+      }
+    }
+    else {
+      // Generic E.164: total digits (cc + subscriber) must be 7-15
+      const total = countryCode.length + subscriber.length;
+      if (total < 7 || total > 15) {
+        throw new ConstraintError('Invalid phone number length');
+      }
+    }
+
+    // Format output
+    if (international) {
+      if (countryRules?.international) {
+        return `+${countryCode} ${applyTemplate(subscriber, countryRules.international)}`;
+      }
+      return `+${countryCode}${subscriber}`;
+    }
+
+    if (countryRules?.national) {
+      return applyTemplate(subscriber, countryRules.national);
+    }
+    return subscriber;
+  }
+};

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

@@ -0,0 +1,62 @@
+
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { ArrayExecutor } from '../../executor/array-executor.js';
+import { map } from '../../helpers/object.js';
+import { ConstraintError, SchemaError } from '../../errors.js';
+
+/**
+ * ## $pick
+ *
+ * Returns a new object or dense array containing only the specified keys/indices from the input.
+ * Keys not present in the input are silently omitted from the result.
+ * For arrays, numeric indices are selected and the result is a dense (packed) array.
+ *
+ * ### Parameters
+ * - Array of key names or indices (string[]|number[], required): The keys/indices to retain.
+ *
+ * ### Example
+ * ```js
+ * // Retain only 'id' and 'name' from an object
+ * new Schema('object').transformer({$pick: ['id', 'name']})
+ * // {id: 1, name: 'Alice', secret: 'xyz'} → {id: 1, name: 'Alice'}
+ *
+ * // Select the first and third elements from an array
+ * new Schema('array').transformer({$pick: [0, 2]})
+ * // ['a', 'b', 'c', 'd'] → ['a', 'c']
+ *
+ * // Strip sensitive fields from a user record before returning
+ * new Schema('object').transformer({$pick: ['id', 'username', 'email', 'role']})
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const PICK_OPERATOR = {
+  keyword: 'pick',
+
+  build: (args) => {
+    if (!Array.isArray(args) || args.length === 0) {
+      throw new SchemaError('$pick requires a non-empty array of key names');
+    }
+
+    const argsSpec = map(args, v => v.spec);
+
+    return new FunctionValueProcessor(
+      (value, _target, location, options) => {
+        const keys = Array.isArray(options.args) ? options.args : [];
+        if (typeof value !== 'object' || value === null) {
+          throw new ConstraintError(`$pick requires an object or array input`, {location});
+        }
+        if (Array.isArray(value)) {
+          return keys.filter(k => k >= 0 && k < value.length).map(k => value[k]);
+        }
+        const result = {};
+        for (const k of keys) {
+          if (k in value) result[k] = value[k];
+        }
+        return result;
+      },
+      new ComposedValueProcessor(new ArrayExecutor(args), argsSpec)
+    );
+  }
+};

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

@@ -0,0 +1,63 @@
+import { PipelineExecutor } from '../../executor/pipeline-executor.js';
+
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { map } from '../../helpers/object.js';
+import { ResolverError } from '../../errors.js';
+
+/**
+ * @import {ValueProcessorDefinition} from '../../value-processor/value-processor.js'
+ */
+
+/**
+ * ## $pipeline
+ *
+ * Executes a sequence of processors in order, passing the output of each processor
+ * as input to the next. The final processor's output becomes the result.
+ *
+ * **Note**: Handler arrays (normalizers, validators, etc.) implicitly create pipelines,
+ * so this processor is rarely used directly. It's primarily used internally by the
+ * schema compiler to aggregate handler arrays into single compiled processors.
+ *
+ * ### Parameters
+ * - `processors` (`Array<ProcessorSpec>`, required): Array of processor specifications to execute in sequence.
+ *   Each element can be a string keyword (e.g., `'$trim'`), a parameterized processor object
+ *   (e.g., `{$range: {min: 0}}`), a RegExp, or a function.
+ *
+ * **Behavior**: Processors execute left-to-right. If any processor throws an error, the pipeline
+ * stops and the error propagates. Each processor receives the output of the previous processor
+ * as its input value.
+ *
+ * ### Example
+ * ```js
+ * // Explicit pipeline (equivalent to passing an array to .normalizer())
+ * new Schema('string').normalizer({$pipeline: ['$trim', '$lowercase', '$alphanum']})
+ *
+ * // Use $pipeline inside a conditional to chain processors on a branch
+ * new Schema('string').transformer({
+ *   $if: [
+ *     '$numeric',
+ *     {$pipeline: ['$number', {$clamp: {min: 0, max: 100}}]},
+ *   ]
+ * })
+ * ```
+ *
+ * @type {ValueProcessorDefinition}
+ */
+export const PIPELINE_OPERATOR = {
+  keyword: 'pipeline',
+  build: (args) => {
+    if (!Array.isArray(args)) {
+      throw new ResolverError('$pipeline requires an array of processors');
+    }
+
+    const descriptions = args.map(arg => arg.description ?? '').filter(Boolean);
+    const description = descriptions.length > 1
+                        ? descriptions.map(d => (d.includes('|') || d.includes('&')) ? `(${d})` : d).join(' >> ')
+                        : descriptions[0]
+    const spec = {$pipeline: map(args, arg => arg.spec)}
+
+    return new ComposedValueProcessor(new PipelineExecutor(args), spec, description);
+  }
+}
+
+

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

@@ -0,0 +1,22 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $port
+ *
+ * Validates that a value is a valid TCP/UDP port number (1-65535).
+ * Accepts numeric values or strings that can be converted to numbers.
+ * Returns the value as a number or a string, depending on the underlying schema.
+ * (defaults to a number).
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const PORT_CONSTRAINT = {
+  keyword: 'port',
+  process: (value, _target, location) => {
+    const num = Number(value);
+    if (!(Number.isInteger(num) && num >= 1 && num <= 65535)) {
+      throw new ConstraintError('Port must be between 1 and 65535');
+    }
+    return location.schema.options.type === 'string'? `${num}` : num;
+  }
+};

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

@@ -0,0 +1,23 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $positive
+ *
+ * Validates that a numeric value is positive (greater than 0).
+ * Input must already be a number; use `$number` in a prior normalizer if coercion from string is needed.
+ *
+ * See also:
+ * - `$negative` to enforce the opposite constraint
+ * - `$range` if you want "non-negative" ( greater than or equal to 0) semantics.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const POSITIVE_CONSTRAINT = {
+  keyword: 'positive',
+  process: (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+      throw new ConstraintError('Must be a positive number');
+    }
+    return value;
+  }
+};

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

@@ -0,0 +1,55 @@
+import { CompiledSchema } from '../../compiled-schema.js';
+import { SchemaError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $process
+ *
+ * Process the incoming value according to the provided schema
+ *
+ * Important note: the provided schema is run in isolation in a private local context, which means
+ * that it (and its handlers) have no access to the outer schema or the global target value, and all
+ * paths are relative to the root of the provided schema.
+ *
+ * ### Parameters
+ * - `schema` (CompiledSchema, required): the compiled schema to apply to the input value.
+ *   Any `Schema` found in a handler pipeline will be automatically compiled;
+ *   Use `$compile` to produce a `CompiledSchema` from a `Schema` literal value.
+ *
+ * ### Example
+ * ```js
+ * import { Schema, SchemaResolver } from '@versionzero/schema';
+ *
+ * // Compile a reusable sub-schema and run values through it
+ * const resolver = new SchemaResolver();
+ * const portSchema = await resolver.compile(
+ *   new Schema('number').validator({$range: {min: 1, max: 65535}})
+ * );
+ *
+ * // portSchema is automatically compiled:
+ * new Schema('object', {
+ *   port: new Schema('any').validator({$process: {schema: portSchema}}),
+ * })
+ *
+ * // Use $compile inline to compile-then-process in a single pipeline
+ * const mySchema = new Schema('string').validator('$non-empty');
+ * new Schema('any').normalizer([{$compile: {$literal: mySchema}}, '$process'])
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const PROCESS_OPERATOR = {
+  keyword: 'process',
+  parameters: [ { parameter: 'schema', required: true } ],
+
+  process: (value, _target, location, options) => {
+
+    const schema = options.args.schema;
+
+    if (!(schema instanceof CompiledSchema)) {
+      throw new SchemaError(`Schema argument must be an instance of CompiledSchema, got ${formatValue(schema)})`, {location});
+    }
+
+    return schema._process(value); // do not pass options, or outer schema context/paths will leak in!
+  }
+};

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

@@ -0,0 +1,49 @@
+import { SchemaError } from '../../errors.js';
+
+/**
+ * ## $property
+ *
+ * Extracts a named property value from an object. This operator is useful for accessing
+ * nested properties or extracting specific fields during processing pipelines.
+ *
+ * Returns `undefined` if the current value is not an object or if the property doesn't exist.
+ * Throws a `SchemaError` if the specified property name is not defined in the schema.
+ *
+ * ### Parameters
+ * - `name` (string, required): The name of the schema-defined property to extract from the input object.
+ *   The property must be declared in the current schema; use `$get` for arbitrary path access without
+ *   schema awareness.
+ *
+ * ### Example
+ * ```js
+ * // Conditionally require 'apiKey' only when 'useApiKey' is true
+ * new Schema('object', {
+ *   useApiKey: new Schema('boolean'),
+ *   apiKey: new Schema('string').validator({
+ *     $if: [{$property: 'useApiKey'}, '$non-empty']
+ *   }),
+ * })
+ *
+ * // Discriminate a union using a schema property value
+ * new Schema('object', {
+ *   type: new Schema('string'),
+ *   config: new Schema('any'),
+ * }).discriminator({$property: 'type'})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const PROPERTY_OPERATOR = {
+  keyword: 'property',
+  parameters: [{parameter: 'name', required: true}],
+  process: (value, _target, location, options) => {
+    const propertyName = options.args.name;
+    if (propertyName === undefined) {
+      throw new SchemaError('$property expects a property name', {location})
+    }
+    if (location.schema.getPropertySchema(propertyName) === undefined) {
+      throw new SchemaError(`Unknown $property ${propertyName}`, {location});
+    }
+    return (typeof value === 'object' && value !== null)? value[propertyName] : undefined;
+  }
+};

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

@@ -0,0 +1,72 @@
+
+import { ConstraintError, ResolverError } from '../../errors.js';
+
+/**
+ * ## $range
+ *
+ * Validates that a numeric value falls within the specified range (inclusive).
+ * Can specify minimum, maximum, or both bounds.
+ *
+ * ### Parameters
+ * - `min` (number, optional): Minimum value (inclusive). If omitted, no lower bound.
+ * - `max` (number, optional): Maximum value (inclusive). If omitted, no upper bound.
+ *
+ * ### Example
+ * ```js
+ * // Object form with named parameters
+ * new Schema('number').validator({$range: {min: 1, max: 100}})
+ *
+ * // Array form [min, max]
+ * new Schema('number').validator({$range: [1, 65535]})
+ *
+ * // Only a lower bound (percentage, must be non-negative)
+ * new Schema('number').validator({$range: {min: 0}})
+ *
+ * // Only an upper bound
+ * new Schema('number').validator({$range: {max: 255}})
+ * ```
+ *
+ * See also: `$positive` and `$negative` for common named ranges.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const RANGE_CONSTRAINT = {
+  keyword: 'range',
+  parameters: [ { parameter: 'min', type: 'number', default: undefined }, { parameter: 'max', type: 'number', default: undefined } ],
+
+  process: (value, _target, _location, options) => {
+    const { min, max } = options.args;
+
+    const num = Number(value);
+    if (!Number.isFinite(num)) {
+      throw new ConstraintError('Value must be a number');
+    }
+    if (min !== undefined && num < min) {
+      throw new ConstraintError(`Value must be at least ${min}`);
+    }
+    if (max !== undefined && num > max) {
+      throw new ConstraintError(`Value must be at most ${max}`);
+    }
+    return value;
+  },
+  describe: (args) => {
+
+    if (!args) {
+      return undefined;  // should never happen
+    }
+
+    const minProcessor = (Array.isArray(args)? args[0] : args.min);
+    const maxProcessor = (Array.isArray(args)? args[1] : args.max);
+
+    const min = minProcessor?.description;
+    const max = maxProcessor?.description;
+
+    return min !== undefined && max !== undefined
+           ? `${min}-${max}`
+           : min !== undefined
+             ? `≥${min}`
+             : max !== undefined
+               ? `≤${max}`
+               : undefined
+  }
+};

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

@@ -0,0 +1,79 @@
+import { deepValue } from '../../helpers/deep.js';
+
+import { SchemaError } from '../../errors.js';
+
+/**
+ * ## $reference
+ *
+ * Returns the value at the referenced path (relative to the current schema) in the target data, or undefined if not set.
+ *
+ * Throws a `SchemaError` if the specified path is not defined in the schema.
+ *
+ * ### Parameters
+ * - `path` (string, required): path from the current schema into the top-level target object; must be a valid
+ *   schema path (dot-separated, supports / for absolute or ^ for parents).
+ * - `pending` (boolean, optional, default: false): If true will fall back to any pending value not yet in the target data.
+ * - `completed` (boolean, optional, default: false): If true, will only return a value if the reference is completed (useful for checking if all children are handled).
+ *
+ * ### Example
+ * ```js
+ * // Validate 'port' is within range only when 'ssl' is enabled at the top level
+ * new Schema('object', {
+ *   ssl: new Schema('boolean'),
+ *   port: new Schema('number').validator({
+ *     $if: [{$reference: 'ssl'}, {$range: {min: 443, max: 443}}]
+ *   }),
+ * })
+ *
+ * // Cross-field consistency: confirm 'passwordConfirm' matches 'password'
+ * new Schema('object', {
+ *   password: new Schema('string'),
+ *   passwordConfirm: new Schema('string').validator(
+ *     (value, target) => value === target.password || undefined
+ *   ),
+ * })
+ * ```
+ * ### See Also
+ * - Use `$property` for getting a named child value.
+ * - Use `$get` for getting values under the input value (without the path needing to be in the schema.)
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const REFERENCE_OPERATOR = {
+  keyword: 'reference',
+  parameters: [{parameter: 'path', required: true}, {parameter: 'pending', required: false, default: false}, {parameter: 'completed', required: false, type: 'boolean', default: false}],
+  process: (_, target, location, options) => {
+    const path = options.args.path;
+    if (path === undefined) {
+      throw new SchemaError('$reference expects a path')
+    }
+    const state = options.state.getRelativeState(path);
+
+    const requireCompleted = options.args.completed;
+
+    if (state === undefined) {
+      if (requireCompleted) {
+        return undefined;  // welp.
+      }
+      // We're lost.  Maybe we can find it in the target data?
+      const resolvedLocation = location.relative(path);
+      return resolvedLocation? deepValue(target, resolvedLocation.path) : undefined;
+    }
+    if (requireCompleted && !state.completed) {
+      return undefined;
+    }
+    if (state.value !== undefined) {
+      return state.value;
+    }
+    if (options.args.pending) {
+      return state.pending;
+    }
+    return undefined;
+  },
+  /*
+      description: `${path}`
+    };
+  }
+
+   */
+};