@stacksjs/stx/dist/route-middleware.d.ts

A performant UI Framework. Powered by Bun.

import path from 'node:path';
import type { PageMeta } from './head';
/**
 * Redirect to a different route
 *
 * @param path - Path to redirect to
 * @param options - Redirect options
 * @returns Navigation result for the middleware system
 *
 * @example
 * ```typescript
 * export default defineMiddleware(async (ctx) => {
 *   if (!ctx.cookies.get('token')) {
 *     return navigateTo('/login')
 *   }
 * })
 * ```
 */
export declare function navigateTo(path: string, options?: NavigateToOptions): NavigateToResult;
/**
 * Abort navigation with an error
 *
 * @param error - Error message or error object
 * @returns Navigation result for the middleware system
 *
 * @example
 * ```typescript
 * export default defineMiddleware(async (ctx) => {
 *   if (!hasPermission(ctx)) {
 *     return abortNavigation({ statusCode: 403, message: 'Forbidden' })
 *   }
 * })
 * ```
 */
export declare function abortNavigation(error: string | NavigationError): AbortNavigationResult;
/**
 * Define a route middleware
 *
 * @param handler - Middleware handler function
 * @param options - Middleware options
 * @returns Middleware definition
 *
 * @example
 * ```typescript
 * // middleware/auth.ts - runs on both server and client
 * export default defineMiddleware(async (ctx) => {
 *   const token = ctx.cookies.get('auth_token')
 *   if (!token) {
 *     return navigateTo('/login')
 *   }
 * })
 *
 * // middleware/theme.ts - client only (can use localStorage)
 * export default defineMiddleware(async (ctx) => {
 *   const theme = ctx.storage.get('theme')
 *   ctx.state.theme = theme || 'light'
 * }, { mode: 'client' })
 * ```
 */
export declare function defineMiddleware(handler: RouteMiddlewareHandler, options?: MiddlewareOptions): RouteMiddlewareDefinition;
/**
 * Create a cookie manager for server-side usage
 */
export declare function createServerCookieManager(request: Request, responseHeaders: Headers): CookieManager;
/**
 * Create a cookie manager for client-side usage
 */
export declare function createClientCookieManager(): CookieManager;
/**
 * Create a storage manager (localStorage wrapper)
 */
export declare function createStorageManager(): StorageManager;
/**
 * Register a middleware by name
 */
export declare function registerMiddleware(name: string, middleware: RouteMiddlewareDefinition): void;
/**
 * Get a middleware by name
 */
export declare function getMiddleware(name: string): RouteMiddlewareDefinition | undefined;
/**
 * Check if a middleware is registered
 */
export declare function hasMiddleware(name: string): boolean;
/**
 * Clear all registered middleware
 */
export declare function clearMiddleware(): void;
/**
 * Get all registered middleware names
 */
export declare function getMiddlewareNames(): string[];
/**
 * Load middleware from the middleware/ directory
 */
export declare function loadMiddlewareFromDirectory(baseDir: string, middlewareDir?: string): Promise<void>;
/**
 * Create a route location object
 */
export declare function createRouteLocation(pathname: string, params: Record<string, string>, meta: PageMeta, search?: string): RouteLocation;
/**
 * Create a middleware context
 */
export declare function createMiddlewareContext(to: RouteLocation, from: RouteLocation | null, request?: Request): MiddlewareContext;
/**
 * Run middleware chain for a route
 *
 * @param middlewareNames - Names of middleware to run
 * @param context - Middleware context
 * @returns Result of middleware execution
 */
export declare function runMiddleware(middlewareNames: string | string[], context: MiddlewareContext): Promise<MiddlewareResult>;
/**
 * Route location information
 */
export declare interface RouteLocation {
  path: string
  params: Record<string, string>
  query: Record<string, string>
  fullPath: string
  meta: PageMeta
}
/**
 * Cookie manager for reading/writing cookies
 */
export declare interface CookieManager {
  get(name: string): string | undefined
  set(name: string, value: string, options?: CookieOptions): void
  delete(name: string): void
  getAll(): Record<string, string>
}
/**
 * Cookie options for setting cookies
 */
export declare interface CookieOptions {
  expires?: Date | number
  path?: string
  domain?: string
  secure?: boolean
  httpOnly?: boolean
  sameSite?: 'strict' | 'lax' | 'none'
}
/**
 * Safe localStorage wrapper (returns null on server)
 */
export declare interface StorageManager {
  get(key: string): string | null
  set(key: string, value: string): void
  remove(key: string): void
  isAvailable(): boolean
}
/**
 * Middleware context passed to handlers
 */
export declare interface MiddlewareContext {
  to: RouteLocation
  from: RouteLocation | null
  isClient: boolean
  isServer: boolean
  cookies: CookieManager
  storage: StorageManager
  state: Record<string, unknown>
  request?: Request
  responseHeaders: Headers
}
/**
 * Middleware definition options
 */
export declare interface MiddlewareOptions {
  mode?: MiddlewareMode
}
/**
 * Registered middleware definition
 */
export declare interface RouteMiddlewareDefinition {
  handler: RouteMiddlewareHandler
  mode: MiddlewareMode
}
/**
 * Navigation redirect result
 */
export declare interface NavigateToResult {
  type: 'redirect'
  path: string
  options: NavigateToOptions
}
/**
 * Navigation abort result
 */
export declare interface AbortNavigationResult {
  type: 'abort'
  error: NavigationError
}
/**
 * Options for navigateTo()
 */
export declare interface NavigateToOptions {
  replace?: boolean
  external?: boolean
  redirectCode?: 301 | 302 | 303 | 307 | 308
}
/**
 * Navigation error for abortNavigation()
 */
export declare interface NavigationError {
  statusCode: number
  message: string
}
/**
 * Result of running middleware chain
 */
export declare interface MiddlewareResult {
  passed: boolean
  redirect?: NavigateToResult
  abort?: AbortNavigationResult
  state: Record<string, unknown>
  responseHeaders: Headers
}
/**
 * Middleware execution mode
 */
export type MiddlewareMode = 'universal' | 'server' | 'client'
/**
 * Middleware handler function
 */
export type RouteMiddlewareHandler = (
  context: MiddlewareContext
) => void | Promise<void> | NavigationResult | Promise<NavigationResult | void>
/**
 * Result from middleware (redirect or abort)
 */
export type NavigationResult = NavigateToResult | AbortNavigationResult