Automatically redirect unresolved versions in unpkg demo

Author: mjackson

demos/unpkg/README.md

@@ -12,17 +12,12 @@ pnpm start
 
 Then visit http://localhost:44100
 
-Try browsing packages:
-
-- http://localhost:44100/lodash
-- http://localhost:44100/react@18
-- http://localhost:44100/@remix-run/cookie
-- http://localhost:44100/express/package.json
+Semver ranges are supported (via the [semver](https://www.npmjs.com/package/semver) package). URLs without a version, or with partial/range versions, automatically redirect to the fully resolved version.
 
 ## Code Highlights
 
 - [`app/routes.ts`](app/routes.ts) uses a single `/*path` route to handle all package URLs. This one pattern handles package names, versions, scoped packages, and file paths.
 - [`app/lib/npm.ts`](app/lib/npm.ts) fetches package tarballs from npm, decompresses them with `node:zlib`, and parses them using `@remix-run/tar-parser`. The `parsePackagePath()` function handles the tricky parsing of URLs like `/@remix-run/[email protected]/src/index.ts`.
-- Also in [`app/lib/npm.ts`](app/lib/npm.ts), `resolveVersion()` handles dist-tags like `latest`, exact versions, and partial versions (e.g., `18` resolves to `18.3.1`).
+- Also in [`app/lib/npm.ts`](app/lib/npm.ts), `resolveVersion()` handles dist-tags like `latest`, exact versions, partial versions (e.g., `18` resolves to `18.3.1`), and semver ranges (e.g., `^18.2` or `~1.0.0`).
 - [`app/lib/cache.ts`](app/lib/cache.ts) caches decompressed tarballs to the temp directory using `@remix-run/file-storage`. This avoids re-downloading packages on repeated requests.
 - [`app/lib/render.ts`](app/lib/render.ts) uses the `html` template tag from `@remix-run/html-template` for safe HTML generation with automatic XSS escaping.

demos/unpkg/app/lib/npm.test.ts

@@ -4,6 +4,7 @@ import { describe, it } from 'node:test'
 import {
   parsePackagePath,
   resolveVersion,
+  isFullyResolvedVersion,
   getFilesAtPath,
   PackageNotFoundError,
   VersionNotFoundError,
@@ -76,6 +77,21 @@ describe('parsePackagePath', () => {
       name: 'InvalidPathError',
     })
   })
+
+  it('parses URL-encoded caret semver range', () => {
+    let result = parsePackagePath('react@%5E18.2')
+    assert.deepEqual(result, { name: 'react', version: '^18.2', filePath: '' })
+  })
+
+  it('parses URL-encoded tilde semver range', () => {
+    let result = parsePackagePath('lodash@%7E4.17')
+    assert.deepEqual(result, { name: 'lodash', version: '~4.17', filePath: '' })
+  })
+
+  it('parses unencoded semver range', () => {
+    let result = parsePackagePath('react@^18.2')
+    assert.deepEqual(result, { name: 'react', version: '^18.2', filePath: '' })
+  })
 })
 
 describe('resolveVersion', () => {
@@ -150,6 +166,73 @@ describe('resolveVersion', () => {
       name: 'VersionNotFoundError',
     })
   })
+
+  it('resolves caret range to highest matching version', () => {
+    assert.equal(resolveVersion(mockMetadata, '^1.0.0'), '1.1.0')
+  })
+
+  it('resolves tilde range to highest matching version', () => {
+    assert.equal(resolveVersion(mockMetadata, '~1.0.0'), '1.0.1')
+  })
+
+  it('resolves greater-than-or-equal range', () => {
+    assert.equal(resolveVersion(mockMetadata, '>=1.0.0'), '2.0.0')
+  })
+
+  it('resolves complex semver range', () => {
+    assert.equal(resolveVersion(mockMetadata, '>=1.0.0 <2.0.0'), '1.1.0')
+  })
+
+  it('throws for semver range with no matching version', () => {
+    assert.throws(() => resolveVersion(mockMetadata, '^5.0.0'), {
+      name: 'VersionNotFoundError',
+    })
+  })
+})
+
+describe('isFullyResolvedVersion', () => {
+  let mockMetadata: PackageMetadata = {
+    name: 'test-package',
+    'dist-tags': {
+      latest: '2.0.0',
+    },
+    versions: {
+      '1.0.0': {
+        name: 'test-package',
+        version: '1.0.0',
+        dist: { tarball: 'http://example.com/1.0.0.tgz', shasum: 'abc' },
+      },
+      '2.0.0': {
+        name: 'test-package',
+        version: '2.0.0',
+        dist: { tarball: 'http://example.com/2.0.0.tgz', shasum: 'def' },
+      },
+    },
+  }
+
+  it('returns true for exact version in versions', () => {
+    assert.equal(isFullyResolvedVersion(mockMetadata, '1.0.0'), true)
+    assert.equal(isFullyResolvedVersion(mockMetadata, '2.0.0'), true)
+  })
+
+  it('returns false for dist-tag', () => {
+    assert.equal(isFullyResolvedVersion(mockMetadata, 'latest'), false)
+  })
+
+  it('returns false for partial version', () => {
+    assert.equal(isFullyResolvedVersion(mockMetadata, '1'), false)
+    assert.equal(isFullyResolvedVersion(mockMetadata, '1.0'), false)
+  })
+
+  it('returns false for semver range', () => {
+    assert.equal(isFullyResolvedVersion(mockMetadata, '^1.0.0'), false)
+    assert.equal(isFullyResolvedVersion(mockMetadata, '~1.0.0'), false)
+    assert.equal(isFullyResolvedVersion(mockMetadata, '>=1.0.0'), false)
+  })
+
+  it('returns false for non-existent version', () => {
+    assert.equal(isFullyResolvedVersion(mockMetadata, '3.0.0'), false)
+  })
 })
 
 describe('getFilesAtPath', () => {

demos/unpkg/app/lib/npm.ts

@@ -1,5 +1,6 @@
 import * as zlib from 'node:zlib'
 import { parseTar, type TarEntry } from '@remix-run/tar-parser'
+import * as semver from 'semver'
 
 import { tarballCache, getTarballCacheKey } from './cache.ts'
 
@@ -52,11 +53,19 @@ export async function fetchPackageMetadata(packageName: string): Promise<Package
   return response.json()
 }
 
+/**
+ * Check if a version specifier is fully resolved (an exact version that exists).
+ */
+export function isFullyResolvedVersion(metadata: PackageMetadata, specifier: string): boolean {
+  return specifier in metadata.versions
+}
+
 /**
  * Resolve a version specifier to a concrete version.
  * Supports:
  * - Exact versions: "1.2.3"
  * - Partial versions: "1", "1.2" -> matches highest in range
+ * - Semver ranges: "^1.2.0", "~1.2.0", ">=1.0.0 <2.0.0"
  * - Dist tags: "latest", "beta"
  */
 export function resolveVersion(metadata: PackageMetadata, specifier: string): string {
@@ -70,33 +79,27 @@ export function resolveVersion(metadata: PackageMetadata, specifier: string): st
     return specifier
   }
 
-  // Try to match as a partial version (e.g., "18" matches "18.3.1")
   let versions = Object.keys(metadata.versions)
-  let matching = versions.filter((v) => v.startsWith(specifier + '.') || v === specifier)
 
-  if (matching.length > 0) {
-    // Sort by semver and return highest
-    matching.sort(compareSemver)
-    return matching[matching.length - 1]
+  // Try to match as a semver range (^1.2.0, ~1.0.0, >=1.0.0, etc.)
+  if (semver.validRange(specifier)) {
+    let match = semver.maxSatisfying(versions, specifier)
+    if (match) {
+      return match
+    }
   }
 
-  throw new VersionNotFoundError(metadata.name, specifier)
-}
-
-/**
- * Compare two semver strings for sorting.
- */
-function compareSemver(a: string, b: string): number {
-  let partsA = a.split('.').map((p) => parseInt(p, 10) || 0)
-  let partsB = b.split('.').map((p) => parseInt(p, 10) || 0)
-
-  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
-    let numA = partsA[i] || 0
-    let numB = partsB[i] || 0
-    if (numA !== numB) return numA - numB
+  // Try to match as a partial version (e.g., "18" matches "18.3.1")
+  // Convert partial version to a range: "18" -> "18.x", "18.2" -> "18.2.x"
+  let partialRange = specifier + '.x'
+  if (semver.validRange(partialRange)) {
+    let match = semver.maxSatisfying(versions, partialRange)
+    if (match) {
+      return match
+    }
   }
 
-  return 0
+  throw new VersionNotFoundError(metadata.name, specifier)
 }
 
 /**
@@ -282,13 +285,16 @@ export function getFilesAtPath(files: Map<string, PackageFile>, dirPath: string)
  *   "lodash@4/package.json" -> { name: "lodash", version: "4", filePath: "package.json" }
  *   "@remix-run/cookie" -> { name: "@remix-run/cookie", version: "latest", filePath: "" }
  *   "@remix-run/[email protected]/src/index.ts" -> { name: "@remix-run/cookie", version: "1.0.0", filePath: "src/index.ts" }
+ *   "react@^18.2" -> { name: "react", version: "^18.2", filePath: "" } (semver range)
  */
 export function parsePackagePath(path: string): {
   name: string
   version: string
   filePath: string
 } {
-  let parts = path.split('/')
+  // Decode URL-encoded characters (e.g., %5E -> ^, %7E -> ~)
+  let decodedPath = decodeURIComponent(path)
+  let parts = decodedPath.split('/')
   let name: string
   let rest: string[]
 

demos/unpkg/app/pages/browse.ts

@@ -5,8 +5,11 @@ import { lookup } from 'mrmime'
 import { html, render, formatBytes, icons } from '../lib/render.ts'
 import {
   parsePackagePath,
+  fetchPackageMetadata,
   fetchPackageContents,
   getFilesAtPath,
+  isFullyResolvedVersion,
+  resolveVersion,
   PackageNotFoundError,
   VersionNotFoundError,
   InvalidPathError,
@@ -27,6 +30,17 @@ export async function browseHandler(
 
   try {
     let { name, version, filePath } = parsePackagePath(path)
+
+    // Fetch metadata first to check if version needs resolution
+    let metadata = await fetchPackageMetadata(name)
+
+    // If the version is not fully resolved, redirect to the resolved version URL
+    if (!isFullyResolvedVersion(metadata, version)) {
+      let resolvedVersion = resolveVersion(metadata, version)
+      let redirectUrl = `/${name}@${resolvedVersion}${filePath ? '/' + filePath : ''}`
+      return redirect(redirectUrl)
+    }
+
     let contents = await fetchPackageContents(name, version)
     let resolvedVersion = contents.metadata.version
 

demos/unpkg/app/router.test.ts

@@ -108,4 +108,87 @@ describe('router', () => {
       assert.equal(response.status, 404)
     })
   })
+
+  describe('version redirects', () => {
+    it('redirects package without version to latest', async () => {
+      let response = await router.fetch(new Request('http://localhost/is-number'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]')
+    })
+
+    it('redirects dist-tag "latest" to resolved version', async () => {
+      let response = await router.fetch(new Request('http://localhost/is-number@latest'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]')
+    })
+
+    it('redirects partial major version to highest match', async () => {
+      let response = await router.fetch(new Request('http://localhost/is-number@1'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]')
+    })
+
+    it('redirects partial major.minor version to highest match', async () => {
+      let response = await router.fetch(new Request('http://localhost/[email protected]'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]')
+    })
+
+    it('redirects caret semver range to highest compatible version', async () => {
+      let response = await router.fetch(new Request('http://localhost/is-number@^1.0.0'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]')
+    })
+
+    it('redirects tilde semver range to highest patch version', async () => {
+      let response = await router.fetch(new Request('http://localhost/is-number@~1.1.0'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]')
+    })
+
+    it('redirects URL-encoded caret range', async () => {
+      // %5E is URL-encoded ^
+      let response = await router.fetch(new Request('http://localhost/is-number@%5E2.0.0'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]')
+    })
+
+    it('redirects URL-encoded tilde range', async () => {
+      // %7E is URL-encoded ~
+      let response = await router.fetch(new Request('http://localhost/is-number@%7E2.0.0'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]')
+    })
+
+    it('redirects complex semver range', async () => {
+      let response = await router.fetch(new Request('http://localhost/is-number@>=1.0.0 <2.0.0'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]')
+    })
+
+    it('preserves file path in redirect', async () => {
+      let response = await router.fetch(new Request('http://localhost/is-number@^7/package.json'))
+
+      assert.equal(response.status, 302)
+      assert.equal(response.headers.get('Location'), '/[email protected]/package.json')
+    })
+
+    it('does not redirect fully resolved version', async () => {
+      let response = await router.fetch(new Request('http://localhost/[email protected]'))
+
+      // Should return 200 (directory listing), not a redirect
+      assert.equal(response.status, 200)
+      let text = await response.text()
+      assert.ok(text.includes('is-number'))
+    })
+  })
 })

demos/unpkg/package.json

@@ -10,10 +10,12 @@
     "@remix-run/node-fetch-server": "workspace:*",
     "@remix-run/response": "workspace:*",
     "@remix-run/tar-parser": "workspace:*",
-    "mrmime": "^2.0.0"
+    "mrmime": "^2.0.0",
+    "semver": "^7.6.3"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
+    "@types/semver": "^7.5.8",
     "tsx": "^4.20.6"
   },
   "scripts": {