@molecule/api-server-default-express 1.0.4 → 1.2.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-16T23:31:50.537Z
+Generated: 2026-10-19T14:30:49.145Z
 -->
 
 # @molecule/api-server-default-express
@@ -16,6 +16,12 @@ returns a `(port?) => Promise<server>` function that runs
 migrations, wires bonds, mounts router + middleware, and starts
 an HTTP (or self-signed HTTPS for local dev) listener.
 
+It also wires the process lifecycle by default: `GET /health/live` and
+`GET /health/ready`, in-flight request tracking with `Connection: close`
+while draining, and SIGTERM/SIGINT graceful shutdown (drain bound
+`SHUTDOWN_TIMEOUT_MS`, default 25 s) that runs ordered shutdown hooks and
+exits 0. Pass `lifecycle: { disabled: true }` to opt out.
+
 > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
 > It is written to be read by coding agents as much as by people, and is generated from this
 > package's source — edit `src/index.ts` JSDoc, not this file.
@@ -50,7 +56,7 @@ await create()
 ## Installation
 
 ```bash
-npm install @molecule/api-server-default-express @molecule/api-error-tracking @molecule/api-logger @molecule/api-middleware-body-parser @molecule/api-middleware-cookie-parser @molecule/api-middleware-cors @molecule/api-secrets express pem
+npm install @molecule/api-server-default-express @molecule/api-error-tracking @molecule/api-logger @molecule/api-middleware-body-parser @molecule/api-middleware-cookie-parser @molecule/api-middleware-cors @molecule/api-process-lifecycle @molecule/api-process-lifecycle-express @molecule/api-secrets express pem
 npm install -D @types/express
 ```
 
@@ -108,6 +114,34 @@ interface CreateServerOptions {
    * resource router.
    */
   preApiRouter?: (app: express.Express) => Promise<void> | void
+  /**
+   * Process-lifecycle tuning. Omitted, the canonical defaults apply: health
+   * routes at `/health/live` and `/health/ready`, a 25 s drain bound
+   * (`SHUTDOWN_TIMEOUT_MS`), a 5 s load-balancer flip wait in production
+   * (`SHUTDOWN_LB_FLIP_WAIT_MS`), and SIGTERM/SIGINT handlers that exit 0.
+   * Set `{ disabled: true }` to keep a legacy process with no lifecycle
+   * wiring (health routes and signal handlers are not installed).
+   */
+  lifecycle?: ServerLifecycleOptions
+}
+```
+
+#### `ServerLifecycleOptions`
+
+Options for the process-lifecycle wiring inside {@link createServerFactory}.
+
+```typescript
+interface ServerLifecycleOptions {
+  /** Skip the lifecycle wiring entirely. Defaults to `false`. */
+  disabled?: boolean
+  /** Maximum time to drain in-flight requests. Defaults to `SHUTDOWN_TIMEOUT_MS` / 25 s. */
+  drainTimeoutMs?: number
+  /** Time to keep listening after draining starts. Defaults to `SHUTDOWN_LB_FLIP_WAIT_MS` / 5 s in production. */
+  flipWaitMs?: number
+  /** Exit function override (tests). Defaults to `process.exit`. */
+  exit?: (code: number) => void
+  /** Signals to handle. Defaults to `['SIGTERM', 'SIGINT']`. */
+  signals?: NodeJS.Signals[]
 }
 ```
 
@@ -270,6 +304,8 @@ Peer dependencies:
 - `@molecule/api-middleware-body-parser`
 - `@molecule/api-middleware-cookie-parser`
 - `@molecule/api-middleware-cors`
+- `@molecule/api-process-lifecycle`
+- `@molecule/api-process-lifecycle-express`
 - `@molecule/api-secrets`
 - `express`
 - `pem`

package/dist/index.d.ts

@@ -7,6 +7,12 @@
  * migrations, wires bonds, mounts router + middleware, and starts
  * an HTTP (or self-signed HTTPS for local dev) listener.
  *
+ * It also wires the process lifecycle by default: `GET /health/live` and
+ * `GET /health/ready`, in-flight request tracking with `Connection: close`
+ * while draining, and SIGTERM/SIGINT graceful shutdown (drain bound
+ * `SHUTDOWN_TIMEOUT_MS`, default 25 s) that runs ordered shutdown hooks and
+ * exits 0. Pass `lifecycle: { disabled: true }` to opt out.
+ *
  * @example
  * ```ts
  * import { createServerFactory } from '@molecule/api-server-default-express'

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA"}

package/dist/index.js

@@ -7,6 +7,12 @@
  * migrations, wires bonds, mounts router + middleware, and starts
  * an HTTP (or self-signed HTTPS for local dev) listener.
  *
+ * It also wires the process lifecycle by default: `GET /health/live` and
+ * `GET /health/ready`, in-flight request tracking with `Connection: close`
+ * while draining, and SIGTERM/SIGINT graceful shutdown (drain bound
+ * `SHUTDOWN_TIMEOUT_MS`, default 25 s) that runs ordered shutdown hooks and
+ * exits 0. Pass `lifecycle: { disabled: true }` to opt out.
+ *
  * @example
  * ```ts
  * import { createServerFactory } from '@molecule/api-server-default-express'

package/dist/server.d.ts

@@ -94,6 +94,30 @@ export interface CreateServerOptions {
      * resource router.
      */
     preApiRouter?: (app: express.Express) => Promise<void> | void;
+    /**
+     * Process-lifecycle tuning. Omitted, the canonical defaults apply: health
+     * routes at `/health/live` and `/health/ready`, a 25 s drain bound
+     * (`SHUTDOWN_TIMEOUT_MS`), a 5 s load-balancer flip wait in production
+     * (`SHUTDOWN_LB_FLIP_WAIT_MS`), and SIGTERM/SIGINT handlers that exit 0.
+     * Set `{ disabled: true }` to keep a legacy process with no lifecycle
+     * wiring (health routes and signal handlers are not installed).
+     */
+    lifecycle?: ServerLifecycleOptions;
+}
+/**
+ * Options for the process-lifecycle wiring inside {@link createServerFactory}.
+ */
+export interface ServerLifecycleOptions {
+    /** Skip the lifecycle wiring entirely. Defaults to `false`. */
+    disabled?: boolean;
+    /** Maximum time to drain in-flight requests. Defaults to `SHUTDOWN_TIMEOUT_MS` / 25 s. */
+    drainTimeoutMs?: number;
+    /** Time to keep listening after draining starts. Defaults to `SHUTDOWN_LB_FLIP_WAIT_MS` / 5 s in production. */
+    flipWaitMs?: number;
+    /** Exit function override (tests). Defaults to `process.exit`. */
+    exit?: (code: number) => void;
+    /** Signals to handle. Defaults to `['SIGTERM', 'SIGINT']`. */
+    signals?: NodeJS.Signals[];
 }
 /**
  * Register a hook to run with the HTTP(S) server right before it listens.

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,MAAM,YAAY,CAAA;AAI9B,OAAO,OAAO,MAAM,SAAS,CAAA;AAS7B,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAetE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,mBA6CrC,CAAA;AAED,yCAAyC;AACzC,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,6EAA6E;IAC7E,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC9D;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC9D;AAYD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACjE,IAAI,CAEN;AAYD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,CAAC,cAU/C,CAAA;AA6BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,mBAAmB,GACxB,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAqH5D"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,MAAM,YAAY,CAAA;AAI9B,OAAO,OAAO,MAAM,SAAS,CAAA;AAgB7B,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAetE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,mBA6CrC,CAAA;AAED,yCAAyC;AACzC,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,6EAA6E;IAC7E,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC9D;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC7D;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gHAAgH;IAChH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;CAC3B;AAmBD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACjE,IAAI,CAEN;AAYD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,CAAC,cAU/C,CAAA;AA6BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,mBAAmB,GACxB,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAyJ5D"}

package/dist/server.js

@@ -8,6 +8,8 @@ import { logger } from '@molecule/api-logger';
 import { bodyParser as bodyParserMiddleware } from '@molecule/api-middleware-body-parser';
 import { cookieParser as cookieParserMiddleware } from '@molecule/api-middleware-cookie-parser';
 import { cors as corsMiddleware } from '@molecule/api-middleware-cors';
+import { setProvider as setLifecycleProvider } from '@molecule/api-process-lifecycle';
+import { installExpressLifecycle, provider as sharedLifecycleProvider, } from '@molecule/api-process-lifecycle-express';
 import { buildConfigReport, logConfigReport } from '@molecule/api-secrets';
 /**
  * Classify a thrown value for the API error middleware. Returns a {@link TaggedError}
@@ -118,6 +120,12 @@ export const errorMiddleware = (error, req, res, _next) => {
         res.status(500).json({ error: 'Internal Server Error' });
     }
 };
+/**
+ * The lifecycle handle of the most recently created server in this process.
+ * Repeated `create()` calls (tests, embedded servers) replace it so signal
+ * handlers never stack.
+ */
+let activeLifecycle = null;
 /**
  * Generic server-lifecycle hooks invoked with the real HTTP(S) server once it
  * has been created in `createServerFactory`, before it starts listening. Lets a
@@ -228,6 +236,21 @@ export function createServerFactory(opts) {
                 captureException(error, { tags: { source: 'unhandledRejection' } });
             });
         }
+        // Bond the lifecycle provider BEFORE the app's own setup runs, so a bond's
+        // setup (database, Redis, queue) can register readiness checks and shutdown
+        // hooks at the moment it knows what it owns.
+        const lifecycleOptions = opts.lifecycle;
+        let lifecycleProvider = null;
+        if (!lifecycleOptions?.disabled) {
+            activeLifecycle?.uninstall();
+            activeLifecycle = null;
+            // The provider is the bond package's process-wide singleton, so a
+            // generated `bonds/process-lifecycle-express.ts` (which calls
+            // `setProvider(provider)` during setupBonds) wires the SAME instance the
+            // health routes read and app code registers checks on.
+            lifecycleProvider = sharedLifecycleProvider;
+            setLifecycleProvider(lifecycleProvider);
+        }
         await opts.runMigrations();
         await opts.setupBonds();
         if (opts.postBondsSetup)
@@ -242,6 +265,19 @@ export function createServerFactory(opts) {
         // /api, /health and error responses all carry them (mirrors the platform
         // server). Anti-clickjacking + nosniff + referrer baseline; HSTS in prod only.
         app.use(securityHeadersMiddleware);
+        // Process lifecycle: count every request (before any route), mount
+        // GET /health/live + /health/ready, and carry the drain state. The signal
+        // handlers are installed once the real HTTP server exists (below).
+        let lifecycle = null;
+        if (lifecycleProvider) {
+            lifecycle = installExpressLifecycle({
+                app,
+                provider: lifecycleProvider,
+                wireProvider: false,
+                ...(lifecycleOptions ?? {}),
+            });
+            activeLifecycle = lifecycle;
+        }
         if (opts.preBodyParser) {
             // Custom-ordering path: mount cors+cookie before custom hooks
             // (e.g. multipart uploads) which run BEFORE the body parser
@@ -302,7 +338,13 @@ export function createServerFactory(opts) {
         httpServer.keepAliveTimeout = 65_000;
         httpServer.headersTimeout = 66_000;
         await runServerCreatedHooks(httpServer);
+        // Signal handlers are installed before the listener starts: a SIGTERM that
+        // arrives during boot must still drain rather than kill the process mid-boot.
+        lifecycle?.attachServer(httpServer);
         httpServer.listen(port, () => {
+            // The boot sequence is complete and the listener owns the port: from here
+            // /health/ready answers 200 (unless a critical check fails).
+            lifecycle?.markReady();
             logger.info(`Started ${process.env.NODE_ENV} ${process.env.HTTPS ? 'HTTPS' : 'HTTP'} server on port ${port}.`);
             // Boot-time configuration report: bonds self-register their secret
             // definitions at import; log which are configured vs missing (each

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-server-default-express",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "Default Express server factory: bonds setup, DB migrations, body/cookie/cors middleware, /api router mount, /health endpoint, 401 normalization, optional HTTPS via self-signed pem certs. Extracts 80-line server.ts shipped by 79 fleet apps.",
   "homepage": "https://www.molecule.dev/packages/api-server-default-express",
   "type": "module",
@@ -28,6 +28,10 @@
     "express"
   ],
   "license": "Apache-2.0",
+  "dependencies": {
+    "@molecule/api-process-lifecycle": "1.2.0",
+    "@molecule/api-process-lifecycle-express": "1.2.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/molecule-dev/molecule.git",