@versionzero/schema 1.0.0

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

@@ -0,0 +1,30 @@
+/**
+ * ## $target
+ *
+ * Returns the target value passed to the processor (value being built relative to the root).
+ * (Note: may return undefined or partial results, depending on the schema!)
+ *
+ * ### Example
+ *
+ * ```js
+ * // Uses $target to provide an object for $get to access
+ * new Schema('object')
+ *   .property('level-one', new Schema('object')
+ *     .property('enable-level-3', new Schema('boolean').default(false))
+ *     .property('level-two', new Schema('object')
+ *       .property('level-three', new Schema('object')
+ *         .condition(['$target', {get: 'level-one.enable-level-3'}])
+ *         .property('child', new Schema('string'))
+ *       )
+ *     )
+ *   )
+ * // { "level-one": { "level-two": { "level-three": { "child": "ignored" } } } }
+ * // { "level-one": { "enable-level-3": true, "level-two": { "level-three": { "child": "is set" } } } }
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const TARGET_OPERATOR = {
+  keyword: 'target',
+  process: (_input, target) => target
+};

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

@@ -0,0 +1,60 @@
+
+import { FunctionValueProcessor } from '../../value-processor/function-value-processor.js';
+import { ComposedValueProcessor } from '../../value-processor/composed-value-processor.js';
+import { ConstraintError, SchemaError } from '../../errors.js';
+
+/**
+ * ## $template
+ *
+ * Operator that interpolates a template string using properties from the input object.
+ * Placeholders use `{key}` syntax; double braces `{{` and `}}` are literal brace escapes.
+ *
+ * The input must be a plain object. Unknown keys resolve to an empty string.
+ *
+ * ### Parameters
+ * - `template` (string, required): The template string to interpolate.
+ *
+ * ### Example
+ * ```js
+ * // Build a connection string from object properties
+ * new Schema('object', {
+ *   host: new Schema('string'),
+ *   port: new Schema('number'),
+ *   database: new Schema('string'),
+ * }).transformer({$template: 'postgresql://{host}:{port}/{database}'})
+ *
+ * // Format a greeting from a user object
+ * new Schema('object').transformer({$template: 'Hello, {firstName} {lastName}!'})
+ *
+ * // Use double-braces to produce literal curly braces
+ * new Schema('object').transformer({$template: 'Value: {{literal}}'})
+ * // {} → 'Value: {literal}'
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const TEMPLATE_OPERATOR = {
+  keyword: 'template',
+  build: (args) => {
+    const template = (Array.isArray(args) ? args[0] : args)?.spec;
+    if (typeof template !== 'string') {
+      throw new SchemaError('$template requires a string argument');
+    }
+    const fn = new FunctionValueProcessor((value, _target, location) => {
+      if (typeof value !== 'object' || value === null) {
+        throw new ConstraintError('$template requires an object input', {location});
+      }
+      return template
+        .replace(/\{\{/g, '\x00')
+        .replace(/\}\}/g, '\x01')
+        .replace(/\{([^}]+)\}/g, (_, key) => {
+          const v = value[key];
+          return v === undefined ? '' : String(v);
+        })
+        .replace(/\x00/g, '{')
+        .replace(/\x01/g, '}');
+    });
+    fn.description = template;
+    return new ComposedValueProcessor(fn, {$template: template});
+  }
+};

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

@@ -0,0 +1,17 @@
+import { toTitleCase } from '../../helpers/case.js';
+
+/**
+ * ## $title-case
+ *
+ * Converts a string to title case, capitalizing the first letter of each significant word
+ * and leaving articles, coordinating conjunctions, and short prepositions lowercase when
+ * they appear in the middle of the phrase. The first and last words are always capitalized.
+ *
+ * Lowercase words: a, an, the, and, but, or, nor, for, so, yet, at, by, in, of, on, to, up, as, via
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const TITLE_CASE_OPERATOR = {
+  keyword: 'title-case',
+  process: (value) => toTitleCase(String(value))
+};

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

@@ -0,0 +1,14 @@
+/**
+ * ## $trim
+ *
+ * Removes leading and trailing whitespace from a string value.
+ * Safe to use in normalize phase (non-throwing operator).
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const TRIM_OPERATOR = {
+  keyword: 'trim',
+  process: (value) => {
+    return String(value).trim();
+  }
+};

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

@@ -0,0 +1,35 @@
+import { isTruthy } from '../../helpers/truthy.js';
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $truthy
+ *
+ * Validates that the value is "truthy".  Note that the definition of what values are "truthy"
+ * mirrors the boolean schema normalization of special strings like "true" and "no".
+ *
+ * ### Example
+ * ```js
+ * // Require a feature flag to be truthy before processing a value
+ * new Schema('object', {
+ *   enabled: new Schema('boolean'),
+ *   config: new Schema('string').validator({$assert: {$property: 'enabled'}}),
+ * })
+ *
+ * // Use $truthy inside a conditional to branch on truthiness
+ * new Schema('any').transformer({
+ *   $if: ['$truthy', '$uppercase']
+ * })
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const TRUTHY_CONSTRAINT = {
+  keyword: 'truthy',
+  process: (value) => {
+    if (isTruthy(value)) {
+      return value;
+    }
+    throw new ConstraintError('Must be truthy');
+  }
+};
+

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

@@ -0,0 +1,24 @@
+import { CompiledSchema } from '../../compiled-schema.js';
+
+/**
+ * ## $type
+ *
+ * Returns the type name of the input value as a string. Unlike the `$is-*` constraint family,
+ * this operator produces the type name as a value usable in pipelines and templates.
+ *
+ * **Return values**: `'string'`, `'number'`, `'boolean'`, `'array'`, `'object'`, `'date'`, `'schema'`, `'null'`, `'undefined'`
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const TYPE_OPERATOR = {
+  keyword: 'type',
+
+  process: (value) => {
+    if (value === null) return 'null';
+    if (value === undefined) return 'undefined';
+    if (value instanceof Date) return 'date';
+    if (Array.isArray(value)) return 'array';
+    if (value instanceof CompiledSchema) return 'schema';
+    return typeof value;
+  }
+};

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

@@ -0,0 +1,21 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $unique
+ *
+ * Returns a new array with duplicate values removed, preserving insertion order
+ * of first occurrences. Uses identity-based (`Set`) deduplication.
+ * Throws if the input is not an array.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const UNIQUE_OPERATOR = {
+  keyword: 'unique',
+  process: (value, _target, location) => {
+    if (!Array.isArray(value)) {
+      throw new ConstraintError(`$unique requires an array, got ${formatValue(value)}`, {location});
+    }
+    return [...new Set(value)];
+  }
+};

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

@@ -0,0 +1,14 @@
+/**
+ * ## $uppercase
+ *
+ * Converts a string value to uppercase. Safe to use in normalize phase (non-throwing).
+ * Non-string values are coerced to strings before conversion.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const UPPERCASE_OPERATOR = {
+  keyword: 'uppercase',
+  process: (value) => {
+    return String(value).toUpperCase();
+  }
+};

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

@@ -0,0 +1,31 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $url
+ *
+ * Validates that a string is a valid URL and normalizes it to canonical form.
+ * Uses the WHATWG URL Standard for validation and normalization. The normalized
+ * URL includes explicit protocol, properly encoded characters, and standardized formatting.
+ *
+ * - `https://example.com` → `https://example.com/`
+ * - `http://localhost:8080/api` → `http://localhost:8080/api`
+ * - `https://example.com/path?query=value` → `https://example.com/path?query=value`
+ * - `ftp://files.example.com/` → `ftp://files.example.com/`
+ *
+ * - `not-a-url` (missing protocol)
+ * - `//example.com` (missing protocol)
+ * - `example.com` (missing protocol)
+ * - `http://` (missing host)
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const URL_CONSTRAINT = {
+  keyword: 'url',
+  process: (value) => {
+    try {
+      return new URL(value).toString();
+    } catch {
+      throw new ConstraintError('Invalid URL format');
+    }
+  }
+};

package/src/core-library/processors/url-decode-operator.js

@@ -0,0 +1,50 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $url-decode
+ *
+ * Decodes a percent-encoded URL string.
+ *
+ * Use `{$url-decode: {full: true}}` to decode a complete URL (`decodeURI`)
+ * rather than a component (`decodeURIComponent`). Full-URL decoding preserves
+ * sequences that are valid structural URL characters (`%2F` etc.) undecoded.
+ *
+ * Throws if the input is not a string or contains a malformed escape sequence.
+ *
+ * ### Parameters
+ * - `full` (boolean, optional, default `false`): Use full-URL decoding (`decodeURI`) rather than component decoding (`decodeURIComponent`).
+ *
+ * ### Example
+ * ```js
+ * // Decode a percent-encoded query parameter
+ * new Schema('string').normalizer('$url-decode')
+ * // 'hello%20world%20%26%20more' → 'hello world & more'
+ *
+ * // Decode a full URL without decoding structural characters
+ * new Schema('string').normalizer({'$url-decode': {full: true}})
+ * // 'https://example.com/path%20with%20spaces' → 'https://example.com/path with spaces'
+ *
+ * // Decode then validate the result
+ * new Schema('string').normalizer('$url-decode').validator('$non-empty')
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const URL_DECODE_OPERATOR = {
+  keyword: 'url-decode',
+  parameters: [ { parameter: 'full', default: false } ],
+
+  process: (value, _target, location, options) => {
+    if (typeof value !== 'string') {
+      throw new ConstraintError(`$url-decode requires a string, got ${formatValue(value)}`, {location});
+    }
+    const full = options.args?.['full'] ?? false;
+    try {
+      return full ? decodeURI(value) : decodeURIComponent(value);
+    }
+    catch (error) {
+      throw new ConstraintError(`$url-decode: malformed URI sequence — ${error.message}`, {location, cause: error});
+    }
+  }
+};

package/src/core-library/processors/url-encode-operator.js

@@ -0,0 +1,44 @@
+/**
+ * ## $url-encode
+ *
+ * Percent-encodes a string for safe use as a URL component (query param value,
+ * path segment, etc.). Encodes all characters except unreserved URI characters
+ * (`A–Z a–z 0–9 - _ . !  ~ * ' ( )`).
+ *
+ * Use `{$url-encode: {full: true}}` to encode a complete URL instead of a
+ * component — this preserves `://`, `/`, `?`, `&`, `=`, and other structural
+ * characters rather than encoding them.
+ *
+ * Non-string inputs are coerced to string before encoding.
+ *
+ * ### Parameters
+ * - `full` (boolean, optional, default `false`): Use full-URL encoding (`encodeURI`) rather than component encoding (`encodeURIComponent`).
+ *
+ * ### Example
+ * ```js
+ * // Encode a query parameter value
+ * new Schema('string').transformer('$url-encode')
+ * // 'hello world & more' → 'hello%20world%20%26%20more'
+ *
+ * // Encode a full URL, preserving structural characters
+ * new Schema('string').transformer({'$url-encode': {full: true}})
+ * // 'https://example.com/path with spaces' → 'https://example.com/path%20with%20spaces'
+ *
+ * // Build an encoded query string from an object
+ * new Schema('object', {
+ *   q: new Schema('string').transformer('$url-encode'),
+ *   page: new Schema('number'),
+ * })
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const URL_ENCODE_OPERATOR = {
+  keyword: 'url-encode',
+  parameters: [ { parameter: 'full', default: false } ],
+
+  process: (value, _target, _location, options) => {
+    const full = options.args?.['full'] ?? false;
+    return full ? encodeURI(`${value}`) : encodeURIComponent(`${value}`);
+  }
+};

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

@@ -0,0 +1,31 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $uuid
+ *
+ * Validates that a string matches valid UUID format (versions 1-5).
+ * UUIDs must follow RFC 4122 format: 8-4-4-4-12 hexadecimal digits
+ * separated by hyphens.
+ *
+ * - `550e8400-e29b-41d4-a716-446655440000` (v4)
+ * - `6ba7b810-9dad-11d1-80b4-00c04fd430c8` (v1)
+ * - `3d813cbb-47fb-32ba-91df-831e1593ac29` (v3)
+ * - `A6EAFB30-E49B-51D4-9B1D-8F6C0F89E8B3` (case-insensitive)
+ *
+ * - `550e8400-e29b-41d4-a716` (too short)
+ * - `550e8400e29b41d4a716446655440000` (missing hyphens)
+ * - `550e8400-e29b-61d4-a716-446655440000` (invalid version digit)
+ * - `not-a-valid-uuid-string`
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const UUID_CONSTRAINT = {
+  keyword: 'uuid',
+  process: (value) => {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    if (!uuidRegex.test(value)) {
+      throw new ConstraintError('Invalid UUID format');
+    }
+    return value;
+  }
+};

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

@@ -0,0 +1,20 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $values
+ *
+ * Returns the enumerable own property values of an object as an array.
+ * Throws if the input is not a plain object.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const VALUES_OPERATOR = {
+  keyword: 'values',
+  process: (value, _target, location) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      throw new ConstraintError(`$values requires a plain object, got ${formatValue(value)}`, {location});
+    }
+    return Object.values(value);
+  }
+};

package/src/core-library/schemas/any-schema.js

@@ -0,0 +1,23 @@
+import { SchemaLocation } from "../../schema-location.js";
+import { Schema } from '../../schema.js';
+import { hasStringProperties } from '../../helpers/has-string-properties.js';
+import { EMPTY } from '../../constants.js';
+
+/**
+ * @param {any} value
+ * @param {any} _
+ * @param {SchemaLocation} location
+ * @returns {any}
+ */
+function anyValueProcessor(value, _, location) {
+  const schema = location.schema;
+  if (value === EMPTY && schema.isContainer) {
+    return (!schema.isArray && hasStringProperties(schema))? {} : [];
+  }
+  return value;
+}
+
+export const ANY_SCHEMA = new Schema()
+  .option('type', 'any')
+  .normalizer(anyValueProcessor)
+  .transformer(anyValueProcessor)

package/src/core-library/schemas/array-schema.js

@@ -0,0 +1,8 @@
+import { Schema } from '../../schema.js';
+
+export const ARRAY_SCHEMA = new Schema()
+  .option('type', 'array')
+  .option('container', true)
+  .normalizer('$array')
+//  .transformer('$array')
+  .validator('$is-array')

package/src/core-library/schemas/boolean-schema.js

@@ -0,0 +1,10 @@
+import { Schema } from '../../schema.js';
+import { isTruthy } from '../../helpers/truthy.js';
+
+export const BOOLEAN_SCHEMA = new Schema()
+  .option('type', 'boolean')
+  .meta('valueName', 'boolean')
+  .normalizer(isTruthy)
+  .validator({$in: [true, false]})
+
+

package/src/core-library/schemas/date-schema.js

@@ -0,0 +1,12 @@
+import { Schema } from '../../schema.js';
+
+export const DATE_SCHEMA = new Schema()
+  .option('type', 'date')
+  .meta('parserTypeHint', 'string')
+  .meta('valueName', 'date')
+  .meta('valueDescription', 'ms|iso date|"now"|[+|-]offset[d|h|m|s|ms]')
+  .normalizer('$date')
+  .transformer('$date')
+  .validator('$is-date')
+  .serializer('$is-date')
+  .serializer('$string')

package/src/core-library/schemas/function-schema.js

@@ -0,0 +1,40 @@
+import { Schema } from '../../schema.js';
+import { deepValue } from '../../helpers/deep.js';
+
+
+import { ConstraintError } from '../../errors.js';
+
+export const FUNCTION_SCHEMA = new Schema()
+  .option('type', 'function')
+  .meta('parserTypeHint', 'string')
+  .meta('hidden')
+  .meta('internal')
+  .meta('omitFromSerialize')
+  .option('dynamic', false)
+  .normalizer((value) => {
+    if (typeof value === 'function' || typeof value === 'string') {
+      return value;
+    }
+    throw new ConstraintError('Invalid function', {value})
+  })
+  .transformer((value, result) => {
+    if (typeof value === 'string') {
+      value = deepValue(result, value);  // look up the string as a reference in the current target
+    }
+    if (typeof value === 'function') {
+      return value;
+    }
+    throw new ConstraintError('Invalid function', {value});
+  })
+  .validator(value => {
+    if (typeof value === 'function') {
+      return value;
+    }
+    throw new ConstraintError('Invalid function', {value});
+  })
+  .serializer((value) => {
+    if (typeof value === 'function') {
+      return value.name;
+    }
+    throw new ConstraintError('Invalid function', {value})
+  })

package/src/core-library/schemas/number-schema.js

@@ -0,0 +1,9 @@
+import { Schema } from '../../schema.js';
+
+export const NUMBER_SCHEMA = new Schema()
+  .option('type', 'number')
+  .meta('valueName', 'number')
+  .normalizer('$number')
+  //.transformer('$number')
+  .validator('$is-number')
+

package/src/core-library/schemas/object-schema.js

@@ -0,0 +1,10 @@
+import { Schema } from '../../schema.js';
+
+export const OBJECT_SCHEMA = new Schema()
+  .option('type', 'object')
+  .option('container', true)
+  .meta('valueName', 'object')
+  .normalizer('$object')
+//  .transformer('$object')
+  .validator('$is-object')
+

package/src/core-library/schemas/root-schema.js

@@ -0,0 +1,21 @@
+import { Schema } from '../../schema.js';
+
+export const ROOT_SCHEMA = new Schema()
+  .default(true)
+  .meta('hidden')
+  .meta('internal')
+  .meta('omitFromSerialize')
+  .normalizer(() => 'root-schema')
+  .transformer((_v, _c, location) => {
+    while (location?.parent) {
+      location = location.parent;
+    }
+    return location?.schema;
+  })
+  .serializer((_v, _c, location) => {
+    while (location?.parent) {
+      location = location.parent;
+    }
+    return location?.schema.toData();
+  })
+

package/src/core-library/schemas/string-schema.js

@@ -0,0 +1,9 @@
+import { Schema } from '../../schema.js';
+
+export const STRING_SCHEMA = new Schema()
+  .option('type', 'string')
+  .meta('valueName', 'string')
+  .normalizer('$string')
+//  .transformer('$string')
+  .validator('$is-string')
+

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

@@ -0,0 +1,47 @@
+import { BUFFER_SCHEMA } from './schemas/buffer-schema.js';
+
+/** @import { ValueProcessorDefinition } from '../value-processor/value-processor.js' */
+/** @import { SchemaResolver } from '../schema-resolver.js' */
+
+let modules;
+try {
+  modules ??= await Promise.all([
+    import('./processors/base64-decode-operator.js'),
+    import('./processors/base64-encode-operator.js'),
+    import('./processors/buffer-operator.js'),
+    import('./processors/directory-constraint.js'),
+    import('./processors/executable-constraint.js'),
+    import('./processors/file-constraint.js'),
+    import('./processors/file-size-constraint.js'),
+    import('./processors/is-buffer-constraint.js'),
+    import('./processors/readable-constraint.js'),
+    import('./processors/reachable-constraint.js'),
+    import('./processors/writable-constraint.js'),
+  ]);
+}
+catch (error) {
+  throw new Error('Failed to load Node.js processors', { cause: error });
+}
+
+/** @type {ValueProcessorDefinition[]} */
+const NODE_PROCESSORS = modules.flatMap(
+  ns => Object.values(ns).filter(v => v && typeof v.keyword === 'string')
+);
+
+/**
+ * Node.js-specific schemas and processors.
+ *
+ * Loaded automatically when running under Node.js.  Registers the `buffer`
+ * schema type and processors that depend on `node:fs`, `node:dns`, or the
+ * Node.js `Buffer` global.
+ *
+ * @param {SchemaResolver} resolver
+ * @param {object} options
+ */
+export default function coreLibraryNode(resolver, options) {
+  resolver.registerSchema('buffer', BUFFER_SCHEMA);
+
+  for (const definition of NODE_PROCESSORS) {
+    resolver.registerValueProcessorDefinition(definition);
+  }
+}

package/src/core-library-node/processors/base64-decode-operator.js

@@ -0,0 +1,20 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $base64-decode
+ *
+ * Decodes a Base64-encoded string to a Buffer.
+ * Throws if the input is not a string.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const BASE64_DECODE_OPERATOR = {
+  keyword: 'base64-decode',
+  process: (value, _target, location) => {
+    if (typeof value !== 'string') {
+      throw new ConstraintError(`$base64-decode requires a string, got ${formatValue(value)}`, {location});
+    }
+    return Buffer.from(value, 'base64');
+  }
+};

package/src/core-library-node/processors/base64-encode-operator.js

@@ -0,0 +1,20 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $base64-encode
+ *
+ * Encodes a Buffer to a Base64 string.
+ * Throws if the input is not a Buffer.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const BASE64_ENCODE_OPERATOR = {
+  keyword: 'base64-encode',
+  process: (value, _target, location) => {
+    if (!Buffer.isBuffer(value)) {
+      throw new ConstraintError(`$base64-encode requires a Buffer, got ${formatValue(value)}`, {location});
+    }
+    return value.toString('base64');
+  }
+};