@versionzero/schema 1.0.0

package/src/executor/conditional-executor.js

@@ -0,0 +1,134 @@
+import { Executor, toExecutor, UNDEFINED_EXECUTOR } from './executor.js';
+import { isTruthy } from '../helpers/truthy.js';
+
+/**
+ * @template T
+ * @typedef {object} ConditionalExecutorActions
+ * @property {any} [success]
+ * @property {any} [failure]
+ */
+
+/**
+ * Checks if the provided predicate succeeds.  Usable as-is, or as a base class with behavior configured by flags.
+ *
+ * Default behavior simply tries running the predicate; if it throws or rejects, it is considered a failure.
+ *
+ * On success, the success action is called with the original input (default: returns the value)
+ * On failure, the failure action is called with the original input (default: return undefined)
+ *
+ * @template T
+ * @augments {Executor<T>}
+ */
+export class ConditionalExecutor extends Executor {
+  /** @type {Executor} */
+  #predicate;
+  /** @type {Executor} */
+  #success;
+  /** @type {Executor} */
+  #failure;
+
+  /** @type {boolean} */
+  #passResult = false;
+
+  /** @type {boolean} */
+  #passError = false;
+
+  /** @type {boolean} */
+  #checkTruthy = false;
+
+  /** @type {boolean} */
+  #checkDefined = false;
+
+  /**
+   * Construct a `ConditionalExecutor` from a predicate and optional success/failure executors.
+   * - If no success executor is provided, the resolved value from the predicate is returned.
+   * - If no failure executor is provided, `undefined` is returned.
+   *
+   * @param {any} predicate
+   * @param {ConditionalExecutorActions<T>} [actions]
+   * @param {symbol[]} [flags]
+   */
+  constructor(predicate, actions = {}, flags = []) {
+    super();
+    this.#predicate = toExecutor(predicate ?? new Executor());
+    this.#success = toExecutor(actions.success ?? new Executor());
+    this.#failure = toExecutor(actions.failure ?? UNDEFINED_EXECUTOR);
+
+    for (const flag of flags) {
+      if (flag === ConditionalExecutor.CHECK_TRUTHY) {
+        this.#checkTruthy = true;
+      }
+      else if (flag === ConditionalExecutor.CHECK_DEFINED) {
+        this.#checkDefined = true;
+      }
+      else if (flag === ConditionalExecutor.PASS_RESULT) {
+        this.#passResult = true;
+      }
+      else if (flag === ConditionalExecutor.PASS_ERROR) {
+        this.#passError = true;
+      }
+      else {
+        throw new Error(`Unknown flag`);
+      }
+    }
+  }
+
+  /**
+   * @param {T} input
+   * @param {...any} variadic
+   * @returns {T|null|undefined|Promise<T|null|undefined>}
+   */
+  execute(input, ...variadic) {
+
+    const handle = (error, result) => {
+
+      let success;
+      const value = this.#passResult ? result : input;
+      const failureValue = this.#passError? error : value;
+
+      if (error) {
+        success = false;
+      }
+      else {
+        if (this.#checkTruthy) {
+          success = isTruthy(result);
+        }
+        else if (this.#checkDefined) {
+          success = (result !== undefined);
+        }
+        else {
+          success = true;
+        }
+      }
+      if (success) {
+        return this.#success.execute(value, ...variadic);
+      }
+      else {
+        return this.#failure.execute(failureValue, ...variadic);
+      }
+    }
+
+    let result;
+    try {
+      result = this.#predicate.execute(input, ...variadic);
+    }
+    catch (error) {
+      return handle(error);
+    }
+
+    if (result instanceof Promise) {
+      return result.then(resolved => {
+        return handle(undefined, resolved);
+      }, rejected => {
+        return handle(rejected);
+      })
+    }
+    return handle(undefined, result);
+  }
+
+  static CHECK_TRUTHY = Symbol('CHECK-TRUTHY');
+  static CHECK_DEFINED = Symbol('CHECK-DEFINED');
+  static PASS_RESULT = Symbol('PASS-RESULT');
+  static PASS_ERROR = Symbol('PASS-ERROR');
+
+}

package/src/executor/each-executor.js

@@ -0,0 +1,68 @@
+import { Executor, toExecutor } from './executor.js';
+
+/**
+ * @template T
+ * @template E
+ * @augments {Executor<T>}
+ */
+export class EachExecutor extends Executor {
+  /** @type {Executor<E>} */
+  #executor;
+
+  /** @type {((value:T|null|undefined)=>(E|null|undefined)[])|undefined} */
+  #toValues;
+
+  /** @type {((values:(E|null|undefined)[], input:T|null|undefined)=>T|null|undefined)|undefined} */
+  #fromValues;
+
+  /**
+   * @param {Executor<E>|any} each - executor to apply to each value during execute
+   * @param {(value:T|null|undefined)=>(E|null|undefined)[]} [toValues] - optional value factory
+   * @param {((values:(E|null|undefined)[],input:T|null|undefined)=>T|null|undefined)} [fromValues]
+   */
+  constructor(each, toValues, fromValues) {
+    super();
+    this.#executor = toExecutor(each);
+    this.#toValues = toValues;
+    this.#fromValues = fromValues;
+  }
+
+  /**
+   * @param {T|null|undefined} input
+   * @param {...any} extra
+   * @returns {T|null|undefined|Promise<T|null|undefined>}
+   */
+  execute(input, ...extra) {
+
+    let values = (this.#toValues? this.#toValues(input) : /** @type {E[]} */ (input));
+
+    if (!values) {
+      return input;
+    }
+
+    if (!Array.isArray(values)) {
+      values = [values];
+    }
+
+    let sync = true;
+
+    const results = values.map(value => {
+      const result = this.#executor.execute(value, ...extra);
+      if (sync && result instanceof Promise) {
+        sync = false;
+      }
+      return result;
+    });
+
+    if (sync) {
+      // @ts-ignore
+      return this.#fromValues? this.#fromValues(results, input) : results;
+    }
+    else {
+      // @ts-ignore - just make sure T is E[]
+      return Promise.all(results).then(resolved => {
+        return this.#fromValues? this.#fromValues(resolved, input) : (resolved);
+      })
+    }
+  }
+}

package/src/executor/executor.js

@@ -0,0 +1,123 @@
+
+/** @import {Thenable} from './thenable.js' */
+
+/**
+ * @template T
+ * @typedef {(input:T|null|undefined, ...variadic:any) => T|null|undefined|Promise<T|null|undefined>} ExecutorFunction
+ */
+
+/**
+ * @template T
+ * @template R
+ * @typedef {(input:T|null|undefined, ...variadic:any) => R|null|undefined|Promise<R|null|undefined>} MappingExecutorFunction
+ */
+
+/**
+ * An `Executor` is a composable unit of computation that processes an input into an output.
+ *
+ * Executors are designed for fine-grained runtime composition (executors calling other executors) and
+ * are frequently used in hot code paths.  Executors may be synchronous or asynchronous, but fully synchronous
+ * executor call chains are optimized to incur no async overhead.  Only the outermost call thus needs to be awaited.
+ *
+ * Errors are surfaced as exceptions or rejections.
+ *
+ * Combinator executors may catch and transform errors, or intercept and reinterpret intermediate outputs.
+ *
+ * @template T
+ */
+export class Executor
+{
+  /**
+   * Process on a given input.
+   *
+   * The execute() method may return an output synchronously, or return a `Promise`
+   * for deferred output.  Callers must handle both cases.
+   *
+   * Output value conventions:
+   * - An output value of `null` signals that processing this input will *never* produce an output.  Most executors
+   *   receiving `null` as input should propagate it immediately without processing, although coordinator executors
+   *   that check for success or failure may choose to branch to an appropriate handler executor based on the result.
+   * - An output value of `undefined` signals that this input could not be processed *at this time*.
+   *   It is a soft signal (often used to halt a chain); individual executors define whether
+   *   `undefined` is a legal input for their context.
+   *
+   * @param {T|null|undefined} input - required primary input
+   * @param {...any} variadic - optional extra arguments (defined as needed by subclasses)
+   * @returns {T|null|undefined|Promise<T|null|undefined>}
+   */
+  execute(input, ...variadic) {
+    return input;
+  }
+
+  get isConstant() {
+    return false;
+  }
+}
+
+
+/**
+ * Wrap a provided executor function as an Executor
+ *
+ * @template T
+ * @augments Executor<T>
+ */
+export class FunctionExecutor extends Executor {
+  #execute;
+  /**
+   * @param {ExecutorFunction<T>} execute
+   */
+  constructor(execute) {
+    super();
+    this.#execute = execute;
+  }
+
+  /**
+   * @param {T} input - required primary input
+   * @param {...any} variadic - optional extra arguments (defined as needed by subclasses)
+   * @returns {T|null|undefined|Promise<T|null|undefined>}
+   */
+  execute(input, ...variadic) {
+    return this.#execute(input, ...variadic);
+  }
+}
+
+export class ConstantExecutor extends Executor {
+  #value;
+  /**
+   * @param {any} value
+   */
+  constructor(value) {
+    super();
+    this.#value = value;
+  }
+  execute() {
+    return this.#value;
+  }
+
+  get isConstant() {
+    return true;
+  }
+}
+
+export const NULL_EXECUTOR = new ConstantExecutor(null);
+export const UNDEFINED_EXECUTOR = new ConstantExecutor(undefined);
+export const TRUE_EXECUTOR = new ConstantExecutor(true);
+export const FALSE_EXECUTOR = new ConstantExecutor(false);
+
+/**
+ * @template T
+ * @param {T|Executor<T>|ExecutorFunction<T>} e
+ * @returns {Executor<T>}
+ */
+export function toExecutor(e) {
+  if (e instanceof Executor) {
+    return e;
+  }
+  else if (typeof e === 'function') {
+    // @ts-ignore
+    return new FunctionExecutor(e);
+  }
+  else {
+    return new ConstantExecutor(e);
+  }
+}

package/src/executor/object-executor.js

@@ -0,0 +1,98 @@
+import { Executor, toExecutor } from './executor.js';
+
+import { SchemaError } from '../errors.js';
+
+/** @typedef {[key:string, executor:Executor]} ObjectExecutorEntry */
+
+/**
+ * @augments {Executor<any>}
+ */
+export class ObjectExecutor extends Executor {
+
+  /** @type {ObjectExecutorEntry[]} */
+  #executorEntries = [];
+  /** @type {((input:any) => any) | undefined} */
+  #preprocess;
+
+  /** @type {any} */
+  #constantValue;
+
+  /**
+   * @param {object} [object]
+   * @param {(input:any) => any} [preprocess]
+   */
+  constructor(object = {}, preprocess) {
+
+    super();
+
+    let isConstant = true;
+    for (const [key, item] of Object.entries(object)) {
+      if (item === undefined) {
+        continue;
+      }
+      const itemExecutor = toExecutor(item);
+      this.#executorEntries.push([key, itemExecutor]);
+      isConstant &&= itemExecutor.isConstant;
+    }
+    this.#preprocess = preprocess;
+
+    if (isConstant) {
+      if (preprocess) {
+        throw new SchemaError('Cannot use a preprocessor with a constant object executor');
+      }
+      this.#constantValue = Object.fromEntries(this.#executorEntries.map(([key, executor]) => [key, executor.execute(true)]));
+    }
+
+  }
+  /**
+   * @param {any} input
+   * @param {...any} extra
+   * @returns {object|Promise<object>}
+   */
+  execute(input, ...extra) {
+    if (this.#constantValue !== undefined) {
+      return this.#constantValue;
+    }
+    const output = {};
+    let current = 0;
+
+    const entries = this.#executorEntries;
+
+    while (current < entries.length) {
+      const key = entries[current][0];
+      const executeInput = this.#preprocess? this.#preprocess(input) : input
+      const result = entries[current++][1].execute(executeInput, ...extra);
+
+      if (result instanceof Promise) {
+        return result.then(resolved => {
+          output[key] = resolved;
+          return this.#resume(input, extra, current, output)
+        })
+      }
+      else {
+        output[key] = result;
+      }
+    }
+    return output;
+  }
+
+  /**
+   * @param {any} input
+   * @param {any[]} extra
+   * @param {number} resumeIndex
+   * @param {object} output
+   * @returns {Promise<object>}
+   */
+  async #resume(input, extra, resumeIndex, output) {
+    const entries = this.#executorEntries;
+    while (resumeIndex < entries.length) {
+      const key = entries[resumeIndex][0];
+      const executeInput = this.#preprocess? this.#preprocess(input) : input
+      output[key] = await entries[resumeIndex++][1].execute(executeInput, ...extra);
+    }
+    return output;
+  }
+  get isConstant() {
+    return this.#constantValue !== undefined;
+  }
+}

package/src/executor/parallel-executor.js

@@ -0,0 +1,43 @@
+
+import { Executor, toExecutor } from './executor.js';
+
+/**
+ * Executes a fixed set of executors concurrently, passing the same input value and variadic arguments to each,
+ * and returning an array of all results in the same order as the executors.
+ *
+ * When all executors are synchronous, execution is sequential and the result is a plain array.
+ * When any executor returns a Promise, all results are collected via `Promise.all`, giving true
+ * concurrent execution for I/O-bound processors.
+ *
+ * Errors propagate immediately — a synchronous throw or async rejection halts collection
+ * and surfaces the error to the caller without waiting for remaining executors.
+ *
+ * @augments {Executor<any>}
+ */
+export class ParallelExecutor extends Executor {
+
+  #executors;
+
+  /**
+   * @param {Array<any>} [parallel] - executors/functions/values to execute concurrently
+   */
+  constructor(parallel = []) {
+    super();
+    this.#executors = parallel.map((/** @type {any} */ item) => toExecutor(item));
+  }
+
+  /**
+   * @param {any} input
+   * @param {...any} variadic
+   * @returns {any[]|Promise<any[]>}
+   */
+  execute(input, ...variadic) {
+    let hasAsync = false;
+    const results = this.#executors.map(exec => {
+      const result = exec.execute(input, ...variadic);
+      if (result instanceof Promise) hasAsync = true;
+      return result;
+    });
+    return hasAsync ? Promise.all(results) : results;
+  }
+}

package/src/executor/pipeline-executor.js

@@ -0,0 +1,65 @@
+import { Executor, toExecutor } from './executor.js';
+
+/**
+ * @augments Executor<any>
+ */
+export class PipelineExecutor extends Executor
+{
+  /** @type {Executor<any>[]} */
+  #executors;
+
+  /**
+   * @param {Array<any>|any} pipeline - executors/functions/values to execute as a pipeline
+   */
+  constructor(pipeline = []) {
+    if (!Array.isArray(pipeline)) {
+      pipeline = [pipeline]
+    }
+    super();
+    this.#executors = pipeline.map((/** @type {any} */ item) => toExecutor(item));
+  }
+
+  /**
+   * @param {any} value
+   * @param {...any} variadic
+   * @returns {any|Promise<any>}
+   */
+  execute(value, ...variadic) {
+//    if (value === null) {
+//      return null;
+//    }
+    let current = 0;
+
+    const executors = this.#executors;
+
+    while (current < executors.length) {
+      value = executors[current++].execute(value, ...variadic);
+
+//      if (value === null) {
+//        return null;
+//      }
+
+      if (value instanceof Promise) {
+        return value.then(resolved => this.#resume(resolved, variadic, current));
+      }
+    }
+    return value;
+  }
+
+  /**
+   * @param {unknown} value
+   * @param {any[]} variadic
+   * @param {number} resumeIndex
+   * @returns {Promise<any>}
+   */
+  async #resume(value, variadic, resumeIndex) {
+    while (resumeIndex < this.#executors.length) {
+//      if (value === null) {
+//        return null;
+//      }
+      const input = value;
+      value = await this.#executors[resumeIndex++].execute(value, ...variadic);
+    }
+    return value;
+  }
+}