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

package/README.md

@@ -200,12 +200,71 @@ class UserController {
 }
 ```
 
-Make sure to register an error handler middleware:
+Sapling ships with default error middlewares, and you can also write your own.
+Register error middlewares after your regular middlewares and controllers:
 
 ```typescript
-Sapling.loadResponseStatusErrorMiddleware(app, (err, req, res, next) => {
-  res.status(err.status).json({ error: err.message });
-});
+import {
+  DefaultBaseErrorMiddleware,
+  DefaultResponseStatusErrorMiddleware,
+} from "@tahminator/sapling";
+
+// regular middlewares & controllers first
+const middlewares: Class<any>[] = [CookieParserMiddleware];
+middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+
+const controllers: Class<any>[] = [UserController];
+controllers.map(Sapling.resolve).forEach((r) => app.use(r));
+
+// error middlewares last
+const errorMiddlewares: Class<any>[] = [
+  DefaultResponseStatusErrorMiddleware,
+  DefaultBaseErrorMiddleware,
+];
+errorMiddlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+```
+
+You can also write your own error middlewares. A specific handler should call
+`next(err)` when it does not handle the error, and a base handler should be last
+and return a response:
+
+```typescript
+@MiddlewareClass()
+class ResponseStatusErrorMiddleware {
+  @Middleware()
+  handle(
+    err: unknown,
+    _request: Request,
+    _response: Response,
+    next: NextFunction,
+  ) {
+    if (err instanceof ResponseStatusError) {
+      return ResponseEntity.status(err.status).body({ message: err.message });
+    }
+
+    // MUST call next(err) to continue the chain
+    next(err);
+  }
+}
+
+@MiddlewareClass()
+class BaseErrorMiddleware {
+  @Middleware()
+  handle(
+    err: unknown,
+    _request: Request,
+    _response: Response,
+    _next: NextFunction,
+  ) {
+    console.error("[Error]", err);
+
+    return ResponseEntity.status(500).body({
+      message: "Internal Server Error",
+    });
+
+    // no next(err) since last middleware in chain, we are done propagating
+  }
+}
 ```
 
 ### Middleware
@@ -234,10 +293,41 @@ class CookieParserMiddleware {
 // Register it like any controller
 app.use(Sapling.resolve(CookieParserMiddleware));
 
+// Register middlewares before controllers
+app.use(Sapling.resolve(UserController));
+
 // You can also still choose to load plugins the Express.js way
 app.use(cookieParser());
 ```
 
+You can also write custom middlewares as well. It is functionally the same way as Express: call `next()` explicitly to
+continue down the chain:
+
+```typescript
+import { MiddlewareClass, Middleware } from "@tahminator/sapling";
+import { NextFunction, Request, Response } from "express";
+
+@MiddlewareClass()
+class RequestTimerMiddleware {
+  @Middleware()
+  handle(request: Request, _response: Response, next: NextFunction) {
+    const start = Date.now();
+
+    request.on("finish", () => {
+      const elapsedMs = Date.now() - start;
+      console.log(`[Request] ${request.method} ${request.path} ${elapsedMs}ms`);
+    });
+
+    // MUST call next() to continue the chain
+    next();
+  }
+}
+
+// Register middlewares before controllers
+app.use(Sapling.resolve(RequestTimerMiddleware));
+app.use(Sapling.resolve(UserController));
+```
+
 ### Request Validation
 
 Validate and transform request bodies, route params, and query strings at the controller level using `@RequestBody`, `@RequestParam`, and `@RequestQuery`. These decorators accept any [Standard Schema](https://github.com/standard-schema/standard-schema) compatible validator (Zod, Valibot, ArkType, etc.).

package/dist/index.cjs

@@ -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.
@@ -262,9 +264,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.
@@ -343,13 +349,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.
@@ -361,148 +367,22 @@ 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;
 	}
-};
-//#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.
-*/
-var IterableWeakMap = class IterableWeakMap {
-	#weakMap = /* @__PURE__ */ new WeakMap();
-	#refSet = /* @__PURE__ */ new Set();
-	#finalizationGroup = new FinalizationRegistry(IterableWeakMap.#cleanup);
-	static #cleanup(heldValue) {
-		heldValue.set.delete(heldValue.ref);
+	static setOpenApiPath(path) {
+		_settings.doc.openApiPath = path;
 	}
-	constructor(iterable) {
-		if (iterable) for (const [key, value] of iterable) this.set(key, value);
-	}
-	set(key, value) {
-		const ref = new WeakRef(key);
-		this.#weakMap.set(key, {
-			value,
-			ref
-		});
-		this.#refSet.add(ref);
-		this.#finalizationGroup.register(key, {
-			set: this.#refSet,
-			ref
-		}, ref);
-		return this;
-	}
-	get(key) {
-		return this.#weakMap.get(key)?.value;
-	}
-	delete(key) {
-		const entry = this.#weakMap.get(key);
-		if (!entry) return false;
-		this.#weakMap.delete(key);
-		this.#refSet.delete(entry.ref);
-		this.#finalizationGroup.unregister(entry.ref);
-		return true;
-	}
-	*[Symbol.iterator]() {
-		for (const ref of this.#refSet) {
-			const key = ref.deref();
-			if (!key) continue;
-			const entry = this.#weakMap.get(key);
-			if (entry) yield [key, entry.value];
-		}
-	}
-	entries() {
-		return this[Symbol.iterator]();
-	}
-	*keys() {
-		for (const [key] of this) yield key;
-	}
-	*values() {
-		for (const [, value] of this) yield value;
-	}
-	forEach(callback, thisArg) {
-		for (const [key, value] of this) callback.call(thisArg, value, key, this);
+	static setSwaggerPath(path) {
+		_settings.doc.swaggerPath = path;
 	}
 };
 //#endregion
-//#region src/annotation/injectable.ts
-const _InjectableRegistry = /* @__PURE__ */ new WeakMap();
-const _InjectableDeps = new IterableWeakMap();
-/**
-* Mark the class as an injectable to be handled by Sapling. The class can now be
-* be injected into other classes, as well as allow the class to inject other `@Injectable` classes.
-*
-* @argument deps - An optional array to define any dependencies that this class may require.
-*/
-function Injectable(deps = []) {
-	return function(target) {
-		_InjectableRegistry.set(target, null);
-		_InjectableDeps.set(target, deps);
-	};
-}
-/**
-* Resolves and instantiates a class along with all of it's transitive dependencies.
-*
-* Uses topological sort (Kahn's algorithm) to ensure that the dependency graph is created
-* in a correct order.
-*
-* When `resolve` is first called (usually during controller registration),
-* it will compute the dependency graph of all `@Injectable` classes and instantiates
-* them in the correct order.
-*
-* Subsequent calls to dependencies that have already been resolved are cached, so they will
-* re-use the created singletons instead of re-instantiation.
-*/
-function _resolve(ctor) {
-	const inDegree = /* @__PURE__ */ new Map();
-	const graph = /* @__PURE__ */ new Map();
-	_InjectableDeps.forEach((deps, node) => {
-		inDegree.set(node, inDegree.get(node) || 0);
-		deps.forEach((dep) => {
-			if (dep === void 0) throw new Error(`There is an @Injectable (${node.name}) which has a dependency that cannot be found. This is likely caused by a circular dependency.`);
-			inDegree.set(dep, inDegree.get(dep) || 0);
-			inDegree.set(node, inDegree.get(node) + 1);
-			if (!graph.has(dep)) graph.set(dep, []);
-			graph.get(dep).push(node);
-		});
-	});
-	const queue = [];
-	inDegree.forEach((deg, node) => {
-		if (deg === 0) queue.push(node);
-	});
-	while (queue.length) {
-		const current = queue.shift();
-		if (!_InjectableRegistry.get(current)) {
-			const instance = new current(...(_InjectableDeps.get(current) || []).map((dep) => _InjectableRegistry.get(dep)));
-			_InjectableRegistry.set(current, instance);
-		}
-		(graph.get(current) || []).forEach((neighbor) => {
-			inDegree.set(neighbor, (inDegree.get(neighbor) ?? 0) - 1);
-			if (inDegree.get(neighbor) === 0) queue.push(neighbor);
-		});
-	}
-	if (!_InjectableRegistry.get(ctor)) throw new Error("Circular dependency detected or injectable not registered");
-	return _InjectableRegistry.get(ctor);
-}
-//#endregion
 //#region src/annotation/request.ts
 const _requestSchemaStore = /* @__PURE__ */ new WeakMap();
 /**
@@ -711,6 +591,229 @@ 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",
+	PUT: "put",
+	POST: "post",
+	DELETE: "delete",
+	OPTIONS: "options",
+	PATCH: "patch",
+	HEAD: "head",
+	USE: "use"
+};
+//#endregion
+//#region lib/weakmap.ts
+/**
+* WeakMap that is iterable.
+*/
+var IterableWeakMap = class IterableWeakMap {
+	#weakMap = /* @__PURE__ */ new WeakMap();
+	#refSet = /* @__PURE__ */ new Set();
+	#finalizationGroup = new FinalizationRegistry(IterableWeakMap.#cleanup);
+	static #cleanup(heldValue) {
+		heldValue.set.delete(heldValue.ref);
+	}
+	constructor(iterable) {
+		if (iterable) for (const [key, value] of iterable) this.set(key, value);
+	}
+	set(key, value) {
+		const ref = new WeakRef(key);
+		this.#weakMap.set(key, {
+			value,
+			ref
+		});
+		this.#refSet.add(ref);
+		this.#finalizationGroup.register(key, {
+			set: this.#refSet,
+			ref
+		}, ref);
+		return this;
+	}
+	get(key) {
+		return this.#weakMap.get(key)?.value;
+	}
+	delete(key) {
+		const entry = this.#weakMap.get(key);
+		if (!entry) return false;
+		this.#weakMap.delete(key);
+		this.#refSet.delete(entry.ref);
+		this.#finalizationGroup.unregister(entry.ref);
+		return true;
+	}
+	*[Symbol.iterator]() {
+		for (const ref of this.#refSet) {
+			const key = ref.deref();
+			if (!key) continue;
+			const entry = this.#weakMap.get(key);
+			if (entry) yield [key, entry.value];
+		}
+	}
+	entries() {
+		return this[Symbol.iterator]();
+	}
+	*keys() {
+		for (const [key] of this) yield key;
+	}
+	*values() {
+		for (const [, value] of this) yield value;
+	}
+	forEach(callback, thisArg) {
+		for (const [key, value] of this) callback.call(thisArg, value, key, this);
+	}
+};
+//#endregion
+//#region src/annotation/injectable.ts
+const _InjectableRegistry = /* @__PURE__ */ new WeakMap();
+const _InjectableDeps = new IterableWeakMap();
+/**
+* Mark the class as an injectable to be handled by Sapling. The class can now be
+* be injected into other classes, as well as allow the class to inject other `@Injectable` classes.
+*
+* @argument deps - An optional array to define any dependencies that this class may require.
+*/
+function Injectable(deps = []) {
+	return function(target) {
+		_InjectableRegistry.set(target, null);
+		_InjectableDeps.set(target, deps);
+	};
+}
+/**
+* Resolves and instantiates a class along with all of it's transitive dependencies.
+*
+* Uses topological sort (Kahn's algorithm) to ensure that the dependency graph is created
+* in a correct order.
+*
+* When `resolve` is first called (usually during controller registration),
+* it will compute the dependency graph of all `@Injectable` classes and instantiates
+* them in the correct order.
+*
+* Subsequent calls to dependencies that have already been resolved are cached, so they will
+* re-use the created singletons instead of re-instantiation.
+*/
+function _resolve(ctor) {
+	const inDegree = /* @__PURE__ */ new Map();
+	const graph = /* @__PURE__ */ new Map();
+	_InjectableDeps.forEach((deps, node) => {
+		inDegree.set(node, inDegree.get(node) || 0);
+		deps.forEach((dep) => {
+			if (dep === void 0) throw new Error(`There is an @Injectable (${node.name}) which has a dependency that cannot be found. This is likely caused by a circular dependency.`);
+			inDegree.set(dep, inDegree.get(dep) || 0);
+			inDegree.set(node, inDegree.get(node) + 1);
+			if (!graph.has(dep)) graph.set(dep, []);
+			graph.get(dep).push(node);
+		});
+	});
+	const queue = [];
+	inDegree.forEach((deg, node) => {
+		if (deg === 0) queue.push(node);
+	});
+	while (queue.length) {
+		const current = queue.shift();
+		if (!_InjectableRegistry.get(current)) {
+			const instance = new current(...(_InjectableDeps.get(current) || []).map((dep) => _InjectableRegistry.get(dep)));
+			_InjectableRegistry.set(current, instance);
+		}
+		(graph.get(current) || []).forEach((neighbor) => {
+			inDegree.set(neighbor, (inDegree.get(neighbor) ?? 0) - 1);
+			if (inDegree.get(neighbor) === 0) queue.push(neighbor);
+		});
+	}
+	if (!_InjectableRegistry.get(ctor)) throw new Error("Circular dependency detected or injectable not registered");
+	return _InjectableRegistry.get(ctor);
+}
+//#endregion
 //#region src/annotation/controller.ts
 const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 /**
@@ -722,6 +825,7 @@ const _ControllerRegistry = /* @__PURE__ */ new WeakMap();
 function Controller({ prefix = "", deps = [] } = {}) {
 	return (target) => {
 		const targetClass = target;
+		_registerControllerClass(target, prefix);
 		const router = (0, express.Router)();
 		const routes = _getRoutes(target);
 		const usedRoutes = /* @__PURE__ */ new Set();
@@ -813,7 +917,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);
@@ -823,7 +927,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 });
@@ -833,6 +947,41 @@ 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
+let Serve = class Serve {
+	constructor() {
+		this.handlers = swagger_ui_express.default.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_ui_express.default.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
 exports.Controller = Controller;
 exports.DELETE = DELETE;
 Object.defineProperty(exports, "DefaultBaseErrorMiddleware", {
@@ -841,12 +990,25 @@ Object.defineProperty(exports, "DefaultBaseErrorMiddleware", {
 		return DefaultBaseErrorMiddleware;
 	}
 });
+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;
 exports.Html404ErrorPage = Html404ErrorPage;
@@ -871,8 +1033,13 @@ exports._ControllerRegistry = _ControllerRegistry;
 exports._InjectableDeps = _InjectableDeps;
 exports._InjectableRegistry = _InjectableRegistry;
 exports._Route = _Route;
+exports._generateOpenApiSpec = _generateOpenApiSpec;
 exports._getRequestSchemas = _getRequestSchemas;
 exports._getRoutes = _getRoutes;
 exports._parseOrThrow = _parseOrThrow;
+exports._registerControllerClass = _registerControllerClass;
 exports._resolve = _resolve;
+exports._setOpenApiConfig = _setOpenApiConfig;
+exports._settings = _settings;
 exports.methodResolve = methodResolve;
+exports.openApiGenerator = openApiGenerator;