@stacksjs/bun-router 0.0.14 → 0.0.15

package/src/cli/index.ts

@@ -0,0 +1,287 @@
+import type { GenerateMiddlewareTypesOptions, MapMiddlewareOptions } from './middleware'
+import type { OpenAPIOptions } from './openapi'
+import type { GenerateRouterTypesOptions } from './router'
+import type { GenerateRouteTypesOptions, RouteListOptions } from './routes'
+import process from 'node:process'
+import { CLI } from '@stacksjs/clapp'
+import { version } from '../../package.json'
+import { generateMiddlewareMap, generateMiddlewareTypes, watchDirectoryForMiddleware, watchMiddlewareDirectory } from './middleware'
+import { generateOpenAPISpec } from './openapi'
+import { generateRouterTypes, watchRouterFiles } from './router'
+import { displayRoutes, generateRouteTypes, watchRoutesDirectory } from './routes'
+import { checkRouterHealth, clearCaches, debugRoute, testRoutes, validateRoutes } from './utils'
+
+/**
+ * Create and configure the CLI
+ */
+export function createCLI(): CLI {
+  const cli = new CLI('router')
+
+  // Set version info
+  cli.version(version)
+
+  // Register commands
+  registerRouteCommands(cli)
+  registerMiddlewareCommands(cli)
+  registerRouterCommands(cli)
+  registerOpenAPICommands(cli)
+  registerUtilityCommands(cli)
+
+  // Add help command
+  cli.help()
+
+  return cli
+}
+
+/**
+ * Register route-related commands
+ */
+function registerRouteCommands(cli: CLI): void {
+  cli
+    .command('route:list', 'List all registered routes')
+    .option('-v, --verbose', 'Show detailed information including middleware')
+    .option('-vv, --extra-verbose', 'Show very detailed information')
+    .option('--path <path>', 'Filter routes by path prefix')
+    .option('--except-vendor', 'Exclude vendor routes')
+    .option('--only-vendor', 'Show only vendor routes')
+    .example('router route:list')
+    .example('router route:list -v')
+    .example('router route:list --path=/api')
+    .action(async (options: RouteListOptions) => {
+      try {
+        await displayRoutes(options)
+      }
+      catch (error: any) {
+        console.error(`Failed to list routes: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  cli
+    .command('route:types', 'Generate TypeScript types for route names')
+    .option('--output <file>', 'Output file path', { default: 'route-types.ts' })
+    .option('--watch', 'Watch for changes in routes directory')
+    .example('router route:types')
+    .example('router route:types --output src/types/routes.ts')
+    .example('router route:types --watch')
+    .action(async (options: GenerateRouteTypesOptions) => {
+      try {
+        const outputPath = options.output || 'route-types.ts'
+        if (options.watch) {
+          await watchRoutesDirectory(outputPath)
+        }
+        else {
+          await generateRouteTypes(outputPath)
+        }
+      }
+      catch (error: any) {
+        console.error(`Failed to generate route types: ${error.message}`)
+        process.exit(1)
+      }
+    })
+}
+
+/**
+ * Register middleware-related commands
+ */
+function registerMiddlewareCommands(cli: CLI): void {
+  cli
+    .command('middleware:types', 'Generate TypeScript types for middleware configurations')
+    .option('--output <file>', 'Output file path', { default: 'middleware-types.ts' })
+    .option('--watch', 'Watch for changes in middleware directory')
+    .example('router middleware:types')
+    .example('router middleware:types --output src/types/middleware.ts')
+    .example('router middleware:types --watch')
+    .action(async (options: GenerateMiddlewareTypesOptions) => {
+      try {
+        const outputPath = options.output || 'middleware-types.ts'
+        if (options.watch) {
+          await watchMiddlewareDirectory(outputPath)
+        }
+        else {
+          await generateMiddlewareTypes(outputPath)
+        }
+      }
+      catch (error: any) {
+        console.error(`Failed to generate middleware types: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  cli
+    .command('middleware:map', 'Generate TypeScript types for all middleware in the project')
+    .option('--dir <directory>', 'Directory to scan for middleware classes', { default: 'src' })
+    .option('--output <file>', 'Output file path', { default: 'middleware-map.ts' })
+    .option('--watch', 'Watch for changes in the specified directory')
+    .example('router middleware:map')
+    .example('router middleware:map --dir app')
+    .example('router middleware:map --output src/types/project-middleware.ts')
+    .example('router middleware:map --watch')
+    .action(async (options: MapMiddlewareOptions) => {
+      try {
+        const outputPath = options.output || 'middleware-map.ts'
+        const directoryPath = options.dir || 'src'
+
+        if (options.watch) {
+          await watchDirectoryForMiddleware(directoryPath, outputPath)
+        }
+        else {
+          await generateMiddlewareMap(directoryPath, outputPath)
+        }
+      }
+      catch (error: any) {
+        console.error(`Failed to generate middleware map: ${error.message}`)
+        process.exit(1)
+      }
+    })
+}
+
+/**
+ * Register router extension-related commands
+ */
+function registerRouterCommands(cli: CLI): void {
+  cli
+    .command('router:types', 'Generate TypeScript types for router extensions')
+    .option('--output <file>', 'Output file path', { default: 'router-types.ts' })
+    .option('--watch', 'Watch for changes in router files')
+    .example('router router:types')
+    .example('router router:types --output src/types/router.ts')
+    .example('router router:types --watch')
+    .action(async (options: GenerateRouterTypesOptions) => {
+      try {
+        const outputPath = options.output || 'router-types.ts'
+        if (options.watch) {
+          await watchRouterFiles(outputPath)
+        }
+        else {
+          await generateRouterTypes(outputPath)
+        }
+      }
+      catch (error: any) {
+        console.error(`Failed to generate router types: ${error.message}`)
+        process.exit(1)
+      }
+    })
+}
+
+/**
+ * Register OpenAPI-related commands
+ */
+function registerOpenAPICommands(cli: CLI): void {
+  cli
+    .command('openapi', 'Generate OpenAPI specification for API routes')
+    .option('--output <file>', 'Output file path', { default: 'openapi.json' })
+    .option('--title <title>', 'API title', { default: 'API Documentation' })
+    .option('--version <version>', 'API version', { default: '1.0.0' })
+    .option('--description <description>', 'API description')
+    .option('--base-path <path>', 'Base API path', { default: '/' })
+    .option('--servers <urls>', 'Comma-separated list of server URLs')
+    .option('--tags', 'Group endpoints by tags', { default: true })
+    .option('--security', 'Include security schemes if available', { default: true })
+    .example('router openapi')
+    .example('router openapi --output api-spec.json')
+    .example('router openapi --title "My API" --version 2.0')
+    .example('router openapi --servers http://localhost:3000,https://api.example.com')
+    .action(async (options: OpenAPIOptions) => {
+      try {
+        await generateOpenAPISpec(options)
+      }
+      catch (error: any) {
+        console.error(`Failed to generate OpenAPI specification: ${error.message}`)
+        process.exit(1)
+      }
+    })
+}
+
+/**
+ * Register utility commands for debugging and development
+ */
+function registerUtilityCommands(cli: CLI): void {
+  cli
+    .command('health', 'Check router health and configuration')
+    .option('--verbose', 'Show detailed health information')
+    .example('router health')
+    .example('router health --verbose')
+    .action(async (options: { verbose?: boolean }) => {
+      try {
+        await checkRouterHealth(options)
+      }
+      catch (error: any) {
+        console.error(`Health check failed: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  cli
+    .command('test:routes', 'Test routes by making HTTP requests')
+    .option('--base-url <url>', 'Base URL for testing', { default: 'http://localhost:3000' })
+    .option('--filter <pattern>', 'Filter routes by path pattern')
+    .option('--method <methods>', 'Test only specific HTTP methods (comma-separated)')
+    .option('--timeout <ms>', 'Request timeout in milliseconds', { default: 5000 })
+    .example('router test:routes')
+    .example('router test:routes --base-url http://localhost:8080')
+    .example('router test:routes --filter "/api/*"')
+    .example('router test:routes --method GET,POST')
+    .action(async (options: { baseUrl?: string, filter?: string, method?: string, timeout?: number }) => {
+      try {
+        await testRoutes(options)
+      }
+      catch (error: any) {
+        console.error(`Route testing failed: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  cli
+    .command('debug:route <path>', 'Debug route matching for a specific path')
+    .option('--method <method>', 'HTTP method to test', { default: 'GET' })
+    .option('--verbose', 'Show detailed matching information')
+    .example('router debug:route /api/users/123')
+    .example('router debug:route /api/users/123 --method POST --verbose')
+    .action(async (path: string, options: { method?: string, verbose?: boolean }) => {
+      try {
+        await debugRoute(path, options)
+      }
+      catch (error: any) {
+        console.error(`Route debugging failed: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  cli
+    .command('cache:clear', 'Clear route caches')
+    .option('--stats', 'Show cache statistics before clearing')
+    .example('router cache:clear')
+    .example('router cache:clear --stats')
+    .action(async (options: { stats?: boolean }) => {
+      try {
+        await clearCaches(options)
+      }
+      catch (error: any) {
+        console.error(`Cache clearing failed: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  cli
+    .command('validate', 'Validate route definitions and configuration')
+    .option('--strict', 'Use strict validation rules')
+    .option('--fix', 'Automatically fix simple issues')
+    .example('router validate')
+    .example('router validate --strict --fix')
+    .action(async (options: { strict?: boolean, fix?: boolean }) => {
+      try {
+        await validateRoutes(options)
+      }
+      catch (error: any) {
+        console.error(`Route validation failed: ${error.message}`)
+        process.exit(1)
+      }
+    })
+}
+
+export * from './middleware'
+export * from './openapi'
+export * from './router'
+export * from './routes'
+export * from './utils'

package/src/cli/middleware.ts

@@ -0,0 +1,291 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { middleware } from '../../src/middleware'
+import { chalk } from './colors'
+
+/**
+ * Options for the middleware:types command
+ */
+export interface GenerateMiddlewareTypesOptions {
+  output?: string
+  watch?: boolean
+}
+
+/**
+ * Options for the middleware:map command
+ */
+export interface MapMiddlewareOptions {
+  output?: string
+  dir?: string
+  watch?: boolean
+}
+
+/**
+ * Generate TypeScript types for middleware configurations
+ */
+export async function generateMiddlewareTypes(outputPath: string): Promise<void> {
+  // Get middleware information
+  const middlewareInfo = Object.entries(middleware).map(([key, instance]) => ({
+    name: key,
+    className: instance.constructor.name,
+  }))
+
+  // Generate type definition
+  const typeContent = `/**
+ * This file is auto-generated.
+ * DO NOT EDIT THIS FILE DIRECTLY.
+ * To update, run 'bun router middleware:types'
+ */
+import type { ${middlewareInfo.map(m => m.className).join(', ')} } from './middleware'
+
+/**
+ * Available middleware map with middleware names as keys
+ */
+export interface MiddlewareMap {
+${middlewareInfo.map(m => `  '${m.name}': ${m.className}`).join('\n')}
+}
+
+/**
+ * String literal type of available middleware names
+ */
+export type MiddlewareName = ${middlewareInfo.map(m => `'${m.name}'`).join(' | ')}
+
+/**
+ * Middleware configuration type for router setup
+ */
+export type MiddlewareConfig = MiddlewareName | ${middlewareInfo.map(m => m.className).join(' | ')}
+
+/**
+ * Function to check if a middleware name is valid
+ */
+export function isValidMiddleware(name: string): name is MiddlewareName {
+  return [${middlewareInfo.map(m => `'${m.name}'`).join(', ')}].includes(name)
+}
+`
+
+  // Write to file
+  await fs.writeFile(outputPath, typeContent)
+}
+
+/**
+ * Find TypeScript files in a directory recursively
+ */
+async function findTsFiles(dir: string): Promise<string[]> {
+  const files: string[] = []
+  const entries = await fs.readdir(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...await findTsFiles(fullPath))
+    }
+    else if (entry.isFile() && entry.name.endsWith('.ts')) {
+      files.push(fullPath)
+    }
+  }
+
+  return files
+}
+
+/**
+ * Scan a file for middleware classes
+ */
+async function scanFileForMiddleware(filePath: string): Promise<{ name: string, path: string }[]> {
+  const middlewareClasses: { name: string, path: string }[] = []
+
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+
+    // Look for class declarations that implement Middleware or have "Middleware" in their name
+    const classRegex = /export\s+(?:default\s+)?class\s+(\w+)\s+(?:implements\s+Middleware|\{[\s\S]*?handle\s*\([\s\S]*?\))/g
+    let match: RegExpExecArray | null = null
+
+    // eslint-disable-next-line no-cond-assign
+    while (match = classRegex.exec(content)) {
+      const className = match[1]
+
+      // If the class name indicates it's middleware or it implements Middleware interface
+      if (className.includes('Middleware') || match[0].includes('implements Middleware')) {
+        const relativePath = path.relative(process.cwd(), filePath)
+        // Remove extension for import path
+        const importPath = relativePath.replace(/\.ts$/, '')
+        middlewareClasses.push({
+          name: className,
+          path: importPath,
+        })
+      }
+    }
+  }
+  catch (error) {
+    console.warn(chalk.yellow(`Error scanning file ${filePath}: ${error}`))
+  }
+
+  return middlewareClasses
+}
+
+/**
+ * Generate middleware type mappings for user project
+ */
+export async function generateMiddlewareMap(
+  directoryPath: string,
+  outputPath: string,
+): Promise<void> {
+  console.log(chalk.blue(`Scanning directory: ${directoryPath} for middleware classes...`))
+
+  try {
+    // Find all TypeScript files in the directory
+    const tsFiles = await findTsFiles(directoryPath)
+    const allMiddleware: { name: string, path: string }[] = []
+
+    // Scan each file for middleware
+    for (const file of tsFiles) {
+      const middlewareInFile = await scanFileForMiddleware(file)
+      allMiddleware.push(...middlewareInFile)
+    }
+
+    if (allMiddleware.length === 0) {
+      console.warn(chalk.yellow('No middleware classes found in the specified directory.'))
+      return
+    }
+
+    // Generate the type definition
+    const imports = allMiddleware.map(m => `import { ${m.name} } from '${m.path}'`).join('\n')
+    const interfaceMembers = allMiddleware.map(m => `  ${m.name}: typeof ${m.name}`).join('\n')
+    const typeNames = allMiddleware.map(m => m.name).join(' | ')
+
+    const typeContent = `/**
+ * This file is auto-generated.
+ * DO NOT EDIT THIS FILE DIRECTLY.
+ * To update, run 'bun router middleware:map'
+ */
+
+${imports}
+
+/**
+ * Map of all available middleware in the project
+ */
+export interface MiddlewareMap {
+${interfaceMembers}
+}
+
+/**
+ * Type representing all available middleware classes in the project
+ */
+export type MiddlewareType = ${typeNames}
+
+/**
+ * Type for a middleware handler function
+ */
+export type MiddlewareHandler = (req: any, next: () => Promise<Response>) => Promise<Response>
+
+/**
+ * Ensure the middleware module exports all the middleware classes used in the project
+ */
+export const middlewareMap: MiddlewareMap = {
+${allMiddleware.map(m => `  ${m.name}: ${m.name}`).join(',\n')}
+}
+`
+
+    // Write to file
+    await fs.writeFile(outputPath, typeContent)
+    console.log(chalk.green(`✨ Middleware map generated at ${outputPath} with ${allMiddleware.length} middleware classes`))
+
+    // List found middleware
+    console.log(chalk.blue('Found middleware classes:'))
+    for (const m of allMiddleware) {
+      console.log(chalk.cyan(`  - ${m.name} (${m.path})`))
+    }
+  }
+  catch (error) {
+    console.error(chalk.red(`Error generating middleware map: ${error}`))
+    throw error
+  }
+}
+
+/**
+ * Watch for changes in the directory and regenerate middleware map
+ */
+export async function watchDirectoryForMiddleware(
+  directoryPath: string,
+  outputPath: string,
+): Promise<void> {
+  // Check if directory exists
+  try {
+    await fs.access(directoryPath)
+  }
+  catch {
+    console.error(chalk.red(`Directory not found at ${directoryPath}`))
+    process.exit(1)
+  }
+
+  // Initial generation
+  await generateMiddlewareMap(directoryPath, outputPath)
+  console.log(chalk.blue(`Watching for changes in ${directoryPath}...`))
+
+  // Setup file watcher
+  let timeoutId: ReturnType<typeof setTimeout> | null = null
+  const watcher = fs.watch(directoryPath, { recursive: true })
+
+  for await (const _event of watcher) {
+    // Debounce to avoid multiple regenerations when multiple files change
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
+
+    timeoutId = setTimeout(async () => {
+      console.log(chalk.yellow(`Changes detected. Regenerating middleware map...`))
+      try {
+        await generateMiddlewareMap(directoryPath, outputPath)
+      }
+      catch (error: any) {
+        console.error(chalk.red(`Error regenerating middleware map: ${error.message}`))
+      }
+      timeoutId = null
+    }, 500)
+  }
+}
+
+/**
+ * Watch for changes in the middleware directory and regenerate types
+ */
+export async function watchMiddlewareDirectory(outputPath: string): Promise<void> {
+  const middlewarePath = path.join(process.cwd(), 'src', 'middleware')
+
+  // Check if middleware directory exists
+  try {
+    await fs.access(middlewarePath)
+  }
+  catch {
+    console.error(chalk.red(`Middleware directory not found at ${middlewarePath}`))
+    process.exit(1)
+  }
+
+  // Initial generation
+  await generateMiddlewareTypes(outputPath)
+  console.log(chalk.green(`✨ Middleware types generated at ${outputPath}`))
+  console.log(chalk.blue(`Watching for changes in ${middlewarePath}...`))
+
+  // Setup file watcher
+  let timeoutId: ReturnType<typeof setTimeout> | null = null
+  const watcher = fs.watch(middlewarePath, { recursive: true })
+
+  for await (const _event of watcher) {
+    // Debounce to avoid multiple regenerations when multiple files change
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
+
+    timeoutId = setTimeout(async () => {
+      console.log(chalk.yellow(`Changes detected in middleware directory. Regenerating types...`))
+      try {
+        await generateMiddlewareTypes(outputPath)
+        console.log(chalk.green(`✨ Middleware types regenerated at ${outputPath}`))
+      }
+      catch (error: any) {
+        console.error(chalk.red(`Error regenerating types: ${error.message}`))
+      }
+      timeoutId = null
+    }, 500)
+  }
+}