@pristine-ts/data-mapping-common 2.0.7 → 2.0.9

package/dist/types/builders/auto-data-mapping.builder.d.ts

@@ -2,6 +2,17 @@ import { ClassConstructor } from "class-transformer";
 import { DataMappingBuilder } from "./data-mapping.builder";
 import { AutoDataMappingBuilderOptions } from "../options/auto-data-mapping-builder.options";
 export declare class AutoDataMappingBuilder {
+    /**
+     * Schema cache keyed by destination class. The auto-built schema is deterministic in `destinationType`
+     * + the *shape* of the source (which decoration metadata describes), so for a stable class definition
+     * the same builder can be reused across calls. We key only by destinationType to keep things simple;
+     * if the source shape varies and the auto-inference depends on it (e.g. inferring scalar-array member
+     * type from `source[propertyKey][0]`), callers needing fresh inference can bypass the cache via the
+     * `disableCache` option.
+     *
+     * Stored under a WeakMap so unused destination classes can be garbage-collected.
+     */
+    private readonly cache;
     /**
      * This method receives a source object and a destinationType that corresponds to the type of the class
      * that the source should be mapped to. It then creates a DataMappingBuilder object that contains the schema
@@ -11,6 +22,11 @@ export declare class AutoDataMappingBuilder {
      * @param options
      */
     build(source: any, destinationType: ClassConstructor<any>, options?: AutoDataMappingBuilderOptions): DataMappingBuilder;
+    /**
+     * Clear the cached schema for a destinationType (or the whole cache when no argument is passed).
+     * Useful in tests, or when class metadata changes at runtime (rare).
+     */
+    clearCache(destinationType?: ClassConstructor<any>): void;
     /**
      * This method is the internal method that is called recursively to build the schema.
      *

package/dist/types/builders/data-mapping.builder.d.ts

@@ -88,11 +88,12 @@ export declare class DataMappingBuilder extends BaseDataMappingNode {
      */
     import(schema: any): void;
     /**
-     * This method exports this node.
+     * This method exports the schema as a plain object. The export does not mutate the live tree —
+     * the builder remains usable for mapping after this call returns.
      */
     export(): {
         nodes: {
-            [x: string]: DataMappingLeaf | DataMappingNode;
+            [key: string]: any;
         };
         normalizers: {
             key: DataNormalizerUniqueKey;

package/dist/types/errors/data-normalizer-not-found.error.d.ts

@@ -0,0 +1,8 @@
+import { DataNormalizerUniqueKey } from "../types/data-normalizer-unique-key.type";
+/**
+ * Thrown when a leaf references a normalizer key that hasn't been registered with the DataMapper.
+ */
+export declare class DataNormalizerNotFoundError extends Error {
+    readonly normalizerUniqueKey: DataNormalizerUniqueKey;
+    constructor(message: string, normalizerUniqueKey: DataNormalizerUniqueKey);
+}

package/dist/types/errors/errors.d.ts

@@ -1,8 +1,11 @@
 export * from "./array-data-mapping-node-invalid-source-property-type.error";
+export * from "./auto-map-primitive-type-normalizer-not-found.error";
 export * from "./data-after-mapping-interceptor-already-added.error";
 export * from "./data-before-mapping-interceptor-already-added.error";
 export * from "./data-normalizer-already-added.error";
+export * from "./data-normalizer-not-found.error";
 export * from "./data-mapping-interceptor-not-found.error";
 export * from "./data-mapping-source-property-not-found.error";
 export * from "./normalizer-invalid-source-type.error";
+export * from "./undefined-destination-property.error";
 export * from "./undefined-source-property.error";

package/dist/types/errors/undefined-destination-property.error.d.ts

@@ -0,0 +1,8 @@
+import { DataMappingLeaf } from "../nodes/data-mapping.leaf";
+import { DataMappingNode } from "../nodes/data-mapping.node";
+/**
+ * Thrown when a Node is being committed to its parent without a `destinationProperty` set.
+ */
+export declare class UndefinedDestinationPropertyError extends Error {
+    constructor(node: DataMappingLeaf | DataMappingNode);
+}

package/dist/types/interfaces/data-mapping-interceptor.interface.d.ts

@@ -7,13 +7,17 @@ export interface DataMappingInterceptorInterface {
     getUniqueKey(): DataMappingInterceptorUniqueKeyType;
     /**
      * This method is called before the row is being mapped and normalized. It allows you to combine fields for example if that's what you want.
+     *
      * @param row
+     * @param options The options associated with this interceptor entry on the builder.
      */
-    beforeMapping(row: any): Promise<any>;
+    beforeMapping(row: any, options?: any): Promise<any>;
     /**
      * This method is called after the row is being mapped and normalized. It can allow you to apply operations on each
      * field or combine fields for example.
+     *
      * @param row
+     * @param options The options associated with this interceptor entry on the builder.
      */
-    afterMapping(row: any): Promise<any>;
+    afterMapping(row: any, options?: any): Promise<any>;
 }

package/dist/types/nodes/data-mapping.leaf.d.ts

@@ -27,6 +27,11 @@ export declare class DataMappingLeaf {
      * This property contains an array of Normalizers that must be excluded from normalizers defined by parents.
      */
     excludedNormalizers: Set<DataNormalizerUniqueKey>;
+    /**
+     * Memoized merge of inherited root normalizers (minus excluded) and leaf-local normalizers.
+     * Cleared whenever the leaf's normalizer configuration changes.
+     */
+    private effectiveNormalizersCache?;
     /**
      * This method specified whether it's possible that this element not be present in the `source` object.
      */
@@ -65,6 +70,12 @@ export declare class DataMappingLeaf {
      * @param normalizerUniqueKey
      */
     excludeNormalizer(normalizerUniqueKey: DataNormalizerUniqueKey): DataMappingLeaf;
+    /**
+     * Returns the merged list of normalizers applied to this leaf: inherited root normalizers minus the
+     * ones explicitly excluded here, followed by leaf-local normalizers. Memoized — the cache is cleared
+     * by `addNormalizer`/`excludeNormalizer`.
+     */
+    private getEffectiveNormalizers;
     /**
      * This method adds this node to its parent and returns the parent.
      */

package/dist/types/nodes/data-mapping.node.d.ts

@@ -85,6 +85,52 @@ export declare class DataMappingNode extends BaseDataMappingNode {
     map(source: any, destination: any, normalizersMap: {
         [key in DataNormalizerUniqueKey]: DataNormalizerInterface<any, any>;
     }, options?: DataMapperOptions): Promise<void>;
+    /**
+     * Build the destination object for the single-object case.
+     *
+     * If a `destinationType` (class constructor) is set, instantiate the class. Otherwise return
+     * a plain object. When `includeSourceKeys` is true, the source's own enumerable properties are
+     * seeded onto the result so they survive the mapping; sub-nodes then overlay renamed keys on top.
+     *
+     * Note: the single-object case treats `destinationType` strictly as a class constructor.
+     * Factory callbacks only make sense for the per-element ObjectArray case below.
+     */
+    private buildDestinationObject;
+    /**
+     * Build the destination object for a single element of an ObjectArray. Mirrors
+     * `buildDestinationObject`, with two extra wrinkles unique to arrays:
+     *
+     *   1. `destinationType` can be a *factory callback* instead of a fixed class. The callback
+     *      receives the source array's parent + the element's index and returns an instance of
+     *      the concrete class to use. This is how polymorphic arrays work (e.g. some elements
+     *      become `Cat`, others `Dog`).
+     *   2. The seed value is the per-element object, not the whole array.
+     */
+    private buildArrayMemberDestination;
+    /**
+     * Resolve the concrete class constructor for a single element of an ObjectArray.
+     *
+     * `destinationType` here is one of two things:
+     *
+     *   - a **class constructor** (uniform array — every element maps to the same class), or
+     *   - a **factory callback** of shape `(source, sourceProperty, index) => instance`
+     *     (polymorphic array — class is chosen per element).
+     *
+     * JavaScript gives us no clean way to distinguish a class constructor from a callback —
+     * both are `typeof === "function"`. The conventional discriminant: a class constructor has
+     * a `.prototype` object (where its instance methods live); an arrow function does not.
+     *
+     * Caveat: a regular `function() { ... }` expression used as a callback would also have a
+     * `.prototype` and would be mis-classified as a class. The public type only documents the
+     * arrow-function form (`ArrayMemberTypeFactoryCallbackType = (...) => any`), and in practice
+     * callers use arrow functions, so this is safe for documented usage.
+     */
+    private resolveArrayMemberConstructor;
+    /**
+     * Run every direct child node against `(sourceElement, destinationElement)`. Each child
+     * writes its mapped destination property onto `destinationElement`.
+     */
+    private runSubNodes;
     /**
      * This method imports a schema.
      *
@@ -92,7 +138,13 @@ export declare class DataMappingNode extends BaseDataMappingNode {
      */
     import(schema: any): void;
     /**
-     * This method exports this node.
+     * This method exports this node. The exported representation is a plain object — it does not mutate
+     * the live tree, so the same builder can continue to be used for mapping after `export()` is called.
+     *
+     * `destinationType` is intentionally not serialized: class constructors aren't transferable, and
+     * factory callbacks (`ArrayMemberTypeFactoryCallbackType`) hold closures. To rehydrate a schema with
+     * the same destination instantiation behavior, decorate the destination class with class-transformer's
+     * `@Type()` and pass the destination class to `DataMapper.map()`.
      */
     export(): {
         _type: DataMappingNodeTypeEnum;
@@ -100,7 +152,7 @@ export declare class DataMappingNode extends BaseDataMappingNode {
         destinationProperty: string;
         isOptional: boolean;
         nodes: {
-            [x: string]: DataMappingLeaf | DataMappingNode;
+            [key: string]: any;
         };
     };
 }

package/dist/types/options/auto-data-mapping-builder.options.d.ts

@@ -21,5 +21,17 @@ export declare class AutoDataMappingBuilderOptions {
      * This property specifies if the errors should be logged.
      */
     logErrors?: boolean;
+    /**
+     * When `true`, bypass the AutoDataMappingBuilder schema cache and always rebuild from metadata.
+     *
+     * The cache keys by destinationType only. If the auto-inference depends on the live source shape
+     * (e.g. inferring the element type of an untyped scalar array from `source[propertyKey][0]`),
+     * the first call wins and subsequent calls reuse that decision. Pass `true` when you need fresh
+     * inference per call.
+     *
+     * Default value is `false`. Optional in the type so existing consumers passing a plain object
+     * literal (without instantiating `AutoDataMappingBuilderOptions`) remain compatible.
+     */
+    disableCache?: boolean;
     constructor(options?: Partial<AutoDataMappingBuilderOptions>);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/data-mapping-common",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "",
   "module": "dist/lib/esm/data-mapping-common.js",
   "main": "dist/lib/cjs/data-mapping-common.js",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@pristine-ts/class-validator": "^2.0.4",
-    "@pristine-ts/common": "^2.0.7",
+    "@pristine-ts/common": "^2.0.9",
     "@pristine-ts/metadata": "^1.0.16",
     "class-transformer": "^0.5.1",
     "date-fns": "^3.3.1"
@@ -63,7 +63,7 @@
       "jest-extended/all"
     ]
   },
-  "gitHead": "8788c711f72b7ebdcec76bc8f6a56d51af143087",
+  "gitHead": "760994a87a1207f1670d31c67c6b8cde4c5b09f4",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",