@tahminator/sapling 2.0.4 → 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,148 +342,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();
 /**
@@ -687,6 +566,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();
 /**
@@ -698,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();
@@ -789,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);
@@ -799,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 });
@@ -809,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.4",
+  "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"
   }
 }