@versionzero/schema 1.0.0 → 1.1.0

package/README.md

@@ -227,7 +227,7 @@ You can think of it like having a toolkit for composing rich runtime-enforced in
 with reflection; embracing the dynamic nature of JavaScript, rather than pretending it has
 static types.
 
-_Read more about this [in the full documentation](https://docs.v0.net/schema/rationale)._
+_Read more about this [in the full documentation](https://docs.v0.net/schema/guide/rationale)._
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versionzero/schema",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A composable schema library that supports asynchronous processing",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -63,7 +63,7 @@
     "test:browser": "playwright test",
     "test:all": "npm test && npm run test:browser",
     "clean": "rm -rf types docs-output* processors-output* .mdrun .c8 .nyc_output",
-    "release:dry": "npx -p semantic-release@24 -p @semantic-release/exec@7 semantic-release --dry-run --no-ci"
+    "release:dry": "npx -p semantic-release@24 -p @semantic-release/exec@7 -p @semantic-release/changelog@6 -p @semantic-release/git@10 semantic-release --dry-run --no-ci"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",

package/src/compiled-schema.js

@@ -144,16 +144,16 @@ export class CompiledSchema
   }
 
   /**
-   * Handlers are associated with asynchronous value processors.
+   * Handlers are associated with value processors.
    *
-   * The "friendly" handler definitions from the source Schema are each compiled into asynchronous functions
-   * that run as a pipeline.
+   * The "friendly" handler definitions from the source Schema are each compiled into an array
+   * of functions (sync or async) that run as a pipeline.
    *
-   * All handlers have the same async signature, receiving:
+   * All value processors have the same signature, receiving:
    *   1. a value to be processed by the current schema
-   *   2. a reference to the top-level aggregate target being built or processed by the entire schema hierarchy
-   *   3. a location defining the current schema and the traversal path to where it was encountered
-   *   5. any (unmanaged / developer defined) options passed to whatever invoked the handler processing
+   *   2. the top-level aggregate target value being built or processed by the entire schema hierarchy
+   *   3. a location cursor referencing the associated schema and the traversal path to where it was encountered
+   *   4. any (unmanaged / developer defined) options passed to whatever invoked the handler processing
    *
    * The compiled handlers may vary in their return types and exception handling behavior.
    *
@@ -617,7 +617,7 @@ export class CompiledSchema
 
   /**
    * Use the registered discriminator to return a matching union schema, or undefined if the union cannot be resolved.
-   * Discriminator functions must return either one of the unionSchema members, a unionSchema key, or undefined.
+   * Discriminator functions must return either a unionSchema key or (compiled) member reference, or undefined.
    *
    * (This is an executor function that may return synchronous or asynchronous results.)
    *
@@ -668,7 +668,7 @@ export class CompiledSchema
   }
   /**
    * Use the registered discriminator to return a matching union schema, or undefined if the union cannot be resolved.
-   * Discriminator functions must return either one of the unionSchema members, a unionSchema key, or undefined.
+   * Discriminator functions must return either a unionSchema key or (compiled) member reference, or undefined.
    *
    * (This an async wrapper around the internal `_discriminateUnion` executor function.)
    *
@@ -899,7 +899,7 @@ export class CompiledSchema
    * Finalize a transformed input value by running any necessary post-processing steps.
    *
    * Runs all finalizer value processors in a pipeline until one returns undefined or throws an error.
-   * - The input to the pipeline is be assumed to be transformed.
+   * - The input to the pipeline is assumed to be transformed.
    * - Finalizers are generally only required for incremental schemas that need to check child values.
    * - A finalizer on the root schema (or that checks for the root path, if the root schema is shared)
    *   can act as an "entire output" finalizer.
@@ -950,7 +950,7 @@ export class CompiledSchema
    * Finalize a transformed input value by running any necessary post-processing steps.
    *
    * Runs all finalizer value processors in a pipeline until one returns undefined or throws an error.
-   * - The input to the pipeline is be assumed to be transformed.
+   * - The input to the pipeline is assumed to be transformed.
    * - Finalizers are generally only required for incremental schemas that need to check child values.
    * - A finalizer on the root schema (or that checks for the root path, if the root schema is shared)
    *   can act as an "entire output" finalizer.

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/schema.js

@@ -459,7 +459,7 @@ export class Schema
   }
 
   /**
-   * The discriminator handler returns the key or schema of the union member that should be used
+   * The discriminator handler returns the key or schema of the union member that should be used.
    * This function appends a single value processor to the handler pipeline.
    *
    * @param {ValueProcessorSpec} spec
@@ -470,7 +470,7 @@ export class Schema
   }
 
   /**
-   * The discriminator handler returns the key or schema of the union member that should be used
+   * The discriminator handler returns the key or schema of the union member that should be used.
    * This function applies multiple value processors to the handler pipeline.
    * (Note that it would be highly unusual to want more than one!)
    *

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/compiled-schema.d.ts

@@ -71,16 +71,16 @@ export class CompiledSchema {
      */
     get propertyEntries(): IteratorObject<[string, CompiledSchema]>;
     /**
-     * Handlers are associated with asynchronous value processors.
+     * Handlers are associated with value processors.
      *
-     * The "friendly" handler definitions from the source Schema are each compiled into asynchronous functions
-     * that run as a pipeline.
+     * The "friendly" handler definitions from the source Schema are each compiled into an array
+     * of functions (sync or async) that run as a pipeline.
      *
-     * All handlers have the same async signature, receiving:
+     * All value processors have the same signature, receiving:
      *   1. a value to be processed by the current schema
-     *   2. a reference to the top-level aggregate target being built or processed by the entire schema hierarchy
-     *   3. a location defining the current schema and the traversal path to where it was encountered
-     *   5. any (unmanaged / developer defined) options passed to whatever invoked the handler processing
+     *   2. the top-level aggregate target value being built or processed by the entire schema hierarchy
+     *   3. a location cursor referencing the associated schema and the traversal path to where it was encountered
+     *   4. any (unmanaged / developer defined) options passed to whatever invoked the handler processing
      *
      * The compiled handlers may vary in their return types and exception handling behavior.
      *
@@ -386,7 +386,7 @@ export class CompiledSchema {
     _checkValue(value: any, ErrorClass: any): any;
     /**
      * Use the registered discriminator to return a matching union schema, or undefined if the union cannot be resolved.
-     * Discriminator functions must return either one of the unionSchema members, a unionSchema key, or undefined.
+     * Discriminator functions must return either a unionSchema key or (compiled) member reference, or undefined.
      *
      * (This is an executor function that may return synchronous or asynchronous results.)
      *
@@ -400,7 +400,7 @@ export class CompiledSchema {
     _discriminateUnion(value: any, target?: any, location?: SchemaLocation, options?: object): CompiledSchema | undefined | Promise<CompiledSchema | undefined>;
     /**
      * Use the registered discriminator to return a matching union schema, or undefined if the union cannot be resolved.
-     * Discriminator functions must return either one of the unionSchema members, a unionSchema key, or undefined.
+     * Discriminator functions must return either a unionSchema key or (compiled) member reference, or undefined.
      *
      * (This an async wrapper around the internal `_discriminateUnion` executor function.)
      *
@@ -526,7 +526,7 @@ export class CompiledSchema {
      * Finalize a transformed input value by running any necessary post-processing steps.
      *
      * Runs all finalizer value processors in a pipeline until one returns undefined or throws an error.
-     * - The input to the pipeline is be assumed to be transformed.
+     * - The input to the pipeline is assumed to be transformed.
      * - Finalizers are generally only required for incremental schemas that need to check child values.
      * - A finalizer on the root schema (or that checks for the root path, if the root schema is shared)
      *   can act as an "entire output" finalizer.
@@ -545,7 +545,7 @@ export class CompiledSchema {
      * Finalize a transformed input value by running any necessary post-processing steps.
      *
      * Runs all finalizer value processors in a pipeline until one returns undefined or throws an error.
-     * - The input to the pipeline is be assumed to be transformed.
+     * - The input to the pipeline is assumed to be transformed.
      * - Finalizers are generally only required for incremental schemas that need to check child values.
      * - A finalizer on the root schema (or that checks for the root path, if the root schema is shared)
      *   can act as an "entire output" finalizer.

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/schema.d.ts

@@ -234,7 +234,7 @@ export class Schema {
      */
     addMetadata(metadata: object, policy?: symbol): Schema;
     /**
-     * The discriminator handler returns the key or schema of the union member that should be used
+     * The discriminator handler returns the key or schema of the union member that should be used.
      * This function appends a single value processor to the handler pipeline.
      *
      * @param {ValueProcessorSpec} spec
@@ -242,7 +242,7 @@ export class Schema {
      */
     unionDiscriminator(spec: ValueProcessorSpec): Schema;
     /**
-     * The discriminator handler returns the key or schema of the union member that should be used
+     * The discriminator handler returns the key or schema of the union member that should be used.
      * This function applies multiple value processors to the handler pipeline.
      * (Note that it would be highly unusual to want more than one!)
      *

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';