@versionzero/schema 1.0.0

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

@@ -0,0 +1,76 @@
+
+import { ConstraintError } from '../../errors.js';
+import { parseDate } from '../../helpers/parse-date.js';
+
+/**
+ * ## $date-range
+ *
+ * Validates that a date value falls within the specified range (inclusive).
+ * Can specify minimum, maximum, or both bounds.  Bounds are parsed using
+ * the same rules as the `date` schema normalizer, so strings, numbers,
+ * and Date objects are all accepted.
+ *
+ * ### Parameters
+ * - `min` (optional): Minimum date (inclusive). If omitted, no lower bound.
+ * - `max` (optional): Maximum date (inclusive). If omitted, no upper bound.
+ *
+ * ### Example
+ * ```js
+ * // Object form with named parameters
+ * new Schema('date').validator({'$date-range': {min: '2024-01-01', max: '2024-12-31'}})
+ *
+ * // Cross-reference: end date must be >= start date
+ * new Schema('object')
+ *   .property('start', new Schema('date'))
+ *   .property('end', new Schema('date').validator({'$date-range': {min: {$reference: '^start'}}}))
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const DATE_RANGE_CONSTRAINT = {
+  keyword: 'date-range',
+  parameters: [
+    { parameter: 'min', default: undefined },
+    { parameter: 'max', default: undefined },
+  ],
+
+  process: (value, _target, _location, options) => {
+    const { min, max } = options.args;
+
+    const dateMs = (value instanceof Date ? value : parseDate(value)).getTime();
+
+    if (min !== undefined) {
+      const minMs = (min instanceof Date ? min : parseDate(min)).getTime();
+      if (dateMs < minMs) {
+        throw new ConstraintError(`Date must not be before ${new Date(minMs).toISOString()}`);
+      }
+    }
+    if (max !== undefined) {
+      const maxMs = (max instanceof Date ? max : parseDate(max)).getTime();
+      if (dateMs > maxMs) {
+        throw new ConstraintError(`Date must not be after ${new Date(maxMs).toISOString()}`);
+      }
+    }
+    return value;
+  },
+
+  describe: (args) => {
+    if (!args) {
+      return undefined;
+    }
+
+    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/defined-constraint.js

@@ -0,0 +1,30 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $defined
+ *
+ * Allow any value, as long as it's defined.
+ *
+ * ### Example
+ * ```js
+ * // Ensure an optional field, when supplied, is not undefined
+ * new Schema('any').validator('$defined')
+ *
+ * // Gate a sub-pipeline: only run if the value is defined
+ * new Schema('any').normalizer({$gate: ['$defined', '$trim']})
+ *
+ * // Require a computed result to be defined
+ * new Schema('string').validator({$require: {$get: {path: 'nested.key'}}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const DEFINED_CONSTRAINT = {
+  keyword: 'defined',
+  process: (value) => {
+    if (value === undefined) {
+      throw new ConstraintError('Must be defined');
+    }
+    return value;
+  }
+};

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

@@ -0,0 +1,57 @@
+import { EachExecutor } from "../../executor/each-executor.js";
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { Executor } from '../../executor/executor.js';
+import { PipelineExecutor } from '../../executor/pipeline-executor.js';
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $each
+ *
+ * Applies a processor to each element of an array. The processor can be any valid
+ * processor specification (RegExp, function, keyword, or parameterized processor).
+ * If any element fails validation, the entire array is rejected.
+ *
+ * This operator is useful for applying consistent validation or transformation rules
+ * across all array elements without requiring explicit array element schemas.
+ *
+ * ### Parameters
+ * - `processor` (any valid processor spec, required): The processor to apply to each element.
+ *   Can be a RegExp, function, string keyword (e.g., `'$numeric'`), or parameterized processor object.
+ *
+ * ### Example
+ * ```js
+ * // Trim whitespace from every string in an array
+ * new Schema('array').transformer({$each: '$trim'})
+ *
+ * // Validate that every element is numeric
+ * new Schema('array').validator({$each: '$numeric'})
+ *
+ * // Validate that each element is within a range
+ * new Schema('array').validator({$each: {$range: {min: 0, max: 100}}})
+ *
+ * // Normalize every tag: trim and lowercase
+ * new Schema('object', {
+ *   tags: new Schema('array').transformer({$each: ['$trim', '$lowercase']}),
+ * })
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const EACH_OPERATOR = {
+  keyword: 'each',
+  parameters: [{parameter: 'processor', required: true}],
+  build: (args) => {
+    const processor = (Array.isArray(args)? args[0] : args.processor) ?? new Executor();
+    // TODO - wrap the processor in a function that passes the original collection in the options
+
+    const values = (Array.isArray(args)? args[1] : args.values) ?? new Executor();
+
+    const spec = {$each: processor.spec};
+    const description = processor.description ? `[${processor.description}]...` : 'values...';
+
+    return new ComposedValueProcessor(new PipelineExecutor([values, new EachExecutor(processor)]), spec, description);
+  }
+};
+
+
+

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

@@ -0,0 +1,112 @@
+import { ConstraintError } from '../../errors.js';
+import { isFalsey } from '../../helpers/truthy.js';
+
+// Username: letters, digits, and limited special chars (._%+-)
+// No leading/trailing dot, no consecutive dots
+// Domain: 2+ dot-separated labels of letters/digits/hyphens, ending with 2+ letter TLD
+// No consecutive dots, no leading/trailing hyphens in labels
+const EMAIL_REGEX =
+  /^[a-zA-Z0-9_%+-](?:[a-zA-Z0-9_%+.-]*[a-zA-Z0-9_%+-])?@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/;
+
+// Additional check: no consecutive dots in local part
+const CONSECUTIVE_DOTS = /\.\./;
+
+/**
+ * ## $email
+ *
+ * Validates that a string matches a practical email address format (local-part@domain.tld).
+ *
+ * **Username (local part):**
+ * - Allowed characters: letters, digits, `.`, `_`, `%`, `+`, `-`
+ * - Must not start or end with a dot
+ * - Must not contain consecutive dots
+ *
+ * **Domain:**
+ * - Must consist of at least two dot-separated labels (e.g. `example.com`)
+ * - Labels may contain letters, digits, and hyphens (no leading/trailing hyphens)
+ * - Must not contain consecutive dots
+ * - Must end in a TLD of 2+ letters
+ *
+ * **Not supported (by design):** quoted local parts, comments, IP address literals, emoji,
+ * non-ASCII characters.  This processor is intended to handle addresses as they are typically
+ * used.  If you need to support all the madness that the official RFC allows, you'll need to
+ * write your own version.
+ *
+ * The default behavior is to convert the address to lower case for consistency, but this
+ * can be overridden.
+ *
+ * ### Parameters
+ * - `case` (string, default `'lower'`): Case conversion applied to the domain portion,
+ *   and (unless overridden by `case-sensitive`) to the username portion as well.
+ *   Accepts `'lower'` or `'upper'`, or if falsey, doesn't do any conversion.
+ * - `case-sensitive` (boolean, default `false`): When `true`, preserve the original case of
+ *   the username portion. When `false`, the username is converted using the `case` parameter.
+ *   (Rationale: RFC 5321 technically allows case-sensitive local parts, but virtually all
+ *   providers treat them as case-insensitive.)
+ * - `filter` (boolean, default `false`): When `true`, strip plus-addressing
+ *   (e.g. `user+tag@` becomes `user@`), and for `gmail.com` domains, additionally remove
+ *   all dots from the username (since Gmail ignores them).
+ *
+ * ### Example
+ * ```js
+ * // Basic validation only
+ * new Schema('string').validator('$email')
+ *
+ * // Normalize to lowercase, strip plus-addressing
+ * new Schema('string').validator({'$email': {filter: true}})
+ *
+ * // Preserve username case
+ * new Schema('string').validator({'$email': {'case-sensitive': true}})
+ *
+ * // Work for the government and like to shout at people?
+ * new Schema('string').validator({'$email': {'case': 'upper'}}
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const EMAIL_CONSTRAINT = {
+  keyword: 'email',
+  parameters: [
+    { parameter: 'case', default: 'lower' },
+    { parameter: 'case-sensitive', type: 'boolean', default: false },
+    { parameter: 'filter', type: 'boolean', default: false },
+  ],
+
+  process: (value, _target, _location, options) => {
+    const { 'case': caseParam, 'case-sensitive': caseSensitive, filter } = options.args;
+
+    if (!EMAIL_REGEX.test(value)) {
+      throw new ConstraintError('Invalid email format');
+    }
+
+    const atIndex = value.lastIndexOf('@');
+    let username = value.slice(0, atIndex);
+    let domain = value.slice(atIndex + 1);
+
+    // Reject consecutive dots in local part (regex alone can't catch all combos cleanly)
+    if (CONSECUTIVE_DOTS.test(username)) {
+      throw new ConstraintError('Invalid email format');
+    }
+
+    // Apply filter: strip plus-addressing and gmail dot normalization
+    if (filter) {
+      const plusIndex = username.indexOf('+');
+      if (plusIndex !== -1) {
+        username = username.slice(0, plusIndex);
+      }
+      if (domain.toLowerCase() === 'gmail.com') {
+        username = username.replace(/\./g, '');
+      }
+    }
+
+    // Apply case conversion
+
+    const applyCase = isFalsey(caseParam)? (s) => s : (caseParam === 'upper' ? (s) => s.toUpperCase() : (s) => s.toLowerCase());
+    domain = applyCase(domain);
+    if (!caseSensitive) {
+      username = applyCase(username);
+    }
+
+    return `${username}@${domain}`;
+  }
+};

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

@@ -0,0 +1,25 @@
+import { isPlainObject } from '../../helpers/object.js';
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $entries
+ *
+ * Returns the enumerable own properties of an object as an array of `[key, value]` pairs,
+ * matching the output of `Object.entries()`.
+ *
+ * The resulting array can be reconstructed back into an object with `$object`.
+ *
+ * Throws if the input is not a plain object.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const ENTRIES_OPERATOR = {
+  keyword: 'entries',
+  process: (value, _target, location) => {
+    if (!isPlainObject(value)) {
+      throw new ConstraintError(`$entries requires a plain object, got ${formatValue(value)}`, {location});
+    }
+    return Object.entries(value);
+  }
+};

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

@@ -0,0 +1,37 @@
+import { deepEquals } from "../../helpers/deep.js";
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $eq
+ *
+ * Do a deep equality check between the value and the provided constraint value.
+ *
+ * ### Parameters
+ * - `value` (any, required): The value to compare against using deep equality.
+ *
+ * ### Example
+ * ```js
+ * // Ensure a status field can only be 'active'
+ * new Schema('string').validator({$eq: 'active'})
+ *
+ * // Ensure an object matches an exact structure
+ * new Schema('object').validator({$eq: {type: 'config', version: 1}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}*
+ */
+export const EQ_CONSTRAINT = {
+  keyword: 'eq',
+  parameters: [ { parameter: 'value', required: true }, { parameter: 'compare' } ],
+
+  process: (value, _target, location, options) => {
+    const eqValue = options.args['value'];
+    const compare = options.args['compare'] ?? value;
+
+    if (!deepEquals(eqValue, compare)) {
+      throw new ConstraintError(`Value ${formatValue(value)} was not equal to constraint`, {value, location});
+    }
+    return value;
+  }
+}

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

@@ -0,0 +1,74 @@
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { ConditionalExecutor } from '../../executor/conditional-executor.js';
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { EachExecutor } from '../../executor/each-executor.js';
+
+import { SchemaError } from '../../errors.js';
+
+/**
+ * ## $filter
+ *
+ * Runs a processor on each element of the input array, keeping elements for which the processor
+ * succeeds and returning the processor's output value (consistent with standard processor semantics).
+ * Elements are filtered out if the processor throws or returns undefined.
+ * (Note that processor results are not checked for truthiness — only for definedness.)
+ *
+ * Non-arrays are "filtered" as an empty array.
+ *
+ * ### Parameters
+ * - `processor` (any valid processor spec, optional): The processor to apply to each element.
+ *   Elements where the processor returns undefined or throws are excluded from the result.
+ *   If omitted, null/undefined elements are removed.
+ *
+ * ### Example
+ * ```js
+ * // Remove null and undefined values from an array
+ * new Schema('array').transformer('$filter')
+ *
+ * // Keep only numeric strings
+ * new Schema('array').transformer({$filter: '$numeric'})
+ *
+ * // Keep only values within range
+ * new Schema('array').transformer({$filter: {$range: {min: 0, max: 100}}})
+ *
+ * // Filter out non-email strings from a list
+ * new Schema('object', {
+ *   recipients: new Schema('array').transformer({$filter: '$email'}),
+ * })
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const FILTER_OPERATOR = {
+  keyword: 'filter',
+  parameters: [{parameter: 'processor', required: false}],
+  build: (args) => {
+    let processor;
+    if (Array.isArray(args)) {
+      if (args.length > 1) {
+        throw new SchemaError('Expected exactly one argument for $filter operator');
+      }
+      processor = args[0];
+    }
+    else if (typeof args === 'object') {
+      if (Object.keys(args).length !== 1) {
+        throw new SchemaError('Expected only "processor" argument for $filter operator');
+      }
+      processor = args.processor;
+    }
+    processor ??= new FunctionValueProcessor(v => (v === undefined || v === null)? undefined : v);
+
+    return new ComposedValueProcessor(
+      new EachExecutor(
+        new ConditionalExecutor(processor, {}, [ConditionalExecutor.CHECK_DEFINED, ConditionalExecutor.PASS_RESULT]),
+        (inputs) => {
+          if (!Array.isArray(inputs)) {
+            return [];
+          }
+          return inputs;
+        },
+        (results) => (Array.isArray(results)? results.filter(r => r !== undefined) : [])
+      ),
+      {$filter: processor.spec});
+  }
+};

package/src/core-library/processors/find-schema-operator.js

@@ -0,0 +1,45 @@
+import { SchemaError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $find-schema
+ *
+ * Find a schema in the schema hierarchy based on a dotted path.  Returns the current schema by default.
+ * The provided path is interpreted relative to the currently active schema but supports navigation
+ * to the root schema using '/' and parent schema using '^'.
+ *
+ * ### Parameters
+ * - `path` (string | number, required): Dot-separated property path or array index.
+ *
+ * Example paths:
+ * - '': The current schema.
+ * - '/': The root schema.
+ * - 'xyzzy': Find the 'xyzzy' child of the current schema.
+ * - 'xyzzy.plugh': Find the 'plugh' child of the 'xyzzy' child of the current schema.
+ * - 'child.^': The current schema if and only if the child exists.
+ * - `/.foo.bar`: Find the 'bar' property in the 'foo' child of the root.
+ * - `^`: Return the parent schema
+ * - `^^jim`: Get the grandparent schema's child named 'jim' (uncle jim)
+ * - `^.^.jim`: Same thing (extra dots are ignored.)
+ *
+ * ```js
+ * new Schema('any').transformer({'$metadata': {name: 'description', schema: {'$find-schema': '^'}}})
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const FIND_SCHEMA_OPERATOR = {
+  keyword: 'find-schema',
+  parameters: [{parameter: 'path', required: false}],
+
+  process: (value, _target, location, options) => {
+    /** @type {string} */
+    const path = options.args?.path ?? value ?? '.';
+
+    if (typeof path !== 'string') {
+      throw new SchemaError(`$find-schema "path" must be a string, got ${formatValue(path)}`, {location});
+    }
+
+    return location.relative(path)?.schema;
+  }
+};

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

@@ -0,0 +1,40 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $flatten
+ *
+ * Returns a new array with sub-array elements flattened to the specified depth.
+ * Throws if the input is not an array.
+ *
+ * ### Parameters
+ * - `depth` (number, optional, default `1`): The depth to flatten. Use `Infinity` to flatten completely.
+ *
+ * ### Example
+ * ```js
+ * // Flatten one level of nesting
+ * new Schema('array').transformer('$flatten')
+ * // [[1, 2], [3, 4]] → [1, 2, 3, 4]
+ *
+ * // Flatten all levels
+ * new Schema('array').transformer({$flatten: {depth: Infinity}})
+ * // [1, [2, [3, [4]]]] → [1, 2, 3, 4]
+ *
+ * // Flatten exactly 2 levels
+ * new Schema('array').transformer({$flatten: {depth: 2}})
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const FLATTEN_OPERATOR = {
+  keyword: 'flatten',
+  parameters: [ { parameter: 'depth', default: 1 } ],
+
+  process: (value, _target, location, options) => {
+    if (!Array.isArray(value)) {
+      throw new ConstraintError(`$flatten requires an array, got ${formatValue(value)}`, {location});
+    }
+    const depth = options.args?.['depth'] ?? 1;
+    return value.flat(depth);
+  }
+};

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

@@ -0,0 +1,47 @@
+/**
+ * ## $floor
+ *
+ * Rounds a numeric value down to the specified number of decimal places.
+ * 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).
+ *
+ * **Input/Output Examples**:
+ * - `$floor`: `3.7` → `3`, `9.99` → `9`, `-2.3` → `-3`
+ * - `{$floor: 2}`: `3.14159` → `3.14`, `99.999` → `99.99`, `5.1` → `5.1`
+ * - `{$floor: 1}`: `3.76` → `3.7`, `9.01` → `9.0`
+ *
+ * ### Example
+ * ```js
+ * // Truncate to integer (floor toward zero for positive numbers)
+ * new Schema('number').transformer('$floor')
+ * // 9.99 → 9
+ *
+ * // Preserve 2 decimal places, discarding extra precision
+ * new Schema('number').transformer({$floor: {precision: 2}})
+ * // 3.14159 → 3.14
+ *
+ * // Strip sub-cent precision from a price field
+ * new Schema('object', {
+ *   price: new Schema('number').transformer({$floor: {precision: 2}}),
+ * })
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const FLOOR_OPERATOR = {
+  keyword: 'floor',
+  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.floor(num * multiplier) / multiplier;
+  }
+};

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

@@ -0,0 +1,44 @@
+import { deepValue } from '../../helpers/deep.js';
+
+/**
+ * ## $get
+ *
+ * Extracts a value from the input using a dot-separated path (for objects) or a numeric
+ * index (for arrays). Does not require the path to be declared as a schema property —
+ * use `$property` when schema-awareness is needed.
+ *
+ * Returns `undefined` if the path does not resolve.
+ *
+ * ### Parameters
+ * - `path` (string | number, required): Dot-separated property path or array index.
+ *
+ * ### Example
+ * ```js
+ * // Extract a nested property from an object
+ * new Schema('object').transformer({$get: {path: 'database.host'}})
+ * // {database: {host: 'localhost'}} → 'localhost'
+ *
+ * // Extract an array element by index
+ * new Schema('array').transformer({$get: {path: 0}})
+ * // ['first', 'second'] → 'first'
+ *
+ * // Use as a conditional predicate — only proceed if the path exists
+ * new Schema('object').transformer({
+ *   $when: [{$get: {path: 'config.timeout'}}]
+ * })
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const GET_OPERATOR = {
+  keyword: 'get',
+  parameters: [{parameter: 'path', required: true}],
+
+  process: (value, _target, _location, options) => {
+    const path = options.args?.path;
+    if (typeof path === 'number') {
+      return Array.isArray(value) ? value[path] : undefined;
+    }
+    return deepValue(value, path);
+  }
+};

package/src/core-library/processors/group-by-operator.js

@@ -0,0 +1,84 @@
+
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { EachExecutor } from '../../executor/each-executor.js';
+import { ConstraintError, SchemaError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $group-by
+ *
+ * Groups an array of objects by a key, returning an object whose values are arrays of elements
+ * that share that key value.
+ *
+ * - `{'$group-by': 'key'}` — groups by the named property on each element
+ * - `{'$group-by': processor}` — groups by the result of executing the processor against each element
+ *   (any compiled processor spec, e.g. `'$type'`, `{$get: 'field'}`, or a function)
+ *
+ * Elements where the extracted key is `undefined` are omitted from the result.
+ * Insertion order is preserved within each group.
+ *
+ * ### Parameters
+ * - `key` (string or processor, required): Property name to group by, or a processor that extracts
+ *   the grouping key from each element. Plain strings (no leading `$`) are treated as property names;
+ *   all other processor specs are executed as extractors.
+ *
+ * ### Example
+ * ```js
+ * // Group an array of log entries by their severity level
+ * new Schema('array').transformer({'$group-by': 'level'})
+ * // [{level:'error', msg:'...'}, {level:'info', msg:'...'}]
+ * // → {error: [{level:'error', ...}], info: [{level:'info', ...}]}
+ *
+ * // Group by a computed key (the JS type of each element)
+ * new Schema('array').transformer({'$group-by': '$type'})
+ * // [1, 'a', 2, 'b'] → {number: [1, 2], string: ['a', 'b']}
+ *
+ * // Group by a nested property using $get
+ * new Schema('array').transformer({'$group-by': {$get: 'meta.region'}})
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const GROUP_BY_OPERATOR = {
+  keyword: 'group-by',
+
+  build: (args) => {
+    if (!Array.isArray(args) || args.length !== 1) {
+      throw new SchemaError('$group-by requires a single key or processor argument');
+    }
+
+    const keyArg = args[0];
+    const keySpec = keyArg?.spec;
+
+    // Plain property name strings (no leading $) → property lookup per element.
+    // Processor keywords ($type), complex specs, functions → execute as extractor.
+    const keyExtractor = (typeof keySpec === 'string' && !keySpec.startsWith('$'))
+      ? new FunctionValueProcessor(element => element?.[keySpec])
+      : keyArg;
+
+    return new ComposedValueProcessor(
+      new EachExecutor(
+        keyExtractor,
+        (input) => {
+          if (!Array.isArray(input)) {
+            throw new ConstraintError(`$group-by requires an array, got ${formatValue(input)}`);
+          }
+          return input;
+        },
+        (keys, input) => {
+          const result = {};
+          for (let i = 0; i < input.length; i++) {
+            const key = keys[i];
+            if (key === undefined) continue;
+            const groupKey = String(key);
+            if (!result[groupKey]) result[groupKey] = [];
+            result[groupKey].push(input[i]);
+          }
+          return result;
+        }
+      ),
+      {'$group-by': keySpec}
+    );
+  }
+};