@versionzero/schema 1.0.0

package/src/traversal/executors/check-condition.js

@@ -0,0 +1,42 @@
+import { TraversalState } from '../traversal-state.js';
+
+/**
+ * Check whether we have a passing condition.
+ *
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function checkCondition(state) {
+  // once we have passed the condition check, it's locked in
+  if (state.condition === true) {
+    return state;
+  }
+
+  if (state.schema === undefined) {
+    return undefined;
+  }
+
+  //const value = state.pending ?? state.input ?? state.value;
+  // todo - think about this:
+  //        resolve-union uses pending/input/value like the snippet I extracted above, why is condition just using input?
+  //        hmm, pending will never contain any children before the condition returns true...
+  //        possibility: allow pending to build up but never be transformed?
+
+
+  const result = state.schema._checkCondition(state.input, state.context.getValue(), state.location, state.options);
+
+  const handleConditionResult = (result) => {
+    state.condition = result;
+    if (!result && state.context.final) {
+      state.value = null;
+    }
+    return result ? state : (state.context.final ? null : undefined);
+  }
+
+  if (result instanceof Promise) {
+    return result.then(resolved => {
+      return handleConditionResult(resolved);
+    })
+  }
+  return handleConditionResult(result);
+}

package/src/traversal/executors/check-input.js

@@ -0,0 +1,27 @@
+import { TraversalState } from '../traversal-state.js';
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined}
+ */
+export function checkInput(state) {
+
+  if (state.input === null) {
+    return null;
+  }
+  if (state.schema === undefined) { //} || state.schema.isImplicit) {
+    return undefined;
+  }
+  if (state.schema.isImplicit) {
+    return state;
+  }
+
+  // we can't check whether undefined is accepted
+  if (state.input === undefined) {
+    return state;
+  }
+
+  state.schema.ensureAccepts(state.input);
+
+  return state;
+}

package/src/traversal/executors/check-required.js

@@ -0,0 +1,19 @@
+import { TraversalState } from '../traversal-state.js';
+
+import { ValidationError } from '../../errors.js';
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState}
+ */
+export function checkRequired(state) {
+
+  if (!state.condition) {
+    return state;
+  }
+
+  if (state.context.final && state.isRequired && (state.value === undefined)) {
+    throw new ValidationError('Undefined required value', {path: state.path})
+  }
+  return state;
+}

package/src/traversal/executors/check-schema.js

@@ -0,0 +1,45 @@
+import { TraversalState } from '../traversal-state.js';
+
+import { ValidationError } from '../../errors.js';
+
+/**
+ *
+ * @param {TraversalState} state
+ * @returns {TraversalState|undefined|null}
+ */
+export function checkSchema(state) {
+
+  if (state.schema !== undefined) {
+    // If we have a schema, we're good to go.
+    return state;
+  }
+
+  const parentState = state.parent;
+
+  if (parentState === undefined) {
+    throw new ValidationError('invariant: root path schema must be defined');
+  }
+  if (parentState.schema === undefined) {
+    throw new ValidationError('invariant: cannot process a child if parent schema is undefined');
+  }
+
+  if (!parentState.schema.isUnion || state.context.final) {
+    // invalid property detected
+    const strict = parentState?.schema?.strict ?? parentState?.context.strict;
+    if (strict) {
+      // current schema may not be a union because we resolved successfully; check the path from the root.
+      const pathExists = state.context.root.schema?.isValidPath(state.path);
+      const message = pathExists ? 'Unexpected property' : 'Unknown property';
+      throw new ValidationError(message, {path: state.path});
+    }
+    else {
+      // prune
+      state.value = null;
+
+      return null;
+    }
+  }
+
+  //
+  return undefined;
+}

package/src/traversal/executors/defaults.js

@@ -0,0 +1,21 @@
+import { TraversalState } from "../traversal-state.js";
+import { EMPTY } from '../../constants.js';
+
+/**
+ * If the input is undefined but the schema defines a default, use that value
+ *
+ * @param {TraversalState} state
+ * @returns {TraversalState}
+ */
+export function defaults(state) {
+  if (state.assignedInput === undefined && state.pending === undefined && state.value === undefined) {
+    if (state.schema?.default !== undefined) {
+      state.assignedInput = state.schema.default;
+      state.mandatory = true; // does this need to be earlier?
+    }
+    else if (state.isDeep && state.isContainer) {
+      state.assignedInput = EMPTY;
+    }
+  }
+  return state;
+}

package/src/traversal/executors/enter-existing.js

@@ -0,0 +1,25 @@
+import { TraversalState } from "../traversal-state.js";
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined}
+ */
+export function enterExisting(state) {
+  if (state.assignedInput === undefined && state.parent) {
+    state.assignedInput = state.parent.input?.[state.key];
+  }
+  if (state.isPruned) {
+    return null;
+  }
+  if (state.completed) {
+    return undefined;
+  }
+
+  state.input = state.assignedInput;
+
+  if (state.schema !== undefined) {
+    state.pending = state.input;
+  }
+
+  return state;
+}

package/src/traversal/executors/enter-input.js

@@ -0,0 +1,25 @@
+import { TraversalState } from '../traversal-state.js';
+
+/**
+ *
+ *
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined}
+ */
+export function enterInput(state) {
+  const parentState = state.parent;
+
+  if (parentState) {
+    state.assignedInput ??= parentState.input?.[state.key];
+  }
+  state.input ??= state.assignedInput;
+
+  if (state.isPruned) {
+    return null;
+  }
+  if (state.completed) {
+    return undefined;
+  }
+
+  return state;
+}

package/src/traversal/executors/enter.js

@@ -0,0 +1,37 @@
+import { TraversalState } from '../traversal-state.js';
+import { EMPTY } from '../../constants.js';
+
+/**
+ *
+ * @param {TraversalState} state
+ * @returns {TraversalState|undefined|null}
+ */
+export function enter(state) {
+
+  const parentState = state.parent;
+
+  if (parentState) {
+    if (state.assignedInput === undefined || state.assignedInput === EMPTY) {
+      // we generally have our assigned input pushed down
+      const input = parentState.input?.[state.key];
+
+      if (input !== undefined) {
+        state.assignedInput = input;
+      }
+    }
+    if (state.schema?.isImplicit && !state.isPruned ) {
+      state.value ??= parentState.value?.[state.key];  // fixme ?
+    }
+  }
+  if (state.isPruned) {
+    return null;
+  }
+  if (state.completed) {
+    return undefined;
+  }
+//  if (state.isComplete) {
+//    return undefined;
+//  }
+
+  return state;
+}

package/src/traversal/executors/exit.js

@@ -0,0 +1,74 @@
+import { TraversalState } from '../traversal-state.js';
+import { SchemaError } from '../../errors.js';
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function exit(state) {
+  if (state.value === null) {
+    return state;
+  }
+
+  if (state.value === undefined) {
+    if (state.input !== undefined) {
+      return state;
+    }
+  }
+
+  if (state.completed) {
+    return undefined;
+  }
+
+  const parentState = state.parent;
+
+  // todo - should we fast-out if previously completed?
+  state.completed = state.isComplete;
+
+  if (parentState === undefined) {
+    // We're processing the root, so we don't need to copy our value anywhere.
+    // As long as we are not a union, mark outselves as processed.
+    if (!state.isUnion) {
+      state.processed = true;
+    }
+    return state;
+  }
+
+  const parentContainer = parentState.pending ?? parentState.value;
+
+  if (parentContainer === null) {
+    // oops, we shouldn't even be here!
+    return null;
+  }
+
+  if (parentContainer === undefined || (typeof parentContainer !== 'object')) {
+    // try to be helpful
+    let stringifiedParentContainer = `${parentContainer}`;
+    if (stringifiedParentContainer.length > 20) {
+      stringifiedParentContainer = stringifiedParentContainer.slice(0, 20) + '...'
+    }
+    const message = stringifiedParentContainer.length?
+                    `«${stringifiedParentContainer}» is not a valid container (set opaque option?)`
+                    : 'Not a valid container (set opaque option?)'
+
+    throw new SchemaError(message, {path: parentState.path});
+  }
+
+  const key = state.key;
+
+  if (state.schema?.isImplicit) {
+    state.value ??= parentContainer[key];  // set this so that children can use this as a container
+    state.processed = true;
+  }
+  else {
+    if (parentContainer[key] !== state.value) {
+      parentContainer[key] = state.value;
+      state.context.update();   // todo - monitor whether this triggers too many extra passes for complex deps!
+    }
+
+    if (!state.isUnion) {
+      state.processed = true;
+    }
+  }
+  return state;
+}

package/src/traversal/executors/finalize.js

@@ -0,0 +1,64 @@
+import { TraversalState } from '../traversal-state.js';
+import { FinalizeError } from '../../errors.js';
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|undefined|Promise<TraversalState|undefined>}
+ */
+export function finalize(state) {
+  if (state.completed) {
+    return state;
+  }
+  if (state.schema === undefined) {
+    if (state.allowUnknown) {
+      return state;
+    }
+    throw new FinalizeError('Unknown value', {path: state.path});
+  }
+
+  if (!state.schema.requiresFinalization) {
+    return state;
+  }
+
+  const doFinalization = state.context.final || state.isComplete;
+
+  if (!doFinalization) {
+    return undefined;
+  }
+
+  if (state.schema.isUnion) {
+    throw new FinalizeError('Unable to resolve union', {path: state.path})
+  }
+
+  // todo - block reference schemas from having finalizers
+  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 FinalizeError(`Incomplete assignment`, {value: state.pending, path: state.path});
+  }
+  if (state.value === undefined) {
+    return state;
+  }
+
+  const result = state.schema._finalizeValue(state.value, state.target, state.location, state.options);
+
+  /**
+   * @param {any} finalized
+   * @returns {TraversalState}
+   */
+  const updateState = (finalized) => {
+    if (finalized !== state.value) {
+      state.value = finalized;
+    }
+    return state;
+  }
+
+  return (result instanceof Promise)? result.then(updateState) : updateState(result);
+}

package/src/traversal/executors/index.js

@@ -0,0 +1,42 @@
+import { StepExecutor } from '../../executor/step-executor.js';
+import { Executor } from "../../executor/executor.js";
+import { TraversalState } from "../traversal-state.js";
+import { enter } from './enter.js';
+import { checkSchema } from './check-schema.js';
+import { defaults } from './defaults.js';
+import { normalize } from './normalize.js';
+import { checkInput } from './check-input.js';
+import { resolveUnion } from './resolve-union.js';
+import { checkCondition } from './check-condition.js';
+import { preparePending } from './prepare-pending.js';
+import { transformEarly } from './transform-early.js';
+import { transform } from './transform.js';
+import { checkRequired } from './check-required.js';
+import { validate } from './validate.js';
+import { exit } from './exit.js';
+
+import { enterInput } from './enter-input.js';
+import { enterExisting } from './enter-existing.js';
+import { prepareExisting } from './prepare-existing.js';
+import { serialize } from './serialize.js';
+import { finalize } from './finalize.js';
+import { TraversalStateExecutor } from './traversal-state-executor.js';
+
+
+export const PROCESS_ENTER = /** @type {Executor<TraversalState>} */ (new StepExecutor([enter, checkSchema, defaults, normalize, checkInput, resolveUnion, checkCondition, preparePending, transformEarly]));
+export const PROCESS_EXIT = /** @type {Executor<TraversalState>} */ (new StepExecutor([transform, finalize, checkRequired, validate, exit]));
+export const PROCESS_EXECUTOR = new TraversalStateExecutor(PROCESS_ENTER, PROCESS_EXIT);
+
+export const VALIDATE_ENTER = /** @type {Executor<TraversalState>} */ (new StepExecutor([enterExisting, resolveUnion, checkCondition, prepareExisting]));
+export const VALIDATE_EXIT = /** @type {Executor<TraversalState>} */ (new StepExecutor([checkRequired, validate, exit]));
+export const VALIDATE_EXECUTOR = new TraversalStateExecutor(VALIDATE_ENTER, VALIDATE_EXIT);
+
+export const SERIALIZE_ENTER = /** @type {Executor<TraversalState>} */ (new StepExecutor([enter, checkSchema, serialize, resolveUnion, checkCondition ]));
+export const SERIALIZE_EXIT = /** @type {Executor<TraversalState>} */ (new StepExecutor([exit]));
+export const SERIALIZE_EXECUTOR = new TraversalStateExecutor(SERIALIZE_ENTER, SERIALIZE_EXIT);
+
+export const PRELOAD_ENTER = /** @type {Executor<TraversalState>} */ (new StepExecutor([enterExisting, prepareExisting]));
+export const PRELOAD_EXIT = /** @type {Executor<TraversalState>} */ (new StepExecutor([exit]));
+export const PRELOAD_EXECUTOR = new TraversalStateExecutor(PRELOAD_ENTER, PRELOAD_EXIT);
+
+

package/src/traversal/executors/normalize.js

@@ -0,0 +1,38 @@
+import { TraversalState } from '../traversal-state.js';
+
+/**
+ * Normalize the assigned input value
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function normalize(state) {
+  if (state.processed && state.hasProcessedInput) {
+    // fast-out to avoid renormalization if possible
+    return state;
+  }
+  if (state.assignedInput === null) {
+    return null;
+  }
+  if (state.assignedInput === undefined) {
+    return state;
+  }
+  if (state.location === undefined) {
+    return undefined;
+  }
+  const schema = state.location.schema;
+  const normalized = schema._normalizeValue(state.assignedInput, state.target, state.location, state.options);
+
+  /**
+   * @param {any} normalized
+   * @returns {TraversalState|null}
+   */
+  const updateState = (normalized) => {
+    state.input = normalized;
+
+    if (normalized === null) {
+      return null;
+    }
+    return state;
+  }
+  return (normalized instanceof Promise)? normalized.then(updateState) : updateState(normalized);
+}

package/src/traversal/executors/prepare-existing.js

@@ -0,0 +1,27 @@
+import { TraversalState } from '../traversal-state.js';
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|undefined}
+ */
+export function prepareExisting(state) {
+  if (state.schema === undefined) {
+    return undefined;
+  }
+
+  if (state.input === undefined) {
+    if (!state.schema.options.allowUndefined) {
+      return state;
+    }
+  }
+
+  if (state.isUnion) {
+    state.pending ??= state.input;
+  }
+  else {
+    state.value = state.pending ?? state.input;
+    state.pending = undefined;
+  }
+
+  return state;
+}

package/src/traversal/executors/prepare-pending.js

@@ -0,0 +1,54 @@
+import { TraversalState } from '../traversal-state.js';
+import { EMPTY } from '../../constants.js';
+import { SchemaError } from '../../errors.js';
+
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|undefined|null|Promise<TraversalState|undefined|null>}
+ */
+export function preparePending(state) {
+
+  if (state.location === undefined) {
+    return undefined;
+  }
+  const schema = state.location.schema;
+
+  if (state.input === undefined) {
+    if (!schema.options.allowUndefined) {
+      return state;
+    }
+  }
+
+  if (state.hasChildren) {
+    if (state.pending !== undefined) {
+      return state; // use existing
+    }
+    if (state.value !== undefined) {
+      if (state.isIncremental) {
+        state.pending = state.value;
+        return state;
+      }
+      else {
+        throw new SchemaError('Value already processed', {location: state.location});
+      }
+    }
+
+    // create an empty container
+    const normalized = schema._normalizeValue(EMPTY, state.target, state.location, state.options);
+
+    if (normalized instanceof Promise) {
+      return normalized.then(normalized => {
+        state.pending = normalized;
+        return state;
+      })
+    }
+    state.pending = normalized;
+    return state;
+  }
+  else {
+    state.pending = state.input;
+    return state;
+  }
+
+}

package/src/traversal/executors/resolve-union.js

@@ -0,0 +1,50 @@
+import { TraversalState } from '../traversal-state.js';
+
+import { CompiledSchema } from "../../compiled-schema.js";
+import { UnionResolutionError } from '../../errors.js';
+
+/**
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function resolveUnion(state) {
+
+  if (!state.schema?.isUnion || !state.location) {
+    return state;
+  }
+
+  // todo - think about this, it's pretty weird (a union should never have .value, I think!)
+  //        counterpoint: what about pre-existing data being validated?
+
+  const value = state.pending ?? state.input ?? state.value;
+  const result = state.schema._discriminateUnion(value, state.target, state.location, {...state.options, strict: state.context.final});
+
+  /**
+   * @param {CompiledSchema|undefined} unionSchema
+   * @returns {TraversalState|undefined|null|Promise<TraversalState|null|undefined>}
+   */
+  const handleUnionSchema = (unionSchema) => {
+    if (unionSchema) {
+      state.schema = unionSchema;
+
+      if (unionSchema.isUnion) {
+        // whoa, multiple layers!
+        return resolveUnion(state);
+      }
+
+
+      //return undefined;  // consider forcing a loop so that we re-normalize with the new schema?
+    }
+    else {
+      if (state.context.final) {
+        throw new UnionResolutionError('Unable to resolve union', {location: state.location});
+      }
+    }
+    return state;
+  }
+
+  return (result instanceof Promise)
+         ? result.then(resolved => handleUnionSchema(resolved))
+         : handleUnionSchema(result);
+}
+

package/src/traversal/executors/serialize.js

@@ -0,0 +1,48 @@
+import { TraversalState } from '../traversal-state.js';
+import { isPlainObject } from '../../helpers/object.js';
+import { isTruthy } from '../../helpers/truthy.js';
+
+/**
+ * Serialize the pending/input and save as output state value
+ *
+ * Runs pre-child-traversal; acts in the same way that normalize does.
+ * Setting the input will propagate down to assigned values in the child states.
+ *
+ * @param {TraversalState} state
+ * @returns {TraversalState|null|undefined|Promise<TraversalState|null|undefined>}
+ */
+export function serialize(state) {
+  if (state.schema === undefined) {
+    return undefined;
+  }
+  const schema = state.schema;
+
+  if (state.assignedInput === null || schema.isImplicit || isTruthy(schema.metadata['omitFromSerialize'])) {
+    return null;
+  }
+
+  if (state.assignedInput === undefined) {
+    return state;
+  }
+
+  const result = schema._serializeValue(state.assignedInput, state.target, state.location, state.options);
+
+  /**
+   * @param {any} serialized
+   * @returns {null|TraversalState}
+   */
+  const updateState = (serialized) => {
+    if (serialized === null) {
+      state.value = null;
+      return null;
+    }
+    state.pending ??= state.hasChildren? ((schema.isArray || Array.isArray(result))? [] : {}) : serialized;
+    if (!state.isUnion) {
+      state.value = state.pending;
+    }
+    state.input = serialized;
+    return state;
+  }
+
+  return (result instanceof Promise)? result.then(updateState) : updateState(result);
+}