@versionzero/schema 1.0.0

package/src/core-library/processors/has-prefix-constraint.js

@@ -0,0 +1,37 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $has-prefix
+ *
+ * Check that the provided string value starts with the prefix value
+ *
+ * ### Parameters
+ * - `match` (string, required): The required prefix string.
+ *
+ * ### Example
+ * ```js
+ * // Require all feature flag names to start with 'ff_'
+ * new Schema('string').validator({'$has-prefix': 'ff_'})
+ *
+ * // Require environment variables to start with 'APP_'
+ * new Schema('object', {
+ *   envKey: new Schema('string').validator({'$has-prefix': 'APP_'}),
+ * })
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}*
+ */
+export const HAS_PREFIX_CONSTRAINT = {
+  keyword: 'has-prefix',
+  parameters: [ { parameter: 'match', required: true } ],
+
+  process: (value, _target, location, options) => {
+    const prefix = options.args['match'];
+
+    if (!`${value}`.startsWith(prefix)) {
+      throw new ConstraintError(`Value ${formatValue(value)} did not start with prefix ${formatValue(prefix)}`, {location});
+    }
+    return value;
+  }
+}

package/src/core-library/processors/has-suffix-constraint.js

@@ -0,0 +1,35 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $has-suffix
+ *
+ * Check that the provided string value ends with the suffix value
+ *
+ * ### Parameters
+ * - `match` (string, required): The required suffix string.
+ *
+ * ### Example
+ * ```js
+ * // Require file paths to end with '.json'
+ * new Schema('string').validator({'$has-suffix': '.json'})
+ *
+ * // Require callback URLs to end with '/callback'
+ * new Schema('string').validator({'$has-suffix': '/callback'})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}*
+ */
+export const HAS_SUFFIX_CONSTRAINT = {
+  keyword: 'has-suffix',
+  parameters: [ { parameter: 'match', required: true } ],
+
+  process: (value, _target, location, options) => {
+    const suffix = options.args['match'];
+
+    if (!`${value}`.endsWith(suffix)) {
+      throw new ConstraintError(`Value ${formatValue(value)} did not end with suffix ${formatValue(suffix)}`, {location});
+    }
+    return value;
+  }
+}

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

@@ -0,0 +1,20 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $hex
+ *
+ * Validates that a string contains only valid hexadecimal characters (0-9, a-f, A-F).
+ * Does not require or validate a "0x" prefix - the value should be the raw hex digits.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const HEX_CONSTRAINT = {
+  keyword: 'hex',
+  process: (value) => {
+    const hexRegex = /^[0-9a-fA-F]+$/;
+    if (!hexRegex.test(value)) {
+      throw new ConstraintError('Must contain only hexadecimal characters');
+    }
+    return value;
+  }
+};

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

@@ -0,0 +1,22 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $hostname
+ *
+ * Validates that a string matches valid hostname format according to RFC 1123.
+ * Hostnames must start and end with alphanumeric characters and may contain
+ * hyphens between labels. Each label (section between dots) can be up to 63
+ * characters long.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const HOSTNAME_CONSTRAINT = {
+  keyword: 'hostname',
+  process: (value) => {
+    const hostnameRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+    if (!hostnameRegex.test(value)) {
+      throw new ConstraintError('Invalid hostname format');
+    }
+    return value;
+  }
+};

package/src/core-library/processors/http-url-constraint.js

@@ -0,0 +1,27 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $http-url
+ *
+ * Validates that a string is a valid HTTP or HTTPS URL. Uses the URL Web API for
+ * validation and specifically requires the protocol to be either `http:` or `https:`.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const HTTP_URL_CONSTRAINT = {
+  keyword: 'http-url',
+  process: (value) => {
+    try {
+      const url = new URL(value);
+      if (!['http:', 'https:'].includes(url.protocol)) {
+        throw new ConstraintError('URL must use HTTP or HTTPS protocol');
+      }
+      return value;
+    } catch (error) {
+      if (error instanceof ConstraintError) {
+        throw error;
+      }
+      throw new ConstraintError('Invalid HTTP URL format', {cause: error});
+    }
+  }
+};

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

@@ -0,0 +1,66 @@
+import { isEmpty, map } from "../../helpers/object.js";
+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 { ConstraintError, ResolverError, SchemaError } from '../../errors.js';
+
+/** @import {ValueProcessor, ValueProcessorDefinition} from '../../value-processor/value-processor.js' */
+
+/**
+ * ## $in
+ *
+ * Validates that a value is included in an allowed list of values.
+ * Uses strict equality (===) for comparison.
+ *
+ * ### Parameters
+ * The parameter is an array (not an object) of allowed values passed directly to the processor.
+ * - Array of values (array, required): The allowed values to match against using strict equality
+ *
+ * ### Example
+ * ```js
+ * // Restrict a log level to known values
+ * new Schema('string').validator({$in: ['debug', 'info', 'warn', 'error']})
+ *
+ * // Accept only specific HTTP methods
+ * new Schema('string').normalizer('$uppercase').validator({$in: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']})
+ *
+ * // Restrict a numeric status code to expected values
+ * new Schema('number').validator({$in: [200, 201, 204, 400, 401, 403, 404, 500]})
+ * ```
+ *
+ * @type {ValueProcessorDefinition}
+ */
+export const IN_CONSTRAINT = {
+  keyword: 'in',
+
+  build: (args) => {
+
+    const vpa = (Array.isArray(args)? args : args?.['values']);
+
+    if (isEmpty(args)) {
+      throw new SchemaError('Must define at least one value for $in');
+    }
+
+    const description = Array.isArray(vpa)? vpa.map(v => v.description).join('|')
+                                          : '[?]';
+
+    const argsSpec = map(vpa, v => v.spec)
+    const spec = {$in: argsSpec}
+
+    /** @type {ValueProcessor} */
+    const processor =
+      new FunctionValueProcessor(
+        (value, _target, location, options) => {
+          const values = (Array.isArray(options.args)? options.args : args.values) ?? [];
+          if (!values.includes(value)) {
+            throw new ConstraintError(`Value must be one of {${values.join('|')}}`, {location});
+          }
+          return value;
+        }, new ComposedValueProcessor(new ArrayExecutor(vpa), argsSpec)
+      );
+    // yuck, need a better contract for this...
+    processor.spec = spec;
+    processor.description = description;
+    return processor;
+  }
+};

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

@@ -0,0 +1,98 @@
+
+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 { Executor } from '../../executor/executor.js';
+import { ParametersValueProcessor } from "../../value-processor/parameters-value-processor.js";
+import { ConditionalExecutor } from '../../executor/conditional-executor.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $index-by
+ *
+ * Groups an array of objects by a unique key, returning an object whose value is the single array element value
+ * that has that key.  If the keys are not unique, throws an error.
+ *
+ * - `{'$index-by': 'key'}` — indexes by the named property on each element
+ * - `{'$index-by': processor}` — indexes by the result of executing the processor against each element
+ *
+ * Elements where the extracted key is `undefined` are omitted from the result.
+ *
+ * ### Parameters
+ * - `key` (string): Property name to group by, or a processor that extracts
+ *   the grouping key from each element.  If you use a bare argument or a single element array,
+ *   it is assumed to be the key.
+ * - `processor`: Must be passed via object parameter.  Must be a processor that will parse the provided
+ *   element and return the index key.  The outer collection is passed to the processor as `options.input`.
+ *
+ * ### Example
+ * ```js
+ * // TODO
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const INDEX_BY_OPERATOR = {
+  keyword: 'index-by',
+  parameters: [{parameter: 'processor', required: true}],
+  build: (args) => {
+
+    let processor;
+    let keyProcessor;
+
+    if (Array.isArray(args)) {
+      if (args.length !== 1) {
+        throw new SchemaError(`$index-by requires only a single key, or extended arguments with a processor`);
+      }
+      keyProcessor = args[0];
+    }
+    else if (typeof args === 'object') {
+      keyProcessor = args.key;
+      processor = args.processor;
+    }
+    if (keyProcessor) {
+      if (processor) {
+        throw new SchemaError(`$index-by requires only a key or a processor, not both`);
+      }
+      processor = new FunctionValueProcessor((value, target, location, options) => {
+        const result = keyProcessor.execute(value, target, location, {...options, input: value});
+
+        if (result instanceof Promise) {
+          return result.then(resolved => (resolved !== undefined)? value?.[resolved] : undefined)
+        }
+        return result !== undefined ? value?.[result] : undefined;
+      })
+    }
+
+    if (!processor) {
+      throw new SchemaError(`$index-by requires a key or processor argument`);
+    }
+
+    return new ComposedValueProcessor(
+      new EachExecutor(
+        processor,
+        (input) => {
+          if (!Array.isArray(input)) {
+            throw new ConstraintError(`$index-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;
+            if (result[String(key)] !== undefined) {
+              // todo - add a conflict policy argument, e.g. "first", "last", "error"
+              throw new ConstraintError(`$index-by requires unique keys, got duplicate key ${key}`);
+            }
+            result[String(key)] = input[i];
+          }
+          return result;
+        }
+      ),
+      {'$index-by': args}
+    );
+  }
+};

package/src/core-library/processors/index.js

@@ -0,0 +1,131 @@
+/** @import { ValueProcessorDefinition } from '../../value-processor/value-processor.js'; */
+
+let modules;
+try {
+  modules ??= await Promise.all([
+    import('./aggregation-operators.js'),
+    import('./alpha-constraint.js'),
+    import('./alphanum-constraint.js'),
+    import('./array-operator.js'),
+    import('./assert-constraint.js'),
+    import('./base64-constraint.js'),
+    import('./camel-case-operator.js'),
+    import('./capitalize-operator.js'),
+    import('./cardnum-constraint.js'),
+    import('./ceil-operator.js'),
+    import('./collapse-operator.js'),
+    import('./compact-operator.js'),
+    import('./compile-operator.js'),
+    import('./concat-operator.js'),
+    import('./conditional-operators.js'),
+    import('./constant-case-operator.js'),
+    import('./data-size-operator.js'),
+    import('./date-object-operator.js'),
+    import('./date-operator.js'),
+    import('./date-range-constraint.js'),
+    import('./defined-constraint.js'),
+    import('./each-operator.js'),
+    import('./email-constraint.js'),
+    import('./entries-operator.js'),
+    import('./eq-constraint.js'),
+    import('./filter-operator.js'),
+    import('./find-schema-operator.js'),
+    import('./flatten-operator.js'),
+    import('./floor-operator.js'),
+    import('./get-operator.js'),
+    import('./group-by-operator.js'),
+    import('./has-prefix-constraint.js'),
+    import('./has-suffix-constraint.js'),
+    import('./hex-constraint.js'),
+    import('./hostname-constraint.js'),
+    import('./http-url-constraint.js'),
+    import('./in-constraint.js'),
+    import('./instanceof-constraint.js'),
+    import('./index-by-operator.js'),
+    import('./input-operator.js'),
+    import('./integer-constraint.js'),
+    import('./invoke-operator.js'),
+    import('./ipv4-constraint.js'),
+    import('./ipv6-constraint.js'),
+    import('./is-array-constraint.js'),
+    import('./is-date-constraint.js'),
+    import('./is-number-constraint.js'),
+    import('./is-object-constraint.js'),
+    import('./is-string-constraint.js'),
+    import('./join-operator.js'),
+    import('./json-constraint.js'),
+    import('./json-decode-operator.js'),
+    import('./json-encode-operator.js'),
+    import('./kebab-case-operator.js'),
+    import('./keys-operator.js'),
+    import('./length-constraint.js'),
+    import('./lookup-operator.js'),
+    import('./lowercase-operator.js'),
+    import('./map-operator.js'),
+    import('./match-operator.js'),
+    import('./matches-constraint.js'),
+    import('./math-operators.js'),
+    import('./merge-deep-operator.js'),
+    import('./merge-operator.js'),
+    import('./metadata-operator.js'),
+    import('./negative-constraint.js'),
+    import('./never-constraint.js'),
+    import('./non-empty-constraint.js'),
+    import('./not-constraint.js'),
+    import('./number-operator.js'),
+    import('./numeric-constraint.js'),
+    import('./object-operator.js'),
+    import('./omit-operator.js'),
+    import('./parallel-operator.js'),
+    import('./pascal-case-operator.js'),
+    import('./pick-operator.js'),
+    import('./phone-constraint.js'),
+    import('./pipeline-operator.js'),
+    import('./port-constraint.js'),
+    import('./positive-constraint.js'),
+    import('./process-operator.js'),
+    import('./property-operator.js'),
+    import('./range-constraint.js'),
+    import('./reference-operator.js'),
+    import('./require-constraint.js'),
+    import('./reverse-operator.js'),
+    import('./round-operator.js'),
+    import('./schema-handler-operators.js'),
+    import('./semver-constraint.js'),
+    import('./sequence-processors.js'),
+    import('./sort-operator.js'),
+    import('./split-operator.js'),
+    import('./string-extra-operators.js'),
+    import('./string-operator.js'),
+    import('./target-operator.js'),
+    import('./template-operator.js'),
+    import('./title-case-operator.js'),
+    import('./type-operator.js'),
+    import('./trim-operator.js'),
+    import('./truthy-constraint.js'),
+    import('./unique-operator.js'),
+    import('./uppercase-operator.js'),
+    import('./url-constraint.js'),
+    import('./url-decode-operator.js'),
+    import('./url-encode-operator.js'),
+    import('./uuid-constraint.js'),
+    import('./values-operator.js'),
+  ]);
+}
+catch (error) {
+  throw new Error('Failed to load built-in processors', { cause: error });
+}
+
+
+/** @type {ValueProcessorDefinition[]} */
+export const BUILTIN_PROCESSORS = modules.flatMap(
+  ns => Object.values(ns).filter(v => v && typeof v.keyword === 'string')
+);
+
+/**
+ * Get all built-in value processor definitions
+ * @returns {ValueProcessorDefinition[]}
+ */
+export function getBuiltinProcessors() {
+  return BUILTIN_PROCESSORS;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * ## $input
+ *
+ * Returns the input value passed to the processor.  Acts as a declarative "pass-through".
+ * Useful for passing the input to processor arguments that don't normally use the input as a default,
+ * or as a placeholder in array arguments.
+ *
+ * ### Example
+ * ```js
+ * //
+ * new Schema('string')
+ *   .transformer([['{', '$input', '}']])
+ *   .transformer({'$join': ''})
+ *
+ * "hello" -> "{hello}"
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const INPUT_OPERATOR = {
+  keyword: 'input',
+  process: input => input
+};

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

@@ -0,0 +1,38 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $instanceof
+ *
+ * Validates that the input is an instance of the specified constructor.
+ *
+ * ### Parameters
+ * - `clazz` (Function, required): The constructor function to test against.
+ *
+ * ### Example
+ * ```js
+ * // Validate that a value is an instance of a custom class
+ * new Schema('any').validator({$instanceof: MyClass})
+ *
+ * // Validate that a value is a Map
+ * new Schema('any').validator({$instanceof: Map})
+ *
+ * // Validate that a value is an Error
+ * new Schema('any').validator({$instanceof: Error})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const INSTANCEOF_CONSTRAINT = {
+  keyword: 'instanceof',
+  parameters: [ { parameter: 'clazz', type: 'function', required: true } ],
+
+  process: (value, _target, location, options) => {
+    const ctor = options.args['clazz'];
+    if (!(value instanceof ctor)) {
+      const name = ctor.name || 'anonymous';
+      throw new ConstraintError(`Expected instance of ${name}, got ${formatValue(value)}`, {location});
+    }
+    return value;
+  }
+}

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

@@ -0,0 +1,22 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $integer
+ *
+ * Validates that a numeric value is an integer (no fractional part).
+ * Input must already be a number; use `$number` in a prior normalizer if coercion from string is needed.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const INTEGER_CONSTRAINT = {
+  keyword: 'integer',
+  process: (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new ConstraintError('Must be a finite number');
+    }
+    if (!Number.isInteger(value)) {
+      throw new ConstraintError('Must be an integer');
+    }
+    return value;
+  }
+};

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

@@ -0,0 +1,33 @@
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { Executor } from '../../executor/executor.js';
+import { PipelineExecutor } from '../../executor/pipeline-executor.js';
+import { ParameterizedValueProcessor } from '../../value-processor/parameterized-value-processor.js';
+
+/**
+ * ## $invoke
+ *
+ * Calls a provided processor and passes it arguments (if any).
+ *
+ * ### Parameters
+ * - `processor` (any valid processor spec, required): The processor to invoke.
+ * - `arguments` (optional; any extra values to pass to the processor in `options.args`)
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const INVOKE_OPERATOR = {
+  keyword: 'invoke',
+  parameters: [{parameter: 'processor', required: true}, {parameter: 'arguments', required: false}],
+  build: (args) => {
+    const processor = (Array.isArray(args)? args[0] : args.processor);
+    const wrapped = new ComposedValueProcessor(new PipelineExecutor([
+      processor,
+      v => v
+    ]), processor.spec)
+    const processorArguments = (Array.isArray(args)? args[1] : args['arguments']);
+
+    return new ParameterizedValueProcessor(wrapped, processorArguments, {$invoke: {processor: processor?.spec, arguments: processorArguments?.spec}})
+  }
+};
+
+
+