@tahminator/sapling 2.0.3 → 2.0.5

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

@@ -505,24 +505,31 @@ function _resolve(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;
-}
+/**
+* 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;
@@ -530,6 +537,30 @@ function RequestBody(schema) {
 		_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;
@@ -537,6 +568,31 @@ function RequestParam(schema) {
 		_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;
@@ -544,6 +600,24 @@ function RequestQuery(schema) {
 		_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);
 }

package/dist/index.d.cts

@@ -489,8 +489,82 @@ type RequestSchemaDefinition = {
   param?: StandardSchemaV1;
   query?: StandardSchemaV1;
 };
+/**
+ * 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
+ *      >;
+ *    }
+ *  }
+ * ```
+ */
 declare function RequestBody(schema: StandardSchemaV1): MethodDecorator;
+/**
+ * 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
+ *      >;
+ *    }
+ *  }
+ * ```
+ */
 declare function RequestParam(schema: StandardSchemaV1): MethodDecorator;
+/**
+ * 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
+ *      >;
+ *    }
+ *  }
+ * ```
+ */
 declare function RequestQuery(schema: StandardSchemaV1): MethodDecorator;
 declare function _getRequestSchemas(ctor: Function, fnName: string): RequestSchemaDefinition | undefined;
 declare function _parseOrThrow<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown, kind: ParserErrorLocation): Promise<StandardSchemaV1.InferOutput<TSchema>>;

package/dist/index.d.mts

@@ -489,8 +489,82 @@ type RequestSchemaDefinition = {
   param?: StandardSchemaV1;
   query?: StandardSchemaV1;
 };
+/**
+ * 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
+ *      >;
+ *    }
+ *  }
+ * ```
+ */
 declare function RequestBody(schema: StandardSchemaV1): MethodDecorator;
+/**
+ * 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
+ *      >;
+ *    }
+ *  }
+ * ```
+ */
 declare function RequestParam(schema: StandardSchemaV1): MethodDecorator;
+/**
+ * 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
+ *      >;
+ *    }
+ *  }
+ * ```
+ */
 declare function RequestQuery(schema: StandardSchemaV1): MethodDecorator;
 declare function _getRequestSchemas(ctor: Function, fnName: string): RequestSchemaDefinition | undefined;
 declare function _parseOrThrow<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown, kind: ParserErrorLocation): Promise<StandardSchemaV1.InferOutput<TSchema>>;

package/dist/index.mjs

@@ -481,24 +481,31 @@ function _resolve(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;
-}
+/**
+* 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;
@@ -506,6 +513,30 @@ function RequestBody(schema) {
 		_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;
@@ -513,6 +544,31 @@ function RequestParam(schema) {
 		_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;
@@ -520,6 +576,24 @@ function RequestQuery(schema) {
 		_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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tahminator/sapling",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "author": "Tahmid Ahmed",
   "description": "A library to help you write cleaner Express.js code",
   "repository": {