serverstruct 1.0.0 → 1.2.0

package/dist/openapi.mjs

@@ -0,0 +1,231 @@
+import { getQuery, getRouterParams, getValidatedQuery, getValidatedRouterParams, readBody, readValidatedBody } from "h3";
+import { isAnyZodType } from "zod-openapi/api";
+import { createDocument } from "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 = isAnyZodType(bodyRawSchema) ? bodyRawSchema : void 0;
+	return {
+		schemas: {
+			params: paramsSchema,
+			query: querySchema,
+			headers: headersSchema,
+			body: bodySchema
+		},
+		params: (event) => paramsSchema ? getValidatedRouterParams(event, paramsSchema) : Promise.resolve(getRouterParams(event)),
+		query: (event) => querySchema ? getValidatedQuery(event, querySchema) : Promise.resolve(getQuery(event)),
+		body: (event) => bodySchema ? readValidatedBody(event, bodySchema) : 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
+export { OpenApiPaths, OpenApiRouter, createDocument, createRouter, jsonRequest, jsonResponse, metadata };

package/dist/openapi.scalar.cjs

@@ -0,0 +1,13 @@
+let h3 = require("h3");
+let _scalar_core_libs_html_rendering = require("@scalar/core/libs/html-rendering");
+
+//#region src/openapi.scalar.ts
+function apiReference(configuration, customTheme) {
+	return (0, h3.html)((0, _scalar_core_libs_html_rendering.getHtmlDocument)({
+		_integration: "serverstruct",
+		...configuration
+	}, customTheme));
+}
+
+//#endregion
+exports.apiReference = apiReference;

package/dist/openapi.scalar.d.cts

@@ -0,0 +1,8 @@
+import * as h30 from "h3";
+import { HtmlRenderingConfiguration } from "@scalar/core/libs/html-rendering";
+
+//#region src/openapi.scalar.d.ts
+type ApiReferenceConfiguration = Partial<HtmlRenderingConfiguration>;
+declare function apiReference(configuration: ApiReferenceConfiguration, customTheme?: string): h30.HTTPResponse;
+//#endregion
+export { ApiReferenceConfiguration, apiReference };

package/dist/openapi.scalar.d.mts

@@ -0,0 +1,8 @@
+import * as h31 from "h3";
+import { HtmlRenderingConfiguration } from "@scalar/core/libs/html-rendering";
+
+//#region src/openapi.scalar.d.ts
+type ApiReferenceConfiguration = Partial<HtmlRenderingConfiguration>;
+declare function apiReference(configuration: ApiReferenceConfiguration, customTheme?: string): h31.HTTPResponse;
+//#endregion
+export { ApiReferenceConfiguration, apiReference };

package/dist/openapi.scalar.mjs

@@ -0,0 +1,13 @@
+import { html } from "h3";
+import { getHtmlDocument } from "@scalar/core/libs/html-rendering";
+
+//#region src/openapi.scalar.ts
+function apiReference(configuration, customTheme) {
+	return html(getHtmlDocument({
+		_integration: "serverstruct",
+		...configuration
+	}, customTheme));
+}
+
+//#endregion
+export { apiReference };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverstruct",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Type safe and modular servers with H3",
   "private": false,
   "main": "./dist/index.cjs",
@@ -16,15 +16,38 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./openapi": {
+      "import": {
+        "types": "./dist/openapi.d.mts",
+        "default": "./dist/openapi.mjs"
+      },
+      "require": {
+        "types": "./dist/openapi.d.cts",
+        "default": "./dist/openapi.cjs"
+      }
+    },
+    "./openapi/scalar": {
+      "import": {
+        "types": "./dist/openapi.scalar.d.mts",
+        "default": "./dist/openapi.scalar.mjs"
+      },
+      "require": {
+        "types": "./dist/openapi.scalar.d.cts",
+        "default": "./dist/openapi.scalar.cjs"
+      }
+    },
+    "./otel": {
+      "import": {
+        "types": "./dist/otel.d.mts",
+        "default": "./dist/otel.mjs"
+      },
+      "require": {
+        "types": "./dist/otel.d.cts",
+        "default": "./dist/otel.cjs"
+      }
     }
   },
-  "scripts": {
-    "build": "tsc && tsdown src/index.ts --format esm,cjs",
-    "release": "pnpm run build && changeset publish",
-    "watch": "vitest",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
-  },
   "keywords": [
     "h3",
     "server",
@@ -43,6 +66,7 @@
   "homepage": "https://github.com/eriicafes/serverstruct#readme",
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
+    "@opentelemetry/sdk-trace-node": "^2.5.1",
     "@types/node": "^25.0.3",
     "@vitest/coverage-v8": "^4.0.16",
     "tsdown": "^0.18.3",
@@ -50,7 +74,19 @@
     "vitest": "^4.0.16"
   },
   "peerDependencies": {
-    "getbox": ">= 1.0.0 <2.0.0",
-    "h3": ">=2.0.1-rc.6 <3.0.0"
+    "@opentelemetry/api": ">=1.9.0 <2.0.0",
+    "@opentelemetry/semantic-conventions": ">=1.39.0 <2.0.0",
+    "@scalar/core": ">=0.3.37",
+    "getbox": ">=1.0.0 <2.0.0",
+    "h3": ">=2.0.1-rc.6 <3.0.0",
+    "zod": ">=4.0.0 <5.0.0",
+    "zod-openapi": ">=5.4.6 <6.0.0"
+  },
+  "scripts": {
+    "build": "tsc && tsdown",
+    "release": "pnpm run build && changeset publish",
+    "watch": "vitest",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
 }

package/tsdown.config.mts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: [
+    "./src/index.ts",
+    "./src/openapi.ts",
+    "./src/openapi.scalar.ts",
+    "./src/otel.ts",
+  ],
+  format: ["esm", "cjs"],
+});