refactor: review

Author: araujogui

npm-shrinkwrap.json

@@ -1,5 +1,5 @@
-import { BASE_URL } from '../../../constants.mjs';
 import { transformNodeToString } from '../../../utils/unist.mjs';
+import { buildApiDocURL } from '../../../utils/url.mjs';
 
 /**
  * Retrieves the description of a given API doc entry. It first checks whether
@@ -38,8 +38,7 @@ export const getEntryDescription = entry => {
 export const buildApiDocLink = entry => {
   const title = entry.heading.data.name;
 
-  const path = entry.api_doc_source.replace(/^doc\//, '/docs/latest/');
-  const url = new URL(path, BASE_URL);
+  const url = buildApiDocURL(entry);
 
   const link = `[${title}](${url})`;
 

src/generators/llms-txt/utils/buildApiDocLink.mjs

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import dedent from 'dedent';
 
 import { BASE_URL } from '../../constants.mjs';
+import { buildApiDocUrl } from './utils/buildApiDocUrl.mjs';
 
 /**
  * This generator generates a sitemap.xml file for search engine optimization
@@ -33,17 +34,7 @@ export default {
 
     const apiPages = entries
       .filter(entry => entry.heading.depth === 1)
-      .map(entry => {
-        const path = entry.api_doc_source.replace(/^doc\//, '/docs/latest/');
-        const url = new URL(path, BASE_URL).href;
-
-        return {
-          loc: url,
-          lastmod,
-          changefreq: 'weekly',
-          priority: '0.8',
-        };
-      });
+      .map(entry => buildApiDocUrl(entry, lastmod));
 
     apiPages.push({
       loc: new URL('/docs/latest/api/', BASE_URL).href,

src/generators/sitemap/index.mjs

@@ -0,0 +1,13 @@
+export interface SitemapUrl {
+  loc: string;
+  lastmod?: string;
+  changefreq?:
+    | 'always'
+    | 'hourly'
+    | 'daily'
+    | 'weekly'
+    | 'monthly'
+    | 'yearly'
+    | 'never';
+  priority?: string;
+}

src/generators/sitemap/types.d.ts

@@ -0,0 +1,14 @@
+import { buildApiDocURL } from '../../../utils/url.mjs';
+
+/**
+ * Builds an API doc sitemap url.
+ *
+ * @param {ApiDocMetadataEntry} entry
+ * @param {string} lastmod
+ * @returns {import('../types').SitemapUrl}
+ */
+export const buildApiDocUrl = (entry, lastmod) => {
+  const { href } = buildApiDocURL(entry, true);
+
+  return { loc: href, lastmod, changefreq: 'weekly', priority: '0.8' };
+};

src/generators/sitemap/utils/buildApiDocUrl.mjs

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { buildApiDocURL } from '../url.mjs';
+
+const BASE = 'https://nodejs.org/';
+
+describe('buildApiDocURL', () => {
+  it('builds markdown doc URLs from doc/ sources', () => {
+    const entry = { api_doc_source: 'doc/api/fs.md' };
+
+    const result = buildApiDocURL(entry);
+
+    assert.equal(result.href, `${BASE}docs/latest/api/fs.md`);
+  });
+
+  it('builds html doc URLs when requested', () => {
+    const entry = { api_doc_source: 'doc/api/path.md' };
+
+    const result = buildApiDocURL(entry, true);
+
+    assert.equal(result.href, `${BASE}docs/latest/api/path.html`);
+  });
+
+  it('leaves non doc/ sources untouched', () => {
+    const entry = { api_doc_source: 'api/crypto.md' };
+
+    const result = buildApiDocURL(entry);
+
+    assert.equal(result.href, `${BASE}api/crypto.md`);
+  });
+});

src/utils/__tests__/url.test.mjs

@@ -0,0 +1,19 @@
+import { BASE_URL } from '../constants.mjs';
+
+/**
+ * Builds the url of a api doc entry.
+ *
+ * @param {ApiDocMetadataEntry} entry
+ * @param {boolean} [useHtml]
+ * @returns {URL}
+ */
+export const buildApiDocURL = (entry, useHtml = false) => {
+  const path = entry.api_doc_source.replace(/^doc\//, '/docs/latest/');
+
+  if (useHtml) {
+    const htmlPath = path.replace(/\.md$/, '.html');
+    return new URL(htmlPath, BASE_URL);
+  }
+
+  return new URL(path, BASE_URL);
+};