@cleverbrush/mapper 4.5.0 → 5.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (C) 2024 by Andrew Zolotuhkin <andrew_zol@cleverbrush.com>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/cleverbrush/framework/actions/workflows/ci.yml/badge.svg)](https://github.com/cleverbrush/framework/actions/workflows/ci.yml)
 [![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](../../LICENSE)
 <!-- coverage-badge-start -->
-![Coverage](https://img.shields.io/badge/coverage-96.8%25-brightgreen)
+![Unit coverage](https://img.shields.io/badge/unit_coverage-98.8%25-brightgreen)
 <!-- coverage-badge-end -->
 
 A type-safe, declarative object mapper for converting objects between different `@cleverbrush/schema` representations. Uses PropertyDescriptors as pointers to properties (similar to expressions in C# .NET) and enforces **compile-time completeness** — TypeScript will produce an error if any target property is not mapped, auto-mapped, or explicitly ignored.
@@ -86,7 +86,7 @@ const dto = await mapFn({
 1. **Define schemas** — use `@cleverbrush/schema` to define source and target shapes
 2. **Configure mappings** — use `.for()` to select a target property, then `.from()`, `.compute()`, or `.ignore()` to define how it's populated
 3. **Auto-mapping fills the gaps** — properties with the same name and compatible type are mapped automatically
-4. **Get a mapper function** — `registry.getMapper(from, to)` returns an async function that transforms objects
+4. **Get a mapper function** — use `getMapper(from, to)` for an async function or `getSyncMapper(from, to)` when all steps are synchronous
 5. **TypeScript enforces completeness** — if any target property is unmapped, you get a compile-time error
 
 ## Compile-Time Safety
@@ -225,6 +225,32 @@ Every non-auto-mappable target property must be either mapped or explicitly igno
 - A **compile-time TypeScript type error** — a type-assignability mismatch that includes the unmapped property names in the type parameters
 - A **runtime `MapperConfigurationError`** if type checks are bypassed
 
+## Synchronous mapping
+
+Use the same `configure()` API and retrieve a synchronous mapper when every final
+step and nested mapping is synchronous:
+
+```ts
+const registry = mapper().configure(Source, Target, m => m
+    .for(t => t.label).compute(s => s.name.toUpperCase()));
+const toTarget = registry.getSyncMapper(Source, Target);
+const results = rows.map(toTarget); // ordinary values, not promises
+```
+
+Completeness checking, `.from()`, ignores, nested objects/arrays and compatible
+auto-mapping still apply. Async computations or nested async mappings reject
+`getSyncMapper()` at compile time; runtime guards cover JavaScript and unsafe
+casts too. Callbacks are never probed during configuration. A function falsely
+typed as synchronous that returns a promise/thenable throws when invoked.
+`getMapper()` still always returns an async function. There is no separate
+`configureSync()` API.
+
+Configure once and reuse the same source/target schema instances. Queries can
+provide their projection schema through `.rowSchema`; see the
+[projection-aware read guide](../knex-schema/README.md#projection-aware-reads), including separate
+definition/mapping/service files and explicit polymorphic dispatch. The mapper
+performs no database calls or application enrichment.
+
 ## API
 
 ### `mapper()`
@@ -252,6 +278,13 @@ const mapFn = registry.getMapper(ApiUser, DomainUser);
 const result = await mapFn(sourceObject);
 ```
 
+### `registry.getSyncMapper(fromSchema, toSchema)`
+
+Retrieves an ordinary function for a complete, synchronous mapping. It returns
+the target value directly and can be passed to `rows.map(...)`. Async final steps
+or nested async mappings are rejected. See [Synchronous mapping](#synchronous-mapping)
+for runtime guards and schema identity requirements.
+
 ### `Mapper`
 
 A fluent builder for configuring how each target property is populated:

package/dist/MappingRegistry.d.ts

@@ -1,4 +1,4 @@
-import { ArraySchemaBuilder, type InferType, ObjectSchemaBuilder, type PropertyDescriptor, type PropertyDescriptorTree, type SchemaBuilder, SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR } from '@cleverbrush/schema';
+import { type InferType, ObjectSchemaBuilder, type PropertyDescriptor, type PropertyDescriptorTree, type SchemaBuilder, SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR } from '@cleverbrush/schema';
 /**
  * Internal symbol used to brand target property descriptors with their key.
  * Using a symbol instead of a string property keeps it out of IntelliSense.
@@ -9,14 +9,49 @@ declare const SYMBOL_TARGET_PROPERTY_KEY: unique symbol;
  * unmapped target properties. Using a symbol keeps it out of IntelliSense.
  */
 declare const SYMBOL_UNMAPPED: unique symbol;
+declare const SYMBOL_STEPS: unique symbol;
+type Step<T, K extends string, Async extends boolean> = Omit<T, K> & Record<K, Async>;
+type IsAsync<T> = 0 extends 1 & T ? true : [Extract<T, PromiseLike<any>>] extends [never] ? false : true;
+type ArraySchemaShape = {
+    introspect(): {
+        elementSchema: unknown;
+    };
+};
+type ObjectSchemaShape = {
+    introspect(): {
+        properties: unknown;
+    };
+};
+type SameProperties<A, B> = [keyof A, keyof B] extends [keyof B, keyof A] ? [A, B] extends [B, A] ? true : false : false;
+type RegisteredMatch<S, T, Registered> = S extends ObjectSchemaShape ? T extends ObjectSchemaShape ? Registered extends [infer From, infer To] ? [InferType<S>, InferType<T>] extends [
+    InferType<From>,
+    InferType<To>
+] ? [InferType<From>, InferType<To>] extends [
+    InferType<S>,
+    InferType<T>
+] ? SameProperties<ExtractSchemaProperties<S>, ExtractSchemaProperties<From>> extends true ? SameProperties<ExtractSchemaProperties<T>, ExtractSchemaProperties<To>> : false : false : false : false : false : false;
+type NestedAsync<S, T, Registered> = S extends ArraySchemaShape ? T extends ArraySchemaShape ? NestedAsync<ExtractArrayElementSchema<S>, ExtractArrayElementSchema<T>, Registered> : false : true extends RegisteredMatch<S, T, Registered> ? true : false;
+type AsyncKeys<S, T, Registered, Steps> = {
+    [K in keyof ExtractSchemaProperties<T> & string]: K extends keyof Steps ? Steps[K] extends false ? never : K : K extends keyof ExtractSchemaProperties<S> ? NestedAsync<ExtractSchemaProperties<S>[K], ExtractSchemaProperties<T>[K], Registered> extends false ? never : K : never;
+}[keyof ExtractSchemaProperties<T> & string];
+/** Compile-time diagnostics for incomplete or asynchronous mapping steps. */
+type SyncMappingArguments<Unmapped extends string, Async> = [Unmapped] extends [
+    never
+] ? [Async] extends [never] ? [] : [error: 'Mapping contains asynchronous steps'] : [error: `Unmapped properties: ${Unmapped}`];
+/** Compile-time diagnostics for registered synchronous mapping pairs. */
+type RegisteredSyncArguments<Pair, Registered, Async> = Pair extends Registered ? Pair extends Async ? [error: 'Mapping contains asynchronous steps'] : [] : [error: 'Mapping is not registered'];
 /**
  * Extracts the properties record from an ObjectSchemaBuilder.
  */
-type ExtractSchemaProperties<T> = T extends ObjectSchemaBuilder<infer TProperties, any, any> ? TProperties : never;
+type ExtractSchemaProperties<T> = T extends {
+    introspect(): {
+        properties: infer TProperties;
+    };
+} ? TProperties : never;
 /**
  * Gets all top-level property key names of an ObjectSchemaBuilder.
  */
-type SchemaKeys<T extends ObjectSchemaBuilder<any, any, any>> = keyof ExtractSchemaProperties<T> & string;
+type SchemaKeys<T extends ObjectSchemaShape> = keyof ExtractSchemaProperties<T> & string;
 /**
  * Branded phantom type that tags a property descriptor with its key name.
  * This allows TypeScript to infer which property was selected in the
@@ -32,23 +67,27 @@ type TargetPropertyKey<K extends string> = {
  * with `TargetPropertyKey<K>` so the key can be inferred from the return
  * type of the selector callback.
  */
-type TargetPropertyTree<TSchema extends ObjectSchemaBuilder<any, any, any>, TAllowedKeys extends string> = {
-    [K in SchemaKeys<TSchema> & TAllowedKeys]: TargetPropertyKey<K> & PropertyDescriptor<TSchema, ExtractSchemaProperties<TSchema>[K], any>;
+type TargetPropertyTree<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TAllowedKeys extends string> = {
+    -readonly [K in keyof ExtractSchemaProperties<TSchema> as K extends TAllowedKeys ? K : never]-?: TargetPropertyKey<K & string> & PropertyDescriptor<TSchema, ExtractSchemaProperties<TSchema>[K], any>;
 };
 /**
  * Infers the TypeScript type of a specific property in an ObjectSchemaBuilder
  * by its key name.
  */
-type SchemaPropertyInferredType<TSchema extends ObjectSchemaBuilder<any, any, any>, K extends string> = K extends keyof ExtractSchemaProperties<TSchema> ? InferType<ExtractSchemaProperties<TSchema>[K]> : never;
+type SchemaPropertyInferredType<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, K extends string> = K extends keyof ExtractSchemaProperties<TSchema> ? InferType<ExtractSchemaProperties<TSchema>[K]> : never;
 /**
  * Extracts the schema (SchemaBuilder) of a specific property in an
  * ObjectSchemaBuilder by its key name.
  */
-type TargetPropertySchema<TSchema extends ObjectSchemaBuilder<any, any, any>, K extends string> = K extends keyof ExtractSchemaProperties<TSchema> ? ExtractSchemaProperties<TSchema>[K] : never;
+type TargetPropertySchema<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, K extends string> = K extends keyof ExtractSchemaProperties<TSchema> ? ExtractSchemaProperties<TSchema>[K] : never;
 /**
  * Extracts the element schema from an ArraySchemaBuilder.
  */
-type ExtractArrayElementSchema<T> = T extends ArraySchemaBuilder<infer TElementSchema, any, any> ? TElementSchema : never;
+type ExtractArrayElementSchema<T> = T extends {
+    introspect(): {
+        elementSchema: infer TElementSchema;
+    };
+} ? NonNullable<TElementSchema> : never;
 /**
  * Extracts the property schema from a PropertyDescriptor's `getSchema()`
  * return type. Used by {@link IsFromCompatible} to recover the source
@@ -72,13 +111,13 @@ type ExtractPropertySchema<T> = T extends {
  *   → `false` (same-name, compatible primitive types → auto-mappable)
  * - Neither is ObjectSchemaBuilder + incompatible InferType → `true`
  */
-type NeedsMapping<TSourcePropSchema, TTargetPropSchema, TRegistered> = TSourcePropSchema extends ArraySchemaBuilder<any, any, any> ? TTargetPropSchema extends ArraySchemaBuilder<any, any, any> ? NeedsMapping<ExtractArrayElementSchema<TSourcePropSchema>, ExtractArrayElementSchema<TTargetPropSchema>, TRegistered> : true : TTargetPropSchema extends ArraySchemaBuilder<any, any, any> ? true : TSourcePropSchema extends ObjectSchemaBuilder<any, any, any> ? TTargetPropSchema extends ObjectSchemaBuilder<any, any, any> ? [TSourcePropSchema, TTargetPropSchema] extends TRegistered ? false : InferType<TSourcePropSchema> extends InferType<TTargetPropSchema> ? InferType<TTargetPropSchema> extends InferType<TSourcePropSchema> ? false : true : true : true : TTargetPropSchema extends ObjectSchemaBuilder<any, any, any> ? true : InferType<TSourcePropSchema> extends InferType<TTargetPropSchema> ? false : true;
+type NeedsMapping<TSourcePropSchema, TTargetPropSchema, TRegistered> = TSourcePropSchema extends ArraySchemaShape ? TTargetPropSchema extends ArraySchemaShape ? NeedsMapping<ExtractArrayElementSchema<TSourcePropSchema>, ExtractArrayElementSchema<TTargetPropSchema>, TRegistered> : true : TTargetPropSchema extends ArraySchemaShape ? true : TSourcePropSchema extends ObjectSchemaShape ? TTargetPropSchema extends ObjectSchemaShape ? true extends RegisteredMatch<TSourcePropSchema, TTargetPropSchema, TRegistered> ? false : InferType<TSourcePropSchema> extends InferType<TTargetPropSchema> ? InferType<TTargetPropSchema> extends InferType<TSourcePropSchema> ? false : true : true : true : TTargetPropSchema extends ObjectSchemaShape ? true : InferType<TSourcePropSchema> extends InferType<TTargetPropSchema> ? false : true;
 /**
  * From all keys of the target schema, filter down to only those that
  * require explicit mapping (i.e. `NeedsMapping` is `true`).
  * Keys where `NeedsMapping` is `false` can be auto-mapped via the registry.
  */
-type KeysNeedingMapping<TFromSchema extends ObjectSchemaBuilder<any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any>, TRegistered> = {
+type KeysNeedingMapping<TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TRegistered> = {
     [K in SchemaKeys<TToSchema>]: K extends SchemaKeys<TFromSchema> ? NeedsMapping<ExtractSchemaProperties<TFromSchema>[K], ExtractSchemaProperties<TToSchema>[K], TRegistered> extends true ? K : never : K;
 }[SchemaKeys<TToSchema>];
 /**
@@ -90,7 +129,7 @@ type KeysNeedingMapping<TFromSchema extends ObjectSchemaBuilder<any, any, any>,
  */
 type CheckSchemaCompatible<TSourceSchema, TTargetSchema, TRegistered> = [
     InferType<TSourceSchema>
-] extends [InferType<TTargetSchema>] ? true : TSourceSchema extends ArraySchemaBuilder<any, any, any> ? TTargetSchema extends ArraySchemaBuilder<any, any, any> ? CheckSchemaCompatible<ExtractArrayElementSchema<TSourceSchema>, ExtractArrayElementSchema<TTargetSchema>, TRegistered> : false : TSourceSchema extends ObjectSchemaBuilder<any, any, any> ? TTargetSchema extends ObjectSchemaBuilder<any, any, any> ? [TSourceSchema, TTargetSchema] extends TRegistered ? true : false : false : false;
+] extends [InferType<TTargetSchema>] ? true : TSourceSchema extends ArraySchemaShape ? TTargetSchema extends ArraySchemaShape ? CheckSchemaCompatible<ExtractArrayElementSchema<TSourceSchema>, ExtractArrayElementSchema<TTargetSchema>, TRegistered> : false : TSourceSchema extends ObjectSchemaShape ? TTargetSchema extends ObjectSchemaShape ? true extends RegisteredMatch<TSourceSchema, TTargetSchema, TRegistered> ? true : false : false : false;
 /**
  * Checks whether the source property selected by `from()` is compatible
  * with the target property, evaluated *after* `TReturn` has been inferred.
@@ -100,8 +139,11 @@ type CheckSchemaCompatible<TSourceSchema, TTargetSchema, TRegistered> = [
  * successfully, and this type performs the actual compatibility check
  * in the `_args` conditional spread.
  */
-type IsFromCompatible<TReturn, TToSchema extends ObjectSchemaBuilder<any, any, any>, TKey extends string, TRegistered> = [ExtractPropertySchema<TReturn>] extends [never] ? false : CheckSchemaCompatible<ExtractPropertySchema<TReturn>, TargetPropertySchema<TToSchema, TKey>, TRegistered>;
-export type SchemaToSchemaMapperResult<TFromSchema extends ObjectSchemaBuilder<any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any>> = (from: InferType<TFromSchema>) => Promise<InferType<TToSchema>>;
+type IsFromCompatible<TReturn, TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TKey extends string, TRegistered> = [ExtractPropertySchema<TReturn>] extends [never] ? false : CheckSchemaCompatible<ExtractPropertySchema<TReturn>, TargetPropertySchema<TToSchema, TKey>, TRegistered>;
+/** A mapping function that always returns a Promise, including for pure mappings. */
+export type SchemaToSchemaMapperResult<TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = (from: InferType<TFromSchema>) => Promise<InferType<TToSchema>>;
+/** A complete synchronous mapping; unexpected thenables throw instead of leaking into DTOs. */
+export type SyncSchemaToSchemaMapperResult<TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = (from: InferType<TFromSchema>) => InferType<TToSchema>;
 export declare class MapperConfigurationError extends Error {
     constructor(messageOrUnmappedProperties: string | string[]);
 }
@@ -112,11 +154,11 @@ export declare class MapperConfigurationError extends Error {
  * - `compute()` — compute from the entire source object
  * - `ignore()` — explicitly skip the property
  */
-export declare class PropertyMappingBuilder<TFromSchema extends ObjectSchemaBuilder<any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any>, TKey extends string, TUnmapped extends string, TRegistered = never> {
+export declare class PropertyMappingBuilder<TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TKey extends string, TUnmapped extends string, TRegistered = never, TAsyncRegistered = never, TSteps = {}> {
     private readonly _mapper;
     private readonly _targetKey;
     /** @internal */
-    constructor(mapper: Mapper<TFromSchema, TToSchema, any, TRegistered>, targetKey: TKey);
+    constructor(mapper: Mapper<TFromSchema, TToSchema, any, TRegistered, TAsyncRegistered, TSteps>, targetKey: TKey);
     /**
      * Maps the target property from a source property. The selector
      * receives the source schema's PropertyDescriptorTree and supports
@@ -141,21 +183,21 @@ export declare class PropertyMappingBuilder<TFromSchema extends ObjectSchemaBuil
                 success: boolean;
             };
         };
-    }>(selector: (tree: PropertyDescriptorTree<TFromSchema, TFromSchema, SchemaPropertyInferredType<TToSchema, TKey>>) => TReturn, ..._args: [TReturn] extends [never] ? [
+    }>(selector: (tree: PropertyDescriptorTree<TFromSchema, TFromSchema, any>) => TReturn, ..._args: [TReturn] extends [never] ? [
         error: `Property '${TKey}': source property type is not assignable to the target property type. Use compute() instead.`
     ] : IsFromCompatible<TReturn, TToSchema, TKey, TRegistered> extends true ? [] : [
         error: `Property '${TKey}': source property type is not assignable to the target property type. Use compute() instead.`
-    ]): Mapper<TFromSchema, TToSchema, Exclude<TUnmapped, TKey>, TRegistered>;
+    ]): Mapper<TFromSchema, TToSchema, Exclude<TUnmapped, TKey>, TRegistered, TAsyncRegistered, Step<TSteps, TKey, NestedAsync<ExtractPropertySchema<TReturn>, TargetPropertySchema<TToSchema, TKey>, TAsyncRegistered>>>;
     /**
      * Computes the target property value from the entire source object.
      * Supports both sync and async functions.
      */
-    compute(fn: ((obj: InferType<TFromSchema>) => SchemaPropertyInferredType<TToSchema, TKey>) | ((obj: InferType<TFromSchema>) => Promise<SchemaPropertyInferredType<TToSchema, TKey>>)): Mapper<TFromSchema, TToSchema, Exclude<TUnmapped, TKey>, TRegistered>;
+    compute<TResult extends SchemaPropertyInferredType<TToSchema, TKey> | Promise<SchemaPropertyInferredType<TToSchema, TKey>>>(fn: (obj: InferType<TFromSchema>) => TResult): Mapper<TFromSchema, TToSchema, Exclude<TUnmapped, TKey>, TRegistered, TAsyncRegistered, Step<TSteps, TKey, IsAsync<TResult>>>;
     /**
      * Explicitly excludes the target property from mapping.
      * The property will not appear in the output object.
      */
-    ignore(): Mapper<TFromSchema, TToSchema, Exclude<TUnmapped, TKey>, TRegistered>;
+    ignore(): Mapper<TFromSchema, TToSchema, Exclude<TUnmapped, TKey>, TRegistered, TAsyncRegistered, Step<TSteps, TKey, false>>;
 }
 /**
  * A fluent builder for configuring how each target property is populated
@@ -173,9 +215,11 @@ export declare class PropertyMappingBuilder<TFromSchema extends ObjectSchemaBuil
  * @typeParam TToSchema - target ObjectSchemaBuilder
  * @typeParam TUnmapped - union of target property key names not yet mapped
  */
-export declare class Mapper<TFromSchema extends ObjectSchemaBuilder<any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any>, TUnmapped extends string = SchemaKeys<TToSchema>, TRegistered = never> {
+export declare class Mapper<TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TUnmapped extends string = SchemaKeys<TToSchema>, TRegistered = never, TAsyncRegistered = never, TSteps = {}> {
     /** Phantom property for structural type-checking of TUnmapped. */
     readonly [SYMBOL_UNMAPPED]: TUnmapped;
+    /** @internal Tracks final per-property computations without executing them. */
+    readonly [SYMBOL_STEPS]: TSteps;
     private readonly _fromSchema;
     private readonly _toSchema;
     private readonly _registry;
@@ -186,7 +230,7 @@ export declare class Mapper<TFromSchema extends ObjectSchemaBuilder<any, any, an
      * @param toSchema - `object` schema to map to
      * @param registry - optional MappingRegistry to auto-register the mapper
      */
-    constructor(fromSchema: TFromSchema, toSchema: TToSchema, registry?: MappingRegistry<any>);
+    constructor(fromSchema: TFromSchema, toSchema: TToSchema, registry?: MappingRegistry<any, any>);
     /**
      * Selects a target property to configure. The selector callback
      * receives a tree of all target properties. Navigate by
@@ -196,7 +240,15 @@ export declare class Mapper<TFromSchema extends ObjectSchemaBuilder<any, any, an
      * ObjectSchemaBuilder with a registered mapping) are also available
      * for explicit override.
      */
-    for<TKey extends SchemaKeys<TToSchema>>(selector: (tree: TargetPropertyTree<TToSchema, SchemaKeys<TToSchema>>) => TargetPropertyKey<TKey>): PropertyMappingBuilder<TFromSchema, TToSchema, TKey, TUnmapped, TRegistered>;
+    for<TKey extends SchemaKeys<TToSchema>>(selector: (tree: TargetPropertyTree<TToSchema, SchemaKeys<TToSchema>>) => TargetPropertyKey<TKey>): PropertyMappingBuilder<TFromSchema, TToSchema, TKey, TUnmapped, TRegistered, TAsyncRegistered, TSteps>;
+    /**
+     * Compile a synchronous function when the complete mapping has no async steps.
+     * Eligibility is inferred through compute(), from(), nested mappings and overrides.
+     * Callbacks are never probed during configuration. A disguised Promise/thenable
+     * throws at invocation; known async functions/dependencies throw at compilation.
+     * @throws MapperConfigurationError for incomplete or asynchronous mappings.
+     */
+    getSyncMapper(..._args: SyncMappingArguments<TUnmapped, AsyncKeys<TFromSchema, TToSchema, TAsyncRegistered, TSteps>>): SyncSchemaToSchemaMapperResult<TFromSchema, TToSchema>;
     /**
      * Returns the configured async mapping function.
      *
@@ -212,9 +264,9 @@ export declare class Mapper<TFromSchema extends ObjectSchemaBuilder<any, any, an
      */
     getMapper(..._args: [TUnmapped] extends [never] ? [] : [error: `Unmapped properties: ${TUnmapped}`]): SchemaToSchemaMapperResult<TFromSchema, TToSchema>;
 }
-export declare class MappingRegistry<TRegistered = never> {
+export declare class MappingRegistry<TRegistered = never, TAsyncRegistered = never> {
     #private;
-    protected readonly _mappers: Map<ObjectSchemaBuilder<any, any, any>, Map<ObjectSchemaBuilder<any, any, any>, SchemaToSchemaMapperResult<any, any>>>;
+    protected readonly _mappers: Map<ObjectSchemaBuilder<any, any, any, any, any, any, any>, Map<ObjectSchemaBuilder<any, any, any, any, any, any, any>, SchemaToSchemaMapperResult<any, any>>>;
     /**
      * Defines a mapping between two schemas and returns a new immutable
      * registry containing the mapping. The callback `fn` receives a fresh
@@ -231,7 +283,21 @@ export declare class MappingRegistry<TRegistered = never> {
      * @throws if schemas are invalid, mapping is duplicate, or unmapped
      *         properties remain that cannot be auto-mapped
      */
-    configure<TFromSchema extends ObjectSchemaBuilder<any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any>>(fromSchema: TFromSchema, toSchema: TToSchema, fn: (mapper: Mapper<TFromSchema, TToSchema, KeysNeedingMapping<TFromSchema, TToSchema, TRegistered>, TRegistered>) => Mapper<TFromSchema, TToSchema, never, TRegistered>): MappingRegistry<TRegistered | [TFromSchema, TToSchema]>;
+    configure<TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TSteps = {}>(fromSchema: TFromSchema, toSchema: TToSchema, fn: (mapper: Mapper<TFromSchema, TToSchema, KeysNeedingMapping<TFromSchema, TToSchema, TRegistered>, TRegistered, TAsyncRegistered>) => Mapper<TFromSchema, TToSchema, never, TRegistered, TAsyncRegistered, TSteps>): MappingRegistry<TRegistered | [TFromSchema, TToSchema], TAsyncRegistered | ([
+        AsyncKeys<TFromSchema, TToSchema, TAsyncRegistered, TSteps>
+    ] extends [never] ? never : [TFromSchema, TToSchema])>;
+    /**
+     * Retrieve a registered synchronous mapper inferred from configure().
+     * The pair must be registered and its final steps must all be synchronous.
+     * Async mappings remain usable with getMapper(); configuration never executes
+     * compute callbacks. Unexpected thenables throw when the returned mapper runs.
+     * @throws MapperConfigurationError for an asynchronous dependency.
+     * @throws Error if the schema pair has not been registered.
+     */
+    getSyncMapper<TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(fromSchema: TFromSchema, toSchema: TToSchema, ..._args: RegisteredSyncArguments<[
+        TFromSchema,
+        TToSchema
+    ], TRegistered, TAsyncRegistered>): SyncSchemaToSchemaMapperResult<TFromSchema, TToSchema>;
     /**
      * Gets a mapper function that will map from the fromSchema to the toSchema.
      * Throws an error if no mapper is found for the given schemas pair.
@@ -240,7 +306,7 @@ export declare class MappingRegistry<TRegistered = never> {
      * @returns a function that will take a value of the fromSchema type as an argument and
      * return a promise resolving to a value of the toSchema type
      */
-    getMapper<TFromSchema extends ObjectSchemaBuilder<any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any>>(fromSchema: TFromSchema, toSchema: TToSchema): SchemaToSchemaMapperResult<TFromSchema, TToSchema>;
+    getMapper<TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(fromSchema: TFromSchema, toSchema: TToSchema): SchemaToSchemaMapperResult<TFromSchema, TToSchema>;
 }
 /**
  * Creates a new empty {@link MappingRegistry}.

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export type { SchemaToSchemaMapperResult } from './MappingRegistry.js';
+export type { SchemaToSchemaMapperResult, SyncSchemaToSchemaMapperResult } from './MappingRegistry.js';
 export { Mapper, MapperConfigurationError, MappingRegistry, mapper, PropertyMappingBuilder } from './MappingRegistry.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-import{ArraySchemaBuilder as u,ObjectSchemaBuilder as i,SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR as g}from"@cleverbrush/schema";var j=Symbol("targetPropertyKey");var l=class extends Error{constructor(e){super(typeof e=="string"?e:`Mapper configuration error: the following target properties are not mapped and not ignored: ${e.join(", ")}`),this.name="MapperConfigurationError"}};function b(m,e,r){if(m instanceof i&&e instanceof i){if(r){let o=r._mappers.get(m)?.get(e);if(o)return o}let a=Object.keys(m.introspect().properties||{}).sort(),s=Object.keys(e.introspect().properties||{}).sort();return a.length===s.length&&a.every((t,o)=>t===s[o])?async t=>t:null}if(m instanceof u&&e instanceof u){let a=m.introspect().elementSchema,s=e.introspect().elementSchema;if(a&&s){let t=b(a,s,r);if(t)return async o=>{if(o!=null)return Array.isArray(o)?Promise.all(o.map(t)):o}}return null}if(!(m instanceof i)&&!(e instanceof i)&&!(m instanceof u)&&!(e instanceof u)){let a=typeof m.introspect=="function"?m.introspect():void 0,s=typeof e.introspect=="function"?e.introspect():void 0;return!a||!s||a.type!==s.type?null:async t=>t}return null}var x=class{_mapper;_targetKey;constructor(e,r){this._mapper=e,this._targetKey=r}from(e,...r){let a=i.getPropertiesFor(this._mapper._fromSchema),t=e(a)[g],o=t.getSchema(),y=(this._mapper._toSchema.introspect().properties||{})[this._targetKey];if(o instanceof i&&y instanceof i&&this._mapper._registry){let T=this._mapper._registry._mappers.get(o)?.get(y);if(T)return this._mapper._mappings.set(this._targetKey,{type:"auto",sourceDescriptorInner:t,autoMapper:T}),this._mapper}if(o instanceof u&&y instanceof u){let h=o.introspect().elementSchema,T=y.introspect().elementSchema;if(h&&T){let p=b(h,T,this._mapper._registry);if(p)return this._mapper._mappings.set(this._targetKey,{type:"autoArray",sourceDescriptorInner:t,elementMapper:p}),this._mapper}}return this._mapper._mappings.set(this._targetKey,{type:"prop",sourceDescriptorInner:t}),this._mapper}compute(e){return this._mapper._mappings.set(this._targetKey,{type:"custom",fn:e}),this._mapper}ignore(){return this._mapper._mappings.set(this._targetKey,{type:"ignore"}),this._mapper}},M=class{_fromSchema;_toSchema;_registry;_mappings=new Map;constructor(e,r,a){this._fromSchema=e,this._toSchema=r,this._registry=a}for(e){let r,a=new Proxy({},{get(o,d){return typeof d=="string"&&(r=d),{[j]:d}}});if(e(a),!r)throw new Error("for selector must access a property on the target tree");let s=this._toSchema.introspect();if(!(s.properties?Object.keys(s.properties):[]).includes(r))throw new l(`Property "${r}" does not exist in the target schema`);return new x(this,r)}getMapper(...e){let r=this._toSchema.introspect(),a=r.properties?Object.keys(r.properties):[];if(this._registry){let h=this._fromSchema.introspect().properties||{},T=r.properties||{},p=i.getPropertiesFor(this._fromSchema);for(let c of a){if(this._mappings.has(c))continue;let S=h[c],n=T[c];if(!S||!n)continue;let f=p[c];if(f?.[g]){if(S instanceof i&&n instanceof i){let _=this._registry._mappers.get(S)?.get(n);if(_){this._mappings.set(c,{type:"auto",sourceDescriptorInner:f[g],autoMapper:_});continue}let P=Object.keys(S.introspect().properties||{}).sort(),B=Object.keys(n.introspect().properties||{}).sort();P.length===B.length&&P.every((O,E)=>O===B[E])&&this._mappings.set(c,{type:"prop",sourceDescriptorInner:f[g]});continue}if(!(S instanceof i)&&!(n instanceof i)&&!(S instanceof u)&&!(n instanceof u)){this._mappings.set(c,{type:"prop",sourceDescriptorInner:f[g]});continue}if(S instanceof u&&n instanceof u){let K=S.introspect().elementSchema,_=n.introspect().elementSchema;if(K&&_){let P=b(K,_,this._registry);P&&this._mappings.set(c,{type:"autoArray",sourceDescriptorInner:f[g],elementMapper:P})}}}}}let s=a.filter(y=>!this._mappings.has(y));if(s.length>0)throw new l(s);let t=i.getPropertiesFor(this._toSchema),o=new Map(this._mappings),d=async y=>{let h={};for(let[T,p]of o){if(p.type==="ignore")continue;let c;if(p.type==="prop"){let n=p.sourceDescriptorInner.getValue(y);if(n.success)c=n.value;else continue}else if(p.type==="custom")c=await p.fn(y);else if(p.type==="auto"){let n=p.sourceDescriptorInner.getValue(y);if(n.success&&n.value!==void 0)c=await p.autoMapper(n.value);else continue}else if(p.type==="autoArray"){let n=p.sourceDescriptorInner.getValue(y);if(n.success&&n.value!=null){if(!Array.isArray(n.value))throw new l(`Expected array for property "${T}" but got ${typeof n.value}`);c=await Promise.all(n.value.map(p.elementMapper))}else continue}let S=t[T];S?.[g]?S[g].setValue(h,c,{createMissingStructure:!0}):h[T]=c}return h};return this._registry&&this._registry._mappers.get(this._fromSchema)?.set(this._toSchema,d),d}},R=class m{_mappers=new Map;#e(e,r){return!(!e||!r||!(e instanceof i)||!(r instanceof i))}configure(e,r,a){if(!this.#e(e,r))throw new Error("Both fromSchema and toSchema must be instances of ObjectSchemaBuilder");if(this._mappers.get(e)?.has(r))throw new Error("Duplicate mapping: a mapping for this schemas pair is already registered");let t=new m;for(let[y,h]of this._mappers)t._mappers.set(y,new Map(h));t._mappers.has(e)||t._mappers.set(e,new Map);let o=new M(e,r,t);return a(o).getMapper(),t}getMapper(e,r){if(!this.#e(e,r))throw new Error("Both fromSchema and toSchema must be instances of ObjectSchemaBuilder");let a=this._mappers.get(e);if(!a)throw new Error("No mapper found for the given schemas pair");let s=a.get(r);if(!s)throw new Error("No mapper found for the given schemas pair");return s}};function I(){return new R}export{M as Mapper,l as MapperConfigurationError,R as MappingRegistry,x as PropertyMappingBuilder,I as mapper};
+import{ArraySchemaBuilder as g,ObjectSchemaBuilder as u,SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR as f}from"@cleverbrush/schema";var j=Symbol("targetPropertyKey");var R=new WeakMap;function E(p,e){if(p!=null&&typeof p.then=="function")throw new l(`Synchronous mapping returned a thenable for property "${e}"`);return p}function I(p){let e=R.get(p);if(!e)throw new l("Mapping contains an asynchronous computation or nested mapper");return e}var l=class extends Error{constructor(e){super(typeof e=="string"?e:`Mapper configuration error: the following target properties are not mapped and not ignored: ${e.join(", ")}`),this.name="MapperConfigurationError"}};function O(p,e,t){if(p instanceof u&&e instanceof u){if(t){let a=t._mappers.get(p)?.get(e);if(a)return a}let c=Object.keys(p.introspect().properties||{}).sort(),m=Object.keys(e.introspect().properties||{}).sort();if(c.length===m.length&&c.every((r,a)=>r===m[a])){let r=async a=>a;return R.set(r,a=>a),r}return null}if(p instanceof g&&e instanceof g){let c=p.introspect().elementSchema,m=e.introspect().elementSchema;if(c&&m){let r=O(c,m,t);if(r){let a=async T=>{if(T!=null)return Array.isArray(T)?Promise.all(T.map(r)):T},d=R.get(r);return d&&R.set(a,T=>{if(T!=null)return Array.isArray(T)?T.map(d):T}),a}}return null}if(!(p instanceof u)&&!(e instanceof u)&&!(p instanceof g)&&!(e instanceof g)){let c=typeof p.introspect=="function"?p.introspect():void 0,m=typeof e.introspect=="function"?e.introspect():void 0;if(!c||!m||c.type!==m.type)return null;let r=async a=>a;return R.set(r,a=>a),r}return null}var A=class{_mapper;_targetKey;constructor(e,t){this._mapper=e,this._targetKey=t}from(e,...t){let c=u.getPropertiesFor(this._mapper._fromSchema),r=e(c)[f],a=r.getSchema(),T=(this._mapper._toSchema.introspect().properties||{})[this._targetKey];if(a instanceof u&&T instanceof u&&this._mapper._registry){let i=this._mapper._registry._mappers.get(a)?.get(T);if(i)return this._mapper._mappings.set(this._targetKey,{type:"auto",sourceDescriptorInner:r,autoMapper:i}),this._mapper}if(a instanceof g&&T instanceof g){let y=a.introspect().elementSchema,i=T.introspect().elementSchema;if(y&&i){let h=O(y,i,this._mapper._registry);if(h)return this._mapper._mappings.set(this._targetKey,{type:"autoArray",sourceDescriptorInner:r,elementMapper:h}),this._mapper}}return this._mapper._mappings.set(this._targetKey,{type:"prop",sourceDescriptorInner:r}),this._mapper}compute(e){return this._mapper._mappings.set(this._targetKey,{type:"custom",fn:e}),this._mapper}ignore(){return this._mapper._mappings.set(this._targetKey,{type:"ignore"}),this._mapper}},K=class{_fromSchema;_toSchema;_registry;_mappings=new Map;constructor(e,t,c){this._fromSchema=e,this._toSchema=t,this._registry=c}for(e){let t,c=new Proxy({},{get(a,d){return typeof d=="string"&&(t=d),{[j]:d}}});if(e(c),!t)throw new Error("for selector must access a property on the target tree");let m=this._toSchema.introspect();if(!(m.properties?Object.keys(m.properties):[]).includes(t))throw new l(`Property "${t}" does not exist in the target schema`);return new A(this,t)}getSyncMapper(...e){return I(this.getMapper())}getMapper(...e){let t=this._toSchema.introspect(),c=t.properties?Object.keys(t.properties):[];if(this._registry){let i=this._fromSchema.introspect().properties||{},h=t.properties||{},o=u.getPropertiesFor(this._fromSchema);for(let S of c){if(this._mappings.has(S))continue;let n=i[S],s=h[S];if(!n||!s)continue;let x=o[S];if(x?.[f]){if(n instanceof u&&s instanceof u){let M=this._registry._mappers.get(n)?.get(s);if(M){this._mappings.set(S,{type:"auto",sourceDescriptorInner:x[f],autoMapper:M});continue}let _=Object.keys(n.introspect().properties||{}).sort(),F=Object.keys(s.introspect().properties||{}).sort();_.length===F.length&&_.every((B,v)=>B===F[v])&&this._mappings.set(S,{type:"prop",sourceDescriptorInner:x[f]});continue}if(!(n instanceof u)&&!(s instanceof u)&&!(n instanceof g)&&!(s instanceof g)){this._mappings.set(S,{type:"prop",sourceDescriptorInner:x[f]});continue}if(n instanceof g&&s instanceof g){let P=n.introspect().elementSchema,M=s.introspect().elementSchema;if(P&&M){let _=O(P,M,this._registry);_&&this._mappings.set(S,{type:"autoArray",sourceDescriptorInner:x[f],elementMapper:_})}}}}}let m=c.filter(y=>!this._mappings.has(y));if(m.length>0)throw new l(m);let r=u.getPropertiesFor(this._toSchema),a=new Map(this._mappings),d=async y=>{let i={};for(let[h,o]of a){if(o.type==="ignore")continue;let S;if(o.type==="prop"){let s=o.sourceDescriptorInner.getValue(y);if(s.success)S=s.value;else continue}else if(o.type==="custom")S=await o.fn(y);else if(o.type==="auto"){let s=o.sourceDescriptorInner.getValue(y);if(s.success&&s.value!==void 0)S=await o.autoMapper(s.value);else continue}else if(o.type==="autoArray"){let s=o.sourceDescriptorInner.getValue(y);if(s.success&&s.value!=null){if(!Array.isArray(s.value))throw new l(`Expected array for property "${h}" but got ${typeof s.value}`);S=await Promise.all(s.value.map(o.elementMapper))}else continue}let n=r[h];n?.[f]?n[f].setValue(i,S,{createMissingStructure:!0}):i[h]=S}return i},T=[...a].map(([y,i])=>{let h=i.autoMapper??i.elementMapper,o=h?R.get(h):void 0;return h&&!o||i.fn?.constructor.name==="AsyncFunction"?null:{key:y,entry:i,nestedSync:o}});return T.every(y=>y!==null)&&R.set(d,y=>{let i={};for(let{key:h,entry:o,nestedSync:S}of T){if(o.type==="ignore")continue;let n;if(o.type==="custom")n=E(o.fn(y),h);else{let x=o.sourceDescriptorInner.getValue(y);if(!x.success)continue;if(n=x.value,o.type==="auto"){if(n===void 0)continue;n=E(S(n),h)}else if(o.type==="autoArray"){if(n==null)continue;if(!Array.isArray(n))throw new l(`Expected array for property "${h}" but got ${typeof n}`);n=n.map(P=>E(S(P),h))}}let s=r[h]?.[f];s?s.setValue(i,n,{createMissingStructure:!0}):i[h]=n}return i}),this._registry&&this._registry._mappers.get(this._fromSchema)?.set(this._toSchema,d),d}},b=class p{_mappers=new Map;#e(e,t){return!(!e||!t||!(e instanceof u)||!(t instanceof u))}configure(e,t,c){if(!this.#e(e,t))throw new Error("Both fromSchema and toSchema must be instances of ObjectSchemaBuilder");if(this._mappers.get(e)?.has(t))throw new Error("Duplicate mapping: a mapping for this schemas pair is already registered");let r=new p;for(let[T,y]of this._mappers)r._mappers.set(T,new Map(y));r._mappers.has(e)||r._mappers.set(e,new Map);let a=new K(e,t,r);return c(a).getMapper(),r}getSyncMapper(e,t,...c){return I(this.getMapper(e,t))}getMapper(e,t){if(!this.#e(e,t))throw new Error("Both fromSchema and toSchema must be instances of ObjectSchemaBuilder");let c=this._mappers.get(e);if(!c)throw new Error("No mapper found for the given schemas pair");let m=c.get(t);if(!m)throw new Error("No mapper found for the given schemas pair");return m}};function w(){return new b}export{K as Mapper,l as MapperConfigurationError,b as MappingRegistry,A as PropertyMappingBuilder,w as mapper};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/MappingRegistry.ts"],"sourcesContent":["import {\n    ArraySchemaBuilder,\n    type InferType,\n    ObjectSchemaBuilder,\n    type PropertyDescriptor,\n    type PropertyDescriptorTree,\n    type SchemaBuilder,\n    SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n} from '@cleverbrush/schema';\n\n/**\n * Internal symbol used to brand target property descriptors with their key.\n * Using a symbol instead of a string property keeps it out of IntelliSense.\n */\nconst SYMBOL_TARGET_PROPERTY_KEY: unique symbol = Symbol('targetPropertyKey');\n\n/**\n * Internal symbol used as a phantom property key on Mapper to track\n * unmapped target properties. Using a symbol keeps it out of IntelliSense.\n */\nconst SYMBOL_UNMAPPED: unique symbol = Symbol('unmapped');\n\n// ── Helper Types ──────────────────────────────────────────────────────\n\n/**\n * Extracts the properties record from an ObjectSchemaBuilder.\n */\ntype ExtractSchemaProperties<T> =\n    T extends ObjectSchemaBuilder<infer TProperties, any, any>\n        ? TProperties\n        : never;\n\n/**\n * Gets all top-level property key names of an ObjectSchemaBuilder.\n */\ntype SchemaKeys<T extends ObjectSchemaBuilder<any, any, any>> =\n    keyof ExtractSchemaProperties<T> & string;\n\n/**\n * Branded phantom type that tags a property descriptor with its key name.\n * This allows TypeScript to infer which property was selected in the\n * `for` callback, enabling compile-time tracking of mapped vs unmapped\n * properties.\n */\ntype TargetPropertyKey<K extends string> = {\n    readonly [SYMBOL_TARGET_PROPERTY_KEY]: K;\n};\n\n/**\n * Creates a tree of selectable target properties, filtered to only show\n * properties whose keys are in `TAllowedKeys`. Each property is branded\n * with `TargetPropertyKey<K>` so the key can be inferred from the return\n * type of the selector callback.\n */\ntype TargetPropertyTree<\n    TSchema extends ObjectSchemaBuilder<any, any, any>,\n    TAllowedKeys extends string\n> = {\n    [K in SchemaKeys<TSchema> & TAllowedKeys]: TargetPropertyKey<K> &\n        PropertyDescriptor<TSchema, ExtractSchemaProperties<TSchema>[K], any>;\n};\n\n/**\n * Infers the TypeScript type of a specific property in an ObjectSchemaBuilder\n * by its key name.\n */\ntype SchemaPropertyInferredType<\n    TSchema extends ObjectSchemaBuilder<any, any, any>,\n    K extends string\n> = K extends keyof ExtractSchemaProperties<TSchema>\n    ? InferType<ExtractSchemaProperties<TSchema>[K]>\n    : never;\n\n/**\n * Extracts the schema (SchemaBuilder) of a specific property in an\n * ObjectSchemaBuilder by its key name.\n */\ntype TargetPropertySchema<\n    TSchema extends ObjectSchemaBuilder<any, any, any>,\n    K extends string\n> = K extends keyof ExtractSchemaProperties<TSchema>\n    ? ExtractSchemaProperties<TSchema>[K]\n    : never;\n\n/**\n * Extracts the element schema from an ArraySchemaBuilder.\n */\ntype ExtractArrayElementSchema<T> =\n    T extends ArraySchemaBuilder<infer TElementSchema, any, any>\n        ? TElementSchema\n        : never;\n\n/**\n * Extracts the property schema from a PropertyDescriptor's `getSchema()`\n * return type. Used by {@link IsFromCompatible} to recover the source\n * property's schema from the inferred `TReturn` of the `from()` selector.\n */\ntype ExtractPropertySchema<T> = T extends {\n    [SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]: {\n        getSchema(): infer TSchema;\n    };\n}\n    ? TSchema\n    : never;\n\n/**\n * Determines whether a property needs an explicit mapping configuration.\n *\n * - Both are ObjectSchemaBuilder with registered mapping → `false` (auto-mappable)\n * - Both are ObjectSchemaBuilder without registered mapping → `true`\n * - Either is ObjectSchemaBuilder but the other is not → `true`\n * - Both are ArraySchemaBuilder with element schemas that have registered mapping → `false`\n * - Both are ArraySchemaBuilder with same InferType → `false`\n * - Array vs non-array → `true`\n * - Neither is ObjectSchemaBuilder + InferType<source> extends InferType<target>\n *   → `false` (same-name, compatible primitive types → auto-mappable)\n * - Neither is ObjectSchemaBuilder + incompatible InferType → `true`\n */\ntype NeedsMapping<TSourcePropSchema, TTargetPropSchema, TRegistered> =\n    TSourcePropSchema extends ArraySchemaBuilder<any, any, any>\n        ? TTargetPropSchema extends ArraySchemaBuilder<any, any, any>\n            ? NeedsMapping<\n                  ExtractArrayElementSchema<TSourcePropSchema>,\n                  ExtractArrayElementSchema<TTargetPropSchema>,\n                  TRegistered\n              >\n            : true\n        : TTargetPropSchema extends ArraySchemaBuilder<any, any, any>\n          ? true\n          : TSourcePropSchema extends ObjectSchemaBuilder<any, any, any>\n            ? TTargetPropSchema extends ObjectSchemaBuilder<any, any, any>\n                ? [TSourcePropSchema, TTargetPropSchema] extends TRegistered\n                    ? false\n                    : InferType<TSourcePropSchema> extends InferType<TTargetPropSchema>\n                      ? InferType<TTargetPropSchema> extends InferType<TSourcePropSchema>\n                          ? false\n                          : true\n                      : true\n                : true\n            : TTargetPropSchema extends ObjectSchemaBuilder<any, any, any>\n              ? true\n              : InferType<TSourcePropSchema> extends InferType<TTargetPropSchema>\n                ? false\n                : true;\n\n/**\n * From all keys of the target schema, filter down to only those that\n * require explicit mapping (i.e. `NeedsMapping` is `true`).\n * Keys where `NeedsMapping` is `false` can be auto-mapped via the registry.\n */\ntype KeysNeedingMapping<\n    TFromSchema extends ObjectSchemaBuilder<any, any, any>,\n    TToSchema extends ObjectSchemaBuilder<any, any, any>,\n    TRegistered\n> = {\n    [K in SchemaKeys<TToSchema>]: K extends SchemaKeys<TFromSchema>\n        ? NeedsMapping<\n              ExtractSchemaProperties<TFromSchema>[K],\n              ExtractSchemaProperties<TToSchema>[K],\n              TRegistered\n          > extends true\n            ? K\n            : never\n        : K;\n}[SchemaKeys<TToSchema>];\n\n/**\n * Checks whether two property schemas are compatible, considering\n * registered mappings. Mirrors {@link NeedsMapping}'s structure:\n * receives schemas as direct type parameters, uses\n * {@link ExtractArrayElementSchema} for arrays, and checks registration\n * via tuple-extends-union (not inline `infer`).\n */\ntype CheckSchemaCompatible<TSourceSchema, TTargetSchema, TRegistered> =\n    // Direct InferType match → compatible\n    [InferType<TSourceSchema>] extends [InferType<TTargetSchema>]\n        ? true\n        : // Both arrays → recurse into element schemas\n          TSourceSchema extends ArraySchemaBuilder<any, any, any>\n          ? TTargetSchema extends ArraySchemaBuilder<any, any, any>\n              ? CheckSchemaCompatible<\n                    ExtractArrayElementSchema<TSourceSchema>,\n                    ExtractArrayElementSchema<TTargetSchema>,\n                    TRegistered\n                >\n              : false\n          : // Both objects → check registration\n            TSourceSchema extends ObjectSchemaBuilder<any, any, any>\n            ? TTargetSchema extends ObjectSchemaBuilder<any, any, any>\n                ? [TSourceSchema, TTargetSchema] extends TRegistered\n                    ? true\n                    : false\n                : false\n            : false;\n\n/**\n * Checks whether the source property selected by `from()` is compatible\n * with the target property, evaluated *after* `TReturn` has been inferred.\n *\n * This decouples inference from validation: the `TReturn` constraint uses\n * `any` for setValue/getValue value types so TypeScript always infers\n * successfully, and this type performs the actual compatibility check\n * in the `_args` conditional spread.\n */\ntype IsFromCompatible<\n    TReturn,\n    TToSchema extends ObjectSchemaBuilder<any, any, any>,\n    TKey extends string,\n    TRegistered\n> = [ExtractPropertySchema<TReturn>] extends [never]\n    ? false\n    : CheckSchemaCompatible<\n          ExtractPropertySchema<TReturn>,\n          TargetPropertySchema<TToSchema, TKey>,\n          TRegistered\n      >;\n\n// ── Mapper Result Type ────────────────────────────────────────────────\n\nexport type SchemaToSchemaMapperResult<\n    TFromSchema extends ObjectSchemaBuilder<any, any, any>,\n    TToSchema extends ObjectSchemaBuilder<any, any, any>\n> = (from: InferType<TFromSchema>) => Promise<InferType<TToSchema>>;\n\n// ── Error Class ───────────────────────────────────────────────────────\n\nexport class MapperConfigurationError extends Error {\n    constructor(messageOrUnmappedProperties: string | string[]) {\n        super(\n            typeof messageOrUnmappedProperties === 'string'\n                ? messageOrUnmappedProperties\n                : `Mapper configuration error: the following target properties are not mapped and not ignored: ${messageOrUnmappedProperties.join(', ')}`\n        );\n        this.name = 'MapperConfigurationError';\n    }\n}\n\n// ── Internal Mapping Entry ────────────────────────────────────────────\n\ntype MappingEntry = {\n    type: 'prop' | 'custom' | 'ignore' | 'auto' | 'autoArray';\n    sourceDescriptorInner?: ReturnType<\n        PropertyDescriptor<\n            any,\n            any,\n            any\n        >[typeof SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]['getValue']\n    > extends any\n        ? any\n        : never;\n    fn?: (obj: any) => any;\n    autoMapper?: SchemaToSchemaMapperResult<any, any>;\n    elementMapper?: (element: any) => Promise<any>;\n};\n\n// ── Array Element Mapper Resolution ───────────────────────────────────\n\n/**\n * Resolves an element mapper for array properties.\n * Handles ObjectSchemaBuilder elements (via registry) and\n * primitive elements (direct copy when types match).\n * Returns null if no valid element mapper can be resolved.\n */\nfunction resolveElementMapper(\n    sourceElementSchema: SchemaBuilder<any, any, any>,\n    targetElementSchema: SchemaBuilder<any, any, any>,\n    registry: MappingRegistry<any> | undefined\n): ((element: any) => Promise<any>) | null {\n    // Both element schemas are ObjectSchemaBuilder: look up registered mapper\n    if (\n        sourceElementSchema instanceof ObjectSchemaBuilder &&\n        targetElementSchema instanceof ObjectSchemaBuilder\n    ) {\n        if (registry) {\n            const fromSchemaMappers =\n                registry['_mappers'].get(sourceElementSchema);\n            const autoMapper = fromSchemaMappers?.get(targetElementSchema);\n            if (autoMapper) {\n                return autoMapper as (element: any) => Promise<any>;\n            }\n        }\n        // Same inferred structure: copy directly\n        const fromKeys = Object.keys(\n            sourceElementSchema.introspect().properties || {}\n        ).sort();\n        const toKeys = Object.keys(\n            targetElementSchema.introspect().properties || {}\n        ).sort();\n        if (\n            fromKeys.length === toKeys.length &&\n            fromKeys.every((k, i) => k === toKeys[i])\n        ) {\n            return async (element: any) => element;\n        }\n        return null;\n    }\n\n    // Both element schemas are ArraySchemaBuilder: recursive element mapping\n    if (\n        sourceElementSchema instanceof ArraySchemaBuilder &&\n        targetElementSchema instanceof ArraySchemaBuilder\n    ) {\n        const innerSourceElement =\n            sourceElementSchema.introspect().elementSchema;\n        const innerTargetElement =\n            targetElementSchema.introspect().elementSchema;\n        if (innerSourceElement && innerTargetElement) {\n            const innerMapper = resolveElementMapper(\n                innerSourceElement,\n                innerTargetElement,\n                registry\n            );\n            if (innerMapper) {\n                return async (arr: any) => {\n                    if (arr == null) return undefined;\n                    if (!Array.isArray(arr)) return arr;\n                    return Promise.all(arr.map(innerMapper));\n                };\n            }\n        }\n        return null;\n    }\n\n    // Neither is ObjectSchemaBuilder nor ArraySchemaBuilder:\n    // treat as primitive-compatible only when element schema types match.\n    if (\n        !(sourceElementSchema instanceof ObjectSchemaBuilder) &&\n        !(targetElementSchema instanceof ObjectSchemaBuilder) &&\n        !(sourceElementSchema instanceof ArraySchemaBuilder) &&\n        !(targetElementSchema instanceof ArraySchemaBuilder)\n    ) {\n        const sourceIntrospection =\n            typeof (sourceElementSchema as any).introspect === 'function'\n                ? (sourceElementSchema as any).introspect()\n                : undefined;\n        const targetIntrospection =\n            typeof (targetElementSchema as any).introspect === 'function'\n                ? (targetElementSchema as any).introspect()\n                : undefined;\n\n        if (\n            !sourceIntrospection ||\n            !targetIntrospection ||\n            sourceIntrospection.type !== targetIntrospection.type\n        ) {\n            return null;\n        }\n        return async (element: any) => element;\n    }\n\n    return null;\n}\n\n// ── PropertyMappingBuilder ────────────────────────────────────────────\n\n/**\n * Intermediate builder returned by `for()`. Provides three strategies\n * to configure how the selected target property is populated:\n * - `from()` — copy from a source property\n * - `compute()` — compute from the entire source object\n * - `ignore()` — explicitly skip the property\n */\nexport class PropertyMappingBuilder<\n    TFromSchema extends ObjectSchemaBuilder<any, any, any>,\n    TToSchema extends ObjectSchemaBuilder<any, any, any>,\n    TKey extends string,\n    TUnmapped extends string,\n    TRegistered = never\n> {\n    private readonly _mapper: Mapper<TFromSchema, TToSchema, any, TRegistered>;\n    private readonly _targetKey: TKey;\n\n    /** @internal */\n    constructor(\n        mapper: Mapper<TFromSchema, TToSchema, any, TRegistered>,\n        targetKey: TKey\n    ) {\n        this._mapper = mapper;\n        this._targetKey = targetKey;\n    }\n\n    /**\n     * Maps the target property from a source property. The selector\n     * receives the source schema's PropertyDescriptorTree and supports\n     * nested paths (e.g. `(s) => s.address.city`).\n     *\n     * Type compatibility is enforced: only source properties whose\n     * inferred type is assignable to the target property type will\n     * appear in the selector callback.\n     *\n     * Under `strictFunctionTypes`, the `setValue` and `getValue` constraints\n     * provide bidirectional type checking:\n     * - `setValue` contravariance rejects source schemas with extra properties\n     * - `getValue` covariance rejects source schemas with missing properties\n     * - registered mappings widen the constraint via intersection\n     */\n    public from<\n        TReturn extends {\n            [SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]: {\n                getSchema(): SchemaBuilder<any, any, any>;\n                setValue: (obj: any, value: any) => any;\n                getValue: (obj: any) => {\n                    value?: any;\n                    success: boolean;\n                };\n            };\n        }\n    >(\n        selector: (\n            tree: PropertyDescriptorTree<\n                TFromSchema,\n                TFromSchema,\n                SchemaPropertyInferredType<TToSchema, TKey>\n            >\n        ) => TReturn,\n        ..._args: [TReturn] extends [never]\n            ? [\n                  error: `Property '${TKey}': source property type is not assignable to the target property type. Use compute() instead.`\n              ]\n            : IsFromCompatible<\n                    TReturn,\n                    TToSchema,\n                    TKey,\n                    TRegistered\n                > extends true\n              ? []\n              : [\n                    error: `Property '${TKey}': source property type is not assignable to the target property type. Use compute() instead.`\n                ]\n    ): Mapper<TFromSchema, TToSchema, Exclude<TUnmapped, TKey>, TRegistered> {\n        const sourceTree = ObjectSchemaBuilder.getPropertiesFor(\n            this._mapper['_fromSchema']\n        );\n        const sourceDescriptor = selector(sourceTree as any);\n        const inner = sourceDescriptor[SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR];\n\n        // Check if both source and target property schemas are ObjectSchemaBuilder;\n        // if so, look up the registered mapper and use it at runtime.\n        const sourceSchema = inner.getSchema();\n        const toProperties = (this._mapper['_toSchema'].introspect()\n            .properties || {}) as Record<string, any>;\n        const targetPropSchema = toProperties[this._targetKey];\n\n        if (\n            sourceSchema instanceof ObjectSchemaBuilder &&\n            targetPropSchema instanceof ObjectSchemaBuilder &&\n            this._mapper['_registry']\n        ) {\n            const fromSchemaMappers =\n                this._mapper['_registry']['_mappers'].get(sourceSchema);\n            const autoMapper = fromSchemaMappers?.get(targetPropSchema);\n            if (autoMapper) {\n                this._mapper['_mappings'].set(this._targetKey, {\n                    type: 'auto',\n                    sourceDescriptorInner: inner,\n                    autoMapper\n                });\n                return this._mapper as any;\n            }\n        }\n\n        // Check if both source and target are ArraySchemaBuilder;\n        // if so, resolve the element mapper and use element-wise mapping.\n        if (\n            sourceSchema instanceof ArraySchemaBuilder &&\n            targetPropSchema instanceof ArraySchemaBuilder\n        ) {\n            const sourceElementSchema = (\n                sourceSchema as ArraySchemaBuilder<any, any, any>\n            ).introspect().elementSchema;\n            const targetElementSchema = (\n                targetPropSchema as ArraySchemaBuilder<any, any, any>\n            ).introspect().elementSchema;\n\n            if (sourceElementSchema && targetElementSchema) {\n                const elementMapper = resolveElementMapper(\n                    sourceElementSchema,\n                    targetElementSchema,\n                    this._mapper['_registry']\n                );\n                if (elementMapper) {\n                    this._mapper['_mappings'].set(this._targetKey, {\n                        type: 'autoArray',\n                        sourceDescriptorInner: inner,\n                        elementMapper\n                    });\n                    return this._mapper as any;\n                }\n            }\n        }\n\n        this._mapper['_mappings'].set(this._targetKey, {\n            type: 'prop',\n            sourceDescriptorInner: inner\n        });\n\n        return this._mapper as any;\n    }\n\n    /**\n     * Computes the target property value from the entire source object.\n     * Supports both sync and async functions.\n     */\n    public compute(\n        fn:\n            | ((\n                  obj: InferType<TFromSchema>\n              ) => SchemaPropertyInferredType<TToSchema, TKey>)\n            | ((\n                  obj: InferType<TFromSchema>\n              ) => Promise<SchemaPropertyInferredType<TToSchema, TKey>>)\n    ): Mapper<TFromSchema, TToSchema, Exclude<TUnmapped, TKey>, TRegistered> {\n        this._mapper['_mappings'].set(this._targetKey, {\n            type: 'custom',\n            fn: fn as any\n        });\n\n        return this._mapper as any;\n    }\n\n    /**\n     * Explicitly excludes the target property from mapping.\n     * The property will not appear in the output object.\n     */\n    public ignore(): Mapper<\n        TFromSchema,\n        TToSchema,\n        Exclude<TUnmapped, TKey>,\n        TRegistered\n    > {\n        this._mapper['_mappings'].set(this._targetKey, {\n            type: 'ignore'\n        });\n\n        return this._mapper as any;\n    }\n}\n\n// ── Mapper ────────────────────────────────────────────────────────────\n\n/**\n * A fluent builder for configuring how each target property is populated\n * from a source schema. Uses PropertyDescriptors as pointers to properties\n * (similar to expressions in C# .NET).\n *\n * The `TUnmapped` type parameter tracks which target properties have not\n * yet been mapped or ignored. `getMapper()` is only callable (without\n * arguments) when `TUnmapped` is `never` — i.e. all properties have been\n * accounted for. If any property is missing, TypeScript will produce a\n * compile-time type error (a type-assignability mismatch that includes\n * the unmapped property names in its type parameters).\n *\n * @typeParam TFromSchema - source ObjectSchemaBuilder\n * @typeParam TToSchema - target ObjectSchemaBuilder\n * @typeParam TUnmapped - union of target property key names not yet mapped\n */\nexport class Mapper<\n    TFromSchema extends ObjectSchemaBuilder<any, any, any>,\n    TToSchema extends ObjectSchemaBuilder<any, any, any>,\n    TUnmapped extends string = SchemaKeys<TToSchema>,\n    TRegistered = never\n> {\n    /** Phantom property for structural type-checking of TUnmapped. */\n    declare readonly [SYMBOL_UNMAPPED]: TUnmapped;\n\n    private readonly _fromSchema: TFromSchema;\n    private readonly _toSchema: TToSchema;\n    private readonly _registry: MappingRegistry<any> | undefined;\n    private readonly _mappings: Map<string, MappingEntry> = new Map();\n\n    /**\n     * Creates a new instance of the Mapper class.\n     * @param fromSchema - `object` schema to map from\n     * @param toSchema - `object` schema to map to\n     * @param registry - optional MappingRegistry to auto-register the mapper\n     */\n    public constructor(\n        fromSchema: TFromSchema,\n        toSchema: TToSchema,\n        registry?: MappingRegistry<any>\n    ) {\n        this._fromSchema = fromSchema;\n        this._toSchema = toSchema;\n        this._registry = registry;\n    }\n\n    /**\n     * Selects a target property to configure. The selector callback\n     * receives a tree of all target properties. Navigate by\n     * property name: `(t) => t.cityName`.\n     *\n     * Auto-mappable properties (same name and compatible type, or\n     * ObjectSchemaBuilder with a registered mapping) are also available\n     * for explicit override.\n     */\n    public for<TKey extends SchemaKeys<TToSchema>>(\n        selector: (\n            tree: TargetPropertyTree<TToSchema, SchemaKeys<TToSchema>>\n        ) => TargetPropertyKey<TKey>\n    ): PropertyMappingBuilder<\n        TFromSchema,\n        TToSchema,\n        TKey,\n        TUnmapped,\n        TRegistered\n    > {\n        // At runtime, use a Proxy to detect which property was accessed\n        let capturedKey: string | undefined;\n        const proxy = new Proxy({} as any, {\n            get(_target, prop) {\n                if (typeof prop === 'string') {\n                    capturedKey = prop;\n                }\n                return { [SYMBOL_TARGET_PROPERTY_KEY]: prop };\n            }\n        });\n\n        selector(proxy);\n\n        if (!capturedKey) {\n            throw new Error(\n                'for selector must access a property on the target tree'\n            );\n        }\n\n        // Validate that the captured key exists in the target schema\n        const toIntrospection = this._toSchema.introspect();\n        const targetProperties = toIntrospection.properties\n            ? Object.keys(toIntrospection.properties)\n            : [];\n        if (!targetProperties.includes(capturedKey)) {\n            throw new MapperConfigurationError(\n                `Property \"${capturedKey}\" does not exist in the target schema`\n            );\n        }\n\n        return new PropertyMappingBuilder(this, capturedKey as TKey);\n    }\n\n    /**\n     * Returns the configured async mapping function.\n     *\n     * **Compile-time safety:** This method is only callable without\n     * arguments when all target properties have been mapped or explicitly\n     * ignored. If any property is unmapped, TypeScript will require\n     * a string argument describing the unmapped properties, producing\n     * a clear compile-time error.\n     *\n     * **Runtime safety:** Even if TypeScript checks are bypassed (e.g.\n     * via `as any`), a `MapperConfigurationError` is thrown at runtime\n     * listing the unmapped properties.\n     */\n    public getMapper(\n        ..._args: [TUnmapped] extends [never]\n            ? []\n            : [error: `Unmapped properties: ${TUnmapped}`]\n    ): SchemaToSchemaMapperResult<TFromSchema, TToSchema> {\n        // Runtime validation: ensure all target properties are covered\n        const toIntrospection = this._toSchema.introspect();\n        const targetProperties = toIntrospection.properties\n            ? Object.keys(toIntrospection.properties)\n            : [];\n\n        // Auto-mapping: fill in unmapped properties using registered nested mappers\n        if (this._registry) {\n            const fromIntrospection = this._fromSchema.introspect();\n            const fromProperties = (fromIntrospection.properties ||\n                {}) as Record<string, any>;\n            const toProperties = (toIntrospection.properties || {}) as Record<\n                string,\n                any\n            >;\n            const fromTree = ObjectSchemaBuilder.getPropertiesFor(\n                this._fromSchema\n            );\n\n            for (const key of targetProperties) {\n                if (this._mappings.has(key)) continue;\n\n                const fromPropSchema = fromProperties[key];\n                const toPropSchema = toProperties[key];\n\n                if (!fromPropSchema || !toPropSchema) continue;\n\n                const sourceDescriptor = (fromTree as any)[key];\n                if (!sourceDescriptor?.[SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR])\n                    continue;\n\n                // ObjectSchemaBuilder → ObjectSchemaBuilder: use registered mapper\n                if (\n                    fromPropSchema instanceof ObjectSchemaBuilder &&\n                    toPropSchema instanceof ObjectSchemaBuilder\n                ) {\n                    const fromSchemaMappers =\n                        this._registry['_mappers'].get(fromPropSchema);\n                    const autoMapper = fromSchemaMappers?.get(toPropSchema);\n                    if (autoMapper) {\n                        this._mappings.set(key, {\n                            type: 'auto',\n                            sourceDescriptorInner:\n                                sourceDescriptor[\n                                    SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n                                ],\n                            autoMapper\n                        });\n                        continue;\n                    }\n\n                    // Same-name ObjectSchemaBuilder with identical property keys:\n                    // copy directly (full type safety ensured at compile time\n                    // via bidirectional InferType check)\n                    const fromKeys = Object.keys(\n                        fromPropSchema.introspect().properties || {}\n                    ).sort();\n                    const toKeys = Object.keys(\n                        toPropSchema.introspect().properties || {}\n                    ).sort();\n                    if (\n                        fromKeys.length === toKeys.length &&\n                        fromKeys.every((k, i) => k === toKeys[i])\n                    ) {\n                        this._mappings.set(key, {\n                            type: 'prop',\n                            sourceDescriptorInner:\n                                sourceDescriptor[\n                                    SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n                                ]\n                        });\n                    }\n                    continue;\n                }\n\n                // Primitive → Primitive: auto-map same-name props\n                // (type compatibility is ensured at the type level by\n                // KeysNeedingMapping / NeedsMapping)\n                if (\n                    !(fromPropSchema instanceof ObjectSchemaBuilder) &&\n                    !(toPropSchema instanceof ObjectSchemaBuilder) &&\n                    !(fromPropSchema instanceof ArraySchemaBuilder) &&\n                    !(toPropSchema instanceof ArraySchemaBuilder)\n                ) {\n                    this._mappings.set(key, {\n                        type: 'prop',\n                        sourceDescriptorInner:\n                            sourceDescriptor[SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]\n                    });\n                    continue;\n                }\n\n                // ArraySchemaBuilder → ArraySchemaBuilder: use element mapper\n                if (\n                    fromPropSchema instanceof ArraySchemaBuilder &&\n                    toPropSchema instanceof ArraySchemaBuilder\n                ) {\n                    const sourceElementSchema =\n                        fromPropSchema.introspect().elementSchema;\n                    const targetElementSchema =\n                        toPropSchema.introspect().elementSchema;\n                    if (sourceElementSchema && targetElementSchema) {\n                        const elementMapper = resolveElementMapper(\n                            sourceElementSchema,\n                            targetElementSchema,\n                            this._registry\n                        );\n                        if (elementMapper) {\n                            this._mappings.set(key, {\n                                type: 'autoArray',\n                                sourceDescriptorInner:\n                                    sourceDescriptor[\n                                        SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n                                    ],\n                                elementMapper\n                            });\n                        }\n                    }\n                }\n            }\n        }\n\n        const unmapped = targetProperties.filter(\n            key => !this._mappings.has(key)\n        );\n\n        if (unmapped.length > 0) {\n            throw new MapperConfigurationError(unmapped);\n        }\n\n        const targetTree = ObjectSchemaBuilder.getPropertiesFor(this._toSchema);\n\n        const mappings = new Map(this._mappings);\n\n        const mapperFn = async (\n            source: InferType<TFromSchema>\n        ): Promise<InferType<TToSchema>> => {\n            const result = {} as any;\n\n            for (const [key, entry] of mappings) {\n                if (entry.type === 'ignore') {\n                    continue;\n                }\n\n                let value: any;\n\n                if (entry.type === 'prop') {\n                    const getResult =\n                        entry.sourceDescriptorInner.getValue(source);\n                    if (getResult.success) {\n                        value = getResult.value;\n                    } else {\n                        continue;\n                    }\n                } else if (entry.type === 'custom') {\n                    value = await entry.fn!(source);\n                } else if (entry.type === 'auto') {\n                    const getResult =\n                        entry.sourceDescriptorInner.getValue(source);\n                    if (getResult.success && getResult.value !== undefined) {\n                        value = await entry.autoMapper!(getResult.value);\n                    } else {\n                        continue;\n                    }\n                } else if (entry.type === 'autoArray') {\n                    const getResult =\n                        entry.sourceDescriptorInner.getValue(source);\n                    // null/undefined → skip (spec §6); non-array → error\n                    if (getResult.success && getResult.value != null) {\n                        if (!Array.isArray(getResult.value)) {\n                            throw new MapperConfigurationError(\n                                `Expected array for property \"${key}\" but got ${typeof getResult.value}`\n                            );\n                        }\n                        value = await Promise.all(\n                            getResult.value.map(entry.elementMapper!)\n                        );\n                    } else {\n                        continue;\n                    }\n                }\n\n                const targetDescriptor = (targetTree as any)[key];\n                if (targetDescriptor?.[SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]) {\n                    targetDescriptor[\n                        SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n                    ].setValue(result, value, {\n                        createMissingStructure: true\n                    });\n                } else {\n                    result[key] = value;\n                }\n            }\n\n            return result;\n        };\n\n        // Auto-register in the registry if available\n        if (this._registry) {\n            this._registry['_mappers']\n                .get(this._fromSchema)\n                ?.set(this._toSchema, mapperFn);\n        }\n\n        return mapperFn;\n    }\n}\n\n// ── MappingRegistry ───────────────────────────────────────────────────\n\nexport class MappingRegistry<TRegistered = never> {\n    protected readonly _mappers: Map<\n        ObjectSchemaBuilder<any, any, any>,\n        Map<\n            ObjectSchemaBuilder<any, any, any>,\n            SchemaToSchemaMapperResult<any, any>\n        >\n    > = new Map();\n\n    #ensureObjectSchemas(\n        fromSchema: ObjectSchemaBuilder<any, any, any>,\n        toSchema: ObjectSchemaBuilder<any, any, any>\n    ): boolean {\n        return !(\n            !fromSchema ||\n            !toSchema ||\n            fromSchema instanceof ObjectSchemaBuilder === false ||\n            toSchema instanceof ObjectSchemaBuilder === false\n        );\n    }\n\n    /**\n     * Defines a mapping between two schemas and returns a new immutable\n     * registry containing the mapping. The callback `fn` receives a fresh\n     * `Mapper` and must return it after configuring property mappings.\n     * The mapper is automatically finalized and registered. Properties\n     * not explicitly mapped or ignored may be auto-mapped if a matching\n     * nested mapping is already registered in the registry.\n     *\n     * @param fromSchema - source ObjectSchemaBuilder\n     * @param toSchema - target ObjectSchemaBuilder\n     * @param fn - callback that configures property mappings on the mapper\n     * @returns a new MappingRegistry containing all previous mappings plus\n     *          the newly configured one\n     * @throws if schemas are invalid, mapping is duplicate, or unmapped\n     *         properties remain that cannot be auto-mapped\n     */\n    public configure<\n        TFromSchema extends ObjectSchemaBuilder<any, any, any>,\n        TToSchema extends ObjectSchemaBuilder<any, any, any>\n    >(\n        fromSchema: TFromSchema,\n        toSchema: TToSchema,\n        fn: (\n            mapper: Mapper<\n                TFromSchema,\n                TToSchema,\n                KeysNeedingMapping<TFromSchema, TToSchema, TRegistered>,\n                TRegistered\n            >\n        ) => Mapper<TFromSchema, TToSchema, never, TRegistered>\n    ): MappingRegistry<TRegistered | [TFromSchema, TToSchema]> {\n        if (!this.#ensureObjectSchemas(fromSchema, toSchema)) {\n            throw new Error(\n                'Both fromSchema and toSchema must be instances of ObjectSchemaBuilder'\n            );\n        }\n\n        // Check for duplicate mappings\n        const existingFromMappers = this._mappers.get(fromSchema);\n        if (existingFromMappers?.has(toSchema)) {\n            throw new Error(\n                'Duplicate mapping: a mapping for this schemas pair is already registered'\n            );\n        }\n\n        // Create new immutable registry with cloned mappings\n        const newRegistry = new MappingRegistry<\n            TRegistered | [TFromSchema, TToSchema]\n        >();\n        for (const [from, toMap] of this._mappers) {\n            newRegistry._mappers.set(from, new Map(toMap));\n        }\n\n        // Ensure the from→to map slot exists so getMapper can register\n        if (!newRegistry._mappers.has(fromSchema)) {\n            newRegistry._mappers.set(fromSchema, new Map());\n        }\n\n        // Create mapper with new registry reference\n        const mapper = new Mapper<\n            TFromSchema,\n            TToSchema,\n            KeysNeedingMapping<TFromSchema, TToSchema, TRegistered>,\n            TRegistered\n        >(fromSchema, toSchema, newRegistry);\n\n        // Configure via user callback\n        const configuredMapper = fn(mapper);\n\n        // Implicit finalization: auto-map + validate + register\n        (\n            configuredMapper as Mapper<\n                TFromSchema,\n                TToSchema,\n                never,\n                TRegistered\n            >\n        ).getMapper();\n\n        return newRegistry;\n    }\n\n    /**\n     * Gets a mapper function that will map from the fromSchema to the toSchema.\n     * Throws an error if no mapper is found for the given schemas pair.\n     * @param fromSchema a schema to map from\n     * @param toSchema a schema to map to\n     * @returns a function that will take a value of the fromSchema type as an argument and\n     * return a promise resolving to a value of the toSchema type\n     */\n    public getMapper<\n        TFromSchema extends ObjectSchemaBuilder<any, any, any>,\n        TToSchema extends ObjectSchemaBuilder<any, any, any>\n    >(\n        fromSchema: TFromSchema,\n        toSchema: TToSchema\n    ): SchemaToSchemaMapperResult<TFromSchema, TToSchema> {\n        if (!this.#ensureObjectSchemas(fromSchema, toSchema)) {\n            throw new Error(\n                'Both fromSchema and toSchema must be instances of ObjectSchemaBuilder'\n            );\n        }\n\n        const mappers = this._mappers.get(fromSchema);\n        if (!mappers) {\n            throw new Error('No mapper found for the given schemas pair');\n        }\n        const mapper = mappers.get(toSchema);\n        if (!mapper) {\n            throw new Error('No mapper found for the given schemas pair');\n        }\n\n        return mapper;\n    }\n}\n\n/**\n * Creates a new empty {@link MappingRegistry}.\n *\n * This is a convenience factory function — an alternative to\n * `new MappingRegistry()` that reads better in a fluent chain:\n *\n * ```ts\n * const registry = mapper()\n *   .configure(A, B, m => ...)\n *   .configure(C, D, m => ...);\n * ```\n */\nexport function mapper(): MappingRegistry {\n    return new MappingRegistry();\n}\n"],"mappings":"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","names":["ArraySchemaBuilder","ObjectSchemaBuilder","SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR","SYMBOL_TARGET_PROPERTY_KEY","MapperConfigurationError","messageOrUnmappedProperties","resolveElementMapper","sourceElementSchema","targetElementSchema","registry","ObjectSchemaBuilder","autoMapper","fromKeys","toKeys","k","i","element","ArraySchemaBuilder","innerSourceElement","innerTargetElement","innerMapper","arr","sourceIntrospection","targetIntrospection","PropertyMappingBuilder","mapper","targetKey","selector","_args","sourceTree","inner","SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR","sourceSchema","targetPropSchema","elementMapper","fn","Mapper","fromSchema","toSchema","capturedKey","proxy","_target","prop","SYMBOL_TARGET_PROPERTY_KEY","toIntrospection","targetProperties","fromProperties","toProperties","fromTree","key","fromPropSchema","toPropSchema","sourceDescriptor","unmapped","targetTree","mappings","mapperFn","source","result","entry","value","getResult","targetDescriptor","MappingRegistry","_MappingRegistry","#ensureObjectSchemas","newRegistry","from","toMap","mappers"]}
+{"version":3,"sources":["../src/MappingRegistry.ts"],"sourcesContent":["import {\n    ArraySchemaBuilder,\n    type InferType,\n    ObjectSchemaBuilder,\n    type PropertyDescriptor,\n    type PropertyDescriptorTree,\n    type SchemaBuilder,\n    SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n} from '@cleverbrush/schema';\n\n/**\n * Internal symbol used to brand target property descriptors with their key.\n * Using a symbol instead of a string property keeps it out of IntelliSense.\n */\nconst SYMBOL_TARGET_PROPERTY_KEY: unique symbol = Symbol('targetPropertyKey');\n\n/**\n * Internal symbol used as a phantom property key on Mapper to track\n * unmapped target properties. Using a symbol keeps it out of IntelliSense.\n */\nconst SYMBOL_UNMAPPED: unique symbol = Symbol('unmapped');\nconst SYMBOL_STEPS: unique symbol = Symbol('mappingSteps');\n\ntype Step<T, K extends string, Async extends boolean> = Omit<T, K> &\n    Record<K, Async>;\ntype IsAsync<T> = 0 extends 1 & T\n    ? true\n    : [Extract<T, PromiseLike<any>>] extends [never]\n      ? false\n      : true;\n// Inspect metadata instead of recursively comparing the entire fluent builder.\ntype ArraySchemaShape = { introspect(): { elementSchema: unknown } };\ntype ObjectSchemaShape = { introspect(): { properties: unknown } };\ntype SameProperties<A, B> = [keyof A, keyof B] extends [keyof B, keyof A]\n    ? [A, B] extends [B, A]\n        ? true\n        : false\n    : false;\n// Runtime registration still uses schema identity. At compile time compare the\n// declared fields, not every recursive builder/validation method. Exact key sets\n// prevent an empty or smaller schema from matching an unrelated registration.\ntype RegisteredMatch<S, T, Registered> = S extends ObjectSchemaShape\n    ? T extends ObjectSchemaShape\n        ? Registered extends [infer From, infer To]\n            ? [InferType<S>, InferType<T>] extends [\n                  InferType<From>,\n                  InferType<To>\n              ]\n                ? [InferType<From>, InferType<To>] extends [\n                      InferType<S>,\n                      InferType<T>\n                  ]\n                    ? SameProperties<\n                          ExtractSchemaProperties<S>,\n                          ExtractSchemaProperties<From>\n                      > extends true\n                        ? SameProperties<\n                              ExtractSchemaProperties<T>,\n                              ExtractSchemaProperties<To>\n                          >\n                        : false\n                    : false\n                : false\n            : false\n        : false\n    : false;\ntype NestedAsync<S, T, Registered> = S extends ArraySchemaShape\n    ? T extends ArraySchemaShape\n        ? NestedAsync<\n              ExtractArrayElementSchema<S>,\n              ExtractArrayElementSchema<T>,\n              Registered\n          >\n        : false\n    : true extends RegisteredMatch<S, T, Registered>\n      ? true\n      : false;\ntype AsyncKeys<S, T, Registered, Steps> = {\n    [K in keyof ExtractSchemaProperties<T> & string]: K extends keyof Steps\n        ? Steps[K] extends false\n            ? never\n            : K\n        : K extends keyof ExtractSchemaProperties<S>\n          ? NestedAsync<\n                ExtractSchemaProperties<S>[K],\n                ExtractSchemaProperties<T>[K],\n                Registered\n            > extends false\n              ? never\n              : K\n          : never;\n}[keyof ExtractSchemaProperties<T> & string];\n\n/** Compile-time diagnostics for incomplete or asynchronous mapping steps. */\ntype SyncMappingArguments<Unmapped extends string, Async> = [Unmapped] extends [\n    never\n]\n    ? [Async] extends [never]\n        ? []\n        : [error: 'Mapping contains asynchronous steps']\n    : [error: `Unmapped properties: ${Unmapped}`];\n\n/** Compile-time diagnostics for registered synchronous mapping pairs. */\ntype RegisteredSyncArguments<Pair, Registered, Async> = Pair extends Registered\n    ? Pair extends Async\n        ? [error: 'Mapping contains asynchronous steps']\n        : []\n    : [error: 'Mapping is not registered'];\n\nconst syncImplementations = new WeakMap<Function, (source: any) => any>();\n\nfunction assertSync(value: any, key: string): any {\n    if (value != null && typeof value.then === 'function') {\n        throw new MapperConfigurationError(\n            `Synchronous mapping returned a thenable for property \"${key}\"`\n        );\n    }\n    return value;\n}\n\nfunction synchronous(fn: Function): (source: any) => any {\n    const result = syncImplementations.get(fn);\n    if (!result)\n        throw new MapperConfigurationError(\n            'Mapping contains an asynchronous computation or nested mapper'\n        );\n    return result;\n}\n\n// ── Helper Types ──────────────────────────────────────────────────────\n\n/**\n * Extracts the properties record from an ObjectSchemaBuilder.\n */\ntype ExtractSchemaProperties<T> = T extends {\n    introspect(): { properties: infer TProperties };\n}\n    ? TProperties\n    : never;\n\n/**\n * Gets all top-level property key names of an ObjectSchemaBuilder.\n */\ntype SchemaKeys<T extends ObjectSchemaShape> =\n    keyof ExtractSchemaProperties<T> & string;\n\n/**\n * Branded phantom type that tags a property descriptor with its key name.\n * This allows TypeScript to infer which property was selected in the\n * `for` callback, enabling compile-time tracking of mapped vs unmapped\n * properties.\n */\ntype TargetPropertyKey<K extends string> = {\n    readonly [SYMBOL_TARGET_PROPERTY_KEY]: K;\n};\n\n/**\n * Creates a tree of selectable target properties, filtered to only show\n * properties whose keys are in `TAllowedKeys`. Each property is branded\n * with `TargetPropertyKey<K>` so the key can be inferred from the return\n * type of the selector callback.\n */\ntype TargetPropertyTree<\n    TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TAllowedKeys extends string\n> = {\n    // Filter source properties without detaching the target key's declaration.\n    -readonly [K in keyof ExtractSchemaProperties<TSchema> as K extends TAllowedKeys\n        ? K\n        : never]-?: TargetPropertyKey<K & string> &\n        PropertyDescriptor<TSchema, ExtractSchemaProperties<TSchema>[K], any>;\n};\n\n/**\n * Infers the TypeScript type of a specific property in an ObjectSchemaBuilder\n * by its key name.\n */\ntype SchemaPropertyInferredType<\n    TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    K extends string\n> = K extends keyof ExtractSchemaProperties<TSchema>\n    ? InferType<ExtractSchemaProperties<TSchema>[K]>\n    : never;\n\n/**\n * Extracts the schema (SchemaBuilder) of a specific property in an\n * ObjectSchemaBuilder by its key name.\n */\ntype TargetPropertySchema<\n    TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    K extends string\n> = K extends keyof ExtractSchemaProperties<TSchema>\n    ? ExtractSchemaProperties<TSchema>[K]\n    : never;\n\n/**\n * Extracts the element schema from an ArraySchemaBuilder.\n */\ntype ExtractArrayElementSchema<T> = T extends {\n    introspect(): { elementSchema: infer TElementSchema };\n}\n    ? NonNullable<TElementSchema>\n    : never;\n\n/**\n * Extracts the property schema from a PropertyDescriptor's `getSchema()`\n * return type. Used by {@link IsFromCompatible} to recover the source\n * property's schema from the inferred `TReturn` of the `from()` selector.\n */\ntype ExtractPropertySchema<T> = T extends {\n    [SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]: {\n        getSchema(): infer TSchema;\n    };\n}\n    ? TSchema\n    : never;\n\n/**\n * Determines whether a property needs an explicit mapping configuration.\n *\n * - Both are ObjectSchemaBuilder with registered mapping → `false` (auto-mappable)\n * - Both are ObjectSchemaBuilder without registered mapping → `true`\n * - Either is ObjectSchemaBuilder but the other is not → `true`\n * - Both are ArraySchemaBuilder with element schemas that have registered mapping → `false`\n * - Both are ArraySchemaBuilder with same InferType → `false`\n * - Array vs non-array → `true`\n * - Neither is ObjectSchemaBuilder + InferType<source> extends InferType<target>\n *   → `false` (same-name, compatible primitive types → auto-mappable)\n * - Neither is ObjectSchemaBuilder + incompatible InferType → `true`\n */\ntype NeedsMapping<TSourcePropSchema, TTargetPropSchema, TRegistered> =\n    TSourcePropSchema extends ArraySchemaShape\n        ? TTargetPropSchema extends ArraySchemaShape\n            ? NeedsMapping<\n                  ExtractArrayElementSchema<TSourcePropSchema>,\n                  ExtractArrayElementSchema<TTargetPropSchema>,\n                  TRegistered\n              >\n            : true\n        : TTargetPropSchema extends ArraySchemaShape\n          ? true\n          : TSourcePropSchema extends ObjectSchemaShape\n            ? TTargetPropSchema extends ObjectSchemaShape\n                ? true extends RegisteredMatch<\n                      TSourcePropSchema,\n                      TTargetPropSchema,\n                      TRegistered\n                  >\n                    ? false\n                    : InferType<TSourcePropSchema> extends InferType<TTargetPropSchema>\n                      ? InferType<TTargetPropSchema> extends InferType<TSourcePropSchema>\n                          ? false\n                          : true\n                      : true\n                : true\n            : TTargetPropSchema extends ObjectSchemaShape\n              ? true\n              : InferType<TSourcePropSchema> extends InferType<TTargetPropSchema>\n                ? false\n                : true;\n\n/**\n * From all keys of the target schema, filter down to only those that\n * require explicit mapping (i.e. `NeedsMapping` is `true`).\n * Keys where `NeedsMapping` is `false` can be auto-mapped via the registry.\n */\ntype KeysNeedingMapping<\n    TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TRegistered\n> = {\n    [K in SchemaKeys<TToSchema>]: K extends SchemaKeys<TFromSchema>\n        ? NeedsMapping<\n              ExtractSchemaProperties<TFromSchema>[K],\n              ExtractSchemaProperties<TToSchema>[K],\n              TRegistered\n          > extends true\n            ? K\n            : never\n        : K;\n}[SchemaKeys<TToSchema>];\n\n/**\n * Checks whether two property schemas are compatible, considering\n * registered mappings. Mirrors {@link NeedsMapping}'s structure:\n * receives schemas as direct type parameters, uses\n * {@link ExtractArrayElementSchema} for arrays, and checks registration\n * via tuple-extends-union (not inline `infer`).\n */\ntype CheckSchemaCompatible<TSourceSchema, TTargetSchema, TRegistered> =\n    // Direct InferType match → compatible\n    [InferType<TSourceSchema>] extends [InferType<TTargetSchema>]\n        ? true\n        : // Both arrays → recurse into element schemas\n          TSourceSchema extends ArraySchemaShape\n          ? TTargetSchema extends ArraySchemaShape\n              ? CheckSchemaCompatible<\n                    ExtractArrayElementSchema<TSourceSchema>,\n                    ExtractArrayElementSchema<TTargetSchema>,\n                    TRegistered\n                >\n              : false\n          : // Both objects → check registration\n            TSourceSchema extends ObjectSchemaShape\n            ? TTargetSchema extends ObjectSchemaShape\n                ? true extends RegisteredMatch<\n                      TSourceSchema,\n                      TTargetSchema,\n                      TRegistered\n                  >\n                    ? true\n                    : false\n                : false\n            : false;\n\n/**\n * Checks whether the source property selected by `from()` is compatible\n * with the target property, evaluated *after* `TReturn` has been inferred.\n *\n * This decouples inference from validation: the `TReturn` constraint uses\n * `any` for setValue/getValue value types so TypeScript always infers\n * successfully, and this type performs the actual compatibility check\n * in the `_args` conditional spread.\n */\ntype IsFromCompatible<\n    TReturn,\n    TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TKey extends string,\n    TRegistered\n> = [ExtractPropertySchema<TReturn>] extends [never]\n    ? false\n    : CheckSchemaCompatible<\n          ExtractPropertySchema<TReturn>,\n          TargetPropertySchema<TToSchema, TKey>,\n          TRegistered\n      >;\n\n// ── Mapper Result Type ────────────────────────────────────────────────\n\n/** A mapping function that always returns a Promise, including for pure mappings. */\nexport type SchemaToSchemaMapperResult<\n    TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>\n> = (from: InferType<TFromSchema>) => Promise<InferType<TToSchema>>;\n\n/** A complete synchronous mapping; unexpected thenables throw instead of leaking into DTOs. */\nexport type SyncSchemaToSchemaMapperResult<\n    TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>\n> = (from: InferType<TFromSchema>) => InferType<TToSchema>;\n\n// ── Error Class ───────────────────────────────────────────────────────\n\nexport class MapperConfigurationError extends Error {\n    constructor(messageOrUnmappedProperties: string | string[]) {\n        super(\n            typeof messageOrUnmappedProperties === 'string'\n                ? messageOrUnmappedProperties\n                : `Mapper configuration error: the following target properties are not mapped and not ignored: ${messageOrUnmappedProperties.join(', ')}`\n        );\n        this.name = 'MapperConfigurationError';\n    }\n}\n\n// ── Internal Mapping Entry ────────────────────────────────────────────\n\ntype MappingEntry = {\n    type: 'prop' | 'custom' | 'ignore' | 'auto' | 'autoArray';\n    sourceDescriptorInner?: ReturnType<\n        PropertyDescriptor<\n            any,\n            any,\n            any\n        >[typeof SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]['getValue']\n    > extends any\n        ? any\n        : never;\n    fn?: (obj: any) => any;\n    autoMapper?: SchemaToSchemaMapperResult<any, any>;\n    elementMapper?: (element: any) => Promise<any>;\n};\n\n// ── Array Element Mapper Resolution ───────────────────────────────────\n\n/**\n * Resolves an element mapper for array properties.\n * Handles ObjectSchemaBuilder elements (via registry) and\n * primitive elements (direct copy when types match).\n * Returns null if no valid element mapper can be resolved.\n */\nfunction resolveElementMapper(\n    sourceElementSchema: SchemaBuilder<any, any, any>,\n    targetElementSchema: SchemaBuilder<any, any, any>,\n    registry: MappingRegistry<any, any> | undefined\n): ((element: any) => Promise<any>) | null {\n    // Both element schemas are ObjectSchemaBuilder: look up registered mapper\n    if (\n        sourceElementSchema instanceof ObjectSchemaBuilder &&\n        targetElementSchema instanceof ObjectSchemaBuilder\n    ) {\n        if (registry) {\n            const fromSchemaMappers =\n                registry['_mappers'].get(sourceElementSchema);\n            const autoMapper = fromSchemaMappers?.get(targetElementSchema);\n            if (autoMapper) {\n                return autoMapper as (element: any) => Promise<any>;\n            }\n        }\n        // Same inferred structure: copy directly\n        const fromKeys = Object.keys(\n            sourceElementSchema.introspect().properties || {}\n        ).sort();\n        const toKeys = Object.keys(\n            targetElementSchema.introspect().properties || {}\n        ).sort();\n        if (\n            fromKeys.length === toKeys.length &&\n            fromKeys.every((k, i) => k === toKeys[i])\n        ) {\n            const copy = async (element: any) => element;\n            syncImplementations.set(copy, element => element);\n            return copy;\n        }\n        return null;\n    }\n\n    // Both element schemas are ArraySchemaBuilder: recursive element mapping\n    if (\n        sourceElementSchema instanceof ArraySchemaBuilder &&\n        targetElementSchema instanceof ArraySchemaBuilder\n    ) {\n        const innerSourceElement =\n            sourceElementSchema.introspect().elementSchema;\n        const innerTargetElement =\n            targetElementSchema.introspect().elementSchema;\n        if (innerSourceElement && innerTargetElement) {\n            const innerMapper = resolveElementMapper(\n                innerSourceElement,\n                innerTargetElement,\n                registry\n            );\n            if (innerMapper) {\n                const mapArray = async (arr: any) => {\n                    if (arr == null) return undefined;\n                    if (!Array.isArray(arr)) return arr;\n                    return Promise.all(arr.map(innerMapper));\n                };\n                const sync = syncImplementations.get(innerMapper);\n                if (sync)\n                    syncImplementations.set(mapArray, arr => {\n                        if (arr == null) return undefined;\n                        if (!Array.isArray(arr)) return arr;\n                        return arr.map(sync);\n                    });\n                return mapArray;\n            }\n        }\n        return null;\n    }\n\n    // Neither is ObjectSchemaBuilder nor ArraySchemaBuilder:\n    // treat as primitive-compatible only when element schema types match.\n    if (\n        !(sourceElementSchema instanceof ObjectSchemaBuilder) &&\n        !(targetElementSchema instanceof ObjectSchemaBuilder) &&\n        !(sourceElementSchema instanceof ArraySchemaBuilder) &&\n        !(targetElementSchema instanceof ArraySchemaBuilder)\n    ) {\n        const sourceIntrospection =\n            typeof (sourceElementSchema as any).introspect === 'function'\n                ? (sourceElementSchema as any).introspect()\n                : undefined;\n        const targetIntrospection =\n            typeof (targetElementSchema as any).introspect === 'function'\n                ? (targetElementSchema as any).introspect()\n                : undefined;\n\n        if (\n            !sourceIntrospection ||\n            !targetIntrospection ||\n            sourceIntrospection.type !== targetIntrospection.type\n        ) {\n            return null;\n        }\n        const copy = async (element: any) => element;\n        syncImplementations.set(copy, element => element);\n        return copy;\n    }\n\n    return null;\n}\n\n// ── PropertyMappingBuilder ────────────────────────────────────────────\n\n/**\n * Intermediate builder returned by `for()`. Provides three strategies\n * to configure how the selected target property is populated:\n * - `from()` — copy from a source property\n * - `compute()` — compute from the entire source object\n * - `ignore()` — explicitly skip the property\n */\nexport class PropertyMappingBuilder<\n    TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TKey extends string,\n    TUnmapped extends string,\n    TRegistered = never,\n    TAsyncRegistered = never,\n    TSteps = {}\n> {\n    private readonly _mapper: Mapper<\n        TFromSchema,\n        TToSchema,\n        any,\n        TRegistered,\n        TAsyncRegistered,\n        TSteps\n    >;\n    private readonly _targetKey: TKey;\n\n    /** @internal */\n    constructor(\n        mapper: Mapper<\n            TFromSchema,\n            TToSchema,\n            any,\n            TRegistered,\n            TAsyncRegistered,\n            TSteps\n        >,\n        targetKey: TKey\n    ) {\n        this._mapper = mapper;\n        this._targetKey = targetKey;\n    }\n\n    /**\n     * Maps the target property from a source property. The selector\n     * receives the source schema's PropertyDescriptorTree and supports\n     * nested paths (e.g. `(s) => s.address.city`).\n     *\n     * Type compatibility is enforced: only source properties whose\n     * inferred type is assignable to the target property type will\n     * appear in the selector callback.\n     *\n     * Under `strictFunctionTypes`, the `setValue` and `getValue` constraints\n     * provide bidirectional type checking:\n     * - `setValue` contravariance rejects source schemas with extra properties\n     * - `getValue` covariance rejects source schemas with missing properties\n     * - registered mappings widen the constraint via intersection\n     */\n    public from<\n        TReturn extends {\n            [SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]: {\n                getSchema(): SchemaBuilder<any, any, any>;\n                setValue: (obj: any, value: any) => any;\n                getValue: (obj: any) => {\n                    value?: any;\n                    success: boolean;\n                };\n            };\n        }\n    >(\n        selector: (\n            tree: PropertyDescriptorTree<TFromSchema, TFromSchema, any>\n        ) => TReturn,\n        ..._args: [TReturn] extends [never]\n            ? [\n                  error: `Property '${TKey}': source property type is not assignable to the target property type. Use compute() instead.`\n              ]\n            : IsFromCompatible<\n                    TReturn,\n                    TToSchema,\n                    TKey,\n                    TRegistered\n                > extends true\n              ? []\n              : [\n                    error: `Property '${TKey}': source property type is not assignable to the target property type. Use compute() instead.`\n                ]\n    ): Mapper<\n        TFromSchema,\n        TToSchema,\n        Exclude<TUnmapped, TKey>,\n        TRegistered,\n        TAsyncRegistered,\n        Step<\n            TSteps,\n            TKey,\n            NestedAsync<\n                ExtractPropertySchema<TReturn>,\n                TargetPropertySchema<TToSchema, TKey>,\n                TAsyncRegistered\n            >\n        >\n    > {\n        const sourceTree = ObjectSchemaBuilder.getPropertiesFor(\n            this._mapper['_fromSchema']\n        );\n        const sourceDescriptor = selector(sourceTree as any);\n        const inner = sourceDescriptor[SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR];\n\n        // Check if both source and target property schemas are ObjectSchemaBuilder;\n        // if so, look up the registered mapper and use it at runtime.\n        const sourceSchema = inner.getSchema();\n        const toProperties = (this._mapper['_toSchema'].introspect()\n            .properties || {}) as Record<string, any>;\n        const targetPropSchema = toProperties[this._targetKey];\n\n        if (\n            sourceSchema instanceof ObjectSchemaBuilder &&\n            targetPropSchema instanceof ObjectSchemaBuilder &&\n            this._mapper['_registry']\n        ) {\n            const fromSchemaMappers =\n                this._mapper['_registry']['_mappers'].get(sourceSchema);\n            const autoMapper = fromSchemaMappers?.get(targetPropSchema);\n            if (autoMapper) {\n                this._mapper['_mappings'].set(this._targetKey, {\n                    type: 'auto',\n                    sourceDescriptorInner: inner,\n                    autoMapper\n                });\n                return this._mapper as any;\n            }\n        }\n\n        // Check if both source and target are ArraySchemaBuilder;\n        // if so, resolve the element mapper and use element-wise mapping.\n        if (\n            sourceSchema instanceof ArraySchemaBuilder &&\n            targetPropSchema instanceof ArraySchemaBuilder\n        ) {\n            const sourceElementSchema = (\n                sourceSchema as ArraySchemaBuilder<\n                    any,\n                    any,\n                    any,\n                    any,\n                    any,\n                    any,\n                    any\n                >\n            ).introspect().elementSchema;\n            const targetElementSchema = (\n                targetPropSchema as ArraySchemaBuilder<\n                    any,\n                    any,\n                    any,\n                    any,\n                    any,\n                    any,\n                    any\n                >\n            ).introspect().elementSchema;\n\n            if (sourceElementSchema && targetElementSchema) {\n                const elementMapper = resolveElementMapper(\n                    sourceElementSchema,\n                    targetElementSchema,\n                    this._mapper['_registry']\n                );\n                if (elementMapper) {\n                    this._mapper['_mappings'].set(this._targetKey, {\n                        type: 'autoArray',\n                        sourceDescriptorInner: inner,\n                        elementMapper\n                    });\n                    return this._mapper as any;\n                }\n            }\n        }\n\n        this._mapper['_mappings'].set(this._targetKey, {\n            type: 'prop',\n            sourceDescriptorInner: inner\n        });\n\n        return this._mapper as any;\n    }\n\n    /**\n     * Computes the target property value from the entire source object.\n     * Supports both sync and async functions.\n     */\n    public compute<\n        TResult extends\n            | SchemaPropertyInferredType<TToSchema, TKey>\n            | Promise<SchemaPropertyInferredType<TToSchema, TKey>>\n    >(\n        fn: (obj: InferType<TFromSchema>) => TResult\n    ): Mapper<\n        TFromSchema,\n        TToSchema,\n        Exclude<TUnmapped, TKey>,\n        TRegistered,\n        TAsyncRegistered,\n        Step<TSteps, TKey, IsAsync<TResult>>\n    > {\n        this._mapper['_mappings'].set(this._targetKey, {\n            type: 'custom',\n            fn: fn as any\n        });\n\n        return this._mapper as any;\n    }\n\n    /**\n     * Explicitly excludes the target property from mapping.\n     * The property will not appear in the output object.\n     */\n    public ignore(): Mapper<\n        TFromSchema,\n        TToSchema,\n        Exclude<TUnmapped, TKey>,\n        TRegistered,\n        TAsyncRegistered,\n        Step<TSteps, TKey, false>\n    > {\n        this._mapper['_mappings'].set(this._targetKey, {\n            type: 'ignore'\n        });\n\n        return this._mapper as any;\n    }\n}\n\n// ── Mapper ────────────────────────────────────────────────────────────\n\n/**\n * A fluent builder for configuring how each target property is populated\n * from a source schema. Uses PropertyDescriptors as pointers to properties\n * (similar to expressions in C# .NET).\n *\n * The `TUnmapped` type parameter tracks which target properties have not\n * yet been mapped or ignored. `getMapper()` is only callable (without\n * arguments) when `TUnmapped` is `never` — i.e. all properties have been\n * accounted for. If any property is missing, TypeScript will produce a\n * compile-time type error (a type-assignability mismatch that includes\n * the unmapped property names in its type parameters).\n *\n * @typeParam TFromSchema - source ObjectSchemaBuilder\n * @typeParam TToSchema - target ObjectSchemaBuilder\n * @typeParam TUnmapped - union of target property key names not yet mapped\n */\nexport class Mapper<\n    TFromSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n    TUnmapped extends string = SchemaKeys<TToSchema>,\n    TRegistered = never,\n    TAsyncRegistered = never,\n    TSteps = {}\n> {\n    /** Phantom property for structural type-checking of TUnmapped. */\n    declare readonly [SYMBOL_UNMAPPED]: TUnmapped;\n    /** @internal Tracks final per-property computations without executing them. */\n    declare readonly [SYMBOL_STEPS]: TSteps;\n\n    private readonly _fromSchema: TFromSchema;\n    private readonly _toSchema: TToSchema;\n    private readonly _registry: MappingRegistry<any, any> | undefined;\n    private readonly _mappings: Map<string, MappingEntry> = new Map();\n\n    /**\n     * Creates a new instance of the Mapper class.\n     * @param fromSchema - `object` schema to map from\n     * @param toSchema - `object` schema to map to\n     * @param registry - optional MappingRegistry to auto-register the mapper\n     */\n    public constructor(\n        fromSchema: TFromSchema,\n        toSchema: TToSchema,\n        registry?: MappingRegistry<any, any>\n    ) {\n        this._fromSchema = fromSchema;\n        this._toSchema = toSchema;\n        this._registry = registry;\n    }\n\n    /**\n     * Selects a target property to configure. The selector callback\n     * receives a tree of all target properties. Navigate by\n     * property name: `(t) => t.cityName`.\n     *\n     * Auto-mappable properties (same name and compatible type, or\n     * ObjectSchemaBuilder with a registered mapping) are also available\n     * for explicit override.\n     */\n    public for<TKey extends SchemaKeys<TToSchema>>(\n        selector: (\n            tree: TargetPropertyTree<TToSchema, SchemaKeys<TToSchema>>\n        ) => TargetPropertyKey<TKey>\n    ): PropertyMappingBuilder<\n        TFromSchema,\n        TToSchema,\n        TKey,\n        TUnmapped,\n        TRegistered,\n        TAsyncRegistered,\n        TSteps\n    > {\n        // At runtime, use a Proxy to detect which property was accessed\n        let capturedKey: string | undefined;\n        const proxy = new Proxy({} as any, {\n            get(_target, prop) {\n                if (typeof prop === 'string') {\n                    capturedKey = prop;\n                }\n                return { [SYMBOL_TARGET_PROPERTY_KEY]: prop };\n            }\n        });\n\n        selector(proxy);\n\n        if (!capturedKey) {\n            throw new Error(\n                'for selector must access a property on the target tree'\n            );\n        }\n\n        // Validate that the captured key exists in the target schema\n        const toIntrospection = this._toSchema.introspect();\n        const targetProperties = toIntrospection.properties\n            ? Object.keys(toIntrospection.properties)\n            : [];\n        if (!targetProperties.includes(capturedKey)) {\n            throw new MapperConfigurationError(\n                `Property \"${capturedKey}\" does not exist in the target schema`\n            );\n        }\n\n        return new PropertyMappingBuilder(this, capturedKey as TKey);\n    }\n\n    /**\n     * Compile a synchronous function when the complete mapping has no async steps.\n     * Eligibility is inferred through compute(), from(), nested mappings and overrides.\n     * Callbacks are never probed during configuration. A disguised Promise/thenable\n     * throws at invocation; known async functions/dependencies throw at compilation.\n     * @throws MapperConfigurationError for incomplete or asynchronous mappings.\n     */\n    public getSyncMapper(\n        ..._args: SyncMappingArguments<\n            TUnmapped,\n            AsyncKeys<TFromSchema, TToSchema, TAsyncRegistered, TSteps>\n        >\n    ): SyncSchemaToSchemaMapperResult<TFromSchema, TToSchema> {\n        return synchronous(\n            (\n                this.getMapper as () => SchemaToSchemaMapperResult<\n                    TFromSchema,\n                    TToSchema\n                >\n            )()\n        );\n    }\n\n    /**\n     * Returns the configured async mapping function.\n     *\n     * **Compile-time safety:** This method is only callable without\n     * arguments when all target properties have been mapped or explicitly\n     * ignored. If any property is unmapped, TypeScript will require\n     * a string argument describing the unmapped properties, producing\n     * a clear compile-time error.\n     *\n     * **Runtime safety:** Even if TypeScript checks are bypassed (e.g.\n     * via `as any`), a `MapperConfigurationError` is thrown at runtime\n     * listing the unmapped properties.\n     */\n    public getMapper(\n        ..._args: [TUnmapped] extends [never]\n            ? []\n            : [error: `Unmapped properties: ${TUnmapped}`]\n    ): SchemaToSchemaMapperResult<TFromSchema, TToSchema> {\n        // Runtime validation: ensure all target properties are covered\n        const toIntrospection = this._toSchema.introspect();\n        const targetProperties = toIntrospection.properties\n            ? Object.keys(toIntrospection.properties)\n            : [];\n\n        // Auto-mapping: fill in unmapped properties using registered nested mappers\n        if (this._registry) {\n            const fromIntrospection = this._fromSchema.introspect();\n            const fromProperties = (fromIntrospection.properties ||\n                {}) as Record<string, any>;\n            const toProperties = (toIntrospection.properties || {}) as Record<\n                string,\n                any\n            >;\n            const fromTree = ObjectSchemaBuilder.getPropertiesFor(\n                this._fromSchema\n            );\n\n            for (const key of targetProperties) {\n                if (this._mappings.has(key)) continue;\n\n                const fromPropSchema = fromProperties[key];\n                const toPropSchema = toProperties[key];\n\n                if (!fromPropSchema || !toPropSchema) continue;\n\n                const sourceDescriptor = (fromTree as any)[key];\n                if (!sourceDescriptor?.[SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR])\n                    continue;\n\n                // ObjectSchemaBuilder → ObjectSchemaBuilder: use registered mapper\n                if (\n                    fromPropSchema instanceof ObjectSchemaBuilder &&\n                    toPropSchema instanceof ObjectSchemaBuilder\n                ) {\n                    const fromSchemaMappers =\n                        this._registry['_mappers'].get(fromPropSchema);\n                    const autoMapper = fromSchemaMappers?.get(toPropSchema);\n                    if (autoMapper) {\n                        this._mappings.set(key, {\n                            type: 'auto',\n                            sourceDescriptorInner:\n                                sourceDescriptor[\n                                    SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n                                ],\n                            autoMapper\n                        });\n                        continue;\n                    }\n\n                    // Same-name ObjectSchemaBuilder with identical property keys:\n                    // copy directly (full type safety ensured at compile time\n                    // via bidirectional InferType check)\n                    const fromKeys = Object.keys(\n                        fromPropSchema.introspect().properties || {}\n                    ).sort();\n                    const toKeys = Object.keys(\n                        toPropSchema.introspect().properties || {}\n                    ).sort();\n                    if (\n                        fromKeys.length === toKeys.length &&\n                        fromKeys.every((k, i) => k === toKeys[i])\n                    ) {\n                        this._mappings.set(key, {\n                            type: 'prop',\n                            sourceDescriptorInner:\n                                sourceDescriptor[\n                                    SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n                                ]\n                        });\n                    }\n                    continue;\n                }\n\n                // Primitive → Primitive: auto-map same-name props\n                // (type compatibility is ensured at the type level by\n                // KeysNeedingMapping / NeedsMapping)\n                if (\n                    !(fromPropSchema instanceof ObjectSchemaBuilder) &&\n                    !(toPropSchema instanceof ObjectSchemaBuilder) &&\n                    !(fromPropSchema instanceof ArraySchemaBuilder) &&\n                    !(toPropSchema instanceof ArraySchemaBuilder)\n                ) {\n                    this._mappings.set(key, {\n                        type: 'prop',\n                        sourceDescriptorInner:\n                            sourceDescriptor[SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]\n                    });\n                    continue;\n                }\n\n                // ArraySchemaBuilder → ArraySchemaBuilder: use element mapper\n                if (\n                    fromPropSchema instanceof ArraySchemaBuilder &&\n                    toPropSchema instanceof ArraySchemaBuilder\n                ) {\n                    const sourceElementSchema =\n                        fromPropSchema.introspect().elementSchema;\n                    const targetElementSchema =\n                        toPropSchema.introspect().elementSchema;\n                    if (sourceElementSchema && targetElementSchema) {\n                        const elementMapper = resolveElementMapper(\n                            sourceElementSchema,\n                            targetElementSchema,\n                            this._registry\n                        );\n                        if (elementMapper) {\n                            this._mappings.set(key, {\n                                type: 'autoArray',\n                                sourceDescriptorInner:\n                                    sourceDescriptor[\n                                        SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n                                    ],\n                                elementMapper\n                            });\n                        }\n                    }\n                }\n            }\n        }\n\n        const unmapped = targetProperties.filter(\n            key => !this._mappings.has(key)\n        );\n\n        if (unmapped.length > 0) {\n            throw new MapperConfigurationError(unmapped);\n        }\n\n        const targetTree = ObjectSchemaBuilder.getPropertiesFor(this._toSchema);\n\n        const mappings = new Map(this._mappings);\n\n        const mapperFn = async (\n            source: InferType<TFromSchema>\n        ): Promise<InferType<TToSchema>> => {\n            const result = {} as any;\n\n            for (const [key, entry] of mappings) {\n                if (entry.type === 'ignore') {\n                    continue;\n                }\n\n                let value: any;\n\n                if (entry.type === 'prop') {\n                    const getResult =\n                        entry.sourceDescriptorInner.getValue(source);\n                    if (getResult.success) {\n                        value = getResult.value;\n                    } else {\n                        continue;\n                    }\n                } else if (entry.type === 'custom') {\n                    value = await entry.fn!(source);\n                } else if (entry.type === 'auto') {\n                    const getResult =\n                        entry.sourceDescriptorInner.getValue(source);\n                    if (getResult.success && getResult.value !== undefined) {\n                        value = await entry.autoMapper!(getResult.value);\n                    } else {\n                        continue;\n                    }\n                } else if (entry.type === 'autoArray') {\n                    const getResult =\n                        entry.sourceDescriptorInner.getValue(source);\n                    // null/undefined → skip (spec §6); non-array → error\n                    if (getResult.success && getResult.value != null) {\n                        if (!Array.isArray(getResult.value)) {\n                            throw new MapperConfigurationError(\n                                `Expected array for property \"${key}\" but got ${typeof getResult.value}`\n                            );\n                        }\n                        value = await Promise.all(\n                            getResult.value.map(entry.elementMapper!)\n                        );\n                    } else {\n                        continue;\n                    }\n                }\n\n                const targetDescriptor = (targetTree as any)[key];\n                if (targetDescriptor?.[SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]) {\n                    targetDescriptor[\n                        SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n                    ].setValue(result, value, {\n                        createMissingStructure: true\n                    });\n                } else {\n                    result[key] = value;\n                }\n            }\n\n            return result;\n        };\n\n        // The same finalized entries drive the sync executor. Only execution differs;\n        // descriptor selection, automatic mapping and completeness are shared above.\n        const syncEntries = [...mappings].map(([key, entry]) => {\n            const nested = entry.autoMapper ?? entry.elementMapper;\n            const nestedSync = nested\n                ? syncImplementations.get(nested)\n                : undefined;\n            if (\n                (nested && !nestedSync) ||\n                entry.fn?.constructor.name === 'AsyncFunction'\n            )\n                return null;\n            return { key, entry, nestedSync };\n        });\n        if (syncEntries.every(entry => entry !== null)) {\n            syncImplementations.set(mapperFn, source => {\n                const result: Record<string, any> = {};\n                for (const { key, entry, nestedSync } of syncEntries) {\n                    if (entry.type === 'ignore') continue;\n                    let value: any;\n                    if (entry.type === 'custom')\n                        value = assertSync(entry.fn!(source), key);\n                    else {\n                        const read =\n                            entry.sourceDescriptorInner.getValue(source);\n                        if (!read.success) continue;\n                        value = read.value;\n                        if (entry.type === 'auto') {\n                            if (value === undefined) continue;\n                            value = assertSync(nestedSync!(value), key);\n                        } else if (entry.type === 'autoArray') {\n                            if (value == null) continue;\n                            if (!Array.isArray(value))\n                                throw new MapperConfigurationError(\n                                    `Expected array for property \"${key}\" but got ${typeof value}`\n                                );\n                            value = value.map(element =>\n                                assertSync(nestedSync!(element), key)\n                            );\n                        }\n                    }\n                    const target = (targetTree as any)[key]?.[\n                        SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n                    ];\n                    if (target)\n                        target.setValue(result, value, {\n                            createMissingStructure: true\n                        });\n                    else result[key] = value;\n                }\n                return result;\n            });\n        }\n\n        // Auto-register in the registry if available\n        if (this._registry) {\n            this._registry['_mappers']\n                .get(this._fromSchema)\n                ?.set(this._toSchema, mapperFn);\n        }\n\n        return mapperFn;\n    }\n}\n\n// ── MappingRegistry ───────────────────────────────────────────────────\n\nexport class MappingRegistry<TRegistered = never, TAsyncRegistered = never> {\n    protected readonly _mappers: Map<\n        ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n        Map<\n            ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n            SchemaToSchemaMapperResult<any, any>\n        >\n    > = new Map();\n\n    #ensureObjectSchemas(\n        fromSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any>,\n        toSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any>\n    ): boolean {\n        return !(\n            !fromSchema ||\n            !toSchema ||\n            fromSchema instanceof ObjectSchemaBuilder === false ||\n            toSchema instanceof ObjectSchemaBuilder === false\n        );\n    }\n\n    /**\n     * Defines a mapping between two schemas and returns a new immutable\n     * registry containing the mapping. The callback `fn` receives a fresh\n     * `Mapper` and must return it after configuring property mappings.\n     * The mapper is automatically finalized and registered. Properties\n     * not explicitly mapped or ignored may be auto-mapped if a matching\n     * nested mapping is already registered in the registry.\n     *\n     * @param fromSchema - source ObjectSchemaBuilder\n     * @param toSchema - target ObjectSchemaBuilder\n     * @param fn - callback that configures property mappings on the mapper\n     * @returns a new MappingRegistry containing all previous mappings plus\n     *          the newly configured one\n     * @throws if schemas are invalid, mapping is duplicate, or unmapped\n     *         properties remain that cannot be auto-mapped\n     */\n    public configure<\n        TFromSchema extends ObjectSchemaBuilder<\n            any,\n            any,\n            any,\n            any,\n            any,\n            any,\n            any\n        >,\n        TToSchema extends ObjectSchemaBuilder<\n            any,\n            any,\n            any,\n            any,\n            any,\n            any,\n            any\n        >,\n        TSteps = {}\n    >(\n        fromSchema: TFromSchema,\n        toSchema: TToSchema,\n        fn: (\n            mapper: Mapper<\n                TFromSchema,\n                TToSchema,\n                KeysNeedingMapping<TFromSchema, TToSchema, TRegistered>,\n                TRegistered,\n                TAsyncRegistered\n            >\n        ) => Mapper<\n            TFromSchema,\n            TToSchema,\n            never,\n            TRegistered,\n            TAsyncRegistered,\n            TSteps\n        >\n    ): MappingRegistry<\n        TRegistered | [TFromSchema, TToSchema],\n        | TAsyncRegistered\n        | ([\n              AsyncKeys<TFromSchema, TToSchema, TAsyncRegistered, TSteps>\n          ] extends [never]\n              ? never\n              : [TFromSchema, TToSchema])\n    > {\n        if (!this.#ensureObjectSchemas(fromSchema, toSchema)) {\n            throw new Error(\n                'Both fromSchema and toSchema must be instances of ObjectSchemaBuilder'\n            );\n        }\n\n        // Check for duplicate mappings\n        const existingFromMappers = this._mappers.get(fromSchema);\n        if (existingFromMappers?.has(toSchema)) {\n            throw new Error(\n                'Duplicate mapping: a mapping for this schemas pair is already registered'\n            );\n        }\n\n        // Create new immutable registry with cloned mappings\n        const newRegistry = new MappingRegistry<\n            TRegistered | [TFromSchema, TToSchema],\n            | TAsyncRegistered\n            | ([\n                  AsyncKeys<TFromSchema, TToSchema, TAsyncRegistered, TSteps>\n              ] extends [never]\n                  ? never\n                  : [TFromSchema, TToSchema])\n        >();\n        for (const [from, toMap] of this._mappers) {\n            newRegistry._mappers.set(from, new Map(toMap));\n        }\n\n        // Ensure the from→to map slot exists so getMapper can register\n        if (!newRegistry._mappers.has(fromSchema)) {\n            newRegistry._mappers.set(fromSchema, new Map());\n        }\n\n        // Create mapper with new registry reference\n        const mapper = new Mapper<\n            TFromSchema,\n            TToSchema,\n            KeysNeedingMapping<TFromSchema, TToSchema, TRegistered>,\n            TRegistered,\n            TAsyncRegistered\n        >(fromSchema, toSchema, newRegistry);\n\n        // Configure via user callback\n        const configuredMapper = fn(mapper);\n\n        // Implicit finalization: auto-map + validate + register\n        configuredMapper.getMapper();\n\n        return newRegistry;\n    }\n\n    /**\n     * Retrieve a registered synchronous mapper inferred from configure().\n     * The pair must be registered and its final steps must all be synchronous.\n     * Async mappings remain usable with getMapper(); configuration never executes\n     * compute callbacks. Unexpected thenables throw when the returned mapper runs.\n     * @throws MapperConfigurationError for an asynchronous dependency.\n     * @throws Error if the schema pair has not been registered.\n     */\n    public getSyncMapper<\n        TFromSchema extends ObjectSchemaBuilder<\n            any,\n            any,\n            any,\n            any,\n            any,\n            any,\n            any\n        >,\n        TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>\n    >(\n        fromSchema: TFromSchema,\n        toSchema: TToSchema,\n        ..._args: RegisteredSyncArguments<\n            [TFromSchema, TToSchema],\n            TRegistered,\n            TAsyncRegistered\n        >\n    ): SyncSchemaToSchemaMapperResult<TFromSchema, TToSchema> {\n        return synchronous(this.getMapper(fromSchema, toSchema));\n    }\n\n    /**\n     * Gets a mapper function that will map from the fromSchema to the toSchema.\n     * Throws an error if no mapper is found for the given schemas pair.\n     * @param fromSchema a schema to map from\n     * @param toSchema a schema to map to\n     * @returns a function that will take a value of the fromSchema type as an argument and\n     * return a promise resolving to a value of the toSchema type\n     */\n    public getMapper<\n        TFromSchema extends ObjectSchemaBuilder<\n            any,\n            any,\n            any,\n            any,\n            any,\n            any,\n            any\n        >,\n        TToSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>\n    >(\n        fromSchema: TFromSchema,\n        toSchema: TToSchema\n    ): SchemaToSchemaMapperResult<TFromSchema, TToSchema> {\n        if (!this.#ensureObjectSchemas(fromSchema, toSchema)) {\n            throw new Error(\n                'Both fromSchema and toSchema must be instances of ObjectSchemaBuilder'\n            );\n        }\n\n        const mappers = this._mappers.get(fromSchema);\n        if (!mappers) {\n            throw new Error('No mapper found for the given schemas pair');\n        }\n        const mapper = mappers.get(toSchema);\n        if (!mapper) {\n            throw new Error('No mapper found for the given schemas pair');\n        }\n\n        return mapper;\n    }\n}\n\n/**\n * Creates a new empty {@link MappingRegistry}.\n *\n * This is a convenience factory function — an alternative to\n * `new MappingRegistry()` that reads better in a fluent chain:\n *\n * ```ts\n * const registry = mapper()\n *   .configure(A, B, m => ...)\n *   .configure(C, D, m => ...);\n * ```\n */\nexport function mapper(): MappingRegistry {\n    return new MappingRegistry();\n}\n"],"mappings":"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","names":["ArraySchemaBuilder","ObjectSchemaBuilder","SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR","SYMBOL_TARGET_PROPERTY_KEY","syncImplementations","assertSync","value","key","MapperConfigurationError","synchronous","fn","result","messageOrUnmappedProperties","resolveElementMapper","sourceElementSchema","targetElementSchema","registry","ObjectSchemaBuilder","autoMapper","fromKeys","toKeys","k","i","copy","element","ArraySchemaBuilder","innerSourceElement","innerTargetElement","innerMapper","mapArray","arr","sync","sourceIntrospection","targetIntrospection","PropertyMappingBuilder","mapper","targetKey","selector","_args","sourceTree","inner","SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR","sourceSchema","targetPropSchema","elementMapper","Mapper","fromSchema","toSchema","capturedKey","proxy","_target","prop","SYMBOL_TARGET_PROPERTY_KEY","toIntrospection","targetProperties","fromProperties","toProperties","fromTree","fromPropSchema","toPropSchema","sourceDescriptor","unmapped","targetTree","mappings","mapperFn","source","entry","getResult","targetDescriptor","syncEntries","nested","nestedSync","read","target","MappingRegistry","_MappingRegistry","#ensureObjectSchemas","newRegistry","from","toMap","mappers"]}

package/package.json

@@ -5,7 +5,7 @@
         "email": "andrew_zol@cleverbrush.com"
     },
     "dependencies": {
-        "@cleverbrush/schema": "^4.5.0"
+        "@cleverbrush/schema": "^5.1.0"
     },
     "description": "Type-safe, schema-driven object mapper for @cleverbrush/schema — compile-time completeness, selector-based field mapping, auto-mapping",
     "files": [
@@ -20,7 +20,7 @@
         "data transformation",
         "cleverbrush"
     ],
-    "license": "BSD 3-Clause",
+    "license": "BSD-3-Clause",
     "main": "./dist/index.js",
     "exports": {
         ".": {
@@ -30,6 +30,9 @@
     },
     "sideEffects": false,
     "name": "@cleverbrush/mapper",
+    "engines": {
+        "node": ">=24"
+    },
     "readme": "https://github.com/cleverbrush/framework/tree/master/libs/mapper#readme",
     "repository": {
         "type": "git",
@@ -42,5 +45,5 @@
     },
     "type": "module",
     "types": "./dist/index.d.ts",
-    "version": "4.5.0"
+    "version": "5.1.0"
 }