feat(parser): support generics in type parsing (#668)

* feat(parser): support basic TypeScript generics in markdown links

* test(parser): add coverage for basic generic types

* feat(parser): support inner union types and multi-parameters in generics

* style(parser): apply reviewer feedback (move functions, extract regex, cleanup fallback)

* fix(parser): use regex for array suffix and fix test spacing

* refactor(parser): move generic regex to constants file per reviewer feedback

* chore: remove deprecated constants file resurrected during merge

Author: moshams272

src/generators/metadata/constants.mjs

@@ -73,6 +73,9 @@ export const DOC_API_HEADING_TYPES = [
   },
 ];
 
+// This regex is used to match basic TypeScript generic types (e.g., Promise<string>)
+export const TYPE_GENERIC_REGEX = /^([^<]+)<([^>]+)>$/;
+
 // This is a mapping for types within the Markdown content and their respective
 // JavaScript primitive types within the MDN JavaScript docs
 // @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Data_structures#primitive_values

src/generators/metadata/utils/__tests__/transformers.mjs

@@ -26,4 +26,39 @@ describe('transformTypeToReferenceLink', () => {
       '[`<SomeOtherType>`](fromTypeMap)'
     );
   });
+
+  it('should transform a basic Generic type into a Markdown link', () => {
+    strictEqual(
+      transformTypeToReferenceLink('{Promise<string>}'),
+      '[`<Promise>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[`<string>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)&gt;'
+    );
+  });
+
+  it('should partially transform a Generic type if only one part is known', () => {
+    strictEqual(
+      transformTypeToReferenceLink('{CustomType<string>}', {}),
+      '`<CustomType>`&lt;[`<string>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)&gt;'
+    );
+  });
+
+  it('should transform a Generic type with an inner union like {Promise<string|boolean>}', () => {
+    strictEqual(
+      transformTypeToReferenceLink('{Promise<string|boolean>}', {}),
+      '[`<Promise>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[`<string>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) | [`<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type)&gt;'
+    );
+  });
+
+  it('should transform multi-parameter generics like {Map<string, number>}', () => {
+    strictEqual(
+      transformTypeToReferenceLink('{Map<string, number>}', {}),
+      '[`<Map>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)&lt;[`<string>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type), [`<number>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)&gt;'
+    );
+  });
+
+  it('should handle outer unions with generics like {Promise<string|number> | boolean}', () => {
+    strictEqual(
+      transformTypeToReferenceLink('{Promise<string|number> | boolean}', {}),
+      '[`<Promise>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[`<string>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) | [`<number>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)&gt; | [`<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type)'
+    );
+  });
 });

src/generators/metadata/utils/transformers.mjs

@@ -1,4 +1,3 @@
-import { transformNodesToString } from '../../../utils/unist.mjs';
 import {
   DOC_MDN_BASE_URL_JS_GLOBALS,
   DOC_MDN_BASE_URL_JS_PRIMITIVES,
@@ -7,8 +6,10 @@ import {
   DOC_TYPES_MAPPING_PRIMITIVES,
   DOC_MAN_BASE_URL,
   DOC_API_HEADING_TYPES,
+  TYPE_GENERIC_REGEX,
 } from '../constants.mjs';
 import { slug } from './slugger.mjs';
+import { transformNodesToString } from '../../../utils/unist.mjs';
 
 /**
  * @param {string} text The inner text
@@ -24,7 +25,81 @@ export const transformUnixManualToLink = (
 ) => {
   return `[\`${text}\`](${DOC_MAN_BASE_URL}${sectionNumber}/${command}.${sectionNumber}${sectionLetter}.html)`;
 };
+/**
+ * Safely splits the string by `|`, ignoring pipes that are inside `< >`
+ *
+ * @param {string} str The type string to split
+ * @returns {string[]} An array of type pieces
+ */
+const splitByOuterUnion = str => {
+  const result = [];
+  let current = '';
+  let depth = 0;
+
+  for (const char of str) {
+    if (char === '<') {
+      depth++;
+    } else if (char === '>') {
+      depth--;
+    } else if (char === '|' && depth === 0) {
+      result.push(current);
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+
+  result.push(current);
+  return result;
+};
 
+/**
+ * Attempts to parse and format a basic Generic type (e.g., Promise<string>).
+ * It also supports union and multi-parameter types within the generic brackets.
+ *
+ * @param {string} typePiece The plain type piece to be evaluated
+ * @param {Function} transformType The function used to resolve individual types into links
+ * @returns {string|null} The formatted Markdown link, or null if no match is found
+ */
+const formatBasicGeneric = (typePiece, transformType) => {
+  const genericMatch = typePiece.match(TYPE_GENERIC_REGEX);
+
+  if (genericMatch) {
+    const baseType = genericMatch[1].trim();
+    const innerType = genericMatch[2].trim();
+
+    const baseResult = transformType(baseType.replace(/\[\]$/, ''));
+    const baseFormatted = baseResult
+      ? `[\`<${baseType}>\`](${baseResult})`
+      : `\`<${baseType}>\``;
+
+    // Split while capturing delimiters (| or ,) to preserve original syntax
+    const parts = innerType.split(/([|,])/);
+
+    const innerFormatted = parts
+      .map(part => {
+        const trimmed = part.trim();
+        // If it is a delimiter, return it as is
+        if (trimmed === '|') {
+          return ' | ';
+        }
+
+        if (trimmed === ',') {
+          return ', ';
+        }
+
+        const innerRes = transformType(trimmed.replace(/\[\]$/, ''));
+        return innerRes
+          ? `[\`<${trimmed}>\`](${innerRes})`
+          : `\`<${trimmed}>\``;
+      })
+      .join('');
+
+    return `${baseFormatted}&lt;${innerFormatted}&gt;`;
+  }
+
+  return null;
+};
 /**
  * This method replaces plain text Types within the Markdown content into Markdown links
  * that link to the actual relevant reference for such type (either internal or external link)
@@ -34,8 +109,9 @@ export const transformUnixManualToLink = (
  * @returns {string} The Markdown link as a string (formatted in Markdown)
  */
 export const transformTypeToReferenceLink = (type, record) => {
-  // Removes the wrapping tags that wrap the type references such as `<>` and `{}`
-  const typeInput = type.replace(/[{}<>]/g, '');
+  // Removes the wrapping curly braces that wrap the type references
+  // We keep the angle brackets `<>` intact here to parse Generics later
+  const typeInput = type.replace(/[{}]/g, '');
 
   /**
    * Handles the mapping (if there's a match) of the input text
@@ -65,7 +141,7 @@ export const transformTypeToReferenceLink = (type, record) => {
 
     // Transform Node.js type/module references into Markdown links
     // that refer to other API docs pages within the Node.js API docs
-    if (lookupPiece in record) {
+    if (record && lookupPiece in record) {
       return record[lookupPiece];
     }
 
@@ -80,13 +156,20 @@ export const transformTypeToReferenceLink = (type, record) => {
     return '';
   };
 
-  const typePieces = typeInput.split('|').map(piece => {
+  const typePieces = splitByOuterUnion(typeInput).map(piece => {
     // This is the content to render as the text of the Markdown link
     const trimmedPiece = piece.trim();
 
+    // 1. Attempt to format as a basic Generic type first
+    const genericMarkdown = formatBasicGeneric(trimmedPiece, transformType);
+    if (genericMarkdown) {
+      return genericMarkdown;
+    }
+
+    // 2. Fallback to the logic for plain types
     // This is what we will compare against the API types mappings
     // The ReGeX below is used to remove `[]` from the end of the type
-    const result = transformType(trimmedPiece.replace('[]', ''));
+    const result = transformType(trimmedPiece.replace(/\[\]$/, ''));
 
     // If we have a valid result and the piece is not empty, we return the Markdown link
     if (trimmedPiece.length && result.length) {