@versionzero/schema 1.0.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versionzero/schema",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "A composable schema library that supports asynchronous processing",
   "license": "Apache-2.0",
   "publishConfig": {

package/src/compiled-schema.js

@@ -1256,7 +1256,7 @@ export class CompiledSchema
    */
   _process(input, target, options = {}) {
     const location = options?.location ?? new SchemaLocation(this);
-    const context = (options.context instanceof TraversalContext) ? options.context : new TraversalContext(location, {strict: options?.strict, deep: options?.deep, debug: options?.debug});
+    const context = (options.context instanceof TraversalContext) ? options.context : new TraversalContext(location, {strict: options?.strict, deep: options?.deep, debug: options?.debug, stats: options?.stats});
 
     const executors = [];
 

package/src/schema-resolver.js

@@ -51,6 +51,8 @@ export function registerCoreLibrary(libraryFn) {
 /** @import { SchemaData } from './types.js' */
 /** @import { ValueProcessorDefinition, ValueProcessorSpec, ValueProcessorBuilder, ValueProcessorFunction, ValueProcessorArgs, ValueProcessorParameter, KeywordValueProcessorSpec } from './value-processor/value-processor.js' */
 
+/** @typedef {{name:string, namespace?:string, schema:Schema}} RegisteredSchemaInfo */
+
 /**
  * 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.
@@ -58,7 +60,7 @@ export function registerCoreLibrary(libraryFn) {
 export class SchemaResolver
 {
   /**
-   * @type {Map<string,Schema>}
+   * @type {Map<string,RegisteredSchemaInfo>}
    */
   #schemaMap = new Map();
   /**
@@ -85,7 +87,7 @@ export class SchemaResolver
       throw new ResolverError(`Registry can only store Schema instances`);
     }
     const registryName = toKebabCase(name);
-    this.#schemaMap.set(registryName, schema);
+    this.#schemaMap.set(registryName, {name: registryName, schema});
     return this;
   }
 
@@ -96,11 +98,11 @@ export class SchemaResolver
    */
   getSchema(name) {
     const registryName = toKebabCase(name);
-    const schema = this.#schemaMap.get(registryName);
-    if (!schema) {
+    const schemaInfo = this.#schemaMap.get(registryName);
+    if (!schemaInfo) {
       throw new ResolverError(`Unable to resolve "${name}"`);
     }
-    return schema;
+    return schemaInfo.schema;
   }
 
   /**
@@ -113,6 +115,14 @@ export class SchemaResolver
     return this.#schemaMap.has(registryName);
   }
 
+  /**
+   * return all registered schemas
+   * @returns {RegisteredSchemaInfo[]}
+   */
+  listRegisteredSchemas() {
+    return [...this.#schemaMap.values()];
+  }
+
   /**
    * Register a value processor definition
    * @param {ValueProcessorDefinition} definition
@@ -121,20 +131,24 @@ export class SchemaResolver
   registerValueProcessorDefinition(definition) {
     const {keyword, process, description, build} = definition;
 
-    if (!keyword) {
+    if (!keyword || typeof keyword !== 'string') {
       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`);
+      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`);
+      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`);
+      throw new ResolverError(`Processor definition description for '$${keyword}' must be a string`);
+    }
+
+    if (this.#constantKeywordProcessors[`${keyword}`]) {
+      throw new ResolverError(`Processor keyword conflict with builtin literal '$${keyword}'`)
     }
 
     this.#processorMap.set(keyword, definition);
@@ -176,6 +190,24 @@ export class SchemaResolver
     });
   }
 
+  /**
+   * List all registered value processors (and reserved builtins)
+   *
+   * @returns {ValueProcessorDefinition[]}
+   */
+  listValueProcessorDefinitions() {
+
+    return [
+                        ...Object.entries(this.#constantKeywordProcessors).map(([k,v]) => ({
+                          keyword: k,
+                          build: (() => v),
+                          spec: `$${k}`,
+                          reserved: true
+                        })),
+                        ...this.#processorMap.values()
+    ];
+  }
+
 
   /**
    * Load a library of schemas and/or value processors.
@@ -209,13 +241,11 @@ export class SchemaResolver
 
   }
 
-
-
-  _constantKeywords = {
-    $null: NULL_EXECUTOR,
-    $undefined: UNDEFINED_EXECUTOR,
-    $true: TRUE_EXECUTOR,
-    $false: FALSE_EXECUTOR
+  #constantKeywordProcessors = {
+    'null': new ComposedValueProcessor(NULL_EXECUTOR, '$null'),
+    'undefined': new ComposedValueProcessor(UNDEFINED_EXECUTOR, '$undefined'),
+    'true': new ComposedValueProcessor(TRUE_EXECUTOR, '$true'),
+    'false': new ComposedValueProcessor(FALSE_EXECUTOR, '$false')
   }
 
   /**
@@ -230,8 +260,8 @@ export class SchemaResolver
     }
     const [keyword, rawArgs] = extractKeywordValueProcessorSpec(spec);
 
-    if (this._constantKeywords[spec]) {
-      return new ComposedValueProcessor(this._constantKeywords[spec], spec);
+    if (this.#constantKeywordProcessors[keyword]) {
+      return this.#constantKeywordProcessors[keyword];
     }
 
     if (keyword === 'literal') {

package/src/traversal/traversal-context.js

@@ -13,6 +13,7 @@ import { SchemaError } from '../errors.js';
  * @property {boolean} [strict]
  * @property {boolean} [deep]
  * @property {boolean} [debug]
+ * @property {object} [stats]
  */
 
 /** @typedef {TraversalContextStandardOptions & {[key:string]:any}} TraversalContextOptions */
@@ -28,7 +29,7 @@ export class TraversalContext
     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._options = {...options, deep: options.deep ?? false, strict: options.strict ?? true, debug: options.debug ?? false, stats: options.stats ?? {}}
 
     this.traversals = 0;
     this.counter = 0;
@@ -52,6 +53,10 @@ export class TraversalContext
     return this._options.strict;
   }
 
+  get stats() {
+    return this._options.stats;
+  }
+
   update() {
     this.counter++;
     this.final = false;
@@ -192,6 +197,11 @@ export class TraversalContext
     let done = false;
 
     const updateDone = (counter) => {
+      this.traversals++;
+
+      this.stats.traversals = this.traversals;
+      this.stats.updates = this.counter;
+
       if (this.isComplete) {
         done = true;
       }
@@ -222,7 +232,6 @@ export class TraversalContext
           );
         }
         updateDone(counter);
-        this.traversals++;
       }
       return result;
     }

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

@@ -44,11 +44,13 @@ import { SchemaLocation } from '../schema-location.js';
 /**
  * @typedef {object} ValueProcessorDefinition
  * @property {string} keyword
+ * @property {string} [namespace]
  * @property {ValueProcessorFunction} [process]
  * @property {ValueProcessorParameter[]} [parameters]
  * @property {string} [description]
  * @property {ValueProcessorBuilder} [build]
  * @property {ValueProcessorDescriber} [describe]
+ * @property {boolean} [reserved]
  */
 
 

package/types/schema-resolver.d.ts

@@ -9,6 +9,7 @@ export function registerCoreLibrary(libraryFn: (resolver: SchemaResolver, option
 /** @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' */
+/** @typedef {{name:string, namespace?:string, schema:Schema}} RegisteredSchemaInfo */
 /**
  * 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.
@@ -33,6 +34,11 @@ export class SchemaResolver {
      * @returns {boolean}
      */
     hasSchema(name: string): boolean;
+    /**
+     * return all registered schemas
+     * @returns {RegisteredSchemaInfo[]}
+     */
+    listRegisteredSchemas(): RegisteredSchemaInfo[];
     /**
      * Register a value processor definition
      * @param {ValueProcessorDefinition} definition
@@ -54,6 +60,12 @@ export class SchemaResolver {
      * @returns {SchemaResolver}
      */
     registerValueProcessorBuilder(keyword: string, build: ValueProcessorBuilder): SchemaResolver;
+    /**
+     * List all registered value processors (and reserved builtins)
+     *
+     * @returns {ValueProcessorDefinition[]}
+     */
+    listValueProcessorDefinitions(): ValueProcessorDefinition[];
     /**
      * Load a library of schemas and/or value processors.
      *
@@ -68,12 +80,6 @@ export class SchemaResolver {
      * @returns {Promise<void>}
      */
     use(libraryFunction: (resolver: SchemaResolver, options: object) => Promise<void> | void, options?: object): Promise<void>;
-    _constantKeywords: {
-        $null: ConstantExecutor;
-        $undefined: ConstantExecutor;
-        $true: ConstantExecutor;
-        $false: ConstantExecutor;
-    };
     /**
      * @param {SchemaCompiler} compiler
      * @param {KeywordValueProcessorSpec} spec
@@ -131,11 +137,15 @@ export type SchemaResolverLibraryOptions = {
     name: string;
     [key: string]: any;
 };
+export type RegisteredSchemaInfo = {
+    name: string;
+    namespace?: string;
+    schema: Schema;
+};
 import { Schema } from './schema.js';
 import type { ValueProcessorDefinition } from './value-processor/value-processor.js';
 import type { ValueProcessorFunction } from './value-processor/value-processor.js';
 import type { ValueProcessorBuilder } from './value-processor/value-processor.js';
-import { ConstantExecutor } from './executor/executor.js';
 import { SchemaCompiler } from './schema-compiler.js';
 import type { KeywordValueProcessorSpec } from './value-processor/value-processor.js';
 import { ValueProcessor } from './value-processor/value-processor.js';

package/types/traversal/traversal-context.d.ts

@@ -3,6 +3,7 @@
  * @property {boolean} [strict]
  * @property {boolean} [deep]
  * @property {boolean} [debug]
+ * @property {object} [stats]
  */
 /** @typedef {TraversalContextStandardOptions & {[key:string]:any}} TraversalContextOptions */
 export class TraversalContext {
@@ -17,6 +18,7 @@ export class TraversalContext {
         deep: boolean;
         strict: boolean;
         debug: boolean;
+        stats: any;
     };
     traversals: number;
     counter: number;
@@ -28,9 +30,11 @@ export class TraversalContext {
         deep: boolean;
         strict: boolean;
         debug: boolean;
+        stats: any;
     };
     get deep(): boolean;
     get strict(): boolean;
+    get stats(): any;
     update(): void;
     set final(finalize: boolean);
     get final(): boolean;
@@ -58,6 +62,7 @@ export type TraversalContextStandardOptions = {
     strict?: boolean | undefined;
     deep?: boolean | undefined;
     debug?: boolean | undefined;
+    stats?: object;
 };
 export type TraversalContextOptions = TraversalContextStandardOptions & {
     [key: string]: any;

package/types/value-processor/value-processor.d.ts

@@ -31,11 +31,13 @@
 /**
  * @typedef {object} ValueProcessorDefinition
  * @property {string} keyword
+ * @property {string} [namespace]
  * @property {ValueProcessorFunction} [process]
  * @property {ValueProcessorParameter[]} [parameters]
  * @property {string} [description]
  * @property {ValueProcessorBuilder} [build]
  * @property {ValueProcessorDescriber} [describe]
+ * @property {boolean} [reserved]
  */
 /**
  * @augments {Executor<any>}
@@ -82,11 +84,13 @@ export type ValueProcessorDescriber = (args: {
 } | ValueProcessor[] | undefined) => string | undefined;
 export type ValueProcessorDefinition = {
     keyword: string;
+    namespace?: string | undefined;
     process?: ValueProcessorFunction | undefined;
     parameters?: ValueProcessorParameter[] | undefined;
     description?: string | undefined;
     build?: ValueProcessorBuilder | undefined;
     describe?: ValueProcessorDescriber | undefined;
+    reserved?: boolean | undefined;
 };
 import { Executor } from '../executor/executor.js';
 import { SchemaLocation } from '../schema-location.js';