generate references (#7882)

www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts

@@ -126,6 +126,7 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
       "**/pricing/builders.ts",
       "**/search/**",
       "**/totals/**",
+      "**/dml/**",
     ],
   }),
   workflows: getOptions({

www/utils/packages/typedoc-generate-references/src/constants/references-details.ts

@@ -25,4 +25,4 @@ export const customModulesOptions: Record<string, Partial<TypeDocOptions>> = {
 }
 
 // a list of modules that now support DML
-export const dmlModules = ["currency"]
+export const dmlModules = ["currency", "region"]

www/utils/packages/typedoc-plugin-custom/src/constants.ts

@@ -1 +0,0 @@
-export const RELATION_NAMES = ["HasOne", "HasMany", "BelongsTo", "ManyToMany"]

www/utils/packages/typedoc-plugin-custom/src/dml-relations-resolver.ts

@@ -6,8 +6,7 @@ import {
   ParameterType,
   ReferenceType,
 } from "typedoc"
-import { getDmlProperties, isDmlEntity } from "utils"
-import { RELATION_NAMES } from "./constants"
+import { RELATION_NAMES, getDmlProperties, isDmlEntity } from "utils"
 
 export class DmlRelationsResolver {
   private app: Application
@@ -15,10 +14,15 @@ export class DmlRelationsResolver {
     reflection: DeclarationReflection
     properties: DeclarationReflection[]
   }[]
+  private relationProperties: {
+    property: DeclarationReflection
+    target: DeclarationReflection
+  }[]
 
   constructor(app: Application) {
     this.app = app
     this.dmlReflectionsAndProperties = []
+    this.relationProperties = []
 
     this.app.options.addDeclaration({
       name: "resolveDmlRelations",
@@ -34,8 +38,15 @@ export class DmlRelationsResolver {
 
     this.app.converter.on(
       Converter.EVENT_RESOLVE_BEGIN,
-      this.resolveRelations.bind(this)
+      this.resolveRelationReferences.bind(this),
+      1
     )
+
+    // this.app.converter.on(
+    //   Converter.EVENT_RESOLVE_BEGIN,
+    //   this.resolveRelationTargets.bind(this),
+    //   -1
+    // )
   }
 
   addReflection(_context: Context, reflection: DeclarationReflection) {
@@ -50,10 +61,11 @@ export class DmlRelationsResolver {
     }
   }
 
-  resolveRelations(context: Context) {
+  resolveRelationReferences(context: Context) {
     if (!this.app.options.getValue("resolveDmlRelations")) {
       return
     }
+
     this.dmlReflectionsAndProperties.forEach(({ properties }) => {
       properties.forEach((property) => {
         if (
@@ -90,10 +102,32 @@ export class DmlRelationsResolver {
             context.project
           ),
         ]
+        this.relationProperties.push({
+          property,
+          target: relatedReflection,
+        })
       })
     })
   }
 
+  resolveRelationTargets(context: Context) {
+    if (!this.app.options.getValue("resolveDmlRelations")) {
+      return
+    }
+    this.relationProperties.forEach(({ property, target }) => {
+      const targetSymbol = context.project.getSymbolFromReflection(target)
+      if (property.type?.type !== "reference" || !targetSymbol) {
+        return
+      }
+      // change reference to the target itself.
+      property.type = ReferenceType.createResolvedReference(
+        `DmlEntity`,
+        target,
+        context.project
+      )
+    })
+  }
+
   findReflectionMatchingProperties(
     properties: DeclarationReflection[]
   ): DeclarationReflection | undefined {

www/utils/packages/typedoc-plugin-custom/src/dml-types-normalizer.ts

@@ -4,11 +4,8 @@ import {
   Converter,
   DeclarationReflection,
   ParameterType,
-  ReferenceType,
   ReflectionFlag,
-  ReflectionKind,
 } from "typedoc"
-import { getDmlProperties, isDmlEntity } from "utils"
 
 export function load(app: Application) {
   app.options.addDeclaration({
@@ -18,52 +15,33 @@ export function load(app: Application) {
     defaultValue: false,
   })
 
-  app.converter.on(Converter.EVENT_RESOLVE_BEGIN, (context: Context) => {
-    if (!app.options.getValue("normalizeDmlTypes")) {
-      return
-    }
-
-    for (const reflection of context.project.getReflectionsByKind(
-      ReflectionKind.Variable
-    )) {
-      if (
-        !(reflection instanceof DeclarationReflection) ||
-        !isDmlEntity(reflection)
-      ) {
-        break
-      }
-
-      const properties = getDmlProperties(reflection.type as ReferenceType)
-
-      properties.forEach((property) => {
-        if (property.type?.type !== "reference") {
-          return
-        }
-
-        normalizeNullable(property)
-      })
-    }
-  })
+  app.converter.on(
+    Converter.EVENT_CREATE_DECLARATION,
+    (_context: Context, reflection: DeclarationReflection) => {
+      normalizeNullable(reflection)
+    },
+    2
+  )
 }
 
-function normalizeNullable(property: DeclarationReflection) {
-  const propertyReference = property.type as ReferenceType
+function normalizeNullable(reflection: DeclarationReflection) {
   if (
-    propertyReference.name !== "NullableModifier" ||
-    !propertyReference.typeArguments ||
-    propertyReference.typeArguments?.length < 2
+    reflection.type?.type !== "reference" ||
+    reflection.type.name !== "NullableModifier" ||
+    !reflection.type.typeArguments ||
+    reflection.type.typeArguments?.length < 2
   ) {
     return
   }
 
-  const actualType = propertyReference.typeArguments[1]
+  const actualType = reflection.type.typeArguments[1]
 
   if (actualType.type !== "reference") {
     return
   }
 
   // change the property's type to reference the actual type
-  property.type = actualType
+  reflection.type = actualType
   // set a flag on the property to consider it optional
-  property.setFlag(ReflectionFlag.Optional)
+  reflection.setFlag(ReflectionFlag.Optional)
 }

www/utils/packages/typedoc-plugin-custom/src/mermaid-diagram-dml-generator.ts

@@ -11,8 +11,7 @@ import {
   ReflectionKind,
   TypeDocOptionMap,
 } from "typedoc"
-import { RELATION_NAMES } from "./constants"
-import { getDmlProperties, isDmlEntity } from "utils"
+import { RELATION_NAMES, getDmlProperties, isDmlEntity } from "utils"
 
 type Relations = Map<
   string,

www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts

@@ -10,9 +10,11 @@ import * as Handlebars from "handlebars"
 import { stripCode } from "../utils"
 import { Parameter, ParameterStyle, ReflectionParameterType } from "../types"
 import {
+  getDmlRelationProperties,
   getReflectionType,
   getType,
   getTypeChildren,
+  isDmlRelation,
   stripLineBreaks,
 } from "utils"
 import { MarkdownTheme } from "../theme"
@@ -153,6 +155,10 @@ export function reflectionComponentFormatter({
     children: [],
   }
 
+  if (level + 1 > (maxLevel || MarkdownTheme.MAX_LEVEL)) {
+    return componentItem
+  }
+
   const hasChildren = "children" in reflection && reflection.children?.length
 
   if (reflection.variant === "declaration" && isDmlEntity(reflection)) {
@@ -167,9 +173,20 @@ export function reflectionComponentFormatter({
       })
     )
   } else if (
-    (reflection.type || hasChildren) &&
-    level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)
+    reflection.variant === "declaration" &&
+    isDmlRelation(reflection)
   ) {
+    componentItem.children = getDmlRelationProperties(
+      reflection.type as ReferenceType
+    ).map((childItem) =>
+      reflectionComponentFormatter({
+        reflection: childItem,
+        level: level + 1,
+        maxLevel,
+        project,
+      })
+    )
+  } else if (reflection.type || hasChildren) {
     const children = hasChildren
       ? reflection.children
       : getTypeChildren({

www/utils/packages/utils/src/dml-utils.ts

@@ -8,9 +8,29 @@ export function isDmlEntity(reflection: DeclarationReflection) {
   return reflection.type.name === "DmlEntity"
 }
 
+export const RELATION_NAMES = ["HasOne", "HasMany", "BelongsTo", "ManyToMany"]
+
+export function isDmlRelation(reflection: DeclarationReflection) {
+  if (reflection.type?.type !== "reference") {
+    return false
+  }
+
+  const reflectionType = reflection.type
+
+  return RELATION_NAMES.some((relatioName) =>
+    reflectionType.name.startsWith(relatioName)
+  )
+}
+
+const MAX_LEVEL = 2
+
 export function getDmlProperties(
-  reflectionType: ReferenceType
+  reflectionType: ReferenceType,
+  level = 1
 ): DeclarationReflection[] {
+  if (level > MAX_LEVEL) {
+    return []
+  }
   if (
     !reflectionType.typeArguments?.length ||
     reflectionType.typeArguments[0].type !== "intersection"
@@ -22,3 +42,21 @@ export function getDmlProperties(
 
   return schemaType.declaration.children || []
 }
+
+export function getDmlRelationProperties(
+  reflectionType: ReferenceType
+): DeclarationReflection[] {
+  if (
+    !reflectionType.typeArguments?.length ||
+    reflectionType.typeArguments[0].type !== "reference" ||
+    !(
+      reflectionType.typeArguments[0].reflection instanceof
+      DeclarationReflection
+    ) ||
+    reflectionType.typeArguments[0].reflection.type?.type !== "reference"
+  ) {
+    return []
+  }
+
+  return getDmlProperties(reflectionType.typeArguments[0].reflection.type)
+}