@versionzero/schema 1.0.0

package/src/core-library-node/processors/buffer-operator.js

@@ -0,0 +1,39 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $buffer
+ *
+ * Converts a value to a Node.js Buffer.  Accepts:
+ * - `Buffer` — passed through unchanged
+ * - `string` — decoded from Base64 via `Buffer.from(value, 'base64')`
+ * - `{size, fill?, encoding?}` — allocated via `Buffer.alloc(size, fill, encoding)`
+ * - `{encoding, buffer}` — constructed from an underlying ArrayBuffer via `Buffer.from(value.buffer)`
+ * - anything else (TypedArray, byte array, etc.) — via `Buffer.from(value)`
+ *
+ * See `$is-buffer` for strict Buffer validation without conversion.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const BUFFER_OPERATOR = {
+  keyword: 'buffer',
+  process: (value) => {
+    if (Buffer.isBuffer(value)) {
+      return value;
+    }
+    try {
+      if (typeof value === 'string') {
+        return Buffer.from(value, 'base64');
+      }
+      if (typeof value === 'object' && Number.isInteger(value?.size)) {
+        return Buffer.alloc(value.size, value.fill ?? 0, value.encoding ?? 'utf8');
+      }
+      if (typeof value === 'object' && value?.encoding !== undefined) {
+        return Buffer.from(value.buffer, value.encoding);
+      }
+      return Buffer.from(value);
+    }
+    catch (error) {
+      throw new ConstraintError('Buffer array contains invalid data', {cause: error});
+    }
+  }
+};

package/src/core-library-node/processors/directory-constraint.js

@@ -0,0 +1,35 @@
+import * as fs from 'node:fs/promises';
+
+
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $directory
+ *
+ * Validates that a path exists on the filesystem and is a directory (not a file).
+ * This is an **async processor** that performs filesystem operations.
+ *
+ * The processor checks both existence and type, throwing distinct errors for:
+ * - Path does not exist (`ENOENT`)
+ * - Path exists but is a file, symlink, or other non-directory type
+ * - Path is inaccessible due to permissions or other filesystem errors
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const DIRECTORY_CONSTRAINT = {
+  keyword: 'directory',
+  process: async (value) => {
+    try {
+      const stat = await fs.stat(value);
+      if (!stat.isDirectory()) {
+        throw new ConstraintError('Path exists but is not a directory');
+      }
+      return value;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new ConstraintError('Directory does not exist');
+      }
+      throw new ConstraintError(`Cannot access directory: ${error.message}`);
+    }
+  }
+};

package/src/core-library-node/processors/executable-constraint.js

@@ -0,0 +1,34 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+
+
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $executable
+ *
+ * Validates that a file path points to an executable file by checking execute
+ * permissions. This is an asynchronous processor that performs a file system
+ * access check.
+ *
+ * This processor is particularly useful for validating script paths, binary
+ * paths, and command executables in configuration files.
+ *
+ * **Note**: This processor performs async file system checks and should usually
+ * be used as a validator. Execution permissions are platform-dependent (Unix/Linux/macOS
+ * use chmod +x; Windows uses file extensions and ACLs).
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const EXECUTABLE_CONSTRAINT = {
+  keyword: 'executable',
+  process: async (value) => {
+    try {
+      await fs.access(value, constants.X_OK);
+      return value;
+    } catch {
+      throw new ConstraintError('File is not executable');
+    }
+  },
+  description: 'path'
+};

package/src/core-library-node/processors/file-constraint.js

@@ -0,0 +1,34 @@
+import * as fs from 'node:fs/promises';
+
+
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $file
+ *
+ * Validates that a path exists in the filesystem and is a file (not a directory or other type).
+ * Performs an asynchronous filesystem check using `fs.stat()`.
+ *
+ * - Non-existent paths: `"/does/not/exist.txt"` → throws "File does not exist"
+ * - Directory paths: `"/var/log"` → throws "Path exists but is not a file"
+ * - Inaccessible paths: `"/root/secret.txt"` (permission denied) → throws "Cannot access file: ..."
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const FILE_CONSTRAINT = {
+  keyword: 'file',
+  process: async (value) => {
+    try {
+      const stat = await fs.stat(value);
+      if (!stat.isFile()) {
+        throw new ConstraintError('Path exists but is not a file');
+      }
+      return value;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new ConstraintError('File does not exist');
+      }
+      throw new ConstraintError(`Cannot access file: ${error.message}`);
+    }
+  }
+};

package/src/core-library-node/processors/file-size-constraint.js

@@ -0,0 +1,94 @@
+import * as fs from 'node:fs/promises';
+import { ConstraintError, ResolverError } from '../../errors.js';
+
+/**
+ * ## $file-size
+ *
+ * Validates that a file's size falls within the specified range. Accepts size constraints
+ * in bytes and checks the file's metadata without loading the entire file into memory.
+ * Can specify minimum, maximum, or both bounds.
+ *
+ * **This is an async processor** that performs filesystem I/O, and probably best suited
+ * for use during transformation or validation phases.
+ *
+ * ### Parameters
+ * - `min` (number, optional): Minimum file size in bytes (inclusive). If omitted, no lower bound.
+ * - `max` (number, optional): Maximum file size in bytes (inclusive). If omitted, no upper bound.
+ *
+ * **Unit Conversions**: Size must be specified in bytes. Use standard conversions:
+ * - 1 KB = 1024 bytes
+ * - 1 MB = 1024 * 1024 bytes (1,048,576)
+ * - 1 GB = 1024 * 1024 * 1024 bytes (1,073,741,824)
+ *
+ * **Note**: Typically used with `$file` validator to ensure the file exists before checking size.
+ * The processor reads file metadata via `fs.stat()` and does not load file contents.
+ *
+ * ### Example
+ * ```js
+ * // Validate a config file exists and is under 1 MB
+ * new Schema('string')
+ *   .validator('$file')
+ *   .validator({'$file-size': {max: 1024 * 1024}})
+ *
+ * // Require an upload file to be between 1 KB and 10 MB
+ * new Schema('string')
+ *   .validator('$file')
+ *   .validator({'$file-size': {min: 1024, max: 10 * 1024 * 1024}})
+ *
+ * // Ensure a log file is not empty
+ * new Schema('string')
+ *   .validator('$file')
+ *   .validator({'$file-size': {min: 1}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const FILE_SIZE_CONSTRAINT = {
+  keyword: 'file-size',
+  parameters: [ { parameter: 'min', type: 'number', default: undefined }, { parameter: 'max', type: 'number', default: undefined } ],
+
+  process: async (value, _target, _location, options) => {
+
+    const min = options.args.min;
+    const max = options.args.max;
+
+    try {
+      const stat = await fs.stat(value);
+      const size = stat.size;
+
+      if (min !== undefined && size < min) {
+        throw new ConstraintError(`File size must be at least ${min} bytes`);
+      }
+      if (max !== undefined && size > max) {
+        throw new ConstraintError(`File size must be at most ${max} bytes`);
+      }
+      return value;
+    } catch (error) {
+      if (error instanceof ConstraintError) {
+        throw error;
+      }
+      throw new ConstraintError(`Cannot access file: ${error.message}`);
+    }
+  },
+  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 min = minProcessor?.description;
+    const max = maxProcessor?.description;
+
+    return min !== undefined && max !== undefined
+           ? `${min}-${max}B`
+           : min !== undefined
+             ? `≥${min}B`
+             : max !== undefined
+               ? `≤${max}B`
+               : undefined
+  }
+
+};

package/src/core-library-node/processors/is-buffer-constraint.js

@@ -0,0 +1,21 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $is-buffer
+ *
+ * Validates that the input is a Node.js Buffer.
+ *
+ * See `$buffer` for looser normalization that accepts values that can be converted to a Buffer.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const IS_BUFFER_CONSTRAINT = {
+  keyword: 'is-buffer',
+  process: (value) => {
+    if (Buffer.isBuffer(value)) {
+      return value;
+    }
+    throw new ConstraintError('Must be a Buffer');
+  },
+  description: ''
+};

package/src/core-library-node/processors/reachable-constraint.js

@@ -0,0 +1,28 @@
+import { lookup } from 'node:dns/promises';
+
+
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $reachable
+ *
+ * Validates that a hostname is reachable by performing a DNS lookup.
+ * This is an asynchronous processor that checks if the hostname resolves to an IP address.
+ *
+ * Note: This processor performs a network operation and may fail if DNS is unavailable
+ * or the hostname does not exist. It does not verify that the host is responding on any port,
+ * only that it has a DNS record.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const REACHABLE_CONSTRAINT = {
+  keyword: 'reachable',
+  process: async (value) => {
+    try {
+      await lookup(value);
+      return value;
+    } catch {
+      throw new ConstraintError('Host is not reachable');
+    }
+  }
+};

package/src/core-library-node/processors/readable-constraint.js

@@ -0,0 +1,34 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+
+
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $readable
+ *
+ * Validates that a file or directory path exists and has read permissions for the
+ * current process. Performs an asynchronous file system access check.
+ *
+ * This processor uses Node.js `fs.access()` with `R_OK` flag to verify read permissions
+ * without actually opening the file. Note that permission checks can be subject to race
+ * conditions where permissions change between validation and actual file access.
+ *
+ * (e.g., `"/etc/hosts"`, `"./config.json"`, `"~/Documents"`)
+ *
+ * or non-string values
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const READABLE_CONSTRAINT = {
+  keyword: 'readable',
+  process: async (value) => {
+    try {
+      await fs.access(value, constants.R_OK);
+      return value;
+    } catch {
+      throw new ConstraintError('File is not readable');
+    }
+  },
+  description: 'path'
+};

package/src/core-library-node/processors/writable-constraint.js

@@ -0,0 +1,59 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+
+
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $writable
+ *
+ * Validates that a file system path is writable by checking write permissions.
+ * If the path does not exist, validates that the parent directory exists and is writable.
+ *
+ * This is an asynchronous processor that performs file system permission checks.
+ *
+ * - Existing files with write permissions: `/tmp/output.log`, `./config.json`
+ * - Non-existent paths in writable directories: `/tmp/new-file.txt`, `./data/output.csv`
+ *
+ * - Read-only files: `/etc/hosts`, system-protected paths
+ * - Paths in non-existent parent directories: `/nonexistent/dir/file.txt`
+ * - Paths in read-only directories: `/read-only-mount/file.txt`
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const WRITABLE_CONSTRAINT = {
+  keyword: 'writable',
+  process: async (value) => {
+    try {
+      // Try to access the file
+      await fs.access(value, constants.W_OK);
+      return value;
+    } catch (error) {
+      // File doesn't exist or isn't writable
+      if (error.code === 'ENOENT') {
+        // File doesn't exist - check if parent directory is writable
+        const path = await import('node:path');
+        const parentDir = path.dirname(value);
+
+        try {
+          const stat = await fs.stat(parentDir);
+          if (!stat.isDirectory()) {
+            throw new ConstraintError('Parent path exists but is not a directory');
+          }
+          await fs.access(parentDir, constants.W_OK);
+          return value; // Parent is writable
+        } catch (parentError) {
+          if (parentError.code === 'ENOENT') {
+            throw new ConstraintError('Parent directory does not exist');
+          }
+          else if (parentError instanceof ConstraintError) {
+            throw parentError;
+          }
+          throw new ConstraintError('Parent directory is not writable');
+        }
+      }
+      throw new ConstraintError('File is not writable');
+    }
+  },
+  description: 'path'
+};

package/src/core-library-node/schemas/buffer-schema.js

@@ -0,0 +1,10 @@
+import { Schema } from '../../schema.js';
+
+export const BUFFER_SCHEMA = new Schema()
+  .option('type', 'buffer')
+  .meta('valueName', 'buffer')
+  .meta('parserTypeHint', 'string')
+  .normalizer('$buffer')
+  .transformer('$buffer')
+  .validator('$is-buffer')
+  .serializer('$base64-encode')

package/src/errors.js

@@ -0,0 +1,209 @@
+import { SchemaLocation } from "./schema-location.js";
+import { formatValue } from './helpers/format.js';
+
+
+/**
+ * Format a location/path (possibly with property), typically for error messages.
+ *
+ * @param {string} message
+ * @param {string|undefined} where - path
+ * @param {string|number} [property]
+ * @param {string} [prep]
+ * @returns {string}
+ * @internal
+ */
+function fpm(message, where, property, prep = 'at') {
+
+  if (where === '') {
+    where = '(root)'
+  }
+  else if (where){
+    where = `"${where}"`
+  }
+
+  if (property) {
+    where = where? `${where} property "${property}"` : `property "${property}"`;
+  }
+
+  let m = message;
+
+  if (where) {
+    m += ` ${prep} ${where}`;
+  }
+
+  return m;
+}
+
+/**
+ * @param {string} message
+ * @param {any} value
+ * @param {string|undefined} where
+ * @param {string|number} [property]
+ * @param {string} [prep]
+ * @returns {string}
+ * @internal
+ */
+function fpvm(message, value, where, property, prep) {
+  /** @type {string|undefined} */
+  const valueString = formatValue(value);
+
+  if (valueString?.length) {
+    message = `${message} with value ${valueString}`;
+  }
+  return fpm(message, where, property,  prep);
+}
+
+export class SchemaError extends Error {
+  /**
+   * @param {string} message
+   * @param {object} [data]
+   * @param {Error|any} [data.cause]
+   * @param {string} [data.path]
+   * @param {SchemaLocation} [data.location]
+   * @param {string|number} [data.property]
+   * @param {any} [data.value]
+   * @param {number} [data.code]
+   * @param {Array<Error>} [data.errors]
+   * @param {boolean} [preserveStack]
+   */
+  constructor(message, data, preserveStack = false) {
+    // noinspection JSCheckFunctionSignatures
+
+    /** @type {Error|undefined} */
+    const cause = data?.cause
+      ? data.cause instanceof Error
+        ? data.cause
+        : new SchemaError(data.cause, undefined, false)
+      : undefined;
+
+    const path = data?.path ?? data?.location?.path ?? data?.cause?.path ?? data?.cause?.location?.path;
+    const property = data?.property;
+
+    if (!message?.length && cause?.message) {
+      message = cause.message;
+    }
+
+    if (!path || message.indexOf(path) === -1) {
+      if (data?.hasOwnProperty('value')) {
+        message = fpvm(message, data?.value, path, property);
+      }
+      else {
+        message = fpm(message, path, property);
+      }
+    }
+
+    super(message, cause ? { cause } : undefined);
+
+    if (data) {
+      /** @type {any} */
+      this.data = { ...data, cause };
+    }
+    // restore prototype chain
+    const actualProto = new.target.prototype;
+
+    if (Object.setPrototypeOf) {
+      Object.setPrototypeOf(this, actualProto);
+    } else {
+      // @ts-ignore
+      this.__proto__ = actualProto;
+    }
+
+    if (!preserveStack) {
+//       @ts-ignore
+       delete this.stack;
+    }
+
+    if (data?.cause && !super.cause) {
+      // should be set on super, but just in case...
+      this.cause = data.cause;
+    }
+  }
+
+  get name() {
+    return this.constructor.name;
+  }
+  get stack() {
+    return "";
+  }
+
+  set stack(str) {}
+
+  //  get cause() {
+  //    return super.cause ?? this.data?.cause;
+  //  }
+
+  toString() {
+    if (this.message) {
+      return `${this.name}: ${this.message}`;
+    } else {
+      // @ts-ignore
+      if (this.cause?.message) {
+        // @ts-ignore
+        return `${this.name}: ${this.cause.message}`;
+      } else {
+        return this.name;
+      }
+    }
+  }
+}
+
+/**
+ * @param {Error} error
+ * @param {RegExp|string} match
+ * @param {string} [fullErrorMessage]
+ * @param {Error} [err]
+ * @returns {boolean}
+ * @internal
+ */
+export function assertErrorMessageInCauseChain(error, match, fullErrorMessage, err) {
+
+  if (err === undefined) {
+    err = new Error('message not found in cause chain');
+  }
+
+  const errorMessage = (error?.message ?? '');
+
+  fullErrorMessage = fullErrorMessage? `${fullErrorMessage} «${errorMessage}»` : `«${errorMessage}»`;
+
+  if (match instanceof RegExp && match.test(errorMessage)) {
+    return true;
+  }
+  else if (errorMessage.toLowerCase() === `${match}`.toLowerCase()) {
+    return true;
+  }
+  else if (error.cause instanceof Error) {
+    return assertErrorMessageInCauseChain(error.cause, match, fullErrorMessage, err );
+  }
+  else {
+    err.message = `«${match}» not found in cause chain ${fullErrorMessage}`;
+    throw err;
+  }
+}
+
+
+export class ConstraintError
+  extends SchemaError {}
+
+export class ValidationError
+  extends SchemaError {}
+
+export class NormalizeError
+  extends SchemaError {}
+
+export class TransformError
+  extends SchemaError {}
+
+export class FinalizeError
+  extends SchemaError {}
+
+export class SerializeError
+  extends SchemaError {}
+
+export class UnionResolutionError
+  extends SchemaError {}
+
+export class ResolverError
+  extends SchemaError {}
+
+export class SchemaCompilationError
+  extends SchemaError {}

package/src/executor/array-executor.js

@@ -0,0 +1,78 @@
+import { Executor, toExecutor } from './executor.js';
+
+/**
+ * @augments {Executor<any>}
+ */
+export class ArrayExecutor extends Executor {
+
+  /** @type {Executor<any>[]} */
+  #executors = [];
+
+  /** @type {any} */
+  #constantValue;
+
+  /**
+   * @param {any[]|any} [array]
+   */
+  constructor(array = []) {
+    if (!Array.isArray(array)) {
+      array = [array];
+    }
+    super();
+
+    let isConstant = true;
+    for (const item of array) {
+      const itemExecutor = toExecutor(item);
+      isConstant &&= itemExecutor.isConstant;
+      this.#executors.push(itemExecutor);
+    }
+    this.#constantValue = isConstant ? this.#executors.map(executor => executor.execute(true)) : undefined;
+  }
+  /**
+   * @param {any} input
+   * @param {...any} extra
+   * @returns {any[]|Promise<any[]>}
+   */
+  execute(input, ...extra) {
+    if (this.#constantValue !== undefined) {
+      return this.#constantValue;
+    }
+    const output = [];
+    let current = 0;
+
+    const executors = this.#executors;
+
+    while (current < executors.length) {
+      const result = executors[current++].execute(input, ...extra);
+
+      if (result instanceof Promise) {
+        return result.then(resolved => {
+          output.push(resolved);
+          return this.#resume(input, extra, current, output)
+        })
+      }
+      else {
+        output.push(result);
+      }
+    }
+    return output;
+  }
+
+  /**
+   * @param {any} input
+   * @param {any[]} extra
+   * @param {number} resumeIndex
+   * @param {Array<any>} output
+   * @returns {Promise<any[]>}
+   */
+  async #resume(input, extra, resumeIndex, output) {
+    while (resumeIndex < this.#executors.length) {
+      output.push(await this.#executors[resumeIndex++].execute(input, ...extra));
+    }
+    return output;
+  }
+
+  get isConstant() {
+    return this.#constantValue !== undefined;
+  }
+}