feat: Add enum value-level descriptions and deprecation metadata

Author: javan-b

@generated/user/user-update-without-articles.input.ts

@@ -15,54 +15,55 @@ import { ProfileUpdateOneWithoutUserNestedInput } from '../profile/profile-updat
 
 @InputType()
 export class UserUpdateWithoutArticlesInput {
-  @Field(() => StringFieldUpdateOperationsInput, { nullable: true })
-  id?: StringFieldUpdateOperationsInput;
 
-  @Field(() => StringFieldUpdateOperationsInput, { nullable: true })
-  email?: StringFieldUpdateOperationsInput;
+    @Field(() => StringFieldUpdateOperationsInput, {nullable:true})
+    id?: StringFieldUpdateOperationsInput;
 
-  @Field(() => StringFieldUpdateOperationsInput, { nullable: true })
-  name?: StringFieldUpdateOperationsInput;
+    @Field(() => StringFieldUpdateOperationsInput, {nullable:true})
+    email?: StringFieldUpdateOperationsInput;
 
-  @Field(() => StringFieldUpdateOperationsInput, { nullable: true })
-  password?: StringFieldUpdateOperationsInput;
+    @Field(() => StringFieldUpdateOperationsInput, {nullable:true})
+    name?: StringFieldUpdateOperationsInput;
 
-  @Field(() => NullableStringFieldUpdateOperationsInput, { nullable: true })
-  bio?: NullableStringFieldUpdateOperationsInput;
+    @Field(() => StringFieldUpdateOperationsInput, {nullable:true})
+    password?: StringFieldUpdateOperationsInput;
 
-  @Field(() => NullableStringFieldUpdateOperationsInput, { nullable: true })
-  image?: NullableStringFieldUpdateOperationsInput;
+    @Field(() => NullableStringFieldUpdateOperationsInput, {nullable:true})
+    bio?: NullableStringFieldUpdateOperationsInput;
 
-  @Field(() => NullableIntFieldUpdateOperationsInput, { nullable: true })
-  countComments?: NullableIntFieldUpdateOperationsInput;
+    @Field(() => NullableStringFieldUpdateOperationsInput, {nullable:true})
+    image?: NullableStringFieldUpdateOperationsInput;
 
-  @Field(() => NullableFloatFieldUpdateOperationsInput, { nullable: true })
-  rating?: NullableFloatFieldUpdateOperationsInput;
+    @Field(() => NullableIntFieldUpdateOperationsInput, {nullable:true})
+    countComments?: NullableIntFieldUpdateOperationsInput;
 
-  @Field(() => NullableDecimalFieldUpdateOperationsInput, { nullable: true })
-  @Type(() => NullableDecimalFieldUpdateOperationsInput)
-  money?: NullableDecimalFieldUpdateOperationsInput;
+    @Field(() => NullableFloatFieldUpdateOperationsInput, {nullable:true})
+    rating?: NullableFloatFieldUpdateOperationsInput;
 
-  @Field(() => NullableEnumRoleFieldUpdateOperationsInput, { nullable: true })
-  role?: NullableEnumRoleFieldUpdateOperationsInput;
+    @Field(() => NullableDecimalFieldUpdateOperationsInput, {nullable:true})
+    @Type(() => NullableDecimalFieldUpdateOperationsInput)
+    money?: NullableDecimalFieldUpdateOperationsInput;
 
-  @Field(() => UserUpdateManyWithoutFollowersNestedInput, { nullable: true })
-  @Type(() => UserUpdateManyWithoutFollowersNestedInput)
-  following?: UserUpdateManyWithoutFollowersNestedInput;
+    @Field(() => NullableEnumRoleFieldUpdateOperationsInput, {nullable:true})
+    role?: NullableEnumRoleFieldUpdateOperationsInput;
 
-  @Field(() => UserUpdateManyWithoutFollowingNestedInput, { nullable: true })
-  @Type(() => UserUpdateManyWithoutFollowingNestedInput)
-  followers?: UserUpdateManyWithoutFollowingNestedInput;
+    @Field(() => UserUpdateManyWithoutFollowersNestedInput, {nullable:true})
+    @Type(() => UserUpdateManyWithoutFollowersNestedInput)
+    following?: UserUpdateManyWithoutFollowersNestedInput;
 
-  @Field(() => ArticleUpdateManyWithoutFavoritedByNestedInput, { nullable: true })
-  @Type(() => ArticleUpdateManyWithoutFavoritedByNestedInput)
-  favoriteArticles?: ArticleUpdateManyWithoutFavoritedByNestedInput;
+    @Field(() => UserUpdateManyWithoutFollowingNestedInput, {nullable:true})
+    @Type(() => UserUpdateManyWithoutFollowingNestedInput)
+    followers?: UserUpdateManyWithoutFollowingNestedInput;
 
-  @Field(() => CommentUpdateManyWithoutAuthorNestedInput, { nullable: true })
-  @Type(() => CommentUpdateManyWithoutAuthorNestedInput)
-  comments?: CommentUpdateManyWithoutAuthorNestedInput;
+    @Field(() => ArticleUpdateManyWithoutFavoritedByNestedInput, {nullable:true})
+    @Type(() => ArticleUpdateManyWithoutFavoritedByNestedInput)
+    favoriteArticles?: ArticleUpdateManyWithoutFavoritedByNestedInput;
 
-  @Field(() => ProfileUpdateOneWithoutUserNestedInput, { nullable: true })
-  @Type(() => ProfileUpdateOneWithoutUserNestedInput)
-  profile?: ProfileUpdateOneWithoutUserNestedInput;
+    @Field(() => CommentUpdateManyWithoutAuthorNestedInput, {nullable:true})
+    @Type(() => CommentUpdateManyWithoutAuthorNestedInput)
+    comments?: CommentUpdateManyWithoutAuthorNestedInput;
+
+    @Field(() => ProfileUpdateOneWithoutUserNestedInput, {nullable:true})
+    @Type(() => ProfileUpdateOneWithoutUserNestedInput)
+    profile?: ProfileUpdateOneWithoutUserNestedInput;
 }

prisma/schema.prisma

@@ -104,11 +104,19 @@ model Comment {
   articleId String?
 }
 
+/// user access control
 enum Role {
+  /// default user access control
   USER
+  /// have full access control
+  NINGA
+  /// @deprecated Use USER instead
+  ADMIN
+  REVIEWER // no comment and won't show in registerenum valuemaps
 }
 
 model Profile {
+  /// @deprecated Use new name instead
   id     Int     @id @default(autoincrement())
   user   User    @relation(fields: [userId], references: [id])
   userId String  @unique

src/handlers/prisma-enum-doc.ts

@@ -0,0 +1,24 @@
+// utils/prisma-enum-doc.ts
+
+type EnumValueDocInfo = { description: string } | { deprecationReason: string };
+
+export function extractEnumValueDocs(
+  values: readonly { name: string; [key: string]: any }[],
+): Record<string, EnumValueDocInfo> {
+  return Object.fromEntries(
+    values
+      .map((value): [string, EnumValueDocInfo] | null => {
+        const { name } = value;
+        const documentation: unknown = value.documentation;
+
+        if (typeof documentation !== 'string') return null;
+
+        if (documentation.startsWith('@deprecated')) {
+          return [name, { deprecationReason: documentation.slice(11).trim() }];
+        }
+
+        return [name, { description: documentation }];
+      })
+      .filter((entry): entry is [string, EnumValueDocInfo] => entry !== null),
+  );
+}

src/handlers/register-enum.ts

@@ -2,13 +2,15 @@ import { EnumDeclarationStructure, StructureKind } from 'ts-morph';
 
 import { ImportDeclarationMap } from '../helpers/import-declaration-map';
 import { EventArguments, SchemaEnum } from '../types';
+import { extractEnumValueDocs } from './prisma-enum-doc';
 
 export function registerEnum(enumType: SchemaEnum, args: EventArguments) {
-  const { getSourceFile, enums, config } = args;
+  const { config, enums, getSourceFile } = args;
 
   if (!config.emitBlocks.prismaEnums && !enums[enumType.name]) return;
 
   const dataModelEnum = enums[enumType.name];
+  const enumTypesData = dataModelEnum?.values || [];
   const sourceFile = getSourceFile({
     name: enumType.name,
     type: 'enum',
@@ -17,10 +19,25 @@ export function registerEnum(enumType: SchemaEnum, args: EventArguments) {
   const importDeclarations = new ImportDeclarationMap();
 
   importDeclarations.set('registerEnumType', {
-    namedImports: [{ name: 'registerEnumType' }],
     moduleSpecifier: '@nestjs/graphql',
+    namedImports: [{ name: 'registerEnumType' }],
   });
 
+  // Extract valuesMap from enum documentation
+  const valuesMap = extractEnumValueDocs(enumTypesData);
+
+  // Remove entries with no description or deprecationReason
+  const filteredValuesMap = Object.fromEntries(
+    Object.entries(valuesMap).filter(([_, v]) => Object.keys(v).length > 0),
+  );
+
+  // Format only if needed
+  const hasValuesMap = Object.keys(filteredValuesMap).length > 0;
+  const formattedValuesMap = hasValuesMap
+    ? JSON.stringify(filteredValuesMap, null, 2).replace(/"([^"]+)":/g, '$1:')
+    : '';
+  const valuesMapEntry = hasValuesMap ? `, valuesMap: ${formattedValuesMap}` : '';
+
   const enumStructure: EnumDeclarationStructure = {
     kind: StructureKind.Enum,
     isExported: true,
@@ -36,9 +53,9 @@ export function registerEnum(enumType: SchemaEnum, args: EventArguments) {
       ...importDeclarations.toStatements(),
       enumStructure,
       '\n',
-      `registerEnumType(${enumType.name}, { name: '${
-        enumType.name
-      }', description: ${JSON.stringify(dataModelEnum?.documentation)} })`,
+      `registerEnumType(${enumType.name}, { name: '${enumType.name}', description: ${JSON.stringify(
+        dataModelEnum?.documentation,
+      )}${valuesMapEntry} })`,
     ],
   });
 }