serverstruct 1.0.0 → 1.2.0

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