serverstruct 1.0.0 → 1.2.0

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/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;