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

package/dist/lib/esm/types/data-mapper-error-reporter.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data-mapper-error-reporter.type.js.map

package/dist/lib/esm/types/data-mapper-error-reporter.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-mapper-error-reporter.type.js","sourceRoot":"","sources":["../../../../src/types/data-mapper-error-reporter.type.ts"],"names":[],"mappings":""}

package/dist/lib/esm/types/types.js

@@ -1,4 +1,5 @@
 export * from "./array-member-type-factory-callback.type";
+export * from "./data-mapper-error-reporter.type";
 export * from "./data-normalizer-unique-key.type";
 export * from "./data-mapping-interceptor-unique-key.type";
 export * from "./type-factory-callback.type";

package/dist/lib/esm/types/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/types/types.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,mCAAmC,CAAC;AAClD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/types/types.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,8BAA8B,CAAC"}

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

@@ -82,14 +82,14 @@ export declare class DataMappingBuilder extends BaseDataMappingNode {
      */
     end(): DataMappingBuilder;
     /**
-     * This method imports a schema.
-     *
-     * @param schema
+     * Rehydrate this builder from a previously-exported schema. Replaces every field this
+     * class owns; child nodes are rebuilt via `DataMappingSerializer.importChildren`, which is
+     * the same helper `DataMappingNode.import` uses (so the two stay consistent).
      */
     import(schema: any): void;
     /**
-     * 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 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: {

package/dist/types/data-mapping-common.d.ts

@@ -8,4 +8,6 @@ export * from "./nodes/nodes";
 export * from "./normalizer-options/normalizer-options";
 export * from "./normalizers/normalizers";
 export * from "./options/options";
+export * from "./reporters/reporters";
+export * from "./serializers/serializers";
 export * from "./types/types";

package/dist/types/interfaces/fluent-array-of-objects-options.interface.d.ts

@@ -0,0 +1,21 @@
+import { ClassConstructor } from "class-transformer";
+import { ArrayMemberTypeFactoryCallbackType } from "../types/array-member-type-factory-callback.type";
+/**
+ * Options for a fluent array-of-objects field (`arrayOfObjects()` on `BaseDataMappingNode`).
+ *
+ * Unlike `FluentNestedOptions`, `destinationType` here also accepts a factory callback for
+ * polymorphic arrays — where each element of the array maps to a different concrete class
+ * (e.g. an `items` array containing both `Cat` and `Dog`, discriminated by a `kind` field).
+ */
+export interface FluentArrayOfObjectsOptions {
+    /**
+     * When true, the array node is skipped silently if the source property is missing.
+     */
+    isOptional?: boolean;
+    /**
+     * Either a class constructor (uniform array — every element maps to the same class) or a
+     * factory callback `(source, sourceProperty, index) => instance` that picks the concrete
+     * class per element.
+     */
+    destinationType?: ClassConstructor<any> | ArrayMemberTypeFactoryCallbackType;
+}

package/dist/types/interfaces/fluent-leaf-options.interface.d.ts

@@ -0,0 +1,27 @@
+import { DataNormalizerUniqueKey } from "../types/data-normalizer-unique-key.type";
+/**
+ * Options for a fluent leaf field — used by both `field()` and `arrayOfScalars()` on
+ * `BaseDataMappingNode`. Both expose the same per-leaf knobs (normalizers, optional flag,
+ * excluded inherited normalizers), so they share this options shape.
+ */
+export interface FluentLeafOptions {
+    /**
+     * Normalizers to apply to the value as it flows from source to destination. Each entry is
+     * either a unique key (shorthand) or `{key, options}` to pass normalizer-specific options.
+     */
+    normalizers?: Array<DataNormalizerUniqueKey | {
+        key: DataNormalizerUniqueKey;
+        options?: any;
+    }>;
+    /**
+     * Normalizers added at the builder root that should NOT apply to this leaf. Useful when a
+     * global normalizer (e.g. lowercase everything) needs to be skipped for one specific field
+     * (e.g. an API key that's case-sensitive).
+     */
+    excludeNormalizers?: DataNormalizerUniqueKey[];
+    /**
+     * When true, the leaf is skipped silently if the source property is missing. When false /
+     * undefined, a missing source property throws `DataMappingSourcePropertyNotFoundError`.
+     */
+    isOptional?: boolean;
+}

package/dist/types/interfaces/fluent-nested-options.interface.d.ts

@@ -0,0 +1,19 @@
+import { ClassConstructor } from "class-transformer";
+/**
+ * Options for a fluent single-nested-object field (`nested()` on `BaseDataMappingNode`).
+ *
+ * Single-object case: `destinationType` is strictly a class constructor. The
+ * polymorphic-array case (where the destination class is chosen per element) has its own
+ * options interface — see `FluentArrayOfObjectsOptions`.
+ */
+export interface FluentNestedOptions {
+    /**
+     * When true, the nested node is skipped silently if the source property is missing.
+     */
+    isOptional?: boolean;
+    /**
+     * If set, the destination property is instantiated as this class (via `plainToInstance`).
+     * Without it, the destination is a plain object.
+     */
+    destinationType?: ClassConstructor<any>;
+}

package/dist/types/interfaces/interfaces.d.ts

@@ -1,2 +1,5 @@
 export * from "./data-normalizer.interface";
 export * from "./data-mapping-interceptor.interface";
+export * from "./fluent-array-of-objects-options.interface";
+export * from "./fluent-leaf-options.interface";
+export * from "./fluent-nested-options.interface";

package/dist/types/mappers/data.mapper.d.ts

@@ -6,13 +6,27 @@ import { AutoDataMappingBuilder } from "../builders/auto-data-mapping.builder";
 import { AutoDataMappingBuilderOptions } from "../options/auto-data-mapping-builder.options";
 import { DataMapperOptions } from "../options/data-mapper.options";
 import { PrimitiveType } from "../enums/primitive-type.enum";
+import { DataMapperErrorReporter } from "../types/data-mapper-error-reporter.type";
 export declare class DataMapper {
     private readonly autoDataMappingBuilder;
     private readonly dataNormalizers;
     private readonly dataTransformerInterceptors;
     private readonly dataNormalizersMap;
     private readonly dataTransformerInterceptorsMap;
-    constructor(autoDataMappingBuilder: AutoDataMappingBuilder, dataNormalizers: DataNormalizerInterface<any, any>[], dataTransformerInterceptors: DataMappingInterceptorInterface[]);
+    /**
+     * Resolved error reporter — either the one passed to the constructor, or the built-in
+     * `console.error` fallback. Resolved once so the catch path doesn't ?? on every call.
+     */
+    private readonly errorReporter;
+    constructor(autoDataMappingBuilder: AutoDataMappingBuilder, dataNormalizers: DataNormalizerInterface<any, any>[], dataTransformerInterceptors: DataMappingInterceptorInterface[], 
+    /**
+     * Where `autoMap` should send errors when `logErrors: true` is set in the call options.
+     *
+     * Default: writes to `console.error`. Pass a custom function to route into your app's
+     * logger (e.g. the DI-wired DataMapper in `@pristine-ts/data-mapping` adapts this to
+     * `LogHandlerInterface`). Pass `() => {}` to silence reports even when `logErrors` is on.
+     */
+    errorReporter?: DataMapperErrorReporter);
     /**
      * This method takes an array of source and maps each item.
      *

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

@@ -1,15 +1,50 @@
 import { DataMappingNode } from "./data-mapping.node";
 import { DataMappingLeaf } from "./data-mapping.leaf";
+import { FluentLeafOptions } from "../interfaces/fluent-leaf-options.interface";
+import { FluentNestedOptions } from "../interfaces/fluent-nested-options.interface";
+import { FluentArrayOfObjectsOptions } from "../interfaces/fluent-array-of-objects-options.interface";
 export declare abstract class BaseDataMappingNode {
     nodes: {
         [sourceProperty in string]: DataMappingNode | DataMappingLeaf;
     };
+    abstract add(): DataMappingLeaf;
+    abstract addNestingLevel(): DataMappingNode;
+    abstract addArrayOfObjects(): DataMappingNode;
+    abstract addArrayOfScalar(): DataMappingLeaf;
     /**
-     * This method is called by the node itself to tell its parent that it has been build and is ready to be added.
-     * We use this mechanism to force the `end()` method on the leaf to be called so we can do some validations before
-     * adding it to the tree.
+     * Add a leaf mapping. `field(src)` is shorthand for `field(src, src)` (no rename).
      *
-     * @param node
+     * Equivalent to `.add().setSourceProperty(src).setDestinationProperty(dst).end()`, plus
+     * applying normalizer / optional / excludeNormalizers options.
+     */
+    field(source: string, destination?: string, options?: FluentLeafOptions): this;
+    /**
+     * Add a nested object mapping. The build callback receives the new node and configures its
+     * children — no explicit `.end()` needed; this method calls it for you when the callback
+     * returns.
+     */
+    nested(source: string, destination: string, build: (node: DataMappingNode) => void, options?: FluentNestedOptions): this;
+    /**
+     * Add an array-of-objects mapping. The build callback configures the per-element schema —
+     * every element in the source array is mapped through it. `destinationType` can be a class
+     * (uniform array) or a factory callback (polymorphic array).
+     */
+    arrayOfObjects(source: string, destination: string, build: (node: DataMappingNode) => void, options?: FluentArrayOfObjectsOptions): this;
+    /**
+     * Add an array-of-scalars mapping. Normalizers in `options` apply to every element of the
+     * array, not to the array itself. `arrayOfScalars(src)` is shorthand for same-name source
+     * and destination.
+     */
+    arrayOfScalars(source: string, destination?: string, options?: FluentLeafOptions): this;
+    /**
+     * Called by the node itself to tell its parent that it has been built and is ready to be
+     * added. We use this mechanism to force the `end()` method on the leaf to be called so we
+     * can do some validations before adding it to the tree.
      */
     addNode(node: DataMappingLeaf | DataMappingNode): void;
+    /**
+     * Shared between `field()` and `arrayOfScalars()` — both take the same options shape.
+     * Static helper so it can be called against either a freshly-built leaf or any leaf type.
+     */
+    private static applyLeafOptions;
 }

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

@@ -132,19 +132,19 @@ export declare class DataMappingNode extends BaseDataMappingNode {
      */
     private runSubNodes;
     /**
-     * This method imports a schema.
-     *
-     * @param schema
+     * Rehydrate this node from a previously-exported sub-schema. Children are rebuilt via
+     * `DataMappingSerializer.importChildren`, the same helper `DataMappingBuilder.import` uses
+     * (so the two stay consistent).
      */
     import(schema: any): void;
     /**
-     * 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.
+     * Export this node as a plain object. Does not mutate the live tree — the builder remains
+     * usable for mapping after this call returns.
      *
-     * `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()`.
+     * `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;

package/dist/types/reporters/console-error.reporter.d.ts

@@ -0,0 +1,16 @@
+import { DataMapperErrorReporter } from "../types/data-mapper-error-reporter.type";
+/**
+ * Built-in default reporter. Writes a header line + the error + a structured context payload
+ * to `console.error`. Used when no custom reporter is supplied to DataMapper — gives the
+ * frontend (and any non-DI caller) useful output out of the box.
+ *
+ * Exposed as a class-with-static-method so callers can compose it from their own reporters,
+ * e.g. `(err, ctx) => { sendToSentry(err); ConsoleErrorReporter.report(err, ctx); }`.
+ */
+export declare class ConsoleErrorReporter {
+    /**
+     * Matches the `DataMapperErrorReporter` shape so a method reference (`ConsoleErrorReporter.report`)
+     * can be passed wherever the callback type is expected.
+     */
+    static readonly report: DataMapperErrorReporter;
+}

package/dist/types/reporters/reporters.d.ts

@@ -0,0 +1 @@
+export * from "./console-error.reporter";

package/dist/types/serializers/data-mapping.serializer.d.ts

@@ -0,0 +1,46 @@
+import { DataMappingNode } from "../nodes/data-mapping.node";
+import { DataMappingLeaf } from "../nodes/data-mapping.leaf";
+import { DataMappingBuilder } from "../builders/data-mapping.builder";
+/**
+ * Pure helpers for serializing / deserializing the children-map shared between
+ * `DataMappingBuilder` and `DataMappingNode`.
+ *
+ * Both classes hold the same `{ [sourceProperty]: DataMappingNode | DataMappingLeaf }` shape
+ * and both need to walk it the same way during `import()` / `export()`. Keeping that walk in
+ * one place avoids the two implementations drifting apart (which they already had — see the
+ * old destination-property-leak bug).
+ *
+ * Stateless class-as-namespace per the project convention (no constructor dependencies, no
+ * instance state, so static methods make the call site read straight: `DataMappingSerializer.
+ * importChildren(...)`).
+ *
+ * Note on imports: this module is in a small cycle with `data-mapping.node.ts` — the
+ * serializer references Node and Leaf so it can instantiate them, and Node references the
+ * serializer so its `import()` / `export()` can delegate. The cycle resolves cleanly because
+ * the references are used only inside method bodies (not at module top level), so by the
+ * time anything runs both modules are fully evaluated.
+ */
+export declare class DataMappingSerializer {
+    /**
+     * Rebuild a populated children map from the `nodes` field of a serialized schema.
+     *
+     * Dispatches on the `_type` discriminator: ScalarArray + Leaf hydrate as `DataMappingLeaf`,
+     * Node + ObjectArray hydrate as `DataMappingNode`. The created child's own `import()` is
+     * called to fill in its fields and (for nodes) recurse into its own children.
+     */
+    static importChildren(root: DataMappingBuilder, parent: DataMappingBuilder | DataMappingNode, schemaNodes: {
+        [key: string]: any;
+    } | undefined): {
+        [sourceProperty: string]: DataMappingNode | DataMappingLeaf;
+    };
+    /**
+     * Serialize a children map back into a plain `nodes` object suitable for embedding in a
+     * schema export. Returns a fresh object — does not mutate the input, so callers can safely
+     * continue to use the live tree after exporting.
+     */
+    static exportChildren(nodes: {
+        [sourceProperty: string]: DataMappingNode | DataMappingLeaf;
+    }): {
+        [key: string]: any;
+    };
+}

package/dist/types/serializers/serializers.d.ts

@@ -0,0 +1 @@
+export * from "./data-mapping.serializer";

package/dist/types/types/data-mapper-error-reporter.type.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Callback the DataMapper invokes when `autoMap` swallows an error and `logErrors: true`
+ * is set on the options.
+ *
+ * Defined as a plain function type so `data-mapping-common` stays free of a logging-framework
+ * dependency — important because this package is consumed by frontend bundles (Angular, etc.)
+ * where pulling `@pristine-ts/logging` and its transitive deps in would add weight for no
+ * functional benefit.
+ *
+ * Wiring options:
+ *   - Pass nothing to DataMapper → errors print via the built-in `ConsoleErrorReporter`.
+ *   - Pass a custom reporter → errors go where you want them.
+ *   - Pass `() => {}` (no-op) → errors are silently dropped even when `logErrors: true`.
+ *
+ * The DI-wired DataMapper in `@pristine-ts/data-mapping` provides an adapter that routes
+ * into the framework's `LogHandlerInterface`.
+ */
+export type DataMapperErrorReporter = (error: Error, context: {
+    source: unknown;
+    destinationType: unknown;
+}) => void;

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

@@ -1,4 +1,5 @@
 export * from "./array-member-type-factory-callback.type";
+export * from "./data-mapper-error-reporter.type";
 export * from "./data-normalizer-unique-key.type";
 export * from "./data-mapping-interceptor-unique-key.type";
 export * from "./type-factory-callback.type";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/data-mapping-common",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "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.9",
+    "@pristine-ts/common": "^2.0.11",
     "@pristine-ts/metadata": "^1.0.16",
     "class-transformer": "^0.5.1",
     "date-fns": "^3.3.1"
@@ -63,7 +63,7 @@
       "jest-extended/all"
     ]
   },
-  "gitHead": "760994a87a1207f1670d31c67c6b8cde4c5b09f4",
+  "gitHead": "1e2fa6067d9eb4915a34400d03f2f3b896f03b2f",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",

package/readme.md

@@ -1 +1,43 @@
-# Data Mapping module.
+# @pristine-ts/data-mapping-common
+
+Framework-agnostic core for [`@pristine-ts/data-mapping`](../data-mapping). No DI container,
+no logging dependency — usable directly in Angular / browser bundles.
+
+## What's here
+
+- `DataMapper` — `autoMap`, `map`, `mapAll`
+- `AutoDataMappingBuilder` — schema inference from `@property` / `@array` decorators (with a `WeakMap` cache)
+- `DataMappingBuilder` — fluent schema construction (`field`, `nested`, `arrayOfObjects`, `arrayOfScalars`)
+- Built-in normalizers: `StringNormalizer`, `NumberNormalizer`, `BooleanNormalizer`, `DateNormalizer`, `LowercaseNormalizer`
+- `ConsoleErrorReporter` — default error sink that writes to `console.error`
+
+## Standalone usage
+
+```sh
+npm install @pristine-ts/data-mapping-common class-transformer
+```
+
+```ts
+import {
+  DataMapper, AutoDataMappingBuilder,
+  StringNormalizer, NumberNormalizer, BooleanNormalizer, DateNormalizer, LowercaseNormalizer,
+} from "@pristine-ts/data-mapping-common";
+
+const dataMapper = new DataMapper(
+  new AutoDataMappingBuilder(),
+  [new StringNormalizer(), new NumberNormalizer(), new BooleanNormalizer(), new DateNormalizer(), new LowercaseNormalizer()],
+  [],
+);
+
+const user = await dataMapper.autoMap(payload, User);
+```
+
+Errors go to `console.error` by default. Pass a custom `DataMapperErrorReporter` to the
+constructor to redirect them.
+
+## Backend / DI usage
+
+If you're inside a Pristine app, import [`@pristine-ts/data-mapping`](../data-mapping)
+instead — it wires `DataMapper` into the DI container, registers the built-in normalizers,
+and routes errors through `LogHandlerInterface`. **See [`@pristine-ts/data-mapping`](../data-mapping)
+for the full API reference** — everything documented there is also exported from this package.