@tahminator/sapling 2.1.0-beta.0e8a97e8 → 2.1.0-beta.419f8e67

package/dist/index.cjs

@@ -401,19 +401,37 @@ function __decorate(decorators, target, key, desc) {
 //#region src/middleware/health/registrar.ts
 let HealthRegistrar = class HealthRegistrar {
 	_checks;
-	_sealed;
+	_ready;
 	constructor() {
 		this._checks = [];
-		this._sealed = false;
+		this._ready = false;
 	}
+	/**
+	* Add a health check.
+	*
+	* Health checks will be used to determine whether service can serve traffic or not (a.k.a `liveness`).
+	*/
 	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.
+	*/
+	_markReady() {
+		this._ready = true;
+	}
+	/**
+	* @internal
+	*/
+	async ready() {
+		return this._ready;
 	}
-	async check() {
-		if (!this._sealed) return false;
+	/**
+	* @internal
+	*/
+	async live() {
+		if (!this._ready) return false;
 		return (await Promise.all(this._checks.map((c) => c()))).every((c) => c === true);
 	}
 };
@@ -423,7 +441,10 @@ HealthRegistrar = __decorate([Injectable()], HealthRegistrar);
 const _settings = {
 	serialize: JSON.stringify,
 	deserialize: JSON.parse,
-	health: { path: "/up" },
+	health: {
+		ready: { path: "/ready" },
+		live: { path: "/live" }
+	},
 	doc: {
 		openApiPath: "/openapi.json",
 		swaggerPath: "/swagger.html",
@@ -491,15 +512,30 @@ 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) {
 		app.use(express.default.text({ type: "application/json" }));
 		app.use(Sapling.json());
-		_InjectableRegistry.get(HealthRegistrar)?.seal();
+		return new Proxy(app, { get(target, prop, receiver) {
+			if (prop === "listen") {
+				const originalListen = target[prop];
+				return function(...args) {
+					const server = originalListen.apply(target, args);
+					server.once("listening", () => {
+						Sapling.onPostStartup();
+						console.log("Sapling successfully initialized post-startup hooks on server start");
+					});
+					return server;
+				};
+			}
+			return Reflect.get(target, prop, receiver);
+		} });
+	}
+	static onPostStartup() {
+		_InjectableRegistry.get(HealthRegistrar)?._markReady();
 	}
 	/**
 	* Serialize a value into a JSON string.
@@ -540,37 +576,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 `/ready`
+			*/
+			setReadyPath(path) {
+				_settings.health.ready.path = path;
+			},
+			/**
+			* change default endpoint that live endpoint will be served on.
+			*
+			* @default `/live`
+			*/
+			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`
@@ -1163,12 +1221,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.ready();
+		return ResponseEntity.ok().body({ up });
+	}
+	async liveness(_request, _response, _next) {
+		const up = await this.healthRegistrar.live();
 		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

@@ -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,12 +848,12 @@ 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): void;
+  static registerApp(app: e.Express): e.Express;
+  static onPostStartup(): void;
   /**
    * Serialize a value into a JSON string.
    *
@@ -905,6 +910,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 `/ready`
+       */
+      setReadyPath(this: void, path: string): void;
+      /**
+       * change default endpoint that live endpoint will be served on.
+       *
+       * @default `/live`
+       */
+      setLivePath(this: void, path: string): void;
+    };
   };
   /**
    * This method can be used in a `@MiddlewareClass` to register any libraries
@@ -1096,18 +1118,43 @@ declare const DefaultSwaggerMiddleware: {
 type HealthCheck = () => boolean | Promise<boolean>;
 declare class HealthRegistrar {
   private _checks;
-  private _sealed;
+  private _ready;
   constructor();
+  /**
+   * Add a health check.
+   *
+   * Health checks will be used to determine whether service can serve traffic or not (a.k.a `liveness`).
+   */
   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.
+   */
+  _markReady(): void;
+  /**
+   * @internal
+   */
+  ready(): Promise<boolean>;
+  /**
+   * @internal
+   */
+  live(): 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, _next: NextFunction): Promise<ResponseEntity<{
+    up: boolean;
+  }>>;
+  liveness(_request: Request, _response: Response, _next: NextFunction): Promise<ResponseEntity<{
     up: boolean;
   }>>;
 }

package/dist/index.d.mts

@@ -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,12 +848,12 @@ 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): void;
+  static registerApp(app: e.Express): e.Express;
+  static onPostStartup(): void;
   /**
    * Serialize a value into a JSON string.
    *
@@ -905,6 +910,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 `/ready`
+       */
+      setReadyPath(this: void, path: string): void;
+      /**
+       * change default endpoint that live endpoint will be served on.
+       *
+       * @default `/live`
+       */
+      setLivePath(this: void, path: string): void;
+    };
   };
   /**
    * This method can be used in a `@MiddlewareClass` to register any libraries
@@ -1096,18 +1118,43 @@ declare const DefaultSwaggerMiddleware: {
 type HealthCheck = () => boolean | Promise<boolean>;
 declare class HealthRegistrar {
   private _checks;
-  private _sealed;
+  private _ready;
   constructor();
+  /**
+   * Add a health check.
+   *
+   * Health checks will be used to determine whether service can serve traffic or not (a.k.a `liveness`).
+   */
   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.
+   */
+  _markReady(): void;
+  /**
+   * @internal
+   */
+  ready(): Promise<boolean>;
+  /**
+   * @internal
+   */
+  live(): 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, _next: NextFunction): Promise<ResponseEntity<{
+    up: boolean;
+  }>>;
+  liveness(_request: Request, _response: Response, _next: NextFunction): Promise<ResponseEntity<{
     up: boolean;
   }>>;
 }

package/dist/index.mjs

@@ -376,19 +376,37 @@ function __decorate(decorators, target, key, desc) {
 //#region src/middleware/health/registrar.ts
 let HealthRegistrar = class HealthRegistrar {
 	_checks;
-	_sealed;
+	_ready;
 	constructor() {
 		this._checks = [];
-		this._sealed = false;
+		this._ready = false;
 	}
+	/**
+	* Add a health check.
+	*
+	* Health checks will be used to determine whether service can serve traffic or not (a.k.a `liveness`).
+	*/
 	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.
+	*/
+	_markReady() {
+		this._ready = true;
+	}
+	/**
+	* @internal
+	*/
+	async ready() {
+		return this._ready;
 	}
-	async check() {
-		if (!this._sealed) return false;
+	/**
+	* @internal
+	*/
+	async live() {
+		if (!this._ready) return false;
 		return (await Promise.all(this._checks.map((c) => c()))).every((c) => c === true);
 	}
 };
@@ -398,7 +416,10 @@ HealthRegistrar = __decorate([Injectable()], HealthRegistrar);
 const _settings = {
 	serialize: JSON.stringify,
 	deserialize: JSON.parse,
-	health: { path: "/up" },
+	health: {
+		ready: { path: "/ready" },
+		live: { path: "/live" }
+	},
 	doc: {
 		openApiPath: "/openapi.json",
 		swaggerPath: "/swagger.html",
@@ -466,15 +487,30 @@ 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) {
 		app.use(e.text({ type: "application/json" }));
 		app.use(Sapling.json());
-		_InjectableRegistry.get(HealthRegistrar)?.seal();
+		return new Proxy(app, { get(target, prop, receiver) {
+			if (prop === "listen") {
+				const originalListen = target[prop];
+				return function(...args) {
+					const server = originalListen.apply(target, args);
+					server.once("listening", () => {
+						Sapling.onPostStartup();
+						console.log("Sapling successfully initialized post-startup hooks on server start");
+					});
+					return server;
+				};
+			}
+			return Reflect.get(target, prop, receiver);
+		} });
+	}
+	static onPostStartup() {
+		_InjectableRegistry.get(HealthRegistrar)?._markReady();
 	}
 	/**
 	* Serialize a value into a JSON string.
@@ -515,37 +551,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 `/ready`
+			*/
+			setReadyPath(path) {
+				_settings.health.ready.path = path;
+			},
+			/**
+			* change default endpoint that live endpoint will be served on.
+			*
+			* @default `/live`
+			*/
+			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`
@@ -1138,12 +1196,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.ready();
+		return ResponseEntity.ok().body({ up });
+	}
+	async liveness(_request, _response, _next) {
+		const up = await this.healthRegistrar.live();
 		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.0e8a97e8",
+  "version": "2.1.0-beta.419f8e67",
   "author": "Tahmid Ahmed",
   "description": "A library to help you write cleaner Express.js code",
   "repository": {