refactor: extract parsePackageSpecifier as a shared util

Author: serhalp

app/pages/search.vue

@@ -5,6 +5,7 @@ import { onKeyDown } from '@vueuse/core'
 import { debounce } from 'perfect-debounce'
 import { isValidNewPackageName } from '~/utils/package-name'
 import { isPlatformSpecificPackage } from '~/utils/platform-packages'
+import { parsePackageSpecifier } from '#shared/utils/parse-package-param'
 import { normalizeSearchParam } from '#shared/utils/url'
 
 const route = useRoute()
@@ -422,16 +423,6 @@ function focusElement(el: HTMLElement) {
   el.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
 }
 
-// Parse "pkg@version" from search input (e.g. "esbuild@0.25.12", "@angular/core@^18")
-function parsePackageAtVersion(input: string): { name: string; version?: string } {
-  const atIndex = input.startsWith('@') ? input.indexOf('@', 1) : input.indexOf('@')
-  if (atIndex > 0) {
-    const version = input.slice(atIndex + 1)
-    if (version) return { name: input.slice(0, atIndex), version }
-  }
-  return { name: input }
-}
-
 // Navigate to package page
 async function navigateToPackage(packageName: string) {
   await navigateTo(packageRoute(packageName))
@@ -471,7 +462,7 @@ function handleResultsKeydown(e: KeyboardEvent) {
     if (!inputValue) return
 
     // Handle "pkg@version" format (e.g. "esbuild@0.25.12", "@angular/core@^18")
-    const { name, version } = parsePackageAtVersion(inputValue)
+    const { name, version } = parsePackageSpecifier(inputValue)
     if (version) {
       return navigateTo(packageRoute(name, version))
     }

modules/runtime/server/cache.ts

@@ -1,5 +1,6 @@
 import process from 'node:process'
 import type { CachedFetchResult } from '#shared/utils/fetch-cache-config'
+import { parsePackageSpecifier } from '#shared/utils/parse-package-param'
 import { createFetch } from 'ofetch'
 
 /**
@@ -64,42 +65,6 @@ function getFixturePath(type: FixtureType, name: string): string {
   return `${dir}:${filename.replace(/\//g, ':')}`
 }
 
-/**
- * Parse a scoped package name with optional version.
- * Handles formats like: @scope/name, @scope/name@version, name, name@version
- */
-function parseScopedPackageWithVersion(input: string): { name: string; version?: string } {
-  if (input.startsWith('@')) {
-    // Scoped package: @scope/name or @scope/name@version
-    const slashIndex = input.indexOf('/')
-    if (slashIndex === -1) {
-      // Invalid format like just "@scope"
-      return { name: input }
-    }
-    const afterSlash = input.slice(slashIndex + 1)
-    const atIndex = afterSlash.indexOf('@')
-    if (atIndex === -1) {
-      // @scope/name (no version)
-      return { name: input }
-    }
-    // @scope/name@version
-    return {
-      name: input.slice(0, slashIndex + 1 + atIndex),
-      version: afterSlash.slice(atIndex + 1),
-    }
-  }
-
-  // Unscoped package: name or name@version
-  const atIndex = input.indexOf('@')
-  if (atIndex === -1) {
-    return { name: input }
-  }
-  return {
-    name: input.slice(0, atIndex),
-    version: input.slice(atIndex + 1),
-  }
-}
-
 function getMockForUrl(url: string): MockResult | null {
   let urlObj: URL
   try {
@@ -174,7 +139,7 @@ function getMockForUrl(url: string): MockResult | null {
     const packageMatch = decodeURIComponent(pathname).match(/^\/v1\/packages\/npm\/(.+)$/)
     if (packageMatch?.[1]) {
       const pkgWithVersion = packageMatch[1]
-      const parsed = parseScopedPackageWithVersion(pkgWithVersion)
+      const parsed = parsePackageSpecifier(pkgWithVersion)
       return {
         data: {
           type: 'npm',

shared/utils/parse-package-param.ts

@@ -35,6 +35,31 @@ export interface ParsedPackageParams {
  * // { packageName: '@nuxt/kit', version: '1.0.0', rest: ['src', 'index.ts'] }
  * ```
  */
+/**
+ * Parse a "pkg@version" specifier string into name and optional version.
+ * Handles scoped packages correctly (the scope `@` is not treated as a version separator).
+ *
+ * @example
+ * ```ts
+ * parsePackageSpecifier('esbuild@0.25.12')
+ * // { name: 'esbuild', version: '0.25.12' }
+ *
+ * parsePackageSpecifier('@angular/core@^18')
+ * // { name: '@angular/core', version: '^18' }
+ *
+ * parsePackageSpecifier('react')
+ * // { name: 'react' }
+ * ```
+ */
+export function parsePackageSpecifier(input: string): { name: string; version?: string } {
+  const atIndex = input.startsWith('@') ? input.indexOf('@', 1) : input.indexOf('@')
+  if (atIndex > 0) {
+    const version = input.slice(atIndex + 1)
+    if (version) return { name: input.slice(0, atIndex), version }
+  }
+  return { name: input }
+}
+
 export function parsePackageParam(pkgParam: string): ParsedPackageParams {
   const segments = pkgParam.split('/')
   const vIndex = segments.indexOf('v')

test/unit/shared/utils/parse-package-param.spec.ts

@@ -1,126 +1,62 @@
 import { describe, expect, it } from 'vitest'
-import { parsePackageParam } from '../../../../shared/utils/parse-package-param'
+import { parsePackageSpecifier } from '../../../../shared/utils/parse-package-param'
 
-describe('parsePackageParam', () => {
-  describe('unscoped packages', () => {
-    it('parses package name without version', () => {
-      const result = parsePackageParam('vue')
-      expect(result).toEqual({
-        packageName: 'vue',
-        version: undefined,
-        rest: [],
-      })
-    })
-
-    it('parses package name with version', () => {
-      const result = parsePackageParam('vue/v/3.4.0')
-      expect(result).toEqual({
-        packageName: 'vue',
-        version: '3.4.0',
-        rest: [],
-      })
-    })
-
-    it('parses package name with prerelease version', () => {
-      const result = parsePackageParam('nuxt/v/4.0.0-rc.1')
-      expect(result).toEqual({
-        packageName: 'nuxt',
-        version: '4.0.0-rc.1',
-        rest: [],
-      })
-    })
-
-    it('parses package name with version and file path', () => {
-      const result = parsePackageParam('vue/v/3.4.0/src/index.ts')
-      expect(result).toEqual({
-        packageName: 'vue',
-        version: '3.4.0',
-        rest: ['src', 'index.ts'],
-      })
+describe('parsePackageSpecifier', () => {
+  it('parses unscoped package with exact version', () => {
+    expect(parsePackageSpecifier('esbuild@0.25.12')).toEqual({
+      name: 'esbuild',
+      version: '0.25.12',
     })
+  })
 
-    it('parses package name with version and nested file path', () => {
-      const result = parsePackageParam('lodash/v/4.17.21/lib/fp/map.js')
-      expect(result).toEqual({
-        packageName: 'lodash',
-        version: '4.17.21',
-        rest: ['lib', 'fp', 'map.js'],
-      })
+  it('parses unscoped package with caret range', () => {
+    expect(parsePackageSpecifier('react@^18.0.0')).toEqual({
+      name: 'react',
+      version: '^18.0.0',
     })
   })
 
-  describe('scoped packages', () => {
-    it('parses scoped package name without version', () => {
-      const result = parsePackageParam('@nuxt/kit')
-      expect(result).toEqual({
-        packageName: '@nuxt/kit',
-        version: undefined,
-        rest: [],
-      })
+  it('parses scoped package with exact version', () => {
+    expect(parsePackageSpecifier('@angular/core@18.0.0')).toEqual({
+      name: '@angular/core',
+      version: '18.0.0',
     })
+  })
 
-    it('parses scoped package name with version', () => {
-      const result = parsePackageParam('@nuxt/kit/v/1.0.0')
-      expect(result).toEqual({
-        packageName: '@nuxt/kit',
-        version: '1.0.0',
-        rest: [],
-      })
+  it('parses scoped package with range', () => {
+    expect(parsePackageSpecifier('@angular/core@^18')).toEqual({
+      name: '@angular/core',
+      version: '^18',
     })
+  })
 
-    it('parses scoped package name with version and file path', () => {
-      const result = parsePackageParam('@vue/compiler-sfc/v/3.5.0/dist/index.d.ts')
-      expect(result).toEqual({
-        packageName: '@vue/compiler-sfc',
-        version: '3.5.0',
-        rest: ['dist', 'index.d.ts'],
-      })
-    })
+  it('returns name only for unscoped package without version', () => {
+    expect(parsePackageSpecifier('esbuild')).toEqual({ name: 'esbuild' })
+  })
 
-    it('parses deeply nested scoped packages', () => {
-      const result = parsePackageParam('@types/node/v/22.0.0')
-      expect(result).toEqual({
-        packageName: '@types/node',
-        version: '22.0.0',
-        rest: [],
-      })
-    })
+  it('returns name only for scoped package without version', () => {
+    expect(parsePackageSpecifier('@angular/core')).toEqual({ name: '@angular/core' })
   })
 
-  describe('edge cases', () => {
-    it('handles package name that looks like a version marker', () => {
-      // Package named "v" shouldn't be confused with version separator
-      const result = parsePackageParam('v')
-      expect(result).toEqual({
-        packageName: 'v',
-        version: undefined,
-        rest: [],
-      })
-    })
+  it('returns name only for bare scope', () => {
+    expect(parsePackageSpecifier('@angular')).toEqual({ name: '@angular' })
+  })
 
-    it('handles version segment without actual version', () => {
-      // "v" at the end without a version after it
-      const result = parsePackageParam('vue/v')
-      expect(result).toEqual({
-        packageName: 'vue/v',
-        version: undefined,
-        rest: [],
-      })
-    })
+  it('handles trailing @ with no version', () => {
+    expect(parsePackageSpecifier('esbuild@')).toEqual({ name: 'esbuild@' })
+  })
 
-    it('handles package with "v" in the name followed by version', () => {
-      const result = parsePackageParam('vueuse/v/12.0.0')
-      expect(result).toEqual({
-        packageName: 'vueuse',
-        version: '12.0.0',
-        rest: [],
-      })
+  it('parses version with union range', () => {
+    expect(parsePackageSpecifier('@angular/core@^18 || ^19')).toEqual({
+      name: '@angular/core',
+      version: '^18 || ^19',
     })
+  })
 
-    it('handles empty rest when file path is empty', () => {
-      const result = parsePackageParam('react/v/18.2.0')
-      expect(result.rest).toEqual([])
-      expect(result.rest.length).toBe(0)
+  it('parses dist-tag as version', () => {
+    expect(parsePackageSpecifier('nuxt@latest')).toEqual({
+      name: 'nuxt',
+      version: 'latest',
     })
   })
 })