@tahminator/sapling 2.0.3 → 2.0.5-beta.2f539758

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

@@ -264,7 +264,8 @@ var ParserError = class ParserError extends ResponseStatusError {
 //#region src/helper/sapling.ts
 const settings = {
 	serialize: JSON.stringify,
-	deserialize: JSON.parse
+	deserialize: JSON.parse,
+	openapi: { path: "/openapi.json" }
 };
 /**
 * Collection of utility functions which are essential for Sapling to function.
@@ -369,7 +370,304 @@ var Sapling = class Sapling {
 	static setDeserializeFn(fn) {
 		settings.deserialize = fn;
 	}
+	static setOpenApiPath(path) {
+		settings.openapi.path = 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) {
+		return schema["~standard"].jsonSchema.output({ target: "openapi-3.0" });
+	}
 };
+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 = {
@@ -503,140 +801,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();
 /**
@@ -648,6 +812,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();
@@ -739,7 +904,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);
@@ -749,7 +914,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 });
@@ -759,6 +934,15 @@ 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("/openapi.json")], DefaultOpenApiMiddleware.prototype, "handle", null);
+DefaultOpenApiMiddleware = __decorate([MiddlewareClass()], DefaultOpenApiMiddleware);
+//#endregion
 exports.Controller = Controller;
 exports.DELETE = DELETE;
 Object.defineProperty(exports, "DefaultBaseErrorMiddleware", {
@@ -767,6 +951,18 @@ 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() {
@@ -800,5 +996,9 @@ exports._Route = _Route;
 exports._getRequestSchemas = _getRequestSchemas;
 exports._getRoutes = _getRoutes;
 exports._parseOrThrow = _parseOrThrow;
+exports._registerControllerClass = _registerControllerClass;
 exports._resolve = _resolve;
+exports.generateOpenApiSpec = generateOpenApiSpec;
 exports.methodResolve = methodResolve;
+exports.openApiGenerator = openApiGenerator;
+exports.setOpenApiConfig = setOpenApiConfig;