@versionzero/schema 1.0.0

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

@@ -0,0 +1,74 @@
+
+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';
+
+/**
+ * ## $require
+ *
+ * Require that the provided processor returns a defined value; return the original input if so.
+ * Throws a constraint error if the processor does not return a defined value.
+ *
+ * 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 a defined return value.
+ *   If omitted, the input value itself is checked for defined-ness.
+ *
+ * ### Example
+ * ```js
+ * // Require the input to be defined (not undefined)
+ * new Schema('any').validator('$require')
+ *
+ * // Require a lookup to succeed (key must exist in the table)
+ * new Schema('string').validator({
+ *   $require: {$lookup: {$literal: {admin: 1, user: 2, guest: 3}}}
+ * })
+ *
+ * // Require a nested path to resolve
+ * new Schema('object').validator({$require: {$get: 'metadata.version'}})
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const REQUIRE_CONSTRAINT = {
+  keyword: 'require',
+  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('$require requires no more than a single processor argument');
+      }
+    }
+    else if (typeof args === 'object') {
+      processor = args.processor;
+    }
+    if (!(processor instanceof ValueProcessor)) {
+      throw new SchemaError('$require requires a processor argument');
+    }
+
+    const spec = args.length === 0? '$require' : {'$require': 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 undefined', {cause: error}); } },
+        [ConditionalExecutor.CHECK_DEFINED, ConditionalExecutor.PASS_ERROR]
+      ),
+      spec, description);
+  }
+};

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

@@ -0,0 +1,20 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $reverse
+ *
+ * Returns a new array with elements in reverse order. Non-mutating.
+ * Throws if the input is not an array.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const REVERSE_OPERATOR = {
+  keyword: 'reverse',
+  process: (value, _target, location) => {
+    if (!Array.isArray(value)) {
+      throw new ConstraintError(`$reverse requires an array, got ${formatValue(value)}`, {location});
+    }
+    return [...value].reverse();
+  }
+};

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

@@ -0,0 +1,53 @@
+/**
+ * ## $round
+ *
+ * Rounds a numeric value to the nearest integer or to a specified number of decimal places.
+ * Safe to use in normalize phase (non-throwing). Non-numeric values pass through unchanged.
+ *
+ * ### Parameters
+ * - `precision` (number, optional): Number of decimal places. Defaults to 0 (integer rounding).
+ *
+ * **Examples**:
+ * - `3.7` with precision 0 → `4`
+ * - `3.14159` with precision 2 → `3.14`
+ * - `123.456` with precision 1 → `123.5`
+ * - `"not a number"` → `"not a number"` (passes through unchanged)
+ *
+ * ### Example
+ * ```js
+ * // Round to nearest integer
+ * new Schema('number').transformer('$round')
+ * // 3.5 → 4, 3.4 → 3
+ *
+ * // Round a price to 2 decimal places
+ * new Schema('number').transformer({$round: {precision: 2}})
+ * // 9.9950 → 9.99, 9.9951 → 10.00
+ *
+ * // Round a sensor reading to 1 decimal place
+ * new Schema('object', {
+ *   temperature: new Schema('number').transformer({$round: {precision: 1}}),
+ * })
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const ROUND_OPERATOR = {
+  keyword: 'round',
+  parameters: [ { parameter: 'precision', default: 0 } ],
+
+  process: (value, _target, _location, options) => {
+    const precision = options.args.precision;
+    const multiplier = Math.pow(10, precision);
+    const num = Number(value);
+    if (!Number.isFinite(num)) {
+      return value; // Pass through non-numeric values unchanged
+    }
+    return Math.round(num * multiplier) / multiplier;
+  },
+  /*
+      description: precision > 0 ? `round(${precision})` : 'round'
+    };
+  }
+
+   */
+};

package/src/core-library/processors/schema-handler-operators.js

@@ -0,0 +1,54 @@
+import { CompiledSchema } from '../../compiled-schema.js';
+import { SchemaError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $normalize
+ *
+ * Normalize the incoming value according using 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';
+ *
+ * const resolver = new SchemaResolver();
+ *
+ * const  = await resolver.compile(
+ *   new Schema('object')
+ *     .property('collection', new Schema('array')
+ *       .property('*', new Schema('string').normalizer('$trim').normalizer('$lowercase'))
+ *     .property('chosen', new Schema('string').normalizer({$normalize: {'$find-schema': '^.collection.*'}})
+ * );
+ *
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const NORMALIZE_OPERATOR = {
+  keyword: 'normalize',
+  parameters: [ { parameter: 'schema', required: true }, { parameter: 'value', required: false } ],
+
+  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});
+    }
+
+    const cycleCheck = (options.cycleCheck ?? new Set());
+
+    if (cycleCheck.has(location.schema)) {
+      throw new SchemaError(`Cycle detected while processing $normalize`, {location, value});
+    }
+    cycleCheck.add(location.schema);
+
+    const v = options.args.value ?? value;
+
+    return schema._normalizeValue(v, target, undefined, {cycleCheck}); // do not pass options, or outer schema context/paths will leak in!
+  }
+};

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

@@ -0,0 +1,282 @@
+import { ConstraintError, ResolverError } from '../../errors.js';
+
+/**
+ * Strict semver regex per semver.org 2.0.0 spec.
+ * Groups: 1=major, 2=minor, 3=patch, 4=prerelease (optional), 5=build (optional)
+ */
+const SEMVER_REGEX = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+/**
+ * @typedef {{ major: number, minor: number, patch: number, prerelease: string[], build: string[] }} SemVer
+ */
+
+/**
+ * Parse a semver string into its components.
+ * @param {string} str
+ * @returns {SemVer}
+ */
+function parseSemVer(str) {
+  const m = SEMVER_REGEX.exec(str.trim());
+  if (!m) {
+    throw new ResolverError(`Invalid semver: "${str}"`);
+  }
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] ? m[4].split('.') : [],
+    build: m[5] ? m[5].split('.') : [],
+  };
+}
+
+/**
+ * Compare two pre-release identifier arrays per semver 2.0.0 §11.
+ * Returns negative if a < b, 0 if equal, positive if a > b.
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {number}
+ */
+function comparePrerelease(a, b) {
+  // no prerelease on either — equal
+  if (a.length === 0 && b.length === 0) return 0;
+  // a version with prerelease has lower precedence than the release version
+  if (a.length === 0) return 1;
+  if (b.length === 0) return -1;
+
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    // fewer fields = lower precedence
+    if (i >= a.length) return -1;
+    if (i >= b.length) return 1;
+
+    const ai = a[i];
+    const bi = b[i];
+    if (ai === bi) continue;
+
+    const aNum = /^\d+$/.test(ai);
+    const bNum = /^\d+$/.test(bi);
+
+    // numeric identifiers always have lower precedence than alphanumeric
+    if (aNum && !bNum) return -1;
+    if (!aNum && bNum) return 1;
+
+    if (aNum && bNum) {
+      const diff = Number(ai) - Number(bi);
+      if (diff !== 0) return diff;
+    } else {
+      // both alphanumeric — lexicographic
+      if (ai < bi) return -1;
+      if (ai > bi) return 1;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Compare two parsed semver objects. Build metadata is ignored per spec.
+ * Returns negative if a < b, 0 if equal, positive if a > b.
+ * @param {SemVer} a
+ * @param {SemVer} b
+ * @returns {number}
+ */
+function compareSemVer(a, b) {
+  return (a.major - b.major)
+      || (a.minor - b.minor)
+      || (a.patch - b.patch)
+      || comparePrerelease(a.prerelease, b.prerelease);
+}
+
+// --- range parsing ---
+
+/** @typedef {(v: SemVer) => boolean} SemVerPredicate */
+
+/** Matches a single comparator: optional operator + semver */
+const COMPARATOR_REGEX = /^(>=|<=|>|<|=)?\s*((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?:[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?)$/;
+
+/**
+ * Parse a single comparator (e.g. '>=1.0.0', '<2.0.0', '1.2.3') into a predicate.
+ * @param {string} comp
+ * @returns {SemVerPredicate}
+ */
+function parseComparator(comp) {
+  const m = COMPARATOR_REGEX.exec(comp.trim());
+  if (!m) {
+    throw new ResolverError(`Invalid semver comparator: "${comp}"`);
+  }
+  const op = m[1] || '=';
+  const target = parseSemVer(m[2]);
+
+  switch (op) {
+    case '=':  return (v) => compareSemVer(v, target) === 0;
+    case '>':  return (v) => compareSemVer(v, target) > 0;
+    case '>=': return (v) => compareSemVer(v, target) >= 0;
+    case '<':  return (v) => compareSemVer(v, target) < 0;
+    case '<=': return (v) => compareSemVer(v, target) <= 0;
+    default:   throw new ResolverError(`Unknown semver operator: "${op}"`);
+  }
+}
+
+/**
+ * Parse a caret range (^1.2.3) into a predicate.
+ * ^major.minor.patch means >=major.minor.patch and:
+ *   major > 0: < (major+1).0.0
+ *   major === 0, minor > 0: < 0.(minor+1).0
+ *   major === 0, minor === 0: < 0.0.(patch+1)
+ * @param {string} version
+ * @returns {SemVerPredicate}
+ */
+function parseCaret(version) {
+  const min = parseSemVer(version);
+  /** @type {SemVer} */
+  let max;
+  if (min.major > 0) {
+    max = { major: min.major + 1, minor: 0, patch: 0, prerelease: [], build: [] };
+  } else if (min.minor > 0) {
+    max = { major: 0, minor: min.minor + 1, patch: 0, prerelease: [], build: [] };
+  } else {
+    max = { major: 0, minor: 0, patch: min.patch + 1, prerelease: [], build: [] };
+  }
+  return (v) => compareSemVer(v, min) >= 0 && compareSemVer(v, max) < 0;
+}
+
+/**
+ * Parse a tilde range (~1.2.3) into a predicate.
+ * ~major.minor.patch means >=major.minor.patch <major.(minor+1).0
+ * @param {string} version
+ * @returns {SemVerPredicate}
+ */
+function parseTilde(version) {
+  const min = parseSemVer(version);
+  /** @type {SemVer} */
+  const max = { major: min.major, minor: min.minor + 1, patch: 0, prerelease: [], build: [] };
+  return (v) => compareSemVer(v, min) >= 0 && compareSemVer(v, max) < 0;
+}
+
+/**
+ * Parse a semver range expression into a predicate.
+ * Supports: comparators (>=, >, <=, <, =), caret (^), tilde (~),
+ * and space-separated AND of comparators.
+ * @param {string} range
+ * @returns {SemVerPredicate}
+ */
+function parseRange(range) {
+  const trimmed = range.trim();
+
+  if (trimmed.startsWith('^')) {
+    return parseCaret(trimmed.slice(1));
+  }
+  if (trimmed.startsWith('~')) {
+    return parseTilde(trimmed.slice(1));
+  }
+
+  // space-separated AND of comparators
+  const parts = trimmed.split(/\s+/);
+  if (parts.length === 1) {
+    return parseComparator(parts[0]);
+  }
+  const predicates = parts.map(parseComparator);
+  return (v) => predicates.every(p => p(v));
+}
+
+/**
+ * ## $semver
+ *
+ * Validates that a string is a valid semantic version per the semver 2.0.0 spec.
+ *
+ * ### Parameters
+ * - `in` (string, optional): Semver range expression. Supports comparators
+ *   (`>=1.0.0`, `<2.0.0`), caret (`^1.2.3`), tilde (`~1.2.3`), and
+ *   space-separated AND (`>=1.0.0 <2.0.0`).
+ * - `min` (string, optional): Minimum version (inclusive).
+ * - `max` (string, optional): Maximum version (inclusive).
+ *
+ * Use either `in` OR `min`/`max`, not both.
+ *
+ * ### Example
+ * ```js
+ * // Format-only validation
+ * new Schema('string').validator('$semver')
+ *
+ * // Caret range (positional `in`)
+ * new Schema('string').validator({$semver: '^1.2.0'})
+ *
+ * // Tilde range
+ * new Schema('string').validator({$semver: '~1.2.0'})
+ *
+ * // Comparator range
+ * new Schema('string').validator({$semver: '>=1.0.0 <2.0.0'})
+ *
+ * // Explicit min/max (inclusive)
+ * new Schema('string').validator({$semver: {min: '1.0.0', max: '2.0.0'}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const SEMVER_CONSTRAINT = {
+  keyword: 'semver',
+
+  parameters: [
+    { parameter: 'in',  default: undefined, type: 'string' },
+    { parameter: 'min', default: undefined, type: 'string' },
+    { parameter: 'max', default: undefined, type: 'string' },
+  ],
+
+  process: (value, _target, _location, options) => {
+    const parsed = SEMVER_REGEX.exec(value);
+    if (!parsed) {
+      throw new ConstraintError('Invalid semver');
+    }
+
+    const { in: inRange, min, max } = options?.args ?? {};
+
+    if (inRange !== undefined && (min !== undefined || max !== undefined)) {
+      throw new ResolverError('$semver: "in" and "min"/"max" are mutually exclusive');
+    }
+
+    const ver = {
+      major: Number(parsed[1]),
+      minor: Number(parsed[2]),
+      patch: Number(parsed[3]),
+      prerelease: parsed[4] ? parsed[4].split('.') : [],
+      build: parsed[5] ? parsed[5].split('.') : [],
+    };
+
+    if (inRange !== undefined) {
+      const predicate = parseRange(inRange);
+      if (!predicate(ver)) {
+        throw new ConstraintError(`Version not in range "${inRange}"`);
+      }
+    }
+
+    if (min !== undefined) {
+      if (compareSemVer(ver, parseSemVer(min)) < 0) {
+        throw new ConstraintError(`Version below minimum ${min}`);
+      }
+    }
+    if (max !== undefined) {
+      if (compareSemVer(ver, parseSemVer(max)) > 0) {
+        throw new ConstraintError(`Version above maximum ${max}`);
+      }
+    }
+
+    return value;
+  },
+
+  describe: (args) => {
+    if (!args) return undefined;
+
+    const inProcessor = (Array.isArray(args) ? args[0] : args.in);
+    const minProcessor = (Array.isArray(args) ? args[1] : args.min);
+    const maxProcessor = (Array.isArray(args) ? args[2] : args.max);
+
+    const inVal = inProcessor?.description;
+    const min = minProcessor?.description;
+    const max = maxProcessor?.description;
+
+    if (inVal !== undefined) return `in ${inVal}`;
+    if (min !== undefined && max !== undefined) return `${min}–${max}`;
+    if (min !== undefined) return `≥${min}`;
+    if (max !== undefined) return `≤${max}`;
+    return undefined;
+  }
+};