@versionzero/schema 1.0.0

package/src/types.js

@@ -0,0 +1,102 @@
+/**
+ * @typedef {object} ISchema
+ * @property {string} [base] - Base schema name for extension
+ * @property {ISchemaProperties} properties - Schema properties
+ * @property {ISchemaOptions} options - Schema options
+ * @property {ISchemaMetadata} metadata - Schema metadata
+ * @property {ISchemaHandlers} handlers - Schema handlers
+ * @property {ISchemaUnion} unionSchemas - Union schema definitions
+ * @property {(schema:ISchema) => SchemaData|undefined} toData - Serialize schema to plain object
+ */
+
+/** @import { ValueProcessorSpec } from './value-processor/value-processor.js' */
+
+/**
+ * @typedef {object} ISchemaMetadataCommon
+ * @property {string} [description] - help text description of the property; used by CommandLineSource
+ * @property {string} [valueName] - help text type name of the property value; used by CommandLineSource
+ * @property {string} [valueDescription] - help text description of the property value; used by CommandLineSource
+ * @property {string} [flagHint] - request a specific flag character; used by CommandLineSource
+ * @property {boolean} [advanced] - filter from basic help text; used by CommandLineSource
+ * @property {boolean} [hidden] - hide from help; used by CommandLineSource
+ * @property {boolean} [general] - mark this field for CommandLineSource to be used without a flag or option
+ * @property {string} [parserTypeHint] - set to base/primitive types to help source parsers interpret values
+ * @property {boolean} [omitFromSerialize] - set to true to omit this schema's value when serializing
+ */
+
+/** @typedef {ISchemaMetadataCommon & {[key:string]: any}} ISchemaMetadata */
+
+/** @typedef {"any"|"string"|"number"|"boolean"|"bigint"|"symbol"|"object"|"array"|"function"|"buffer"|"null"} SchemaFundamentalType */
+
+ /**
+  * @typedef {object} ISchemaOptionsCommon
+  * @property {SchemaFundamentalType} [type] - should only be set on the core types supported by the schema
+  * @property {function(string,ISchema):void} [compileHook] - a function called during schema compilation
+  * @property {boolean} [allowEmpty] - whether an array type or string type can be empty
+  * @property {boolean} [allowUndefined] - whether undefined values can be passed through this schema
+  * @property {boolean} [allowErrors] - whether to throw when a processor returns an Error, or treat it as a legal value
+  * @property {boolean} [allowUnknownValues] - when true, values are advisory (for expansion/metadata) and do not gate ensureAccepts
+  * @property {boolean} [strict] - whether to do strict typechecking (defaults to true; must be explicitly false to be "lax")
+  * @property {boolean} [reference] - disallow direct assignment; value will be inherited from a parent
+  * @property {boolean} [required] - flag indicating whether this field is required
+  * @property {boolean} [literal] - flag indicating that this field always returns the option value
+  * @property {boolean} [implicit] - flag indicating that this field exists implicitly in the post-transform value
+  * @property {boolean} [dynamic] - true/undefined means treat functional values as dynamic lookups; false means treat functions as values
+  * @property {string} [context] - triggers value to be copied to the context field with this name
+  * @property {any} [default] - default value
+  * @property {Array<any>} [values] - list of legal input values for this field (each is normalized during compilation)
+  * @property {boolean} [selector] - true if this schema acts as a selector
+  * @property {boolean|string} [selection] - this schema activates if the selector matches the value, or matches this prop name if true
+  */
+
+/** @typedef {ISchemaOptionsCommon & {[key:string]: any}} ISchemaOptions */
+
+/**
+ * @typedef {object} ISchemaHandlers
+ * @property {Array<ValueProcessorSpec>} [normalizers]
+ * @property {Array<ValueProcessorSpec>} [conditions]
+ * @property {Array<ValueProcessorSpec>} [transformers]
+ * @property {Array<ValueProcessorSpec>} [serializers]
+ * @property {ValueProcessorSpec} [unionDiscriminator]
+ */
+
+
+
+/**
+ * @typedef {object} ISchemaMetadataAttributesCommon
+ * @property {string} [_description] - help text description of the property; used by CommandLineSource
+ * @property {string} [_valueName] - help text type name of the property value; used by CommandLineSource
+ * @property {string} [_valueDescription] - help text description of the property value; used by CommandLineSource
+ * @property {string} [_flagHint] - request a specific flag character; used by CommandLineSource
+ * @property {boolean} [_advanced] - filter from basic help text; used by CommandLineSource
+ * @property {boolean} [_hidden] - hide from help; used by CommandLineSource
+ * @property {boolean} [_general] - mark this field for CommandLineSource to be used without a flag or option
+ * @property {string} [_parserTypeHint] - set to base/primitive types to help source parsers interpret values
+ * @property {boolean} [_omitFromSerialize] - set to true to omit this schema's value when serializing
+ * @deprecated
+ */
+
+/**
+ * @typedef {ISchemaOptionsCommon & ISchemaMetadataAttributesCommon & {[key:string]: any}} ISchemaAttributes
+ * @deprecated
+ */
+
+/**
+ * @typedef {{[key:string]: ISchema}} ISchemaProperties
+ */
+
+/**
+ * @typedef {{[key:string]: ISchema}} ISchemaUnion
+ */
+
+/**
+ * @typedef {object} SchemaData
+ * @property {string} [base]
+ * @property {{[key:string]: SchemaData}} [properties]
+ * @property {{[key:string]: any}} [handlers]
+ * @property {{[key:string]: string}} [metadata]
+ * @property {{[key:string]: any}} [options]
+ * @property {{[key:string]: SchemaData}} [unionSchemas]
+ */
+
+export {}; // Make this a module

package/src/value-processor/composed-value-processor.js

@@ -0,0 +1,43 @@
+import { Executor } from "../executor/executor.js";
+import { stringify } from "../helpers/stringify.js";
+import { ValueProcessor } from './value-processor.js';
+import { isPrimitive } from '../helpers/object.js';
+
+
+/**
+ * Wrap an existing executor as a ValueProcessor
+ *
+ * @augments {ValueProcessor}
+ */
+export class ComposedValueProcessor extends ValueProcessor
+{
+  /** @type {Executor<any>} */
+  #executor;
+
+  /**
+   * @param {Executor<any>} executor
+   * @param {any} spec
+   * @param {string} [description]
+   */
+  constructor(executor, spec, description) {
+    if (executor instanceof ValueProcessor) {
+      description = executor.description;
+    }
+    if (!description && executor.isConstant) {
+      const results = executor.execute(true);
+      description = isPrimitive(results)? `${results}`: stringify(results);
+    }
+    super(spec, description);
+    this.#executor = executor;
+  }
+
+  execute(value, target, location, options) {
+    return this.#executor.execute(value, target, location, options);
+  }
+
+  get isConstant() {
+    return this.#executor.isConstant;
+  }
+
+
+}

package/src/value-processor/defined-value-processor.js

@@ -0,0 +1,72 @@
+import { ValueProcessor } from './value-processor.js';
+import { ComposedValueProcessor } from './composed-value-processor.js';
+import { ArrayExecutor } from '../executor/array-executor.js';
+import { ObjectExecutor } from '../executor/object-executor.js';
+import { ParametersValueProcessor } from './parameters-value-processor.js';
+import { FunctionValueProcessor } from './function-value-processor.js';
+import { ParameterizedValueProcessor } from './parameterized-value-processor.js';
+import { SchemaCompilationError, SchemaError } from '../errors.js';
+import { isEmpty, map } from '../helpers/object.js';
+import { CompiledSchema } from '../compiled-schema.js';
+
+/** @import {ValueProcessorFunction, ValueProcessorDefinition, ValueProcessorArgs} from './value-processor.js' */
+
+/**
+ * @augments {ParameterizedValueProcessor}
+ */
+export class DefinedValueProcessor extends ParameterizedValueProcessor
+{
+  /**
+   * @param {ValueProcessorDefinition} definition
+   * @param {ValueProcessor[]|{[parameter:string]:ValueProcessor}} [args]
+   */
+  constructor(definition, args) {
+
+    if (!definition.keyword) {
+      throw new SchemaError('No keyword found in processor definition');
+    }
+    if (!definition.process) {
+      throw new SchemaError('No process function found in processor definition');
+    }
+    if (definition.build) {
+      // This should have been handled upstream!
+      throw new SchemaCompilationError('Internal compiler error: factory definitions unsupported by DefinedValueProcessor');
+    }
+
+    if (definition instanceof CompiledSchema) {
+      // coding error!
+      throw new SchemaCompilationError('Internal compiler error: a CompiledSchema was incorrectly identified as a DefinedValueProcessor');
+    }
+
+    let argsProcessor;
+    let spec;
+
+
+    if (definition.parameters !== undefined) {
+      argsProcessor = new ParametersValueProcessor(definition.parameters, args);
+      spec = {[`$${definition.keyword}`]: argsProcessor.spec}
+    }
+    else if (!isEmpty(args)) {
+      const argSpecs = map(args, arg => arg.spec);
+
+      if (Array.isArray(args)) {
+        argsProcessor = new ComposedValueProcessor(new ArrayExecutor(args), argSpecs);
+      }
+      else if (typeof args === 'object') {
+        argsProcessor = new ComposedValueProcessor(new ObjectExecutor(args), argSpecs)
+      }
+      else {
+        throw new SchemaCompilationError('Internal compiler error: unsupported keyword arguments type')
+      }
+      spec = {[`$${definition.keyword}`]: argsProcessor.spec}
+    }
+    else {
+      spec = `$${definition.keyword}`;
+    }
+
+    const description = definition.description ?? (definition.describe?.(args) ?? `${definition.keyword}`)
+
+    super(new FunctionValueProcessor(definition.process), argsProcessor, spec, description);
+  }
+}
+

package/src/value-processor/function-value-processor.js

@@ -0,0 +1,68 @@
+import { ValueProcessor } from './value-processor.js';
+import { SchemaLocation } from "../schema-location.js";
+
+import { SchemaError } from '../errors.js';
+import { isEmpty, map } from '../helpers/object.js';
+
+/** @import {ValueProcessorFunction, ValueProcessorDefinition, ValueProcessorArgs} from './value-processor.js' */
+
+/**
+ * @augments {ValueProcessor}
+ */
+export class FunctionValueProcessor extends ValueProcessor
+{
+  /** @type {ValueProcessor|undefined} */
+  #argsProcessor;
+
+  /** @type {ValueProcessorFunction} */
+  #process;
+
+  /**
+   * @param {ValueProcessorFunction} process
+   * @param {ValueProcessor} [args]
+   */
+  constructor(process, args) {
+    super();
+
+    if (args) {
+      if (!(args instanceof ValueProcessor)) {
+        throw new SchemaError('FunctionValueProcessor args must be a ValueProcessor');
+      }
+      this.#argsProcessor = args;
+    }
+
+    this.#process = process;
+    this.spec = process;
+  }
+
+  /**
+   * @param {any} value
+   * @param {any} target
+   * @param {SchemaLocation} location
+   * @param {object} options
+   * @returns {any|null|undefined|Promise<any|null|undefined>}
+   */
+  execute(value, target, location, options) {
+    if (this.#argsProcessor) {
+      const args = this.#argsProcessor.execute(value, target, location, options);
+
+      if (args instanceof Promise) {
+        return args.then(argsResolved => this.#process(value, target, location, {...options, args: argsResolved}))
+      }
+      return this.#process(value, target, location, {...options, args});
+    }
+    return this.#process(value, target, location, options);
+  }
+}
+
+/**
+ * @param {string} keyword
+ * @param {ValueProcessorArgs|undefined} args
+ * @returns {any}
+ */
+function getSpec(keyword, args) {
+  if (!args || isEmpty(args)) {
+    return `$${keyword}`;
+  }
+  return {[`$${keyword}`]: map(args, arg => arg.spec)};
+}

package/src/value-processor/parameterized-value-processor.js

@@ -0,0 +1,45 @@
+import { ValueProcessor } from './value-processor.js';
+import { SchemaLocation } from "../schema-location.js";
+
+/**
+ * @augments {ValueProcessor}
+ */
+export class ParameterizedValueProcessor extends ValueProcessor
+{
+  /** @type {ValueProcessor} */
+  #mainProcessor;
+  /** @type {ValueProcessor|undefined} */
+  #argsProcessor;
+
+  /**
+   * @param {ValueProcessor} mainProcessor
+   * @param {ValueProcessor|undefined} argsProcessor
+   * @param {any} spec
+   * @param {string} [description]
+   */
+  constructor(mainProcessor, argsProcessor, spec, description) {
+
+    super(spec, description);
+    this.#mainProcessor = mainProcessor;
+    this.#argsProcessor = argsProcessor;
+  }
+
+  /**
+   * @param {any} value
+   * @param {any} target
+   * @param {SchemaLocation} location
+   * @param {object} options
+   * @returns {any|null|undefined|Promise<any|null|undefined>}
+   */
+  execute(value, target, location, options) {
+    if (this.#argsProcessor) {
+      const args = this.#argsProcessor.execute(value, target, location, options);
+
+      if (args instanceof Promise) {
+        return args.then(argsResolved => this.#mainProcessor.execute(value, target, location, {...options, args: argsResolved}))
+      }
+      return this.#mainProcessor.execute(value, target, location, {...options, args});
+    }
+    return this.#mainProcessor.execute(value, target, location, options);
+  }
+}

package/src/value-processor/parameters-value-processor.js

@@ -0,0 +1,178 @@
+import { ConstantExecutor, Executor, toExecutor } from '../executor/executor.js';
+import { ObjectExecutor } from '../executor/object-executor.js';
+import { ValueProcessor } from './value-processor.js';
+import { SchemaLocation } from "../schema-location.js";
+import { ComposedValueProcessor } from './composed-value-processor.js';
+import { SchemaError } from '../errors.js';
+import { map } from '../helpers/object.js';
+import { formatValue } from '../helpers/format.js';
+
+/** @typedef {[key:string, executor:Executor]} ObjectExecutorEntry */
+
+/**
+ * ParametersValueProcessor is an Executor that uses a list of parameter definitions to validate and execute
+ * provided argument Executors.
+ *
+ * Parameters are managed as follows:
+ * - The first optional parameter without an explicit default will use the pipeline value as its default.
+ * - If a type option is specified, that argument will be validated against that type.
+ * - Constant executors will be checked at construction.
+ * - If all parameters are passed constant executor arguments, the entire executor will be constant.
+ * - Receiving "undefined" as an argument value at runtime should not be interpreted as a missing argument,
+ *   as it may simply indicate that the value is not yet available (but may become available later.)
+ *
+ * @augments {ValueProcessor}
+ */
+export class ParametersValueProcessor extends ValueProcessor {
+
+  /** @type {Executor} */
+  #executor;
+
+  /** @type {object[]} */
+  #parameters;
+
+  /** @type {any} */
+  #constantValue;
+
+  /**
+   * @param {object[]} [parameters]
+   * @param {ValueProcessor[]|{[parameter:string]:ValueProcessor}} [argsProcessors]
+   */
+  constructor(parameters = [], argsProcessors = {}) {
+
+    super();
+
+    const processorObject = {};
+
+    if (Array.isArray(argsProcessors)) {
+      if (argsProcessors.length > parameters.length) {
+        throw new SchemaError(`Too many arguments`);
+      }
+      for (let p = 0; p < parameters.length; ++p) {
+        if (p < argsProcessors.length) {
+          processorObject[parameters[p].parameter] = argsProcessors[p];
+        }
+      }
+    }
+    else {
+      if (Object.keys(argsProcessors).length > parameters.length) {
+        throw new SchemaError('Too many arguments');
+      }
+      for (let p = 0; p < parameters.length; ++p) {
+        const arg = argsProcessors[parameters[p].parameter];
+        if (arg) {
+          processorObject[parameters[p].parameter] = arg;
+        }
+      }
+      for (const parameter of Object.keys(argsProcessors)) {
+        if (processorObject[parameter] === undefined) {
+          throw new SchemaError(`Unknown parameter ${parameter}`);
+        }
+      }
+    }
+
+    // Parameter sequence matters!
+    let considerUsingInput = true;
+    let handlingUndefaultedOptionals = false;
+
+    for (let p = 0; p < parameters.length; ++p) {
+      const hasDefault = parameters[p].hasOwnProperty('default');  // we want to be able to explicitly have an undefined default
+      if (parameters[p].required) {
+        if (handlingUndefaultedOptionals) {
+          throw new SchemaError(`Required parameter ${parameters[p].parameter} cannot follow optional parameter`);
+        }
+      }
+      else if (!hasDefault) {
+        if (handlingUndefaultedOptionals) {
+          considerUsingInput = false;
+        }
+        handlingUndefaultedOptionals = true;
+      }
+      if (processorObject[parameters[p].parameter] === undefined && hasDefault) {
+        processorObject[parameters[p].parameter] = new ComposedValueProcessor(new ConstantExecutor(parameters[p].default), parameters[p].default);
+      }
+
+      if (processorObject[parameters[p].parameter] === undefined) {
+        if (parameters[p].required) {
+          throw new SchemaError(`Missing required argument for parameter ${parameters[p].parameter}`);
+        }
+        if (handlingUndefaultedOptionals && considerUsingInput && !hasDefault) {
+          processorObject[parameters[p].parameter] = new ComposedValueProcessor(new Executor(), '$input');
+          considerUsingInput = false;
+        }
+      }
+
+      if (processorObject[parameters[p].parameter]?.isConstant && parameters[p].type !== undefined) {
+        const value = processorObject[parameters[p].parameter].execute(true);
+        if (parameters[p].type !== undefined && value !== undefined && typeof value !== parameters[p].type) {
+          throw new SchemaError(`Invalid ${parameters[p].type} type for parameter "${parameters[p].parameter}"`, {value});
+        }
+      }
+    }
+    this.#executor = new ObjectExecutor(processorObject);
+    this.#parameters = parameters;
+    if (this.#executor.isConstant) {
+       const args = this.#executor.execute(true);
+       this.#constantValue = this.#check(args);
+
+       let d='';
+       for (const [p,v] of Object.entries(args)) {
+         if (d.length) {
+           d += ','
+         }
+         d += `${p}=${v}`
+       }
+       this.description=`[${d}]`
+    }
+    this.spec = map(processorObject, param => param.spec);
+
+  }
+
+  // Note: required / default are compilation checks, not runtime!
+  // All processors should expect they may receive undefined argument values, as sometimes they are resolved
+  // dynamically and may not have a value yet.  Some processors may treat this as an error and throw, others
+  // may simply return undefined.  If an argument having an undefined value might lead to surprising results,
+  // it should be guarded externally.  For example:
+  //
+  // .validator({$length: {min: {$reference: '^^.settings.minimum'}}})
+  //
+  // It may be the case that the reference value is not set, which would result in $length not enforcing
+  // a minimum at all.  To ensure it only gets set when the dependency is available, it should be written as:
+  //
+  // .validator({$require: {$reference: '^^.settings.minimum'}})
+
+  #check(args) {
+    for (const p of this.#parameters) {
+      if (args[p.parameter] !== undefined) {
+        if (p.type && (typeof args[p.parameter] !== p.type)) {
+          throw new SchemaError(`Invalid type for parameter ${p.parameter}, expected ${p.type}`)
+        }
+      }
+    }
+    return args;
+  }
+
+
+  /**
+   * @param {object} args
+   * @param {any} target
+   * @param {SchemaLocation} location
+   * @param {object} options
+   * @returns {object|Promise<object>}
+   */
+  execute(args, target, location, options) {
+    if (this.#constantValue !== undefined) {
+      return this.#constantValue;
+    }
+    const result = this.#executor.execute(args, target, location, options);
+
+    if (result instanceof Promise) {
+      return result.then(resolved => this.#check(resolved))
+    }
+    return this.#check(result);
+  }
+
+  get isConstant() {
+    return this.#constantValue !== undefined;
+  }
+}

package/src/value-processor/spec.js

@@ -0,0 +1,89 @@
+import { ValueProcessor } from './value-processor.js';
+import { SchemaError } from '../errors.js';
+import { isPlainObject } from '../helpers/object.js';
+/** @import { ValueProcessorSpec, KeywordValueProcessorSpec } from './value-processor.js' */
+
+/**
+ * @param {ValueProcessorSpec} spec
+ * @returns {spec is KeywordValueProcessorSpec}
+ * @package
+ */
+export function isKeywordValueProcessorSpec(spec) {
+
+  if (typeof spec === 'string' && spec.charAt(0) === '$') {
+    return true;
+  }
+  if (typeof spec === 'object' && spec !== null) {
+    const keys = Object.keys(spec);
+    if (keys.length === 1 && keys[0].charAt(0) === '$') {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {KeywordValueProcessorSpec} keywordSpec
+ * @returns {[string,any]}
+ * @package
+ */
+export function extractKeywordValueProcessorSpec(keywordSpec) {
+  let keyword;
+  let args = [];
+  if (typeof keywordSpec === 'string' && (keywordSpec.charAt(0) === '$')) {
+    keyword = keywordSpec.slice(1);
+  }
+  else if (typeof keywordSpec === 'object' && keywordSpec !== null) {
+    const keys = Object.keys(keywordSpec);
+
+    if (keys.length === 1 && keys[0].charAt(0) === '$') {
+      keyword = keys[0].slice(1);
+      args = keywordSpec[keys[0]];
+    }
+  }
+
+  if (!keyword) {
+    throw new SchemaError('Not a keyword operation');
+  }
+
+  return [keyword, args];
+}
+
+/**
+ * Check whether a candidate spec is legal
+ * @param {any} spec
+ * @returns {boolean}
+ * @package
+ */
+export function isLegalValueProcessorSpec(spec) {
+  if (spec === null || spec === undefined) {
+    return false;
+  }
+  if (spec instanceof ValueProcessor) {
+    return true;
+  }
+  if (Array.isArray(spec)) {
+    for (let s = 0; s < spec.length; ++s) {
+      if (!isLegalValueProcessorSpec(spec[s])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  if (isPlainObject(spec)) {
+    let dollar = 0;
+    for (const key of Object.keys(spec)) {
+      if (key.charAt(0) === '$') {
+        dollar++
+      }
+      if (dollar > 1) {
+        return false;
+      }
+      if (key !== '$literal' && !isLegalValueProcessorSpec(spec[key])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  return true;
+}