serverstruct 1.1.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,170 +18,151 @@ 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 });
 ```
 
-## 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;
-});
-```
-
-### Accessing the Box Instance
-
-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!");
+  app.get("/", () => "Hello from custom app!");
+  return app;
 });
-
-const port = box.get(Port);
-serve({ port });
 ```
 
 ## Controllers
 
-Use `controller()` to create h3 app constructors:
+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[] = [];
+
+  add(user: User) {
+    this.users.push(user);
+    return user;
+  }
+}
+
+// Create a controller
+const usersController = controller((app, box) => {
+  const store = box.get(UserStore);
 
-  app.get("/", () => users);
+  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 });
 ```
 
 ## Handlers
 
-Use `handler()` to create h3 handler constructors:
+Use `handler()` to create H3 handler constructors:
 
 ```typescript
 import { application, handler } from "serverstruct";
 
-class UserService {
-  getUser(id: string) {
-    return { id, name: "Alice" };
-  }
-}
-
 // Define a handler
 const getUserHandler = handler((event, box) => {
-  const userService = box.get(UserService);
+  const store = box.get(UserStore);
+
   const id = event.context.params?.id;
-  return userService.getUser(id);
+  return store.users.find((user) => user.id === id);
 });
 
 // Use it in your app
 const app = application((app, box) => {
-  app.get("/users/:id", box.get(getUserHandler));
+  app.get("/users/:id", box.new(getUserHandler));
 });
 ```
 
 ### Event Handlers
 
-Use `eventHandler()` to create h3 handlers with additional options like metadata and middleware:
+Use `eventHandler()` to create H3 handler constructors with additional options like meta and middleware:
 
 ```typescript
 import { application, eventHandler } from "serverstruct";
 
-class UserService {
-  getUser(id: string) {
-    return { id, name: "Alice" };
-  }
-}
-
-// Define an event handler with middleware and metadata
+// Define an event handler with additional options
 const getUserHandler = eventHandler((box) => ({
   handler(event) {
-    const userService = box.get(UserService);
+    const store = box.get(UserStore);
+
     const id = event.context.params?.id;
-    return userService.getUser(id);
+    return store.users.find((user) => user.id === id);
   },
   meta: { auth: true },
-  middleware: [
-    (event) => {
-      const token = event.headers.get("authorization");
-      if (!token || token !== "secret-token") {
-        throw new Error("Unauthorized");
-      }
-    },
-  ],
+  middleware: [],
 }));
 
 // Use it in your app
 const app = application((app, box) => {
-  app.get("/users/:id", box.get(getUserHandler));
+  app.get("/users/:id", box.new(getUserHandler));
 });
 ```
 
 ## Middleware
 
-Use `middleware()` to create h3 middleware constructors:
+Use `middleware()` to create H3 middleware constructors:
 
 ```typescript
 import { application, middleware } from "serverstruct";
@@ -200,75 +186,143 @@ const app = application((app, box) => {
 });
 ```
 
-## Context
+All middlewares defined with `app.use()` are global and execute before the matched handler in the exact order they are defined.
 
-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.
+## Error Handling
 
-```typescript
-import { application, context } from "serverstruct";
+Error handlers are middleware that catch errors after calling `await next()`.
 
-interface User {
-  id: string;
-  name: string;
-}
+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.
 
-// Create a context store
-const userContext = context<User>();
+Use H3's `onError` helper to define error handlers:
+
+```typescript
+import { onError } from "h3";
+import { application } from "serverstruct";
 
 const app = application((app) => {
-  // Set context in middleware
-  app.use((event) => {
-    const user = { id: "123", name: "Alice" };
-    userContext.set(event, user);
+  app.use(
+    onError((error) => {
+      console.log("Error:", error);
+    }),
+  );
+  app.get("/", () => {
+    throw new Error("Oops");
   });
+});
+```
 
-  // Access context in handlers
-  app.get("/profile", (event) => {
-    const user = userContext.get(event);
-    return { profile: user };
+When the error handler needs access to the Box, wrap it with `middleware()`:
+
+```typescript
+import { onError } from "h3";
+import { application, middleware } from "serverstruct";
+
+const errorHandler = middleware((event, next, box) => {
+  return onError((error) => {
+    console.log("Error:", error);
+  });
+});
+
+const app = application((app, box) => {
+  app.use(box.get(errorHandler));
+  app.get("/", () => {
+    throw new Error("Oops");
   });
 });
 ```
 
-### Context Methods
+### Not Found Routes
 
-- `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
+To catch not found routes, define a catch-all handler and return the desired error:
 
 ```typescript
-const requestIdContext = context<string>();
+import { H3Error } from "h3";
 
 const app = application((app) => {
-  app.use((event) => {
-    requestIdContext.set(event, crypto.randomUUID());
-  });
+  app.get("/", () => "Hello world!");
+  app.all("**", () => new H3Error({ status: 404, message: "Not found" }));
+});
+```
 
-  app.get("/", (event) => {
-    // Safe access - throws if not set
-    const id = requestIdContext.get(event);
+Mounted apps can define their own not found handlers:
 
-    // Optional access - returns undefined if not set
-    const maybeId = requestIdContext.lookup(event);
+```typescript
+const usersApp = application((app) => {
+  app.get("/", () => ["Alice", "Bob"]);
+  app.all(
+    "**",
+    () => new H3Error({ status: 404, message: "User route not found" }),
+  );
+});
 
-    return { requestId: id };
-  });
+const app = application((app) => {
+  app.mount("/users", usersApp);
+  app.all("**", () => new H3Error({ status: 404, message: "Not found" }));
 });
 ```
 
-## Custom Box Instance
+## Box Instance
 
-You can also pass your own Box instance to share dependencies across multiple applications or mock dependencies:
+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();
 
-// Mock a dependency
-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/openapi.cjs

@@ -0,0 +1,242 @@
+let h3 = require("h3");
+let zod_openapi_api = require("zod-openapi/api");
+let zod_openapi = require("zod-openapi");
+
+//#region src/openapi.ts
+function createContext(operation) {
+	const paramsSchema = operation.requestParams?.path;
+	const querySchema = operation.requestParams?.query;
+	const headersSchema = operation.requestParams?.header;
+	const bodyRawSchema = operation.requestBody?.content?.["application/json"]?.schema;
+	const bodySchema = (0, zod_openapi_api.isAnyZodType)(bodyRawSchema) ? bodyRawSchema : void 0;
+	return {
+		schemas: {
+			params: paramsSchema,
+			query: querySchema,
+			headers: headersSchema,
+			body: bodySchema
+		},
+		params: (event) => paramsSchema ? (0, h3.getValidatedRouterParams)(event, paramsSchema) : Promise.resolve((0, h3.getRouterParams)(event)),
+		query: (event) => querySchema ? (0, h3.getValidatedQuery)(event, querySchema) : Promise.resolve((0, h3.getQuery)(event)),
+		body: (event) => bodySchema ? (0, h3.readValidatedBody)(event, bodySchema) : (0, h3.readBody)(event),
+		reply: (event, status, data, headers) => {
+			event.res.status = status;
+			if (headers) for (const [key, value] of Object.entries(headers)) event.res.headers.set(key, String(value));
+			return data;
+		}
+	};
+}
+const HTTP_METHODS = [
+	"get",
+	"post",
+	"put",
+	"delete",
+	"patch"
+];
+/**
+* Collects OpenAPI operation definitions for document generation.
+*
+* Register operations by HTTP method and path. The accumulated `paths`
+* object can be passed to `createDocument()` to generate the OpenAPI spec.
+*
+* Each registration returns a typed {@link RouterContext} for use in route handlers.
+*
+* @example
+* ```ts
+* // Singleton via getbox DI
+* const paths = box.get(OpenApiPaths);
+*
+* const getPost = paths.get("/posts/{id}", { ... });
+*
+* // Generate OpenAPI document
+* createDocument({ openapi: "3.1.0", info: { ... }, paths: paths.paths });
+* ```
+*/
+var OpenApiPaths = class {
+	paths = {};
+	get(path, operation) {
+		return this.register(path, "get", operation);
+	}
+	post(path, operation) {
+		return this.register(path, "post", operation);
+	}
+	put(path, operation) {
+		return this.register(path, "put", operation);
+	}
+	delete(path, operation) {
+		return this.register(path, "delete", operation);
+	}
+	patch(path, operation) {
+		return this.register(path, "patch", operation);
+	}
+	/** Register an operation for all standard HTTP methods (get, post, put, delete, patch). */
+	all(path, operation) {
+		return this.on(HTTP_METHODS, path, operation);
+	}
+	/** Register an operation for specific HTTP methods. */
+	on(methods, path, operation) {
+		const item = {};
+		for (const method of methods) item[method] = operation;
+		this.paths[path] = {
+			...this.paths[path],
+			...item
+		};
+		return createContext(operation);
+	}
+	register(path, method, operation) {
+		this.paths[path] = {
+			...this.paths[path],
+			[method]: operation
+		};
+		return createContext(operation);
+	}
+};
+/**
+* Combines OpenAPI path registration with H3 route registration.
+*
+* Each method registers the operation in {@link OpenApiPaths} (converting the
+* H3 path syntax to OpenAPI format) and simultaneously registers the route
+* handler on the H3 app. The handler receives the typed {@link RouterContext}.
+*
+* @example
+* ```ts
+* const router = createRouter(app, box.get(OpenApiPaths));
+*
+* router.get("/posts/:id", {
+*   operationId: "getPost",
+*   requestBody: jsonRequest(inputSchema),
+*   responses: {
+*     200: jsonResponse(outputSchema, { description: "Success" }),
+*   },
+* }, async (event, ctx) => {
+*   const body = await ctx.body(event);
+*   return ctx.reply(event, 200, { message: "ok" });
+* });
+* ```
+*/
+var OpenApiRouter = class {
+	constructor(app, paths) {
+		this.app = app;
+		this.paths = paths;
+	}
+	get(path, operation, handler, opts) {
+		const ctx = this.paths.get(toOpenApiPath(path), operation);
+		this.app.get(path, (event) => handler(event, ctx), opts);
+		return this;
+	}
+	post(path, operation, handler, opts) {
+		const ctx = this.paths.post(toOpenApiPath(path), operation);
+		this.app.post(path, (event) => handler(event, ctx), opts);
+		return this;
+	}
+	put(path, operation, handler, opts) {
+		const ctx = this.paths.put(toOpenApiPath(path), operation);
+		this.app.put(path, (event) => handler(event, ctx), opts);
+		return this;
+	}
+	delete(path, operation, handler, opts) {
+		const ctx = this.paths.delete(toOpenApiPath(path), operation);
+		this.app.delete(path, (event) => handler(event, ctx), opts);
+		return this;
+	}
+	patch(path, operation, handler, opts) {
+		const ctx = this.paths.patch(toOpenApiPath(path), operation);
+		this.app.patch(path, (event) => handler(event, ctx), opts);
+		return this;
+	}
+	/** Register a route and operation for all standard HTTP methods. */
+	all(path, operation, handler, opts) {
+		const ctx = this.paths.all(toOpenApiPath(path), operation);
+		this.app.all(path, (event) => handler(event, ctx), opts);
+		return this;
+	}
+	/** Register a route and operation for specific HTTP methods. */
+	on(methods, path, operation, handler, opts) {
+		const ctx = this.paths.on(methods, toOpenApiPath(path), operation);
+		for (const method of methods) this.app.on(method, path, (event) => handler(event, ctx), opts);
+		return this;
+	}
+};
+/** Create an {@link OpenApiRouter} that combines H3 route registration with OpenAPI path collection. */
+function createRouter(app, paths) {
+	return new OpenApiRouter(app, paths);
+}
+/** Builder for OpenAPI metadata passed to `.meta()` on Zod schemas. */
+const metadata = (meta) => meta;
+/**
+* Build a typed `requestBody` object with `application/json` content.
+*
+* Additional media type options (e.g. `example`) can be passed via `opts.content`.
+*
+* @example
+* ```ts
+* jsonRequest(inputSchema)
+* jsonRequest(inputSchema, { description: "Create a post", content: { example: { title: "Hello" } } })
+* ```
+*/
+function jsonRequest(schema, opts) {
+	const { content, ...rest } = opts || {};
+	return {
+		required: true,
+		...rest,
+		content: { "application/json": {
+			schema,
+			...content
+		} }
+	};
+}
+/**
+* Build a typed response object with `application/json` content.
+*
+* Additional media type options (e.g. `example`) can be passed via `opts.content`.
+*
+* @example
+* ```ts
+* jsonResponse(outputSchema, { description: "Success" })
+* jsonResponse(outputSchema, {
+*   description: "Success",
+*   headers: z.object({ "x-request-id": z.string() }).meta({}),
+* })
+* ```
+*/
+function jsonResponse(schema, opts) {
+	const { content, headers, ...rest } = opts;
+	return {
+		...rest,
+		headers,
+		content: { "application/json": {
+			schema,
+			...content
+		} }
+	};
+}
+/**
+* Convert H3 path syntax to OpenAPI path syntax.
+*
+* - `/:name` → `/{name}`
+* - `/*`     → `/{param}`
+* - `/**`    → `/{path}`
+*/
+function toOpenApiPath(route) {
+	if (!route.startsWith("/")) route = "/" + route;
+	return route.split("/").map((segment) => {
+		if (segment.startsWith(":")) return `{${segment.slice(1)}}`;
+		else if (segment === "*") return "{param}";
+		else if (segment === "**") return "{path}";
+		else return segment;
+	}).join("/");
+}
+
+//#endregion
+exports.OpenApiPaths = OpenApiPaths;
+exports.OpenApiRouter = OpenApiRouter;
+Object.defineProperty(exports, 'createDocument', {
+  enumerable: true,
+  get: function () {
+    return zod_openapi.createDocument;
+  }
+});
+exports.createRouter = createRouter;
+exports.jsonRequest = jsonRequest;
+exports.jsonResponse = jsonResponse;
+exports.metadata = metadata;