@versionzero/schema 1.0.0

package/src/executor/sequence-executor.js

@@ -0,0 +1,206 @@
+import { Executor, toExecutor } from './executor.js';
+import { isTruthy } from '../helpers/truthy.js';
+
+/**
+ * Call a sequence of executors on the input until one returns a truthy value.  Exceptions/rejections are caught and
+ * interpreted as a falsey value.  Return the first successful truthy result, or undefined on failure.
+ *
+ * @template T
+ * @augments {Executor<T>}
+ */
+export class SequenceExecutor extends Executor {
+  #executors;
+
+  #criteriaBehavior;
+  #checkBehavior;
+  #returnBehavior;
+  #errorBehavior;
+
+  /**
+   * @param {Array<any>|any} [executors]
+   * @param {symbol[]} [flags]
+   */
+  constructor(executors = [], flags = []) {
+    if (!Array.isArray(executors)) {
+      executors = [executors];
+    }
+    super();
+    this.#executors = executors.map((/** @type {any} */ item) => toExecutor(item));
+
+    for (const flag of flags) {
+      if (flag === SequenceExecutor.ALL_CRITERIA) {
+        this.#criteriaBehavior = flag;
+      }
+      else if (flag === SequenceExecutor.ANY_CRITERIA) {
+        this.#criteriaBehavior = flag;
+      }
+      else if (flag === SequenceExecutor.EXCLUSIVE_CRITERIA) {
+        this.#criteriaBehavior = flag;
+      }
+      else if (flag === SequenceExecutor.SUCCESS_CHECK) {
+        this.#checkBehavior = flag;
+      }
+      else if (flag === SequenceExecutor.DEFINED_CHECK) {
+        this.#checkBehavior = flag;
+      }
+      else if (flag === SequenceExecutor.TRUTHY_CHECK) {
+        this.#checkBehavior = flag;
+      }
+      else if (flag === SequenceExecutor.INPUT_RETURN) {
+        this.#returnBehavior = flag;
+      }
+      else if (flag === SequenceExecutor.RESULT_RETURN) {
+        this.#returnBehavior = flag;
+      }
+      else if (flag === SequenceExecutor.RETHROW_ERRORS) {
+        this.#errorBehavior = flag;
+      }
+      else if (flag === SequenceExecutor.CAPTURE_ERRORS) {
+        this.#errorBehavior = flag;
+      }
+      else {
+        throw new Error(`Unknown flag`);
+      }
+    }
+
+    this.#criteriaBehavior ??= SequenceExecutor.ALL_CRITERIA;
+    this.#checkBehavior ??= SequenceExecutor.SUCCESS_CHECK;
+    this.#returnBehavior ??= SequenceExecutor.INPUT_RETURN;
+    this.#errorBehavior ??= SequenceExecutor.RETHROW_ERRORS;
+  }
+  /**
+   * @param {any} input
+   * @param {...any} extra
+   * @returns {T|null|undefined|Promise<T|null|undefined>}
+   */
+  execute(input, ...extra) {
+    let lastResult = undefined;
+    let successCount = 0;
+    let failureCount = 0;
+    let current = 0;
+
+    const criteriaSatisfied = () => {
+      switch(this.#criteriaBehavior) {
+        case SequenceExecutor.ANY_CRITERIA:       return successCount > 0;
+        case SequenceExecutor.EXCLUSIVE_CRITERIA: return successCount === 1 && current === this.#executors.length;
+        case SequenceExecutor.ALL_CRITERIA:       return successCount === this.#executors.length;
+      }
+      return false;
+    }
+
+    const criteriaFailed = () => {
+      switch (this.#criteriaBehavior) {
+        case SequenceExecutor.ANY_CRITERIA:       return successCount === 0 && current === this.#executors.length;
+        case SequenceExecutor.EXCLUSIVE_CRITERIA: return successCount > 1;
+        case SequenceExecutor.ALL_CRITERIA:       return failureCount > 0;
+      }
+      return false;
+    }
+    /**
+     * @returns {Promise<any>}
+     */
+    const resume = async () => {
+      while (current < this.#executors.length) {
+        if (criteriaFailed() || criteriaSatisfied()) {
+          break;
+        }
+        try {
+          const result = await this.#executors[current++].execute(input, ...extra);
+          handleResult(result);
+        }
+        catch (error) {
+          if (this.#checkBehavior === SequenceExecutor.SUCCESS_CHECK) {
+            return undefined;
+          }
+          handleFailure(error);
+        }
+      }
+      return finalResult();
+    }
+
+
+    /** @param {any} result */
+    const handleResult = (result) => {
+      const success = this.#checkBehavior === SequenceExecutor.TRUTHY_CHECK
+                      ? isTruthy(result)
+                      : this.#checkBehavior === SequenceExecutor.DEFINED_CHECK
+                        ? result !== undefined
+                        : true;
+
+      if (success) {
+        successCount++;
+      }
+      else {
+        failureCount++;
+      }
+
+      if (!criteriaFailed()) {
+        lastResult = result;
+      }
+    }
+    /** @param {Error} error */
+    const handleFailure = (error) => {
+      if (this.#errorBehavior === SequenceExecutor.RETHROW_ERRORS) {
+        throw error;
+      }
+      // an exception/rejection fails all three check types.
+      failureCount++;
+    }
+
+    const finalResult = () => {
+      if (criteriaSatisfied()) {
+        return this.#returnBehavior === SequenceExecutor.RESULT_RETURN ? lastResult : input;
+      }
+      return undefined;
+    }
+
+    const executors = this.#executors;
+
+    while (current < executors.length) {
+      let result;
+      try {
+        result = executors[current++].execute(input, ...extra);
+        if (result instanceof Promise) {
+          return result.then(
+            resolved => {
+              handleResult(resolved);
+              return resume();
+            },
+            rejected => {
+              handleFailure(rejected);
+              return resume();
+            })
+        }
+        handleResult(result);
+      }
+      catch (error) {
+        handleFailure(error);
+        if (this.#checkBehavior === SequenceExecutor.SUCCESS_CHECK) {
+          return undefined;
+        }
+      }
+
+      if (criteriaFailed() || criteriaSatisfied()) {
+        break;
+      }
+    }
+    return finalResult();
+  }
+
+
+  static ANY_CRITERIA = Symbol('ANY-CRITERIA');
+  static ALL_CRITERIA = Symbol('ALL-CRITERIA');
+  static EXCLUSIVE_CRITERIA = Symbol('EXCLUSIVE-CRITERIA');
+
+  static TRUTHY_CHECK = Symbol('TRUTHY-CHECK');
+  static DEFINED_CHECK = Symbol('DEFINED-CHECK');
+  static SUCCESS_CHECK = Symbol('SUCCESS-CHECK');
+
+  static RESULT_RETURN = Symbol('RESULT-RETURN');
+  static INPUT_RETURN = Symbol('INPUT-RETURN');
+
+//  static THROW_ERRORS = Symbol('THROW-ERRORS');  // todo - consider throwing on undefined in handleResult?
+  static RETHROW_ERRORS = Symbol('RETHROW-ERRORS');
+  static CAPTURE_ERRORS = Symbol('CAPTURE-ERRORS');
+
+}

package/src/executor/serial-executor.js

@@ -0,0 +1,24 @@
+import { SequenceExecutor } from './sequence-executor.js';
+
+/**
+ * Executes a fixed sequence of executors serially, passing each same input value and variadic arguments.
+ * and returning the original input value on success.  This executor is intended for side-effect-style composition;
+ * for chained processing, see `PipelineExecutor` or `StepExecutor`.  See `SequenceExecutor` to allow fine
+ * tuning of sequence execution behavior.
+ *
+ * @template T
+ * @augments {SequenceExecutor<T>}
+ */
+export class SerialExecutor extends SequenceExecutor {
+  /**
+   * @param {any[]|any} [serial]
+   */
+  constructor(serial = []) {
+    if (!Array.isArray(serial)) {
+      serial = [serial];
+    }
+
+    super(serial)
+  }
+}
+

package/src/executor/step-executor.js

@@ -0,0 +1,68 @@
+import { Executor, toExecutor } from './executor.js';
+
+
+/**
+ * StepExecutor is basically like PipelineExecutor, except that null or undefined step results are returned immediately.
+ *
+ * @template T
+ * @augments {Executor<T>}
+ */
+export class StepExecutor extends Executor {
+
+  #steps;
+
+  /**
+   * @param {Array<any>|any} steps - executors/functions/values to execute as a pipeline
+   */
+  constructor(steps = []) {
+    if (!Array.isArray(steps)) {
+      steps = [steps]
+    }
+    super();
+    this.#steps = steps.map((/** @type {any} */ item) => toExecutor(item));
+  }
+
+  /**
+   * @param {T|null|undefined} value
+   * @param {...any} variadic
+   * @returns {T|null|undefined|Promise<T|null|undefined>}
+   */
+  execute(value, ...variadic) {
+    if (value === null || value === undefined) {
+      return value;
+    }
+    let current = 0;
+
+    const steps = this.#steps;
+
+    while (current < steps.length) {
+      value = steps[current++].execute(value, ...variadic);
+
+      if (value === null || value === undefined) {
+        return value;
+      }
+
+      if (value instanceof Promise) {
+        return value.then(resolved => this.#resume(resolved, variadic, current));
+      }
+    }
+    return value;
+  }
+
+  /**
+   * @param {T|null|undefined} value
+   * @param {any[]} variadic
+   * @param {number} resumeIndex
+   * @returns {Promise<T|null|undefined>}
+   */
+  async #resume(value, variadic, resumeIndex) {
+    while (resumeIndex < this.#steps.length) {
+      if (value === null || value === undefined) {
+        return value;
+      }
+      value = await this.#steps[resumeIndex++].execute(value, ...variadic);
+    }
+    return value;
+  }
+}
+

package/src/helpers/case.js

@@ -0,0 +1,124 @@
+/**
+ * @param {string} str
+ * @returns {string[]}
+ */
+function normalizeToWords(str) {
+  // Handle empty or non-string input
+  if (!str || typeof str !== 'string') {
+    return [];
+  }
+
+  // Split on common delimiters and word boundaries
+  return str
+    // Split on non-alphanumeric characters (handles kebab-case, snake_case, etc.)
+    .split(/[^a-zA-Z0-9]+/)
+    // Split on lowercase-to-uppercase transitions (but not uppercase-to-uppercase)
+    .flatMap(part => part.split(/(?<=[a-z])(?=[A-Z])/))
+    .flatMap(part => part.split(/(?<=[0-9])(?=[A-Za-z])/))
+    // Filter out empty strings and convert to lowercase
+    .filter(word => word.length > 0)
+    .map(word => word.toLowerCase());
+}
+
+// Convert normalized words array to camelCase
+function wordsToCamelCase(words) {
+  if (words.length === 0) {
+    return '';
+  }
+  return words[0] + words.slice(1).map(word =>
+         word.charAt(0).toUpperCase() + word.slice(1)
+  ).join('');
+}
+
+// Convert normalized words array to camelCase
+function wordsToPascalCase(words) {
+  if (words.length === 0) {
+    return '';
+  }
+  return words.map(word =>
+    word.charAt(0).toUpperCase() + word.slice(1)
+  ).join('');
+}
+
+function wordsToCapitalize(words) {
+  if (words.length === 0) {
+    return '';
+  }
+  return words.map(word =>
+    word.charAt(0).toUpperCase() + word.slice(1)
+  ).join(' ');
+}
+
+const TITLE_CASE_LOWERCASE = new Set([
+  'a', 'an', 'the',                          // articles
+  'and', 'but', 'or', 'nor', 'for', 'so', 'yet',  // coordinating conjunctions
+  'at', 'by', 'in', 'of', 'on', 'to', 'up', 'as', 'via'  // short prepositions
+]);
+
+// Convert normalized words array to CONSTANT_CASE
+function wordsToConstantCase(words) {
+  return words.map(word => word.toUpperCase()).join('_');
+}
+
+// Convert normalized words array to kebab-case
+function wordsToKebabCase(words) {
+  return words.map(word => word.toLowerCase()).join('-');
+}
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toCamelCase(str) {
+  return wordsToCamelCase(normalizeToWords(str));
+}
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toPascalCase(str) {
+  return wordsToPascalCase(normalizeToWords(str));
+}
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toConstantCase(str) {
+  return wordsToConstantCase(normalizeToWords(str));
+}
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toKebabCase(str) {
+  return wordsToKebabCase(normalizeToWords(str));
+}
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toCapitalize(str) {
+  return wordsToCapitalize(normalizeToWords(str));
+}
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toTitleCase(str) {
+  if (!str || typeof str !== 'string') return '';
+  const trimmed = str.trim().replace(/\s+/g, ' ');
+  let wordIndex = 0;
+  const lastWordStart = trimmed.search(/\b\w(?=[^]*$)/);
+  return trimmed.replace(/\b(\w)(\w*)\b/g, (match, first, rest, offset) => {
+    const i = wordIndex++;
+    if (i !== 0 && offset !== lastWordStart && TITLE_CASE_LOWERCASE.has(match.toLowerCase())) {
+      return match.toLowerCase();
+    }
+    return first.toUpperCase() + rest.toLowerCase();
+  });
+}

package/src/helpers/data-size.js

@@ -0,0 +1,144 @@
+import { SchemaError } from '../errors.js';
+
+/**
+ * IEC (binary) units: 1 KiB = 1024 bytes.
+ * @type {[string, number][]}
+ */
+const IEC_UNITS = [
+  ['B',   1],
+  ['KiB', 1024],
+  ['MiB', 1024 ** 2],
+  ['GiB', 1024 ** 3],
+  ['TiB', 1024 ** 4],
+  ['PiB', 1024 ** 5],
+];
+
+/**
+ * SI (decimal) units: 1 KB = 1000 bytes.
+ * @type {[string, number][]}
+ */
+const SI_UNITS = [
+  ['B',  1],
+  ['KB', 1000],
+  ['MB', 1000 ** 2],
+  ['GB', 1000 ** 3],
+  ['TB', 1000 ** 4],
+  ['PB', 1000 ** 5],
+];
+
+/**
+ * Suffix-to-multiplier lookup.
+ * When standard is unspecified, both IEC and SI suffixes are accepted.
+ * IEC suffixes (KiB, MiB, ...) always resolve to binary multipliers.
+ * SI suffixes (KB, MB, ...) always resolve to decimal multipliers.
+ * The bare "B" suffix is unambiguous (1 byte in both standards).
+ * @type {Map<string, number>}
+ */
+const SUFFIX_MAP = new Map();
+for (const [unit, mult] of IEC_UNITS) SUFFIX_MAP.set(unit.toLowerCase(), mult);
+for (const [unit, mult] of SI_UNITS)  SUFFIX_MAP.set(unit.toLowerCase(), mult);
+
+/**
+ * IEC-only suffix set for strict mode.
+ * @type {Set<string>}
+ */
+const IEC_SUFFIXES = new Set(IEC_UNITS.map(([u]) => u.toLowerCase()));
+
+/**
+ * SI-only suffix set for strict mode.
+ * @type {Set<string>}
+ */
+const SI_SUFFIXES = new Set(SI_UNITS.map(([u]) => u.toLowerCase()));
+
+/**
+ * Parse pattern: digits with optional decimal, optional whitespace, optional unit suffix.
+ * Captures: [1] = number, [2] = unit suffix (may be empty for bare numbers).
+ */
+const PARSE_RE = /^\s*(\d+(?:\.\d+)?)\s*([a-z]*)\s*$/i;
+
+/**
+ * Parse a data-size string into a byte count.
+ *
+ * Accepts numeric values (treated as bytes), or strings like `'20KiB'`, `'1.5 MB'`, `'512'`.
+ * When `standard` is omitted, both IEC and SI suffixes are accepted.
+ * When `standard` is `'iec'` or `'si'`, only that standard's suffixes are accepted.
+ *
+ * @package
+ * @param {string|number} value
+ * @param {string} [standard] - `'iec'` or `'si'`; omit to accept either
+ * @returns {number} byte count
+ */
+export function parseDataSize(value, standard) {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new SchemaError(`Invalid data size: ${value}`);
+    }
+    return value;
+  }
+
+  if (typeof value !== 'string') {
+    throw new SchemaError(`Invalid data size: expected string or number, got ${typeof value}`);
+  }
+
+  const match = value.match(PARSE_RE);
+  if (!match) {
+    throw new SchemaError(`Invalid data size: "${value}"`);
+  }
+
+  const [, numStr, suffix] = match;
+  const num = parseFloat(numStr);
+
+  // bare number — treat as bytes
+  if (!suffix) return num;
+
+  const key = suffix.toLowerCase();
+  const multiplier = SUFFIX_MAP.get(key);
+
+  if (multiplier === undefined) {
+    throw new SchemaError(`Unknown data size unit: "${suffix}"`);
+  }
+
+  // strict standard enforcement
+  if (standard) {
+    const std = standard.toLowerCase();
+    if (std === 'iec' && !IEC_SUFFIXES.has(key)) {
+      throw new SchemaError(`Unit "${suffix}" is not an IEC unit (expected B, KiB, MiB, GiB, TiB, PiB)`);
+    }
+    if (std === 'si' && !SI_SUFFIXES.has(key)) {
+      throw new SchemaError(`Unit "${suffix}" is not an SI unit (expected B, KB, MB, GB, TB, PB)`);
+    }
+  }
+
+  return num * multiplier;
+}
+
+
+/**
+ * Format a byte count into a human-readable data-size string.
+ *
+ * Selects the largest unit where the value is >= 1 and formats with up to
+ * two decimal places (trailing zeros stripped).
+ *
+ * @package
+ * @param {number} bytes
+ * @param {string} [standard='iec'] - `'iec'` or `'si'`
+ * @returns {string|undefined}
+ */
+export function formatDataSize(bytes, standard = 'iec') {
+  if (!Number.isFinite(bytes) || bytes < 0) {
+    throw new SchemaError(`Invalid byte count: ${bytes}`);
+  }
+
+  const units = standard.toLowerCase() === 'si' ? SI_UNITS : IEC_UNITS;
+
+  // walk from largest to smallest
+  for (let i = units.length - 1; i >= 0; i--) {
+    const [unit, mult] = units[i];
+    if (bytes >= mult || i === 0) {
+      const val = bytes / mult;
+      const formatted = val % 1 === 0 ? String(val) : parseFloat(val.toFixed(2)).toString();
+      return `${formatted} ${unit}`;
+    }
+  }
+  return undefined;
+}

package/src/helpers/debug-sink.js

@@ -0,0 +1,15 @@
+
+const DEBUG_SINK = Symbol.for('@versionzero/debug-sink');
+
+/**
+ * A hook for compatible loggers (e.g., `@versionzero/logger`) to automatically capture debug messages.
+ * (Left in for new code hacking; debug calls were removed for performance reasons after the library was stabilized.)
+ *
+ * @param {...any} args
+ * @package
+ * @deprecated
+ */
+export function debug(...args) {
+  const sink = (globalThis)[DEBUG_SINK] ?? console.log;
+  sink?.(...args);
+}