serverstruct 1.0.0 → 1.1.0

package/README.md

@@ -22,7 +22,7 @@ const app = application((app) => {
 app.serve({ port: 3000 });
 ```
 
-## Composing Apps
+## Apps
 
 Create modular h3 apps and mount them together:
 
@@ -66,9 +66,26 @@ const app = application(() => {
 });
 ```
 
-## Controllers with Dependency Injection
+### Accessing the Box Instance
 
-Use `controller()` to create reusable modules with shared dependencies. It integrates with [getbox](https://github.com/eriicafes/getbox) for dependency injection:
+The `application()` function creates a new Box instance by default and returns it along with `app` and `serve`. You can access the box instance to retrieve dependencies:
+
+```typescript
+import { constant } from "getbox";
+
+const Port = constant(5000);
+
+const { box, serve } = application((app, box) => {
+  app.get("/", () => "Hello world!");
+});
+
+const port = box.get(Port);
+serve({ port });
+```
+
+## Controllers
+
+Use `controller()` to create h3 app constructors:
 
 ```typescript
 import { application, controller } from "serverstruct";
@@ -94,89 +111,161 @@ const app = application((app, box) => {
 app.serve({ port: 3000 });
 ```
 
-The `box` parameter is a getbox `Box` instance that manages dependency instances.
+## Handlers
 
-## Sharing Dependencies
+Use `handler()` to create h3 handler constructors:
 
-Controllers can share dependencies using the `box` parameter.
+```typescript
+import { application, handler } from "serverstruct";
 
-Use `box.get(Class)` to retrieve or create a singleton instance:
+class UserService {
+  getUser(id: string) {
+    return { id, name: "Alice" };
+  }
+}
 
-```typescript
-import { application, controller } from "serverstruct";
+// Define a handler
+const getUserHandler = handler((event, box) => {
+  const userService = box.get(UserService);
+  const id = event.context.params?.id;
+  return userService.getUser(id);
+});
+
+// Use it in your app
+const app = application((app, box) => {
+  app.get("/users/:id", box.get(getUserHandler));
+});
+```
+
+### Event Handlers
+
+Use `eventHandler()` to create h3 handlers with additional options like metadata and middleware:
 
-// A shared service
-class Database {
-  users: User[] = [];
+```typescript
+import { application, eventHandler } from "serverstruct";
 
-  getUsers() { return this.users; }
-  addUser(user: User) { this.users.push(user); }
+class UserService {
+  getUser(id: string) {
+    return { id, name: "Alice" };
+  }
 }
 
-// Controller uses box to access the database
-const usersController = controller((app, box) => {
-  const db = box.get(Database);
+// Define an event handler with middleware and metadata
+const getUserHandler = eventHandler((box) => ({
+  handler(event) {
+    const userService = box.get(UserService);
+    const id = event.context.params?.id;
+    return userService.getUser(id);
+  },
+  meta: { auth: true },
+  middleware: [
+    (event) => {
+      const token = event.headers.get("authorization");
+      if (!token || token !== "secret-token") {
+        throw new Error("Unauthorized");
+      }
+    },
+  ],
+}));
 
-  app.get("/", () => db.getUsers());
-  app.post("/", async (event) => {
-    const body = await readValidatedBody(event, validateUser);
-    db.addUser(body);
-    return body;
-  });
+// Use it in your app
+const app = application((app, box) => {
+  app.get("/users/:id", box.get(getUserHandler));
 });
+```
+
+## Middleware
+
+Use `middleware()` to create h3 middleware constructors:
 
-// Another controller can access the same database
-const statsController = controller((app, box) => {
-  const db = box.get(Database);
+```typescript
+import { application, middleware } from "serverstruct";
+
+class Logger {
+  log(message: string) {
+    console.log(message);
+  }
+}
 
-  app.get("/count", () => ({ count: db.getUsers().length }));
+// Define a middleware
+const logMiddleware = middleware((event, next, box) => {
+  const logger = box.get(Logger);
+  logger.log("Request received");
 });
 
+// Use it in your app
 const app = application((app, box) => {
-  app.mount("/users", box.new(usersController));
-  app.mount("/stats", box.new(statsController));
+  app.use(box.get(logMiddleware));
+  app.get("/", () => "Hello world!");
 });
-
-await app.serve({ port: 3000 });
 ```
 
-`box.get(Class)` creates the instance on first call, then caches it.
+## Context
 
-## Middleware
-
-Use h3's native middleware with `app.use()`:
+The `context()` function creates a request-scoped, type-safe store for per-request values. Each request gets its own isolated context that is automatically cleaned up when the request completes.
 
 ```typescript
+import { application, context } from "serverstruct";
+
+interface User {
+  id: string;
+  name: string;
+}
+
+// Create a context store
+const userContext = context<User>();
+
 const app = application((app) => {
-  // Global middleware
-  app.use(() => console.log("Request received"));
+  // Set context in middleware
+  app.use((event) => {
+    const user = { id: "123", name: "Alice" };
+    userContext.set(event, user);
+  });
 
-  app.get("/", () => "Hello world!");
+  // Access context in handlers
+  app.get("/profile", (event) => {
+    const user = userContext.get(event);
+    return { profile: user };
+  });
 });
 ```
 
-Controllers can have their own middleware:
+### Context Methods
+
+- `set(event, value)` - Store a value for the current request
+- `get(event)` - Retrieve the value for the current request (throws if not found)
+- `lookup(event)` - Retrieve the value or `undefined` if not found
 
 ```typescript
-const usersController = controller((app) => {
-  // Runs only for routes in this controller
-  app.use(() => console.log("Users route accessed"));
+const requestIdContext = context<string>();
 
-  app.get("/", () => [...]);
-  app.post("/", async () => {...});
+const app = application((app) => {
+  app.use((event) => {
+    requestIdContext.set(event, crypto.randomUUID());
+  });
+
+  app.get("/", (event) => {
+    // Safe access - throws if not set
+    const id = requestIdContext.get(event);
+
+    // Optional access - returns undefined if not set
+    const maybeId = requestIdContext.lookup(event);
+
+    return { requestId: id };
+  });
 });
 ```
 
 ## Custom Box Instance
 
-Pass your own Box instance to `application()` for more control:
+You can also pass your own Box instance to share dependencies across multiple applications or mock dependencies:
 
 ```typescript
 import { Box } from "getbox";
 
 const box = new Box();
 
-// Pre-populate with dependencies
+// Mock a dependency
 Box.mock(box, Database, new Database());
 
 const app = application((app, box) => {

package/dist/index.cjs

@@ -1,15 +1,15 @@
-let h3 = require("h3");
 let getbox = require("getbox");
+let h3 = require("h3");
 
 //#region src/index.ts
 /**
-* Creates an h3 application with dependency injection support.
+* Creates an h3 application.
 *
-* @param fn - Function that configures the app. Receives a fresh H3 instance
-*             and Box instance. Can add routes to the provided app, or create
-*             and return a new H3 instance.
+* @param setup - Function that configures the app. Receives a fresh H3 instance
+*                and Box instance. Can add routes to the provided app, or create
+*                and return a new H3 instance.
 * @param box - Optional Box instance. If not provided, creates a new one.
-* @returns Object with `app` (H3 instance) and `serve` method.
+* @returns Object with `app` (H3 instance), `box` (Box instance), and `serve` method.
 *
 * @example
 * ```typescript
@@ -30,28 +30,33 @@ let getbox = require("getbox");
 * await app.serve({ port: 3000 });
 * ```
 */
-function application(fn, box = new getbox.Box()) {
+function application(setup, box = new getbox.Box()) {
 	const defaultApp = new h3.H3();
-	const app = fn(defaultApp, box) || defaultApp;
+	const app = setup(defaultApp, box) || defaultApp;
 	return {
 		app,
+		box,
 		serve: (options) => (0, h3.serve)(app, options)
 	};
 }
 /**
-* Creates a Constructor that produces an h3 app when resolved.
-*
-* Use `box.new(controller)` to create fresh controller instances.
-* Controllers can use `box.get()` to access shared dependencies.
+* Creates an h3 app constructor.
 *
-* @param fn - Function that configures the controller.
-* @returns A Constructor that can be resolved via `box.new(controller)`.
+* @param setup - Function that configures the app.
+* @returns A Constructor that produces an h3 app.
 *
 * @example
 * ```typescript
+* import { application, controller } from "serverstruct";
+*
+* class Database {
+*   getUsers() { return ["Alice", "Bob"]; }
+* }
+*
 * // Define a controller
 * const usersController = controller((app, box) => {
-*   app.get("/", () => ["Alice", "Bob"]);
+*   const db = box.get(Database);
+*   app.get("/", () => db.getUsers());
 * });
 *
 * // Use it in your app
@@ -59,24 +64,188 @@ function application(fn, box = new getbox.Box()) {
 *   app.mount("/users", box.new(usersController));
 * });
 * ```
+*/
+function controller(setup) {
+	return (0, getbox.factory)((box) => application(setup, box).app);
+}
+/**
+* Creates a handler constructor.
+*
+* @param setup - Handler function that receives the event and Box instance.
+* @returns A Constructor that produces an h3 handler.
 *
 * @example
 * ```typescript
-* // Controller with shared dependencies
-* class Database {
-*   getUsers() { return ["Alice", "Bob"]; }
+* import { application, handler } from "serverstruct";
+*
+* class UserService {
+*   getUser(id: string) { return { id, name: "Alice" }; }
 * }
 *
-* const usersController = controller((app, box) => {
-*   const db = box.get(Database);
-*   app.get("/", () => db.getUsers());
+* // Define a handler
+* const getUserHandler = handler((event, box) => {
+*   const userService = box.get(UserService);
+*   const id = event.context.params?.id;
+*   return userService.getUser(id);
+* });
+*
+* // Use it in your app
+* const app = application((app, box) => {
+*   app.get("/users/:id", box.get(getUserHandler));
+* });
+* ```
+*/
+function handler(setup) {
+	return (0, getbox.factory)((box) => (0, h3.defineHandler)((event) => setup(event, box)));
+}
+/**
+* Creates an event handler constructor from a setup function.
+*
+* @param setup - Function that receives Box instance and returns an event handler object.
+* @returns A Constructor that produces an h3 event handler.
+*
+* @example
+* ```typescript
+* import { application, eventHandler } from "serverstruct";
+*
+* class UserService {
+*   getUser(id: string) { return { id, name: "Alice" }; }
+* }
+*
+* // Define an event handler
+* const getUserHandler = eventHandler((box) => ({
+*   handler(event) {
+*     const userService = box.get(UserService);
+*     const id = event.context.params?.id;
+*     return userService.getUser(id);
+*   },
+*   meta: { auth: true }
+* }));
+*
+* // Use it in your app
+* const app = application((app, box) => {
+*   app.get("/users/:id", box.get(getUserHandler));
+* });
+* ```
+*/
+function eventHandler(setup) {
+	return (0, getbox.factory)((box) => (0, h3.defineHandler)(setup(box)));
+}
+/**
+* Creates a middleware constructor.
+*
+* @param setup - Middleware function that receives the event, next function, and Box instance.
+* @returns A Constructor that produces an h3 middleware.
+*
+* @example
+* ```typescript
+* import { application, middleware } from "serverstruct";
+*
+* class AuthService {
+*   validateToken(token: string) { return token === "valid"; }
+* }
+*
+* // Define a middleware
+* const authMiddleware = middleware((event, next, box) => {
+*   const authService = box.get(AuthService);
+*   const token = event.headers.get("authorization");
+*   if (!token || !authService.validateToken(token)) {
+*     throw new Error("Unauthorized");
+*   }
+* });
+*
+* // Use it in your app
+* const app = application((app, box) => {
+*   app.use(box.get(authMiddleware));
+*   app.get("/", () => "Hello world!");
+* });
+* ```
+*/
+function middleware(setup) {
+	return (0, getbox.factory)((box) => (0, h3.defineMiddleware)((event, next) => setup(event, next, box)));
+}
+/**
+* A request-scoped context store for associating values with H3 events.
+*
+* Each request gets its own isolated context that is automatically cleaned up
+* when the request completes. Uses a WeakMap internally to ensure values are
+* garbage collected with their events.
+*
+* @example
+* ```typescript
+* import { application, Context } from "serverstruct";
+*
+* const userContext = new Context<User>();
+*
+* const app = application((app) => {
+*   app.use((event) => {
+*     userContext.set(event, { id: "123", name: "Alice" });
+*   });
+*   app.get("/user", (event) => {
+*     const user = userContext.get(event);
+*     return user;
+*   });
+* });
+* ```
+*/
+var Context = class {
+	#map = /* @__PURE__ */ new WeakMap();
+	/**
+	* Sets a value for the given event.
+	*/
+	set(event, value) {
+		this.#map.set(event, value);
+	}
+	/**
+	* Gets the value for the given event.
+	* @throws Error if no value is set for the event.
+	*/
+	get(event) {
+		if (this.#map.has(event)) return this.#map.get(event);
+		throw new Error("context not found");
+	}
+	/**
+	* Gets the value for the given event, or undefined if not set.
+	*/
+	lookup(event) {
+		return this.#map.get(event);
+	}
+};
+/**
+* Creates a request-scoped context store for associating values with H3 events.
+*
+* Each request gets its own isolated context that is automatically cleaned up
+* when the request completes. Uses a WeakMap internally to ensure values are
+* garbage collected with their events.
+*
+* @returns A Context instance.
+*
+* @example
+* ```typescript
+* import { application, context } from "serverstruct";
+*
+* const userContext = context<User>();
+*
+* const app = application((app) => {
+*   app.use((event) => {
+*     userContext.set(event, { id: "123", name: "Alice" });
+*   });
+*   app.get("/user", (event) => {
+*     const user = userContext.get(event);
+*     return user;
+*   });
 * });
 * ```
 */
-function controller(fn) {
-	return (0, getbox.factory)((box) => application(fn, box).app);
+function context() {
+	return new Context();
 }
 
 //#endregion
+exports.Context = Context;
 exports.application = application;
-exports.controller = controller;
+exports.context = context;
+exports.controller = controller;
+exports.eventHandler = eventHandler;
+exports.handler = handler;
+exports.middleware = middleware;

package/dist/index.d.cts

@@ -1,16 +1,19 @@
-import { H3, serve } from "h3";
+import * as h30 from "h3";
+import { EventHandlerObject, EventHandlerRequest, H3, H3Event, Middleware, serve } from "h3";
 import { Box, Constructor } from "getbox";
 
 //#region src/index.d.ts
+type MaybePromise<T = unknown> = T | Promise<T>;
+type Server = ReturnType<typeof serve>;
 type ServeOptions = Parameters<typeof serve>[1];
 /**
- * Creates an h3 application with dependency injection support.
+ * Creates an h3 application.
  *
- * @param fn - Function that configures the app. Receives a fresh H3 instance
- *             and Box instance. Can add routes to the provided app, or create
- *             and return a new H3 instance.
+ * @param setup - Function that configures the app. Receives a fresh H3 instance
+ *                and Box instance. Can add routes to the provided app, or create
+ *                and return a new H3 instance.
  * @param box - Optional Box instance. If not provided, creates a new one.
- * @returns Object with `app` (H3 instance) and `serve` method.
+ * @returns Object with `app` (H3 instance), `box` (Box instance), and `serve` method.
  *
  * @example
  * ```typescript
@@ -31,24 +34,29 @@ type ServeOptions = Parameters<typeof serve>[1];
  * await app.serve({ port: 3000 });
  * ```
  */
-declare function application(fn: (app: H3, box: Box) => H3 | void, box?: Box): {
+declare function application(setup: (app: H3, box: Box) => H3 | void, box?: Box): {
   app: H3;
-  serve: (options?: ServeOptions) => ReturnType<typeof serve>;
+  box: Box;
+  serve: (options?: ServeOptions) => Server;
 };
 /**
- * Creates a Constructor that produces an h3 app when resolved.
+ * Creates an h3 app constructor.
  *
- * Use `box.new(controller)` to create fresh controller instances.
- * Controllers can use `box.get()` to access shared dependencies.
- *
- * @param fn - Function that configures the controller.
- * @returns A Constructor that can be resolved via `box.new(controller)`.
+ * @param setup - Function that configures the app.
+ * @returns A Constructor that produces an h3 app.
  *
  * @example
  * ```typescript
+ * import { application, controller } from "serverstruct";
+ *
+ * class Database {
+ *   getUsers() { return ["Alice", "Bob"]; }
+ * }
+ *
  * // Define a controller
  * const usersController = controller((app, box) => {
- *   app.get("/", () => ["Alice", "Bob"]);
+ *   const db = box.get(Database);
+ *   app.get("/", () => db.getUsers());
  * });
  *
  * // Use it in your app
@@ -56,20 +64,164 @@ declare function application(fn: (app: H3, box: Box) => H3 | void, box?: Box): {
  *   app.mount("/users", box.new(usersController));
  * });
  * ```
+ */
+declare function controller(setup: (app: H3, box: Box) => H3 | void): Constructor<H3>;
+/**
+ * Creates a handler constructor.
+ *
+ * @param setup - Handler function that receives the event and Box instance.
+ * @returns A Constructor that produces an h3 handler.
  *
  * @example
  * ```typescript
- * // Controller with shared dependencies
- * class Database {
- *   getUsers() { return ["Alice", "Bob"]; }
+ * import { application, handler } from "serverstruct";
+ *
+ * class UserService {
+ *   getUser(id: string) { return { id, name: "Alice" }; }
  * }
  *
- * const usersController = controller((app, box) => {
- *   const db = box.get(Database);
- *   app.get("/", () => db.getUsers());
+ * // Define a handler
+ * const getUserHandler = handler((event, box) => {
+ *   const userService = box.get(UserService);
+ *   const id = event.context.params?.id;
+ *   return userService.getUser(id);
+ * });
+ *
+ * // Use it in your app
+ * const app = application((app, box) => {
+ *   app.get("/users/:id", box.get(getUserHandler));
+ * });
+ * ```
+ */
+declare function handler<Res = unknown, Req extends EventHandlerRequest = EventHandlerRequest>(setup: (event: H3Event<Req>, box: Box) => Res): Constructor<h30.EventHandlerWithFetch<Req, Res>>;
+/**
+ * Creates an event handler constructor from a setup function.
+ *
+ * @param setup - Function that receives Box instance and returns an event handler object.
+ * @returns A Constructor that produces an h3 event handler.
+ *
+ * @example
+ * ```typescript
+ * import { application, eventHandler } from "serverstruct";
+ *
+ * class UserService {
+ *   getUser(id: string) { return { id, name: "Alice" }; }
+ * }
+ *
+ * // Define an event handler
+ * const getUserHandler = eventHandler((box) => ({
+ *   handler(event) {
+ *     const userService = box.get(UserService);
+ *     const id = event.context.params?.id;
+ *     return userService.getUser(id);
+ *   },
+ *   meta: { auth: true }
+ * }));
+ *
+ * // Use it in your app
+ * const app = application((app, box) => {
+ *   app.get("/users/:id", box.get(getUserHandler));
+ * });
+ * ```
+ */
+declare function eventHandler<Res = unknown, Req extends EventHandlerRequest = EventHandlerRequest>(setup: (box: Box) => EventHandlerObject<Req, Res>): Constructor<h30.EventHandlerWithFetch<Req, Res>>;
+/**
+ * Creates a middleware constructor.
+ *
+ * @param setup - Middleware function that receives the event, next function, and Box instance.
+ * @returns A Constructor that produces an h3 middleware.
+ *
+ * @example
+ * ```typescript
+ * import { application, middleware } from "serverstruct";
+ *
+ * class AuthService {
+ *   validateToken(token: string) { return token === "valid"; }
+ * }
+ *
+ * // Define a middleware
+ * const authMiddleware = middleware((event, next, box) => {
+ *   const authService = box.get(AuthService);
+ *   const token = event.headers.get("authorization");
+ *   if (!token || !authService.validateToken(token)) {
+ *     throw new Error("Unauthorized");
+ *   }
+ * });
+ *
+ * // Use it in your app
+ * const app = application((app, box) => {
+ *   app.use(box.get(authMiddleware));
+ *   app.get("/", () => "Hello world!");
+ * });
+ * ```
+ */
+declare function middleware(setup: (event: H3Event, next: () => MaybePromise<unknown | undefined>, box: Box) => MaybePromise<unknown | undefined>): Constructor<Middleware>;
+/**
+ * A request-scoped context store for associating values with H3 events.
+ *
+ * Each request gets its own isolated context that is automatically cleaned up
+ * when the request completes. Uses a WeakMap internally to ensure values are
+ * garbage collected with their events.
+ *
+ * @example
+ * ```typescript
+ * import { application, Context } from "serverstruct";
+ *
+ * const userContext = new Context<User>();
+ *
+ * const app = application((app) => {
+ *   app.use((event) => {
+ *     userContext.set(event, { id: "123", name: "Alice" });
+ *   });
+ *   app.get("/user", (event) => {
+ *     const user = userContext.get(event);
+ *     return user;
+ *   });
+ * });
+ * ```
+ */
+declare class Context<T> {
+  #private;
+  /**
+   * Sets a value for the given event.
+   */
+  set(event: H3Event<any>, value: T): void;
+  /**
+   * Gets the value for the given event.
+   * @throws Error if no value is set for the event.
+   */
+  get(event: H3Event<any>): T;
+  /**
+   * Gets the value for the given event, or undefined if not set.
+   */
+  lookup(event: H3Event<any>): T | undefined;
+}
+/**
+ * Creates a request-scoped context store for associating values with H3 events.
+ *
+ * Each request gets its own isolated context that is automatically cleaned up
+ * when the request completes. Uses a WeakMap internally to ensure values are
+ * garbage collected with their events.
+ *
+ * @returns A Context instance.
+ *
+ * @example
+ * ```typescript
+ * import { application, context } from "serverstruct";
+ *
+ * const userContext = context<User>();
+ *
+ * const app = application((app) => {
+ *   app.use((event) => {
+ *     userContext.set(event, { id: "123", name: "Alice" });
+ *   });
+ *   app.get("/user", (event) => {
+ *     const user = userContext.get(event);
+ *     return user;
+ *   });
  * });
  * ```
  */
-declare function controller(fn: (app: H3, box: Box) => H3 | void): Constructor<H3>;
+declare function context<T>(): Context<T>;
 //#endregion
-export { ServeOptions, application, controller };
+export { Context, ServeOptions, Server, application, context, controller, eventHandler, handler, middleware };

package/dist/index.d.mts

@@ -1,16 +1,19 @@
-import { H3, serve } from "h3";
 import { Box, Constructor } from "getbox";
+import * as h30 from "h3";
+import { EventHandlerObject, EventHandlerRequest, H3, H3Event, Middleware, serve } from "h3";
 
 //#region src/index.d.ts
+type MaybePromise<T = unknown> = T | Promise<T>;
+type Server = ReturnType<typeof serve>;
 type ServeOptions = Parameters<typeof serve>[1];
 /**
- * Creates an h3 application with dependency injection support.
+ * Creates an h3 application.
  *
- * @param fn - Function that configures the app. Receives a fresh H3 instance
- *             and Box instance. Can add routes to the provided app, or create
- *             and return a new H3 instance.
+ * @param setup - Function that configures the app. Receives a fresh H3 instance
+ *                and Box instance. Can add routes to the provided app, or create
+ *                and return a new H3 instance.
  * @param box - Optional Box instance. If not provided, creates a new one.
- * @returns Object with `app` (H3 instance) and `serve` method.
+ * @returns Object with `app` (H3 instance), `box` (Box instance), and `serve` method.
  *
  * @example
  * ```typescript
@@ -31,24 +34,29 @@ type ServeOptions = Parameters<typeof serve>[1];
  * await app.serve({ port: 3000 });
  * ```
  */
-declare function application(fn: (app: H3, box: Box) => H3 | void, box?: Box): {
+declare function application(setup: (app: H3, box: Box) => H3 | void, box?: Box): {
   app: H3;
-  serve: (options?: ServeOptions) => ReturnType<typeof serve>;
+  box: Box;
+  serve: (options?: ServeOptions) => Server;
 };
 /**
- * Creates a Constructor that produces an h3 app when resolved.
+ * Creates an h3 app constructor.
  *
- * Use `box.new(controller)` to create fresh controller instances.
- * Controllers can use `box.get()` to access shared dependencies.
- *
- * @param fn - Function that configures the controller.
- * @returns A Constructor that can be resolved via `box.new(controller)`.
+ * @param setup - Function that configures the app.
+ * @returns A Constructor that produces an h3 app.
  *
  * @example
  * ```typescript
+ * import { application, controller } from "serverstruct";
+ *
+ * class Database {
+ *   getUsers() { return ["Alice", "Bob"]; }
+ * }
+ *
  * // Define a controller
  * const usersController = controller((app, box) => {
- *   app.get("/", () => ["Alice", "Bob"]);
+ *   const db = box.get(Database);
+ *   app.get("/", () => db.getUsers());
  * });
  *
  * // Use it in your app
@@ -56,20 +64,164 @@ declare function application(fn: (app: H3, box: Box) => H3 | void, box?: Box): {
  *   app.mount("/users", box.new(usersController));
  * });
  * ```
+ */
+declare function controller(setup: (app: H3, box: Box) => H3 | void): Constructor<H3>;
+/**
+ * Creates a handler constructor.
+ *
+ * @param setup - Handler function that receives the event and Box instance.
+ * @returns A Constructor that produces an h3 handler.
  *
  * @example
  * ```typescript
- * // Controller with shared dependencies
- * class Database {
- *   getUsers() { return ["Alice", "Bob"]; }
+ * import { application, handler } from "serverstruct";
+ *
+ * class UserService {
+ *   getUser(id: string) { return { id, name: "Alice" }; }
  * }
  *
- * const usersController = controller((app, box) => {
- *   const db = box.get(Database);
- *   app.get("/", () => db.getUsers());
+ * // Define a handler
+ * const getUserHandler = handler((event, box) => {
+ *   const userService = box.get(UserService);
+ *   const id = event.context.params?.id;
+ *   return userService.getUser(id);
+ * });
+ *
+ * // Use it in your app
+ * const app = application((app, box) => {
+ *   app.get("/users/:id", box.get(getUserHandler));
+ * });
+ * ```
+ */
+declare function handler<Res = unknown, Req extends EventHandlerRequest = EventHandlerRequest>(setup: (event: H3Event<Req>, box: Box) => Res): Constructor<h30.EventHandlerWithFetch<Req, Res>>;
+/**
+ * Creates an event handler constructor from a setup function.
+ *
+ * @param setup - Function that receives Box instance and returns an event handler object.
+ * @returns A Constructor that produces an h3 event handler.
+ *
+ * @example
+ * ```typescript
+ * import { application, eventHandler } from "serverstruct";
+ *
+ * class UserService {
+ *   getUser(id: string) { return { id, name: "Alice" }; }
+ * }
+ *
+ * // Define an event handler
+ * const getUserHandler = eventHandler((box) => ({
+ *   handler(event) {
+ *     const userService = box.get(UserService);
+ *     const id = event.context.params?.id;
+ *     return userService.getUser(id);
+ *   },
+ *   meta: { auth: true }
+ * }));
+ *
+ * // Use it in your app
+ * const app = application((app, box) => {
+ *   app.get("/users/:id", box.get(getUserHandler));
+ * });
+ * ```
+ */
+declare function eventHandler<Res = unknown, Req extends EventHandlerRequest = EventHandlerRequest>(setup: (box: Box) => EventHandlerObject<Req, Res>): Constructor<h30.EventHandlerWithFetch<Req, Res>>;
+/**
+ * Creates a middleware constructor.
+ *
+ * @param setup - Middleware function that receives the event, next function, and Box instance.
+ * @returns A Constructor that produces an h3 middleware.
+ *
+ * @example
+ * ```typescript
+ * import { application, middleware } from "serverstruct";
+ *
+ * class AuthService {
+ *   validateToken(token: string) { return token === "valid"; }
+ * }
+ *
+ * // Define a middleware
+ * const authMiddleware = middleware((event, next, box) => {
+ *   const authService = box.get(AuthService);
+ *   const token = event.headers.get("authorization");
+ *   if (!token || !authService.validateToken(token)) {
+ *     throw new Error("Unauthorized");
+ *   }
+ * });
+ *
+ * // Use it in your app
+ * const app = application((app, box) => {
+ *   app.use(box.get(authMiddleware));
+ *   app.get("/", () => "Hello world!");
+ * });
+ * ```
+ */
+declare function middleware(setup: (event: H3Event, next: () => MaybePromise<unknown | undefined>, box: Box) => MaybePromise<unknown | undefined>): Constructor<Middleware>;
+/**
+ * A request-scoped context store for associating values with H3 events.
+ *
+ * Each request gets its own isolated context that is automatically cleaned up
+ * when the request completes. Uses a WeakMap internally to ensure values are
+ * garbage collected with their events.
+ *
+ * @example
+ * ```typescript
+ * import { application, Context } from "serverstruct";
+ *
+ * const userContext = new Context<User>();
+ *
+ * const app = application((app) => {
+ *   app.use((event) => {
+ *     userContext.set(event, { id: "123", name: "Alice" });
+ *   });
+ *   app.get("/user", (event) => {
+ *     const user = userContext.get(event);
+ *     return user;
+ *   });
+ * });
+ * ```
+ */
+declare class Context<T> {
+  #private;
+  /**
+   * Sets a value for the given event.
+   */
+  set(event: H3Event<any>, value: T): void;
+  /**
+   * Gets the value for the given event.
+   * @throws Error if no value is set for the event.
+   */
+  get(event: H3Event<any>): T;
+  /**
+   * Gets the value for the given event, or undefined if not set.
+   */
+  lookup(event: H3Event<any>): T | undefined;
+}
+/**
+ * Creates a request-scoped context store for associating values with H3 events.
+ *
+ * Each request gets its own isolated context that is automatically cleaned up
+ * when the request completes. Uses a WeakMap internally to ensure values are
+ * garbage collected with their events.
+ *
+ * @returns A Context instance.
+ *
+ * @example
+ * ```typescript
+ * import { application, context } from "serverstruct";
+ *
+ * const userContext = context<User>();
+ *
+ * const app = application((app) => {
+ *   app.use((event) => {
+ *     userContext.set(event, { id: "123", name: "Alice" });
+ *   });
+ *   app.get("/user", (event) => {
+ *     const user = userContext.get(event);
+ *     return user;
+ *   });
  * });
  * ```
  */
-declare function controller(fn: (app: H3, box: Box) => H3 | void): Constructor<H3>;
+declare function context<T>(): Context<T>;
 //#endregion
-export { ServeOptions, application, controller };
+export { Context, ServeOptions, Server, application, context, controller, eventHandler, handler, middleware };

package/dist/index.mjs

@@ -1,15 +1,15 @@
-import { H3, serve } from "h3";
 import { Box, factory } from "getbox";
+import { H3, defineHandler, defineMiddleware, serve } from "h3";
 
 //#region src/index.ts
 /**
-* Creates an h3 application with dependency injection support.
+* Creates an h3 application.
 *
-* @param fn - Function that configures the app. Receives a fresh H3 instance
-*             and Box instance. Can add routes to the provided app, or create
-*             and return a new H3 instance.
+* @param setup - Function that configures the app. Receives a fresh H3 instance
+*                and Box instance. Can add routes to the provided app, or create
+*                and return a new H3 instance.
 * @param box - Optional Box instance. If not provided, creates a new one.
-* @returns Object with `app` (H3 instance) and `serve` method.
+* @returns Object with `app` (H3 instance), `box` (Box instance), and `serve` method.
 *
 * @example
 * ```typescript
@@ -30,28 +30,33 @@ import { Box, factory } from "getbox";
 * await app.serve({ port: 3000 });
 * ```
 */
-function application(fn, box = new Box()) {
+function application(setup, box = new Box()) {
 	const defaultApp = new H3();
-	const app = fn(defaultApp, box) || defaultApp;
+	const app = setup(defaultApp, box) || defaultApp;
 	return {
 		app,
+		box,
 		serve: (options) => serve(app, options)
 	};
 }
 /**
-* Creates a Constructor that produces an h3 app when resolved.
+* Creates an h3 app constructor.
 *
-* Use `box.new(controller)` to create fresh controller instances.
-* Controllers can use `box.get()` to access shared dependencies.
-*
-* @param fn - Function that configures the controller.
-* @returns A Constructor that can be resolved via `box.new(controller)`.
+* @param setup - Function that configures the app.
+* @returns A Constructor that produces an h3 app.
 *
 * @example
 * ```typescript
+* import { application, controller } from "serverstruct";
+*
+* class Database {
+*   getUsers() { return ["Alice", "Bob"]; }
+* }
+*
 * // Define a controller
 * const usersController = controller((app, box) => {
-*   app.get("/", () => ["Alice", "Bob"]);
+*   const db = box.get(Database);
+*   app.get("/", () => db.getUsers());
 * });
 *
 * // Use it in your app
@@ -59,23 +64,182 @@ function application(fn, box = new Box()) {
 *   app.mount("/users", box.new(usersController));
 * });
 * ```
+*/
+function controller(setup) {
+	return factory((box) => application(setup, box).app);
+}
+/**
+* Creates a handler constructor.
+*
+* @param setup - Handler function that receives the event and Box instance.
+* @returns A Constructor that produces an h3 handler.
 *
 * @example
 * ```typescript
-* // Controller with shared dependencies
-* class Database {
-*   getUsers() { return ["Alice", "Bob"]; }
+* import { application, handler } from "serverstruct";
+*
+* class UserService {
+*   getUser(id: string) { return { id, name: "Alice" }; }
 * }
 *
-* const usersController = controller((app, box) => {
-*   const db = box.get(Database);
-*   app.get("/", () => db.getUsers());
+* // Define a handler
+* const getUserHandler = handler((event, box) => {
+*   const userService = box.get(UserService);
+*   const id = event.context.params?.id;
+*   return userService.getUser(id);
+* });
+*
+* // Use it in your app
+* const app = application((app, box) => {
+*   app.get("/users/:id", box.get(getUserHandler));
+* });
+* ```
+*/
+function handler(setup) {
+	return factory((box) => defineHandler((event) => setup(event, box)));
+}
+/**
+* Creates an event handler constructor from a setup function.
+*
+* @param setup - Function that receives Box instance and returns an event handler object.
+* @returns A Constructor that produces an h3 event handler.
+*
+* @example
+* ```typescript
+* import { application, eventHandler } from "serverstruct";
+*
+* class UserService {
+*   getUser(id: string) { return { id, name: "Alice" }; }
+* }
+*
+* // Define an event handler
+* const getUserHandler = eventHandler((box) => ({
+*   handler(event) {
+*     const userService = box.get(UserService);
+*     const id = event.context.params?.id;
+*     return userService.getUser(id);
+*   },
+*   meta: { auth: true }
+* }));
+*
+* // Use it in your app
+* const app = application((app, box) => {
+*   app.get("/users/:id", box.get(getUserHandler));
+* });
+* ```
+*/
+function eventHandler(setup) {
+	return factory((box) => defineHandler(setup(box)));
+}
+/**
+* Creates a middleware constructor.
+*
+* @param setup - Middleware function that receives the event, next function, and Box instance.
+* @returns A Constructor that produces an h3 middleware.
+*
+* @example
+* ```typescript
+* import { application, middleware } from "serverstruct";
+*
+* class AuthService {
+*   validateToken(token: string) { return token === "valid"; }
+* }
+*
+* // Define a middleware
+* const authMiddleware = middleware((event, next, box) => {
+*   const authService = box.get(AuthService);
+*   const token = event.headers.get("authorization");
+*   if (!token || !authService.validateToken(token)) {
+*     throw new Error("Unauthorized");
+*   }
+* });
+*
+* // Use it in your app
+* const app = application((app, box) => {
+*   app.use(box.get(authMiddleware));
+*   app.get("/", () => "Hello world!");
+* });
+* ```
+*/
+function middleware(setup) {
+	return factory((box) => defineMiddleware((event, next) => setup(event, next, box)));
+}
+/**
+* A request-scoped context store for associating values with H3 events.
+*
+* Each request gets its own isolated context that is automatically cleaned up
+* when the request completes. Uses a WeakMap internally to ensure values are
+* garbage collected with their events.
+*
+* @example
+* ```typescript
+* import { application, Context } from "serverstruct";
+*
+* const userContext = new Context<User>();
+*
+* const app = application((app) => {
+*   app.use((event) => {
+*     userContext.set(event, { id: "123", name: "Alice" });
+*   });
+*   app.get("/user", (event) => {
+*     const user = userContext.get(event);
+*     return user;
+*   });
+* });
+* ```
+*/
+var Context = class {
+	#map = /* @__PURE__ */ new WeakMap();
+	/**
+	* Sets a value for the given event.
+	*/
+	set(event, value) {
+		this.#map.set(event, value);
+	}
+	/**
+	* Gets the value for the given event.
+	* @throws Error if no value is set for the event.
+	*/
+	get(event) {
+		if (this.#map.has(event)) return this.#map.get(event);
+		throw new Error("context not found");
+	}
+	/**
+	* Gets the value for the given event, or undefined if not set.
+	*/
+	lookup(event) {
+		return this.#map.get(event);
+	}
+};
+/**
+* Creates a request-scoped context store for associating values with H3 events.
+*
+* Each request gets its own isolated context that is automatically cleaned up
+* when the request completes. Uses a WeakMap internally to ensure values are
+* garbage collected with their events.
+*
+* @returns A Context instance.
+*
+* @example
+* ```typescript
+* import { application, context } from "serverstruct";
+*
+* const userContext = context<User>();
+*
+* const app = application((app) => {
+*   app.use((event) => {
+*     userContext.set(event, { id: "123", name: "Alice" });
+*   });
+*   app.get("/user", (event) => {
+*     const user = userContext.get(event);
+*     return user;
+*   });
 * });
 * ```
 */
-function controller(fn) {
-	return factory((box) => application(fn, box).app);
+function context() {
+	return new Context();
 }
 
 //#endregion
-export { application, controller };
+export { Context, application, context, controller, eventHandler, handler, middleware };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverstruct",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Type safe and modular servers with H3",
   "private": false,
   "main": "./dist/index.cjs",
@@ -18,13 +18,6 @@
       }
     }
   },
-  "scripts": {
-    "build": "tsc && tsdown src/index.ts --format esm,cjs",
-    "release": "pnpm run build && changeset publish",
-    "watch": "vitest",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
-  },
   "keywords": [
     "h3",
     "server",
@@ -52,5 +45,12 @@
   "peerDependencies": {
     "getbox": ">= 1.0.0 <2.0.0",
     "h3": ">=2.0.1-rc.6 <3.0.0"
+  },
+  "scripts": {
+    "build": "tsc && tsdown src/index.ts --format esm,cjs",
+    "release": "pnpm run build && changeset publish",
+    "watch": "vitest",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
 }