@cleverbrush/mapper 0.0.0-beta-20260410073748

package/README.md

@@ -0,0 +1,340 @@
+# @cleverbrush/mapper
+
+[![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)
+<!-- 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.
+
+## Why @cleverbrush/mapper?
+
+**The problem:** Converting between different object shapes — API responses to domain models, domain models to DTOs, database rows to view models — is tedious and error-prone. You write manual mapping functions full of `destination.x = source.y` assignments. Add a new property to a schema and nothing tells you the mapper is incomplete. The bug shows up at runtime, not at compile time.
+
+**The solution:** `@cleverbrush/mapper` uses **PropertyDescriptor-based selectors** (similar to C# expression trees) for type-safe property mapping. The TypeScript compiler enforces that **every target property is mapped** — unmapped properties cause a compile-time error. You literally cannot forget a field.
+
+**What makes it different:**
+
+- **Compile-time completeness** — unmapped properties are a TypeScript error, not a runtime surprise
+- **Type-safe selectors** — `.for((t) => t.name).from((s) => s.name)` — fully checked at compile time, not string-based
+- **Auto-mapping** — properties with the same name and compatible type are mapped automatically; you only configure what differs
+- **Immutable registry** — `configure()` returns a new registry; safe to share and extend
+- **No decorators or classes** — works with plain objects and schemas
+
+| Feature | @cleverbrush/mapper | AutoMapper-ts | class-transformer | morphism |
+| --- | --- | --- | --- | --- |
+| Compile-time completeness | ✓ | ✗ | ✗ | ✗ |
+| Type-safe selectors | ✓ | ✗ | ✗ | ✗ |
+| No decorators required | ✓ | ✗ | ✗ | ✓ |
+| Works without classes | ✓ | ✗ | ✗ | ✓ |
+| Auto-mapping | ✓ | ✓ | ✗ | ✗ |
+| Immutable registry | ✓ | ✗ | ✗ | ✗ |
+| Nested schema support | ✓ | ~ | ~ | ✗ |
+
+## Installation
+
+```bash
+npm install @cleverbrush/mapper
+```
+
+**Peer dependency:** `@cleverbrush/schema`
+
+## Quick Start
+
+```typescript
+import { object, string, number } from '@cleverbrush/schema';
+import { mapper } from '@cleverbrush/mapper';
+
+// Define source and target schemas
+const ApiUser = object({
+    first_name: string(),
+    last_name:  string(),
+    birth_year: number()
+});
+
+const DomainUser = object({
+    fullName: string(),
+    age:      number()
+});
+
+// Configure the mapping — returns a new (immutable) registry
+const registry = mapper().configure(
+    ApiUser,
+    DomainUser,
+    (m) =>
+        m
+            .for((t) => t.fullName)
+                .compute((src) => src.first_name + ' ' + src.last_name)
+            .for((t) => t.age)
+                .compute((src) => new Date().getFullYear() - src.birth_year)
+);
+
+// Get the mapper function and use it
+const mapFn = registry.getMapper(ApiUser, DomainUser);
+
+const dto = await mapFn({
+    first_name: 'Jane',
+    last_name:  'Doe',
+    birth_year: 1995
+});
+// { fullName: 'Jane Doe', age: <current year - 1995> }
+```
+
+## How It Works — Step by Step
+
+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
+5. **TypeScript enforces completeness** — if any target property is unmapped, you get a compile-time error
+
+## Compile-Time Safety
+
+The mapper enforces multiple layers of compile-time safety:
+
+### Unmapped properties
+
+Every target property must be either mapped, auto-mapped, or explicitly ignored. If you forget to map a property, TypeScript will produce a compile-time error on the `configure` callback return:
+
+```typescript
+mapper().configure(
+    UserSchema,
+    UserDtoSchema,
+    (m) =>
+        m
+            .for((t) => t.name)
+            .from((f) => f.name)
+            .for((t) => t.cityName)
+            .from((f) => f.address.city)
+    // TS Error: Type 'Mapper<..., "fullAddress", ...>' is not assignable to
+    // type 'Mapper<..., never, ...>'.
+    //   Types of property '[SYMBOL_UNMAPPED]' are incompatible.
+    //     Type '"fullAddress"' is not assignable to type 'never'.
+);
+```
+
+The error message shows the names of the unmapped properties directly in the type mismatch.
+
+### Type-incompatible `from`
+
+`from` only shows source properties whose `InferType` is assignable to the target property's type. If you select an incompatible property (e.g., mapping a `number` to a `string`), TypeScript produces a compile-time error:
+
+```typescript
+// Trying to map a string target from a number source
+m.for((t) => t.cityName).from((f) => f.houseNr)
+// TS Error: source property type is not assignable to target property type
+// Use .compute() instead to transform the value
+```
+
+### Unregistered nested mappings
+
+When `from` maps between two `ObjectSchemaBuilder` properties, a mapping for that schema pair must be registered in the registry first. Otherwise, TypeScript produces a compile-time error:
+
+```typescript
+const PersonSchema = object({ name: string(), address: AddressSchema });
+const PersonDtoSchema = object({ name: string(), address: AddressDtoSchema });
+
+// Error — AddressSchema→AddressDtoSchema is not registered
+mapper().configure(
+    PersonSchema,
+    PersonDtoSchema,
+    (m) =>
+        m
+            .for((t) => t.name)
+            .from((f) => f.name)
+            .for((t) => t.address)
+            .from((f) => f.address) // TS Error: Register a mapping for the
+    // source→target schema pair first
+);
+```
+
+## Auto-Mapping
+
+Properties that can be automatically determined don't need explicit mapping configuration. Auto-mapping activates in two scenarios:
+
+### Same-name, same-type primitives
+
+When the source and target schemas have a property with the **same name** and **compatible `InferType`**, it is auto-mapped automatically:
+
+```typescript
+const Source = object({
+    id:    string(),
+    name:  string(),
+    email: string(),
+    age:   number()
+});
+
+const Target = object({
+    id:       string(),    // same name + type → auto-mapped
+    name:     string(),    // same name + type → auto-mapped
+    email:    string(),    // same name + type → auto-mapped
+    ageGroup: string()     // different name → must be configured
+});
+
+const registry = mapper().configure(Source, Target, (m) =>
+    m
+        .for((t) => t.ageGroup)
+            .compute((src) => src.age < 18 ? 'minor' : 'adult')
+    // id, name, email are auto-mapped — no configuration needed!
+);
+```
+
+### Nested ObjectSchemaBuilder properties
+
+When both the source and target have a same-name property that is an `ObjectSchemaBuilder`, and a mapping for that schema pair has been previously registered, the nested property is auto-mapped using the registered mapper:
+
+```typescript
+const AddressSchema = object({ city: string(), houseNr: number() });
+const AddressDtoSchema = object({ city: string() });
+
+const PersonSchema = object({ name: string(), address: AddressSchema });
+const PersonDtoSchema = object({ name: string(), address: AddressDtoSchema });
+
+const registry = mapper()
+    // Register Address mapping first
+    .configure(AddressSchema, AddressDtoSchema, (m) =>
+        m.for((t) => t.city).from((f) => f.city)
+    )
+    // address is auto-mapped using the registered AddressSchema→AddressDtoSchema mapper
+    .configure(PersonSchema, PersonDtoSchema, (m) =>
+        m.for((t) => t.name).from((f) => f.name)
+    );
+
+const mapFn = registry.getMapper(PersonSchema, PersonDtoSchema);
+const result = await mapFn({
+    name: 'Alice',
+    address: { city: 'Berlin', houseNr: 10 }
+});
+// result: { name: 'Alice', address: { city: 'Berlin' } }
+```
+
+**Ordering matters:** nested mappings must be registered before the parent mapping. Explicit mappings via `compute` or `ignore` take priority over auto-mapping.
+
+## Mapping Strategies
+
+| Strategy | Usage | Purpose |
+| --- | --- | --- |
+| `.from(selector)` | `.for(t => t.x).from(s => s.y)` | Copy from a source property (supports nested paths) |
+| `.compute(fn)` | `.for(t => t.x).compute(s => s.a + s.b)` | Compute from a sync or async function |
+| `.ignore()` | `.for(t => t.x).ignore()` | Exclude a target property |
+| _(auto-mapped)_ | _(no configuration needed)_ | Same-name, compatible-type primitives or registered nested schemas |
+
+Every non-auto-mappable target property must be either mapped or explicitly ignored. Unmapped properties cause:
+
+- 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
+
+## API
+
+### `mapper()`
+
+A convenience factory function that creates a new `MappingRegistry`:
+
+```typescript
+const registry = mapper()
+    .configure(A, B, (m) => ...)
+    .configure(C, D, (m) => ...);
+```
+
+### `registry.configure(fromSchema, toSchema, fn)`
+
+Defines a mapping between two schemas and returns a new immutable registry containing the mapping. The callback `fn` receives a fresh `Mapper` and must return it after configuring all non-auto-mappable property mappings.
+
+Throws if schemas are invalid, the mapping is a duplicate, or if unmapped properties remain that cannot be auto-mapped.
+
+### `registry.getMapper(fromSchema, toSchema)`
+
+Retrieves a previously registered mapper function. Throws if no mapper has been registered for the given schema pair.
+
+```typescript
+const mapFn = registry.getMapper(ApiUser, DomainUser);
+const result = await mapFn(sourceObject);
+```
+
+### `Mapper`
+
+A fluent builder for configuring how each target property is populated:
+
+- **`.for(selector)`** — selects a target property to configure
+- **`.from(selector)`** — maps from a source property (types must be compatible)
+- **`.compute(fn)`** — computes the value from the entire source object (sync or async)
+- **`.ignore()`** — explicitly excludes the property
+- **`.getMapper()`** — returns the mapping function (only available when all properties are mapped)
+
+```typescript
+const mapper = new Mapper(SourceSchema, TargetSchema);
+const mapFn = mapper
+    .for((t) => t.fullName)
+        .compute((src) => `${src.firstName} ${src.lastName}`)
+    .for((t) => t.age)
+        .from((src) => src.years)
+    .getMapper();
+
+const result = await mapFn(sourceObject);
+```
+
+## Real-World Example
+
+A complete example mapping API responses through multiple layers:
+
+```typescript
+import { object, string, number } from '@cleverbrush/schema';
+import { mapper } from '@cleverbrush/mapper';
+
+// API response shape
+const ApiOrderResponse = object({
+    order_id:      string(),
+    customer_name: string(),
+    total_cents:   number(),
+    status_code:   number()
+});
+
+// Domain model
+const Order = object({
+    id:         string(),
+    customer:   string(),
+    totalPrice: string(),
+    status:     string()
+});
+
+const registry = mapper().configure(
+    ApiOrderResponse,
+    Order,
+    (m) =>
+        m
+            .for((t) => t.id)
+                .from((s) => s.order_id)
+            .for((t) => t.customer)
+                .from((s) => s.customer_name)
+            .for((t) => t.totalPrice)
+                .compute((s) => `$${(s.total_cents / 100).toFixed(2)}`)
+            .for((t) => t.status)
+                .compute((s) => {
+                    const statuses: Record<number, string> = {
+                        0: 'pending', 1: 'confirmed', 2: 'shipped', 3: 'delivered'
+                    };
+                    return statuses[s.status_code] ?? 'unknown';
+                })
+);
+
+const mapOrder = registry.getMapper(ApiOrderResponse, Order);
+const order = await mapOrder({
+    order_id: 'ORD-123',
+    customer_name: 'Alice Smith',
+    total_cents: 4999,
+    status_code: 2
+});
+// { id: 'ORD-123', customer: 'Alice Smith', totalPrice: '$49.99', status: 'shipped' }
+```
+
+## Code Quality
+
+- **Linting:** [Biome](https://biomejs.dev/) — enforced on every PR via CI
+- **Type checking:** TypeScript strict mode — all type selectors and mapping configurations are validated at compile time
+- **Unit tests:** [Vitest](https://vitest.dev/) — runtime tests + type-level tests (`expectTypeOf`) covering auto-mapping, computed fields, nested schemas, and compile-time completeness errors
+- **CI:** Every pull request must pass lint + build + test before merge — see [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml)
+
+## License
+
+BSD-3-Clause

package/dist/MappingRegistry.d.ts

@@ -0,0 +1,258 @@
+import { ArraySchemaBuilder, 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.
+ */
+declare const SYMBOL_TARGET_PROPERTY_KEY: unique symbol;
+/**
+ * Internal symbol used as a phantom property key on Mapper to track
+ * unmapped target properties. Using a symbol keeps it out of IntelliSense.
+ */
+declare const SYMBOL_UNMAPPED: unique symbol;
+/**
+ * Extracts the properties record from an ObjectSchemaBuilder.
+ */
+type ExtractSchemaProperties<T> = T extends ObjectSchemaBuilder<infer TProperties, any, any> ? TProperties : never;
+/**
+ * Gets all top-level property key names of an ObjectSchemaBuilder.
+ */
+type SchemaKeys<T extends ObjectSchemaBuilder<any, any, any>> = 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
+ * `for` callback, enabling compile-time tracking of mapped vs unmapped
+ * properties.
+ */
+type TargetPropertyKey<K extends string> = {
+    readonly [SYMBOL_TARGET_PROPERTY_KEY]: K;
+};
+/**
+ * Creates a tree of selectable target properties, filtered to only show
+ * properties whose keys are in `TAllowedKeys`. Each property is branded
+ * 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>;
+};
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * Extracts the element schema from an ArraySchemaBuilder.
+ */
+type ExtractArrayElementSchema<T> = T extends ArraySchemaBuilder<infer TElementSchema, any, any> ? TElementSchema : never;
+/**
+ * Extracts the property schema from a PropertyDescriptor's `getSchema()`
+ * return type. Used by {@link IsFromCompatible} to recover the source
+ * property's schema from the inferred `TReturn` of the `from()` selector.
+ */
+type ExtractPropertySchema<T> = T extends {
+    [SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]: {
+        getSchema(): infer TSchema;
+    };
+} ? TSchema : never;
+/**
+ * Determines whether a property needs an explicit mapping configuration.
+ *
+ * - Both are ObjectSchemaBuilder with registered mapping → `false` (auto-mappable)
+ * - Both are ObjectSchemaBuilder without registered mapping → `true`
+ * - Either is ObjectSchemaBuilder but the other is not → `true`
+ * - Both are ArraySchemaBuilder with element schemas that have registered mapping → `false`
+ * - Both are ArraySchemaBuilder with same InferType → `false`
+ * - Array vs non-array → `true`
+ * - Neither is ObjectSchemaBuilder + InferType<source> extends InferType<target>
+ *   → `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;
+/**
+ * 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> = {
+    [K in SchemaKeys<TToSchema>]: K extends SchemaKeys<TFromSchema> ? NeedsMapping<ExtractSchemaProperties<TFromSchema>[K], ExtractSchemaProperties<TToSchema>[K], TRegistered> extends true ? K : never : K;
+}[SchemaKeys<TToSchema>];
+/**
+ * Checks whether two property schemas are compatible, considering
+ * registered mappings. Mirrors {@link NeedsMapping}'s structure:
+ * receives schemas as direct type parameters, uses
+ * {@link ExtractArrayElementSchema} for arrays, and checks registration
+ * via tuple-extends-union (not inline `infer`).
+ */
+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;
+/**
+ * Checks whether the source property selected by `from()` is compatible
+ * with the target property, evaluated *after* `TReturn` has been inferred.
+ *
+ * This decouples inference from validation: the `TReturn` constraint uses
+ * `any` for setValue/getValue value types so TypeScript always infers
+ * 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>>;
+export declare class MapperConfigurationError extends Error {
+    constructor(messageOrUnmappedProperties: string | string[]);
+}
+/**
+ * Intermediate builder returned by `for()`. Provides three strategies
+ * to configure how the selected target property is populated:
+ * - `from()` — copy from a source property
+ * - `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> {
+    private readonly _mapper;
+    private readonly _targetKey;
+    /** @internal */
+    constructor(mapper: Mapper<TFromSchema, TToSchema, any, TRegistered>, targetKey: TKey);
+    /**
+     * Maps the target property from a source property. The selector
+     * receives the source schema's PropertyDescriptorTree and supports
+     * nested paths (e.g. `(s) => s.address.city`).
+     *
+     * Type compatibility is enforced: only source properties whose
+     * inferred type is assignable to the target property type will
+     * appear in the selector callback.
+     *
+     * Under `strictFunctionTypes`, the `setValue` and `getValue` constraints
+     * provide bidirectional type checking:
+     * - `setValue` contravariance rejects source schemas with extra properties
+     * - `getValue` covariance rejects source schemas with missing properties
+     * - registered mappings widen the constraint via intersection
+     */
+    from<TReturn extends {
+        [SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]: {
+            getSchema(): SchemaBuilder<any, any, any>;
+            setValue: (obj: any, value: any) => any;
+            getValue: (obj: any) => {
+                value?: any;
+                success: boolean;
+            };
+        };
+    }>(selector: (tree: PropertyDescriptorTree<TFromSchema, TFromSchema, SchemaPropertyInferredType<TToSchema, TKey>>) => 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>;
+    /**
+     * 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>;
+    /**
+     * Explicitly excludes the target property from mapping.
+     * The property will not appear in the output object.
+     */
+    ignore(): Mapper<TFromSchema, TToSchema, Exclude<TUnmapped, TKey>, TRegistered>;
+}
+/**
+ * A fluent builder for configuring how each target property is populated
+ * from a source schema. Uses PropertyDescriptors as pointers to properties
+ * (similar to expressions in C# .NET).
+ *
+ * The `TUnmapped` type parameter tracks which target properties have not
+ * yet been mapped or ignored. `getMapper()` is only callable (without
+ * arguments) when `TUnmapped` is `never` — i.e. all properties have been
+ * accounted for. If any property is missing, TypeScript will produce a
+ * compile-time type error (a type-assignability mismatch that includes
+ * the unmapped property names in its type parameters).
+ *
+ * @typeParam TFromSchema - source ObjectSchemaBuilder
+ * @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> {
+    /** Phantom property for structural type-checking of TUnmapped. */
+    readonly [SYMBOL_UNMAPPED]: TUnmapped;
+    private readonly _fromSchema;
+    private readonly _toSchema;
+    private readonly _registry;
+    private readonly _mappings;
+    /**
+     * Creates a new instance of the Mapper class.
+     * @param fromSchema - `object` schema to map from
+     * @param toSchema - `object` schema to map to
+     * @param registry - optional MappingRegistry to auto-register the mapper
+     */
+    constructor(fromSchema: TFromSchema, toSchema: TToSchema, registry?: MappingRegistry<any>);
+    /**
+     * Selects a target property to configure. The selector callback
+     * receives a tree of all target properties. Navigate by
+     * property name: `(t) => t.cityName`.
+     *
+     * Auto-mappable properties (same name and compatible type, or
+     * 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>;
+    /**
+     * Returns the configured async mapping function.
+     *
+     * **Compile-time safety:** This method is only callable without
+     * arguments when all target properties have been mapped or explicitly
+     * ignored. If any property is unmapped, TypeScript will require
+     * a string argument describing the unmapped properties, producing
+     * a clear compile-time error.
+     *
+     * **Runtime safety:** Even if TypeScript checks are bypassed (e.g.
+     * via `as any`), a `MapperConfigurationError` is thrown at runtime
+     * listing the unmapped properties.
+     */
+    getMapper(..._args: [TUnmapped] extends [never] ? [] : [error: `Unmapped properties: ${TUnmapped}`]): SchemaToSchemaMapperResult<TFromSchema, TToSchema>;
+}
+export declare class MappingRegistry<TRegistered = never> {
+    #private;
+    protected readonly _mappers: Map<ObjectSchemaBuilder<any, any, any>, Map<ObjectSchemaBuilder<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
+     * `Mapper` and must return it after configuring property mappings.
+     * The mapper is automatically finalized and registered. Properties
+     * not explicitly mapped or ignored may be auto-mapped if a matching
+     * nested mapping is already registered in the registry.
+     *
+     * @param fromSchema - source ObjectSchemaBuilder
+     * @param toSchema - target ObjectSchemaBuilder
+     * @param fn - callback that configures property mappings on the mapper
+     * @returns a new MappingRegistry containing all previous mappings plus
+     *          the newly configured one
+     * @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]>;
+    /**
+     * 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.
+     * @param fromSchema a schema to map from
+     * @param toSchema a schema to map to
+     * @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>;
+}
+/**
+ * Creates a new empty {@link MappingRegistry}.
+ *
+ * This is a convenience factory function — an alternative to
+ * `new MappingRegistry()` that reads better in a fluent chain:
+ *
+ * ```ts
+ * const registry = mapper()
+ *   .configure(A, B, m => ...)
+ *   .configure(C, D, m => ...);
+ * ```
+ */
+export declare function mapper(): MappingRegistry;
+export {};

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +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};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+    "author": "Andrew Zolotukhin <andrew_zol@cleverbrush.com>",
+    "bugs": {
+        "url": "https://github.com/cleverbrush/framework/issues",
+        "email": "andrew_zol@cleverbrush.com"
+    },
+    "dependencies": {
+        "@cleverbrush/schema": "0.0.0-beta-20260410073748"
+    },
+    "description": "Type-safe, schema-driven object mapper for @cleverbrush/schema — compile-time completeness, selector-based field mapping, auto-mapping",
+    "files": [
+        "dist"
+    ],
+    "homepage": "https://docs.cleverbrush.com/modules/_cleverbrush_mapper.html",
+    "keywords": [
+        "object mapper",
+        "schema mapping",
+        "typescript",
+        "type-safe",
+        "data transformation",
+        "cleverbrush"
+    ],
+    "license": "BSD 3-Clause",
+    "main": "./dist/index.js",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "sideEffects": false,
+    "name": "@cleverbrush/mapper",
+    "readme": "https://github.com/cleverbrush/framework/tree/master/libs/mapper#readme",
+    "repository": {
+        "type": "git",
+        "url": "github:cleverbrush/framework"
+    },
+    "scripts": {
+        "watch": "tsc --build tsconfig.build.json --watch",
+        "build": "tsup && tsc --project tsconfig.build.json --emitDeclarationOnly",
+        "clean": "rm -rf dist tsconfig.build.tsbuildinfo"
+    },
+    "type": "module",
+    "types": "./dist/index.d.ts",
+    "version": "0.0.0-beta-20260410073748"
+}