feat(classes): add logic to handle @autoMapIgnore JSDoc comment

Adding JSDoc tag @autoMapIgnore to a property will allow the Transformer Plugin to skip that property fix #395
nartc · Jan 6, 2022 · 2de6893 · 2de6893
1 parent 3f2bb0e
commit 2de6893
Show file tree

Hide file tree

Showing 3 changed files with 53 additions and 10 deletions.
diff --git a/docs-site/docs/plugins-system/classes-transformer-plugin.md b/docs-site/docs/plugins-system/classes-transformer-plugin.md
@@ -123,6 +123,22 @@ Currently, `@automapper/classes/experimental/transformer-plugin` will handle mos
 
 As mentioned above, this is utilizing an experimental feature of TypeScript. Hence, you need to modify the build step of your project to use `@automapper/classes/experimental/transformer-plugin`
 
+### Ignore a property
+
+The plugin will automatically construct the metadata for all properties that aren't decorated with `@AutoMap`. However, there are also cases where you neither want `@AutoMap` nor having the plugin processing a property (eg: you want to take the control 100% with manual configuration). To ignore a property completely, you can use a JSDoc tag `@autoMapIgnore` on a property
+
+```ts
+class User {
+  firstName: string;
+  lastName: string;
+  profile: Profile;
+  /**
+   * @autoMapIgnore
+   */
+  ignoreMe: string;
+}
+```
+
 ### Options
 
 ```ts

diff --git a/packages/classes/experimental/transformer-plugin/src/lib/model-visitor.ts b/packages/classes/experimental/transformer-plugin/src/lib/model-visitor.ts
@@ -1,10 +1,17 @@
 import { AUTOMAPPER_METADATA_FACTORY_KEY } from '@automapper/classes';
-import type {
+import {
   ArrowFunction,
   ClassDeclaration,
   GetAccessorDeclaration,
+  getAllJSDocTags,
   Identifier,
   ImportDeclaration,
+  isClassDeclaration,
+  isGetAccessorDeclaration,
+  isImportDeclaration,
+  isPropertyDeclaration,
+  JSDocTag,
+  ModuleKind,
   NodeArray,
   NodeFactory,
   ObjectLiteralExpression,
@@ -14,21 +21,14 @@ import type {
   SourceFile,
   Statement,
   StringLiteral,
+  SyntaxKind,
   TransformationContext,
   Type,
   TypeChecker,
   TypeReferenceNode,
-  Visitor,
-} from 'typescript/lib/tsserverlibrary';
-import {
-  isClassDeclaration,
-  isGetAccessorDeclaration,
-  isImportDeclaration,
-  isPropertyDeclaration,
-  ModuleKind,
-  SyntaxKind,
   visitEachChild,
   visitNode,
+  Visitor,
 } from 'typescript/lib/tsserverlibrary';
 import {
   hasPropertyKey,
@@ -106,6 +106,17 @@ export class ModelVisitor {
             return node;
           }
 
+          if (node['jsDoc']) {
+            const ignoreTag = getAllJSDocTags(
+              node['jsDoc'],
+              (tag): tag is JSDocTag =>
+                tag.tagName.escapedText === 'autoMapIgnore'
+            );
+            if (ignoreTag) {
+              return node;
+            }
+          }
+
           ModelVisitor.inspectNode(
             ctx.factory,
             node,

diff --git a/packages/integration-test/src/lib/transformer-plugin/fixtures/user.model.ts b/packages/integration-test/src/lib/transformer-plugin/fixtures/user.model.ts
@@ -40,6 +40,10 @@ export class User {
   maybePrimitives?: string[];
   nullablePrimitives: string[] | null;
   maybeType?: Address;
+  /**
+   * @autoMapIgnore
+   */
+  ignoreMe: string;
 }
 `;
 
@@ -85,6 +89,10 @@ export class User {
   maybePrimitives?: string[];
   nullablePrimitives!: string[] | null;
   maybeType?: Address;
+  /**
+   * @autoMapIgnore
+   */
+  ignoreMe: string;
 }
 `;
 
@@ -140,6 +148,10 @@ class User {
     maybePrimitives;
     nullablePrimitives;
     maybeType;
+    /**
+     * @autoMapIgnore
+     */
+    ignoreMe;
     static __AUTOMAPPER_METADATA_FACTORY__() {
         return [["firstName", { typeFn: () => String }], ["lastName", { typeFn: () => String }], ["profile", { typeFn: () => Profile, depth: 0 }], ["addresses", { typeFn: () => Address, depth: 0 }], ["otherAddresses", { typeFn: () => Address, depth: 0 }], ["flag", { typeFn: () => Boolean }], ["foo", { typeFn: () => null, depth: 0 }], ["nullable", { typeFn: () => String }], ["primitives", { typeFn: () => String }], ["nullableType", { typeFn: () => Address, depth: 0 }], ["maybePrimitives", { typeFn: () => String }], ["nullablePrimitives", { typeFn: () => String }], ["maybeType", { typeFn: () => Address, depth: 0 }]];
     }
@@ -196,6 +208,10 @@ export class User {
     maybePrimitives;
     nullablePrimitives;
     maybeType;
+    /**
+     * @autoMapIgnore
+     */
+    ignoreMe;
     static __AUTOMAPPER_METADATA_FACTORY__() {
         return [["firstName", { typeFn: () => String }], ["lastName", { typeFn: () => String }], ["profile", { typeFn: () => Profile, depth: 0 }], ["addresses", { typeFn: () => Address, depth: 0 }], ["otherAddresses", { typeFn: () => Address, depth: 0 }], ["flag", { typeFn: () => Boolean }], ["foo", { typeFn: () => null, depth: 0 }], ["nullable", { typeFn: () => String }], ["primitives", { typeFn: () => String }], ["nullableType", { typeFn: () => Address, depth: 0 }], ["maybePrimitives", { typeFn: () => String }], ["nullablePrimitives", { typeFn: () => String }], ["maybeType", { typeFn: () => Address, depth: 0 }]];
     }