@tahminator/sapling 2.1.0-beta.e797371f → 2.1.1

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,20 +401,38 @@ function __decorate(decorators, target, key, desc) {
 //#region src/middleware/health/registrar.ts
 let HealthRegistrar = class HealthRegistrar {
 	_checks;
-	_sealed;
+	_live;
 	constructor() {
 		this._checks = [];
-		this._sealed = false;
+		this._live = false;
 	}
+	/**
+	* Add a health check.
+	*
+	* Health checks will be used to determine whether service can serve traffic or not (a.k.a `readiness`).
+	*/
 	add(healthCheck) {
 		this._checks.push(healthCheck);
 	}
-	seal() {
-		this._sealed = true;
+	/**
+	* @internal used by Sapling library, used to determine once all
+	* checks have been registered and server is, at the very least, alive.
+	*/
+	_markLive() {
+		this._live = true;
+	}
+	/**
+	* @internal
+	*/
+	async _liveness() {
+		return this._live;
 	}
-	async check() {
-		if (!this._sealed) return false;
-		return (await Promise.all(this._checks.map((c) => c()))).every((c) => c === true);
+	/**
+	* @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);
@@ -423,7 +441,10 @@ HealthRegistrar = __decorate([Injectable()], HealthRegistrar);
 const _settings = {
 	serialize: JSON.stringify,
 	deserialize: JSON.parse,
-	health: { path: "/up" },
+	health: {
+		ready: { path: "/readyz" },
+		live: { path: "/livez" }
+	},
 	doc: {
 		openApiPath: "/openapi.json",
 		swaggerPath: "/swagger.html",
@@ -491,9 +512,8 @@ var Sapling = class Sapling {
 	* import { Sapling } from "@tahminator/sapling";
 	* import express from "express";
 	*
-	* const app = express();
-	*
-	* app.registerApp(app);
+	* // returns the exact same `express.App` type back to you!
+	* const app = Sapling.registerApp(express());
 	* ```
 	*/
 	static registerApp(app) {
@@ -505,7 +525,7 @@ var Sapling = class Sapling {
 				return function(...args) {
 					const server = originalListen.apply(target, args);
 					server.once("listening", () => {
-						Sapling.onStartup();
+						Sapling._onPostStartup();
 						console.log("Sapling successfully initialized post-startup hooks on server start");
 					});
 					return server;
@@ -514,8 +534,12 @@ var Sapling = class Sapling {
 			return Reflect.get(target, prop, receiver);
 		} });
 	}
-	static onStartup() {
-		_InjectableRegistry.get(HealthRegistrar)?.seal();
+	/**
+	* @internal
+	* visible for testing
+	*/
+	static _onPostStartup() {
+		_InjectableRegistry.get(HealthRegistrar)?._markLive();
 	}
 	/**
 	* Serialize a value into a JSON string.
@@ -556,37 +580,59 @@ var Sapling = class Sapling {
 	/**
 	* Modify extra settings
 	*/
-	static Extras = { 
-	/**
-	* Modify default settings applied to OpenAPI & Swagger
-	*/
-swaggerAndOpenApi: {
+	static Extras = {
 		/**
-		* Set base OpenAPI metadata values.
-		*
-		* @default { title: "API", version: "1.0.0" }
+		* Modify default settings applied to OpenAPI & Swagger
 		*/
-		setMetadata(metadata) {
-			_settings.doc.metadata = metadata;
-		},
-		/**
-		* change default endpoint that will serve OpenAPI spec.
-		* Swagger will also load this endpoint on load.
-		*
-		* @default `/openapi.json`
-		*/
-		setOpenApiPath(path) {
-			_settings.doc.openApiPath = path;
+		swaggerAndOpenApi: {
+			/**
+			* Set base OpenAPI metadata values.
+			*
+			* @default { title: "API", version: "1.0.0" }
+			*/
+			setMetadata(metadata) {
+				_settings.doc.metadata = metadata;
+			},
+			/**
+			* change default endpoint that will serve OpenAPI spec.
+			* Swagger will also load this endpoint on load.
+			*
+			* @default `/openapi.json`
+			*/
+			setOpenApiPath(path) {
+				_settings.doc.openApiPath = path;
+			},
+			/**
+			* change Swagger endpoint.
+			*
+			* @default `/swagger.html`
+			*/
+			setSwaggerPath(path) {
+				_settings.doc.swaggerPath = path;
+			}
 		},
 		/**
-		* change Swagger endpoint.
-		*
-		* @default `/swagger.html`
+		* Modify default settings applied to health / readiness / liveness.
 		*/
-		setSwaggerPath(path) {
-			_settings.doc.swaggerPath = path;
+		health: {
+			/**
+			* change default endpoint that ready endpoint will be served on.
+			*
+			* @default `/readyz`
+			*/
+			setReadyPath(path) {
+				_settings.health.ready.path = path;
+			},
+			/**
+			* change default endpoint that live endpoint will be served on.
+			*
+			* @default `/livez`
+			*/
+			setLivePath(path) {
+				_settings.health.live.path = path;
+			}
 		}
-	} };
+	};
 	/**
 	* This method can be used in a `@MiddlewareClass` to register any libraries
 	* that expect you to register multiple registers at once. An example is `swagger-ui-express`
@@ -1179,12 +1225,17 @@ let DefaultHealthMiddleware = class DefaultHealthMiddleware {
 	constructor(healthRegistrar) {
 		this.healthRegistrar = healthRegistrar;
 	}
-	async serve(_request, _response, _next) {
-		const up = await this.healthRegistrar.check();
+	async readiness(_request, _response, _next) {
+		const up = await this.healthRegistrar._readiness();
+		return ResponseEntity.ok().body({ up });
+	}
+	async liveness(_request, _response, _next) {
+		const up = await this.healthRegistrar._liveness();
 		return ResponseEntity.ok().body({ up });
 	}
 };
-__decorate([GET(_settings.health.path)], DefaultHealthMiddleware.prototype, "serve", null);
+__decorate([GET(_settings.health.ready.path)], DefaultHealthMiddleware.prototype, "readiness", null);
+__decorate([GET(_settings.health.live.path)], DefaultHealthMiddleware.prototype, "liveness", null);
 DefaultHealthMiddleware = __decorate([MiddlewareClass({ deps: [HealthRegistrar] })], DefaultHealthMiddleware);
 //#endregion
 exports.Controller = Controller;

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>;
@@ -795,7 +795,12 @@ type Settings = {
   serialize: (value: any) => string;
   deserialize: (value: string) => any;
   health: {
-    path: string;
+    ready: {
+      path: string;
+    };
+    live: {
+      path: string;
+    };
   };
   doc: {
     openApiPath: string;
@@ -843,13 +848,16 @@ declare class Sapling {
    * import { Sapling } from "@tahminator/sapling";
    * import express from "express";
    *
-   * const app = express();
-   *
-   * app.registerApp(app);
+   * // returns the exact same `express.App` type back to you!
+   * const app = Sapling.registerApp(express());
    * ```
    */
   static registerApp(app: e.Express): e.Express;
-  static onStartup(): void;
+  /**
+   * @internal
+   * visible for testing
+   */
+  static _onPostStartup(): void;
   /**
    * Serialize a value into a JSON string.
    *
@@ -906,6 +914,23 @@ declare class Sapling {
        */
       setSwaggerPath(this: void, path: string): void;
     };
+    /**
+     * Modify default settings applied to health / readiness / liveness.
+     */
+    health: {
+      /**
+       * change default endpoint that ready endpoint will be served on.
+       *
+       * @default `/readyz`
+       */
+      setReadyPath(this: void, path: string): void;
+      /**
+       * change default endpoint that live endpoint will be served on.
+       *
+       * @default `/livez`
+       */
+      setLivePath(this: void, path: string): void;
+    };
   };
   /**
    * This method can be used in a `@MiddlewareClass` to register any libraries
@@ -926,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
@@ -982,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;
   }>;
 }
@@ -993,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;
 }
@@ -1004,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;
 }
@@ -1027,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
@@ -1049,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.
@@ -1070,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.
@@ -1097,18 +1122,42 @@ declare const DefaultSwaggerMiddleware: {
 type HealthCheck = () => boolean | Promise<boolean>;
 declare class HealthRegistrar {
   private _checks;
-  private _sealed;
+  private _live;
   constructor();
+  /**
+   * Add a health check.
+   *
+   * Health checks will be used to determine whether service can serve traffic or not (a.k.a `readiness`).
+   */
   add(healthCheck: HealthCheck): void;
-  seal(): void;
-  check(): Promise<boolean>;
+  /**
+   * @internal used by Sapling library, used to determine once all
+   * checks have been registered and server is, at the very least, alive.
+   */
+  _markLive(): void;
+  /**
+   * @internal
+   */
+  _liveness(): Promise<boolean>;
+  /**
+   * @internal
+   */
+  _readiness(): Promise<boolean>;
 }
 //#endregion
 //#region src/middleware/default/health/index.d.ts
+/**
+ * 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);
-  serve(_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$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>;
@@ -795,7 +795,12 @@ type Settings = {
   serialize: (value: any) => string;
   deserialize: (value: string) => any;
   health: {
-    path: string;
+    ready: {
+      path: string;
+    };
+    live: {
+      path: string;
+    };
   };
   doc: {
     openApiPath: string;
@@ -843,13 +848,16 @@ declare class Sapling {
    * import { Sapling } from "@tahminator/sapling";
    * import express from "express";
    *
-   * const app = express();
-   *
-   * app.registerApp(app);
+   * // returns the exact same `express.App` type back to you!
+   * const app = Sapling.registerApp(express());
    * ```
    */
   static registerApp(app: e.Express): e.Express;
-  static onStartup(): void;
+  /**
+   * @internal
+   * visible for testing
+   */
+  static _onPostStartup(): void;
   /**
    * Serialize a value into a JSON string.
    *
@@ -906,6 +914,23 @@ declare class Sapling {
        */
       setSwaggerPath(this: void, path: string): void;
     };
+    /**
+     * Modify default settings applied to health / readiness / liveness.
+     */
+    health: {
+      /**
+       * change default endpoint that ready endpoint will be served on.
+       *
+       * @default `/readyz`
+       */
+      setReadyPath(this: void, path: string): void;
+      /**
+       * change default endpoint that live endpoint will be served on.
+       *
+       * @default `/livez`
+       */
+      setLivePath(this: void, path: string): void;
+    };
   };
   /**
    * This method can be used in a `@MiddlewareClass` to register any libraries
@@ -926,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
@@ -982,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;
   }>;
 }
@@ -993,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;
 }
@@ -1004,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;
 }
@@ -1027,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
@@ -1049,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.
@@ -1070,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.
@@ -1097,18 +1122,42 @@ declare const DefaultSwaggerMiddleware: {
 type HealthCheck = () => boolean | Promise<boolean>;
 declare class HealthRegistrar {
   private _checks;
-  private _sealed;
+  private _live;
   constructor();
+  /**
+   * Add a health check.
+   *
+   * Health checks will be used to determine whether service can serve traffic or not (a.k.a `readiness`).
+   */
   add(healthCheck: HealthCheck): void;
-  seal(): void;
-  check(): Promise<boolean>;
+  /**
+   * @internal used by Sapling library, used to determine once all
+   * checks have been registered and server is, at the very least, alive.
+   */
+  _markLive(): void;
+  /**
+   * @internal
+   */
+  _liveness(): Promise<boolean>;
+  /**
+   * @internal
+   */
+  _readiness(): Promise<boolean>;
 }
 //#endregion
 //#region src/middleware/default/health/index.d.ts
+/**
+ * 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);
-  serve(_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$1, _next: NextFunction): Promise<ResponseEntity<{
     up: boolean;
   }>>;
 }

package/dist/index.mjs

@@ -376,20 +376,38 @@ function __decorate(decorators, target, key, desc) {
 //#region src/middleware/health/registrar.ts
 let HealthRegistrar = class HealthRegistrar {
 	_checks;
-	_sealed;
+	_live;
 	constructor() {
 		this._checks = [];
-		this._sealed = false;
+		this._live = false;
 	}
+	/**
+	* Add a health check.
+	*
+	* Health checks will be used to determine whether service can serve traffic or not (a.k.a `readiness`).
+	*/
 	add(healthCheck) {
 		this._checks.push(healthCheck);
 	}
-	seal() {
-		this._sealed = true;
+	/**
+	* @internal used by Sapling library, used to determine once all
+	* checks have been registered and server is, at the very least, alive.
+	*/
+	_markLive() {
+		this._live = true;
+	}
+	/**
+	* @internal
+	*/
+	async _liveness() {
+		return this._live;
 	}
-	async check() {
-		if (!this._sealed) return false;
-		return (await Promise.all(this._checks.map((c) => c()))).every((c) => c === true);
+	/**
+	* @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);
@@ -398,7 +416,10 @@ HealthRegistrar = __decorate([Injectable()], HealthRegistrar);
 const _settings = {
 	serialize: JSON.stringify,
 	deserialize: JSON.parse,
-	health: { path: "/up" },
+	health: {
+		ready: { path: "/readyz" },
+		live: { path: "/livez" }
+	},
 	doc: {
 		openApiPath: "/openapi.json",
 		swaggerPath: "/swagger.html",
@@ -466,9 +487,8 @@ var Sapling = class Sapling {
 	* import { Sapling } from "@tahminator/sapling";
 	* import express from "express";
 	*
-	* const app = express();
-	*
-	* app.registerApp(app);
+	* // returns the exact same `express.App` type back to you!
+	* const app = Sapling.registerApp(express());
 	* ```
 	*/
 	static registerApp(app) {
@@ -480,7 +500,7 @@ var Sapling = class Sapling {
 				return function(...args) {
 					const server = originalListen.apply(target, args);
 					server.once("listening", () => {
-						Sapling.onStartup();
+						Sapling._onPostStartup();
 						console.log("Sapling successfully initialized post-startup hooks on server start");
 					});
 					return server;
@@ -489,8 +509,12 @@ var Sapling = class Sapling {
 			return Reflect.get(target, prop, receiver);
 		} });
 	}
-	static onStartup() {
-		_InjectableRegistry.get(HealthRegistrar)?.seal();
+	/**
+	* @internal
+	* visible for testing
+	*/
+	static _onPostStartup() {
+		_InjectableRegistry.get(HealthRegistrar)?._markLive();
 	}
 	/**
 	* Serialize a value into a JSON string.
@@ -531,37 +555,59 @@ var Sapling = class Sapling {
 	/**
 	* Modify extra settings
 	*/
-	static Extras = { 
-	/**
-	* Modify default settings applied to OpenAPI & Swagger
-	*/
-swaggerAndOpenApi: {
+	static Extras = {
 		/**
-		* Set base OpenAPI metadata values.
-		*
-		* @default { title: "API", version: "1.0.0" }
+		* Modify default settings applied to OpenAPI & Swagger
 		*/
-		setMetadata(metadata) {
-			_settings.doc.metadata = metadata;
-		},
-		/**
-		* change default endpoint that will serve OpenAPI spec.
-		* Swagger will also load this endpoint on load.
-		*
-		* @default `/openapi.json`
-		*/
-		setOpenApiPath(path) {
-			_settings.doc.openApiPath = path;
+		swaggerAndOpenApi: {
+			/**
+			* Set base OpenAPI metadata values.
+			*
+			* @default { title: "API", version: "1.0.0" }
+			*/
+			setMetadata(metadata) {
+				_settings.doc.metadata = metadata;
+			},
+			/**
+			* change default endpoint that will serve OpenAPI spec.
+			* Swagger will also load this endpoint on load.
+			*
+			* @default `/openapi.json`
+			*/
+			setOpenApiPath(path) {
+				_settings.doc.openApiPath = path;
+			},
+			/**
+			* change Swagger endpoint.
+			*
+			* @default `/swagger.html`
+			*/
+			setSwaggerPath(path) {
+				_settings.doc.swaggerPath = path;
+			}
 		},
 		/**
-		* change Swagger endpoint.
-		*
-		* @default `/swagger.html`
+		* Modify default settings applied to health / readiness / liveness.
 		*/
-		setSwaggerPath(path) {
-			_settings.doc.swaggerPath = path;
+		health: {
+			/**
+			* change default endpoint that ready endpoint will be served on.
+			*
+			* @default `/readyz`
+			*/
+			setReadyPath(path) {
+				_settings.health.ready.path = path;
+			},
+			/**
+			* change default endpoint that live endpoint will be served on.
+			*
+			* @default `/livez`
+			*/
+			setLivePath(path) {
+				_settings.health.live.path = path;
+			}
 		}
-	} };
+	};
 	/**
 	* This method can be used in a `@MiddlewareClass` to register any libraries
 	* that expect you to register multiple registers at once. An example is `swagger-ui-express`
@@ -1154,12 +1200,17 @@ let DefaultHealthMiddleware = class DefaultHealthMiddleware {
 	constructor(healthRegistrar) {
 		this.healthRegistrar = healthRegistrar;
 	}
-	async serve(_request, _response, _next) {
-		const up = await this.healthRegistrar.check();
+	async readiness(_request, _response, _next) {
+		const up = await this.healthRegistrar._readiness();
+		return ResponseEntity.ok().body({ up });
+	}
+	async liveness(_request, _response, _next) {
+		const up = await this.healthRegistrar._liveness();
 		return ResponseEntity.ok().body({ up });
 	}
 };
-__decorate([GET(_settings.health.path)], DefaultHealthMiddleware.prototype, "serve", null);
+__decorate([GET(_settings.health.ready.path)], DefaultHealthMiddleware.prototype, "readiness", null);
+__decorate([GET(_settings.health.live.path)], DefaultHealthMiddleware.prototype, "liveness", null);
 DefaultHealthMiddleware = __decorate([MiddlewareClass({ deps: [HealthRegistrar] })], DefaultHealthMiddleware);
 //#endregion
 export { Controller, ControllerSchema, DELETE, DefaultBaseErrorMiddleware, DefaultHealthMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, DefaultSwaggerMiddleware, GET, HEAD, HealthRegistrar, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseBody, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteSchema, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _clearOpenApiRegistry, _getControllerSchema, _getOrCreateSchemaDefinition, _getRouteSchema, _getRoutes, _getValidatorSchema, _parseOrThrow, _registerController, _resolve, _saveValidatorSchema, _setControllerSchema, _setRouteSchema, _settings, generateOpenApiSpec, methodResolve, openApiGenerator };

package/package.json

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