npm - @tahminator/sapling - Versions diffs - 2.0.5 → 2.1.0-beta.a2de2fb9 - Mend

@tahminator/sapling 2.0.5 → 2.1.0-beta.a2de2fb9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/index.cjs CHANGED Viewed

@@ -23,6 +23,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let express = require("express");
 express = __toESM(express);
+let swagger_ui_express = require("swagger-ui-express");
+swagger_ui_express = __toESM(swagger_ui_express);
 //#region src/html/404.ts
 /**
 * Default Express.js 404 error page, as a string.
@@ -46,6 +48,7 @@ const Html404ErrorPage = (error) => `<!DOCTYPE html>
 * You can either return `new RedirectView(url)` or `RedirectView.redirect(url)` inside of a controller method.
 */
 var RedirectView = class RedirectView {
+	_url;
 	constructor(url) {
 		this._url = url;
 	}
@@ -141,8 +144,10 @@ let HttpStatus = /* @__PURE__ */ function(HttpStatus) {
 * @typeParam T - the type of the response body
 */
 var ResponseEntity = class {
+	_statusCode;
+	_headers = {};
+	_body;
 	constructor(body, headers = {}, statusCode = 200) {
-		this._headers = {};
 		this._body = body;
 		this._headers = headers;
 		this._statusCode = statusCode;
@@ -195,8 +200,9 @@ var ResponseEntity = class {
 * ensuring type safety when constructing the response.
 */
 var ResponseEntityBuilder = class {
+	_statusCode;
+	_headers = {};
 	constructor(statusCode) {
-		this._headers = {};
 		this._statusCode = statusCode;
 	}
 	/**
@@ -228,6 +234,7 @@ var ResponseEntityBuilder = class {
 * @see {@link Sapling.loadResponseStatusErrorMiddleware}
 */
 var ResponseStatusError = class ResponseStatusError extends Error {
+	status;
 	constructor(status, message) {
 		super(message ?? "Something went wrong.");
 		this.status = status;
@@ -239,150 +246,30 @@ var ResponseStatusError = class ResponseStatusError extends Error {
 //#endregion
 //#region src/helper/error/parse.ts
 /**
-* This error should be thrown when some data cannot be parsed by a given schema.
+* This error should be thrown when some data cannot be parsed by a given Standard Schema compatible schema.
 */
 var ParserError = class ParserError extends ResponseStatusError {
-	constructor(location, issues, vendor) {
-		super(400, ParserError.formatMessage(location, issues, vendor));
+	constructor(location, issues, vendor, functionName) {
+		super(400, ParserError.formatMessage(location, issues, vendor, functionName));
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
-	static formatMessage(location, issues, vendor) {
+	static formatMessage(location, issues, vendor, functionName) {
 		const formatted = issues.map((i) => {
 			const path = Array.isArray(i.path) ? i.path.map((seg) => typeof seg === "object" && seg ? String(seg.key) : String(seg)).join(".") : "";
 			return path ? `${path}: ${i.message}` : i.message;
 		}).join("; ");
-		return `${vendor} failed to parse ${(() => {
-			switch (location) {
-				case "reqbody": return "request body";
-				case "reqparams": return "request params";
-				case "reqquery": return "request query";
-			}
-		})()}: ${formatted}`;
-	}
-};
-//#endregion
-//#region src/helper/sapling.ts
-const settings = {
-	serialize: JSON.stringify,
-	deserialize: JSON.parse
-};
-/**
-* Collection of utility functions which are essential for Sapling to function.
-*/
-var Sapling = class Sapling {
-	/**
-	* If you would prefer to manually resolve your controllers instead, call resolve
-	* on the controller class.
-	*
-	* @example```ts
-	* import { Sapling } from "@tahminator/sapling";
-	* import TestController from "./path/to/test.controller";
-	*
-	* const app = express();
-	*
-	* const router = Sapling.resolve(TestController);
-	* app.use(router);
-	* ```
-	*/
-	static resolve(clazz) {
-		const router = _ControllerRegistry.get(clazz);
-		if (!router) throw new Error("Controller cannot be found");
-		return router;
-	}
-	/**
-	* Register this function as a middleware in order to utilize Sapling's `deserialize` function.
-	*
-	* @example```ts
-	* import { Sapling } from "@tahminator/sapling";
-	* import express from "express";
-	*
-	* const app = express();
-	*
-	* app.use(Sapling.json());
-	* ```
-	*/
-	static json() {
-		return (request, _response, next) => {
-			try {
-				if (!request.body) return next();
-				if (request.headers["content-type"] !== "application/json") return next();
-				if (typeof request.body === "string") request.body = Sapling.deserialize(request.body);
-				else if (typeof request.body === "object") {
-					const raw = JSON.stringify(request.body);
-					request.body = Sapling.deserialize(raw);
-				}
-				next();
-			} catch (err) {
-				next(err);
-			}
-		};
+		return `Failed to parse ${this.getPrettyLocationString(location)} with ${vendor} on ${functionName}: ${formatted}`;
 	}
-	/**
-	* Register your application with all the necessary middlewares and logics for Sapling to function.
-	*
-	* @example```ts
-	* import { Sapling } from "@tahminator/sapling";
-	* import express from "express";
-	*
-	* const app = express();
-	*
-	* app.registerApp(app);
-	* ```
-	*/
-	static registerApp(app) {
-		app.use(express.default.text({ type: "application/json" }));
-		app.use(Sapling.json());
-	}
-	/**
-	* Serialize a value into a JSON string.
-	*
-	* This function is used in {@link ResponseEntity} to serialize the `body`.
-	*
-	* Use `setSerializeFn` to override underlying implementation.
-	*
-	* @defaultValue `JSON.stringify`
-	*/
-	static serialize(value) {
-		return settings.serialize(value);
-	}
-	/**
-	* Replace the function used for `serialize`.
-	*/
-	static setSerializeFn(fn) {
-		settings.serialize = fn;
-	}
-	/**
-	* De-serialize a JSON string back to a JavaScript object.
-	*
-	* This function is used to de-serialize a string into a `body`.
-	*
-	* Use `setDeserializeFn` to override underlying implementation.
-	*
-	* @defaultValue `JSON.parse`
-	*/
-	static deserialize(value) {
-		return settings.deserialize(value);
-	}
-	/**
-	* Replace the function used for `deserialize`
-	*/
-	static setDeserializeFn(fn) {
-		settings.deserialize = fn;
+	static getPrettyLocationString(location) {
+		switch (location) {
+			case "reqbody": return "request body";
+			case "reqparams": return "request params";
+			case "reqquery": return "request query";
+			case "resbody": return "response body";
+		}
 	}
 };
 //#endregion
-//#region src/types.ts
-const methodResolve = {
-	GET: "get",
-	PUT: "put",
-	POST: "post",
-	DELETE: "delete",
-	OPTIONS: "options",
-	PATCH: "patch",
-	HEAD: "head",
-	USE: "use"
-};
-//#endregion
 //#region lib/weakmap.ts
 /**
 * WeakMap that is iterable.
@@ -503,132 +390,239 @@ function _resolve(ctor) {
 	return _InjectableRegistry.get(ctor);
 }
 //#endregion
-//#region src/annotation/request.ts
-const _requestSchemaStore = /* @__PURE__ */ new WeakMap();
-/**
-* Apply to a route method to have `request.body` be parsed by `schema`.
-*
-* This annotation will parse `request.body` & then override `request.body`.
-* You can then just simply cast `request.body` for your use
-*
-* @example
-* ```ts
-*  const CREATE_BOOK_REQUEST_BODY_SCHEMA = z.object({
-*    name: z.string(),
-*    description: z.string().optional(),
-*  });
-*
-* ⠀@Controller({ prefix: "/api/book" })
-*  class BookController {
-*   ⠀@RequestBody(CREATE_BOOK_REQUEST_BODY_SCHEMA)
-*   ⠀@POST()
-*    public createBook(request: e.Request) {
-*      const { name, description } = request.body as unknown as z.infer<
-*        typeof CREATE_BOOK_REQUEST_BODY_SCHEMA
-*      >;
-*    }
-*  }
-* ```
-*/
-function RequestBody(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "body", schema, fnName);
-	};
-}
-/**
-* Apply to a route method to have `request.param` be parsed by `schema`.
-*
-* This annotation will parse `request.param` & then override `request.param`.
-* You can then just simply cast `request.param` for your use
-*
-* @example
-* ```ts
-*  const GET_BOOK_REQUEST_PARAM_SCHEMA = z.object({
-*    bookId: z.string(),
-*  });
-*
-* ⠀@Controller({ prefix: "/api/book" })
-*  class BookController {
-*   ⠀@RequestParam(GET_BOOK_REQUEST_PARAM_SCHEMA)
-*   ⠀@GET("/:bookId")
-*    public getBook(request: e.Request) {
-*      const { bookId } = request.param as unknown as z.infer<
-*        typeof GET_BOOK_REQUEST_PARAM_SCHEMA
-*      >;
-*    }
-*  }
-* ```
-*/
-function RequestParam(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "param", schema, fnName);
-	};
+//#region \0@oxc-project+runtime@0.127.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
+//#endregion
+//#region src/middleware/health/registrar.ts
+let HealthRegistrar = class HealthRegistrar {
+	_checks;
+	_sealed;
+	constructor() {
+		this._checks = [];
+		this._sealed = false;
+	}
+	add(healthCheck) {
+		this._checks.push(healthCheck);
+	}
+	/**
+	* @internal used by Sapling library
+	*/
+	_seal() {
+		this._sealed = true;
+	}
+	async check() {
+		if (!this._sealed) return false;
+		return (await Promise.all(this._checks.map((c) => c()))).every((c) => c === true);
+	}
+};
+HealthRegistrar = __decorate([Injectable()], HealthRegistrar);
+//#endregion
+//#region src/helper/sapling.ts
+const _settings = {
+	serialize: JSON.stringify,
+	deserialize: JSON.parse,
+	health: { path: "/up" },
+	doc: {
+		openApiPath: "/openapi.json",
+		swaggerPath: "/swagger.html",
+		metadata: {
+			title: "API",
+			version: "1.0.0"
+		}
+	}
+};
 /**
-* Apply to a route method to have `request.query` be parsed by `schema`.
-*
-* This annotation will parse `request.query` & then override `request.query`.
-* You can then just simply cast `request.query` for your use
-*
-* @example
-* ```ts
-*  const LIST_BOOKS_REQUEST_QUERY_SCHEMA = z.object({
-*    sort: z.enum(["name", "createdAt"]).optional(),
-*    q: z.string().optional(),
-*  });
-*
-* ⠀@Controller({ prefix: "/api/book" })
-*  class BookController {
-*   ⠀@RequestQuery(LIST_BOOKS_REQUEST_QUERY_SCHEMA)
-*   ⠀@GET()
-*    public listBooks(request: e.Request) {
-*      const { sort, q } = request.query as unknown as z.infer<
-*        typeof LIST_BOOKS_REQUEST_QUERY_SCHEMA
-*      >;
-*    }
-*  }
-* ```
+* Collection of utility functions which are essential for Sapling to function.
 */
-function RequestQuery(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "query", schema, fnName);
-	};
-}
-function _getOrCreateRequestSchemaDefinition(ctor, fnName) {
-	const byFn = (() => {
-		const fn = _requestSchemaStore.get(ctor);
-		if (fn) return fn;
-		const newFn = /* @__PURE__ */ new Map();
-		_requestSchemaStore.set(ctor, newFn);
-		return newFn;
-	})();
-	const existing = byFn.get(fnName);
-	if (existing) return existing;
-	const created = {};
-	byFn.set(fnName, created);
-	return created;
-}
-function _setOnce(def, key, schema, fnName) {
-	if (def[key]) throw new Error(`Duplicate request schema for "${String(key)}" on method "${fnName}"`);
-	def[key] = schema;
-}
-function _getRequestSchemas(ctor, fnName) {
-	return _requestSchemaStore.get(ctor)?.get(fnName);
-}
-async function _parseOrThrow(schema, input, kind) {
-	const result = await schema["~standard"].validate(input);
-	if (result.issues) {
-		console.debug(`Failed to parse a schema`);
-		throw new ParserError(kind, result.issues, schema["~standard"].vendor);
+var Sapling = class Sapling {
+	/**
+	* If you would prefer to manually resolve your controllers instead, call resolve
+	* on the controller class.
+	*
+	* @example```ts
+	* import { Sapling } from "@tahminator/sapling";
+	* import TestController from "./path/to/test.controller";
+	*
+	* const app = express();
+	*
+	* const router = Sapling.resolve(TestController);
+	* app.use(router);
+	* ```
+	*/
+	static resolve(clazz) {
+		const router = _ControllerRegistry.get(clazz);
+		if (!router) throw new Error("Controller cannot be found");
+		return router;
 	}
-	return result.value;
-}
+	/**
+	* Register this function as a middleware in order to utilize Sapling's `deserialize` function.
+	*
+	* @example```ts
+	* import { Sapling } from "@tahminator/sapling";
+	* import express from "express";
+	*
+	* const app = express();
+	*
+	* app.use(Sapling.json());
+	* ```
+	*/
+	static json() {
+		return (request, _response, next) => {
+			try {
+				if (!request.body) return next();
+				if (request.headers["content-type"] !== "application/json") return next();
+				if (typeof request.body === "string") request.body = Sapling.deserialize(request.body);
+				else if (typeof request.body === "object") {
+					const raw = JSON.stringify(request.body);
+					request.body = Sapling.deserialize(raw);
+				}
+				next();
+			} catch (err) {
+				next(err);
+			}
+		};
+	}
+	/**
+	* Register your application with all the necessary middlewares and logics for Sapling to function.
+	*
+	* @example```ts
+	* import { Sapling } from "@tahminator/sapling";
+	* import express from "express";
+	*
+	* const app = express();
+	*
+	* app.registerApp(app);
+	* ```
+	*/
+	static registerApp(app) {
+		app.use(express.default.text({ type: "application/json" }));
+		app.use(Sapling.json());
+		return new Proxy(app, { get(target, prop, receiver) {
+			if (prop === "listen") {
+				const originalListen = target[prop];
+				return function(...args) {
+					const server = originalListen.apply(target, args);
+					server.once("listening", () => {
+						Sapling.onStartup();
+						console.log("Sapling successfully initialized post-startup hooks on server start");
+					});
+					return server;
+				};
+			}
+			return Reflect.get(target, prop, receiver);
+		} });
+	}
+	static onStartup() {
+		_InjectableRegistry.get(HealthRegistrar)?.seal();
+	}
+	/**
+	* Serialize a value into a JSON string.
+	*
+	* This function is used in {@link ResponseEntity} to serialize the `body`.
+	*
+	* Use `setSerializeFn` to override underlying implementation.
+	*
+	* @defaultValue `JSON.stringify`
+	*/
+	static serialize(value) {
+		return _settings.serialize(value);
+	}
+	/**
+	* Replace the function used for `serialize`.
+	*/
+	static setSerializeFn(fn) {
+		_settings.serialize = fn;
+	}
+	/**
+	* De-serialize a JSON string back to a JavaScript object.
+	*
+	* This function is used to de-serialize a string into a `body`.
+	*
+	* Use `setDeserializeFn` to override underlying implementation.
+	*
+	* @defaultValue `JSON.parse`
+	*/
+	static deserialize(value) {
+		return _settings.deserialize(value);
+	}
+	/**
+	* Replace the function used for `deserialize`
+	*/
+	static setDeserializeFn(fn) {
+		_settings.deserialize = fn;
+	}
+	/**
+	* Modify extra settings
+	*/
+	static Extras = {
+	/**
+	* Modify default settings applied to OpenAPI & Swagger
+	*/
+swaggerAndOpenApi: {
+		/**
+		* Set base OpenAPI metadata values.
+		*
+		* @default { title: "API", version: "1.0.0" }
+		*/
+		setMetadata(metadata) {
+			_settings.doc.metadata = metadata;
+		},
+		/**
+		* change default endpoint that will serve OpenAPI spec.
+		* Swagger will also load this endpoint on load.
+		*
+		* @default `/openapi.json`
+		*/
+		setOpenApiPath(path) {
+			_settings.doc.openApiPath = path;
+		},
+		/**
+		* change Swagger endpoint.
+		*
+		* @default `/swagger.html`
+		*/
+		setSwaggerPath(path) {
+			_settings.doc.swaggerPath = path;
+		}
+	} };
+	/**
+	* This method can be used in a `@MiddlewareClass` to register any libraries
+	* that expect you to register multiple registers at once. An example is `swagger-ui-express`
+	*
+	* @example
+	* ```ts
+	* ⠀@MiddlewareClass()
+	*  class Serve {
+	*    // `swagger.serve` returns multiple Express handlers for all the assets and routes
+	*    // that will be served
+	*    private readonly handlers: RequestHandler[] = swagger.serve;
+	*
+	*   ⠀@Middleware(_settings.doc.swaggerPath)
+	*    handle(request: Request, response: Response, next: NextFunction) {
+	*      return Sapling.chainHandlers(this.handlers, request, response, next);
+	*    }
+	*  }
+	* ```
+	*/
+	static chainHandlers(handlers, request, response, next, index = 0) {
+		if (index >= handlers.length) {
+			next();
+			return;
+		}
+		handlers[index]?.(request, response, (err) => {
+			if (err) {
+				next(err);
+				return;
+			}
+			Sapling.chainHandlers(handlers, request, response, next, index + 1);
+		});
+	}
+};
 //#endregion
 //#region src/annotation/route.ts
 const _routeStore = /* @__PURE__ */ new WeakMap();
@@ -711,6 +705,245 @@ function _getRoutes(ctor) {
 	return _routeStore.get(ctor) ?? [];
 }
 //#endregion
+//#region src/annotation/schema.ts
+function ControllerSchema(options) {
+	return (target) => {
+		_setControllerSchema(target, options);
+	};
+}
+function RouteSchema(options) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		_setRouteSchema(ctor, String(propertyKey), options);
+	};
+}
+const _routeSchemaStore = /* @__PURE__ */ new WeakMap();
+const _controllerSchemaStore = /* @__PURE__ */ new WeakMap();
+function getOrCreateRouteSchemaStore(store, ctor) {
+	const existing = store.get(ctor);
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new Map();
+	store.set(ctor, created);
+	return created;
+}
+function _setRouteSchema(ctor, fnName, options) {
+	getOrCreateRouteSchemaStore(_routeSchemaStore, ctor).set(fnName, options);
+}
+function _setControllerSchema(ctor, options) {
+	_controllerSchemaStore.set(ctor, options);
+}
+function _getRouteSchema(ctor, fnName) {
+	return _routeSchemaStore.get(ctor)?.get(fnName);
+}
+function _getControllerSchema(ctor) {
+	return _controllerSchemaStore.get(ctor);
+}
+//#endregion
+//#region src/annotation/validator.ts
+const _validatorSchemaStore = /* @__PURE__ */ new WeakMap();
+function ResponseBody(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_saveValidatorSchema(_getOrCreateSchemaDefinition(ctor, fnName), "responseBody", schema, fnName);
+	};
+}
+function RequestBody(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_saveValidatorSchema(_getOrCreateSchemaDefinition(ctor, fnName), "requestBody", schema, fnName);
+	};
+}
+function RequestParam(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_saveValidatorSchema(_getOrCreateSchemaDefinition(ctor, fnName), "requestParam", schema, fnName);
+	};
+}
+function RequestQuery(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_saveValidatorSchema(_getOrCreateSchemaDefinition(ctor, fnName), "requestQuery", schema, fnName);
+	};
+}
+function getOrCreateValidatorSchemaStore(store, ctor) {
+	const existing = store.get(ctor);
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new Map();
+	store.set(ctor, created);
+	return created;
+}
+function _getOrCreateSchemaDefinition(ctor, fnName) {
+	const byFn = getOrCreateValidatorSchemaStore(_validatorSchemaStore, ctor);
+	const existing = byFn.get(fnName);
+	if (existing) return existing;
+	const created = {};
+	byFn.set(fnName, created);
+	return created;
+}
+async function _parseOrThrow(schema, input, location, fnName) {
+	const result = await schema["~standard"].validate(input);
+	if (result.issues) throw new ParserError(location, result.issues, schema["~standard"].vendor, fnName);
+	return result.value;
+}
+function _saveValidatorSchema(def, key, schema, fnName) {
+	if (def[key]) throw new Error(`Duplicate schema for "${String(key)}" on method "${fnName}"`);
+	def[key] = schema;
+}
+function _getValidatorSchema(ctor, fnName) {
+	return _validatorSchemaStore.get(ctor)?.get(fnName);
+}
+//#endregion
+//#region src/helper/openapi.ts
+var OpenAPIGenerator = class {
+	OPENAPI_VERSION = "3.0.0";
+	controllers = /* @__PURE__ */ new Set();
+	registerController(controllerClass, prefix) {
+		this.controllers.add({
+			class: controllerClass,
+			prefix
+		});
+	}
+	/**
+	* visible for testing
+	*/
+	_clearControllers() {
+		this.controllers.clear();
+	}
+	get metadata() {
+		return _settings.doc.metadata;
+	}
+	generateSpec() {
+		const metadata = this.metadata;
+		const paths = {};
+		const tags = [];
+		for (const { class: controllerClass, prefix } of this.controllers) {
+			const routes = _getRoutes(controllerClass);
+			const controllerSchema = _getControllerSchema(controllerClass);
+			if (controllerSchema?.title) tags.push({
+				name: controllerSchema.title,
+				description: controllerSchema.description
+			});
+			for (const route of routes) {
+				if (route.method === "USE") continue;
+				const schemas = _getValidatorSchema(controllerClass, route.fnName);
+				const routeSchema = _getRouteSchema(controllerClass, route.fnName);
+				if (route.path instanceof RegExp) throw new Error(`You have a route with a regex path of ${route.path.source}. This is not compatible with OpenAPI.`);
+				const openApiPath = (prefix + route.path).replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+				if (!paths[openApiPath]) paths[openApiPath] = {};
+				const responses = {};
+				if (schemas?.responseBody) {
+					const responseSchema = this.toJsonSchema(schemas.responseBody, "output");
+					responses["200"] = {
+						description: responseSchema.description ?? "Successful response",
+						content: { "application/json": { schema: responseSchema } }
+					};
+				} else responses["200"] = { description: "Successful response" };
+				if (routeSchema?.responses) for (const resp of routeSchema.responses) {
+					const statusCode = String(resp.statusCode);
+					const existingResponse = responses[statusCode];
+					const existingSchema = existingResponse && "content" in existingResponse ? existingResponse.content?.["application/json"]?.schema : void 0;
+					const responseSchema = resp.schema ? this.toJsonSchema(resp.schema, "output") : statusCode === "200" ? existingSchema : void 0;
+					responses[statusCode] = {
+						...existingResponse,
+						description: resp.description ?? responseSchema?.description ?? existingResponse?.description ?? `Response ${resp.statusCode}`,
+						...responseSchema ? { content: { "application/json": { schema: responseSchema } } } : {}
+					};
+				}
+				const operation = {
+					responses,
+					summary: routeSchema?.summary,
+					description: routeSchema?.description,
+					tags: controllerSchema?.title ? [controllerSchema.title] : void 0
+				};
+				const parameters = [];
+				if (schemas?.requestParam) {
+					const paramSchema = this.toJsonSchema(schemas.requestParam, "input");
+					if (paramSchema.type === "object" && paramSchema.properties) for (const [name, schema] of Object.entries(paramSchema.properties)) {
+						const parameterSchema = schema;
+						parameters.push({
+							name,
+							in: "path",
+							required: true,
+							description: parameterSchema.description,
+							schema: parameterSchema
+						});
+					}
+				}
+				if (schemas?.requestQuery) {
+					const querySchema = this.toJsonSchema(schemas.requestQuery, "input");
+					if (querySchema.type === "object" && querySchema.properties) for (const [name, schema] of Object.entries(querySchema.properties)) {
+						const isRequired = Array.isArray(querySchema.required) && querySchema.required.includes(name);
+						const parameterSchema = schema;
+						parameters.push({
+							name,
+							in: "query",
+							required: isRequired,
+							description: parameterSchema.description,
+							schema: parameterSchema
+						});
+					}
+				}
+				if (parameters.length > 0) operation.parameters = parameters;
+				if (schemas?.requestBody) {
+					const requestSchema = this.toJsonSchema(schemas.requestBody, "input");
+					operation.requestBody = {
+						required: true,
+						description: requestSchema.description,
+						content: { "application/json": { schema: requestSchema } }
+					};
+				}
+				const method = route.method.toLowerCase();
+				paths[openApiPath][method] = operation;
+			}
+		}
+		return {
+			openapi: this.OPENAPI_VERSION,
+			info: {
+				title: metadata.title,
+				version: metadata.version,
+				description: metadata.description
+			},
+			tags: tags.length > 0 ? tags : void 0,
+			paths
+		};
+	}
+	toJsonSchema(schema, direction = "output") {
+		try {
+			const jsonSchema = schema["~standard"].jsonSchema;
+			return direction === "input" ? jsonSchema.input({ target: "openapi-3.0" }) : jsonSchema.output({ target: "openapi-3.0" });
+		} catch (e) {
+			if (e instanceof Error && e.message.includes("Transforms cannot be represented in JSON Schema")) throw new Error(`${e.message}.\nIt appears that you are using z.transform() - it is highly recommended that you use z.codec instead - https://zod.dev/codecs`, { cause: e });
+			throw e;
+		}
+	}
+};
+const openApiGenerator = new OpenAPIGenerator();
+function _registerController(controllerClass, prefix) {
+	openApiGenerator.registerController(controllerClass, prefix);
+}
+function generateOpenApiSpec() {
+	return openApiGenerator.generateSpec();
+}
+function _clearOpenApiRegistry() {
+	openApiGenerator._clearControllers();
+}
+//#endregion
+//#region src/types.ts
+const methodResolve = {
+	GET: "get",
+	PUT: "put",
+	POST: "post",
+	DELETE: "delete",
+	OPTIONS: "options",
+	PATCH: "patch",
+	HEAD: "head",
+	USE: "use"
+};
+//#endregion
 //#region src/annotation/controller.ts
 const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 /**
@@ -722,6 +955,7 @@ const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 function Controller({ prefix = "", deps = [] } = {}) {
 	return (target) => {
 		const targetClass = target;
+		_registerController(target, prefix);
 		const router = (0, express.Router)();
 		const routes = _getRoutes(target);
 		const usedRoutes = /* @__PURE__ */ new Set();
@@ -746,15 +980,20 @@ Split these into separate @MiddlewareClass classes, or merge the logic into a si
 			if (method === "USE" && fn.length >= 4) {
 				const middlewareFn = async (err, request, response, next) => {
 					try {
-						const result = fn.bind(controllerInstance)(err, request, response, next);
-						if (result instanceof ResponseEntity) {
-							response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(result.getBody()));
-							return;
-						}
-						if (result instanceof RedirectView) {
-							response.redirect(result.getUrl());
-							return;
-						}
+						await validate({
+							target,
+							fnName,
+							request
+						});
+						await handleResult({
+							result: fn.bind(controllerInstance)(err, request, response, next),
+							response,
+							target,
+							fnName,
+							method,
+							path: path instanceof RegExp ? path.source : fp,
+							isErrorMiddleware: true
+						});
 					} catch (e) {
 						console.error(e);
 						next(e);
@@ -764,34 +1003,52 @@ Split these into separate @MiddlewareClass classes, or merge the logic into a si
 				return;
 			}
 			router[methodName](fp, async (request, response, next) => {
-				const schemas = _getRequestSchemas(target, fnName);
-				if (schemas) {
-					if (schemas.body) request.body = await _parseOrThrow(schemas.body, request.body, "reqbody");
-					if (schemas.param) request.params = await _parseOrThrow(schemas.param, request.params, "reqparams");
-					if (schemas.query) {
-						const parsedQuery = await _parseOrThrow(schemas.query, request.query, "reqquery");
-						Object.defineProperty(request, "query", {
-							value: parsedQuery,
-							writable: true,
-							configurable: true
-						});
-					}
-				}
-				const result = await fn.bind(controllerInstance)(request, response, next);
-				if (result instanceof ResponseEntity) {
-					response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(result.getBody()));
-					return;
-				}
-				if (result instanceof RedirectView) {
-					response.redirect(result.getUrl());
-					return;
-				}
-				if (method !== "USE" && !response.writableEnded) response.status(404).send(Html404ErrorPage(`Cannot ${methodName.toUpperCase()} ${path instanceof RegExp ? path.source : fp}`));
+				await validate({
+					target,
+					fnName,
+					request
+				});
+				await handleResult({
+					result: await fn.bind(controllerInstance)(request, response, next),
+					response,
+					target,
+					fnName,
+					method,
+					path: path instanceof RegExp ? path.source : fp
+				});
 			});
 		}
 		_ControllerRegistry.set(targetClass, router);
 	};
 }
+async function handleResult({ result, target, fnName, response, method, path, isErrorMiddleware = false }) {
+	const schemas = _getValidatorSchema(target, fnName);
+	if (result instanceof ResponseEntity) {
+		const body = schemas && schemas.responseBody ? await _parseOrThrow(schemas.responseBody, result.getBody(), "resbody", fnName) : result.getBody();
+		response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(body));
+		return;
+	}
+	if (result instanceof RedirectView) {
+		response.redirect(result.getUrl());
+		return;
+	}
+	if (!isErrorMiddleware && method !== "USE" && !response.writableEnded) response.status(404).send(Html404ErrorPage(`Cannot ${method} ${path}`));
+}
+async function validate({ target, fnName, request }) {
+	const schemas = _getValidatorSchema(target, fnName);
+	if (schemas) {
+		if (schemas.requestBody) request.body = await _parseOrThrow(schemas.requestBody, request.body, "reqbody", fnName);
+		if (schemas.requestParam) request.params = await _parseOrThrow(schemas.requestParam, request.params, "reqparams", fnName);
+		if (schemas.requestQuery) {
+			const parsedQuery = await _parseOrThrow(schemas.requestQuery, request.query, "reqquery", fnName);
+			Object.defineProperty(request, "query", {
+				value: parsedQuery,
+				writable: true,
+				configurable: true
+			});
+		}
+	}
+}
 //#endregion
 //#region src/annotation/middleware.ts
 /**
@@ -805,15 +1062,7 @@ function MiddlewareClass(...args) {
 	return Controller(...args);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.127.0/helpers/decorate.js
-function __decorate(decorators, target, key, desc) {
-	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-	return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-//#endregion
-//#region src/middleware/default/base.ts
+//#region src/middleware/default/error/base.ts
 let DefaultBaseErrorMiddleware = class DefaultBaseErrorMiddleware {
 	handle(err, _request, _response, _next) {
 		console.error("[Error]", err);
@@ -823,7 +1072,20 @@ let DefaultBaseErrorMiddleware = class DefaultBaseErrorMiddleware {
 __decorate([Middleware()], DefaultBaseErrorMiddleware.prototype, "handle", null);
 DefaultBaseErrorMiddleware = __decorate([MiddlewareClass()], DefaultBaseErrorMiddleware);
 //#endregion
-//#region src/middleware/default/responsestatus.ts
+//#region src/middleware/default/error/parse.ts
+let DefaultParserErrorMiddleware = class DefaultParserErrorMiddleware {
+	handle(err, _request, _response, next) {
+		if (err instanceof ParserError) {
+			console.warn(err);
+			return ResponseEntity.status(err.status).body({ message: err.message });
+		}
+		next(err);
+	}
+};
+__decorate([Middleware()], DefaultParserErrorMiddleware.prototype, "handle", null);
+DefaultParserErrorMiddleware = __decorate([MiddlewareClass()], DefaultParserErrorMiddleware);
+//#endregion
+//#region src/middleware/default/error/responsestatus.ts
 let DefaultResponseStatusErrorMiddleware = class DefaultResponseStatusErrorMiddleware {
 	handle(err, _request, _response, next) {
 		if (err instanceof ResponseStatusError) return ResponseEntity.status(err.status).body({ message: err.message });
@@ -833,7 +1095,103 @@ let DefaultResponseStatusErrorMiddleware = class DefaultResponseStatusErrorMiddl
 __decorate([Middleware()], DefaultResponseStatusErrorMiddleware.prototype, "handle", null);
 DefaultResponseStatusErrorMiddleware = __decorate([MiddlewareClass()], DefaultResponseStatusErrorMiddleware);
 //#endregion
+//#region src/middleware/default/openapi/index.ts
+let DefaultOpenApiMiddleware = class DefaultOpenApiMiddleware {
+	handle(_request, _response, _next) {
+		return ResponseEntity.ok().body(generateOpenApiSpec());
+	}
+};
+__decorate([GET(_settings.doc.openApiPath)], DefaultOpenApiMiddleware.prototype, "handle", null);
+DefaultOpenApiMiddleware = __decorate([MiddlewareClass()], DefaultOpenApiMiddleware);
+//#endregion
+//#region src/middleware/default/swagger/index.ts
+/**
+* Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
+*
+* Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+*
+* You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+*
+* ```ts
+*  const middlewares = [
+*    DefaultOpenApiMiddleware,
+*    DefaultSwaggerMiddleware.Serve,
+*    DefaultSwaggerMiddleware.Setup,
+*  ];
+*  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+* ```
+*/
+let Serve = class Serve {
+	handlers = swagger_ui_express.default.serve;
+	handle(request, response, next) {
+		return Sapling.chainHandlers(this.handlers, request, response, next);
+	}
+};
+__decorate([Middleware(_settings.doc.swaggerPath)], Serve.prototype, "handle", null);
+Serve = __decorate([MiddlewareClass()], Serve);
+/**
+* Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
+*
+* Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+*
+* You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+*
+* ```ts
+*  const middlewares = [
+*    DefaultOpenApiMiddleware,
+*    DefaultSwaggerMiddleware.Serve,
+*    DefaultSwaggerMiddleware.Setup,
+*  ];
+*  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+* ```
+*/
+let Setup = class Setup {
+	handler;
+	constructor() {
+		this.handler = swagger_ui_express.default.setup(null, { swaggerOptions: { url: _settings.doc.openApiPath } });
+	}
+	handle(request, response, next) {
+		return this.handler(request, response, next);
+	}
+};
+__decorate([Middleware(_settings.doc.swaggerPath)], Setup.prototype, "handle", null);
+Setup = __decorate([MiddlewareClass()], Setup);
+/**
+* Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
+*
+* Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+*
+* You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+*
+* ```ts
+*  const middlewares = [
+*    DefaultOpenApiMiddleware,
+*    DefaultSwaggerMiddleware.Serve,
+*    DefaultSwaggerMiddleware.Setup,
+*  ];
+*  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+* ```
+*/
+const DefaultSwaggerMiddleware = {
+	Serve,
+	Setup
+};
+//#endregion
+//#region src/middleware/default/health/index.ts
+let DefaultHealthMiddleware = class DefaultHealthMiddleware {
+	constructor(healthRegistrar) {
+		this.healthRegistrar = healthRegistrar;
+	}
+	async serve(_request, _response, _next) {
+		const up = await this.healthRegistrar.check();
+		return ResponseEntity.ok().body({ up });
+	}
+};
+__decorate([GET(_settings.health.path)], DefaultHealthMiddleware.prototype, "serve", null);
+DefaultHealthMiddleware = __decorate([MiddlewareClass({ deps: [HealthRegistrar] })], DefaultHealthMiddleware);
+//#endregion
 exports.Controller = Controller;
+exports.ControllerSchema = ControllerSchema;
 exports.DELETE = DELETE;
 Object.defineProperty(exports, "DefaultBaseErrorMiddleware", {
 	enumerable: true,
@@ -841,14 +1199,39 @@ Object.defineProperty(exports, "DefaultBaseErrorMiddleware", {
 		return DefaultBaseErrorMiddleware;
 	}
 });
+Object.defineProperty(exports, "DefaultHealthMiddleware", {
+	enumerable: true,
+	get: function() {
+		return DefaultHealthMiddleware;
+	}
+});
+Object.defineProperty(exports, "DefaultOpenApiMiddleware", {
+	enumerable: true,
+	get: function() {
+		return DefaultOpenApiMiddleware;
+	}
+});
+Object.defineProperty(exports, "DefaultParserErrorMiddleware", {
+	enumerable: true,
+	get: function() {
+		return DefaultParserErrorMiddleware;
+	}
+});
 Object.defineProperty(exports, "DefaultResponseStatusErrorMiddleware", {
 	enumerable: true,
 	get: function() {
 		return DefaultResponseStatusErrorMiddleware;
 	}
 });
+exports.DefaultSwaggerMiddleware = DefaultSwaggerMiddleware;
 exports.GET = GET;
 exports.HEAD = HEAD;
+Object.defineProperty(exports, "HealthRegistrar", {
+	enumerable: true,
+	get: function() {
+		return HealthRegistrar;
+	}
+});
 exports.Html404ErrorPage = Html404ErrorPage;
 exports.HttpStatus = HttpStatus;
 exports.Injectable = Injectable;
@@ -863,16 +1246,29 @@ exports.RedirectView = RedirectView;
 exports.RequestBody = RequestBody;
 exports.RequestParam = RequestParam;
 exports.RequestQuery = RequestQuery;
+exports.ResponseBody = ResponseBody;
 exports.ResponseEntity = ResponseEntity;
 exports.ResponseEntityBuilder = ResponseEntityBuilder;
 exports.ResponseStatusError = ResponseStatusError;
+exports.RouteSchema = RouteSchema;
 exports.Sapling = Sapling;
 exports._ControllerRegistry = _ControllerRegistry;
 exports._InjectableDeps = _InjectableDeps;
 exports._InjectableRegistry = _InjectableRegistry;
 exports._Route = _Route;
-exports._getRequestSchemas = _getRequestSchemas;
+exports._clearOpenApiRegistry = _clearOpenApiRegistry;
+exports._getControllerSchema = _getControllerSchema;
+exports._getOrCreateSchemaDefinition = _getOrCreateSchemaDefinition;
+exports._getRouteSchema = _getRouteSchema;
 exports._getRoutes = _getRoutes;
+exports._getValidatorSchema = _getValidatorSchema;
 exports._parseOrThrow = _parseOrThrow;
+exports._registerController = _registerController;
 exports._resolve = _resolve;
+exports._saveValidatorSchema = _saveValidatorSchema;
+exports._setControllerSchema = _setControllerSchema;
+exports._setRouteSchema = _setRouteSchema;
+exports._settings = _settings;
+exports.generateOpenApiSpec = generateOpenApiSpec;
 exports.methodResolve = methodResolve;
+exports.openApiGenerator = openApiGenerator;