docs(core): add autoMap mapping configuration docs (#539)

nartc · Jan 22, 2024 · d92f62f · d92f62f
1 parent 4b03318
commit d92f62f
Show file tree

Hide file tree

Showing 10 changed files with 110 additions and 16 deletions.
diff --git a/packages/documentations/docs/api/core/modules.md b/packages/documentations/docs/api/core/modules.md
@@ -901,6 +901,35 @@ ___
 
 ___
 
+### autoMap
+
+▸ **autoMap**<`TSource`, `TDestination`, `TKey`, `TValue`\>(`prop`): [`MappingConfiguration`](modules.md#mappingconfiguration)<`TSource`, `TDestination`\>
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `TSource` | extends { [key in `TKey`]: `TValue` } |
+| `TDestination` | extends { [key in `TKey`]: `TValue` } |
+| `TKey` | extends keyof `TSource` & keyof `TDestination` |
+| `TValue` | extends `TSource`[`TKey`] & `TDestination`[`TKey`] |
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `prop` | `TKey` |
+
+#### Returns
+
+[`MappingConfiguration`](modules.md#mappingconfiguration)<`TSource`, `TDestination`\>
+
+#### Defined in
+
+[lib/mapping-configurations/auto-map.ts:6](https://github.com/nartc/mapper/blob/5906addd/packages/core/src/lib/mapping-configurations/auto-map.ts#L6)
+
+___
+
 ### beforeMap
 
 ▸ **beforeMap**<`TSource`, `TDestination`\>(`cb`): [`MappingConfiguration`](modules.md#mappingconfiguration)<`TSource`, `TDestination`\>

diff --git a/packages/documentations/docs/mapping-configuration/auto-map.mdx b/packages/documentations/docs/mapping-configuration/auto-map.mdx
@@ -0,0 +1,63 @@
+---
+id: auto-map
+title: AutoMap
+sidebar_label: AutoMap
+sidebar_position: 3
+---
+
+`autoMap()` is an alternative to the the `@AutoMap()` decorator. It trivially maps a property with the **same name and type** on the `Source` and `Destination` objects.
+
+## Decoratorless entities and DTOs
+
+Use this specially when your entities and DTOs cannot have the `@AutoMap()` decorator (e.g. when using **constructor assignments**), or when you would rather avoid them:
+
+```ts
+import {
+    autoMap,
+    createMap,
+    forMember,
+    mapFrom,
+    Mapper,
+} from '@automapper/core';
+
+export class DecoratorlessUserEntity {
+    constructor(
+        public readonly firstName: string,
+        public readonly lastName: string,
+        public readonly birthday: Date
+    ) {}
+}
+
+export class DecoratorlessUserDto {
+    firstName!: string;
+    lastName!: string;
+    birthday!: string;
+    fullName!: string;
+}
+
+export function decoratorlessUserProfile(mapper: Mapper) {
+    createMap(
+        mapper,
+        DecoratorlessUserEntity,
+        DecoratorlessUserDto,
+        // Use `autoMap()` on properties that can be trivially mapped.
+        autoMap('firstName'),
+        autoMap('lastName'),
+
+        // Use more elaborate mapping configurations when necessary:
+
+        // 'birthday' exists on both `Source` and `Destination`, but with
+        // different types.
+        forMember(
+          (d) => d.birthday,
+            mapFrom((s) => s.birthday.toDateString())
+        ),
+
+        // 'fullName' doesn't exist on `Source` and must be mapped manually.
+        forMember(
+            (d) => d.fullName,
+            mapFrom((s) => `${s.firstName} ${s.lastName}`)
+        )
+    );
+}
+```
diff --git a/packages/documentations/docs/mapping-configuration/before-map.mdx b/packages/documentations/docs/mapping-configuration/before-map.mdx
@@ -2,7 +2,7 @@
 id: before-map
 title: BeforeMap
 sidebar_label: BeforeMap
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 As the name suggests, `beforeMap()` sets up a `MapCallback` to be called **before** the map operation.

diff --git a/packages/documentations/docs/mapping-configuration/construct-using.mdx b/packages/documentations/docs/mapping-configuration/construct-using.mdx
@@ -2,7 +2,7 @@
 id: construct-using
 title: ConstructUsing
 sidebar_label: ConstructUsing
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 Call `constructUsing()` and pass in a `DestinationConstructor` to customize how AutoMapper should construct the `Destination` before every map operation against that `Destination`.

diff --git a/packages/documentations/docs/mapping-configuration/extend.mdx b/packages/documentations/docs/mapping-configuration/extend.mdx
@@ -2,7 +2,7 @@
 id: extend
 title: Extend
 sidebar_label: Extend
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 Call `extend()` and pass in either a `Mapping` or a pair of models to tell AutoMapper to extend the `MappingProperties` to the `Mapping` we are creating

diff --git a/packages/documentations/docs/mapping-configuration/for-self.mdx b/packages/documentations/docs/mapping-configuration/for-self.mdx
@@ -2,7 +2,7 @@
 id: for-self
 title: ForSelf
 sidebar_label: ForSelf
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 In previous sections, we've learned that we can have [Auto Flattening](../fundamentals/auto-flattening) with [Naming Conventions](../fundamentals/naming-convention).

diff --git a/packages/documentations/docs/mapping-configuration/naming-conventions.mdx b/packages/documentations/docs/mapping-configuration/naming-conventions.mdx
@@ -2,7 +2,7 @@
 id: naming-conventions
 title: NamingConventions
 sidebar_label: NamingConventions
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 Call `namingConventions()` and pass in a `NamingConventionInput` to customize the Mapping's [NamingConvention](../fundamentals/naming-convention)

diff --git a/packages/documentations/docs/mapping-configuration/overview.mdx b/packages/documentations/docs/mapping-configuration/overview.mdx
@@ -71,16 +71,17 @@ In addition, there is [Auto Flattening](../fundamentals/auto-flattening). These
 
 `MappingConfiguration` are functions that augment a `Mapping`. When creating a `Mapping` with `createMap()`, we can pass in as many `MappingConfiguration` as we like and in any order that we want.
 
-| mapping configuration | description                                                             |
-| --------------------- | ----------------------------------------------------------------------- |
-| `afterMap()`          | Attach a `MapCallback` to run after the map operation                   |
-| `beforeMap()`         | Attach a `MapCallback` to run before the map operation                  |
-| `constructUsing()`    | Set a custom constructor for the `Destination` before the map operation |
-| `extend()`            | Extend another `Mapping`                                                |
-| `forMember()`         | Configure a `MappingTransformation` for a property on the `Destination` |
-| `forSelf()`           | Configure flattening for `Destination` from a different `Source`        |
-| `namingConventions()` | Configure the `NamingConvention` for this `Mapping`                     |
-| `typeConverters()`    | Configure the `TypeConverter` for this `Mapping`                        |
+| mapping configuration | description                                                                                                        |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `afterMap()`          | Attach a `MapCallback` to run after the map operation                                                              |
+| `autoMap()`           | Alternative to the `@AutoMap` decorator. Maps a property with same name and type on the `Source` and `Destination` |
+| `beforeMap()`         | Attach a `MapCallback` to run before the map operation                                                             |
+| `constructUsing()`    | Set a custom constructor for the `Destination` before the map operation                                            |
+| `extend()`            | Extend another `Mapping`                                                                                           |
+| `forMember()`         | Configure a `MappingTransformation` for a property on the `Destination`                                            |
+| `forSelf()`           | Configure flattening for `Destination` from a different `Source`                                                   |
+| `namingConventions()` | Configure the `NamingConvention` for this `Mapping`                                                                |
+| `typeConverters()`    | Configure the `TypeConverter` for this `Mapping`                                                                   |
 
 :::caution
 

diff --git a/packages/documentations/docs/mapping-configuration/type-converters.mdx b/packages/documentations/docs/mapping-configuration/type-converters.mdx
@@ -2,7 +2,7 @@
 id: type-converters
 title: TypeConverters
 sidebar_label: TypeConverters
-sidebar_position: 9
+sidebar_position: 10
 ---
 
 ## What is Type Converter?

diff --git a/packages/documentations/sidebars.js b/packages/documentations/sidebars.js
@@ -42,6 +42,7 @@ const sidebars = {
             items: [
                 'mapping-configuration/overview',
                 'mapping-configuration/after-map',
+                'mapping-configuration/auto-map',
                 'mapping-configuration/before-map',
                 'mapping-configuration/construct-using',
                 'mapping-configuration/extend',