@versionzero/schema 1.0.0

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

@@ -0,0 +1,100 @@
+import { CompiledSchema } from '../../compiled-schema.js';
+import { SchemaError } from '../../errors.js';
+import { SchemaLocation } from "../../schema-location.js";
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $metadata
+ *
+ * Extracts named metadata from a schema, either from the current schema or a parameter.
+ *
+ * Useful for getting standard metadata like `type` or `description`, or as a way to transport information
+ * between schemas that get aggregated together.
+ *
+ * If a schema value is passed, the metadata is retrieved only from that particular schema.
+ * If a schema path is passed, or it is left empty (and thus uses the current schema), $metadata will
+ * search from the current schema to the root and return the first value located.  To suppress this search,
+ * pass `false` to the `inherit` parameter.
+ *
+ * Returns `undefined` if the referenced schema or metadata key does not exist.
+ *
+ * ### Parameters
+ * - `name` (string, required): The name of the metadata to extract from the schema.
+ * - `schema` (CompiledSchema|string, optional): The schema (or a relative path to a schema) to extract metadata from.  Defaults to the current schema.
+ * - `inherit` (boolean, optional): Whether to search for metadata in a parent if not found in implicit schema.
+ *
+ * ### Example
+ * ```js
+ * // Here is an example that will simply propagate the current schema description
+ * new Schema('object')
+ *   .property('description', new Schema('string')
+ *     .required()
+ *     .meta('description', 'This will be pulled into the property value')
+ *     .normalizer({$metadata: 'description'}))
+ *
+ * // Extract metadata from a sibling property using a relative path.
+ * // If 'temperature' lacked a 'unit' meta, $metadata would inherit 'metric' from the parent.
+ * const weatherSchema = await resolver.compile(
+ *   new Schema('object')
+ *     .meta('unit', 'metric')
+ *     .property('temperature', new Schema('number').meta('unit', '°C'))
+ *     .property('unit', new Schema('string')
+ *       .default('')
+ *       .transformer({$metadata: {name: 'unit', schema: '^.temperature'}})
+ *     )
+ * );
+ * const weather = await weatherSchema.process({temperature: 22});
+ * console.log('weather:', weather);
+ * // → {temperature: 22, unit: '°C'}
+ *
+ * // Unlike most other "get a value" operators, $metadata does not use the pipeline input as the source
+ * // because it is focused on the current processor calling context rather than values.  However, you can
+ * // force it to use a compiled schema in the value pipeline by using $input:
+ *
+ * new Schema('string')
+ *   .transformer(new Schema('string').meta('greeting', 'hello world'))
+ *   .transformer({'$metadata': {name: 'greeting', schema: '$input'}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const METADATA_OPERATOR = {
+  keyword: 'metadata',
+  parameters: [{parameter: 'name', required: true, type: 'string'}, {parameter: 'schema', required: false, default: undefined}, {parameter: 'inherit', required: false, default: true}],
+  process: (_value, _target, location, options) => {
+
+    const name = options.args.name;
+    const schema = options.args.schema;
+    const inherit = options.args.inherit;
+
+    if (schema !== undefined) {
+      if (schema instanceof CompiledSchema) {
+        return schema.metadata[name];
+      }
+      if (typeof schema === 'string') {
+        const newLocation = location.relative(schema);
+        if (newLocation === undefined) {
+          throw new SchemaError(`$metadata was unable to retrieve a schema at ${formatValue(schema)}`);
+        }
+        location = newLocation;
+      }
+      else {
+        throw new SchemaError(`$metadata expects a valid schema, got ${formatValue(schema)}`, {location});
+      }
+    }
+
+    /** @type {SchemaLocation|undefined} */
+    let search = location;
+
+    while (search !== undefined) {
+      if (search.schema.metadata[name] !== undefined) {
+        return search.schema.metadata[name];
+      }
+      if (!inherit) {
+        break;
+      }
+      search = search.parent;
+    }
+    return undefined;
+  }
+};

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

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

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

@@ -0,0 +1,69 @@
+
+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';
+
+/**
+ * ## $never
+ *
+ * Inverts a processor - Returns the input if the wrapped processor throws or returns an undefined value.
+ * Throw a constraint error if the wrapped processor returns a defined value.
+ *
+ * See `$not` to enforce falseyness.
+ *
+ * ### Parameters
+ * - `value` (ProcessorSpec, required): The processor specification to negate (must not return a defined value).
+ *
+ * ### Example
+ * ```js
+ * // Blacklist specific values — reject any input that is found in the lookup table
+ * new Schema('string').validator({$never: {$lookup: {admin: true, root: true}}})
+ *
+ * // Ensure a value does not parse as a number (must be a non-numeric string)
+ * new Schema('string').validator({$never: '$numeric'})
+ *
+ * // Reject any value that resolves from $get (path must NOT exist)
+ * new Schema('object').validator({$never: {$get: 'deprecated.field'}})
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}*
+ */
+export const NEVER_CONSTRAINT = {
+  keyword: 'never',
+
+  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('$never requires no more than a single value argument');
+      }
+    }
+    else if (typeof args === 'object') {
+      processor = args.processor;
+    }
+    if (!(processor instanceof ValueProcessor)) {
+      throw new SchemaError('$never requires a value argument');
+    }
+
+
+    const needParens = processor.description && /[|&>∧· ]/.test(processor.description);
+    const description = processor.description? (needParens ? `!(${processor.description})` : `!${processor.description}`)
+                                                                  : undefined
+    const spec = {$never: processor.spec};
+
+    return new ComposedValueProcessor(new ConditionalExecutor(processor, {
+      success: () => { throw new ConstraintError('Value must not match the specified condition'); },
+      failure: (value) => value
+    }, [ConditionalExecutor.CHECK_DEFINED]), spec, description);
+  }
+};

package/src/core-library/processors/non-empty-constraint.js

@@ -0,0 +1,59 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $non-empty
+ *
+ * Validates that a string, array, or object is not empty. For strings, the value must contain
+ * at least one non-whitespace character. For arrays, the length must be greater than zero.
+ * For objects, the number of keys must be greater than zero.
+ *
+ * ### Example
+ * ```js
+ * // Require a non-blank username
+ * new Schema('string').normalizer('$trim').validator('$non-empty')
+ *
+ * // Require at least one tag
+ * new Schema('array').validator('$non-empty')
+ *
+ * // Require a non-empty configuration object
+ * new Schema('object').validator('$non-empty')
+ *
+ * // Combine trim + non-empty as a common pattern for required text fields
+ * new Schema('object', {
+ *   name: new Schema('string').normalizer('$trim').validator('$non-empty'),
+ *   description: new Schema('string').normalizer('$trim').validator('$non-empty'),
+ * })
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const NON_EMPTY_CONSTRAINT = {
+  keyword: 'non-empty',
+  process: (value, _target, location) => {
+
+    if (typeof value === 'string') {
+      if (value.trim().length === 0) {
+        throw new ConstraintError('String cannot be empty or whitespace only');
+      }
+    }
+    else if (Array.isArray(value)) {
+      if (value.length === 0) {
+        throw new ConstraintError('Array cannot be empty');
+      }
+    }
+    else if (typeof value === 'object' && value !== null) {
+      if (Object.keys(value).length === 0) {
+        throw new ConstraintError('Object cannot be empty');
+      }
+    }
+    else {
+      if (value === undefined) {
+        throw new ConstraintError('Value cannot be undefined');
+      }
+      else if (value === null) {
+        throw new ConstraintError('Value cannot be null');
+      }
+    }
+    return value;
+  }
+};

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

@@ -0,0 +1,71 @@
+
+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';
+
+/**
+ * ## $not
+ *
+ * Inverts a processor result - returns true if the wrapped processor throws or returns a falsey value.
+ * Throw a constraint error if the wrapped processor returns a truthy value.
+ *
+ * This is useful for expressing negative constraints (e.g., "must not be a hostname").
+ *
+ * See `$never` to require the processor returns undefined or throws an exception.
+ *
+ * ### Parameters
+ * - `value` (ProcessorSpec, required): The processor specification to negate.
+ *
+ * ### Example
+ * ```js
+ * // Reject anything that looks like an IP address (accept hostnames only)
+ * new Schema('string').validator({$not: '$ipv4'})
+ *
+ * // Ensure a string is not a reserved word
+ * new Schema('string').validator({$not: {$in: ['admin', 'root', 'system']}})
+ *
+ * // Require a URL that is NOT an HTTP URL (i.e., must be HTTPS or another scheme)
+ * new Schema('string').validator({$not: '$http-url'}).validator('$url')
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}*
+ */
+export const NOT_CONSTRAINT = {
+  keyword: 'not',
+
+  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('$not requires no more than a single value argument');
+      }
+    }
+    else if (typeof args === 'object') {
+      processor = args.processor;
+    }
+    if (!(processor instanceof ValueProcessor)) {
+      throw new SchemaError('$not requires a value argument');
+    }
+
+
+    const needParens = processor.description && /[|&>∧· ]/.test(processor.description);
+    const description = processor.description? (needParens ? `!(${processor.description})` : `!${processor.description}`)
+                                                                  : undefined
+    const spec = {$not: processor.spec};
+
+    return new ComposedValueProcessor(new ConditionalExecutor(processor, {
+      success: () => { throw new ConstraintError('Value must not match the specified condition'); },
+      failure: () => true
+    }, [ConditionalExecutor.CHECK_TRUTHY]), spec, description);
+  }
+};

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

@@ -0,0 +1,24 @@
+import { EMPTY } from '../../constants.js';
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $number
+ *
+ * Validates and coerces values to numbers. Accepts numeric strings, integers, and floats.
+ * Rejects NaN, Infinity, and non-numeric values.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const NUMBER_OPERATOR = {
+  keyword: 'number',
+  process: (value) => {
+    if (value === EMPTY) {
+      return 0;
+    }
+    const num = Number(value);
+    if (Number.isNaN(num) || !Number.isFinite(num)) {
+      throw new ConstraintError('Must be a number or convertible to a number');
+    }
+    return num;
+  }
+};

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

@@ -0,0 +1,22 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $numeric
+ *
+ * Validates that a string contains only numeric digits (0-9).
+ * The value is coerced to a string before validation, so numbers are accepted
+ * but must not contain decimal points, signs, or scientific notation.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const NUMERIC_CONSTRAINT = {
+  keyword: 'numeric',
+  process: (value) => {
+    const v = `${value}`;
+    const numericRegex = /^[0-9]+$/;
+    if (!numericRegex.test(v)) {
+      throw new ConstraintError('Must contain only digits');
+    }
+    return value;
+  }
+};

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

@@ -0,0 +1,38 @@
+import { parse } from '../../helpers/stringify.js';
+import { EMPTY } from '../../constants.js';
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $object
+ *
+ * Attempts to normalize the input value as an object.
+ *
+ * See `$is-object` for strict object validation.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const OBJECT_OPERATOR = {
+  keyword: 'object',
+  process: (value) => {
+    if (value === EMPTY) {
+      value = {};
+    }
+    if (typeof value === 'string') {
+      // otherwise, we normalize as an object
+      try {
+        value = parse(value);
+      }
+      catch (error) {
+        throw new ConstraintError(`Invalid input string for object: ${formatValue(value)}`, {cause: error});
+      }
+    }
+    if (Array.isArray(value) && value.every(e => Array.isArray(e) && e.length === 2)) {
+      return Object.fromEntries(value);
+    }
+    if (typeof value === 'object') {
+      return value;
+    }
+    throw new ConstraintError(`Invalid input for object: ${formatValue(value)}`);
+  }
+};

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

@@ -0,0 +1,57 @@
+
+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';
+
+/**
+ * ## $omit
+ *
+ * Returns a new object or dense array with the specified keys/indices removed.
+ * Keys not present in the input are silently ignored.
+ * For arrays, numeric indices are excluded and the result is a dense (packed) array.
+ *
+ * ### Parameters
+ * - Array of key names or indices (string[]|number[], required): The keys/indices to exclude.
+ *
+ * ### Example
+ * ```js
+ * // Remove internal fields before returning a user object
+ * new Schema('object').transformer({$omit: ['password', 'salt', '_internalId']})
+ * // {id: 1, name: 'Alice', password: '...', _internalId: 42} → {id: 1, name: 'Alice'}
+ *
+ * // Remove the first element from an array
+ * new Schema('array').transformer({$omit: [0]})
+ * // ['header', 'row1', 'row2'] → ['row1', 'row2']
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const OMIT_OPERATOR = {
+  keyword: 'omit',
+
+  build: (args) => {
+    if (!Array.isArray(args) || args.length === 0) {
+      throw new SchemaError('$omit 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(`$omit requires an object or array input`, {location});
+        }
+        if (Array.isArray(value)) {
+          return value.filter((_v, i) => !keys.includes(i));
+        }
+        return Object.fromEntries(
+          Object.entries(value).filter(([k]) => !keys.includes(k))
+        );
+      },
+      new ComposedValueProcessor(new ArrayExecutor(args), argsSpec)
+    );
+  }
+};

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

@@ -0,0 +1,64 @@
+import { ParallelExecutor } from '../../executor/parallel-executor.js';
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { SchemaError } from '../../errors.js';
+import { map } from '../../helpers/object.js';
+
+/** @import {ValueProcessorDefinition} from '../../value-processor/value-processor.js' */
+
+/**
+ * ## $parallel
+ *
+ * Applies an array of processors concurrently to the same input value, returning an array
+ * of all results in the same order as the processors.
+ *
+ * When all processors are synchronous, execution is sequential and the result is a plain array.
+ * When any processor is asynchronous, all are run via `Promise.all`, giving true concurrent
+ * execution — useful for I/O-bound processors such as HTTP fetches or secret lookups.
+ *
+ * Errors propagate immediately (fail-fast). Wrap individual processors in `$gate` or `$try`
+ * to trap errors and return a fallback instead.
+ *
+ * ### Parameters
+ * - `processors` (Array, required): Array of processor specifications to run concurrently.
+ *
+ * ### Example
+ * ```js
+ * // Fan out to two transforms and collect both results
+ * new Schema('string').transformer({$parallel: ['$uppercase', '$trim']})
+ * // '  hello  ' → ['HELLO', 'hello']
+ *
+ * // Concurrent async lookups (both execute at the same time via Promise.all)
+ * new Schema('string').transformer({$parallel: [fetchUserFlags, fetchUserPermissions]})
+ * // → [flagsResult, permissionsResult]
+ *
+ * // Fan out validation across multiple schemas and collect results
+ * new Schema('object').transformer({
+ *   $parallel: [
+ *     {$get: 'id'},
+ *     {$get: 'name'},
+ *     {$get: 'email'},
+ *   ]
+ * })
+ * ```
+ *
+ * @type {ValueProcessorDefinition}
+ */
+export const PARALLEL_OPERATOR = {
+  keyword: 'parallel',
+  build: (args) => {
+    // The resolver's map() utility wraps scalar specs into single-element arrays before
+    // reaching build(), so {$parallel: '$trim'} arrives as [compiled_trim] and is valid.
+    // Only plain-object args (e.g. {$parallel: {key: spec}}) arrive as non-arrays.
+    if (!Array.isArray(args)) {
+      throw new SchemaError('$parallel requires an array of processors');
+    }
+
+    const spec = {$parallel: map(args, arg => arg.spec)};
+    const descriptions = args.map(arg => arg.description).filter(d => d !== undefined);
+    const description = descriptions.length > 0
+      ? descriptions.map(d => /[|&>·∧ ]/.test(d) ? `(${d})` : d).join(' ⊗ ')
+      : undefined;
+
+    return new ComposedValueProcessor(new ParallelExecutor(args), spec, description);
+  }
+};

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

@@ -0,0 +1,16 @@
+import { toPascalCase } from '../../helpers/case.js';
+
+/**
+ * ## $pascal-case
+ *
+ * Converts a string value to PascalCase format (first letter of each word capitalized, no separators).
+ * Safe to use in normalize phase (non-throwing).
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const PASCAL_CASE_OPERATOR = {
+  keyword: 'pascal-case',
+  process: (value) => {
+    return toPascalCase(String(value));
+  }
+};