feat: add valibot & implement validation/error handling for BE APIs

Author: Kai-ros

package.json

@@ -43,6 +43,7 @@
     "shiki": "^3.21.0",
     "ufo": "^1.6.3",
     "unplugin-vue-router": "^0.19.2",
+    "valibot": "^1.2.0",
     "validate-npm-package-name": "^7.0.2",
     "virtua": "^0.48.3",
     "vue": "3.5.27",

pnpm-lock.yaml

@@ -1,3 +1,6 @@
+import * as v from 'valibot'
+import { PackageNameSchema } from '#shared/schemas/package'
+import { CACHE_MAX_AGE_ONE_HOUR, ERROR_JSR_FETCH_FAILED } from '#shared/utils/constants'
 import type { JsrPackageInfo } from '#shared/types/jsr'
 
 /**
@@ -11,17 +14,25 @@ import type { JsrPackageInfo } from '#shared/types/jsr'
 export default defineCachedEventHandler<Promise<JsrPackageInfo>>(
   async event => {
     const pkgPath = getRouterParam(event, 'pkg')
-    if (!pkgPath) {
-      throw createError({ statusCode: 400, message: 'Package name is required' })
-    }
-    assertValidPackageName(pkgPath)
 
-    return await fetchJsrPackageInfo(pkgPath)
+    try {
+      const packageName = v.parse(PackageNameSchema, pkgPath)
+
+      return await fetchJsrPackageInfo(packageName)
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: ERROR_JSR_FETCH_FAILED,
+      })
+    }
   },
   {
-    maxAge: 60 * 60, // 1 hour
+    maxAge: CACHE_MAX_AGE_ONE_HOUR,
     swr: true,
     name: 'api-jsr-package',
-    getKey: event => getRouterParam(event, 'pkg') ?? '',
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      return `jsr:v1:${pkg.replace(/\/+$/, '').trim()}`
+    },
   },
 )

server/api/jsr/[...pkg].get.ts

@@ -1,25 +1,28 @@
+import * as v from 'valibot'
+import { PackageNameSchema } from '#shared/schemas/package'
+import { CACHE_MAX_AGE_ONE_HOUR, ERROR_NPM_FETCH_FAILED } from '#shared/utils/constants'
+
 export default defineCachedEventHandler(
   async event => {
-    const pkg = getRouterParam(event, 'pkg')
-    if (!pkg) {
-      throw createError({ statusCode: 400, message: 'Package name is required' })
-    }
+    try {
+      const pkg = getRouterParam(event, 'pkg')
 
-    const packageName = pkg.replace(/\//g, '/')
-    assertValidPackageName(packageName)
+      const packageName = v.parse(PackageNameSchema, pkg)
 
-    try {
       return await fetchNpmPackage(packageName)
-    } catch (error) {
-      if (error && typeof error === 'object' && 'statusCode' in error) {
-        throw error
-      }
-      throw createError({ statusCode: 502, message: 'Failed to fetch package from npm registry' })
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: ERROR_NPM_FETCH_FAILED,
+      })
     }
   },
   {
-    maxAge: 60 * 60, // 1 hour
+    maxAge: CACHE_MAX_AGE_ONE_HOUR,
     swr: true,
-    getKey: event => getRouterParam(event, 'pkg') ?? '',
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      return `packument:v1:${pkg.replace(/\/+$/, '').trim()}`
+    },
   },
 )

server/api/registry/[...pkg].get.ts

@@ -1,34 +1,31 @@
+import * as v from 'valibot'
+import { PackageRouteParamsSchema } from '#shared/schemas/package'
 import type { PackageAnalysis, ExtendedPackageJson } from '#shared/utils/package-analysis'
 import {
   analyzePackage,
   getTypesPackageName,
   hasBuiltInTypes,
 } from '#shared/utils/package-analysis'
-
-const NPM_REGISTRY = 'https://registry.npmjs.org'
+import {
+  NPM_REGISTRY,
+  CACHE_MAX_AGE_ONE_DAY,
+  ERROR_PACKAGE_ANALYSIS_FAILED,
+} from '#shared/utils/constants'
 
 export default defineCachedEventHandler(
   async event => {
-    const pkgParam = getRouterParam(event, 'pkg')
-    if (!pkgParam) {
-      throw createError({ statusCode: 400, message: 'Package name is required' })
-    }
-
     // Parse package name and optional version from path
     // e.g., "vue" or "vue/v/3.4.0" or "@nuxt/kit" or "@nuxt/kit/v/1.0.0"
-    const segments = pkgParam.split('/')
-    let packageName: string
-    let version: string | undefined
+    const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
 
-    const vIndex = segments.indexOf('v')
-    if (vIndex !== -1 && vIndex < segments.length - 1) {
-      packageName = segments.slice(0, vIndex).join('/')
-      version = segments.slice(vIndex + 1).join('/')
-    } else {
-      packageName = segments.join('/')
-    }
+    const { rawPackageName, rawVersion } = parsePackageParams(pkgParamSegments)
 
     try {
+      const { packageName, version } = v.parse(PackageRouteParamsSchema, {
+        packageName: rawPackageName,
+        version: rawVersion,
+      })
+
       // Fetch package data
       const encodedName = encodePackageName(packageName)
       const versionSuffix = version ? `/${version}` : '/latest'
@@ -39,8 +36,8 @@ export default defineCachedEventHandler(
       // Only check for @types package if the package doesn't ship its own types
       let typesPackageExists = false
       if (!hasBuiltInTypes(pkg)) {
-        const typesPackageName = getTypesPackageName(packageName)
-        typesPackageExists = await checkPackageExists(typesPackageName)
+        const typesPkgName = getTypesPackageName(packageName)
+        typesPackageExists = await checkPackageExists(typesPkgName)
       }
 
       const analysis = analyzePackage(pkg, { typesPackageExists })
@@ -50,20 +47,20 @@ export default defineCachedEventHandler(
         version: pkg.version ?? version ?? 'latest',
         ...analysis,
       } satisfies PackageAnalysisResponse
-    } catch (error) {
-      if (error && typeof error === 'object' && 'statusCode' in error) {
-        throw error
-      }
-      throw createError({
+    } catch (error: unknown) {
+      handleApiError(error, {
         statusCode: 502,
-        message: 'Failed to analyze package',
+        message: ERROR_PACKAGE_ANALYSIS_FAILED,
       })
     }
   },
   {
-    maxAge: 60 * 60 * 24, // 24 hours - analysis rarely changes
+    maxAge: CACHE_MAX_AGE_ONE_DAY, // 24 hours - analysis rarely changes
     swr: true,
-    getKey: event => getRouterParam(event, 'pkg') ?? '',
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      return `analysis:v1:${pkg.replace(/\/+$/, '').trim()}`
+    },
   },
 )
 

server/api/registry/analysis/[...pkg].get.ts

@@ -1,3 +1,10 @@
+import * as v from 'valibot'
+import { PackageFileQuerySchema } from '#shared/schemas/package'
+import {
+  CACHE_MAX_AGE_ONE_YEAR,
+  ERROR_PACKAGE_VERSION_AND_FILE_FAILED,
+} from '#shared/utils/constants'
+
 const CACHE_VERSION = 2
 
 // Maximum file size to fetch and highlight (500KB)
@@ -50,7 +57,10 @@ async function fetchFileContent(
     if (response.status === 404) {
       throw createError({ statusCode: 404, message: 'File not found' })
     }
-    throw createError({ statusCode: 502, message: 'Failed to fetch file from jsDelivr' })
+    throw createError({
+      statusCode: 502,
+      message: 'Failed to fetch file from jsDelivr',
+    })
   }
 
   // Check content-length header if available
@@ -84,38 +94,33 @@ async function fetchFileContent(
  */
 export default defineCachedEventHandler(
   async event => {
-    const segments = getRouterParam(event, 'pkg')?.split('/') ?? []
-    if (segments.length === 0) {
-      throw createError({
-        statusCode: 400,
-        message: 'Package name, version, and file path are required',
-      })
-    }
-
     // Parse: [pkg, 'v', version, ...filePath] or [@scope, pkg, 'v', version, ...filePath]
-    const vIndex = segments.indexOf('v')
-    if (vIndex === -1 || vIndex >= segments.length - 2) {
-      throw createError({ statusCode: 400, message: 'Version and file path are required' })
-    }
+    const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
 
-    const packageName = segments.slice(0, vIndex).join('/')
-    // Find where version ends (next segment after 'v') and file path begins
-    // Version could be like "1.2.3" or "1.2.3-beta.1"
-    const versionAndPath = segments.slice(vIndex + 1)
+    const { rawPackageName, rawVersion: fullPathAfterV } = parsePackageParams(pkgParamSegments)
 
-    // The version is the first segment after 'v', and everything else is the file path
-    const version = versionAndPath[0]
-    const filePath = versionAndPath.slice(1).join('/')
+    // Since version AND path route are required, we split the remainder
+    // fullPathAfterV => "1.2.3/dist/index.mjs"
+    const versionSegments = fullPathAfterV?.split('/') ?? []
 
-    if (!packageName || !version || !filePath) {
+    if (versionSegments.length < 2) {
       throw createError({
         statusCode: 400,
-        message: 'Package name, version, and file path are required',
+        message: ERROR_PACKAGE_VERSION_AND_FILE_FAILED,
       })
     }
-    assertValidPackageName(packageName)
+
+    // The version is the first segment after 'v', and everything else is the file path
+    const rawVersion = versionSegments[0]
+    const rawFilePath = versionSegments.slice(1).join('/')
 
     try {
+      const { packageName, version, filePath } = v.parse(PackageFileQuerySchema, {
+        packageName: rawPackageName,
+        version: rawVersion,
+        filePath: rawFilePath,
+      })
+
       const content = await fetchFileContent(packageName, version, filePath)
       const language = getLanguageFromPath(filePath)
 
@@ -156,7 +161,10 @@ export default defineCachedEventHandler(
         }
       }
 
-      const html = await highlightCode(content, language, { dependencies, resolveRelative })
+      const html = await highlightCode(content, language, {
+        dependencies,
+        resolveRelative,
+      })
 
       return {
         package: packageName,
@@ -167,19 +175,19 @@ export default defineCachedEventHandler(
         html,
         lines: content.split('\n').length,
       }
-    } catch (error) {
-      if (error && typeof error === 'object' && 'statusCode' in error) {
-        throw error
-      }
-      throw createError({ statusCode: 502, message: 'Failed to fetch file content' })
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: 'Failed to fetch file content',
+      })
     }
   },
   {
     // File content for a specific version never changes - cache permanently
-    maxAge: 60 * 60 * 24 * 365, // 1 year
+    maxAge: CACHE_MAX_AGE_ONE_YEAR, // 1 year
     getKey: event => {
       const pkg = getRouterParam(event, 'pkg') ?? ''
-      return `file:v${CACHE_VERSION}:${pkg}`
+      return `file:v${CACHE_VERSION}:${pkg.replace(/\/+$/, '').trim()}`
     },
   },
 )

server/api/registry/file/[...pkg].get.ts

@@ -1,4 +1,7 @@
+import * as v from 'valibot'
+import { PackageVersionQuerySchema } from '#shared/schemas/package'
 import type { PackageFileTreeResponse } from '#shared/types'
+import { CACHE_MAX_AGE_ONE_YEAR, ERROR_FILE_LIST_FETCH_FAILED } from '#shared/utils/constants'
 
 /**
  * Returns the file tree for a package version.
@@ -9,27 +12,18 @@ import type { PackageFileTreeResponse } from '#shared/types'
  */
 export default defineCachedEventHandler(
   async event => {
-    const segments = getRouterParam(event, 'pkg')?.split('/') ?? []
-    if (segments.length === 0) {
-      throw createError({ statusCode: 400, message: 'Package name and version are required' })
-    }
-
     // Parse package name and version from URL segments
     // Patterns: [pkg, 'v', version] or [@scope, pkg, 'v', version]
-    const vIndex = segments.indexOf('v')
-    if (vIndex === -1 || vIndex >= segments.length - 1) {
-      throw createError({ statusCode: 400, message: 'Version is required (use /v/{version})' })
-    }
+    const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
 
-    const packageName = segments.slice(0, vIndex).join('/')
-    const version = segments.slice(vIndex + 1).join('/')
-
-    if (!packageName || !version) {
-      throw createError({ statusCode: 400, message: 'Package name and version are required' })
-    }
-    assertValidPackageName(packageName)
+    const { rawPackageName, rawVersion } = parsePackageParams(pkgParamSegments)
 
     try {
+      const { packageName, version } = v.parse(PackageVersionQuerySchema, {
+        packageName: rawPackageName,
+        version: rawVersion,
+      })
+
       const jsDelivrData = await fetchFileTree(packageName, version)
       const tree = convertToFileTree(jsDelivrData.files)
 
@@ -39,19 +33,20 @@ export default defineCachedEventHandler(
         default: jsDelivrData.default ?? undefined,
         tree,
       } satisfies PackageFileTreeResponse
-    } catch (error) {
-      if (error && typeof error === 'object' && 'statusCode' in error) {
-        throw error
-      }
-      throw createError({ statusCode: 502, message: 'Failed to fetch file list' })
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: ERROR_FILE_LIST_FETCH_FAILED,
+      })
     }
   },
   {
     // Files for a specific version never change - cache permanently
-    maxAge: 60 * 60 * 24 * 365, // 1 year
+    maxAge: CACHE_MAX_AGE_ONE_YEAR, // 1 year
+    swr: true,
     getKey: event => {
       const pkg = getRouterParam(event, 'pkg') ?? ''
-      return `files:${pkg}`
+      return `files:v1:${pkg.replace(/\/+$/, '').trim()}`
     },
   },
 )