@tahminator/sapling 2.0.5-beta.2f539758 → 2.0.5-beta.30231b0a

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,10 +264,13 @@ var ParserError = class ParserError extends ResponseStatusError {
 };
 //#endregion
 //#region src/helper/sapling.ts
-const settings = {
+const _settings = {
 	serialize: JSON.stringify,
 	deserialize: JSON.parse,
-	openapi: { path: "/openapi.json" }
+	doc: {
+		openApiPath: "/openapi.json",
+		swaggerPath: "/swagger.html"
+	}
 };
 /**
 * Collection of utility functions which are essential for Sapling to function.
@@ -344,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.
@@ -362,16 +367,32 @@ 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.openapi.path = 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
@@ -655,17 +676,22 @@ var OpenAPIGenerator = class {
 		};
 	}
 	toJsonSchema(schema) {
-		return schema["~standard"].jsonSchema.output({ target: "openapi-3.0" });
+		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) {
+function _setOpenApiConfig(config) {
 	openApiGenerator.setConfig(config);
 }
-function generateOpenApiSpec() {
+function _generateOpenApiSpec() {
 	return openApiGenerator.generateSpec();
 }
 //#endregion
@@ -937,12 +963,38 @@ DefaultResponseStatusErrorMiddleware = __decorate([MiddlewareClass()], DefaultRe
 //#region src/middleware/default/openapi/index.ts
 let DefaultOpenApiMiddleware = class DefaultOpenApiMiddleware {
 	handle(_request, _response, _next) {
-		return ResponseEntity.ok().body(generateOpenApiSpec());
+		return ResponseEntity.ok().body(_generateOpenApiSpec());
 	}
 };
-__decorate([GET("/openapi.json")], DefaultOpenApiMiddleware.prototype, "handle", null);
+__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 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_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);
+const DefaultSwaggerMiddleware = {
+	Serve,
+	Setup
+};
+//#endregion
 exports.Controller = Controller;
 exports.DELETE = DELETE;
 Object.defineProperty(exports, "DefaultBaseErrorMiddleware", {
@@ -969,6 +1021,7 @@ Object.defineProperty(exports, "DefaultResponseStatusErrorMiddleware", {
 		return DefaultResponseStatusErrorMiddleware;
 	}
 });
+exports.DefaultSwaggerMiddleware = DefaultSwaggerMiddleware;
 exports.GET = GET;
 exports.HEAD = HEAD;
 exports.Html404ErrorPage = Html404ErrorPage;
@@ -993,12 +1046,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.generateOpenApiSpec = generateOpenApiSpec;
+exports._setOpenApiConfig = _setOpenApiConfig;
+exports._settings = _settings;
 exports.methodResolve = methodResolve;
 exports.openApiGenerator = openApiGenerator;
-exports.setOpenApiConfig = setOpenApiConfig;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import e, { ErrorRequestHandler, NextFunction, Request, Response as Response$1, Router } from "express";
+import e, { ErrorRequestHandler, NextFunction, Request, RequestHandler, Response as Response$1, Router } from "express";
 
 //#region src/html/404.d.ts
 /**
@@ -447,6 +447,15 @@ declare class ParserError extends ResponseStatusError {
 }
 //#endregion
 //#region src/helper/sapling.d.ts
+type Settings = {
+  serialize: (value: any) => string;
+  deserialize: (value: string) => any;
+  doc: {
+    openApiPath: string;
+    swaggerPath: string;
+  };
+};
+declare const _settings: Settings;
 /**
  * Collection of utility functions which are essential for Sapling to function.
  */
@@ -521,6 +530,8 @@ declare class Sapling {
    */
   static setDeserializeFn(this: void, fn: (value: string) => any): void;
   static setOpenApiPath(this: void, path: string): void;
+  static setSwaggerPath(this: void, path: string): void;
+  static chainHandlers(this: void, handlers: RequestHandler[], request: Request, response: Response$1, next: NextFunction, index?: number): void;
 }
 //#endregion
 //#region node_modules/.pnpm/openapi-types@12.1.3/node_modules/openapi-types/dist/index.d.ts
@@ -859,8 +870,8 @@ declare class OpenAPIGenerator {
 }
 declare const openApiGenerator: OpenAPIGenerator;
 declare function _registerControllerClass(controllerClass: Function, prefix: string): void;
-declare function setOpenApiConfig(config: OpenAPIConfig): void;
-declare function generateOpenApiSpec(): OpenAPIV3.Document;
+declare function _setOpenApiConfig(config: OpenAPIConfig): void;
+declare function _generateOpenApiSpec(): OpenAPIV3.Document;
 //#endregion
 //#region src/annotation/request.d.ts
 type RequestSchemaDefinition = {
@@ -979,4 +990,19 @@ declare class DefaultOpenApiMiddleware {
   handle(_request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<OpenAPIV3.Document<{}>>;
 }
 //#endregion
-export { Class, Controller, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, ParserErrorLocation, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRequestSchemas, _getRoutes, _parseOrThrow, _registerControllerClass, _resolve, generateOpenApiSpec, methodResolve, openApiGenerator, setOpenApiConfig };
+//#region src/middleware/default/swagger/index.d.ts
+declare class Serve {
+  private readonly handlers;
+  handle(request: Request, response: Response$1, next: NextFunction): void;
+}
+declare class Setup {
+  private readonly handler;
+  constructor();
+  handle(request: Request, response: Response$1, next: NextFunction): unknown;
+}
+declare const DefaultSwaggerMiddleware: {
+  Serve: typeof Serve;
+  Setup: typeof Setup;
+};
+//#endregion
+export { Class, Controller, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, DefaultSwaggerMiddleware, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, ParserErrorLocation, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _generateOpenApiSpec, _getRequestSchemas, _getRoutes, _parseOrThrow, _registerControllerClass, _resolve, _setOpenApiConfig, _settings, methodResolve, openApiGenerator };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import e, { ErrorRequestHandler, NextFunction, Request, Response as Response$1, Router } from "express";
+import e, { ErrorRequestHandler, NextFunction, Request, RequestHandler, Response as Response$1, Router } from "express";
 
 //#region src/html/404.d.ts
 /**
@@ -447,6 +447,15 @@ declare class ParserError extends ResponseStatusError {
 }
 //#endregion
 //#region src/helper/sapling.d.ts
+type Settings = {
+  serialize: (value: any) => string;
+  deserialize: (value: string) => any;
+  doc: {
+    openApiPath: string;
+    swaggerPath: string;
+  };
+};
+declare const _settings: Settings;
 /**
  * Collection of utility functions which are essential for Sapling to function.
  */
@@ -521,6 +530,8 @@ declare class Sapling {
    */
   static setDeserializeFn(this: void, fn: (value: string) => any): void;
   static setOpenApiPath(this: void, path: string): void;
+  static setSwaggerPath(this: void, path: string): void;
+  static chainHandlers(this: void, handlers: RequestHandler[], request: Request, response: Response$1, next: NextFunction, index?: number): void;
 }
 //#endregion
 //#region node_modules/.pnpm/openapi-types@12.1.3/node_modules/openapi-types/dist/index.d.ts
@@ -859,8 +870,8 @@ declare class OpenAPIGenerator {
 }
 declare const openApiGenerator: OpenAPIGenerator;
 declare function _registerControllerClass(controllerClass: Function, prefix: string): void;
-declare function setOpenApiConfig(config: OpenAPIConfig): void;
-declare function generateOpenApiSpec(): OpenAPIV3.Document;
+declare function _setOpenApiConfig(config: OpenAPIConfig): void;
+declare function _generateOpenApiSpec(): OpenAPIV3.Document;
 //#endregion
 //#region src/annotation/request.d.ts
 type RequestSchemaDefinition = {
@@ -979,4 +990,19 @@ declare class DefaultOpenApiMiddleware {
   handle(_request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<OpenAPIV3.Document<{}>>;
 }
 //#endregion
-export { Class, Controller, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, ParserErrorLocation, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRequestSchemas, _getRoutes, _parseOrThrow, _registerControllerClass, _resolve, generateOpenApiSpec, methodResolve, openApiGenerator, setOpenApiConfig };
+//#region src/middleware/default/swagger/index.d.ts
+declare class Serve {
+  private readonly handlers;
+  handle(request: Request, response: Response$1, next: NextFunction): void;
+}
+declare class Setup {
+  private readonly handler;
+  constructor();
+  handle(request: Request, response: Response$1, next: NextFunction): unknown;
+}
+declare const DefaultSwaggerMiddleware: {
+  Serve: typeof Serve;
+  Setup: typeof Setup;
+};
+//#endregion
+export { Class, Controller, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, DefaultSwaggerMiddleware, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, ParserErrorLocation, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _generateOpenApiSpec, _getRequestSchemas, _getRoutes, _parseOrThrow, _registerControllerClass, _resolve, _setOpenApiConfig, _settings, methodResolve, openApiGenerator };

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,10 +239,13 @@ var ParserError = class ParserError extends ResponseStatusError {
 };
 //#endregion
 //#region src/helper/sapling.ts
-const settings = {
+const _settings = {
 	serialize: JSON.stringify,
 	deserialize: JSON.parse,
-	openapi: { path: "/openapi.json" }
+	doc: {
+		openApiPath: "/openapi.json",
+		swaggerPath: "/swagger.html"
+	}
 };
 /**
 * Collection of utility functions which are essential for Sapling to function.
@@ -320,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.
@@ -338,16 +342,32 @@ 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.openapi.path = 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
@@ -631,17 +651,22 @@ var OpenAPIGenerator = class {
 		};
 	}
 	toJsonSchema(schema) {
-		return schema["~standard"].jsonSchema.output({ target: "openapi-3.0" });
+		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) {
+function _setOpenApiConfig(config) {
 	openApiGenerator.setConfig(config);
 }
-function generateOpenApiSpec() {
+function _generateOpenApiSpec() {
 	return openApiGenerator.generateSpec();
 }
 //#endregion
@@ -913,10 +938,36 @@ DefaultResponseStatusErrorMiddleware = __decorate([MiddlewareClass()], DefaultRe
 //#region src/middleware/default/openapi/index.ts
 let DefaultOpenApiMiddleware = class DefaultOpenApiMiddleware {
 	handle(_request, _response, _next) {
-		return ResponseEntity.ok().body(generateOpenApiSpec());
+		return ResponseEntity.ok().body(_generateOpenApiSpec());
 	}
 };
-__decorate([GET("/openapi.json")], DefaultOpenApiMiddleware.prototype, "handle", null);
+__decorate([GET(_settings.doc.openApiPath)], DefaultOpenApiMiddleware.prototype, "handle", null);
 DefaultOpenApiMiddleware = __decorate([MiddlewareClass()], DefaultOpenApiMiddleware);
 //#endregion
-export { Controller, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, 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, _registerControllerClass, _resolve, generateOpenApiSpec, methodResolve, openApiGenerator, setOpenApiConfig };
+//#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, 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.5-beta.2f539758",
+  "version": "2.0.5-beta.30231b0a",
   "author": "Tahmid Ahmed",
   "description": "A library to help you write cleaner Express.js code",
   "repository": {
@@ -44,13 +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",
-    "openapi-types": "12.1.3",
     "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",
@@ -63,5 +64,8 @@
   "inlinedDependencies": {
     "@standard-schema/spec": "1.1.0",
     "openapi-types": "12.1.3"
+  },
+  "dependencies": {
+    "swagger-ui-express": "^5.0.1"
   }
 }