feat(types): support type index

Author: avivkeller

bin/commands/generate.mjs

@@ -10,6 +10,7 @@ import {
 import { publicGenerators } from '../../src/generators/index.mjs';
 import createGenerator from '../../src/generators.mjs';
 import { parseChangelog, parseIndex } from '../../src/parsers/markdown.mjs';
+import { loadFromURL } from '../../src/utils/parser.mjs';
 import { loadAndParse } from '../utils.mjs';
 
 const availableGenerators = Object.keys(publicGenerators);
@@ -21,6 +22,7 @@ const availableGenerators = Object.keys(publicGenerators);
  * @property {Array<keyof publicGenerators>} target - Specifies the generator target mode.
  * @property {string} version - Specifies the target Node.js version.
  * @property {string} changelog - Specifies the path to the Node.js CHANGELOG.md file.
+ * @property {string} typeMap - Specifies the path to the Node.js Type Map.
  * @property {string} [gitRef] - Git ref/commit URL.
  * @property {number} [threads] - Number of threads to allow.
  */
@@ -112,6 +114,14 @@ export default {
         type: 'text',
       },
     },
+    typeMap: {
+      flags: ['--type-map <path>'],
+      desc: 'The mapping of types to links',
+      prompt: {
+        message: 'Path to doc/api/type_map.json',
+        type: 'text',
+      },
+    },
   },
   /**
    * Handles the action for generating API docs
@@ -121,6 +131,11 @@ export default {
   async action(opts) {
     const docs = await loadAndParse(opts.input, opts.ignore);
     const releases = await parseChangelog(opts.changelog);
+
+    const typeMap = opts.typeMap
+      ? JSON.parse(await loadFromURL(opts.typeMap))
+      : undefined;
+
     const index = opts.index && (await parseIndex(opts.index));
 
     const { runGenerators } = createGenerator(docs);
@@ -134,6 +149,7 @@ export default {
       gitRef: opts.gitRef,
       threads: parseInt(opts.threads, 10),
       index,
+      typeMap,
     });
   },
 };

src/generators/metadata/index.mjs

@@ -20,9 +20,10 @@ export default {
 
   /**
    * @param {Input} inputs
+   * @param {GeneratorOptions} options
    * @returns {Promise<Array<ApiDocMetadataEntry>>}
    */
-  async generate(inputs) {
-    return inputs.flatMap(input => parseApiDoc(input));
+  async generate(inputs, { typeMap }) {
+    return inputs.flatMap(input => parseApiDoc(input, typeMap));
   },
 };

src/generators/metadata/utils/parse.mjs

@@ -15,9 +15,10 @@ import { getRemark } from '../../../utils/remark.mjs';
  * This generator generates a flattened list of metadata entries from a API doc
  *
  * @param {ParserOutput<import('mdast').Root>} input
+ * @param {Record<string, string>} typeMap
  * @returns {Promise<Array<ApiDocMetadataEntry>>}
  */
-export const parseApiDoc = ({ file, tree }) => {
+export const parseApiDoc = ({ file, tree }, typeMap) => {
   /**
    * This holds references to all the Metadata entries for a given file
    * this is used so we can traverse the AST tree and keep mutating things
@@ -38,7 +39,7 @@ export const parseApiDoc = ({ file, tree }) => {
     updateUnixManualReference,
     updateLinkReference,
     addStabilityMetadata,
-  } = createQueries();
+  } = createQueries(typeMap);
 
   // Creates an instance of the Remark processor with GFM support
   // which is used for stringifying the AST tree back to Markdown

src/generators/types.d.ts

@@ -42,6 +42,9 @@ declare global {
 
     // The number of threads the process is allowed to use
     threads: number;
+
+    // The type map
+    typeMap: Record<string, string>;
   }
 
   export interface GeneratorMetadata<I extends any, O extends any> {

src/utils/parser/__tests__/index.test.mjs

@@ -29,6 +29,15 @@ describe('transformTypeToReferenceLink', () => {
       '[`<prefix.Type>`](prefix.html#class-prefixtype)'
     );
   });
+
+  it('should accept a type map', () => {
+    strictEqual(
+      transformTypeToReferenceLink('SomeOtherType', {
+        SomeOtherType: 'fromTypeMap',
+      }),
+      '[`<SomeOtherType>`](fromTypeMap)'
+    );
+  });
 });
 
 describe('normalizeYamlSyntax', () => {

src/utils/parser/index.mjs

@@ -66,9 +66,13 @@ export const transformUnixManualToLink = (
  * that link to the actual relevant reference for such type (either internal or external link)
  *
  * @param {string} type The plain type to be transformed into a Markdown link
+ * @param {Record<string, string>} record The mapping of types to links
  * @returns {string} The Markdown link as a string (formatted in Markdown)
  */
-export const transformTypeToReferenceLink = type => {
+export const transformTypeToReferenceLink = (
+  type,
+  record = DOC_TYPES_MAPPING_NODE_MODULES
+) => {
   // Removes the wrapping tags that wrap the type references such as `<>` and `{}`
   const typeInput = type.replace(/[{}<>]/g, '');
 
@@ -100,8 +104,8 @@ export const transformTypeToReferenceLink = type => {
 
     // 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 DOC_TYPES_MAPPING_NODE_MODULES) {
-      return DOC_TYPES_MAPPING_NODE_MODULES[lookupPiece];
+    if (lookupPiece in record) {
+      return record[lookupPiece];
     }
 
     // Transform Node.js types like 'vm.Something'.

src/utils/queries/index.mjs

@@ -20,8 +20,9 @@ import { transformNodesToString } from '../unist.mjs';
 /**
  * Creates an instance of the Query Manager, which allows to do multiple sort
  * of metadata and content metadata manipulation within an API Doc
+ * @param {Record<string, string>} typeMap The mapping to types to links
  */
-const createQueries = () => {
+const createQueries = typeMap => {
   const remark = getRemark();
   /**
    * Sanitizes the YAML source by returning the inner YAML content
@@ -179,7 +180,7 @@ const createQueries = () => {
     updateTypeReference: (...args) =>
       updateReferences(
         createQueries.QUERIES.normalizeTypes,
-        transformTypeToReferenceLink,
+        type => transformTypeToReferenceLink(type, typeMap),
         ...args
       ),
     /** @param {Array<import('@types/mdast').Node>} args */