@strav/http 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/http",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "HTTP layer for the Strav framework — router, server, middleware, authentication, sessions, validation, and views",
   "license": "MIT",

package/src/http/index.ts

@@ -8,11 +8,13 @@ export { compose } from './middleware.ts'
 export { serializeCookie, parseCookies, withCookie, clearCookie } from './cookie.ts'
 export { rateLimit, MemoryStore } from './rate_limit.ts'
 export { Resource } from './resource.ts'
+export { route, routeUrl } from './route_helper.ts'
 export type { Handler, Middleware, Next } from './middleware.ts'
-export type { GroupOptions, WebSocketHandlers, WebSocketData } from './router.ts'
+export type { GroupOptions, WebSocketHandlers, WebSocketData, RouteDefinition } from './router.ts'
 export type { CookieOptions } from './cookie.ts'
 export type { CorsOptions } from './cors.ts'
 export type { RateLimitOptions, RateLimitStore, RateLimitInfo } from './rate_limit.ts'
+export type { RouteOptions } from './route_helper.ts'
 
 if (!app.has(Router)) app.singleton(Router)
 export const router = app.resolve(Router)

package/src/http/route_helper.ts

@@ -0,0 +1,134 @@
+import { router } from './index.ts'
+import type { RouteDefinition } from './router.ts'
+
+export interface RouteOptions extends Omit<RequestInit, 'body'> {
+  params?: Record<string, any>
+  body?: any
+}
+
+/**
+ * Invoke a named route with automatic method detection and smart defaults.
+ *
+ * @example
+ * // Simple POST with JSON body
+ * await route('auth.register', {
+ *   name: 'John',
+ *   email: 'john@example.com',
+ *   password: 'secret'
+ * })
+ *
+ * // GET with URL parameters
+ * await route('users.show', { params: { id: 123 } })
+ *
+ * // Custom headers and options
+ * await route('api.upload', {
+ *   body: formData,
+ *   headers: { 'X-Custom-Header': 'value' }
+ * })
+ *
+ * // Override detected method
+ * await route('users.index', { method: 'HEAD' })
+ */
+export async function route(
+  name: string,
+  data?: any,
+  options?: RouteOptions
+): Promise<Response> {
+  const routeDef = router.getRouteByName(name)
+  if (!routeDef) {
+    throw new Error(`Route '${name}' not found`)
+  }
+
+  // Determine if data is the body or options
+  let body: any
+  let opts: RouteOptions = {}
+
+  if (data !== undefined) {
+    // If data has params, body, or any RequestInit properties, treat it as options
+    if (
+      typeof data === 'object' &&
+      !Array.isArray(data) &&
+      !(data instanceof FormData) &&
+      !(data instanceof Blob) &&
+      !(data instanceof ArrayBuffer) &&
+      !(data instanceof URLSearchParams) &&
+      ('params' in data || 'body' in data || 'headers' in data || 'cache' in data ||
+       'credentials' in data || 'mode' in data || 'redirect' in data || 'referrer' in data)
+    ) {
+      opts = data
+      body = opts.body
+    } else {
+      // Otherwise, treat data as the body
+      body = data
+      opts = options || {}
+    }
+  } else {
+    opts = options || {}
+  }
+
+  // Generate URL with parameters
+  const generatedUrl = router.generateUrl(name, opts.params)
+
+  // Determine method from route definition
+  const method = opts.method || routeDef.method
+
+  // Build headers with smart defaults
+  const headers = new Headers(opts.headers)
+
+  // Set default Accept header if not provided
+  if (!headers.has('Accept')) {
+    headers.set('Accept', 'application/json')
+  }
+
+  // Handle body and Content-Type
+  let requestBody: string | FormData | Blob | ArrayBuffer | URLSearchParams | undefined
+  if (body !== undefined && method !== 'GET' && method !== 'HEAD') {
+    if (body instanceof FormData || body instanceof Blob || body instanceof ArrayBuffer || body instanceof URLSearchParams) {
+      // Let fetch set the Content-Type for FormData, or use the existing type for Blob/ArrayBuffer
+      requestBody = body
+    } else if (typeof body === 'object') {
+      // JSON body
+      if (!headers.has('Content-Type')) {
+        headers.set('Content-Type', 'application/json')
+      }
+      requestBody = JSON.stringify(body)
+    } else {
+      // String or other primitive
+      requestBody = String(body)
+      if (!headers.has('Content-Type')) {
+        headers.set('Content-Type', 'text/plain')
+      }
+    }
+  }
+
+  // Set default credentials if not provided
+  const credentials = opts.credentials || 'same-origin'
+
+  // Build final fetch options
+  const fetchOptions: RequestInit = {
+    ...opts,
+    method,
+    headers,
+    credentials,
+    ...(requestBody !== undefined && { body: requestBody })
+  }
+
+  // Remove our custom properties
+  delete (fetchOptions as any).params
+
+  return fetch(generatedUrl, fetchOptions)
+}
+
+/**
+ * Generate a URL for a named route with optional parameters.
+ *
+ * @example
+ * const profileUrl = routeUrl('users.profile', { id: 456 })
+ * // Returns '/users/456'
+ *
+ * const searchUrl = routeUrl('api.search', { q: 'test', page: 2 })
+ * // Returns '/api/search?q=test&page=2'
+ */
+export function routeUrl(name: string, params?: Record<string, any>): string {
+  return router.generateUrl(name, params)
+}

package/src/http/router.ts

@@ -19,7 +19,7 @@ export type ControllerAction = [Constructor, string]
 /** Accepted as a route handler: a function or a `[Controller, 'method']` tuple. */
 export type HandlerInput = Handler | ControllerAction
 
-interface RouteDefinition {
+export interface RouteDefinition {
   method: string
   pattern: string
   regex: RegExp
@@ -64,6 +64,8 @@ interface GroupState {
   middleware: Middleware[]
   subdomain?: string
   subdomainParamName?: string
+  alias?: string
+  ref?: GroupRef  // Reference to the GroupRef for deferred alias assignment
 }
 
 // ---------------------------------------------------------------------------
@@ -102,13 +104,69 @@ function parseSubdomain(pattern: string): { value: string; paramName?: string }
 // ---------------------------------------------------------------------------
 
 class RouteRef {
-  constructor(private route: RouteDefinition) {}
+  private groupRefs: (GroupRef | undefined)[]
+  private routeName?: string
+
+  constructor(private route: RouteDefinition, private router: Router) {
+    // Capture references to the GroupRefs from the current stack
+    this.groupRefs = router.groupStack.map(state => state.ref)
+  }
 
   /** Assign a name to this route (for future URL generation). */
   as(name: string): this {
-    this.route.name = name
+    this.routeName = name
+
+    // Define a getter that builds the full name lazily
+    Object.defineProperty(this.route, 'name', {
+      get: () => {
+        const aliases = this.groupRefs
+          .map(ref => ref?.getAlias())
+          .filter(alias => alias)
+
+        const groupAlias = aliases.join('.')
+        return groupAlias ? `${groupAlias}.${this.routeName}` : this.routeName
+      },
+      configurable: true
+    })
+
+    return this
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GroupRef — returned by group methods for chaining (.as)
+// ---------------------------------------------------------------------------
+
+class GroupRef {
+  private alias?: string
+
+  constructor(
+    private router: Router,
+    private groupState: GroupState,
+    private callback: (router: Router) => void
+  ) {
+    // Store reference to this GroupRef in the state
+    this.groupState.ref = this
+  }
+
+  /** Assign an alias to this group (for hierarchical route naming). */
+  as(alias: string): this {
+    this.alias = alias
+    this.groupState.alias = alias
     return this
   }
+
+  /** @internal Get the alias assigned to this group */
+  getAlias(): string | undefined {
+    return this.alias
+  }
+
+  /** @internal Execute the group callback with the current state */
+  execute(): void {
+    this.router.groupStack.push(this.groupState)
+    this.callback(this.router)
+    this.router.groupStack.pop()
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -321,8 +379,13 @@ export default class Router {
    * router.group({ prefix: '/api', middleware: [auth] }, (r) => {
    *   r.get('/users', listUsers)
    * })
+   *
+   * @example With group aliasing:
+   * router.group({ prefix: '/api' }, (r) => {
+   *   r.get('/users', listUsers).as('index')
+   * }).as('api')
    */
-  group(options: GroupOptions, callback: (router: Router) => void): void {
+  group(options: GroupOptions, callback: (router: Router) => void): GroupRef {
     const parent = this.currentGroup()
     const prefix = (parent?.prefix ?? '') + (options.prefix ?? '')
     const middleware = [...(parent?.middleware ?? []), ...(options.middleware ?? [])]
@@ -336,9 +399,21 @@ export default class Router {
       subdomainParamName = parsed.paramName
     }
 
-    this.groupStack.push({ prefix, middleware, subdomain, subdomainParamName })
-    callback(this)
-    this.groupStack.pop()
+    const groupState: GroupState = {
+      prefix,
+      middleware,
+      subdomain,
+      subdomainParamName,
+      alias: undefined
+    }
+
+    const ref = new GroupRef(this, groupState, callback)
+
+    // Execute immediately for backward compatibility
+    // The group can still be chained with .as() but routes are registered immediately
+    ref.execute()
+
+    return ref
   }
 
   /**
@@ -354,8 +429,64 @@ export default class Router {
    *                                 // ctx.params.tenant === 'acme'
    * })
    */
-  subdomain(pattern: string, callback: (router: Router) => void): void {
-    this.group({ subdomain: pattern }, callback)
+  subdomain(pattern: string, callback: (router: Router) => void): GroupRef {
+    return this.group({ subdomain: pattern }, callback)
+  }
+
+  // ---- Route lookup and URL generation ------------------------------------
+
+  /**
+   * Get a route definition by its name.
+   *
+   * @example
+   * const route = router.getRouteByName('users.show')
+   * // Returns route with pattern '/users/:id', method 'GET', etc.
+   */
+  getRouteByName(name: string): RouteDefinition | undefined {
+    return this.routes.find(route => route.name === name)
+  }
+
+  /**
+   * Generate a URL for a named route with optional parameters.
+   *
+   * @example
+   * router.generateUrl('users.show', { id: 123 })
+   * // Returns '/users/123'
+   *
+   * router.generateUrl('api.search', { q: 'test', page: 2 })
+   * // Returns '/api/search?q=test&page=2'
+   */
+  generateUrl(name: string, params?: Record<string, any>): string {
+    const route = this.getRouteByName(name)
+    if (!route) {
+      throw new Error(`Route '${name}' not found`)
+    }
+
+    let url = route.pattern
+    const usedParams = new Set<string>()
+
+    // Replace route parameters
+    for (const paramName of route.paramNames) {
+      if (params?.[paramName] !== undefined) {
+        url = url.replace(`:${paramName}`, String(params[paramName]))
+        usedParams.add(paramName)
+      } else {
+        throw new Error(`Missing required parameter '${paramName}' for route '${name}'`)
+      }
+    }
+
+    // Add remaining params as query string
+    if (params) {
+      const queryParams = Object.entries(params)
+        .filter(([key]) => !usedParams.has(key))
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+
+      if (queryParams.length > 0) {
+        url += '?' + queryParams.join('&')
+      }
+    }
+
+    return url
   }
 
   // ---- Dispatch ------------------------------------------------------------
@@ -496,6 +627,14 @@ export default class Router {
     return this.currentGroup()?.prefix ?? ''
   }
 
+  /** @internal Get the concatenated alias chain from all parent groups */
+  getCurrentGroupAlias(): string {
+    const aliases = this.groupStack
+      .filter(group => group.alias)
+      .map(group => group.alias)
+    return aliases.join('.')
+  }
+
   /** Resolve a `[Controller, 'method']` tuple into a Handler. */
   private toHandler(input: HandlerInput): Handler {
     if (Array.isArray(input)) {
@@ -523,7 +662,7 @@ export default class Router {
     }
 
     this.routes.push(route)
-    return new RouteRef(route)
+    return new RouteRef(route, this)
   }
 
   private extractSubdomain(request: Request): string {