@versionzero/schema 1.0.0

package/types/helpers/deep.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @param {object} target
+ * @param {...object} sources
+ * @returns {object}
+ */
+export function deepMerge(target: object, ...sources: object[]): object;
+/**
+ * deep comparison
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean}
+ * @internal
+ */
+export function deepEquals(a: any, b: any): boolean;
+/**
+ * @param {object|undefined}target
+ * @param {string} path
+ * @param {any} value
+ * @returns {object}
+ */
+export function deepAssign(target: object | undefined, path: string, value: any): object;
+/**
+ *
+ * @param {object} object
+ * @param {string} path
+ * @returns {undefined|any}
+ */
+export function deepValue(object: object, path: string): undefined | any;
+/**
+ * @param {any} value
+ * @returns {any}
+ */
+export function deepPrune(value: any): any;

package/types/helpers/format.d.ts

@@ -0,0 +1,14 @@
+/**
+ *
+ * @param {CompiledSchema} schema
+ * @returns {string}
+ * @package
+ */
+export function formatArgumentType(schema: CompiledSchema): string;
+/**
+ * @param {any} value
+ * @param {object} [options]
+ * @returns {string}
+ */
+export function formatValue(value: any, options?: object): string;
+import { CompiledSchema } from "../compiled-schema.js";

package/types/helpers/has-string-properties.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @param {import("../types.js").ISchema} schema
+ * @returns {boolean}
+ */
+export function hasStringProperties(schema: import("../types.js").ISchema): boolean;

package/types/helpers/index.d.ts

@@ -0,0 +1,13 @@
+export { debug } from "./debug-sink.js";
+export { hasStringProperties } from "./has-string-properties.js";
+export { parseDate } from "./parse-date.js";
+export { parseRegExp } from "./regex.js";
+export { toData } from "./to-data.js";
+export { toCamelCase, toPascalCase, toConstantCase, toKebabCase, toCapitalize, toTitleCase } from "./case.js";
+export { deepMerge, deepEquals, deepAssign, deepValue, deepPrune } from "./deep.js";
+export { formatArgumentType, formatValue } from "./format.js";
+export { isPlainObject, isObject, isEmpty, isPrimitive, isConstructor, isConstructible, isNativeClass, map } from "./object.js";
+export { behead, propertyName } from "./path.js";
+export { stringify, parse } from "./stringify.js";
+export { isTruthyKeyword, isFalseyKeyword, isTruthy, isFalsey } from "./truthy.js";
+export { parseDataSize, formatDataSize } from "./data-size.js";

package/types/helpers/object.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @param {any} obj
+ * @returns {boolean}
+ */
+export function isPlainObject(obj: any): boolean;
+/**
+ * @param {any} item
+ * @returns {boolean}
+ */
+export function isObject(item: any): boolean;
+/**
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isEmpty(value: any): boolean;
+/**
+ * @param {any} item
+ * @returns {boolean}
+ */
+export function isPrimitive(item: any): boolean;
+/**
+ * @param {any} f
+ * @returns {boolean}
+ * @deprecated - usually want isConstructible instead
+ */
+export function isConstructor(f: any): boolean;
+/**
+ * @param {any} f
+ * @returns {boolean}
+ */
+export function isConstructible(f: any): boolean;
+/**
+ * Returns true for ES class syntax (`class Foo {}`) and native builtin
+ * constructors (`Map`, `Set`, `Error`, etc.) — i.e. functions that are
+ * meant to be used with `new` and should not be invoked as plain callbacks.
+ * @param {any} f
+ * @returns {boolean}
+ */
+export function isNativeClass(f: any): boolean;
+/**
+ *
+ * @param {object|any[]|any} collection
+ * @param {(value:any) => any} callback
+ * @returns {object|any[]}
+ */
+export function map(collection: object | any[] | any, callback: (value: any) => any): object | any[];

package/types/helpers/parse-date.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @package
+ * @param {string|number|Date} value
+ * @returns {Date}
+ */
+export function parseDate(value: string | number | Date): Date;

package/types/helpers/path.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Split off the first section of a path
+ *
+ * @param {string} path
+ * @returns {[string,string|undefined]}
+ */
+export function behead(path: string): [string, string | undefined];
+/**
+ * Extract the last part of the path
+ * @param {string} path
+ * @returns {string}
+ */
+export function propertyName(path: string): string;

package/types/helpers/regex.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parse delimited regexp strings
+ *
+ * @param {string|RegExp} rx
+ * @returns {RegExp|undefined}
+ */
+export function parseRegExp(rx: string | RegExp): RegExp | undefined;

package/types/helpers/stringify.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Deterministic stringifier with support for extended types and deserialization.
+ * @package
+ * @param {any} value - Value to stringify
+ * @param {object} [options] - Stringification options
+ * @param {number} [options.space] - Indentation for pretty printing (default: 0)
+ * @param {number} [options.maxDepth] - Maximum recursion depth (default: 100)
+ * @param {boolean} [options.useDelimiters] - Use <<Type>> markers for extended types (default: true)
+ * @param {string} [options.delimiterOpen] - Opening delimiter for type markers (default: '<<')
+ * @param {string} [options.delimiterClose] - Closing delimiter for type markers (default: '>>')
+ * @returns {string} Deterministic JSON string with optional type markers
+ */
+export function stringify(value: any, options?: {
+    space?: number | undefined;
+    maxDepth?: number | undefined;
+    useDelimiters?: boolean | undefined;
+    delimiterOpen?: string | undefined;
+    delimiterClose?: string | undefined;
+}): string;
+/**
+ * Parse a string created by stringify() back into an object.
+ * Handles both plain JSON and extended format with type markers.
+ * @package
+ * @param {string} text - JSON string to parse
+ * @param {object} [options] - Parse options
+ * @param {string} [options.delimiterOpen] - Opening delimiter for type markers (default '<<')
+ * @param {string} [options.delimiterClose] - Closing delimiter for type markers (default '>>')
+ * @returns {any} Parsed value with extended types and circular references restored
+ */
+export function parse(text: string, options?: {
+    delimiterOpen?: string | undefined;
+    delimiterClose?: string | undefined;
+}): any;

package/types/helpers/to-data.d.ts

@@ -0,0 +1,13 @@
+/** @import {SchemaData} from '../types.js' */
+/**
+ * Common implementation shared by both Schema and CompiledSchema
+ * (which only share a "fake" jsdoc interface to define their shape)
+ * @package
+ * @param {Schema|CompiledSchema|SchemaData} schema
+ * @param {WeakMap<object,object>} [seen] - cycle-detection map; shared across recursive calls
+ * @returns {SchemaData}
+ */
+export function toData(schema: Schema | CompiledSchema | SchemaData, seen?: WeakMap<object, object>): SchemaData;
+import { Schema } from '../schema.js';
+import { CompiledSchema } from '../compiled-schema.js';
+import type { SchemaData } from '../types.js';

package/types/helpers/truthy.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Return true if the provided value is one of the magic truthy keywords
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isTruthyKeyword(value: string): boolean;
+/**
+ * Return true if the provided value is one of the magic falsey keywords
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isFalseyKeyword(value: string): boolean;
+/**
+ * This library has a slightly extended notion of truthiness that includes human-friendly string representations
+ *
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isTruthy(value: any): boolean;
+/**
+ * This library has a slightly extended notion of truthiness that includes human-friendly string representations
+ *
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isFalsey(value: any): boolean;

package/types/index.d.ts

@@ -0,0 +1,6 @@
+export { CompiledSchema } from "./compiled-schema.js";
+export { SchemaError } from "./errors.js";
+export { SchemaResolver } from "./schema-resolver.js";
+export { SchemaLocation } from "./schema-location.js";
+export { EMPTY } from "./constants.js";
+export { Schema, SchemaPolicy } from "./schema.js";

package/types/schema-compiler.d.ts

@@ -0,0 +1,49 @@
+/** @typedef {(inputSchema:CompiledSchema|Schema, targetSchema:CompiledSchema, location:SchemaLocation, options?:object) => Promise<Schema|CompiledSchema|import("./types.js").SchemaData|undefined>} InputSchemaProcessor */
+/** @typedef {(inputSchema:CompiledSchema, targetSchema:CompiledSchema, location:SchemaLocation, options?:object) => Promise<CompiledSchema|undefined>} OutputSchemaProcessor */
+/**
+ * This is a marker class for type safety that is replaced before the schema is used.
+ */
+export class CachedSchemaReference extends CompiledSchema {
+    /**
+     * @param {Schema} schema
+     */
+    constructor(schema: Schema);
+    schema: Schema;
+}
+/**
+ * Top-level "Schema Schema" - takes a Schema as input, emits a CompiledSchema as output
+ */
+export class SchemaCompiler extends CompiledSchema {
+    /**
+     * @param {SchemaResolver} resolver
+     */
+    constructor(resolver: SchemaResolver);
+    resolver: SchemaResolver;
+    normalizeCache: Map<any, any>;
+    compileSeen: Map<any, any>;
+    compileCache: Map<any, any>;
+    /**
+     *
+     * @param {CompiledSchema} cs
+     * @param {string} [path]
+     * @param {Set<CompiledSchema>} [seen]
+     * @private
+     */
+    private _replaceCachedReferences;
+    /**
+     * Compile a Schema to a CompiledSchema
+     *
+     * Schemas are compiled using a schema that defines schemas!  This method is a convenience facade over the regular
+     * "process" flow.
+     *
+     * @param {Schema|CompiledSchema|import("./types.js").SchemaData} inputSchema
+     * @returns {CompiledSchema}
+     */
+    compile(inputSchema: Schema | CompiledSchema | import("./types.js").SchemaData): CompiledSchema;
+}
+export type InputSchemaProcessor = (inputSchema: CompiledSchema | Schema, targetSchema: CompiledSchema, location: SchemaLocation, options?: object) => Promise<Schema | CompiledSchema | import("./types.js").SchemaData | undefined>;
+export type OutputSchemaProcessor = (inputSchema: CompiledSchema, targetSchema: CompiledSchema, location: SchemaLocation, options?: object) => Promise<CompiledSchema | undefined>;
+import { CompiledSchema } from './compiled-schema.js';
+import { Schema } from './schema.js';
+import { SchemaResolver } from './schema-resolver.js';
+import { SchemaLocation } from "./schema-location.js";

package/types/schema-location.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The SchemaLocation tracks the schema and parent/child relationships for a given traversal path.
+ *
+ * Schemas can be linked into a hierarchy in multiple positions, so they have no static "parent".
+ * However, traversal builds an implicit hierarchy of locations that each then refer to a schema (if known),
+ * enabling access to any schema within the location hierarchy, including the parent.
+ *
+ * The current location is passed to value processors, effectively acting as a sort of "cursor".
+ */
+export class SchemaLocation {
+    /**
+     * @param {CompiledSchema} schema
+     * @param {SchemaLocation} [parent]
+     * @param {string} [propertyName]
+     */
+    constructor(schema: CompiledSchema, parent?: SchemaLocation, propertyName?: string);
+    /** @type {string} */
+    get path(): string;
+    toString(): string;
+    /** @type {string} */
+    get name(): string;
+    set schema(schema: CompiledSchema);
+    /** @type {CompiledSchema} */
+    get schema(): CompiledSchema;
+    /** @type {SchemaLocation|undefined} */
+    get parent(): SchemaLocation | undefined;
+    /** @type {SchemaLocation} */
+    get root(): SchemaLocation;
+    /**
+     * Return the location of the path relative to the current location.
+     *
+     * @param {string} path
+     * @returns {SchemaLocation|undefined}
+     */
+    relative(path: string): SchemaLocation | undefined;
+    /**
+     * Return the location of the path relative to the root of the known location hierarchy.
+     *
+     * @param {string} path
+     * @returns {SchemaLocation|undefined}
+     */
+    absolute(path: string): SchemaLocation | undefined;
+    /**
+     * Return the location of a sibling with the relative path.
+     *
+     * @param {string} path
+     * @returns {SchemaLocation|undefined}
+     */
+    sibling(path: string): SchemaLocation | undefined;
+    /**
+     * Return a temporary location corresponding to one of our not-yet-resolved union members.
+     *
+     * @param {CompiledSchema} unionSchema
+     * @returns {undefined|SchemaLocation}
+     */
+    union(unionSchema: CompiledSchema): undefined | SchemaLocation;
+    /**
+     * @param {(location:SchemaLocation) => any} predicate
+     * @returns {SchemaLocation|undefined}
+     */
+    findPropertyLocation(predicate: (location: SchemaLocation) => any): SchemaLocation | undefined;
+    #private;
+}
+import { CompiledSchema } from './compiled-schema.js';

package/types/schema-resolver.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 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: (resolver: SchemaResolver, options: object) => void): void;
+/** @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 {
+    /**
+     * add a schema to the registry
+     * @param {string} name
+     * @param {Schema} schema
+     * @returns {SchemaResolver}
+     */
+    registerSchema(name: string, schema: Schema): SchemaResolver;
+    /**
+     * return the registered schema with a given name
+     * @param {string} name
+     * @returns {Schema}
+     */
+    getSchema(name: string): Schema;
+    /**
+     * return true if there exists a registered schema with a given name
+     * @param {string} name
+     * @returns {boolean}
+     */
+    hasSchema(name: string): boolean;
+    /**
+     * Register a value processor definition
+     * @param {ValueProcessorDefinition} definition
+     * @returns {SchemaResolver}
+     */
+    registerValueProcessorDefinition(definition: ValueProcessorDefinition): SchemaResolver;
+    /**
+     * register a named "simple" ValueProcessor
+     * @param {string} keyword
+     * @param {ValueProcessorFunction} process
+     * @param {string} [description]
+     * @returns {SchemaResolver}
+     */
+    registerValueProcessor(keyword: string, process: ValueProcessorFunction, description?: string): SchemaResolver;
+    /**
+     * register a complex ValueProcessor that needs to be built based on schema processor spec
+     * @param {string} keyword
+     * @param {ValueProcessorBuilder} build
+     * @returns {SchemaResolver}
+     */
+    registerValueProcessorBuilder(keyword: string, build: ValueProcessorBuilder): SchemaResolver;
+    /**
+     * 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>}
+     */
+    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
+     * @param {boolean} [recursive]
+     * @returns {ValueProcessor}
+     */
+    compileKeywordValueProcessorSpec(compiler: SchemaCompiler, spec: KeywordValueProcessorSpec, recursive?: boolean): ValueProcessor;
+    compileSchemaValueProcessorSpec(compiler: any, spec: any): ComposedValueProcessor;
+    /**
+     * Convert a processor specification into an executor
+     * @param {SchemaCompiler} compiler
+     * @param {ValueProcessorSpec} spec - The processor specification
+     * @param {boolean} [recursive]
+     * @returns {ValueProcessor}
+     */
+    compileValueProcessorSpecObject(compiler: SchemaCompiler, spec: ValueProcessorSpec, recursive?: boolean): ValueProcessor;
+    /**
+     * Convert a processor specification into an executor
+     * @param {SchemaCompiler} compiler
+     * @param {ValueProcessorSpec} spec - The processor specification
+     * @param {boolean} [recursive]
+     * @returns {ValueProcessor}
+     */
+    compileValueProcessorSpecArray(compiler: SchemaCompiler, spec: ValueProcessorSpec, recursive?: boolean): ValueProcessor;
+    /**
+     * 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: SchemaCompiler, spec: ValueProcessorSpec, recursive?: boolean): ValueProcessor;
+    compiler(): SchemaCompiler;
+    /**
+     * Build a compiled schema from the schema definition.
+     * @param {Schema|CompiledSchema|SchemaData} inputSchema
+     * @returns {CompiledSchema}
+     */
+    compile(inputSchema: Schema | CompiledSchema | SchemaData): CompiledSchema;
+    /**
+     * 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: Schema | CompiledSchema | SchemaData | string, recursive?: boolean): Schema | CompiledSchema;
+    #private;
+}
+export type SchemaResolverLibraryOptions = {
+    name: string;
+    [key: string]: any;
+};
+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';
+import { ComposedValueProcessor } from './value-processor/composed-value-processor.js';
+import type { ValueProcessorSpec } from './value-processor/value-processor.js';
+import { CompiledSchema } from './compiled-schema.js';
+import type { SchemaData } from './types.js';