exstack/dist/serve.d.mts

A utility library designed to simplify and enhance express.js applications.

import Http from "node:http";
import { Express } from "express";
import Https from "node:https";

//#region src/serve.d.ts
type Options = {
  /** Port (default: 3000 or PORT env) */port?: number; /** Hostname (default: 'localhost' or HOST env) */
  host?: string;
  /**
   * Enable graceful shutdown (default: true, disabled in CI/TEST)
   * - `true`: Enable with 5s timeout
   * - `false` or `0` or negative: Disable
   * - `number > 0`: Custom timeout in seconds
   */
  gracefulShutdown?: boolean | number; /** Suppress startup logs */
  silent?: boolean;
};
type Application = Express | Http.Server | Https.Server;
/**
 * Start an Express app or HTTP/HTTPS server with graceful shutdown support
 *
 * @param app - Express application or HTTP/HTTPS server instance
 * @param options - Server configuration options
 * @returns HTTP/HTTPS server instance
 *
 * @example
 * ```typescript
 * // Basic usage with Express
 * const app = express();
 * serve(app, { port: 3000 });
 *
 * // With HTTPS
 * const httpsServer = https.createServer({ cert, key }, app);
 * serve(httpsServer, { port: 443 });
 *
 * // Custom graceful shutdown timeout (10 seconds)
 * serve(app, { port: 3000, gracefulShutdown: 10 });
 *
 * // Disable graceful shutdown
 * serve(app, { gracefulShutdown: false });
 * ```
 *
 * @remarks
 * Graceful shutdown behavior:
 * - On SIGINT/SIGTERM: stops accepting new connections, waits for active requests
 * - Shows countdown timer with remaining time
 * - Press Ctrl+C again to force close immediately
 * - After timeout: automatically force closes all connections
 * - Long-running connections (SSE, WebSocket) will be force closed on timeout
 */
declare const serve: (app: Application, options?: Options) => Http.Server<typeof Http.IncomingMessage, typeof Http.ServerResponse>;
//#endregion
export { serve };