@versionzero/schema 1.0.0

package/src/schema-resolver.js

@@ -0,0 +1,546 @@
+import { CompiledSchema } from './compiled-schema.js';
+import { Schema } from './schema.js';
+import { SchemaCompiler } from './schema-compiler.js';
+
+import {
+  ConstantExecutor,
+  Executor, FALSE_EXECUTOR,
+  FunctionExecutor,
+  NULL_EXECUTOR,
+  toExecutor, TRUE_EXECUTOR,
+  UNDEFINED_EXECUTOR
+} from './executor/executor.js';
+import { FunctionValueProcessor } from './value-processor/function-value-processor.js';
+import {
+  extractKeywordValueProcessorSpec,
+  isKeywordValueProcessorSpec,
+  isLegalValueProcessorSpec
+} from './value-processor/spec.js';
+import { ComposedValueProcessor } from './value-processor/composed-value-processor.js';
+import { ValueProcessor } from './value-processor/value-processor.js';
+import { ObjectExecutor } from './executor/object-executor.js';
+import { ArrayExecutor } from './executor/array-executor.js';
+import { DefinedValueProcessor } from './value-processor/defined-value-processor.js';
+import { ResolverError, SchemaError } from './errors.js';
+import { toKebabCase } from './helpers/case.js';
+import { isNativeClass, map } from './helpers/object.js';
+import { parseRegExp } from './helpers/regex.js';
+
+/**
+ * Module-level registry of core library functions.  Populated by the package entry
+ * point (`src/index.js`) before any SchemaResolver is constructed.  Each registered
+ * function is called synchronously in the constructor of every new SchemaResolver.
+ *
+ * @type {Array<(resolver: SchemaResolver, options: object) => void>}
+ */
+const _coreLibraries = [];
+
+/**
+ * Register a core library function to be loaded into every new SchemaResolver.
+ * Called by the package entry point; not part of the public API.
+ *
+ * @param {(resolver: SchemaResolver, options: object) => void} libraryFn
+ * @internal
+ */
+export function registerCoreLibrary(libraryFn) {
+  _coreLibraries.push(libraryFn);
+}
+
+/** @typedef {{name:string, [key:string]:any}} SchemaResolverLibraryOptions */
+
+/** @import { SchemaData } from './types.js' */
+/** @import { ValueProcessorDefinition, ValueProcessorSpec, ValueProcessorBuilder, ValueProcessorFunction, ValueProcessorArgs, ValueProcessorParameter, KeywordValueProcessorSpec } from './value-processor/value-processor.js' */
+
+/**
+ * The SchemaResolver uses its internal registries of named schemas and value processor keywords to
+ * convert Schemas containing unresolved references into resolved Schemas that are fully self-contained.
+ */
+export class SchemaResolver
+{
+  /**
+   * @type {Map<string,Schema>}
+   */
+  #schemaMap = new Map();
+  /**
+   * @type {Map<string,ValueProcessorDefinition>}
+   */
+  #processorMap = new Map();
+
+  #resolveCache = new Map();
+
+  constructor() {
+    for (const lib of _coreLibraries) {
+      this.use(lib, { sync: true });
+    }
+  }
+
+  /**
+   * add a schema to the registry
+   * @param {string} name
+   * @param {Schema} schema
+   * @returns {SchemaResolver}
+   */
+  registerSchema(name, schema) {
+    if (!(schema instanceof Schema)) {
+      throw new ResolverError(`Registry can only store Schema instances`);
+    }
+    const registryName = toKebabCase(name);
+    this.#schemaMap.set(registryName, schema);
+    return this;
+  }
+
+  /**
+   * return the registered schema with a given name
+   * @param {string} name
+   * @returns {Schema}
+   */
+  getSchema(name) {
+    const registryName = toKebabCase(name);
+    const schema = this.#schemaMap.get(registryName);
+    if (!schema) {
+      throw new ResolverError(`Unable to resolve "${name}"`);
+    }
+    return schema;
+  }
+
+  /**
+   * return true if there exists a registered schema with a given name
+   * @param {string} name
+   * @returns {boolean}
+   */
+  hasSchema(name) {
+    const registryName = toKebabCase(name);
+    return this.#schemaMap.has(registryName);
+  }
+
+  /**
+   * Register a value processor definition
+   * @param {ValueProcessorDefinition} definition
+   * @returns {SchemaResolver}
+   */
+  registerValueProcessorDefinition(definition) {
+    const {keyword, process, description, build} = definition;
+
+    if (!keyword) {
+      throw new ResolverError('Missing keyword in processor definition');
+    }
+
+    if (process && build) {
+      throw new ResolverError(`Processor definition for '${keyword}' cannot define both process and build functions`);
+    }
+
+    if (!process && !build) {
+      throw new ResolverError(`Processor definition for '${keyword}' must have define a process or build function`);
+    }
+
+    if (description && typeof description !== 'string') {
+      throw new ResolverError(`Processor definition description for '${keyword}' must be a string`);
+    }
+
+    this.#processorMap.set(keyword, definition);
+    return this;
+  }
+
+  /**
+   * register a named "simple" ValueProcessor
+   * @param {string} keyword
+   * @param {ValueProcessorFunction} process
+   * @param {string} [description]
+   * @returns {SchemaResolver}
+   */
+  registerValueProcessor(keyword, process, description) {
+    if (typeof process !== 'function') {
+      throw new ResolverError(`Processor for keyword '${keyword}' must be a function`);
+    }
+    return this.registerValueProcessorDefinition({
+      keyword,
+      parameters: [],
+      process,
+      description: description ?? keyword
+    });
+  }
+
+  /**
+   * register a complex ValueProcessor that needs to be built based on schema processor spec
+   * @param {string} keyword
+   * @param {ValueProcessorBuilder} build
+   * @returns {SchemaResolver}
+   */
+  registerValueProcessorBuilder(keyword, build) {
+    if (typeof build !== 'function') {
+      throw new ResolverError(`Processor builder for keyword '${keyword}' must be a function`);
+    }
+    return this.registerValueProcessorDefinition({
+      keyword,
+      build
+    });
+  }
+
+
+  /**
+   * Load a library of schemas and/or value processors.
+   *
+   * Expects a (potentially async) library function accepting a SchemaResolver.  Options passed to `use`
+   * will be propagated to the library function.
+   *
+   * The `name` option is used for error messages.
+   * The `sync` option is used internally to enforce the core library does not get loaded asynchronously.
+   *
+   * @param {(resolver:SchemaResolver, options:object) => Promise<void>|void} libraryFunction
+   * @param {object} [options]
+   * @returns {Promise<void>}
+   */
+  async use(libraryFunction, options = {}) {
+    try {
+      const libraryResult = libraryFunction(this, options);
+      if (libraryResult instanceof Promise && options.sync) {
+        throw new ResolverError('Cannot load async library');
+      }
+      return await libraryResult;
+    }
+    catch (error) {
+      if (error instanceof ResolverError) {
+        throw error;
+      }
+      else {
+        throw new ResolverError(`Error loading library`, {cause: error});
+      }
+    }
+
+  }
+
+
+
+  _constantKeywords = {
+    $null: NULL_EXECUTOR,
+    $undefined: UNDEFINED_EXECUTOR,
+    $true: TRUE_EXECUTOR,
+    $false: FALSE_EXECUTOR
+  }
+
+  /**
+   * @param {SchemaCompiler} compiler
+   * @param {KeywordValueProcessorSpec} spec
+   * @param {boolean} [recursive]
+   * @returns {ValueProcessor}
+   */
+  compileKeywordValueProcessorSpec(compiler, spec, recursive) {
+    if (!isKeywordValueProcessorSpec(spec)) {
+      throw new ResolverError('Not a keyword processor spec');
+    }
+    const [keyword, rawArgs] = extractKeywordValueProcessorSpec(spec);
+
+    if (this._constantKeywords[spec]) {
+      return new ComposedValueProcessor(this._constantKeywords[spec], spec);
+    }
+
+    if (keyword === 'literal') {
+      // note that in the semantically odd case where a user didn't provide args, the literal will be an empty array!
+      return new ComposedValueProcessor(new ConstantExecutor(rawArgs), spec);
+    }
+
+    const definition = this.#processorMap.get(keyword);
+
+    if (!definition) {
+      throw new ResolverError(`Unknown processor keyword: $${keyword}`);
+    }
+    // This "map" call will wrap any non-collection as an array:
+    const args = map(rawArgs, arg => this.compileValueProcessorSpec(compiler, arg, recursive));
+
+    if (definition.build) {
+      const processor = definition.build(args, {compiler});
+      if (processor?.['process']) {
+        return this.compileValueProcessorSpec(compiler, processor, recursive);
+      }
+      if (!(processor instanceof ValueProcessor)) {
+        throw new SchemaError(`ValueProcessor builder for $${keyword} returned invalid`, {value:processor});
+      }
+      return processor;
+    }
+    return new DefinedValueProcessor(definition, args);
+  }
+
+
+  compileSchemaValueProcessorSpec(compiler, spec) {
+    let compiledSchema;
+
+    if (compiler.compileCache.has(spec)) {
+      return new ComposedValueProcessor(new ConstantExecutor(compiler.compileCache.get(spec)), spec);
+    }
+    return new ComposedValueProcessor(
+      new FunctionExecutor(
+        async () => {
+          if (compiler.compileCache.has(spec)) {
+            return compiler.compileCache.get(spec);
+          }
+          compiledSchema ??= (spec instanceof CompiledSchema)? spec : await compiler.compile(spec);
+          return compiledSchema;
+        }
+      ), spec);
+  }
+
+  /**
+   * Convert a processor specification into an executor
+   * @param {SchemaCompiler} compiler
+   * @param {ValueProcessorSpec} spec - The processor specification
+   * @param {boolean} [recursive]
+   * @returns {ValueProcessor}
+   */
+  compileValueProcessorSpecObject(compiler, spec, recursive = false) {
+
+    if (typeof spec !== 'object') {
+      throw new ResolverError('not a spec object');
+    }
+
+    /** @type {{[key:string]:ValueProcessor}} */
+    const out = {};
+    for (const [key, value] of Object.entries(spec)) {
+      out[key] = this.compileValueProcessorSpec(compiler, value, recursive);
+    }
+    return new ComposedValueProcessor(new ObjectExecutor(out), map(out, p => p.spec));
+  }
+
+  /**
+   * Convert a processor specification into an executor
+   * @param {SchemaCompiler} compiler
+   * @param {ValueProcessorSpec} spec - The processor specification
+   * @param {boolean} [recursive]
+   * @returns {ValueProcessor}
+   */
+  compileValueProcessorSpecArray(compiler, spec, recursive = false) {
+
+    if (!Array.isArray(spec)) {
+      throw new ResolverError('not a spec array');
+    }
+    /** @type {ValueProcessor[]} */
+    const out = [];
+    for (let i = 0; i < spec.length; ++i) {
+      out[i] = this.compileValueProcessorSpec(compiler, spec[i], recursive);
+    }
+    return new ComposedValueProcessor(new ArrayExecutor(out), map(out, p => p.spec));
+  }
+
+
+  /**
+   * Convert a value processor specification into a value processor executor
+   *
+   * @param {SchemaCompiler} compiler
+   * @param {ValueProcessorSpec} spec - The processor specification
+   * @param {boolean} [recursive]
+   * @returns {ValueProcessor}
+   */
+  compileValueProcessorSpec(compiler, spec, recursive = false) {
+
+    if (!isLegalValueProcessorSpec(spec)) {
+      throw new SchemaError(`Invalid value processor specification`, {value: spec});
+    }
+
+    /** @type {ValueProcessor} */
+    let valueProcessor;
+
+    if (spec === undefined) {
+      valueProcessor = new ValueProcessor(); // passthrough
+    }
+    else if (spec === null) {
+      spec = '$null';
+      valueProcessor = new ComposedValueProcessor(NULL_EXECUTOR, '$null');
+    }
+    else if (spec === '$resolver') {
+      valueProcessor = new ComposedValueProcessor(new ConstantExecutor(this), spec);
+    }
+    else if (spec === '$compiler') {
+      valueProcessor = new ComposedValueProcessor(new ConstantExecutor(compiler), spec);
+    }
+    else if (spec instanceof ValueProcessor) {
+      valueProcessor = spec;
+    }
+    else if (spec instanceof Schema) {
+      valueProcessor = this.compileSchemaValueProcessorSpec(compiler, spec);
+    }
+    else if (spec instanceof CompiledSchema) {
+      valueProcessor = new ComposedValueProcessor(new ConstantExecutor(spec), spec);
+    }
+    else if (isKeywordValueProcessorSpec(spec)) {
+      valueProcessor = this.compileKeywordValueProcessorSpec(compiler, spec, recursive);
+    }
+    else if (spec instanceof Executor) {
+      valueProcessor = new ComposedValueProcessor(spec, spec);
+    }
+    else if (spec instanceof RegExp) {
+      valueProcessor = new ComposedValueProcessor(new ConstantExecutor(spec), spec, `${spec}`);
+    }
+    else if (spec instanceof Date) {
+      valueProcessor = new ComposedValueProcessor(new ConstantExecutor(spec), spec, spec.toISOString());
+    }
+    else if (typeof spec === 'string' && spec.startsWith('/') && spec.lastIndexOf('/') > 0) {
+      try {
+        const regex = parseRegExp(spec);
+        valueProcessor = new ComposedValueProcessor(new ConstantExecutor(regex), regex, `${regex}`);
+      }
+      catch {
+        throw new SchemaError(`Invalid regex pattern`, {value: spec});
+      }
+    }
+    else if (spec instanceof SchemaCompiler) {
+      valueProcessor = new ComposedValueProcessor(new ConstantExecutor(spec), spec);
+    }
+    else if (typeof spec === 'object' && typeof spec.process === 'function') {
+      valueProcessor = new DefinedValueProcessor(spec);
+    }
+    else if (isNativeClass(spec)) {
+      valueProcessor = new ComposedValueProcessor(new ConstantExecutor(spec), spec, spec.name);
+    }
+    else if (typeof spec === 'function') {
+      valueProcessor = new FunctionValueProcessor(spec);
+    }
+    else if (Array.isArray(spec)) {
+      valueProcessor = this.compileValueProcessorSpecArray(compiler, spec, recursive);
+    }
+    else if (typeof spec === 'object') {
+      valueProcessor = this.compileValueProcessorSpecObject(compiler, spec, recursive);
+    }
+    else {
+      valueProcessor = new ComposedValueProcessor(toExecutor(spec), spec)
+    }
+    if (valueProcessor.spec === undefined) {
+      valueProcessor.spec = spec;
+    }
+
+    return valueProcessor;
+  }
+
+  compiler() {
+    return new SchemaCompiler(this);
+  }
+
+
+  /**
+   * Build a compiled schema from the schema definition.
+   * @param {Schema|CompiledSchema|SchemaData} inputSchema
+   * @returns {CompiledSchema}
+   */
+  compile(inputSchema) {
+    if (inputSchema instanceof CompiledSchema) {
+      return inputSchema;
+    }
+    const compiler = new SchemaCompiler(this);
+    return compiler.compile(inputSchema);
+  }
+
+  /**
+   * Create a new Schema that contains the flattened hierarchy of all resolved base schemas.
+   *
+   * This can be useful if you need to make changes to the full schema, e.g. prepending processors
+   * before the base class handlers.
+   *
+   * @param {Schema|CompiledSchema|SchemaData|string} inputSchema
+   * @param {boolean} [recursive]
+   * @returns {Schema|CompiledSchema}
+   */
+  resolve(inputSchema, recursive = true) {
+    if (inputSchema instanceof CompiledSchema) {
+      return inputSchema;
+    }
+    if (typeof inputSchema === 'string') {
+      if (this.hasSchema(inputSchema)) {
+        inputSchema = this.getSchema(inputSchema);
+      }
+      else {
+        // we don't know it - let's pretend it was just a base.
+        inputSchema = new Schema(inputSchema);
+      }
+    }
+    if (this.#resolveCache.has(inputSchema)) {
+      return this.#resolveCache.get(inputSchema);
+    }
+    const outputSchema = new Schema();
+
+    this.#resolveCache.set(inputSchema, outputSchema);
+    this.#resolveCache.set(outputSchema, outputSchema);
+
+    /** @type {Schema|CompiledSchema|SchemaData|undefined} */
+    let source = inputSchema;
+
+    let strictCompileError;
+
+    let foundType = false;  // we need to hit one of our fundamental types, otherwise we'll use "any"
+
+    while (source !== undefined) {
+      for (const [propName, propSchema] of Object.entries(source.properties ?? {})) {
+        if (!outputSchema.properties.hasOwnProperty(propName)) {
+          const needsResolve = recursive || !(propSchema instanceof Schema || propSchema instanceof CompiledSchema)
+          outputSchema.properties[propName] = needsResolve ? this.resolve(propSchema) : propSchema;
+        }
+      }
+      for (const [metaName, metaValue] of Object.entries(source.metadata ?? {})) {
+        if (!outputSchema.metadata.hasOwnProperty(metaName)) {
+          outputSchema.metadata[metaName] = metaValue;
+        }
+      }
+      for (const [discriminatorValue, unionSchema] of Object.entries(source.unionSchemas ?? {})) {
+        if (!outputSchema.unionSchemas.hasOwnProperty(discriminatorValue)) {
+          const needsResolve = recursive || !(unionSchema instanceof Schema || unionSchema instanceof CompiledSchema)
+          outputSchema.unionSchemas[discriminatorValue] = needsResolve ? this.resolve(unionSchema) : unionSchema;
+        }
+      }
+      for (const [handlerName, handlerValues] of Object.entries(source.handlers ?? {})) {
+        // TODO - add an option that enables a schema to opt out of base handler inheritance
+        if (!outputSchema.handlers.hasOwnProperty(handlerName)) {
+          outputSchema.handlers[handlerName] = [];
+        }
+        outputSchema.handlers[handlerName].unshift(...handlerValues);
+      }
+
+      for (const [optionName, optionValue] of Object.entries(source.options ?? {})) {
+        if (!outputSchema.options.hasOwnProperty(optionName)) {
+          outputSchema.options[optionName] = optionValue;
+          if (optionName === 'type') {
+            foundType = true;
+          }
+        }
+      }
+      if (source instanceof CompiledSchema) {
+        source = undefined;
+      }
+      else {
+        if (source.base === undefined && !foundType) {
+          source.base = 'any';
+        }
+
+        if (source.base) {
+          if (this.hasSchema(source.base)) {
+            source = this.getSchema(source.base);
+          }
+          else {
+            // base schema is undefined; this is only an error if you actually try to use it
+            // allow error to be omitted if the schema is marked "lax"
+            const base = `${source.base}`
+
+            strictCompileError = new ResolverError(`Unable to resolve "${base}"`)
+            outputSchema.normalizer((value, config, location, options) => {
+              const strict = location.schema?.strict ?? options?.strict;
+              if (strict !== false) {
+                throw strictCompileError;
+              }
+              return undefined;
+            });
+            source = undefined;
+          }
+        }
+        else {
+          source = undefined;
+        }
+      }
+      //source = (source instanceof CompiledSchema)? undefined : (source.base ? this.getSchema(source.base) : undefined);
+    }
+    if (!(inputSchema instanceof CompiledSchema) && inputSchema.base && !outputSchema.metadata.parserTypeHint) {
+      outputSchema.metadata.parserTypeHint = inputSchema.base;
+    }
+    if (outputSchema.options.strict !== false && strictCompileError) {
+      throw strictCompileError;
+    }
+    return outputSchema;
+  }
+
+
+}