@versionzero/schema 1.0.0

package/src/traversal/executors/transform-early.js

@@ -0,0 +1,51 @@
+import { TraversalState } from '../traversal-state.js';
+import { deepEquals } from '../../helpers/deep.js';
+import { isEmpty, isObject } from '../../helpers/object.js';
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function transformEarly(state) {
+
+  if (state.value !== undefined && ((state.value === state.pending)
+                                    || (state.hasChildren && state.isIncremental
+                                        && deepEquals(state.pending, state.value)))) {
+    state.pending = undefined;
+    return state;
+  }
+  if (state.pending === undefined || state.schema === undefined || state.isUnion || state.schema.isImplicit) {
+    return state;
+  }
+  if ((state.hasChildren && state.isOpaque) /*|| !state.hasWorkInProgress*/) {
+    return state;
+  }
+
+  if (state.hasChildren && !state.mandatory && isEmpty(state.pending)) {
+    return state;
+  }
+
+  // We will transform early!
+  // Note that this implies that any mutations to child properties performed by this transform
+  // will very likely get overwritten when the children are traversed!
+  //
+
+  const result = state.schema._transformValue(state.pending, state.target, state.location, state.options);
+
+  /**
+   * @param {any} transformed
+   * @returns {TraversalState|null}
+   */
+  const updateState = (transformed) => {
+    if (transformed !== undefined) {
+      if (transformed !== state.value && state.hasChildren) {
+        state.copyPendingChildValues(state.pending, transformed);
+      }
+      state.pending = undefined;
+      state.value = transformed;
+    }
+    return (state.value === null)? null : state;
+  }
+
+  return (result instanceof Promise)? result.then(updateState) : updateState(result);
+}

package/src/traversal/executors/transform.js

@@ -0,0 +1,68 @@
+import { TraversalState } from '../traversal-state.js';
+import { deepEquals } from '../../helpers/deep.js';
+import { isEmpty } from '../../helpers/object.js';
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function transform(state) {
+
+  if (state.isPruned) {
+    return null;
+  }
+  if (state.isComplete) {
+    return state;
+  }
+  if (!state.condition) {
+    return undefined;
+  }
+
+  if (state.schema === undefined || state.isUnion) {
+    return state;
+  }
+
+  if (state.value !== undefined && ((state.value === state.pending)
+                                    || (state.hasChildren && state.isIncremental
+                                        && deepEquals(state.pending, state.value)))) {
+    state.pending = undefined;
+    return state;
+  }
+  if (state.pending === undefined) {
+    return state;
+  }
+  if (state.schema?.isImplicit) {
+    // implicit schemas never directly transform; they must use a value prepared by their parent.
+    return state;
+  }
+  if (!state.hasWorkInProgress || (state.hasChildren && state.isOpaque && state.hasIncompleteDescendents)) {
+    return state;
+  }
+
+  // todo - mandatory may not be set (via TraversalState set input) if we resolved a union this pass!
+
+  if (state.hasChildren && state.isIncremental && !state.mandatory && isEmpty(state.pending) && !state.schema.options.allowEmpty) {
+    return state;
+  }
+
+  // seems to be safe to do the transform
+
+  const result = state.schema._transformValue(state.pending, state.target, state.location, state.options);
+
+  /**
+   * @param {any} transformed
+   * @returns {TraversalState|null}
+   */
+  const updateState = (transformed) => {
+    if (transformed !== undefined) {
+      if (transformed !== state.value && state.hasChildren) {
+        state.copyPendingChildValues(state.pending, transformed);
+      }
+      state.pending = undefined;
+      state.value = transformed;
+    }
+    return (state.value === null)? null : state;
+  }
+
+  return (result instanceof Promise)? result.then(updateState) : updateState(result);
+}

package/src/traversal/executors/traversal-state-executor.js

@@ -0,0 +1,46 @@
+import { TraversalState } from '../traversal-state.js';
+import { Executor, toExecutor } from '../../executor/executor.js';
+import { EachExecutor } from '../../executor/each-executor.js';
+import { SerialExecutor } from "../../executor/serial-executor.js";
+
+
+/**
+ * @augments Executor<TraversalState>
+ */
+export class TraversalStateExecutor extends Executor
+{
+  /** @type {Executor<TraversalState>} */
+  #executor;
+
+  /**
+   * @param {any} enter
+   * @param {any} exit
+   */
+  constructor(enter, exit) {
+    super();
+    /** @type {Executor<TraversalState>} */
+    const enterExecutor = toExecutor(enter);
+    /** @type {Executor<TraversalState>} */
+    const exitExecutor = toExecutor(exit);
+
+    // wrap Each in a Serial so that we can return the original input instead of the processed array
+    /** @type {Executor<TraversalState>} */
+    const childExecutor = new SerialExecutor(
+      /** @type {Executor<TraversalState>} */ (new EachExecutor(this, ((state) => state?.activePropertyStates ?? [])))
+    );
+
+    // todo - wrap in a TryExecutor so we can ensure the location is set in any exceptions
+    this.#executor = new SerialExecutor([enterExecutor, childExecutor, exitExecutor]);
+  }
+
+
+  /**
+   *
+   * @param {TraversalState} state
+   * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+   */
+  execute(state) {
+    return this.#executor.execute(state);
+  }
+}
+

package/src/traversal/executors/validate.js

@@ -0,0 +1,63 @@
+import { TraversalState } from '../traversal-state.js';
+import { PipelineExecutor } from '../../executor/pipeline-executor.js';
+
+import { ValidationError } from '../../errors.js';
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|Promise<TraversalState>}
+ */
+export function validate(state) {
+  if (state.completed) {
+    // we must already be validated!
+    return state;
+  }
+//  const doValidation = state.context.final || (state.value !== undefined && (state.isIncremental || !state.isContainer));
+  const doValidation = state.context.final || state.isComplete;
+
+  if (!doValidation) {
+    const foo = state.isComplete;
+    return state;
+  }
+
+  if (state.schema === undefined) {
+    if (state.allowUnknown) {
+      return state;
+    }
+    throw new ValidationError('Unknown value', {path: state.path});
+  }
+  if (state.schema.isUnion) {
+    throw new ValidationError('Unable to resolve union', {path: state.path})
+  }
+
+  if (state.value === undefined && state.schema.isReference && !state.isRequired) {
+    return state;
+  }
+
+  if (state.hasWorkInProgress) {
+    if (state.value === undefined && !state.isRequired) {
+      return state;
+    }
+
+    const foo = state.hasWorkInProgress;
+    throw new ValidationError(`Incomplete assignment`, {value: state.pending, path: state.path});
+  }
+  if (state.value === undefined) {
+    return state;
+  }
+
+  const result = state.schema._validateValue(state.value, state.target, state.location, state.options);
+
+  /**
+   * @param {any} validated
+   * @returns {TraversalState}
+   */
+  const updateState = (validated) => {
+    if (validated !== state.value) {
+      state.value = validated;
+    }
+    return state;
+  }
+
+  return (result instanceof Promise)? result.then(updateState) : updateState(result);
+}

package/src/traversal/traversal-context.js

@@ -0,0 +1,231 @@
+import { SchemaLocation } from '../schema-location.js';
+
+import { TraversalState } from './traversal-state.js';
+import { debug } from '../helpers/debug-sink.js';
+import { behead } from '../helpers/path.js';
+import { CompiledSchema } from "../compiled-schema.js";
+import { EMPTY } from '../constants.js';
+import { SchemaError } from '../errors.js';
+
+
+/**
+ * @typedef {object} TraversalContextStandardOptions
+ * @property {boolean} [strict]
+ * @property {boolean} [deep]
+ * @property {boolean} [debug]
+ */
+
+/** @typedef {TraversalContextStandardOptions & {[key:string]:any}} TraversalContextOptions */
+
+export class TraversalContext
+{
+  /**
+   * @param {SchemaLocation|CompiledSchema} root
+   * @param {TraversalContextOptions} [options]
+   */
+  constructor(root, options = {}) {
+
+    this.root = (root instanceof CompiledSchema)? new SchemaLocation(root) : root;
+    this._final = false;
+
+    this._options = {...options, deep: options.deep ?? false, strict: options.strict ?? true, debug: options.debug ?? false}
+
+    this.traversals = 0;
+    this.counter = 0;
+
+    /** @type {Map.<string,TraversalState>} */
+    this.stateMap = new Map();
+    this._debugEnabled = options?.debug ?? false;
+
+    this.compiling = false;  // magic flag needed to prevent union resolution of a CompiledSchema value from being a problem
+  }
+
+  get options() {
+    return this._options;
+  }
+
+  get deep() {
+    return this._options.deep;
+  }
+
+  get strict() {
+    return this._options.strict;
+  }
+
+  update() {
+    this.counter++;
+    this.final = false;
+
+//    this._debug('update', {counter: this.counter, final: this.final})
+  }
+
+  _finalizeCount = 0;
+
+  set final(finalize) {
+    // todo - make this configurable?  (it's really just a last resort to prevent hangs.)
+    if (this._final && !finalize && this._finalizeCount++ > 100) {
+      throw new SchemaError('Unable to finalize a stable output value');
+    }
+    this._final = finalize ?? true;
+  }
+
+  get final() {
+    return Boolean(this._final);
+  }
+
+  finalize() {
+    this._final = true;
+    return this;
+  }
+
+  get isComplete() {
+    for (const state of this.stateMap.values()) {
+      if (!state.isComplete) {
+//        this._debug('not complete:', {incomplete: this.incomplete});
+
+        return false;
+      }
+    }
+//    this._debug('COMPLETE');
+    return true;
+  }
+
+  get incomplete() {
+    const incomplete = new Set();
+    for (const state of this.stateMap.values()) {
+      if (!state.isComplete) {
+        incomplete.add(state.path);
+      }
+    }
+    return incomplete;
+  }
+
+  // override the "target" value
+  setValue(value) {
+//    this._debug('setting target value');
+    this._value = value;
+  }
+
+  // get the root "target" value, or the override if set
+  getValue() {
+    if (this._value !== undefined) {
+      return this._value;
+    }
+    const traversalState = this.getState('');
+    return traversalState?.value;
+  }
+
+  /**
+   * @param {any} input
+   * @param {string} [path]
+   */
+  setAssignedInput(input, path = '') {
+    if (input === undefined) {
+      return;
+    }
+
+    let state = this.getState('');  // start at root
+
+    while (path) {
+      const [propertyName, remainingPath] = behead(path);
+      const propertyState = state.getChildState(propertyName);
+
+      state.assignedInput ??= EMPTY;
+      state = propertyState;
+      path = remainingPath;
+      state.mandatory = true;
+    }
+    state.assignedInput = input;
+    state.mandatory = true;
+  }
+
+
+  /**
+   * @param {string|SchemaLocation} path
+   * @returns {TraversalState}
+   */
+  getState(path) {
+    if (path instanceof SchemaLocation) {
+      path = path.path;
+    }
+    let state = this.stateMap.get(path);
+    if (state === undefined) {
+      const context = this;
+
+      /** @type {TraversalState} */
+      state = new TraversalState(context, path);
+
+      if (context._value !== undefined) {
+//      state.value = path === ''? context.#value : deepValue(context.#value, path);
+      }
+      this.stateMap.set(path, state);
+    }
+
+    return state;
+  }
+
+  /*
+    containerAssignmentsComplete(path) {
+      if (path === '' && this.uncompleted.size > 0) {
+        return false;
+      }
+      for (const p of this.uncompleted) {
+        if (p.startsWith(`${path}.`)) {
+          return false;
+        }
+      }
+      return true;
+    }
+
+   */
+
+  _debug(...args) {
+    if (!this._debugEnabled) return;
+
+    debug({contextName: 'context'}, ...args);
+  }
+
+  traverse(executor) {
+
+    const rootState = this.getState('');
+
+    let done = false;
+
+    const updateDone = (counter) => {
+      if (this.isComplete) {
+        done = true;
+      }
+      else if (this.counter === counter) {
+        if (this.final) {
+          done = true;
+        }
+        else {
+          this.final = true;
+        }
+      }
+      else {
+        this.final = false;
+      }
+      return done;
+    }
+
+    const loop = () => {
+      let result = undefined;
+      while (!done) {
+        const counter = this.counter;
+        result = executor.execute(rootState);
+
+        if (result instanceof Promise) {
+          return result.then(
+            resolved => updateDone(counter)? resolved : loop(),
+            rejected => { throw(rejected) }
+          );
+        }
+        updateDone(counter);
+        this.traversals++;
+      }
+      return result;
+    }
+    return loop();
+  }
+}