perf: parallelize jsDelivr README fallback probes

Author: trivikr

server/utils/readme-loaders.ts

@@ -19,14 +19,23 @@ const standardReadmeFilenames = [
 
 /** Matches standard README filenames (case-insensitive, for checking registry metadata) */
 const standardReadmePattern = /^readme(?:\.md|\.markdown)?$/i
+const JSDELIVR_README_FETCH_BATCH_SIZE = 3
 
 export function isStandardReadme(filename: string | undefined): boolean {
   return !!filename && standardReadmePattern.test(filename)
 }
 
+function buildReadmeFetchCandidates(readmeFilename: string | undefined): string[] {
+  if (!readmeFilename) {
+    return standardReadmeFilenames
+  }
+
+  return [readmeFilename, ...standardReadmeFilenames.filter(name => name !== readmeFilename)]
+}
+
 /**
  * Fetch README from jsdelivr CDN for a specific package version.
- * Falls back through common README filenames.
+ * Falls back through candidate README filenames in small parallel batches.
  */
 export async function fetchReadmeFromJsdelivr(
   packageName: string,
@@ -35,15 +44,27 @@ export async function fetchReadmeFromJsdelivr(
 ): Promise<string | null> {
   const versionSuffix = version ? `@${version}` : ''
 
-  for (const filename of readmeFilenames) {
-    try {
-      const url = `https://cdn.jsdelivr.net/npm/${packageName}${versionSuffix}/${filename}`
-      const response = await fetch(url)
-      if (response.ok) {
-        return await response.text()
-      }
-    } catch {
-      // Try next filename
+  for (let index = 0; index < readmeFilenames.length; index += JSDELIVR_README_FETCH_BATCH_SIZE) {
+    const batch = readmeFilenames.slice(index, index + JSDELIVR_README_FETCH_BATCH_SIZE)
+    const responses = await Promise.all(
+      batch.map(async filename => {
+        try {
+          const url = `https://cdn.jsdelivr.net/npm/${packageName}${versionSuffix}/${filename}`
+          const response = await fetch(url)
+          if (!response.ok) {
+            return null
+          }
+
+          return await response.text()
+        } catch {
+          return null
+        }
+      }),
+    )
+
+    const matchedReadme = responses.find((response): response is string => response !== null)
+    if (matchedReadme) {
+      return matchedReadme
     }
   }
 
@@ -84,10 +105,11 @@ export const resolvePackageReadmeSource = defineCachedFunction(
       !isStandardReadme(readmeFilename) ||
       readmeContent!.length >= NPM_README_TRUNCATION_THRESHOLD
     ) {
+      const readmeCandidates = buildReadmeFetchCandidates(readmeFilename)
       const resolvedVersion = version ?? packageData['dist-tags']?.latest
       const jsdelivrReadme = await fetchReadmeFromJsdelivr(
         packageName,
-        standardReadmeFilenames,
+        readmeCandidates,
         resolvedVersion,
       )
       if (jsdelivrReadme) {

test/unit/server/utils/readme-loaders.spec.ts

@@ -38,6 +38,15 @@ describe('isStandardReadme', () => {
 })
 
 describe('fetchReadmeFromJsdelivr', () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals()
+    vi.stubGlobal('defineCachedFunction', (fn: Function) => fn)
+    vi.stubGlobal('$fetch', $fetchMock)
+    vi.stubGlobal('parsePackageParams', parsePackageParams)
+    vi.stubGlobal('fetchNpmPackage', fetchNpmPackageMock)
+    vi.stubGlobal('parseRepositoryInfo', parseRepositoryInfoMock)
+  })
+
   it('returns content when first filename succeeds', async () => {
     const content = '# Package'
     const fetchMock = vi.fn().mockResolvedValue({
@@ -73,6 +82,59 @@ describe('fetchReadmeFromJsdelivr', () => {
     expect(result).toBeNull()
     expect(fetchMock).toHaveBeenCalledTimes(2)
   })
+
+  it('starts a small batch of candidate fetches in parallel', async () => {
+    let resolveReadmeMd!: (value: { ok: false }) => void
+    let resolveLowercase!: (value: { ok: false }) => void
+    let resolveReadme!: (value: { ok: true; text: () => Promise<string> }) => void
+
+    const fetchMock = vi.fn((url: string) => {
+      if (url.endsWith('/README.md')) {
+        return new Promise(resolve => {
+          resolveReadmeMd = resolve
+        })
+      }
+
+      if (url.endsWith('/readme.md')) {
+        return new Promise(resolve => {
+          resolveLowercase = resolve
+        })
+      }
+
+      if (url.endsWith('/README')) {
+        return new Promise(resolve => {
+          resolveReadme = resolve
+        })
+      }
+
+      return Promise.resolve({ ok: false })
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const resultPromise = fetchReadmeFromJsdelivr('pkg', [
+      'README.md',
+      'readme.md',
+      'README',
+      'readme',
+    ])
+
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+    expect(fetchMock.mock.calls.map(([url]) => url)).toEqual([
+      'https://cdn.jsdelivr.net/npm/pkg/README.md',
+      'https://cdn.jsdelivr.net/npm/pkg/readme.md',
+      'https://cdn.jsdelivr.net/npm/pkg/README',
+    ])
+
+    resolveReadmeMd({ ok: false })
+    resolveLowercase({ ok: false })
+    resolveReadme({
+      ok: true,
+      text: async () => '# Package',
+    })
+
+    await expect(resultPromise).resolves.toBe('# Package')
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+  })
 })
 
 describe('resolvePackageReadmeSource', () => {
@@ -172,6 +234,7 @@ describe('resolvePackageReadmeSource', () => {
     const result = await resolvePackageReadmeSource('pkg')
 
     expect(result).toMatchObject({ markdown: jsdelivrContent })
+    expect(fetchMock).toHaveBeenNthCalledWith(1, 'https://cdn.jsdelivr.net/npm/pkg/DOCS.md')
   })
 
   it('returns undefined markdown when no content and jsdelivr fails', async () => {