@tahminator/sapling 2.0.3 → 2.0.5-beta.23c37926

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.
@@ -238,9 +239,13 @@ var ParserError = class ParserError extends ResponseStatusError {
 };
 //#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 +324,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 +342,321 @@ 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;
 	}
 };
 //#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);
+	};
+}
+/**
+* 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
+*      >;
+*    }
+*  }
+* ```
+*/
+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);
+	}
+	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);
+	};
+}
+/**
+* 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/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 = {};
+		for (const { class: controllerClass, prefix } of this.controllers) {
+			const routes = _getRoutes(controllerClass);
+			for (const route of routes) {
+				if (route.method === "USE") continue;
+				const schemas = _getRequestSchemas(controllerClass, route.fnName);
+				const fullPath = route.path instanceof RegExp ? route.path.source : prefix + route.path;
+				const openApiPath = typeof fullPath === "string" ? fullPath.replace(/:(\w+)/g, "{$1}") : fullPath;
+				if (!paths[openApiPath]) paths[openApiPath] = {};
+				const operation = { responses: { "200": { description: "Successful response" } } };
+				const parameters = [];
+				if (schemas?.param) {
+					const paramSchema = this.toJsonSchema(schemas.param);
+					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?.query) {
+					const querySchema = this.toJsonSchema(schemas.query);
+					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?.body) operation.requestBody = {
+					required: true,
+					content: { "application/json": { schema: this.toJsonSchema(schemas.body) } }
+				};
+				const method = route.method.toLowerCase();
+				paths[openApiPath][method] = operation;
+			}
+		}
+		return {
+			openapi: "3.0.0",
+			info: {
+				title: config.title,
+				version: config.version,
+				description: config.description
+			},
+			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,140 +789,6 @@ 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;
-}
-function RequestBody(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "body", schema, fnName);
-	};
-}
-function RequestParam(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "param", schema, fnName);
-	};
-}
-function RequestQuery(schema) {
-	return (target, propertyKey) => {
-		const ctor = target.constructor;
-		const fnName = String(propertyKey);
-		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "query", schema, fnName);
-	};
-}
-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);
-	}
-	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);
-	};
-}
-/**
-* 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/annotation/controller.ts
 const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 /**
@@ -624,6 +800,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();
@@ -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 this.handlers;
+	}
+};
+__decorate([Middleware(_settings.doc.swaggerPath)], Serve.prototype, "handle", null);
+Serve = __decorate([MiddlewareClass()], Serve);
+let Setup = class Setup {
+	constructor() {
+		this.handler = swagger.setup(void 0, { 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, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, DefaultSwaggerMiddleware, GET, HEAD, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _generateOpenApiSpec, _getRequestSchemas, _getRoutes, _parseOrThrow, _registerControllerClass, _resolve, _setOpenApiConfig, _settings, methodResolve, openApiGenerator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tahminator/sapling",
-  "version": "2.0.3",
+  "version": "2.0.5-beta.23c37926",
   "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"
   }
 }