@versionzero/schema 1.0.0

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

@@ -0,0 +1,85 @@
+
+import { SchemaLocation } from "../../schema-location.js";
+import { ConstraintError, ResolverError } from '../../errors.js';
+
+/**
+ * ## $length
+ *
+ * Validates that the length of a string or array falls within specified bounds (inclusive).
+ * Can specify minimum, maximum, exact length, or any combination of min/max.
+ *
+ * For strings, length is measured in characters. For arrays, length is measured in elements.
+ *
+ * ### Parameters
+ * - `exact` (number, optional): Exact required length. If specified, min/max are ignored.
+ * - `min` (number, optional): Minimum length (inclusive). If omitted, no lower bound.
+ * - `max` (number, optional): Maximum length (inclusive). If omitted, no upper bound.
+ *
+ * - With `{min: 3, max: 10}`: strings "abc" to "abcdefghij", arrays with 3-10 elements
+ * - With `{exact: 5}`: string "hello", array [1,2,3,4,5]
+ *
+ * - With `{min: 3, max: 10}`: string "ab" (too short), array with 11 elements (too long)
+ * - With `{exact: 5}`: string "hi" (wrong length), array [1,2,3] (wrong length)
+ *
+ * ### Example
+ * ```js
+ * // Validate a username is between 3 and 32 characters
+ * new Schema('string').validator({$length: {min: 3, max: 32}})
+ *
+ * // Require an exact number of elements in an array
+ * new Schema('array').validator({$length: 3})
+ *
+ * // Validate a fixed-length code (e.g., ISO country code)
+ * new Schema('string').normalizer('$uppercase').validator({$length: {exact: 2}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const LENGTH_CONSTRAINT = {
+  keyword: 'length',
+  parameters: [ { parameter: 'exact', default: undefined, type: 'number' }, { parameter: 'min', default: undefined, type: 'number' }, { parameter: 'max', default: undefined, type: 'number' } ],
+
+  process: (value, _target, _location, options) => {
+    const { min, max, exact } = options.args;
+    const length = Array.isArray(value) ? value.length : String(value).length;
+    const unit = Array.isArray(value) ? 'elements' : 'characters';
+
+    if (exact !== undefined) {
+      if (length !== exact) {
+        throw new ConstraintError(`Length must be exactly ${exact} ${unit}`);
+      }
+      return value;
+    }
+    if (min !== undefined && length < min) {
+      throw new ConstraintError(`Length must be at least ${min} ${unit}`);
+    }
+    if (max !== undefined && length > max) {
+      throw new ConstraintError(`Length must be at most ${max} ${unit}`);
+    }
+    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 exactProcessor = (Array.isArray(args)? args[2] : args.exact);
+
+    const min = minProcessor?.description;
+    const max = maxProcessor?.description;
+    const exact = exactProcessor?.description;
+
+    return exact !== undefined
+           ? `len=${exact}`
+           : min !== undefined && max !== undefined
+             ? `len=${min}-${max}`
+             : min !== undefined
+               ? `len≥${min}`
+               : max !== undefined
+                 ? `len≤${max}`
+                 : undefined
+  }
+};

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

@@ -0,0 +1,84 @@
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { ObjectExecutor } from '../../executor/object-executor.js';
+import { SchemaError } from '../../errors.js';
+import { deepValue } from '../../helpers/deep.js';
+
+/**
+ * ## $lookup
+ *
+ * Uses the pipeline value as a key to look up a corresponding value from the argument
+ * collection. This is the inverse of `$get`: the input value is the key, the argument is the
+ * collection.
+ *
+ * Returns `undefined` if the key is not found in the collection.
+ *
+ * ### Parameters
+ * - Object collection (object, required): The key/value lookup table.
+ *
+ * ### Example
+ * ```js
+ * // Map a string value to a numeric code
+ * new Schema('string').transformer({$lookup: {low: 1, medium: 2, high: 3}})
+ * // 'medium' → 2
+ *
+ * // Use a role name to look up its permission set
+ * new Schema('string').transformer({
+ *   $lookup: {$literal: {
+ *     admin: ['read', 'write', 'delete'],
+ *     editor: ['read', 'write'],
+ *     viewer: ['read'],
+ *   }}
+ * })
+ *
+ * // Validate that a key exists in the table (require a defined result)
+ * new Schema('string').validator({
+ *   $require: {$lookup: {$literal: {us: 'United States', uk: 'United Kingdom', ca: 'Canada'}}}
+ * })
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const LOOKUP_OPERATOR = {
+  keyword: 'lookup',
+  parameters: [{parameter: 'from', required: true, type: 'object'}, {parameter: 'path', type: 'string'}],
+  process: (value, target, location, options) => {
+    // We have a single optional parameter "path", so we know it will automatically get populated with the input value if no argument was supplied
+    const {from, path} = options.args;
+
+    if (from === undefined || path === undefined) {
+      // we enforce argument passing during compilation; since this is an operator, receiving an undefined
+      // collection or path should just be interpreted as "not available".
+      return undefined;
+    }
+
+    // but we do enforce proper typing!
+    if (typeof from !== 'object') {
+      throw new SchemaError('$lookup requires an object argument for "from"', {location});
+    }
+    if (typeof path !== 'string') {
+      throw new SchemaError('$lookup requires a string argument for "path"', {location});
+    }
+    return deepValue(from, path);
+  }
+}
+const LOOKUP_OPERATOR1 = {
+  keyword: 'lookup',
+
+  build: (args) => {
+    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+      throw new SchemaError('$lookup requires an object argument (the lookup table)');
+    }
+
+    const argsSpec = Object.fromEntries(
+      Object.entries(args).map(([k, v]) => [k, v?.spec ?? v])
+    );
+
+    return new FunctionValueProcessor(
+      (value, _target, _location, options) => {
+        return options.args?.[value];
+      },
+      new ComposedValueProcessor(new ObjectExecutor(args), {$lookup: argsSpec})
+    );
+  }
+};

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

@@ -0,0 +1,14 @@
+/**
+ * ## $lowercase
+ *
+ * Converts a string value to lowercase.
+ * Safe to use in normalize phase (non-throwing).
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const LOWERCASE_OPERATOR = {
+  keyword: 'lowercase',
+  process: (value) => {
+    return String(value).toLowerCase();
+  }
+};

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

@@ -0,0 +1,84 @@
+
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { EachExecutor } from '../../executor/each-executor.js';
+import { isPlainObject } from '../../helpers/object.js';
+import { ConstraintError, SchemaError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/** @import { ValueProcessorDefinition } from '../../value-processor/value-processor.js' */
+
+/**
+ * ## $map
+ *
+ * Polymorphic map operator. Applies a processor to each element of an array, or to each
+ * value of a plain object. Returns a new collection of the same shape with transformed values.
+ *
+ * - **Array input**: maps over elements; `undefined` results from the processor appear as `undefined` in output.
+ * - **Object input**: maps over values; keys are always preserved in the output.
+ * - **Non-collection input**: throws a `ConstraintError`.
+ *
+ * Note that `null` returned by the processor is the standard prune signal and will remove
+ * the element/entry from the output.
+ *
+ * ### Parameters
+ * - `processor` (any valid processor spec, required): Applied to each element or value.
+ *
+ * ### Example
+ * ```js
+ * // Uppercase every string in an array
+ * new Schema('array').transformer({$map: '$uppercase'})
+ *
+ * // Parse every element as a number
+ * new Schema('array').transformer({$map: '$number'})
+ *
+ * // Apply a pipeline to every value in an object
+ * new Schema('object').transformer({$map: ['$trim', '$lowercase']})
+ * // {name: '  Alice  ', city: '  NYC  '} → {name: 'alice', city: 'nyc'}
+ *
+ * // Extract a nested field from each element
+ * new Schema('array').transformer({$map: {$get: 'id'}})
+ * // [{id: 1, name: 'a'}, {id: 2, name: 'b'}] → [1, 2]
+ * ```
+ *
+ * @type {ValueProcessorDefinition}
+ */
+export const MAP_OPERATOR = {
+  keyword: 'map',
+  parameters: [{parameter: 'processor', required: true}],
+  build: (args) => {
+    let processor;
+    if (Array.isArray(args)) {
+      if (args.length > 1) {
+        throw new SchemaError('Expected exactly one argument for $map operator');
+      }
+      processor = args[0];
+    }
+    else if (typeof args === 'object') {
+      if (Object.keys(args).length !== 1) {
+        throw new SchemaError('Expected only "processor" argument for $map operator');
+      }
+      processor = args.processor;
+    }
+    processor ??= new FunctionValueProcessor(v => (v === undefined || v === null) ? undefined : v);
+
+    return new ComposedValueProcessor(
+      new EachExecutor(processor,
+        (input) => {
+          if (Array.isArray(input)) { return input }
+          if (isPlainObject(input)) { return Object.values(input) }
+
+          throw new ConstraintError(`$map requires an array or plain object, got ${formatValue(input)}`);
+        },
+        (output, input) => {
+          if (Array.isArray(input)) { return output }
+          if (isPlainObject(input)) {
+            return Object.fromEntries(Object.keys(input).map((key, index) => ([key, output[index]])))
+          }
+
+        }
+      ),
+      {$map: processor.spec}
+    )
+  }
+};

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

@@ -0,0 +1,64 @@
+
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { ConstraintError, SchemaError } from '../../errors.js';
+import { parseRegExp } from '../../helpers/regex.js';
+
+/**
+ * ## $match
+ *
+ * Operator that executes a RegExp match against a string input and returns the extracted result.
+ * Non-string values are passed through unchanged. Returns `undefined` if the string does not match.
+ *
+ * - If the RegExp contains named capture groups (`(?<name>...)`), returns the `groups`
+ *   object (ES2018 named captures) as a plain object.
+ * - Otherwise, returns a plain array of the full match and positional capture groups.
+ *
+ * ### Parameters
+ * - `pattern` (RegExp, required): The pattern to match against.
+ *
+ * ### Example
+ * ```js
+ * // Extract named capture groups from a date string
+ * new Schema('string').transformer({$match: /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/})
+ * // '2026-03-21' → {year: '2026', month: '03', day: '21'}
+ *
+ * // Extract positional captures from a version string
+ * new Schema('string').transformer({$match: /^(\d+)\.(\d+)\.(\d+)$/})
+ * // '1.2.3' → ['1.2.3', '1', '2', '3']
+ *
+ * // Use with $when to only proceed when the pattern matched
+ * new Schema('string').transformer({
+ *   $when: [{$match: /^Bearer (.+)$/}]
+ * })
+ * // 'Bearer abc123' → ['Bearer abc123', 'abc123']
+ * // 'Basic xyz'    → undefined (no match)
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const MATCH_OPERATOR = {
+  keyword: 'match',
+  build: (args) => {
+    let regex = (Array.isArray(args) ? args[0] : args)?.spec;
+    if (typeof regex === 'string') {
+      regex = parseRegExp(regex);
+    }
+    if (!(regex instanceof RegExp)) {
+      throw new SchemaError('$match requires a RegExp argument');
+    }
+    return new ComposedValueProcessor(
+      new FunctionValueProcessor((value, _target, location) => {
+        if (typeof value !== 'string') {
+          throw new ConstraintError('$match requires a string input', {location});
+        }
+        const result = value.match(regex);
+        if (result === null) return undefined;
+        if (result.groups && Object.keys(result.groups).length > 0) return {...result.groups};
+        return [...result];
+      }),
+      {$match: regex},
+      `${regex}`
+    );
+  }
+};

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

@@ -0,0 +1,54 @@
+
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { ConstraintError, SchemaError } from '../../errors.js';
+import { parseRegExp } from '../../helpers/regex.js';
+
+/**
+ * ## $matches
+ *
+ * Constraint that tests the string representation of the input against a RegExp.
+ * Throws a `ConstraintError` if the input does not match. Returns the original value unchanged.
+ *
+ * This is the explicit constraint form; bare RegExp values in processor specs are no longer
+ * treated as implicit constraints and must be wrapped with `$matches`.
+ *
+ * ### Parameters
+ * - `pattern` (RegExp, required): The pattern to test against.
+ *
+ * ### Example
+ * ```js
+ * // Validate a semantic version string
+ * new Schema('string').validator({$matches: /^\d+\.\d+\.\d+$/})
+ *
+ * // Validate a slug (lowercase letters, numbers, hyphens only)
+ * new Schema('string').validator({$matches: /^[a-z0-9]+(?:-[a-z0-9]+)*$/})
+ *
+ * // Validate a hex color code
+ * new Schema('object', {
+ *   color: new Schema('string').validator({$matches: /^#[0-9a-fA-F]{6}$/}),
+ * })
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const MATCHES_CONSTRAINT = {
+  keyword: 'matches',
+  build: (args) => {
+    let regex = (Array.isArray(args) ? args[0] : args)?.spec;
+    if (typeof regex === 'string') {
+      regex = parseRegExp(regex);
+    }
+    if (!(regex instanceof RegExp)) {
+      throw new SchemaError('$matches requires a RegExp argument');
+    }
+    const fn = new FunctionValueProcessor((value, _target, location) => {
+      if (!regex.test(String(value))) {
+        throw new ConstraintError(`Value does not match pattern ${regex}`, {location});
+      }
+      return value;
+    });
+    fn.description = `${regex}`;
+    return new ComposedValueProcessor(fn, {$matches: regex});
+  }
+};

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

@@ -0,0 +1,151 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $abs
+ *
+ * Returns the absolute value of a number.
+ *
+ * ### Example
+ * ```js
+ * // Normalize a signed offset to always be non-negative
+ * new Schema('number').transformer('$abs')
+ *
+ * // Ensure a distance value is always positive
+ * new Schema('object', {
+ *   distance: new Schema('number').transformer('$abs'),
+ * })
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const ABS_OPERATOR = {
+  keyword: 'abs',
+
+  process: (value, _target, location) => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new ConstraintError(`$abs requires a finite number, got ${formatValue(value)}`, {location});
+    }
+    return Math.abs(value);
+  }
+};
+
+/**
+ * ## $pow
+ *
+ * Raises a number to a power.
+ *
+ * - `{$pow: exponent}` — raises the input value to the given exponent
+ * - `{$pow: {exponent, base}}` — raises `base` to `exponent`, ignoring the input value
+ *
+ * ### Parameters
+ * - `exponent` (number, required): The exponent.
+ * - `base` (number, optional): Override the base. Defaults to the input value.
+ *
+ * ### Example
+ * ```js
+ * // Square the input value
+ * new Schema('number').transformer({$pow: {exponent: 2}})
+ * // 4 → 16, 3 → 9
+ *
+ * // Compute 2^n where n is the input
+ * new Schema('number').transformer({$pow: {exponent: '$number', base: 2}})
+ *
+ * // Convert bytes to kilobytes using inverse power
+ * new Schema('number').transformer({$pow: {exponent: -1}})
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const POW_OPERATOR = {
+  keyword: 'pow',
+  parameters: [ { parameter: 'exponent', required: true }, { parameter: 'base' } ],
+
+  process: (value, _target, location, options) => {
+    const exponent = options.args['exponent'];
+    const base = options.args['base'] !== undefined ? options.args['base'] : value;
+
+    if (typeof base !== 'number' || !Number.isFinite(base)) {
+      throw new ConstraintError(`$pow requires a finite number base, got ${formatValue(base)}`, {location});
+    }
+    return Math.pow(base, exponent);
+  }
+};
+
+/**
+ * ## $sqrt
+ *
+ * Returns the square root of a number.
+ *
+ * ### Example
+ * ```js
+ * // Compute the magnitude of a value
+ * new Schema('number').transformer('$sqrt')
+ *
+ * // Validate then take the square root
+ * new Schema('number').validator('$positive').transformer('$sqrt')
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const SQRT_OPERATOR = {
+  keyword: 'sqrt',
+
+  process: (value, _target, location) => {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+      throw new ConstraintError(`$sqrt requires a non-negative finite number, got ${formatValue(value)}`, {location});
+    }
+    return Math.sqrt(value);
+  }
+};
+
+/**
+ * ## $clamp
+ *
+ * Constrains a number to a `[min, max]` range by returning the nearest boundary when the value
+ * falls outside. Unlike `$range` (which throws), `$clamp` transforms.
+ *
+ * Both `min` and `max` are optional; omitting either leaves that end unclamped.
+ *
+ * ### Parameters
+ * - `min` (number, optional): Lower bound.
+ * - `max` (number, optional): Upper bound.
+ *
+ * ### Example
+ * ```js
+ * // Clamp a volume setting to [0, 100]
+ * new Schema('number').transformer({$clamp: {min: 0, max: 100}})
+ *
+ * // Clamp retry count to at most 10 (no lower bound)
+ * new Schema('number').transformer({$clamp: {max: 10}})
+ *
+ * // Ensure a timeout is at least 100ms
+ * new Schema('number').transformer({$clamp: {min: 100}})
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const CLAMP_OPERATOR = {
+  keyword: 'clamp',
+  parameters: [ { parameter: 'min' }, { parameter: 'max' } ],
+
+  process: (value, _target, location, options) => {
+    const min = options.args['min'];
+    const max = options.args['max'];
+
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new ConstraintError(`$clamp requires a finite number, got ${formatValue(value)}`, {location});
+    }
+    if (min !== undefined && (typeof min !== 'number' || !Number.isFinite(min))) {
+      throw new ConstraintError(`$clamp min must be a finite number, got ${formatValue(min)}`, {location});
+    }
+    if (max !== undefined && (typeof max !== 'number' || !Number.isFinite(max))) {
+      throw new ConstraintError(`$clamp max must be a finite number, got ${formatValue(max)}`, {location});
+    }
+
+    let result = value;
+    if (min !== undefined) result = Math.max(min, result);
+    if (max !== undefined) result = Math.min(max, result);
+    return result;
+  }
+};

package/src/core-library/processors/merge-deep-operator.js

@@ -0,0 +1,61 @@
+
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { ObjectExecutor } from '../../executor/object-executor.js';
+import { deepMerge } from '../../helpers/deep.js';
+import { ConstraintError, SchemaError } from '../../errors.js';
+
+/**
+ * ## $merge-deep
+ *
+ * Recursively deep-merges the argument object into the input object, returning
+ * a new object. Nested plain objects are merged rather than replaced; arrays
+ * and primitive values are overwritten. The input is not mutated.
+ *
+ * Use `$merge` for shallow (one-level) merging.
+ *
+ * ### Parameters
+ * - Object of fields to deep-merge (object, required): Key/value pairs to apply over the input.
+ *
+ * ### Example
+ * ```js
+ * // Deep-merge default nested config into the user-supplied object
+ * new Schema('object').transformer({
+ *   '$merge-deep': {
+ *     logging: {level: 'info', format: 'json'},
+ *     server: {port: 3000},
+ *   }
+ * })
+ * // {logging: {level: 'debug'}, server: {host: 'localhost'}}
+ * // → {logging: {level: 'debug', format: 'json'}, server: {host: 'localhost', port: 3000}}
+ *
+ * // Inject a nested metadata field without overwriting sibling keys
+ * new Schema('object').transformer({'$merge-deep': {meta: {version: 1}}})
+ * // {meta: {author: 'rg'}} → {meta: {author: 'rg', version: 1}}
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const MERGE_DEEP_OPERATOR = {
+  keyword: 'merge-deep',
+
+  build: (args) => {
+    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+      throw new SchemaError('$merge-deep requires an object argument');
+    }
+
+    const argsSpec = Object.fromEntries(
+      Object.entries(args).map(([k, v]) => [k, v?.spec ?? v])
+    );
+
+    return new FunctionValueProcessor(
+      (value, _target, location, options) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+          throw new ConstraintError(`$merge-deep requires a plain object input`, {location});
+        }
+        return deepMerge({}, value, options.args);
+      },
+      new ComposedValueProcessor(new ObjectExecutor(args), {'$merge-deep': argsSpec})
+    );
+  }
+};

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

@@ -0,0 +1,54 @@
+
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { ObjectExecutor } from '../../executor/object-executor.js';
+import { ConstraintError, SchemaError } from '../../errors.js';
+
+/**
+ * ## $merge
+ *
+ * Merges the argument object into the input object (shallow). The argument fields take
+ * precedence over same-named fields in the input, consistent with the "apply to the
+ * value being passed through" pattern.
+ *
+ * The input object is not mutated; a new object is returned.
+ *
+ * ### Parameters
+ * - Object of fields to merge (object, required): Key/value pairs to apply over the input.
+ *
+ * ### Example
+ * ```js
+ * // Inject default fields into every output object
+ * new Schema('object').transformer({$merge: {version: 1, active: true}})
+ * // {id: 42} → {id: 42, version: 1, active: true}
+ *
+ * // Overwrite a specific field in the result
+ * new Schema('object').transformer({$merge: {status: 'normalized'}})
+ * // {id: 1, status: 'raw'} → {id: 1, status: 'normalized'}
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const MERGE_OPERATOR = {
+  keyword: 'merge',
+
+  build: (args) => {
+    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+      throw new SchemaError('$merge requires an object argument');
+    }
+
+    const argsSpec = Object.fromEntries(
+      Object.entries(args).map(([k, v]) => [k, v?.spec ?? v])
+    );
+
+    return new FunctionValueProcessor(
+      (value, _target, location, options) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+          throw new ConstraintError(`$merge requires a plain object input`, {location});
+        }
+        return {...value, ...options.args};
+      },
+      new ComposedValueProcessor(new ObjectExecutor(args), {$merge: argsSpec})
+    );
+  }
+};