@strav/http 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/http",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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
@@ -433,6 +433,62 @@ export default class Router {
     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 ------------------------------------------------------------
 
   /**

package/src/index.ts

@@ -5,3 +5,6 @@ export * from './validation/index.ts'
 export * from './policy/index.ts'
 export * from './auth/index.ts'
 export * from './providers/index.ts'
+
+// Route helpers for named route invocation
+export { route, routeUrl } from './http/route_helper.ts'