@tahminator/sapling 2.0.3 → 2.0.5-beta.18ab8bae

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import e, { Router } from "express";
+import swagger from "swagger-ui-express";
 //#region src/html/404.ts
 /**
 * Default Express.js 404 error page, as a string.
@@ -232,15 +233,20 @@ var ParserError = class ParserError extends ResponseStatusError {
 				case "reqbody": return "request body";
 				case "reqparams": return "request params";
 				case "reqquery": return "request query";
+				case "resbody": return "response body";
 			}
 		})()}: ${formatted}`;
 	}
 };
 //#endregion
 //#region src/helper/sapling.ts
-const settings = {
+const _settings = {
 	serialize: JSON.stringify,
-	deserialize: JSON.parse
+	deserialize: JSON.parse,
+	doc: {
+		openApiPath: "/openapi.json",
+		swaggerPath: "/swagger.html"
+	}
 };
 /**
 * Collection of utility functions which are essential for Sapling to function.
@@ -319,13 +325,13 @@ var Sapling = class Sapling {
 	* @defaultValue `JSON.stringify`
 	*/
 	static serialize(value) {
-		return settings.serialize(value);
+		return _settings.serialize(value);
 	}
 	/**
 	* Replace the function used for `serialize`.
 	*/
 	static setSerializeFn(fn) {
-		settings.serialize = fn;
+		_settings.serialize = fn;
 	}
 	/**
 	* De-serialize a JSON string back to a JavaScript object.
@@ -337,16 +343,265 @@ var Sapling = class Sapling {
 	* @defaultValue `JSON.parse`
 	*/
 	static deserialize(value) {
-		return settings.deserialize(value);
+		return _settings.deserialize(value);
 	}
 	/**
 	* Replace the function used for `deserialize`
 	*/
 	static setDeserializeFn(fn) {
-		settings.deserialize = fn;
+		_settings.deserialize = fn;
+	}
+	static setOpenApiPath(path) {
+		_settings.doc.openApiPath = path;
+	}
+	static setSwaggerPath(path) {
+		_settings.doc.swaggerPath = path;
+	}
+	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();
+/**
+* Custom annotation that will store all routes inside of a map,
+* which can then be used to initialize all the routes to the router.
+*/
+function _Route({ method, path = "" }) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const list = _routeStore.get(ctor) ?? [];
+		list.push({
+			method,
+			path: path ?? "",
+			fnName: String(propertyKey)
+		});
+		_routeStore.set(ctor, list);
+	};
+}
+/**
+* Register GET route on the given path (default "") for the given controller.
+*/
+const GET = (path = "") => _Route({
+	method: "GET",
+	path
+});
+/**
+* Register POST route on the given path (default "") for the given controller.
+*/
+const POST = (path = "") => _Route({
+	method: "POST",
+	path
+});
+/**
+* Register PUT route on the given path (default "") for the given controller.
+*/
+const PUT = (path = "") => _Route({
+	method: "PUT",
+	path
+});
+/**
+* Register DELETE route on the given path (default "") for the given controller.
+*/
+const DELETE = (path = "") => _Route({
+	method: "DELETE",
+	path
+});
+/**
+* Register OPTIONS route on the given path (default "") for the given controller.
+*/
+const OPTIONS = (path = "") => _Route({
+	method: "OPTIONS",
+	path
+});
+/**
+* Register PATCH route on the given path (default "") for the given controller.
+*/
+const PATCH = (path = "") => _Route({
+	method: "PATCH",
+	path
+});
+/**
+* Register HEAD route on the given path (default "") for the given controller.
+*/
+const HEAD = (path = "") => _Route({
+	method: "HEAD",
+	path
+});
+/**
+* Register a middleware route on the given path (default "") for the given controller.
+*/
+const Middleware = (path = "") => _Route({
+	method: "USE",
+	path
+});
+/**
+* Given a class constructor, fetch all the routes attached.
+*/
+function _getRoutes(ctor) {
+	return _routeStore.get(ctor) ?? [];
+}
+//#endregion
+//#region src/utils.ts
+function _getOrCreateMap(store, ctor) {
+	const existing = store.get(ctor);
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new Map();
+	store.set(ctor, created);
+	return created;
+}
+//#endregion
+//#region src/annotation/schema.ts
+const _routeSchemaStore = /* @__PURE__ */ new WeakMap();
+const _controllerSchemaStore = /* @__PURE__ */ new WeakMap();
+function ControllerSchema(options) {
+	return (target) => {
+		_setControllerSchema(target, options);
+	};
+}
+function RouteSchema(options) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		_setRouteSchema(ctor, String(propertyKey), options);
+	};
+}
+function _setRouteSchema(ctor, fnName, options) {
+	_getOrCreateMap(_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/helper/openapi.ts
+var OpenAPIGenerator = class {
+	constructor() {
+		this.controllers = /* @__PURE__ */ new Set();
+		this.config = {
+			title: "API",
+			version: "1.0.0"
+		};
+	}
+	setConfig(config) {
+		this.config = config;
+	}
+	registerController(controllerClass, prefix) {
+		this.controllers.add({
+			class: controllerClass,
+			prefix
+		});
+	}
+	generateSpec() {
+		const config = this.config;
+		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;
+				if (!paths[openApiPath]) paths[openApiPath] = {};
+				const responses = {};
+				if (schemas?.responseBody) responses["200"] = {
+					description: "Successful response",
+					content: { "application/json": { schema: this.toJsonSchema(schemas.responseBody) } }
+				};
+				else responses["200"] = { description: "Successful response" };
+				if (routeSchema?.responses) for (const resp of routeSchema.responses) responses[String(resp.statusCode)] = {
+					description: `Response ${resp.statusCode}`,
+					content: { "application/json": { schema: this.toJsonSchema(resp.schema) } }
+				};
+				const operation = {
+					responses,
+					description: routeSchema?.description,
+					tags: controllerSchema?.title ? [controllerSchema.title] : void 0
+				};
+				const parameters = [];
+				if (schemas?.requestParam) {
+					const paramSchema = this.toJsonSchema(schemas.requestParam);
+					if (paramSchema.type === "object" && paramSchema.properties) for (const [name, schema] of Object.entries(paramSchema.properties)) parameters.push({
+						name,
+						in: "path",
+						required: true,
+						schema
+					});
+				}
+				if (schemas?.requestQuery) {
+					const querySchema = this.toJsonSchema(schemas.requestQuery);
+					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);
+						parameters.push({
+							name,
+							in: "query",
+							required: isRequired,
+							schema
+						});
+					}
+				}
+				if (parameters.length > 0) operation.parameters = parameters;
+				if (schemas?.requestBody) operation.requestBody = {
+					required: true,
+					content: { "application/json": { schema: this.toJsonSchema(schemas.requestBody) } }
+				};
+				const method = route.method.toLowerCase();
+				paths[openApiPath][method] = operation;
+			}
+		}
+		return {
+			openapi: "3.0.0",
+			info: {
+				title: config.title,
+				version: config.version,
+				description: config.description
+			},
+			tags: tags.length > 0 ? tags : void 0,
+			paths
+		};
+	}
+	toJsonSchema(schema) {
+		try {
+			return schema["~standard"].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`);
+			throw e;
+		}
+	}
+};
+const openApiGenerator = new OpenAPIGenerator();
+function _registerControllerClass(controllerClass, prefix) {
+	openApiGenerator.registerController(controllerClass, prefix);
+}
+function setOpenApiConfig(config) {
+	openApiGenerator.setConfig(config);
+}
+function generateOpenApiSpec() {
+	return openApiGenerator.generateSpec();
+}
+//#endregion
 //#region src/types.ts
 const methodResolve = {
 	GET: "get",
@@ -479,49 +734,43 @@ function _resolve(ctor) {
 	return _InjectableRegistry.get(ctor);
 }
 //#endregion
-//#region src/annotation/request.ts
-const _requestSchemaStore = /* @__PURE__ */ new WeakMap();
-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;
+//#region src/annotation/validator.ts
+const _validatorSchemaStore = /* @__PURE__ */ new WeakMap();
+function ResponseBody(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateSchemaDefinition(ctor, fnName), "responseBody", schema, fnName);
+	};
 }
 function RequestBody(schema) {
 	return (target, propertyKey) => {
 		const ctor = target.constructor;
 		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "body", schema, fnName);
+		_setOnce(_getOrCreateSchemaDefinition(ctor, fnName), "requestBody", schema, fnName);
 	};
 }
 function RequestParam(schema) {
 	return (target, propertyKey) => {
 		const ctor = target.constructor;
 		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "param", schema, fnName);
+		_setOnce(_getOrCreateSchemaDefinition(ctor, fnName), "requestParam", schema, fnName);
 	};
 }
 function RequestQuery(schema) {
 	return (target, propertyKey) => {
 		const ctor = target.constructor;
 		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "query", schema, fnName);
+		_setOnce(_getOrCreateSchemaDefinition(ctor, fnName), "requestQuery", schema, fnName);
 	};
 }
-function _getRequestSchemas(ctor, fnName) {
-	return _requestSchemaStore.get(ctor)?.get(fnName);
+function _getOrCreateSchemaDefinition(ctor, fnName) {
+	const byFn = _getOrCreateMap(_validatorSchemaStore, ctor);
+	const existing = byFn.get(fnName);
+	if (existing) return existing;
+	const created = {};
+	byFn.set(fnName, created);
+	return created;
 }
 async function _parseOrThrow(schema, input, kind) {
 	const result = await schema["~standard"].validate(input);
@@ -531,86 +780,12 @@ async function _parseOrThrow(schema, input, kind) {
 	}
 	return result.value;
 }
-//#endregion
-//#region src/annotation/route.ts
-const _routeStore = /* @__PURE__ */ new WeakMap();
-/**
-* Custom annotation that will store all routes inside of a map,
-* which can then be used to initialize all the routes to the router.
-*/
-function _Route({ method, path = "" }) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const list = _routeStore.get(ctor) ?? [];
-		list.push({
-			method,
-			path: path ?? "",
-			fnName: String(propertyKey)
-		});
-		_routeStore.set(ctor, list);
-	};
+function _getValidatorSchema(ctor, fnName) {
+	return _validatorSchemaStore.get(ctor)?.get(fnName);
 }
-/**
-* Register GET route on the given path (default "") for the given controller.
-*/
-const GET = (path = "") => _Route({
-	method: "GET",
-	path
-});
-/**
-* Register POST route on the given path (default "") for the given controller.
-*/
-const POST = (path = "") => _Route({
-	method: "POST",
-	path
-});
-/**
-* Register PUT route on the given path (default "") for the given controller.
-*/
-const PUT = (path = "") => _Route({
-	method: "PUT",
-	path
-});
-/**
-* Register DELETE route on the given path (default "") for the given controller.
-*/
-const DELETE = (path = "") => _Route({
-	method: "DELETE",
-	path
-});
-/**
-* Register OPTIONS route on the given path (default "") for the given controller.
-*/
-const OPTIONS = (path = "") => _Route({
-	method: "OPTIONS",
-	path
-});
-/**
-* Register PATCH route on the given path (default "") for the given controller.
-*/
-const PATCH = (path = "") => _Route({
-	method: "PATCH",
-	path
-});
-/**
-* Register HEAD route on the given path (default "") for the given controller.
-*/
-const HEAD = (path = "") => _Route({
-	method: "HEAD",
-	path
-});
-/**
-* Register a middleware route on the given path (default "") for the given controller.
-*/
-const Middleware = (path = "") => _Route({
-	method: "USE",
-	path
-});
-/**
-* Given a class constructor, fetch all the routes attached.
-*/
-function _getRoutes(ctor) {
-	return _routeStore.get(ctor) ?? [];
+function _setOnce(def, key, schema, fnName) {
+	if (def[key]) throw new Error(`Duplicate schema for "${String(key)}" on method "${fnName}"`);
+	def[key] = schema;
 }
 //#endregion
 //#region src/annotation/controller.ts
@@ -624,6 +799,7 @@ const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 function Controller({ prefix = "", deps = [] } = {}) {
 	return (target) => {
 		const targetClass = target;
+		_registerControllerClass(target, prefix);
 		const router = Router();
 		const routes = _getRoutes(target);
 		const usedRoutes = /* @__PURE__ */ new Set();
@@ -666,12 +842,12 @@ 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);
+				const schemas = _getValidatorSchema(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");
+					if (schemas.requestBody) request.body = await _parseOrThrow(schemas.requestBody, request.body, "reqbody");
+					if (schemas.requestParam) request.params = await _parseOrThrow(schemas.requestParam, request.params, "reqparams");
+					if (schemas.requestQuery) {
+						const parsedQuery = await _parseOrThrow(schemas.requestQuery, request.query, "reqquery");
 						Object.defineProperty(request, "query", {
 							value: parsedQuery,
 							writable: true,
@@ -681,7 +857,8 @@ Split these into separate @MiddlewareClass classes, or merge the logic into a si
 				}
 				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()));
+					const body = schemas && schemas.responseBody ? await _parseOrThrow(schemas.responseBody, result.getBody(), "resbody") : result.getBody();
+					response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(body));
 					return;
 				}
 				if (result instanceof RedirectView) {
@@ -715,7 +892,7 @@ function __decorate(decorators, target, key, desc) {
 	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);
@@ -725,7 +902,17 @@ 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) 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 });
@@ -735,4 +922,39 @@ let DefaultResponseStatusErrorMiddleware = class DefaultResponseStatusErrorMiddl
 __decorate([Middleware()], DefaultResponseStatusErrorMiddleware.prototype, "handle", null);
 DefaultResponseStatusErrorMiddleware = __decorate([MiddlewareClass()], DefaultResponseStatusErrorMiddleware);
 //#endregion
-export { Controller, DELETE, DefaultBaseErrorMiddleware, DefaultResponseStatusErrorMiddleware, GET, HEAD, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRequestSchemas, _getRoutes, _parseOrThrow, _resolve, methodResolve };
+//#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
+let Serve = class Serve {
+	constructor() {
+		this.handlers = swagger.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);
+let Setup = class Setup {
+	constructor() {
+		this.handler = swagger.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);
+const DefaultSwaggerMiddleware = {
+	Serve,
+	Setup
+};
+//#endregion
+export { Controller, ControllerSchema, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, DefaultSwaggerMiddleware, GET, HEAD, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseBody, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteSchema, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getControllerSchema, _getOrCreateSchemaDefinition, _getRouteSchema, _getRoutes, _getValidatorSchema, _parseOrThrow, _registerControllerClass, _resolve, _setControllerSchema, _setOnce, _setRouteSchema, _settings, generateOpenApiSpec, methodResolve, openApiGenerator, setOpenApiConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tahminator/sapling",
-  "version": "2.0.3",
+  "version": "2.0.5-beta.18ab8bae",
   "author": "Tahmid Ahmed",
   "description": "A library to help you write cleaner Express.js code",
   "repository": {
@@ -44,12 +44,14 @@
     "@standard-schema/spec": "^1.1.0",
     "@types/express": "^5",
     "@types/supertest": "^7.2.0",
+    "@types/swagger-ui-express": "^4.1.8",
     "@vitest/coverage-istanbul": "^4.1.2",
     "eslint": "^10.1.0",
     "eslint-plugin-perfectionist": "^5.7.0",
     "globals": "^17.4.0",
     "jiti": "^2.6.1",
     "jsdom": "^29.0.1",
+    "openapi-types": "12.1.3",
     "prettier": "^3.8.1",
     "superjson": "^2.2.6",
     "supertest": "^7.2.2",
@@ -60,6 +62,10 @@
     "zod": "^4.4.3"
   },
   "inlinedDependencies": {
-    "@standard-schema/spec": "1.1.0"
+    "@standard-schema/spec": "1.1.0",
+    "openapi-types": "12.1.3"
+  },
+  "dependencies": {
+    "swagger-ui-express": "^5.0.1"
   }
 }