@versionzero/schema 1.0.0

package/types/compiled-schema.d.ts

@@ -0,0 +1,883 @@
+/** @import { TraversalContextOptions } from './traversal/traversal-context.js' */
+/** @import { ISchema, ISchemaOptions, ISchemaMetadata, SchemaData } from './types.js' */
+/** @typedef {ISchemaMetadata} CompiledSchemaMetadata */
+/** @typedef {ISchemaOptions} CompiledSchemaOptions */
+/**
+ * @typedef {object} CompiledSchemaHandlers
+ * @property {Array<ValueProcessor>} [normalizers]
+ * @property {Array<ValueProcessor>} [conditions]
+ * @property {Array<ValueProcessor>} [transformers]
+ * @property {Array<ValueProcessor>} [finalizers]
+ * @property {Array<ValueProcessor>} [validators]
+ * @property {Array<ValueProcessor>} [serializers]
+ * @property {Array<ValueProcessor>} [discriminators]
+ */
+/** @typedef {{[key:string]:CompiledSchema}} CompiledSchemaProperties */
+/** @typedef {{[key:string]:CompiledSchema}} CompiledSchemaUnionSchemas */
+/**
+ * @typedef {object} SharedOptions
+ * @property {SchemaLocation} [location]
+ * @property {TraversalContext|TraversalContextOptions} [context]
+ */
+/** @typedef {SharedOptions & {[key:string]: any}} ValidateOptions */
+/** @typedef {SharedOptions & {[key:string]: any}} SerializeOptions */
+/** @typedef {SharedOptions & {assignments?:Map<string,any>} & {[key:string]: any}} ProcessOptions */
+/** @typedef {SharedOptions & {[key:string]: any}} ProcessAssignmentsOptions */
+/**
+ * CompiledSchema - the resolved version of a schema usable for processing input values into output values
+ *
+ * The SchemaResolver compiler takes an input Schema and constructs a CompiledSchema:
+ * - The base schema hierarchy is resolved and flattened.
+ * - Handlers have their input specifications converted into value processor executors.
+ * - Unions may trigger property hoisting and discriminator synthesis.
+ * - Core options are converted to standardized forms.
+ * - Metadata is expanded by introspecting the resolved schema.
+ * - Errors are thrown if the input Schema is invalid, inconsistent, or missing required data.
+ *
+ * @augments {ISchema}
+ */
+export class CompiledSchema {
+    /** @internal */
+    static __TOKEN: symbol;
+    /**
+     * CompiledSchema constructor - do not call directly (use SchemaResolver.compile())
+     *
+     * @param {symbol} token - magic to reduce shenanigans
+     */
+    constructor(token: symbol);
+    /**
+     * Options contains information that changes schema parsing and processing.
+     *
+     * @type {CompiledSchemaOptions}
+     */
+    get options(): CompiledSchemaOptions;
+    /**
+     * Metadata contains information for describing the schema behavior to users and hints for tools.
+     *
+     * @type {CompiledSchemaMetadata}
+     */
+    get metadata(): CompiledSchemaMetadata;
+    /**
+     * Properties are named child schemas, defining a hierarchical schema structure.
+     *
+     * This is an (inefficient) cache for compatibility with the ISchema "interface".
+     *
+     * @type {CompiledSchemaProperties}
+     */
+    get properties(): CompiledSchemaProperties;
+    /**
+     *
+     * @type {IteratorObject<[string, CompiledSchema]>}
+     */
+    get propertyEntries(): IteratorObject<[string, CompiledSchema]>;
+    /**
+     * Handlers are associated with asynchronous value processors.
+     *
+     * The "friendly" handler definitions from the source Schema are each compiled into asynchronous functions
+     * that run as a pipeline.
+     *
+     * All handlers have the same async 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
+     *
+     * The compiled handlers may vary in their return types and exception handling behavior.
+     *
+     * @type {CompiledSchemaHandlers}
+     */
+    get handlers(): CompiledSchemaHandlers;
+    /**
+     * Get a value processor by handler name
+     *
+     * Handler definitions are compiled into a single value processor pipeline per handler name.
+     *
+     * @param {string} handlerName
+     * @returns {ValueProcessor|undefined}
+     * @internal
+     */
+    getValueProcessor(handlerName: string): ValueProcessor | undefined;
+    /**
+     *
+     * @param {string} handlerName
+     * @param {ValueProcessor} valueProcessor
+     * @returns {ValueProcessor}
+     * @internal
+     */
+    _setValueProcessor(handlerName: string, valueProcessor: ValueProcessor): ValueProcessor;
+    /**
+     * If this schema defines a union, return the schema member elements of the union.
+     *
+     * Unions use a discriminator handler to attempt to resolve to one of the unionSchema member elements
+     * based on either the value being processed or the overall aggregated data.  The key of the
+     * unionSchema in this collection is sometimes used as part of this process.
+     *
+     * Once the discriminator succeeds, the active schema switches to the resolved unionSchema.
+     *
+     * @type {CompiledSchemaUnionSchemas}
+     */
+    get unionSchemas(): CompiledSchemaUnionSchemas;
+    /**
+     *
+     * @type {IteratorObject<[string, CompiledSchema]>}
+     */
+    get unionSchemaEntries(): IteratorObject<[string, CompiledSchema]>;
+    /**
+     * Extract this schema as a raw data object usable for cloning this schema.
+     *
+     * Note that the data may include handler functions, so it cannot be assumed to be serializable to JSON!
+     *
+     * @returns {SchemaData|undefined}
+     */
+    toData(): SchemaData | undefined;
+    /**
+     * Return true if this schema has any child schemas.
+     *
+     * @type {boolean}
+     */
+    get hasChildren(): boolean;
+    /**
+     * Return true if this schema should be treated as a container.
+     *
+     * Any schema that has children is a container, but also those explicitly marked as a container.
+     *
+     * @returns {boolean}
+     */
+    get isContainer(): boolean;
+    /**
+     * Return true if this schema supports wildcard properties.
+     *
+     * @type {boolean}
+     */
+    get hasWildcard(): boolean;
+    /**
+     * Return true if this schema defines an array.
+     *
+     * Arrays sometimes need special treatment; the built-in 'array' base schema sets this option.
+     *
+     * @type {boolean}
+     */
+    get isArray(): boolean;
+    /**
+     * Return true if this schema defines a function value.
+     *
+     * Functions passed to most operations are interpreted as dynamic values (called to retrieve actual value).
+     * This setting overrides that behavior, and forces a passed function to be treated as a simple value.
+     *
+     * @type {boolean}
+     */
+    get isFunction(): boolean;
+    /**
+     * Return true if this schema defines a union.
+     * Unions adopt the behavior of one of their unionSchema member elements based on a discriminator handler function.
+     *
+     * @type {boolean}
+     */
+    get isUnion(): boolean;
+    /**
+     * Return true if this schema is used to select union keys.
+     *
+     * (This doesn't guarantee that there is a matching discriminator on the parent that uses it!)
+     * todo - convert this option into a generated normalizer that enforces union key values at runtime?
+     *
+     * @type {boolean}
+     */
+    get isUnionKey(): boolean;
+    /**
+     * Return true if the schema acts as a selector.
+     *
+     * Selectors control the activation or deactivation of peer selection schemas using a conditional handler
+     * synthesized during compilation.
+     *
+     * @type {boolean}
+     */
+    get isSelector(): boolean;
+    /**
+     * Return true if this schema contains a selector as a child.
+     * @type {boolean}
+     */
+    get hasChildSelector(): boolean;
+    /**
+     * Return true if this schema is a selection conditionally activated by a peer selector.
+     *
+     * @type {boolean}
+     */
+    get isSelection(): boolean;
+    /**
+     * Return true if this schema contains a selection as a child.
+     * @type {boolean}
+     */
+    get hasChildSelection(): boolean;
+    /**
+     * Get the selector value that triggers this selection.  The default value for a selection is its own property name.
+     *
+     * @type {string|boolean|undefined}
+     */
+    get selection(): string | boolean | undefined;
+    /**
+     * Return the legal (normalized) values this schema accepts, if defined.
+     *
+     * (This acts as an "upstream" check before calling any transform handlers.)
+     *
+     * @type {Array<NonNullable<any>>|undefined}
+     */
+    get values(): Array<NonNullable<any>> | undefined;
+    /**
+     * Returns true if this schema defines any values it accepts.
+     *
+     * @type {boolean}
+     */
+    get hasValues(): boolean;
+    /**
+     * Returns whether this schema enforces strict/lax checking.
+     *
+     * - returns true if the schema uses strict checking
+     * - returns false if the schema uses lax checking
+     * - if undefined, it depends on the traversal context and the behavior of individual processors
+     *
+     * This setting is useful for preventing validation errors when transforms return new objects
+     * that contain extra properties that don't match the schema.
+     *
+     * In most contexts (e.g. assignment processing and validation) strict processing is the default.
+     * Setting lax mode changes several behaviors:
+     * - If a union is marked lax, it is not an error to fail to resolve the union
+     * - If a leaf schema is marked lax, it is not an error if a value fails to assign to it
+     *
+     * Lax mode does *not* mean that errors during normalization
+     *
+     * @type {boolean|undefined}
+     */
+    get strict(): boolean | undefined;
+    /**
+     * Returns true if the value defined by this schema is required to exist in the output to be valid.
+     *
+     * Under the normal pathways, this is a shallow requirement:
+     * - Each schema checks its own input; if the required flag is set, the input must not be undefined.
+     * - If the input value is defined and the schema defines child properties, the input will be traversed
+     *   and recursively checked against the child property schemas.
+     * - If the input value is undefined, child property schemas are NOT checked.
+     *
+     * If the "deep" flag is set on the schema, this behavior changes:
+     * - If the input value is undefined on a schema with "deep" set, child properties ARE checked.
+     *
+     * If a schema sets a default value, it will generally satisfy the required setting (unless set to a
+     * value function that returns undefined!)
+     *
+     * @type {boolean}
+     */
+    get required(): boolean;
+    /**
+     * Returns the default value this schema provides if the input is undefined.
+     *
+     * This is normally interpreted as a "shallow" default;
+     * - If the schema being actively processed has a default value and the input value is undefined, the default is used.
+     * - If the schema being actively processed defines child properties, and is passed an input value that does not
+     *   contain a value for a specific child that defines a default, the child's default will be used.
+     * - If the schema being actively processed defines child properties, but is passed an undefined input value,
+     *   the child property schemas will not be traversed, and thus any child defaults will not take effect.
+     *
+     * This last behavior changes if the "deep" schema option is set:
+     * - If the schema being actively processed defines child properties is passed an undefined input value when
+     *   the "deep" option is enabled, child property schemas will be traversed and any defaults will be used.
+     *
+     * The default may also be set to a value function:
+     * `async (value: any, target: any, location:SchemaLocation, options: Object): any`
+     * that will be called during the normalization phase.  This can be useful for late binding, remote lookups,
+     * side effects, or lazy evaluation of expensive values.
+     *
+     * @type {any|undefined}
+     */
+    get default(): any | undefined;
+    /**
+     * Returns whether this schema should be deeply traversed even when the input is empty.
+     *
+     * This is useful for triggering required/defaults settings.  (Note that a schema with
+     * child properties that is marked required is deep by default, because that's almost
+     * always what is wanted/expected.)
+     *
+     * Returns undefined if unset, signaling that the traversal context will decide.
+     *
+     * @type {boolean|undefined}
+     */
+    get deep(): boolean | undefined;
+    /**
+     * Return true if the schema always returns an inherited or referenced value.
+     *
+     * Referenced properties never accept a direct assignment, and will always return the value
+     * corresponding to the first matching property name found higher in the schema.
+     *
+     * @type {boolean}
+     */
+    get isReference(): boolean;
+    /**
+     * Returns true if this schema defines a value that can be assumed to always exist and be valid.
+     *
+     * The implicit setting implies that values passed to this schema should not be visited or validated.
+     *
+     * @type {boolean}
+     */
+    get isImplicit(): boolean;
+    /**
+     * Returns true if the container allows incremental assignment to children.
+     * Deprecated - use "opaque" as a more accurate signal of intent.
+     *
+     * @type {boolean}
+     * @deprecated
+     */
+    get allowIncremental(): boolean;
+    /**
+     * Returns true if the schema defines a value whose internals are hidden after transformation.
+     *
+     * Opaque schemas will typically need a custom validator that understands the post-transform contract.
+     *
+     * Transformation of opaque schemas is delayed until all known child assignments have been staged into a
+     * pending container.  Once an opaque schema is transformed, it no longer accepts assignments.  (This
+     * may cause sequencing issues with late-resolved conditional assignments!)
+     *
+     * @type {boolean}
+     */
+    get isOpaque(): boolean;
+    /**
+     * Check if the provided value (and/or current output target) passes the schema conditional check.
+     *
+     * Schemas that don't have a condition handler defined will always succeed.
+     *
+     * Failed conditions will be repeatedly re-checked during assignment processing until the final pass.
+     * Errors encountered while checking conditions are caught and simply result in a failed condition.
+     *
+     * (This is an executor function that may return synchronous or asynchronous results.)
+     *
+     * @param {any} value
+     * @param {any} [target]
+     * @param {SchemaLocation} [location]
+     * @param {object} [options]
+     * @returns {boolean|Promise<boolean>}
+     * @internal
+     */
+    _checkCondition(value: any, target?: any, location?: SchemaLocation, options?: object): boolean | Promise<boolean>;
+    /**
+     * Check if the provided value (and/or current output target) passes the schema conditional check.
+     *
+     * Failed conditions will be repeatedly re-checked during assignment processing until the final pass.
+     * Errors encountered while checking conditions are caught and simply result in a failed condition.
+     *
+     * (This an async wrapper around the internal `_checkCondition` executor function.)
+     *
+     * @param {any} value
+     * @param {any} [target]
+     * @param {SchemaLocation} [location]
+     * @param {object} [options]
+     * @returns {Promise<boolean>}
+     * @internal
+     */
+    checkCondition(value: any, target?: any, location?: SchemaLocation, options?: object): Promise<boolean>;
+    /**
+     * Return true if this schema is conditional
+     *
+     * @returns {boolean}
+     */
+    get hasConditions(): boolean;
+    /**
+     * Return true if this schema requires finalization
+     *
+     * @returns {boolean}
+     */
+    get requiresFinalization(): boolean;
+    _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.
+     *
+     * (This is an executor function that may return synchronous or asynchronous results.)
+     *
+     * @param {any} value
+     * @param {any} [target]
+     * @param {SchemaLocation} [location]
+     * @param {object} [options]
+     * @returns {CompiledSchema|undefined|Promise<CompiledSchema|undefined>}
+     * @internal
+     */
+    _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.
+     *
+     * (This an async wrapper around the internal `_discriminateUnion` executor function.)
+     *
+     * @param {any} value
+     * @param {any} [target]
+     * @param {SchemaLocation} [location]
+     * @param {object} [options]
+     * @returns {Promise<CompiledSchema|undefined>}
+     * @internal
+     */
+    discriminateUnion(value: any, target?: any, location?: SchemaLocation, options?: object): Promise<CompiledSchema | undefined>;
+    /**
+     * Ensure the input is of an expected shape that can be handled by this schema.
+     *
+     * Runs all normalizer value processors in a pipeline until completion or an error is thrown.
+     * As external data may originate in the form of strings or JSON structures, the main task of
+     * a normalizer is to "canonicalize" these inputs:
+     * - The normalized output should be accepted by the transformer handler.
+     * - Normalizers should usually pass through valid transformed values unchanged.
+     * - By contract, when passed "true", a container schema should construct an "empty"
+     *   container (e.g. {} or []).  (Even a schema that defines transformation to a
+     *   complex class should have a normalized empty container format to use for construction).
+     *
+     * The normalize process will throw an exception if the input is incompatible.
+     *
+     * Unlike other handlers, normalizers should generally not depend on the overall
+     * target state, as they are sometimes invoked in isolation (even during compilation!)
+     * and thus shouldn't assume the "undefined means retry later" behavior of other handlers.
+     *
+     * Also note that normalizeValue does not recursively examine child properties.
+     *
+     * (This is an executor function that may return synchronous or asynchronous results.)
+     *
+     * @param {any} value - value to normalize
+     * @param {any} [target] - top level output target being built (avoid using for normalizers!)
+     * @param {SchemaLocation} [location] - path to this value in the output target
+     * @param {object} [options] - optional tweaks to normalizer behavior
+     * @returns {any|Promise<any>}
+     * @internal
+     */
+    _normalizeValue(value: any, target?: any, location?: SchemaLocation, options?: object): any | Promise<any>;
+    /**
+     * Ensure the input is of an expected shape that can be handled by this schema.
+     *
+     * Runs all normalizer value processors in a pipeline until completion or an error is thrown.
+     * As many external input values will originate in the form of strings or JSON
+     * structures, the main task of a normalizer is to "canonicalize" these inputs:
+     * - The normalized output should be accepted by the transformer handler.
+     * - Normalizers should usually pass through valid transformed values unchanged.
+     * - By contract, when passed "true", a container schema should construct an "empty"
+     *   container (e.g. {} or []).  (Even a schema that defines transformation to a
+     *   complex class should have a normalized empty container format to use for construction).
+     *
+     * The normalize process will throw an exception if the input is incompatible.
+     *
+     * Unlike other handlers, normalizers should generally not depend on the overall
+     * target state, as they are sometimes invoked in isolation (even during compilation!)
+     * and thus shouldn't assume the "undefined means retry later" behavior of other handlers.
+     *
+     * Also note that normalizeValue does not recursively examine child properties.
+     *
+     * (This an async wrapper around the internal `_normalizeValue` executor function.)
+     *
+     * @param {any} value - value to normalize
+     * @param {any} [target] - top level output target being built (avoid using for normalizers!)
+     * @param {SchemaLocation} [location] - path to this value in the output target
+     * @param {object} [options] - optional tweaks to normalizer behavior
+     * @returns {Promise<any>}
+     * @internal
+     */
+    normalizeValue(value: any, target?: any, location?: SchemaLocation, options?: object): Promise<any>;
+    /**
+     * Transform a normalized input value for the final target based on this schema and provided context.
+     *
+     * Runs all transformer value processors in a pipeline until one returns undefined or throws an error.
+     * - The input to the pipeline is assumed to be normalized.
+     * - An error may be thrown if the input cannot be transformed.
+     * - If a transformer depends upon the overall target, it may return undefined to signal
+     *   that the transform should be retried when the target is updated.
+     *
+     * A schema's transform is allowed to enforce validation internally, or it can delegate this to
+     * a finalizer or validator.  In any case, the output from the transform is not guaranteed to be valid.
+     * (Note that conditions and unions are not checked if you call this directly.)
+     *
+     * Child properties are not traversed in this call, and are presumed to already have been transformed.
+     *
+     * (This is an executor function that may return synchronous or asynchronous results.)
+     *
+     * @param {any} value - input value to transform
+     * @param {any} [target] - global target in case the transformer depends on it
+     * @param {SchemaLocation} [location] - the traversal location of the schema
+     * @param {object} [options] - any tweaks to the transformer behavior
+     * @returns {any|Promise<any>} - transformed value
+     * @internal
+     */
+    _transformValue(value: any, target?: any, location?: SchemaLocation, options?: object): any | Promise<any>;
+    /**
+     * Transform a normalized input value for the final target based on this schema and provided context.
+     *
+     * Runs all transformer value processors in a pipeline until one returns undefined or throws an error.
+     * - The input to the pipeline is assumed to be normalized.
+     * - An error may be thrown if the input cannot be transformed.
+     * - If a transformer depends upon the overall target, it may return undefined to signal
+     *   that the transform should be retried when the target is updated.
+     *
+     * A schema's transform is allowed to enforce validation internally, or it can delegate this to
+     * a finalizer or validator.  In any case, the output from the transform is not guaranteed to be valid.
+     * (Note that conditions and unions are not checked if you call this directly.)
+     *
+     * Child properties are not traversed in this call, and are presumed to already have been transformed.
+     *
+     * (This an async wrapper around the internal `_transformValue` executor function.)
+     *
+     * @param {any} value - input value to transform
+     * @param {any} [target] - global target in case the transformer depends on it
+     * @param {SchemaLocation} [location] - the traversal location of the schema
+     * @param {object} [options] - any tweaks to the transformer behavior
+     * @returns {Promise<any>} - transformed value
+     * @internal
+     */
+    transformValue(value: any, target?: any, location?: SchemaLocation, options?: object): Promise<any>;
+    /**
+     * 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.
+     * - 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.
+     *
+     * (This is an executor function that may return synchronous or asynchronous results.)
+     *
+     * @param {any} value - input value to finalize
+     * @param {any} [target] - global target in case the finalizer depends on it
+     * @param {SchemaLocation} [location] - the traversal location of the schema
+     * @param {object} [options] - any tweaks to the finalizer behavior
+     * @returns {any|Promise<any>} - finalized value
+     * @internal
+     */
+    _finalizeValue(value: any, target?: any, location?: SchemaLocation, options?: object): any | Promise<any>;
+    /**
+     * 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.
+     * - 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.
+     *
+     * (This an async wrapper around the internal `_finalizeValue` executor function.)
+     *
+     * @param {any} value - input value to transform
+     * @param {any} [target] - global target in case the transformer depends on it
+     * @param {SchemaLocation} [location] - the traversal location of the schema
+     * @param {object} [options] - any tweaks to the transformer behavior
+     * @returns {Promise<any>} - transformed value
+     * @internal
+     */
+    finalizeValue(value: any, target?: any, location?: SchemaLocation, options?: object): Promise<any>;
+    /**
+     * Validate the provided input value.
+     *
+     * Runs all validator value processors in a pipeline until one throws an error.
+     * Validators can return a different value from the input (presumably "more valid",
+     * e.g. strings trimmed, case made consistent, etc.) but must throw if the input is invalid.
+     *
+     * Children are not traversed in this call.
+     *
+     * (This is an executor function that may return synchronous or asynchronous results.)
+     *
+     * @param {any} value - value to validate
+     * @param {any} [target] - complete output target
+     * @param {SchemaLocation} [location] - traversal location of this schema
+     * @param {object} [options] - options to tweak validation behavior
+     * @returns {any|Promise<any>}
+     * @internal
+     */
+    _validateValue(value: any, target?: any, location?: SchemaLocation, options?: object): any | Promise<any>;
+    /**
+     * Validate the provided input value.
+     *
+     * Runs all validator value processors in a pipeline until one throws an error.
+     * Validators can return a different value from the input (presumably "more valid",
+     * e.g. strings trimmed, case made consistent, etc.) but must throw if the input is invalid.
+     *
+     * Children are not traversed in this call.
+     *
+     * @param {any} value - value to validate
+     * @param {any} [target] - complete output target
+     * @param {SchemaLocation} [location] - traversal location of this schema
+     * @param {object} [options] - options to tweak validation behavior
+     * @returns {Promise<any>}
+     * @internal
+     */
+    validateValue(value: any, target?: any, location?: SchemaLocation, options?: object): Promise<any>;
+    /**
+     * Serialize the provided input value.
+     *
+     * (This is an executor function that may return synchronous or asynchronous results.)
+     *
+     * @param {any} value - value to serialize
+     * @param {any} [target] - entire output being serialized
+     * @param {SchemaLocation} [location] - traversal location to current schema
+     * @param {object} [options] - options to tweak serialization behavior
+     * @returns {any|Promise<any>}
+     * @internal
+     */
+    _serializeValue(value: any, target?: any, location?: SchemaLocation, options?: object): any | Promise<any>;
+    /**
+     * Serialize the provided input value.
+     *
+     * @param {any} value - value to serialize
+     * @param {any} [target] - entire output being serialized
+     * @param {SchemaLocation} [location] - traversal location to current schema
+     * @param {object} [options] - options to tweak serialization behavior
+     * @returns {Promise<any>}
+     * @internal
+     */
+    serializeValue(value: any, target?: any, location?: SchemaLocation, options?: object): Promise<any>;
+    /**
+     * Throw an exception if this schema seems able to handle a given input value.
+     *
+     * @param {any} value
+     */
+    ensureAccepts(value: any): void;
+    /**
+     * @param {any} value
+     * @returns {boolean}
+     */
+    checkAccepts(value: any): boolean;
+    /**
+     * Return a validated output if and only if the input fully matches the schema definition.
+     *
+     * Note: depending on the processors used for validation, the input value may be mutated during validation!
+     * (todo - create an option that prevents this from happening?)
+     *
+     * @param {any} value - input value to validate
+     * @param {ValidateOptions} [options] - any tweaks to the validator behavior
+     * @returns {any|Promise<any>} - validated value
+     * @internal
+     */
+    _validate(value: any, options?: ValidateOptions): any | Promise<any>;
+    /**
+     * Return a validated output if and only if the input fully matches the schema definition.
+     *
+     * Note: depending on the processors used for validation, the input value may be mutated during validation!
+     * (todo - create an option that prevents this from happening?)
+     *
+     * @param {any} value - input value to validate
+     * @param {ValidateOptions} [options] - any tweaks to the validator behavior
+     * @returns {Promise<any>} - validated value
+     */
+    validate(value: any, options?: ValidateOptions): Promise<any>;
+    /**
+     * Process an input value to an output value based on this schema.
+     *
+     * Errors are thrown if:
+     * - the input value doesn't match the schema
+     * - a value processor throws an error
+     * - a value cannot be processed (value processors return undefined) after repeated attempts
+     * - a union cannot be resolved
+     *
+     * If an output target is provided, it is assumed to already be valid.
+     * A few traversal options are supported; pass in a TraversalContext instance for full customization.
+     *
+     * (This is an executor function that may return synchronous or asynchronous results.)
+     *
+     * @param {any} input - the value to process
+     * @param {any} [target] - preexisting output value to build upon, if any
+     * @param {ProcessOptions} [options] - options to customize the traversal
+     * @returns {any|Promise<any>} - returns the output value
+     * @internal
+     */
+    _process(input: any, target?: any, options?: ProcessOptions): any | Promise<any>;
+    /**
+     * Process an input value to an output value based on this schema.
+     *
+     * Errors are thrown if:
+     * - the input value doesn't match the schema
+     * - a value processor throws an error
+     * - a value cannot be processed (value processors return undefined) after repeated attempts
+     * - a union cannot be resolved
+     *
+     * If an output target is provided, it is assumed to already be valid.
+     * A few traversal options are supported; pass in a TraversalContext instance for full customization.
+     *
+     * (This is an async wrapper around the internal `_process` executor function.)
+     *
+     * Note: this method makes `CompiledSchema` look somewhat like a `FunctionValueProcessor`, but it has a
+     * slightly different signature.
+     *
+     * @param {any} input - the value to process
+     * @param {any} [target] - preexisting output value to build upon, if any
+     * @param {ProcessOptions} [options] - options to customize the traversal
+     * @returns {Promise<any>} - returns the output value
+     */
+    process(input: any, target?: any, options?: ProcessOptions): Promise<any>;
+    /**
+     * Process input path/value assignments into an output value based on the schema.
+     *
+     * Paths are dotted references into the schema hierarchy.  Assignment values are normalized, transformed,
+     * validated, and then used to build the output value.
+     *
+     * If a value for the output target is provided, it is assumed to already be valid.
+     *
+     * Errors are thrown if:
+     * - unexpected paths are provided that don't match the schema
+     * - a value is incompatible with the schema referenced by the path
+     * - a value processor throws an error
+     * - a value cannot be processed (value processors return undefined) after repeated attempts
+     * - a union cannot be resolved
+     *
+     * (This an async convenience wrapper around the internal `_process` executor function.)
+     *
+     * @param {Map<string,any>} assignments - path/value associations
+     * @param {any} [target] - preexisting output value to build upon, if any
+     * @param {ProcessAssignmentsOptions} [options] - options to customize the traversal
+     * @returns {Promise<any>} - returns the output value
+     */
+    processAssignments(assignments: Map<string, any>, target?: any, options?: ProcessAssignmentsOptions): Promise<any>;
+    /**
+     * Serialize the config data as if you were going to use the result for a config file.
+     *
+     * Runs all serialization processors in a pipeline.  By default, if any processor returns undefined or throws an error,
+     * serialization of that value returns undefined and will be omitted from the output.  If you set the "strict"
+     * option, errors are re-thrown.
+     *
+     * Serializers attempt to convert resolved values back to an input-friendly value, first via the "serialize"
+     * schema option, or alternatively by trusting that each value is either already compatible, or implements toJSON().
+     *
+     * @param {any} value
+     * @param {SerializeOptions} [options]
+     * @returns {Promise<NonNullable<any>>}
+     */
+    serialize(value: any, options?: SerializeOptions): Promise<NonNullable<any>>;
+    /**
+     * Given a reference to a union schema member, return the matching key, or undefined if it cannot be found.
+     *
+     * @param {CompiledSchema} unionSchema
+     * @returns {string|undefined}
+     */
+    findUnionKey(unionSchema: CompiledSchema): string | undefined;
+    /**
+     * Given a union key or schema, retrieve the matching union schema, or undefined if it cannot be found or is invalid
+     *
+     * @param {string|CompiledSchema} lookup
+     * @returns {CompiledSchema|undefined}
+     */
+    getUnionSchema(lookup: string | CompiledSchema): CompiledSchema | undefined;
+    /**
+     * @param {string} key
+     * @param {CompiledSchema} unionSchema
+     * @returns {CompiledSchema}
+     * @internal
+     */
+    _setUnionSchema(key: string, unionSchema: CompiledSchema): CompiledSchema;
+    /**
+     * Find the schema at a given path, falling back to the wildcard schema if one exists.
+     *
+     * The root schema may be found at '', the empty string.  Array members are referenced with dotted integer indexes.
+     * Note that find() does not check union members; use SchemaLocation for finding schemas resolved during traversal.
+     *
+     * @param {string} path
+     * @returns {undefined|CompiledSchema}
+     */
+    find(path: string): undefined | CompiledSchema;
+    /**
+     * toAssignments - attempt to convert input data to a map of assignments.
+     *
+     * @param {any} object - input
+     * @param {string} prefix - prefix to add to any path generated
+     * @returns {Map<string, any>} - output map of path-to-value associations
+     */
+    toAssignments(object: any, prefix?: string): Map<string, any>;
+    /**
+     * Invoke a provided visitor function on every schema node; if visitor returns false (explicitly), abort early.
+     *
+     * @param {(schema:CompiledSchema, path:string) => any} visitor - visitor function
+     * @param {{onlySerializable?:boolean}} [options]
+     * @returns {boolean} - returns true if visitors all returned true, false if any exited early
+     */
+    visitSchema(visitor: (schema: CompiledSchema, path: string) => any, options?: {
+        onlySerializable?: boolean;
+    }): boolean;
+    /**
+     * Compute all possible schema paths (including union schema properties)
+     *
+     * @returns {Set<string>}
+     */
+    getPropertyPaths(): Set<string>;
+    /**
+     * Return a named property schema (possibly via wildcard)
+     *
+     * @param {string} propertyName
+     * @returns {CompiledSchema|undefined}
+     */
+    getPropertySchema(propertyName: string): CompiledSchema | undefined;
+    /**
+     * Associate a schema with a property name.  Only for use during compilation.
+     *
+     * @param {string} propertyName
+     * @param {CompiledSchema} propertySchema
+     * @returns {CompiledSchema}
+     *
+     * @internal
+     */
+    _setPropertySchema(propertyName: string, propertySchema: CompiledSchema): CompiledSchema;
+    /**
+     * Return all child schemas that have a particular option tag
+     *
+     * @param {string} tag
+     * @returns {CompiledSchema[]}
+     * @deprecated
+     */
+    getTagged(tag: string): CompiledSchema[];
+    /**
+     * Get the first child schema that has a particular option tag
+     *
+     * @param {string} tag
+     * @returns {CompiledSchema|undefined}
+     * @deprecated
+     */
+    getFirstTagged(tag: string): CompiledSchema | undefined;
+    /**
+     * Return true if the path is legal within the schema (including all union schemas)
+     *
+     * @param {string} path
+     * @returns {boolean}
+     */
+    isValidPath(path: string): boolean;
+    /**
+     * Write-protect this schema at the end of compilation.
+     * @param {Set<CompiledSchema>} [seen]
+     * @internal
+     */
+    _freeze(seen?: Set<CompiledSchema>): void;
+    #private;
+}
+export type CompiledSchemaMetadata = ISchemaMetadata;
+export type CompiledSchemaOptions = ISchemaOptions;
+export type CompiledSchemaHandlers = {
+    normalizers?: ValueProcessor[] | undefined;
+    conditions?: ValueProcessor[] | undefined;
+    transformers?: ValueProcessor[] | undefined;
+    finalizers?: ValueProcessor[] | undefined;
+    validators?: ValueProcessor[] | undefined;
+    serializers?: ValueProcessor[] | undefined;
+    discriminators?: ValueProcessor[] | undefined;
+};
+export type CompiledSchemaProperties = {
+    [key: string]: CompiledSchema;
+};
+export type CompiledSchemaUnionSchemas = {
+    [key: string]: CompiledSchema;
+};
+export type SharedOptions = {
+    location?: SchemaLocation | undefined;
+    context?: TraversalContext | TraversalContextOptions | undefined;
+};
+export type ValidateOptions = SharedOptions & {
+    [key: string]: any;
+};
+export type SerializeOptions = SharedOptions & {
+    [key: string]: any;
+};
+export type ProcessOptions = SharedOptions & {
+    assignments?: Map<string, any>;
+} & {
+    [key: string]: any;
+};
+export type ProcessAssignmentsOptions = SharedOptions & {
+    [key: string]: any;
+};
+import { ValueProcessor } from './value-processor/value-processor.js';
+import type { SchemaData } from './types.js';
+import { SchemaLocation } from './schema-location.js';
+import type { ISchemaMetadata } from './types.js';
+import type { ISchemaOptions } from './types.js';
+import { TraversalContext } from './traversal/traversal-context.js';
+import type { TraversalContextOptions } from './traversal/traversal-context.js';