serverstruct 1.1.0 → 1.2.0

package/dist/openapi.d.cts

@@ -0,0 +1,241 @@
+import { EventHandlerResponse, H3, H3Event, RouteOptions } from "h3";
+import { output } from "zod";
+import { CreateDocumentOptions, ZodOpenApiMediaTypeObject, ZodOpenApiMetadata, ZodOpenApiMetadata as ZodOpenApiMetadata$1, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, createDocument } from "zod-openapi";
+
+//#region src/openapi.d.ts
+/** Infer the Zod output type from `requestBody.content["application/json"].schema`. */
+type InferBody<T> = T extends {
+  requestBody: {
+    content: {
+      "application/json": {
+        schema: infer S;
+      };
+    };
+  };
+} ? output<S> : unknown;
+/** Infer the Zod output type from `requestParams.path`. */
+type InferParams<T> = T extends {
+  requestParams: {
+    path: infer S;
+  };
+} ? output<S> : Record<string, string>;
+/** Infer the Zod output type from `requestParams.query`. */
+type InferQuery<T> = T extends {
+  requestParams: {
+    query: infer S;
+  };
+} ? output<S> : Record<string, string>;
+/** Resolve a response object from `responses` by numeric status code, handling both numeric and string keys. */
+type LookupResponseByStatus<R$1, Status extends number> = Status extends keyof R$1 ? R$1[Status] : `${Status}` extends keyof R$1 ? R$1[`${Status}`] : never;
+/** Infer the Zod output type from `responses[status].content["application/json"].schema`. */
+type InferResponse<T, Status extends number> = T extends {
+  responses: infer R;
+} ? LookupResponseByStatus<R, Status> extends {
+  content: {
+    "application/json": {
+      schema: infer S;
+    };
+  };
+} ? output<S> : unknown : unknown;
+/** Infer the Zod output type from `responses[status].headers`. Falls back to `Record<string, string>` when no headers schema is defined. */
+type InferResponseHeaders<T, Status extends number> = T extends {
+  responses: infer R;
+} ? LookupResponseByStatus<R, Status> extends {
+  headers: infer H;
+} ? output<H> : Record<string, string> : Record<string, string>;
+/** Extract the raw Zod schema from `requestBody.content["application/json"].schema`, or `undefined` if absent. */
+type ExtractBodySchema<T> = T extends {
+  requestBody: {
+    content: {
+      "application/json": {
+        schema: infer S;
+      };
+    };
+  };
+} ? S extends {
+  _zod: any;
+} ? S : undefined : undefined;
+/** Extract the raw Zod schema from `requestParams.path`, or `undefined` if absent. */
+type ExtractParamsSchema<T> = T extends {
+  requestParams: {
+    path: infer S;
+  };
+} ? S extends {
+  _zod: any;
+} ? S : undefined : undefined;
+/** Extract the raw Zod schema from `requestParams.query`, or `undefined` if absent. */
+type ExtractQuerySchema<T> = T extends {
+  requestParams: {
+    query: infer S;
+  };
+} ? S extends {
+  _zod: any;
+} ? S : undefined : undefined;
+/** Extract the raw Zod schema from `requestParams.header`, or `undefined` if absent. */
+type ExtractHeadersSchema<T> = T extends {
+  requestParams: {
+    header: infer S;
+  };
+} ? S extends {
+  _zod: any;
+} ? S : undefined : undefined;
+/** Extract numeric status codes from `responses`, normalizing string keys like `"200"` to `200`. */
+type ResponseStatusKeys<T> = T extends {
+  responses: infer R;
+} ? keyof R extends infer K ? K extends number ? K : K extends `${infer N extends number}` ? N : never : never : never;
+/**
+ * Typed context returned from operation registration.
+ *
+ * Provides access to raw Zod schemas for manual validation and
+ * convenience methods for extracting validated request data.
+ *
+ * - `schemas` — raw Zod schemas for use with h3 validation utilities (e.g. `getValidatedRouterParams`)
+ * - `params()` — validates and returns route parameters
+ * - `query()` — validates and returns query string parameters
+ * - `body()` — validates and returns the JSON request body
+ * - `reply()` — sets the response status, optional headers, and returns typed response data
+ */
+type RouterContext<T extends ZodOpenApiOperationObject = ZodOpenApiOperationObject> = {
+  schemas: {
+    params: ExtractParamsSchema<T>;
+    query: ExtractQuerySchema<T>;
+    headers: ExtractHeadersSchema<T>;
+    body: ExtractBodySchema<T>;
+  };
+  params(event: H3Event): Promise<InferParams<T>>;
+  query(event: H3Event): Promise<InferQuery<T>>;
+  body(event: H3Event): Promise<InferBody<T>>;
+  reply<S$1 extends ResponseStatusKeys<T>>(event: H3Event, status: S$1, data: InferResponse<T, S$1>, headers?: InferResponseHeaders<T, S$1>): InferResponse<T, S$1>;
+};
+declare const HTTP_METHODS: readonly ["get", "post", "put", "delete", "patch"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+/**
+ * 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 });
+ * ```
+ */
+declare class OpenApiPaths {
+  paths: ZodOpenApiPathsObject;
+  get<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  post<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  put<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  delete<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  patch<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  /** Register an operation for all standard HTTP methods (get, post, put, delete, patch). */
+  all<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  /** Register an operation for specific HTTP methods. */
+  on<T extends ZodOpenApiOperationObject>(methods: readonly HttpMethod[], path: string, operation: T): RouterContext<T>;
+  private register;
+}
+/**
+ * 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" });
+ * });
+ * ```
+ */
+declare class OpenApiRouter {
+  protected app: H3;
+  protected paths: OpenApiPaths;
+  constructor(app: H3, paths: OpenApiPaths);
+  get<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  post<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  put<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  delete<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  patch<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  /** Register a route and operation for all standard HTTP methods. */
+  all<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  /** Register a route and operation for specific HTTP methods. */
+  on<T extends ZodOpenApiOperationObject>(methods: readonly HttpMethod[], path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+}
+/** Create an {@link OpenApiRouter} that combines H3 route registration with OpenAPI path collection. */
+declare function createRouter(app: H3, paths: OpenApiPaths): OpenApiRouter;
+type Pretty<T> = { [K in keyof T]: T[K] } & {};
+type Merge<T, U> = Omit<T, keyof U> & U;
+type PrettyOmit<T, U extends keyof any> = Pretty<Omit<T, U>>;
+type PrettyMerge<T, U> = Pretty<Merge<T, U>>;
+/** Builder for OpenAPI metadata passed to `.meta()` on Zod schemas. */
+declare const metadata: (meta: ZodOpenApiMetadata$1) => ZodOpenApiMetadata$1;
+/**
+ * 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" } } })
+ * ```
+ */
+declare function jsonRequest<S$1 extends {
+  _zod: any;
+}, O extends PrettyMerge<ZodOpenApiRequestBodyObject, {
+  content?: PrettyOmit<ZodOpenApiMediaTypeObject, "schema">;
+}>>(schema: S$1, opts?: O): PrettyMerge<ZodOpenApiRequestBodyObject, {
+  content: {
+    "application/json": PrettyMerge<{
+      schema: S$1;
+    }, O["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({}),
+ * })
+ * ```
+ */
+declare function jsonResponse<S$1 extends {
+  _zod: any;
+}, H$1 extends {
+  _zod: any;
+} | undefined, O extends PrettyMerge<ZodOpenApiResponseObject, {
+  content?: PrettyOmit<ZodOpenApiMediaTypeObject, "schema">;
+  headers?: H$1;
+}>>(schema: S$1, opts: O): PrettyMerge<ZodOpenApiResponseObject, {
+  content: {
+    "application/json": PrettyMerge<{
+      schema: S$1;
+    }, O["content"]>;
+  };
+  headers: O["headers"];
+}>;
+//#endregion
+export { type CreateDocumentOptions, OpenApiPaths, OpenApiRouter, RouterContext, type ZodOpenApiMetadata, type ZodOpenApiObject, createDocument, createRouter, jsonRequest, jsonResponse, metadata };

package/dist/openapi.d.mts

@@ -0,0 +1,241 @@
+import { EventHandlerResponse, H3, H3Event, RouteOptions } from "h3";
+import { CreateDocumentOptions, ZodOpenApiMediaTypeObject, ZodOpenApiMetadata, ZodOpenApiMetadata as ZodOpenApiMetadata$1, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, createDocument } from "zod-openapi";
+import { output } from "zod";
+
+//#region src/openapi.d.ts
+/** Infer the Zod output type from `requestBody.content["application/json"].schema`. */
+type InferBody<T> = T extends {
+  requestBody: {
+    content: {
+      "application/json": {
+        schema: infer S;
+      };
+    };
+  };
+} ? output<S> : unknown;
+/** Infer the Zod output type from `requestParams.path`. */
+type InferParams<T> = T extends {
+  requestParams: {
+    path: infer S;
+  };
+} ? output<S> : Record<string, string>;
+/** Infer the Zod output type from `requestParams.query`. */
+type InferQuery<T> = T extends {
+  requestParams: {
+    query: infer S;
+  };
+} ? output<S> : Record<string, string>;
+/** Resolve a response object from `responses` by numeric status code, handling both numeric and string keys. */
+type LookupResponseByStatus<R$1, Status extends number> = Status extends keyof R$1 ? R$1[Status] : `${Status}` extends keyof R$1 ? R$1[`${Status}`] : never;
+/** Infer the Zod output type from `responses[status].content["application/json"].schema`. */
+type InferResponse<T, Status extends number> = T extends {
+  responses: infer R;
+} ? LookupResponseByStatus<R, Status> extends {
+  content: {
+    "application/json": {
+      schema: infer S;
+    };
+  };
+} ? output<S> : unknown : unknown;
+/** Infer the Zod output type from `responses[status].headers`. Falls back to `Record<string, string>` when no headers schema is defined. */
+type InferResponseHeaders<T, Status extends number> = T extends {
+  responses: infer R;
+} ? LookupResponseByStatus<R, Status> extends {
+  headers: infer H;
+} ? output<H> : Record<string, string> : Record<string, string>;
+/** Extract the raw Zod schema from `requestBody.content["application/json"].schema`, or `undefined` if absent. */
+type ExtractBodySchema<T> = T extends {
+  requestBody: {
+    content: {
+      "application/json": {
+        schema: infer S;
+      };
+    };
+  };
+} ? S extends {
+  _zod: any;
+} ? S : undefined : undefined;
+/** Extract the raw Zod schema from `requestParams.path`, or `undefined` if absent. */
+type ExtractParamsSchema<T> = T extends {
+  requestParams: {
+    path: infer S;
+  };
+} ? S extends {
+  _zod: any;
+} ? S : undefined : undefined;
+/** Extract the raw Zod schema from `requestParams.query`, or `undefined` if absent. */
+type ExtractQuerySchema<T> = T extends {
+  requestParams: {
+    query: infer S;
+  };
+} ? S extends {
+  _zod: any;
+} ? S : undefined : undefined;
+/** Extract the raw Zod schema from `requestParams.header`, or `undefined` if absent. */
+type ExtractHeadersSchema<T> = T extends {
+  requestParams: {
+    header: infer S;
+  };
+} ? S extends {
+  _zod: any;
+} ? S : undefined : undefined;
+/** Extract numeric status codes from `responses`, normalizing string keys like `"200"` to `200`. */
+type ResponseStatusKeys<T> = T extends {
+  responses: infer R;
+} ? keyof R extends infer K ? K extends number ? K : K extends `${infer N extends number}` ? N : never : never : never;
+/**
+ * Typed context returned from operation registration.
+ *
+ * Provides access to raw Zod schemas for manual validation and
+ * convenience methods for extracting validated request data.
+ *
+ * - `schemas` — raw Zod schemas for use with h3 validation utilities (e.g. `getValidatedRouterParams`)
+ * - `params()` — validates and returns route parameters
+ * - `query()` — validates and returns query string parameters
+ * - `body()` — validates and returns the JSON request body
+ * - `reply()` — sets the response status, optional headers, and returns typed response data
+ */
+type RouterContext<T extends ZodOpenApiOperationObject = ZodOpenApiOperationObject> = {
+  schemas: {
+    params: ExtractParamsSchema<T>;
+    query: ExtractQuerySchema<T>;
+    headers: ExtractHeadersSchema<T>;
+    body: ExtractBodySchema<T>;
+  };
+  params(event: H3Event): Promise<InferParams<T>>;
+  query(event: H3Event): Promise<InferQuery<T>>;
+  body(event: H3Event): Promise<InferBody<T>>;
+  reply<S$1 extends ResponseStatusKeys<T>>(event: H3Event, status: S$1, data: InferResponse<T, S$1>, headers?: InferResponseHeaders<T, S$1>): InferResponse<T, S$1>;
+};
+declare const HTTP_METHODS: readonly ["get", "post", "put", "delete", "patch"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+/**
+ * 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 });
+ * ```
+ */
+declare class OpenApiPaths {
+  paths: ZodOpenApiPathsObject;
+  get<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  post<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  put<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  delete<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  patch<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  /** Register an operation for all standard HTTP methods (get, post, put, delete, patch). */
+  all<T extends ZodOpenApiOperationObject>(path: string, operation: T): RouterContext<T>;
+  /** Register an operation for specific HTTP methods. */
+  on<T extends ZodOpenApiOperationObject>(methods: readonly HttpMethod[], path: string, operation: T): RouterContext<T>;
+  private register;
+}
+/**
+ * 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" });
+ * });
+ * ```
+ */
+declare class OpenApiRouter {
+  protected app: H3;
+  protected paths: OpenApiPaths;
+  constructor(app: H3, paths: OpenApiPaths);
+  get<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  post<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  put<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  delete<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  patch<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  /** Register a route and operation for all standard HTTP methods. */
+  all<T extends ZodOpenApiOperationObject>(path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+  /** Register a route and operation for specific HTTP methods. */
+  on<T extends ZodOpenApiOperationObject>(methods: readonly HttpMethod[], path: string, operation: T, handler: (event: H3Event, ctx: RouterContext<T>) => EventHandlerResponse, opts?: RouteOptions): this;
+}
+/** Create an {@link OpenApiRouter} that combines H3 route registration with OpenAPI path collection. */
+declare function createRouter(app: H3, paths: OpenApiPaths): OpenApiRouter;
+type Pretty<T> = { [K in keyof T]: T[K] } & {};
+type Merge<T, U> = Omit<T, keyof U> & U;
+type PrettyOmit<T, U extends keyof any> = Pretty<Omit<T, U>>;
+type PrettyMerge<T, U> = Pretty<Merge<T, U>>;
+/** Builder for OpenAPI metadata passed to `.meta()` on Zod schemas. */
+declare const metadata: (meta: ZodOpenApiMetadata$1) => ZodOpenApiMetadata$1;
+/**
+ * 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" } } })
+ * ```
+ */
+declare function jsonRequest<S$1 extends {
+  _zod: any;
+}, O extends PrettyMerge<ZodOpenApiRequestBodyObject, {
+  content?: PrettyOmit<ZodOpenApiMediaTypeObject, "schema">;
+}>>(schema: S$1, opts?: O): PrettyMerge<ZodOpenApiRequestBodyObject, {
+  content: {
+    "application/json": PrettyMerge<{
+      schema: S$1;
+    }, O["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({}),
+ * })
+ * ```
+ */
+declare function jsonResponse<S$1 extends {
+  _zod: any;
+}, H$1 extends {
+  _zod: any;
+} | undefined, O extends PrettyMerge<ZodOpenApiResponseObject, {
+  content?: PrettyOmit<ZodOpenApiMediaTypeObject, "schema">;
+  headers?: H$1;
+}>>(schema: S$1, opts: O): PrettyMerge<ZodOpenApiResponseObject, {
+  content: {
+    "application/json": PrettyMerge<{
+      schema: S$1;
+    }, O["content"]>;
+  };
+  headers: O["headers"];
+}>;
+//#endregion
+export { type CreateDocumentOptions, OpenApiPaths, OpenApiRouter, RouterContext, type ZodOpenApiMetadata, type ZodOpenApiObject, createDocument, createRouter, jsonRequest, jsonResponse, metadata };