@tahminator/sapling 2.1.0-beta.6ea2cd3e → 2.1.0-beta.845ac846

package/README.md

@@ -26,6 +26,10 @@ A lightweight Express.js dependency injection & route abstraction library.
     + [Automatic Spec Generation](#automatic-spec-generation)
     + [Adding Documentation with Decorators](#adding-documentation-with-decorators)
     + [Customizing Paths](#customizing-paths)
+  * [Health Checks](#health-checks)
+    + [Liveness and Readiness Probes](#liveness-and-readiness-probes)
+    + [Registering Custom Readiness Checks](#registering-custom-readiness-checks)
+    + [Customizing Health Paths](#customizing-health-paths)
   * [Custom Serialization](#custom-serialization)
 - [Advanced Setup](#advanced-setup)
   * [Automatically import controllers](#automatically-import-controllers)
@@ -97,9 +101,10 @@ class UserController {
   }
 }
 
-// you still have full access of app to do whatever you want!
-const app = express();
-Sapling.registerApp(app);
+// registerApp returns the app back to you - use the returned app instance
+// so Sapling can inject some post-startup hooks into the app.
+// BUT, you still have full access of app to do whatever you want!
+const app = Sapling.registerApp(express());
 
 // @MiddlewareClass should be registered first before @Controller and should be registered in order
 // @Injectable classes will automatically be formed into singletons by Sapling behind the scenes!
@@ -581,6 +586,57 @@ Sapling.Extras.swaggerAndOpenApi.setOpenApiPath("/api-spec.json");
 Sapling.Extras.swaggerAndOpenApi.setSwaggerPath("/api-docs");
 ```
 
+### Health Checks
+
+#### Liveness and Readiness Probes
+
+Register `DefaultHealthMiddleware` to expose two health endpoints:
+
+- `GET /live` — **liveness probe**: returns `{ up: true }` once the server has started listening. Use this to tell your orchestrator the process is alive.
+- `GET /ready` — **readiness probe**: returns `{ up: true }` once the server is live *and* all registered readiness checks pass. Use this to gate traffic until your app is fully initialized.
+
+```typescript
+import { Sapling, DefaultHealthMiddleware } from "@tahminator/sapling";
+
+const app = Sapling.registerApp(express());
+
+app.use(Sapling.resolve(DefaultHealthMiddleware));
+
+app.listen(3000); // _markLive() is called automatically once the server is listening
+```
+
+> [!IMPORTANT]
+> `Sapling.registerApp` returns `express.App` - please use that as your `app` object inside of your server. There is a small post-startup hook applied via a proxy, in which the liveness probe is enabled from such.
+
+#### Registering Custom Readiness Checks
+
+Inject `HealthRegistrar` into any `@Injectable` or controller to add readiness checks. A check is any function returning `boolean | Promise<boolean>`. If any check returns `false` (or throws), `/ready` reports `{ up: false }`.
+
+```typescript
+import { Injectable, HealthRegistrar } from "@tahminator/sapling";
+
+@Injectable([HealthRegistrar])
+class DatabaseService {
+  constructor(
+    private readonly db: Database,
+    private readonly healthRegistrar: HealthRegistrar,
+  ) {
+    healthRegistrar.add(async () => {
+      return this.db.isConnected();
+    });
+  }
+}
+```
+
+#### Customizing Health Paths
+
+The default paths are `/live` and `/ready`. Override them before registering `DefaultHealthMiddleware`:
+
+```typescript
+Sapling.Extras.health.setLivePath("/healthz/live");
+Sapling.Extras.health.setReadyPath("/healthz/ready");
+```
+
 ### Custom Serialization
 
 By default, Sapling uses `JSON.stringify` and `JSON.parse` for serialization. You can override these with custom serializers like [superjson](https://github.com/flightcontrolhq/superjson#readme) to automatically handle Dates, BigInts, and more:

package/dist/index.cjs

@@ -401,15 +401,15 @@ function __decorate(decorators, target, key, desc) {
 //#region src/middleware/health/registrar.ts
 let HealthRegistrar = class HealthRegistrar {
 	_checks;
-	_ready;
+	_live;
 	constructor() {
 		this._checks = [];
-		this._ready = false;
+		this._live = false;
 	}
 	/**
 	* Add a health check.
 	*
-	* Health checks will be used to determine whether service can service traffic or not (a.k.a `liveness`).
+	* Health checks will be used to determine whether service can serve traffic or not (a.k.a `readiness`).
 	*/
 	add(healthCheck) {
 		this._checks.push(healthCheck);
@@ -418,12 +418,21 @@ let HealthRegistrar = class HealthRegistrar {
 	* @internal used by Sapling library, used to determine once all
 	* checks have been registered and server is, at the very least, alive.
 	*/
-	_markReady() {
-		this._ready = true;
+	_markLive() {
+		this._live = true;
 	}
-	async check() {
-		if (!this._ready) return false;
-		return (await Promise.all(this._checks.map((c) => c()))).every((c) => c === true);
+	/**
+	* @internal
+	*/
+	async _liveness() {
+		return this._live;
+	}
+	/**
+	* @internal
+	*/
+	async _readiness() {
+		if (!this._live) return false;
+		return (await Promise.allSettled(this._checks.map((c) => c()))).every((r) => r.status === "fulfilled" && r.value);
 	}
 };
 HealthRegistrar = __decorate([Injectable()], HealthRegistrar);
@@ -433,8 +442,8 @@ const _settings = {
 	serialize: JSON.stringify,
 	deserialize: JSON.parse,
 	health: {
-		ready: { path: "/up" },
-		live: { path: "/live" }
+		ready: { path: "/readyz" },
+		live: { path: "/livez" }
 	},
 	doc: {
 		openApiPath: "/openapi.json",
@@ -516,7 +525,7 @@ var Sapling = class Sapling {
 				return function(...args) {
 					const server = originalListen.apply(target, args);
 					server.once("listening", () => {
-						Sapling.onPostStartup();
+						Sapling._onPostStartup();
 						console.log("Sapling successfully initialized post-startup hooks on server start");
 					});
 					return server;
@@ -525,8 +534,12 @@ var Sapling = class Sapling {
 			return Reflect.get(target, prop, receiver);
 		} });
 	}
-	static onPostStartup() {
-		_InjectableRegistry.get(HealthRegistrar)?._markReady();
+	/**
+	* @internal
+	* visible for testing
+	*/
+	static _onPostStartup() {
+		_InjectableRegistry.get(HealthRegistrar)?._markLive();
 	}
 	/**
 	* Serialize a value into a JSON string.
@@ -605,7 +618,7 @@ var Sapling = class Sapling {
 			/**
 			* change default endpoint that ready endpoint will be served on.
 			*
-			* @default `/up`
+			* @default `/readyz`
 			*/
 			setReadyPath(path) {
 				_settings.health.ready.path = path;
@@ -613,7 +626,7 @@ var Sapling = class Sapling {
 			/**
 			* change default endpoint that live endpoint will be served on.
 			*
-			* @default `/live`
+			* @default `/livez`
 			*/
 			setLivePath(path) {
 				_settings.health.live.path = path;
@@ -1213,11 +1226,11 @@ let DefaultHealthMiddleware = class DefaultHealthMiddleware {
 		this.healthRegistrar = healthRegistrar;
 	}
 	async readiness(_request, _response, _next) {
-		const up = await this.healthRegistrar.check();
+		const up = await this.healthRegistrar._readiness();
 		return ResponseEntity.ok().body({ up });
 	}
 	async liveness(_request, _response, _next) {
-		const up = await this.healthRegistrar.check();
+		const up = await this.healthRegistrar._liveness();
 		return ResponseEntity.ok().body({ up });
 	}
 };

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import e, { ErrorRequestHandler, NextFunction, Request as Request$1, RequestHandler, 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
 /**
@@ -26,7 +26,7 @@ type RouteDefinition = {
 };
 type Class<T> = new (...args: any[]) => T;
 type HttpHeaders = Record<string, string>;
-type ExpressMiddlewareFn = ($1: Request$1, $2: Response$1, $3: NextFunction) => void;
+type ExpressMiddlewareFn = ($1: Request, $2: Response$1, $3: NextFunction) => void;
 //#endregion
 //#region src/annotation/controller.d.ts
 declare const _ControllerRegistry: WeakMap<Function, Router | ErrorRequestHandler>;
@@ -853,7 +853,11 @@ declare class Sapling {
    * ```
    */
   static registerApp(app: e.Express): e.Express;
-  static onPostStartup(): void;
+  /**
+   * @internal
+   * visible for testing
+   */
+  static _onPostStartup(): void;
   /**
    * Serialize a value into a JSON string.
    *
@@ -917,13 +921,13 @@ declare class Sapling {
       /**
        * change default endpoint that ready endpoint will be served on.
        *
-       * @default `/up`
+       * @default `/readyz`
        */
       setReadyPath(this: void, path: string): void;
       /**
        * change default endpoint that live endpoint will be served on.
        *
-       * @default `/live`
+       * @default `/livez`
        */
       setLivePath(this: void, path: string): void;
     };
@@ -947,7 +951,7 @@ declare class Sapling {
    *  }
    * ```
    */
-  static chainHandlers(this: void, handlers: RequestHandler[], request: Request$1, response: Response$1, next: NextFunction, index?: number): void;
+  static chainHandlers(this: void, handlers: RequestHandler[], request: Request, response: Response$1, next: NextFunction, index?: number): void;
 }
 //#endregion
 //#region src/annotation/validator.d.ts
@@ -1003,7 +1007,7 @@ declare function _getControllerSchema(ctor: Function): ControllerSchemaDefinitio
  * If the default is not suitable, you may also easily write your own.
  */
 declare class DefaultBaseErrorMiddleware {
-  handle(err: unknown, _request: Request$1, _response: Response$1, _next: NextFunction): ResponseEntity<{
+  handle(err: unknown, _request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<{
     message: string;
   }>;
 }
@@ -1014,7 +1018,7 @@ declare class DefaultBaseErrorMiddleware {
  * If the default is not suitable, you may also easily write your own.
  */
 declare class DefaultParserErrorMiddleware {
-  handle(err: unknown, _request: Request$1, _response: Response$1, next: NextFunction): ResponseEntity<{
+  handle(err: unknown, _request: Request, _response: Response$1, next: NextFunction): ResponseEntity<{
     message: string;
   }> | undefined;
 }
@@ -1025,7 +1029,7 @@ declare class DefaultParserErrorMiddleware {
  * If the default is not suitable, you may also easily write your own.
  */
 declare class DefaultResponseStatusErrorMiddleware {
-  handle(err: unknown, _request: Request$1, _response: Response$1, next: NextFunction): ResponseEntity<{
+  handle(err: unknown, _request: Request, _response: Response$1, next: NextFunction): ResponseEntity<{
     message: string;
   }> | undefined;
 }
@@ -1048,7 +1052,7 @@ declare class DefaultResponseStatusErrorMiddleware {
  * ```
  */
 declare class DefaultOpenApiMiddleware {
-  handle(_request: Request$1, _response: Response$1, _next: NextFunction): ResponseEntity<OpenAPIV3.Document<{}>>;
+  handle(_request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<OpenAPIV3.Document<{}>>;
 }
 //#endregion
 //#region src/middleware/default/swagger/index.d.ts
@@ -1070,7 +1074,7 @@ declare class DefaultOpenApiMiddleware {
  */
 declare class Serve {
   private readonly handlers;
-  handle(request: Request$1, response: Response$1, next: NextFunction): void;
+  handle(request: Request, response: Response$1, next: NextFunction): void;
 }
 /**
  * Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
@@ -1091,7 +1095,7 @@ declare class Serve {
 declare class Setup {
   private readonly handler;
   constructor();
-  handle(request: Request$1, response: Response$1, next: NextFunction): unknown;
+  handle(request: Request, response: Response$1, next: NextFunction): unknown;
 }
 /**
  * Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
@@ -1118,20 +1122,27 @@ declare const DefaultSwaggerMiddleware: {
 type HealthCheck = () => boolean | Promise<boolean>;
 declare class HealthRegistrar {
   private _checks;
-  private _ready;
+  private _live;
   constructor();
   /**
    * Add a health check.
    *
-   * Health checks will be used to determine whether service can service traffic or not (a.k.a `liveness`).
+   * Health checks will be used to determine whether service can serve traffic or not (a.k.a `readiness`).
    */
   add(healthCheck: HealthCheck): void;
   /**
    * @internal used by Sapling library, used to determine once all
    * checks have been registered and server is, at the very least, alive.
    */
-  _markReady(): void;
-  check(): Promise<boolean>;
+  _markLive(): void;
+  /**
+   * @internal
+   */
+  _liveness(): Promise<boolean>;
+  /**
+   * @internal
+   */
+  _readiness(): Promise<boolean>;
 }
 //#endregion
 //#region src/middleware/default/health/index.d.ts
@@ -1139,15 +1150,14 @@ declare class HealthRegistrar {
  * Enable the serving of `ready` and `live` endpoints.
  *
  * Configure any middleware-specific settings with `Sapling.Extras.health`
- * ```
  */
 declare class DefaultHealthMiddleware {
   private readonly healthRegistrar;
   constructor(healthRegistrar: HealthRegistrar);
-  readiness(_request: Request, _response: Response, _next: NextFunction): Promise<ResponseEntity<{
+  readiness(_request: Request, _response: Response$1, _next: NextFunction): Promise<ResponseEntity<{
     up: boolean;
   }>>;
-  liveness(_request: Request, _response: Response, _next: NextFunction): Promise<ResponseEntity<{
+  liveness(_request: Request, _response: Response$1, _next: NextFunction): Promise<ResponseEntity<{
     up: boolean;
   }>>;
 }

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import e, { ErrorRequestHandler, NextFunction, Request as Request$1, RequestHandler, 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
 /**
@@ -26,7 +26,7 @@ type RouteDefinition = {
 };
 type Class<T> = new (...args: any[]) => T;
 type HttpHeaders = Record<string, string>;
-type ExpressMiddlewareFn = ($1: Request$1, $2: Response$1, $3: NextFunction) => void;
+type ExpressMiddlewareFn = ($1: Request, $2: Response$1, $3: NextFunction) => void;
 //#endregion
 //#region src/annotation/controller.d.ts
 declare const _ControllerRegistry: WeakMap<Function, Router | ErrorRequestHandler>;
@@ -853,7 +853,11 @@ declare class Sapling {
    * ```
    */
   static registerApp(app: e.Express): e.Express;
-  static onPostStartup(): void;
+  /**
+   * @internal
+   * visible for testing
+   */
+  static _onPostStartup(): void;
   /**
    * Serialize a value into a JSON string.
    *
@@ -917,13 +921,13 @@ declare class Sapling {
       /**
        * change default endpoint that ready endpoint will be served on.
        *
-       * @default `/up`
+       * @default `/readyz`
        */
       setReadyPath(this: void, path: string): void;
       /**
        * change default endpoint that live endpoint will be served on.
        *
-       * @default `/live`
+       * @default `/livez`
        */
       setLivePath(this: void, path: string): void;
     };
@@ -947,7 +951,7 @@ declare class Sapling {
    *  }
    * ```
    */
-  static chainHandlers(this: void, handlers: RequestHandler[], request: Request$1, response: Response$1, next: NextFunction, index?: number): void;
+  static chainHandlers(this: void, handlers: RequestHandler[], request: Request, response: Response$1, next: NextFunction, index?: number): void;
 }
 //#endregion
 //#region src/annotation/validator.d.ts
@@ -1003,7 +1007,7 @@ declare function _getControllerSchema(ctor: Function): ControllerSchemaDefinitio
  * If the default is not suitable, you may also easily write your own.
  */
 declare class DefaultBaseErrorMiddleware {
-  handle(err: unknown, _request: Request$1, _response: Response$1, _next: NextFunction): ResponseEntity<{
+  handle(err: unknown, _request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<{
     message: string;
   }>;
 }
@@ -1014,7 +1018,7 @@ declare class DefaultBaseErrorMiddleware {
  * If the default is not suitable, you may also easily write your own.
  */
 declare class DefaultParserErrorMiddleware {
-  handle(err: unknown, _request: Request$1, _response: Response$1, next: NextFunction): ResponseEntity<{
+  handle(err: unknown, _request: Request, _response: Response$1, next: NextFunction): ResponseEntity<{
     message: string;
   }> | undefined;
 }
@@ -1025,7 +1029,7 @@ declare class DefaultParserErrorMiddleware {
  * If the default is not suitable, you may also easily write your own.
  */
 declare class DefaultResponseStatusErrorMiddleware {
-  handle(err: unknown, _request: Request$1, _response: Response$1, next: NextFunction): ResponseEntity<{
+  handle(err: unknown, _request: Request, _response: Response$1, next: NextFunction): ResponseEntity<{
     message: string;
   }> | undefined;
 }
@@ -1048,7 +1052,7 @@ declare class DefaultResponseStatusErrorMiddleware {
  * ```
  */
 declare class DefaultOpenApiMiddleware {
-  handle(_request: Request$1, _response: Response$1, _next: NextFunction): ResponseEntity<OpenAPIV3.Document<{}>>;
+  handle(_request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<OpenAPIV3.Document<{}>>;
 }
 //#endregion
 //#region src/middleware/default/swagger/index.d.ts
@@ -1070,7 +1074,7 @@ declare class DefaultOpenApiMiddleware {
  */
 declare class Serve {
   private readonly handlers;
-  handle(request: Request$1, response: Response$1, next: NextFunction): void;
+  handle(request: Request, response: Response$1, next: NextFunction): void;
 }
 /**
  * Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
@@ -1091,7 +1095,7 @@ declare class Serve {
 declare class Setup {
   private readonly handler;
   constructor();
-  handle(request: Request$1, response: Response$1, next: NextFunction): unknown;
+  handle(request: Request, response: Response$1, next: NextFunction): unknown;
 }
 /**
  * Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
@@ -1118,20 +1122,27 @@ declare const DefaultSwaggerMiddleware: {
 type HealthCheck = () => boolean | Promise<boolean>;
 declare class HealthRegistrar {
   private _checks;
-  private _ready;
+  private _live;
   constructor();
   /**
    * Add a health check.
    *
-   * Health checks will be used to determine whether service can service traffic or not (a.k.a `liveness`).
+   * Health checks will be used to determine whether service can serve traffic or not (a.k.a `readiness`).
    */
   add(healthCheck: HealthCheck): void;
   /**
    * @internal used by Sapling library, used to determine once all
    * checks have been registered and server is, at the very least, alive.
    */
-  _markReady(): void;
-  check(): Promise<boolean>;
+  _markLive(): void;
+  /**
+   * @internal
+   */
+  _liveness(): Promise<boolean>;
+  /**
+   * @internal
+   */
+  _readiness(): Promise<boolean>;
 }
 //#endregion
 //#region src/middleware/default/health/index.d.ts
@@ -1139,15 +1150,14 @@ declare class HealthRegistrar {
  * Enable the serving of `ready` and `live` endpoints.
  *
  * Configure any middleware-specific settings with `Sapling.Extras.health`
- * ```
  */
 declare class DefaultHealthMiddleware {
   private readonly healthRegistrar;
   constructor(healthRegistrar: HealthRegistrar);
-  readiness(_request: Request, _response: Response, _next: NextFunction): Promise<ResponseEntity<{
+  readiness(_request: Request, _response: Response$1, _next: NextFunction): Promise<ResponseEntity<{
     up: boolean;
   }>>;
-  liveness(_request: Request, _response: Response, _next: NextFunction): Promise<ResponseEntity<{
+  liveness(_request: Request, _response: Response$1, _next: NextFunction): Promise<ResponseEntity<{
     up: boolean;
   }>>;
 }

package/dist/index.mjs

@@ -376,15 +376,15 @@ function __decorate(decorators, target, key, desc) {
 //#region src/middleware/health/registrar.ts
 let HealthRegistrar = class HealthRegistrar {
 	_checks;
-	_ready;
+	_live;
 	constructor() {
 		this._checks = [];
-		this._ready = false;
+		this._live = false;
 	}
 	/**
 	* Add a health check.
 	*
-	* Health checks will be used to determine whether service can service traffic or not (a.k.a `liveness`).
+	* Health checks will be used to determine whether service can serve traffic or not (a.k.a `readiness`).
 	*/
 	add(healthCheck) {
 		this._checks.push(healthCheck);
@@ -393,12 +393,21 @@ let HealthRegistrar = class HealthRegistrar {
 	* @internal used by Sapling library, used to determine once all
 	* checks have been registered and server is, at the very least, alive.
 	*/
-	_markReady() {
-		this._ready = true;
+	_markLive() {
+		this._live = true;
 	}
-	async check() {
-		if (!this._ready) return false;
-		return (await Promise.all(this._checks.map((c) => c()))).every((c) => c === true);
+	/**
+	* @internal
+	*/
+	async _liveness() {
+		return this._live;
+	}
+	/**
+	* @internal
+	*/
+	async _readiness() {
+		if (!this._live) return false;
+		return (await Promise.allSettled(this._checks.map((c) => c()))).every((r) => r.status === "fulfilled" && r.value);
 	}
 };
 HealthRegistrar = __decorate([Injectable()], HealthRegistrar);
@@ -408,8 +417,8 @@ const _settings = {
 	serialize: JSON.stringify,
 	deserialize: JSON.parse,
 	health: {
-		ready: { path: "/up" },
-		live: { path: "/live" }
+		ready: { path: "/readyz" },
+		live: { path: "/livez" }
 	},
 	doc: {
 		openApiPath: "/openapi.json",
@@ -491,7 +500,7 @@ var Sapling = class Sapling {
 				return function(...args) {
 					const server = originalListen.apply(target, args);
 					server.once("listening", () => {
-						Sapling.onPostStartup();
+						Sapling._onPostStartup();
 						console.log("Sapling successfully initialized post-startup hooks on server start");
 					});
 					return server;
@@ -500,8 +509,12 @@ var Sapling = class Sapling {
 			return Reflect.get(target, prop, receiver);
 		} });
 	}
-	static onPostStartup() {
-		_InjectableRegistry.get(HealthRegistrar)?._markReady();
+	/**
+	* @internal
+	* visible for testing
+	*/
+	static _onPostStartup() {
+		_InjectableRegistry.get(HealthRegistrar)?._markLive();
 	}
 	/**
 	* Serialize a value into a JSON string.
@@ -580,7 +593,7 @@ var Sapling = class Sapling {
 			/**
 			* change default endpoint that ready endpoint will be served on.
 			*
-			* @default `/up`
+			* @default `/readyz`
 			*/
 			setReadyPath(path) {
 				_settings.health.ready.path = path;
@@ -588,7 +601,7 @@ var Sapling = class Sapling {
 			/**
 			* change default endpoint that live endpoint will be served on.
 			*
-			* @default `/live`
+			* @default `/livez`
 			*/
 			setLivePath(path) {
 				_settings.health.live.path = path;
@@ -1188,11 +1201,11 @@ let DefaultHealthMiddleware = class DefaultHealthMiddleware {
 		this.healthRegistrar = healthRegistrar;
 	}
 	async readiness(_request, _response, _next) {
-		const up = await this.healthRegistrar.check();
+		const up = await this.healthRegistrar._readiness();
 		return ResponseEntity.ok().body({ up });
 	}
 	async liveness(_request, _response, _next) {
-		const up = await this.healthRegistrar.check();
+		const up = await this.healthRegistrar._liveness();
 		return ResponseEntity.ok().body({ up });
 	}
 };

package/package.json

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