serverstruct 1.0.0 → 1.2.0

package/README.md

@@ -2,7 +2,12 @@
 
 ⚡️ Typesafe and modular servers with [H3](https://github.com/unjs/h3).
 
-Serverstruct provides simple helpers for building modular h3 applications with dependency injection using [getbox](https://github.com/eriicafes/getbox).
+Serverstruct provides simple helpers for building modular H3 applications with dependency injection using [getbox](https://github.com/eriicafes/getbox).
+
+## Integrations
+
+- [OpenAPI](./OPENAPI.md) - Typesafe OpenAPI operations with Zod schema validation.
+- [OpenTelemetry](./OTEL.md) - Distributed tracing middleware for HTTP requests.
 
 ## Installation
 
@@ -13,173 +18,311 @@ npm i serverstruct h3 getbox
 ## Quick Start
 
 ```typescript
-import { application } from "serverstruct";
+import { application, serve } from "serverstruct";
 
 const app = application((app) => {
   app.get("/", () => "Hello world!");
 });
 
-app.serve({ port: 3000 });
+serve(app, { port: 3000 });
 ```
 
-## Composing Apps
+## Application
 
-Create modular h3 apps and mount them together:
+`application()` creates an H3 instance and a Box instance for dependency injection.
+You can pass a Box instance to share dependencies across applications (see [Box Instance](#box-instance)).
 
-```typescript
-import { application } from "serverstruct";
+You can mount other apps using `app.mount()`:
 
-// Create a users module
-const { app: usersApp } = application((app) => {
-  const users: User[] = [];
+```typescript
+import { H3 } from "h3";
+import { application, serve } from "serverstruct";
 
-  app.get("/", () => users);
-  app.post("/", async (event) => {
-    const body = await readValidatedBody(event, validateUser);
-    users.push(body);
-    return body;
-  });
+// Create a sub application
+const usersApp = application((app) => {
+  app.get("/", () => ["Alice", "Bob"]);
 });
 
-// Compose in main app
+// Create a regular H3 instance
+const docsApp = new H3().get("/", () => "API Documentation");
+
+// Mount in main app
 const app = application((app) => {
-  app.get("/ping", () => "pong");
+  app.get("/", () => "Hello world!");
   app.mount("/users", usersApp);
+  app.mount("/docs", docsApp);
 });
 
-app.serve({ port: 3000 });
+serve(app, { port: 3000 });
 ```
 
-You can also create and return a new H3 instance to customize H3 options:
+When an app is mounted, its middlewares and routes are copied to the main app in place with middlewares scoped to the base path.
+
+Both `application()` and `controller()` can return a custom H3 instance:
 
 ```typescript
 import { H3 } from "h3";
 
-const app = application(() => {
-  const customApp = new H3({
-    onError: (error) => {
-      console.error(error);
+const customApp = application(() => {
+  const app = new H3({
+    onError: (error, event) => {
+      console.error("Error:", error);
     },
   });
-  customApp.get("/", () => "Hello from custom app!");
-  return customApp;
+  app.get("/", () => "Hello from custom app!");
+  return app;
 });
 ```
 
-## Controllers with Dependency Injection
+## Controllers
 
-Use `controller()` to create reusable modules with shared dependencies. It integrates with [getbox](https://github.com/eriicafes/getbox) for dependency injection:
+Controllers are apps that are initialized with a parent Box instance, sharing the same dependency container. Use `controller()` to create H3 app constructors:
 
 ```typescript
 import { application, controller } from "serverstruct";
 
-// Define a controller
-const usersController = controller((app) => {
-  const users: User[] = [];
+class UserStore {
+  public users: User[] = [];
 
-  app.get("/", () => users);
+  add(user: User) {
+    this.users.push(user);
+    return user;
+  }
+}
+
+// Create a controller
+const usersController = controller((app, box) => {
+  const store = box.get(UserStore);
+
+  app.get("/", () => store.users);
   app.post("/", async (event) => {
-    const body = await readValidatedBody(event, validateUser);
-    users.push(body);
-    return body;
+    const body = await readBody(event);
+    return store.add(body);
   });
 });
 
 // Use it in your main app
 const app = application((app, box) => {
-  app.get("/ping", () => "pong");
+  const store = box.get(UserStore);
+
+  app.get("/count", () => ({
+    users: store.users.length,
+  }));
   app.mount("/users", box.new(usersController));
 });
 
-app.serve({ port: 3000 });
+serve(app, { 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:
+// Define a handler
+const getUserHandler = handler((event, box) => {
+  const store = box.get(UserStore);
+
+  const id = event.context.params?.id;
+  return store.users.find((user) => user.id === id);
+});
+
+// Use it in your app
+const app = application((app, box) => {
+  app.get("/users/:id", box.new(getUserHandler));
+});
+```
+
+### Event Handlers
+
+Use `eventHandler()` to create H3 handler constructors with additional options like meta and middleware:
 
 ```typescript
-import { application, controller } from "serverstruct";
+import { application, eventHandler } from "serverstruct";
+
+// Define an event handler with additional options
+const getUserHandler = eventHandler((box) => ({
+  handler(event) {
+    const store = box.get(UserStore);
+
+    const id = event.context.params?.id;
+    return store.users.find((user) => user.id === id);
+  },
+  meta: { auth: true },
+  middleware: [],
+}));
+
+// Use it in your app
+const app = application((app, box) => {
+  app.get("/users/:id", box.new(getUserHandler));
+});
+```
+
+## Middleware
+
+Use `middleware()` to create H3 middleware constructors:
 
-// A shared service
-class Database {
-  users: User[] = [];
+```typescript
+import { application, middleware } from "serverstruct";
 
-  getUsers() { return this.users; }
-  addUser(user: User) { this.users.push(user); }
+class Logger {
+  log(message: string) {
+    console.log(message);
+  }
 }
 
-// Controller uses box to access the database
-const usersController = controller((app, box) => {
-  const db = box.get(Database);
+// Define a middleware
+const logMiddleware = middleware((event, next, box) => {
+  const logger = box.get(Logger);
+  logger.log("Request received");
+});
 
-  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.use(box.get(logMiddleware));
+  app.get("/", () => "Hello world!");
+});
+```
+
+All middlewares defined with `app.use()` are global and execute before the matched handler in the exact order they are defined.
+
+## Error Handling
+
+Error handlers are middleware that catch errors after calling `await next()`.
+
+The last error handler defined executes before earlier ones. The error bubbles through each error handler until a response is returned or the default error response is sent.
+
+Use H3's `onError` helper to define error handlers:
+
+```typescript
+import { onError } from "h3";
+import { application } from "serverstruct";
+
+const app = application((app) => {
+  app.use(
+    onError((error) => {
+      console.log("Error:", error);
+    }),
+  );
+  app.get("/", () => {
+    throw new Error("Oops");
   });
 });
+```
+
+When the error handler needs access to the Box, wrap it with `middleware()`:
 
-// Another controller can access the same database
-const statsController = controller((app, box) => {
-  const db = box.get(Database);
+```typescript
+import { onError } from "h3";
+import { application, middleware } from "serverstruct";
 
-  app.get("/count", () => ({ count: db.getUsers().length }));
+const errorHandler = middleware((event, next, box) => {
+  return onError((error) => {
+    console.log("Error:", error);
+  });
 });
 
 const app = application((app, box) => {
-  app.mount("/users", box.new(usersController));
-  app.mount("/stats", box.new(statsController));
+  app.use(box.get(errorHandler));
+  app.get("/", () => {
+    throw new Error("Oops");
+  });
 });
-
-await app.serve({ port: 3000 });
 ```
 
-`box.get(Class)` creates the instance on first call, then caches it.
-
-## Middleware
+### Not Found Routes
 
-Use h3's native middleware with `app.use()`:
+To catch not found routes, define a catch-all handler and return the desired error:
 
 ```typescript
-const app = application((app) => {
-  // Global middleware
-  app.use(() => console.log("Request received"));
+import { H3Error } from "h3";
 
+const app = application((app) => {
   app.get("/", () => "Hello world!");
+  app.all("**", () => new H3Error({ status: 404, message: "Not found" }));
 });
 ```
 
-Controllers can have their own middleware:
+Mounted apps can define their own not found handlers:
 
 ```typescript
-const usersController = controller((app) => {
-  // Runs only for routes in this controller
-  app.use(() => console.log("Users route accessed"));
+const usersApp = application((app) => {
+  app.get("/", () => ["Alice", "Bob"]);
+  app.all(
+    "**",
+    () => new H3Error({ status: 404, message: "User route not found" }),
+  );
+});
 
-  app.get("/", () => [...]);
-  app.post("/", async () => {...});
+const app = application((app) => {
+  app.mount("/users", usersApp);
+  app.all("**", () => new H3Error({ status: 404, message: "Not found" }));
 });
 ```
 
-## Custom Box Instance
+## Box Instance
 
-Pass your own Box instance to `application()` for more control:
+By default, `application()` creates a new Box instance. Pass a Box instance to reuse it:
 
 ```typescript
 import { Box } from "getbox";
+import { application, serve } from "serverstruct";
 
 const box = new Box();
 
-// Pre-populate with dependencies
-Box.mock(box, Database, new Database());
+const usersApp = application((app, box) => {
+  const store = box.get(UserStore);
+  app.get("/", () => store.users);
+}, box);
 
 const app = application((app, box) => {
-  app.mount("/users", box.new(usersController));
+  const store = box.get(UserStore);
+  app.get("/count", () => store.users.length);
+  app.mount("/users", usersApp);
 }, box);
+
+serve(app, { port: 3000 });
+```
+
+## Context
+
+`context()` creates a request-scoped, type-safe store for per-request values.
+
+```typescript
+import { application, context } from "serverstruct";
+
+interface User {
+  id: string;
+  name: string;
+}
+
+// Create a context store
+const userContext = context<User>();
+
+const app = application((app) => {
+  // Set context in middleware
+  app.use((event) => {
+    const user = { id: "123", name: "Alice" };
+    userContext.set(event, user);
+  });
+
+  // Access context in handlers
+  app.get("/profile", (event) => {
+    // Optional access - returns undefined if not set
+    const maybeUser = userContext.lookup(event);
+
+    // Safe access - throws if not set
+    const user = userContext.get(event);
+
+    return { profile: user };
+  });
+});
 ```
+
+### 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

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;