feat(types): support type index (#463)

* feat(types): support type index

Author: avivkeller

bin/commands/generate.mjs

@@ -10,6 +10,8 @@ import {
 import { publicGenerators } from '../../src/generators/index.mjs';
 import createGenerator from '../../src/generators.mjs';
 import { parseChangelog, parseIndex } from '../../src/parsers/markdown.mjs';
+import { DEFAULT_TYPE_MAP } from '../../src/utils/parser/constants.mjs';
+import { loadFromURL } from '../../src/utils/parser.mjs';
 import { loadAndParse } from '../utils.mjs';
 
 const availableGenerators = Object.keys(publicGenerators);
@@ -21,6 +23,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 +115,15 @@ 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',
+        initialValue: DEFAULT_TYPE_MAP,
+      },
+    },
   },
   /**
    * Handles the action for generating API docs
@@ -121,6 +133,10 @@ export default {
   async action(opts) {
     const docs = await loadAndParse(opts.input, opts.ignore);
     const releases = await parseChangelog(opts.changelog);
+
+    const rawTypeMap = await loadFromURL(opts.typeMap);
+    const typeMap = JSON.parse(rawTypeMap);
+
     const index = opts.index && (await parseIndex(opts.index));
 
     const { runGenerators } = createGenerator(docs);
@@ -134,6 +150,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

@@ -16,9 +16,10 @@ import { IGNORE_STABILITY_STEMS } from '../constants.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
@@ -39,7 +40,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.mjs

@@ -12,7 +12,7 @@ export const loadFromURL = async url => {
 
   if (!parsedUrl || parsedUrl.protocol === 'file:') {
     // Load from file system
-    return readFile(url, 'utf-8');
+    return readFile(parsedUrl ?? url, 'utf-8');
   } else {
     // Load from network
     const response = await fetch(parsedUrl);

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

@@ -23,10 +23,12 @@ describe('transformTypeToReferenceLink', () => {
     );
   });
 
-  it('should transform a prefixed type into a Markdown link', () => {
+  it('should transform a type into a Markdown link', () => {
     strictEqual(
-      transformTypeToReferenceLink('prefix.Type'),
-      '[`<prefix.Type>`](prefix.html#class-prefixtype)'
+      transformTypeToReferenceLink('SomeOtherType', {
+        SomeOtherType: 'fromTypeMap',
+      }),
+      '[`<SomeOtherType>`](fromTypeMap)'
     );
   });
 });

src/utils/parser/constants.mjs

@@ -1,5 +1,8 @@
 import globals from 'globals';
 
+// The default type map path
+export const DEFAULT_TYPE_MAP = import.meta.resolve('./typeMap.json');
+
 // These are string replacements specific to Node.js API docs for anchor IDs
 export const DOC_API_SLUGS_REPLACEMENTS = [
   { from: /node.js/i, to: 'nodejs' }, // Replace Node.js
@@ -95,199 +98,6 @@ export const DOC_TYPES_MAPPING_GLOBALS = {
   'WebAssembly.Instance': 'WebAssembly/Instance',
 };
 
-// This is a mapping for types within the Markdown content and their respective
-// Node.js types within the Node.js API docs (refers to a different API doc page)
-// Note: These hashes are generated with the GitHub Slugger
-export const DOC_TYPES_MAPPING_NODE_MODULES = {
-  AbortController: 'globals.html#class-abortcontroller',
-  AbortSignal: 'globals.html#class-abortsignal',
-
-  Algorithm: 'webcrypto.html#class-algorithm',
-  AlgorithmIdentifier: 'webcrypto.html#class-algorithmidentifier',
-  AsyncHook: 'async_hooks.html#async_hookscreatehookcallbacks',
-  AsyncLocalStorage: 'async_context.html#class-asynclocalstorage',
-  AsyncResource: 'async_hooks.html#class-asyncresource',
-
-  AesCbcParams: 'webcrypto.html#class-aescbcparams',
-  AesCtrParams: 'webcrypto.html#class-aesctrparams',
-  AesGcmParams: 'webcrypto.html#class-aesgcmparams',
-  AesKeyAlgorithm: 'webcrypto.html#class-aeskeyalgorithm',
-  AesKeyGenParams: 'webcrypto.html#class-aeskeygenparams',
-  AesDerivedKeyParams: 'webcrypto.html#class-aesderivedkeyparams',
-
-  Blob: 'buffer.html#class-blob',
-  BroadcastChannel:
-    'worker_threads.html#class-broadcastchannel-extends-eventtarget',
-  Buffer: 'buffer.html#class-buffer',
-
-  ByteLengthQueuingStrategy: 'webstreams.html#class-bytelengthqueuingstrategy',
-
-  Channel: 'diagnostics_channel.html#class-channel',
-  ChildProcess: 'child_process.html#class-childprocess',
-  Cipher: 'crypto.html#class-cipher',
-  Cipheriv: 'crypto.html#class-cipheriv',
-  Decipheriv: 'crypto.html#class-decipheriv',
-  ClientHttp2Session: 'http2.html#class-clienthttp2session',
-  ClientHttp2Stream: 'http2.html#class-clienthttp2stream',
-
-  CountQueuingStrategy: 'webstreams.html#class-countqueuingstrategy',
-
-  Crypto: 'webcrypto.html#class-crypto',
-  CryptoKey: 'webcrypto.html#class-cryptokey',
-  CryptoKeyPair: 'webcrypto.html#class-cryptokeypair',
-
-  CustomEvent: 'events.html#class-customevent',
-
-  Decipher: 'crypto.html#class-decipher',
-  DiffieHellman: 'crypto.html#class-diffiehellman',
-  DiffieHellmanGroup: 'crypto.html#class-diffiehellmangroup',
-  Domain: 'domain.html#class-domain',
-
-  Duplex: 'stream.html#class-streamduplex',
-
-  ECDH: 'crypto.html#class-ecdh',
-  EcdhKeyDeriveParams: 'webcrypto.html#class-ecdhkeyderiveparams',
-  EcdsaParams: 'webcrypto.html#class-ecdsaparams',
-  EcKeyAlgorithm: 'webcrypto.html#class-eckeyalgorithm',
-  EcKeyGenParams: 'webcrypto.html#class-eckeygenparams',
-  EcKeyImportParams: 'webcrypto.html#class-eckeyimportparams',
-  Ed448Params: 'webcrypto.html#class-ed448params',
-
-  Event: 'events.html#class-event',
-  EventEmitter: 'events.html#class-eventemitter',
-  EventListener: 'events.html#event-listener',
-  EventTarget: 'events.html#class-eventtarget',
-
-  File: 'buffer.html#class-file',
-  FileHandle: 'fs.html#class-filehandle',
-
-  Handle: 'net.html#serverlistenhandle-backlog-callback',
-  Hash: 'crypto.html#class-hash',
-  Histogram: 'perf_hooks.html#class-histogram',
-  HkdfParams: 'webcrypto.html#class-hkdfparams',
-  Hmac: 'crypto.html#class-hmac',
-  HmacImportParams: 'webcrypto.html#class-hmacimportparams',
-  HmacKeyAlgorithm: 'webcrypto.html#class-hmackeyalgorithm',
-  HmacKeyGenParams: 'webcrypto.html#class-hmackeygenparams',
-
-  Http2SecureServer: 'http2.html#class-http2secureserver',
-  Http2Server: 'http2.html#class-http2server',
-  Http2Session: 'http2.html#class-http2session',
-  Http2Stream: 'http2.html#class-http2stream',
-
-  Immediate: 'timers.html#class-immediate',
-
-  IntervalHistogram:
-    'perf_hooks.html#class-intervalhistogram-extends-histogram',
-
-  LockManager: 'worker_threads.html#class-lockmanager',
-
-  KeyAlgorithm: 'webcrypto.html#class-keyalgorithm',
-  KeyObject: 'crypto.html#class-keyobject',
-
-  MIMEParams: 'util.html#class-utilmimeparams',
-  MessagePort: 'worker_threads.html#class-messageport',
-
-  MockModuleContext: 'test.html#class-mockmodulecontext',
-
-  NodeEventTarget: 'events.html#class-nodeeventtarget',
-
-  Pbkdf2Params: 'webcrypto.html#class-pbkdf2params',
-  PerformanceEntry: 'perf_hooks.html#class-performanceentry',
-  PerformanceNodeTiming: 'perf_hooks.html#class-performancenodetiming',
-  PerformanceObserver: 'perf_hooks.html#class-performanceobserver',
-  PerformanceObserverEntryList:
-    'perf_hooks.html#class-performanceobserverentrylist',
-
-  Readable: 'stream.html#class-streamreadable',
-  ReadableByteStreamController:
-    'webstreams.html#class-readablebytestreamcontroller',
-  ReadableStream: 'webstreams.html#class-readablestream',
-  ReadableStreamBYOBReader: 'webstreams.html#class-readablestreambyobreader',
-  ReadableStreamBYOBRequest: 'webstreams.html#class-readablestreambyobrequest',
-  ReadableStreamDefaultController:
-    'webstreams.html#class-readablestreamdefaultcontroller',
-  ReadableStreamDefaultReader:
-    'webstreams.html#class-readablestreamdefaultreader',
-
-  ModuleRequest: 'vm.html#type-modulerequest',
-
-  DatabaseSync: 'sqlite.html#class-databasesync',
-
-  RecordableHistogram:
-    'perf_hooks.html#class-recordablehistogram-extends-histogram',
-
-  RsaHashedKeyAlgorithm: 'webcrypto.html#class-rsahashedkeyalgorithm',
-  RsaHashedImportParams: 'webcrypto.html#class-rsahashedimportparams',
-  RsaHashedKeyGenParams: 'webcrypto.html#class-rsahashedkeygenparams',
-  RsaOaepParams: 'webcrypto.html#class-rsaoaepparams',
-  RsaPssParams: 'webcrypto.html#class-rsapssparams',
-
-  ServerHttp2Session: 'http2.html#class-serverhttp2session',
-  ServerHttp2Stream: 'http2.html#class-serverhttp2stream',
-
-  Sign: 'crypto.html#class-sign',
-
-  Disposable:
-    'https://tc39.es/proposal-explicit-resource-management/#sec-disposable-interface',
-
-  Session: 'sqlite.html#class-session',
-  StatementSync: 'sqlite.html#class-statementsync',
-
-  Stream: 'stream.html#stream',
-
-  SubtleCrypto: 'webcrypto.html#class-subtlecrypto',
-
-  TestsStream: 'test.html#class-testsstream',
-
-  TextDecoderStream: 'webstreams.html#class-textdecoderstream',
-  TextEncoderStream: 'webstreams.html#class-textencoderstream',
-
-  Timeout: 'timers.html#class-timeout',
-  Timer: 'timers.html#timers',
-
-  Tracing: 'tracing.html#tracing-object',
-  TracingChannel: 'diagnostics_channel.html#class-tracingchannel',
-
-  Transform: 'stream.html#class-streamtransform',
-  TransformStream: 'webstreams.html#class-transformstream',
-  TransformStreamDefaultController:
-    'webstreams.html#class-transformstreamdefaultcontroller',
-
-  URL: 'url.html#the-whatwg-url-api',
-  URLSearchParams: 'url.html#class-urlsearchparams',
-
-  Verify: 'crypto.html#class-verify',
-
-  Writable: 'stream.html#class-streamwritable',
-  WritableStream: 'webstreams.html#class-writablestream',
-  WritableStreamDefaultController:
-    'webstreams.html#class-writablestreamdefaultcontroller',
-  WritableStreamDefaultWriter:
-    'webstreams.html#class-writablestreamdefaultwriter',
-
-  Worker: 'worker_threads.html#class-worker',
-
-  X509Certificate: 'crypto.html#class-x509certificate',
-
-  'brotli options': 'zlib.html#class-brotlioptions',
-
-  'import.meta': 'esm.html#importmeta',
-
-  'os.constants.dlopen': 'os.html#dlopen-constants',
-
-  'readlinePromises.Interface': 'readline.html#class-readlinepromisesinterface',
-
-  require: 'modules.html#requireid',
-  module: 'modules.html#the-module-object',
-
-  'zlib options': 'zlib.html#class-options',
-  'zstd options': 'zlib.html#class-zstdoptions',
-
-  'HTTP/2 Headers Object': 'http2.html#headers-object',
-  'HTTP/2 Settings Object': 'http2.html#settings-object',
-};
-
 // This is a mapping for miscellaneous types within the Markdown content and their respective
 // external reference on appropriate 3rd-party vendors/documentation sites.
 export const DOC_TYPES_MAPPING_OTHER = {

src/utils/parser/index.mjs

@@ -7,7 +7,6 @@ import {
   DOC_MDN_BASE_URL_JS_GLOBALS,
   DOC_MDN_BASE_URL_JS_PRIMITIVES,
   DOC_TYPES_MAPPING_GLOBALS,
-  DOC_TYPES_MAPPING_NODE_MODULES,
   DOC_TYPES_MAPPING_OTHER,
   DOC_TYPES_MAPPING_PRIMITIVES,
   DOC_MAN_BASE_URL,
@@ -66,9 +65,10 @@ 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) => {
   // Removes the wrapping tags that wrap the type references such as `<>` and `{}`
   const typeInput = type.replace(/[{}<>]/g, '');
 
@@ -100,8 +100,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'.