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

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

@@ -9,4 +9,5 @@ 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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/data-mapping-common",
-  "version": "2.0.10",
+  "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.10",
+    "@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": "3d0126d73d7a0dec99fcda3824981d893d1d0662",
+  "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.