Core Framework

/**
 * Main H3 application class for creating HTTP servers
 */
class H3 {
  /**
   * Create a new H3 application instance
   * @param config - Optional configuration for the application
   */
  constructor(config?: H3Config);
  
  /**
   * Fetch-compatible request handler
   * @param request - The incoming server request
   * @returns Response or Promise resolving to Response
   */
  fetch(request: ServerRequest): Response | Promise<Response>;
  
  /**
   * Request handler for various input types
   * @param request - Request object, URL, or string
   * @param options - Optional request initialization options
   * @param context - Optional H3 event context
   * @returns Response or Promise resolving to Response
   */
  request(request: ServerRequest | URL | string, options?: RequestInit, context?: H3EventContext): Response | Promise<Response>;
  
  /**
   * Register an H3 plugin
   * @param plugin - Plugin function to register
   * @returns The H3 instance for chaining
   */
  register(plugin: H3Plugin): this;
  
  /**
   * Mount a sub-application or handler at a base path
   * @param base - Base path for mounting
   * @param input - Handler, object with fetch method, or H3 instance
   * @returns The H3 instance for chaining
   */
  mount(base: string, input: FetchHandler | { fetch: FetchHandler } | H3): this;
  
  /**
   * Register global middleware
   * @param handler - Middleware function
   * @param opts - Optional middleware options
   * @returns The H3 instance for chaining
   */
  use(handler: Middleware, opts?: MiddlewareOptions): this;
  
  /**
   * Register route-specific middleware
   * @param route - Route pattern
   * @param handler - Middleware function
   * @param opts - Optional middleware options
   * @returns The H3 instance for chaining
   */
  use(route: string, handler: Middleware, opts?: MiddlewareOptions): this;
  
  /**
   * Register a route handler for specific HTTP method
   * @param method - HTTP method
   * @param route - Route pattern
   * @param handler - Event handler function
   * @param opts - Optional route options
   * @returns The H3 instance for chaining
   */
  on(method: HTTPMethod, route: string, handler: EventHandler, opts?: RouteOptions): this;
  
  /**
   * Register a handler for all HTTP methods
   * @param route - Route pattern
   * @param handler - Event handler function
   * @param opts - Optional route options
   * @returns The H3 instance for chaining
   */
  all(route: string, handler: EventHandler, opts?: RouteOptions): this;
  
  /**
   * Register a GET route handler
   * @param route - Route pattern
   * @param handler - Event handler function
   * @param opts - Optional route options
   * @returns The H3 instance for chaining
   */
  get(route: string, handler: EventHandler, opts?: RouteOptions): this;
  
  /**
   * Register a POST route handler
   * @param route - Route pattern
   * @param handler - Event handler function
   * @param opts - Optional route options
   * @returns The H3 instance for chaining
   */
  post(route: string, handler: EventHandler, opts?: RouteOptions): this;
  
  /**
   * Register a PUT route handler
   * @param route - Route pattern
   * @param handler - Event handler function
   * @param opts - Optional route options
   * @returns The H3 instance for chaining
   */
  put(route: string, handler: EventHandler, opts?: RouteOptions): this;
  
  /**
   * Register a DELETE route handler
   * @param route - Route pattern
   * @param handler - Event handler function
   * @param opts - Optional route options
   * @returns The H3 instance for chaining
   */
  delete(route: string, handler: EventHandler, opts?: RouteOptions): this;
  
  /**
   * Register a PATCH route handler
   * @param route - Route pattern
   * @param handler - Event handler function
   * @param opts - Optional route options
   * @returns The H3 instance for chaining
   */
  patch(route: string, handler: EventHandler, opts?: RouteOptions): this;
  
  /**
   * Register a HEAD route handler
   * @param route - Route pattern
   * @param handler - Event handler function
   * @param opts - Optional route options
   * @returns The H3 instance for chaining
   */
  head(route: string, handler: EventHandler, opts?: RouteOptions): this;
  
  /**
   * Register an OPTIONS route handler
   * @param route - Route pattern
   * @param handler - Event handler function
   * @param opts - Optional route options
   * @returns The H3 instance for chaining
   */
  options(route: string, handler: EventHandler, opts?: RouteOptions): this;
}

import { H3, defineHandler } from "h3";

// Create application
const app = new H3({
  debug: true,
  onError: (error, event) => {
    console.error(`Error on ${event.url}:`, error);
  }
});

// Add routes
app.get("/", defineHandler(() => ({ message: "Hello World" })));
app.post("/users", defineHandler(async (event) => {
  const body = await readBody(event);
  return { user: body, id: Math.random() };
}));

// Add middleware
app.use("/api", defineHandler((event) => {
  console.log(`API request: ${event.method} ${event.url}`);
}));

// Mount sub-app
const apiApp = new H3();
apiApp.get("/status", () => ({ status: "OK" }));
app.mount("/api/v1", apiApp);

/**
 * Base H3 implementation without routing
 */
class H3Core {
  constructor(config?: H3Config);
  fetch(request: ServerRequest): Response | Promise<Response>;
  register(plugin: H3Plugin): this;
}

/**
 * Define a reusable H3 plugin
 * @param def - Plugin definition function
 * @returns Plugin function that can be registered
 */
function definePlugin<T>(def: (h3: H3, options: T) => void): H3Plugin;

import { definePlugin } from "h3";

// Create a logging plugin
const loggingPlugin = definePlugin<{ prefix?: string }>((h3, options) => {
  const prefix = options?.prefix || "LOG";
  
  h3.use((event) => {
    console.log(`${prefix}: ${event.method} ${event.url}`);
  });
});

// Create a CORS plugin
const corsPlugin = definePlugin<{ origin: string }>((h3, options) => {
  h3.use((event) => {
    event.res.setHeader("Access-Control-Allow-Origin", options.origin);
  });
});

// Use plugins
const app = new H3();
app.register(loggingPlugin({ prefix: "API" }));
app.register(corsPlugin({ origin: "*" }));

/**
 * Define a route as a plugin
 * @param def - Route definition object
 * @returns H3 plugin that registers the route
 */
function defineRoute(def: RouteDefinition): H3Plugin;

interface RouteDefinition {
  method?: HTTPMethod | HTTPMethod[];
  path: string;
  handler: EventHandler;
  meta?: H3RouteMeta;
}

import { defineRoute } from "h3";

// Define route as plugin
const userRoutes = defineRoute({
  method: "GET",
  path: "/users/:id",
  handler: defineHandler(async (event) => {
    const id = getRouterParam(event, "id");
    return { user: { id, name: "John Doe" } };
  }),
  meta: { auth: true }
});

// Register route plugin
app.register(userRoutes);

interface H3Config {
  /**
   * Enable debug mode for additional logging
   */
  debug?: boolean;
  
  /**
   * Global error handler
   * @param error - The HTTP error that occurred
   * @param event - The H3 event context
   * @returns Optional response or void
   */
  onError?: (error: HTTPError, event: H3Event) => MaybePromise<void | unknown>;
  
  /**
   * Global request middleware
   * @param event - The H3 event context
   */
  onRequest?: (event: H3Event) => MaybePromise<void>;
  
  /**
   * Global response middleware
   * @param response - The response object
   * @param event - The H3 event context
   * @returns Modified response or void
   */
  onResponse?: (response: Response, event: H3Event) => MaybePromise<void | Response>;
}

interface RouteOptions {
  /**
   * Route metadata for additional information
   */
  meta?: H3RouteMeta;
}

interface MiddlewareOptions {
  /**
   * Middleware metadata
   */
  meta?: H3RouteMeta;
}

interface H3RouteMeta {
  [key: string]: any;
}

type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE';

type H3Plugin = (h3: H3, options?: any) => void;

type FetchHandler = (request: ServerRequest, context?: H3EventContext) => Response | Promise<Response>;

interface H3Route {
  path: string;
  method: HTTPMethod;
  handler: EventHandler;
  meta?: H3RouteMeta;
}

type PreparedResponse = Response | BodyInit | null | undefined;