feat: unifying npm registry requests with caching (#641)

Co-authored-by: James Garbutt <[e-mail]>
Co-authored-by: Philippe Serhal <[e-mail]>
Co-authored-by: Daniel Roe <[e-mail]>

.gitignore

···
 # generated files
 shared/types/lexicons
 
+**/__screenshots__/**
+
 # output
 .vercel

app/composables/npm/useNpmSearch.ts

···
   NpmDownloadCount,
   MinimalPackument,
 } from '#shared/types'
-import { NPM_REGISTRY, NPM_API } from '~/utils/npm/common'
 
 /**
  * Convert packument to search result format for display
···
   query: MaybeRefOrGetter<string>,
   options: MaybeRefOrGetter<NpmSearchOptions> = {},
 ) {
-  const cachedFetch = useCachedFetch()
+  const { $npmRegistry } = useNuxtApp()
+
   // Client-side cache
   const cache = shallowRef<{
     query: string
···
 
   const asyncData = useLazyAsyncData(
     () => `search:incremental:${toValue(query)}`,
-    async (_nuxtApp, { signal }) => {
+    async ({ $npmRegistry, $npmApi }, { signal }) => {
       const q = toValue(query)
 
       if (!q.trim()) {
···
       if (q.length === 1) {
         const encodedName = encodePackageName(q)
         const [{ data: pkg, isStale }, { data: downloads }] = await Promise.all([
-          cachedFetch<Packument>(`${NPM_REGISTRY}/${encodedName}`, { signal }),
-          cachedFetch<NpmDownloadCount>(`${NPM_API}/downloads/point/last-week/${encodedName}`, {
+          $npmRegistry<Packument>(`/${encodedName}`, { signal }),
+          $npmApi<NpmDownloadCount>(`/downloads/point/last-week/${encodedName}`, {
             signal,
           }),
         ])
···
         }
       }
 
-      const { data: response, isStale } = await cachedFetch<NpmSearchResponse>(
-        `${NPM_REGISTRY}/-/v1/search?${params.toString()}`,
+      const { data: response, isStale } = await $npmRegistry<NpmSearchResponse>(
+        `/-/v1/search?${params.toString()}`,
         { signal },
         60,
       )
···
       params.set('size', String(size))
       params.set('from', String(from))
 
-      const { data: response } = await cachedFetch<NpmSearchResponse>(
-        `${NPM_REGISTRY}/-/v1/search?${params.toString()}`,
+      const { data: response } = await $npmRegistry<NpmSearchResponse>(
+        `/-/v1/search?${params.toString()}`,
         {},
         60,
       )

app/composables/npm/useOrgPackages.ts

···
+import type { NuxtApp } from '#app'
 import type { NpmSearchResponse, NpmSearchResult, MinimalPackument } from '#shared/types'
 import { emptySearchResponse, packumentToSearchResult } from './useNpmSearch'
-import { NPM_REGISTRY, NPM_API } from '~/utils/npm/common'
 import { mapWithConcurrency } from '#shared/utils/async'
 
 /**
···
  * Note: npm bulk downloads API does not support scoped packages.
  */
 async function fetchBulkDownloads(
+  $npmApi: NuxtApp['$npmApi'],
   packageNames: string[],
   options: Parameters<typeof $fetch>[1] = {},
 ): Promise<Map<string, number>> {
···
     bulkPromises.push(
       (async () => {
         try {
-          const response = await $fetch<Record<string, { downloads: number } | null>>(
-            `${NPM_API}/downloads/point/last-week/${chunk.join(',')}`,
+          const response = await $npmApi<Record<string, { downloads: number } | null>>(
+            `/downloads/point/last-week/${chunk.join(',')}`,
             options,
           )
-          for (const [name, data] of Object.entries(response)) {
+          for (const [name, data] of Object.entries(response.data)) {
             if (data?.downloads !== undefined) {
               downloads.set(name, data.downloads)
             }
···
         const results = await Promise.allSettled(
           batch.map(async name => {
             const encoded = encodePackageName(name)
-            const data = await $fetch<{ downloads: number }>(
-              `${NPM_API}/downloads/point/last-week/${encoded}`,
+            const { data } = await $npmApi<{ downloads: number }>(
+              `/downloads/point/last-week/${encoded}`,
             )
             return { name, downloads: data.downloads }
           }),
···
  * Returns search-result-like objects for compatibility with PackageList
  */
 export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
-  const cachedFetch = useCachedFetch()
-
   const asyncData = useLazyAsyncData(
     () => `org-packages:${toValue(orgName)}`,
-    async (_nuxtApp, { signal }) => {
+    async ({ $npmRegistry, $npmApi }, { signal }) => {
       const org = toValue(orgName)
       if (!org) {
         return emptySearchResponse
···
       // Get all package names in the org
       let packageNames: string[]
       try {
-        const { data } = await cachedFetch<Record<string, string>>(
-          `${NPM_REGISTRY}/-/org/${encodeURIComponent(org)}/package`,
+        const { data } = await $npmRegistry<Record<string, string>>(
+          `/-/org/${encodeURIComponent(org)}/package`,
           { signal },
         )
         packageNames = Object.keys(data)
···
             async name => {
               try {
                 const encoded = encodePackageName(name)
-                const { data: pkg } = await cachedFetch<MinimalPackument>(
-                  `${NPM_REGISTRY}/${encoded}`,
-                  { signal },
-                )
+                const { data: pkg } = await $npmRegistry<MinimalPackument>(`/${encoded}`, {
+                  signal,
+                })
                 return pkg
               } catch {
                 return null
···
           )
         })(),
         // Fetch downloads in bulk
-        fetchBulkDownloads(packageNames, { signal }),
+        fetchBulkDownloads($npmApi, packageNames, { signal }),
       ])
 
       // Convert to search results with download data

app/composables/npm/useOutdatedDependencies.ts

···
+import type { NuxtApp } from '#app'
 import { maxSatisfying, prerelease, major, minor, diff, gt } from 'semver'
 import type { Packument } from '#shared/types'
 import { mapWithConcurrency } from '#shared/utils/async'
···
   isNonSemverConstraint,
   constraintIncludesPrerelease,
 } from '~/utils/npm/outdated-dependencies'
-import { NPM_REGISTRY } from '~/utils/npm/common'
 
 // Cache for packument fetches to avoid duplicate requests across components
 const packumentCache = new Map<string, Promise<Packument | null>>()
···
  */
 async function checkDependencyOutdated(
   cachedFetch: CachedFetchFunction,
+  $npmRegistry: NuxtApp['$npmRegistry'],
   packageName: string,
   constraint: string,
 ): Promise<OutdatedDependencyInfo | null> {
···
   if (cached) {
     packument = await cached
   } else {
-    const promise = cachedFetch<Packument>(`${NPM_REGISTRY}/${encodePackageName(packageName)}`)
+    const promise = $npmRegistry<Packument>(`/${encodePackageName(packageName)}`)
       .then(({ data }) => data)
       .catch(() => null)
     packumentCache.set(packageName, promise)
···
 export function useOutdatedDependencies(
   dependencies: MaybeRefOrGetter<Record<string, string> | undefined>,
 ) {
+  const { $npmRegistry } = useNuxtApp()
   const cachedFetch = useCachedFetch()
   const outdated = shallowRef<Record<string, OutdatedDependencyInfo>>({})
 
···
     const batchResults = await mapWithConcurrency(
       entries,
       async ([name, constraint]) => {
-        const info = await checkDependencyOutdated(cachedFetch, name, constraint)
+        const info = await checkDependencyOutdated(cachedFetch, $npmRegistry, name, constraint)
         return [name, info] as const
       },
       5,

app/composables/npm/usePackage.ts

···
 import type { Packument, SlimPackument, SlimVersion, SlimPackumentVersion } from '#shared/types'
-import { NPM_REGISTRY } from '~/utils/npm/common'
 import { extractInstallScriptsInfo } from '~/utils/install-scripts'
 
 /** Number of recent versions to include in initial payload */
···
   name: MaybeRefOrGetter<string>,
   requestedVersion?: MaybeRefOrGetter<string | null>,
 ) {
-  const cachedFetch = useCachedFetch()
-
   const asyncData = useLazyAsyncData(
     () => `package:${toValue(name)}:${toValue(requestedVersion) ?? ''}`,
-    async (_nuxtApp, { signal }) => {
+    async ({ $npmRegistry }, { signal }) => {
       const encodedName = encodePackageName(toValue(name))
-      const { data: r, isStale } = await cachedFetch<Packument>(`${NPM_REGISTRY}/${encodedName}`, {
+      const { data: r, isStale } = await $npmRegistry<Packument>(`/${encodedName}`, {
         signal,
       })
       const reqVer = toValue(requestedVersion)

app/composables/npm/usePackageDownloads.ts

···
 import type { NpmDownloadCount } from '#shared/types'
-import { NPM_API } from '~/utils/npm/common'
 
 export function usePackageDownloads(
   name: MaybeRefOrGetter<string>,
   period: MaybeRefOrGetter<'last-day' | 'last-week' | 'last-month' | 'last-year'> = 'last-week',
 ) {
-  const cachedFetch = useCachedFetch()
-
   const asyncData = useLazyAsyncData(
     () => `downloads:${toValue(name)}:${toValue(period)}`,
-    async (_nuxtApp, { signal }) => {
+    async ({ $npmApi }, { signal }) => {
       const encodedName = encodePackageName(toValue(name))
-      const { data, isStale } = await cachedFetch<NpmDownloadCount>(
-        `${NPM_API}/downloads/point/${toValue(period)}/${encodedName}`,
+      const { data, isStale } = await $npmApi<NpmDownloadCount>(
+        `/downloads/point/${toValue(period)}/${encodedName}`,
         { signal },
       )
       return { ...data, isStale }

app/composables/useCachedFetch.ts

···
 import type { CachedFetchResult } from '#shared/utils/fetch-cache-config'
+import { defu } from 'defu'
 
 /**
  * Get the cachedFetch function from the current request context.
···
     return async <T = unknown>(
       url: string,
       options: Parameters<typeof $fetch>[1] = {},
-      _ttl?: number,
+      _ttl: number = FETCH_CACHE_DEFAULT_TTL,
     ): Promise<CachedFetchResult<T>> => {
-      const data = (await $fetch<T>(url, options)) as T
+      const defaultFetchOptions: Parameters<typeof $fetch>[1] = {
+        cache: 'force-cache',
+      }
+      const data = (await $fetch<T>(url, defu(options, defaultFetchOptions))) as T
       return { data, isStale: false, cachedAt: null }
     }
   }
···
   return async <T = unknown>(
     url: string,
     options: Parameters<typeof $fetch>[1] = {},
-    _ttl?: number,
+    _ttl: number = FETCH_CACHE_DEFAULT_TTL,
   ): Promise<CachedFetchResult<T>> => {
-    const data = (await $fetch<T>(url, options)) as T
+    const defaultFetchOptions: Parameters<typeof $fetch>[1] = {
+      cache: 'force-cache',
+    }
+    const data = (await $fetch<T>(url, defu(options, defaultFetchOptions))) as T
     return { data, isStale: false, cachedAt: null }
   }
 }

app/pages/search.vue

···
 /** Cache for existence checks to avoid repeated API calls */
 const existenceCache = ref<Record<string, boolean | 'pending'>>({})
 
-const NPM_REGISTRY = 'https://registry.npmjs.org'
-
 interface NpmSearchResponse {
   total: number
   objects: Array<{ package: { name: string } }>

app/plugins/npm.ts

···
+export default defineNuxtPlugin(() => {
+  const cachedFetch = useCachedFetch()
+
+  return {
+    provide: {
+      npmRegistry: <T>(
+        url: Parameters<CachedFetchFunction>[0],
+        options?: Parameters<CachedFetchFunction>[1],
+        ttl?: Parameters<CachedFetchFunction>[2],
+      ) => {
+        return cachedFetch<T>(url, { baseURL: NPM_REGISTRY, ...options }, ttl)
+      },
+      npmApi: <T>(
+        url: Parameters<CachedFetchFunction>[0],
+        options?: Parameters<CachedFetchFunction>[1],
+        ttl?: Parameters<CachedFetchFunction>[2],
+      ) => {
+        return cachedFetch<T>(url, { baseURL: NPM_API, ...options }, ttl)
+      },
+    },
+  }
+})

app/utils/npm/api.ts

···
 import type { PackageVersionInfo } from '#shared/types'
 import { getVersions } from 'fast-npm-meta'
 import { compare } from 'semver'
-import { NPM_API } from './common'
 
 type NpmDownloadsRangeResponse = {
   start: string
···
   start: string,
   end: string,
 ): Promise<NpmDownloadsRangeResponse> {
+  const { $npmApi } = useNuxtApp()
   const encodedName = encodePackageName(packageName)
-  return await $fetch<NpmDownloadsRangeResponse>(
-    `${NPM_API}/downloads/range/${start}:${end}/${encodedName}`,
-  )
+  return (
+    await $npmApi<NpmDownloadsRangeResponse>(`/downloads/range/${start}:${end}/${encodedName}`)
+  ).data
 }
 
 // ============================================================================

app/utils/npm/common.ts

···
-export const NPM_REGISTRY = 'https://registry.npmjs.org'
-export const NPM_API = 'https://api.npmjs.org'
-
 /**
  * Constructs a scope:team string in the format expected by npm.
  * npm operations require the format @scope:team (with @ prefix).

app/utils/package-name.ts

···
 import validatePackageName from 'validate-npm-package-name'
+import { NPM_REGISTRY } from '#shared/utils/constants'
 import { encodePackageName } from '#shared/utils/npm'
 
 /**
···
   validationWarnings?: string[]
   similarPackages?: SimilarPackage[]
 }
-
-const NPM_REGISTRY = 'https://registry.npmjs.org'
 
 export async function checkPackageExists(
   name: string,

package.json

···
     "@vitest/coverage-v8": "4.0.18",
     "@vue/test-utils": "2.4.6",
     "axe-core": "4.11.1",
+    "defu": "6.1.4",
     "eslint-plugin-regexp": "3.0.0",
     "fast-check": "4.5.3",
     "h3": "1.15.5",

shared/utils/constants.ts

···
 export const BLUESKY_API = 'https://public.api.bsky.app/xrpc/'
 export const BLUESKY_COMMENTS_REQUEST = '/api/atproto/bluesky-comments'
 export const NPM_REGISTRY = 'https://registry.npmjs.org'
+export const NPM_API = 'https://api.npmjs.org'
 export const ERROR_PACKAGE_ANALYSIS_FAILED = 'Failed to analyze package.'
 export const ERROR_PACKAGE_VERSION_AND_FILE_FAILED = 'Version and file path are required.'
 export const ERROR_PACKAGE_REQUIREMENTS_FAILED =

test/nuxt/composables/use-npm-registry.spec.ts

···
 
     // Check that fetch was called with the correct URL (first argument)
     expect(fetchSpy).toHaveBeenCalled()
-    expect(fetchSpy.mock.calls[0]?.[0]).toBe('https://api.npmjs.org/downloads/point/last-week/vue')
+    expect(fetchSpy.mock.calls[0]?.[0]).toBe('/downloads/point/last-week/vue')
     expect(data.value?.downloads).toBe(1234567)
   })
 
···
 
     // Check that fetch was called with the correct URL (first argument)
     expect(fetchSpy).toHaveBeenCalled()
-    expect(fetchSpy.mock.calls[0]?.[0]).toBe('https://api.npmjs.org/downloads/point/last-month/vue')
+    expect(fetchSpy.mock.calls[0]?.[0]).toBe('/downloads/point/last-month/vue')
   })
 
   it('should encode scoped package names', async () => {
···
 
     // Check that fetch was called with the correct URL (first argument)
     expect(fetchSpy).toHaveBeenCalled()
-    expect(fetchSpy.mock.calls[0]?.[0]).toBe(
-      'https://api.npmjs.org/downloads/point/last-week/@vue%2Fcore',
-    )
+    expect(fetchSpy.mock.calls[0]?.[0]).toBe('/downloads/point/last-week/@vue%2Fcore')
   })
 })