node-cluster-serve 0.9.0

package/LICENSE.md

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Javier Aguilar (itsjavi.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# node-cluster-serve
+
+Run a Node.js `serve` function in single-process or `node:cluster` mode with graceful shutdown and
+worker restart limits.
+
+- **Library:** `runServeFunction` — you pass `serve`; the library does not load a file path.
+- **CLI:** `node-cluster-serve` resolves a module path, `import()`s it, and passes `default` as
+  `serve`.
+
+## Install
+
+```bash
+npm install node-cluster-serve
+# or
+npx nypm add node-cluster-serve
+```
+
+## Quick Start (CLI)
+
+Your server module must **default-export** an async `serve` function. Return something with `close`
+(typically an `http.Server`) so SIGTERM/SIGINT can shut down gracefully.
+
+`serve` receives a **`ServeContext`**: `Omit<ServeOptions, 'serve'>`. The runner sets defaults for
+`mode`, `port`, `loggerPrefix`, `workerCount`, and shutdown/restart fields. **`host` may be
+`undefined`** if nothing was passed and no local IPv4 was discovered (use a fallback when calling
+`listen`, as below).
+
+```ts
+// e.g. ./server.js (or ./server.ts if your Node/runtime can import TypeScript)
+import { createServer } from 'node:http'
+import type { ServeContext } from 'node-cluster-serve'
+
+export default async function serve({ host, port }: ServeContext) {
+  const httpServer = createServer((_req, res) => {
+    res.end('ok\n')
+  })
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.listen({ port, host: host ?? '0.0.0.0' }, (err) => (err ? reject(err) : resolve()))
+  })
+
+  return httpServer
+}
+```
+
+Run it (use a path Node can `import()` — usually compiled **`.js`**, unless you rely on TypeScript
+stripping or a loader):
+
+```bash
+node-cluster-serve ./dist/server.js --mode production --port 3000 --workerCount 4
+```
+
+## CLI Arguments
+
+```text
+node-cluster-serve <serverModuleFile> [options]
+```
+
+- `serverModuleFile` (positional, required): file path or `file:` URL to the server module.
+- `--mode`: `development | production | test` (default: `NODE_ENV`)
+- `--host`: bind host (default: `HOST` env, else first local IPv4)
+- `--port`: bind port (default: `PORT` env, else `3000`)
+- `--loggerPrefix`: log prefix (default: `[node-cluster-serve]`)
+- `--workerCount`: worker count (default: `WORKER_COUNT` or `WEB_CONCURRENCY` env, else `1`)
+- `--shutdownGraceMs`: graceful shutdown timeout in ms (default: `10000`)
+- `--restartWindowMs`: crash restart accounting window in ms (default: `30000`)
+- `--maxRestartsPerWindow`: restart cap per window (default: `10`)
+
+The CLI resolves `serverModuleFile` to a `file:` URL and `import()`s it; **`default`** must be the
+`serve` function. Non-`file:` URLs (e.g. `https:`) are rejected.
+
+## Programmatic usage
+
+Import `serve` yourself and pass it on `options.serve`.
+
+```ts
+import { runServeFunction } from 'node-cluster-serve'
+import serve from './server.js'
+
+await runServeFunction({
+  serve,
+  mode: 'production',
+  host: '0.0.0.0',
+  port: 3000,
+  workerCount: 4,
+  loggerPrefix: '[my-app]',
+  shutdownGraceMs: 10_000,
+  restartWindowMs: 30_000,
+  maxRestartsPerWindow: 10,
+})
+```
+
+**When the promise resolves:** it does **not** mean the process is about to exit — the HTTP server
+(or whatever you started) keeps the event loop alive.
+
+- **Single worker (`workerCount === 1`):** resolves after `serve` has resolved (e.g. after `listen`)
+  and signal handlers are registered.
+- **Cluster primary (`workerCount > 1`):** resolves after workers are forked and the primary’s
+  handlers are registered; each worker runs `serve` on its own.
+
+**Return value:** `runServeFunction` fulfills with the **`ServeContext`** object passed into `serve`
+(same reference).
+
+**Cluster mode:** forked workers start a **new Node process** and re-run your **entry file**. That
+entry should call `runServeFunction` again with the same `serve` (usually by importing a shared
+module) so each process has a real function reference.
+
+## Embedding the CLI
+
+`nodeClusterServeCommand` is exported from `node-cluster-serve` for use with
+[citty](https://github.com/unjs/citty).
+
+## Serve function contract
+
+```ts
+type ServeFunction = (context: ServeContext) => Promise<ClosableServer | void>
+type ServeContext = Omit<ServeOptions, 'serve'>
+```
+
+`ClosableServer` may be:
+
+- `{ close(callback) }`, or
+- `{ close(): void | Promise<void> }`, or
+- omitted (`void`) if you handle shutdown yourself.
+
+The CLI expects a **`ServeModule`**: `{ default: ServeFunction }`.
+
+On SIGTERM/SIGINT, each **worker** awaits `close()` on the value returned from `serve`, then exits.
+The **primary** signals workers to shut down when using cluster mode.
+
+## Environment variables
+
+- `NODE_ENV`: fallback for `mode`
+- `HOST`: fallback for `host`
+- `PORT`: fallback for `port`
+- `WORKER_COUNT` / `WEB_CONCURRENCY`: fallback for `workerCount` when not set on the CLI or in
+  options; if both are set, **`WORKER_COUNT` wins**
+
+## License
+
+MIT

package/dist/cli-b8DR3vy7.mjs

@@ -0,0 +1,251 @@
+import cluster from "node:cluster";
+import os from "node:os";
+import { pathToFileURL } from "node:url";
+import { defineCommand } from "citty";
+//#region src/lib/utils.ts
+function parseNumber(raw) {
+	if (raw == null) return void 0;
+	let value = Number(raw);
+	return Number.isFinite(value) ? value : void 0;
+}
+function parseCliNumberArg(name, value) {
+	if (value == null || value === "") return void 0;
+	let parsed = Number(value);
+	if (!Number.isFinite(parsed)) throw new Error(`Invalid --${name} value: "${value}". Expected a number.`);
+	return parsed;
+}
+function parseCliIntegerArg(name, value) {
+	let parsed = parseCliNumberArg(name, value);
+	if (parsed == null) return void 0;
+	if (!Number.isInteger(parsed)) throw new Error(`Invalid --${name} value: "${value}". Expected an integer.`);
+	return parsed;
+}
+function parseCliMinIntArg(name, value, min) {
+	let parsed = parseCliIntegerArg(name, value);
+	if (parsed == null) return void 0;
+	if (parsed < min) throw new Error(`Invalid --${name} value: "${value}". Expected an integer >= ${min}.`);
+	return parsed;
+}
+function parseCliPortArg(value) {
+	let parsed = parseCliMinIntArg("port", value, 1);
+	if (parsed == null) return void 0;
+	if (parsed > 65535) throw new Error(`Invalid --port value: "${value}". Expected an integer <= 65535.`);
+	return parsed;
+}
+function resolveServerModuleFileUrl(input) {
+	let url;
+	if (input instanceof URL) url = input;
+	else if (input.startsWith("file:")) url = new URL(input);
+	else if (input.startsWith("/")) url = pathToFileURL(input);
+	else url = new URL(input, pathToFileURL(`${process.cwd()}/`));
+	if (url.protocol !== "file:") throw new Error(`Module path must resolve to a file: URL (got ${url.protocol}). Remote URLs are not supported.`);
+	return url;
+}
+function getHostAddress() {
+	if (process.env.HOST) return process.env.HOST;
+	return Object.values(os.networkInterfaces()).flat().find((ip) => String(ip?.family).includes("4") && !ip?.internal)?.address;
+}
+function resolveDefaultWorkerCount() {
+	return Math.max(1, parseNumber(process.env.WORKER_COUNT) ?? parseNumber(process.env.WEB_CONCURRENCY) ?? 1);
+}
+//#endregion
+//#region src/lib/server.ts
+const DEFAULT_SHUTDOWN_GRACE_MS = 1e4;
+const DEFAULT_RESTART_WINDOW_MS = 3e4;
+const DEFAULT_MAX_RESTARTS_PER_WINDOW = 10;
+function resolveServerMode(mode) {
+	const resolved = mode ?? process.env.NODE_ENV;
+	if (resolved !== "development" && resolved !== "production" && resolved !== "test") throw new Error("Missing or invalid NODE_ENV/mode. Use development, production, or test.");
+	return resolved;
+}
+function logBoundUrl(loggerPrefix, host, port, workerSuffix) {
+	const suffix = workerSuffix ?? "";
+	if (!host) console.log(`${loggerPrefix} http://localhost:${port}${suffix}`);
+	else console.log(`${loggerPrefix} http://localhost:${port} (http://${host}:${port})${suffix}`);
+}
+async function closeServer(server) {
+	if (!server?.close) return;
+	if (server.close.length > 0) {
+		await new Promise((resolve, reject) => {
+			server.close((error) => {
+				if (error) reject(error);
+				else resolve();
+			});
+		});
+		return;
+	}
+	await server.close();
+}
+/**
+* Runs `options.serve` in the current process, or supervises a cluster when `workerCount > 1`.
+* - **Single worker:** resolves after your `serve` function resolves (e.g. after listen).
+* - **Cluster primary:** resolves after workers are forked and handlers are registered; workers
+*   call `serve` on their own afterward.
+* The promise does not wait for process exit.
+*/
+async function runServeFunction(options) {
+	if (typeof options.serve !== "function") throw new Error("options.serve must be a function");
+	const mode = resolveServerMode(options.mode);
+	const host = options.host ?? getHostAddress();
+	const port = options.port ?? parseNumber(process.env.PORT) ?? 3e3;
+	const loggerPrefix = options.loggerPrefix ?? "[node-cluster-serve]";
+	const shutdownGraceMs = options.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS;
+	const restartWindowMs = options.restartWindowMs ?? DEFAULT_RESTART_WINDOW_MS;
+	const maxRestartsPerWindow = options.maxRestartsPerWindow ?? DEFAULT_MAX_RESTARTS_PER_WINDOW;
+	const workerCount = Math.max(1, options.workerCount ?? resolveDefaultWorkerCount());
+	const resolvedContext = {
+		mode,
+		host,
+		port,
+		loggerPrefix,
+		workerCount,
+		shutdownGraceMs,
+		restartWindowMs,
+		maxRestartsPerWindow
+	};
+	async function startWorker() {
+		const server = await options.serve(resolvedContext);
+		logBoundUrl(loggerPrefix, host, port, cluster.isWorker ? ` (worker ${cluster.worker?.id})` : void 0);
+		let shuttingDown = false;
+		const shutdown = async () => {
+			if (shuttingDown) return;
+			shuttingDown = true;
+			const forceTimeout = setTimeout(() => {
+				console.error(`${loggerPrefix} worker forced shutdown timeout reached`);
+				process.exit(1);
+			}, shutdownGraceMs);
+			try {
+				await closeServer(server);
+				clearTimeout(forceTimeout);
+				process.exit(0);
+			} catch (error) {
+				clearTimeout(forceTimeout);
+				console.error(error);
+				process.exit(1);
+			}
+		};
+		process.once("SIGTERM", () => void shutdown());
+		process.once("SIGINT", () => void shutdown());
+	}
+	if (workerCount > 1 && cluster.isPrimary) {
+		console.log(`${loggerPrefix} starting cluster with ${workerCount} workers`);
+		let shuttingDown = false;
+		let restartTimestamps = [];
+		const livingWorkerCount = () => Object.values(cluster.workers ?? {}).filter((w) => w && !w.isDead()).length;
+		const spawnWorker = () => {
+			const now = Date.now();
+			restartTimestamps = restartTimestamps.filter((ts) => now - ts < restartWindowMs);
+			if (restartTimestamps.length >= maxRestartsPerWindow) {
+				console.error(`${loggerPrefix} restart rate exceeded, refusing to fork more workers`);
+				if (livingWorkerCount() === 0) {
+					console.error(`${loggerPrefix} no workers left; exiting primary`);
+					process.exit(1);
+				}
+				return;
+			}
+			restartTimestamps.push(now);
+			cluster.fork();
+		};
+		for (let i = 0; i < workerCount; i++) spawnWorker();
+		cluster.on("exit", (worker, code, signal) => {
+			console.error(`${loggerPrefix} worker ${worker.process.pid} exited (code=${code} signal=${signal})`);
+			if (shuttingDown) {
+				if (livingWorkerCount() === 0) process.exit(0);
+				return;
+			}
+			spawnWorker();
+		});
+		const shutdownPrimary = async () => {
+			if (shuttingDown) return;
+			shuttingDown = true;
+			console.log(`${loggerPrefix} primary shutting down cluster`);
+			for (const worker of Object.values(cluster.workers ?? {})) worker?.process.kill("SIGTERM");
+			setTimeout(() => {
+				for (const worker of Object.values(cluster.workers ?? {})) worker?.process.kill("SIGKILL");
+				process.exit(1);
+			}, shutdownGraceMs).unref();
+		};
+		process.once("SIGTERM", () => void shutdownPrimary());
+		process.once("SIGINT", () => void shutdownPrimary());
+		return resolvedContext;
+	}
+	await startWorker();
+	return resolvedContext;
+}
+//#endregion
+//#region src/lib/cli.ts
+const nodeClusterServeCommand = defineCommand({
+	meta: {
+		name: "node-cluster-serve",
+		description: "Run a server module in single-process or cluster mode."
+	},
+	args: {
+		serverModuleFile: {
+			type: "positional",
+			description: "Path or file URL to a server module that exports a default serve function.",
+			required: true,
+			valueHint: "file"
+		},
+		mode: {
+			type: "enum",
+			description: "Server mode (defaults to NODE_ENV).",
+			options: [
+				"development",
+				"production",
+				"test"
+			]
+		},
+		host: {
+			type: "string",
+			description: "Host to bind to (defaults to HOST or first local IPv4)."
+		},
+		port: {
+			type: "string",
+			description: "Port to bind to (defaults to PORT or 3000).",
+			valueHint: "number"
+		},
+		loggerPrefix: {
+			type: "string",
+			description: "Log prefix for startup and lifecycle messages."
+		},
+		workerCount: {
+			type: "string",
+			description: "Server worker count (defaults to WORKER_COUNT, WEB_CONCURRENCY or 1).",
+			valueHint: "number"
+		},
+		shutdownGraceMs: {
+			type: "string",
+			description: "Graceful shutdown timeout in milliseconds.",
+			valueHint: "number"
+		},
+		restartWindowMs: {
+			type: "string",
+			description: "Crash restart accounting window in milliseconds.",
+			valueHint: "number"
+		},
+		maxRestartsPerWindow: {
+			type: "string",
+			description: "Maximum worker restarts allowed per restart window.",
+			valueHint: "number"
+		}
+	},
+	async run({ args }) {
+		const serve = (await import(resolveServerModuleFileUrl(String(args.serverModuleFile)).href)).default;
+		if (typeof serve !== "function") throw new Error("Server module must default-export a serve function");
+		await runServeFunction({
+			serve,
+			mode: args.mode,
+			host: args.host,
+			port: parseCliPortArg(args.port),
+			loggerPrefix: args.loggerPrefix,
+			workerCount: parseCliMinIntArg("workerCount", args.workerCount, 1),
+			shutdownGraceMs: parseCliMinIntArg("shutdownGraceMs", args.shutdownGraceMs, 1),
+			restartWindowMs: parseCliMinIntArg("restartWindowMs", args.restartWindowMs, 1),
+			maxRestartsPerWindow: parseCliMinIntArg("maxRestartsPerWindow", args.maxRestartsPerWindow, 1)
+		});
+	}
+});
+//#endregion
+export { resolveServerMode as n, runServeFunction as r, nodeClusterServeCommand as t };
+
+//# sourceMappingURL=cli-b8DR3vy7.mjs.map

package/dist/cli-b8DR3vy7.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-b8DR3vy7.mjs","names":[],"sources":["../src/lib/utils.ts","../src/lib/server.ts","../src/lib/cli.ts"],"sourcesContent":["import os from 'node:os'\nimport { pathToFileURL } from 'node:url'\n\nexport function parseNumber(raw?: string): number | undefined {\n  if (raw == null) return undefined\n  let value = Number(raw)\n  return Number.isFinite(value) ? value : undefined\n}\n\nexport function parseCliNumberArg(name: string, value?: string): number | undefined {\n  if (value == null || value === '') return undefined\n  let parsed = Number(value)\n  if (!Number.isFinite(parsed)) {\n    throw new Error(`Invalid --${name} value: \"${value}\". Expected a number.`)\n  }\n  return parsed\n}\n\nexport function parseCliIntegerArg(name: string, value?: string): number | undefined {\n  let parsed = parseCliNumberArg(name, value)\n  if (parsed == null) return undefined\n  if (!Number.isInteger(parsed)) {\n    throw new Error(`Invalid --${name} value: \"${value}\". Expected an integer.`)\n  }\n  return parsed\n}\n\nexport function parseCliMinIntArg(\n  name: string,\n  value: string | undefined,\n  min: number,\n): number | undefined {\n  let parsed = parseCliIntegerArg(name, value)\n  if (parsed == null) return undefined\n  if (parsed < min) {\n    throw new Error(`Invalid --${name} value: \"${value}\". Expected an integer >= ${min}.`)\n  }\n  return parsed\n}\n\nexport function parseCliPortArg(value?: string): number | undefined {\n  let parsed = parseCliMinIntArg('port', value, 1)\n  if (parsed == null) return undefined\n  if (parsed > 65535) {\n    throw new Error(`Invalid --port value: \"${value}\". Expected an integer <= 65535.`)\n  }\n  return parsed\n}\n\nexport function resolveServerModuleFileUrl(input: string | URL): URL {\n  let url: URL\n  if (input instanceof URL) {\n    url = input\n  } else if (input.startsWith('file:')) {\n    url = new URL(input)\n  } else if (input.startsWith('/')) {\n    url = pathToFileURL(input)\n  } else {\n    url = new URL(input, pathToFileURL(`${process.cwd()}/`))\n  }\n\n  if (url.protocol !== 'file:') {\n    throw new Error(\n      `Module path must resolve to a file: URL (got ${url.protocol}). Remote URLs are not supported.`,\n    )\n  }\n  return url\n}\n\nexport function getHostAddress(): string | undefined {\n  if (process.env.HOST) return process.env.HOST\n  return Object.values(os.networkInterfaces())\n    .flat()\n    .find((ip) => String(ip?.family).includes('4') && !ip?.internal)?.address\n}\n\nexport function resolveDefaultWorkerCount(): number {\n  return Math.max(\n    1,\n    parseNumber(process.env.WORKER_COUNT) ?? parseNumber(process.env.WEB_CONCURRENCY) ?? 1,\n  )\n}\n","import cluster from 'node:cluster'\nimport { getHostAddress, parseNumber, resolveDefaultWorkerCount } from './utils.ts'\n\nconst DEFAULT_SHUTDOWN_GRACE_MS = 10_000\nconst DEFAULT_RESTART_WINDOW_MS = 30_000\nconst DEFAULT_MAX_RESTARTS_PER_WINDOW = 10\n\nexport type ClosableServer = {\n  close?: ((callback: (error?: unknown) => void) => void) | (() => void | Promise<void>)\n}\n\nexport type ServerMode = 'development' | 'production' | 'test'\nexport type ServeContext = Omit<ServeOptions, 'serve'>\nexport type ServeFunction = (context: Omit<ServeOptions, 'serve'>) => Promise<ClosableServer | void>\n\nexport interface ServeOptions {\n  serve: ServeFunction\n  mode?: ServerMode\n  host?: string\n  port?: number\n  loggerPrefix?: string\n  workerCount?: number\n  shutdownGraceMs?: number\n  restartWindowMs?: number\n  maxRestartsPerWindow?: number\n}\n\n/** Module shape the CLI loads: `default` must be a `ServeFunction`. */\nexport type ServeModule = {\n  default: ServeFunction\n}\n\nexport function resolveServerMode(mode?: string): ServerMode {\n  const resolved = mode ?? process.env.NODE_ENV\n  if (resolved !== 'development' && resolved !== 'production' && resolved !== 'test') {\n    throw new Error('Missing or invalid NODE_ENV/mode. Use development, production, or test.')\n  }\n  return resolved\n}\n\nfunction logBoundUrl(\n  loggerPrefix: string,\n  host: string | undefined,\n  port: number,\n  workerSuffix?: string,\n) {\n  const suffix = workerSuffix ?? ''\n  if (!host) {\n    console.log(`${loggerPrefix} http://localhost:${port}${suffix}`)\n  } else {\n    console.log(`${loggerPrefix} http://localhost:${port} (http://${host}:${port})${suffix}`)\n  }\n}\n\nasync function closeServer(server: ClosableServer | void) {\n  if (!server?.close) return\n  if (server.close.length > 0) {\n    await new Promise<void>((resolve, reject) => {\n      ;(server.close as (callback: (error?: unknown) => void) => void)((error?: unknown) => {\n        if (error) reject(error)\n        else resolve()\n      })\n    })\n    return\n  }\n  await (server.close as () => void | Promise<void>)()\n}\n\n/**\n * Runs `options.serve` in the current process, or supervises a cluster when `workerCount > 1`.\n * - **Single worker:** resolves after your `serve` function resolves (e.g. after listen).\n * - **Cluster primary:** resolves after workers are forked and handlers are registered; workers\n *   call `serve` on their own afterward.\n * The promise does not wait for process exit.\n */\nexport async function runServeFunction(options: ServeOptions): Promise<ServeContext> {\n  if (typeof options.serve !== 'function') {\n    throw new Error('options.serve must be a function')\n  }\n\n  const mode = resolveServerMode(options.mode)\n  const host = options.host ?? getHostAddress()\n  const port = options.port ?? parseNumber(process.env.PORT) ?? 3000\n  const loggerPrefix = options.loggerPrefix ?? '[node-cluster-serve]'\n  const shutdownGraceMs = options.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS\n  const restartWindowMs = options.restartWindowMs ?? DEFAULT_RESTART_WINDOW_MS\n  const maxRestartsPerWindow = options.maxRestartsPerWindow ?? DEFAULT_MAX_RESTARTS_PER_WINDOW\n  const workerCount = Math.max(1, options.workerCount ?? resolveDefaultWorkerCount())\n\n  const resolvedContext: ServeContext = {\n    mode,\n    host,\n    port,\n    loggerPrefix,\n    workerCount,\n    shutdownGraceMs,\n    restartWindowMs,\n    maxRestartsPerWindow,\n  }\n\n  async function startWorker() {\n    const server = await options.serve(resolvedContext)\n    logBoundUrl(\n      loggerPrefix,\n      host,\n      port,\n      cluster.isWorker ? ` (worker ${cluster.worker?.id})` : undefined,\n    )\n\n    let shuttingDown = false\n    const shutdown = async () => {\n      if (shuttingDown) return\n      shuttingDown = true\n      const forceTimeout = setTimeout(() => {\n        console.error(`${loggerPrefix} worker forced shutdown timeout reached`)\n        process.exit(1)\n      }, shutdownGraceMs)\n\n      try {\n        await closeServer(server)\n        clearTimeout(forceTimeout)\n        process.exit(0)\n      } catch (error) {\n        clearTimeout(forceTimeout)\n        console.error(error)\n        process.exit(1)\n      }\n    }\n\n    process.once('SIGTERM', () => void shutdown())\n    process.once('SIGINT', () => void shutdown())\n  }\n\n  if (workerCount > 1 && cluster.isPrimary) {\n    console.log(`${loggerPrefix} starting cluster with ${workerCount} workers`)\n    let shuttingDown = false\n    let restartTimestamps: number[] = []\n\n    const livingWorkerCount = () =>\n      Object.values(cluster.workers ?? {}).filter((w) => w && !w.isDead()).length\n\n    const spawnWorker = () => {\n      const now = Date.now()\n      restartTimestamps = restartTimestamps.filter((ts) => now - ts < restartWindowMs)\n      if (restartTimestamps.length >= maxRestartsPerWindow) {\n        console.error(`${loggerPrefix} restart rate exceeded, refusing to fork more workers`)\n        if (livingWorkerCount() === 0) {\n          console.error(`${loggerPrefix} no workers left; exiting primary`)\n          process.exit(1)\n        }\n        return\n      }\n      restartTimestamps.push(now)\n      cluster.fork()\n    }\n\n    for (let i = 0; i < workerCount; i++) {\n      spawnWorker()\n    }\n\n    cluster.on('exit', (worker, code, signal) => {\n      console.error(\n        `${loggerPrefix} worker ${worker.process.pid} exited (code=${code} signal=${signal})`,\n      )\n      if (shuttingDown) {\n        if (livingWorkerCount() === 0) {\n          process.exit(0)\n        }\n        return\n      }\n      spawnWorker()\n    })\n\n    const shutdownPrimary = async () => {\n      if (shuttingDown) return\n      shuttingDown = true\n      console.log(`${loggerPrefix} primary shutting down cluster`)\n\n      for (const worker of Object.values(cluster.workers ?? {})) {\n        worker?.process.kill('SIGTERM')\n      }\n\n      setTimeout(() => {\n        for (const worker of Object.values(cluster.workers ?? {})) {\n          worker?.process.kill('SIGKILL')\n        }\n        process.exit(1)\n      }, shutdownGraceMs).unref()\n    }\n\n    process.once('SIGTERM', () => void shutdownPrimary())\n    process.once('SIGINT', () => void shutdownPrimary())\n    return resolvedContext\n  }\n\n  await startWorker()\n\n  return resolvedContext\n}\n","import { defineCommand } from 'citty'\nimport {\n  runServeFunction,\n  type ServeFunction,\n  type ServeModule,\n  type ServerMode,\n} from './server.ts'\nimport { parseCliMinIntArg, parseCliPortArg, resolveServerModuleFileUrl } from './utils.ts'\n\nexport const nodeClusterServeCommand = defineCommand({\n  meta: {\n    name: 'node-cluster-serve',\n    description: 'Run a server module in single-process or cluster mode.',\n  },\n  args: {\n    serverModuleFile: {\n      type: 'positional',\n      description: 'Path or file URL to a server module that exports a default serve function.',\n      required: true,\n      valueHint: 'file',\n    },\n    mode: {\n      type: 'enum',\n      description: 'Server mode (defaults to NODE_ENV).',\n      options: ['development', 'production', 'test'],\n    },\n    host: {\n      type: 'string',\n      description: 'Host to bind to (defaults to HOST or first local IPv4).',\n    },\n    port: {\n      type: 'string',\n      description: 'Port to bind to (defaults to PORT or 3000).',\n      valueHint: 'number',\n    },\n    loggerPrefix: {\n      type: 'string',\n      description: 'Log prefix for startup and lifecycle messages.',\n    },\n    workerCount: {\n      type: 'string',\n      description: 'Server worker count (defaults to WORKER_COUNT, WEB_CONCURRENCY or 1).',\n      valueHint: 'number',\n    },\n    shutdownGraceMs: {\n      type: 'string',\n      description: 'Graceful shutdown timeout in milliseconds.',\n      valueHint: 'number',\n    },\n    restartWindowMs: {\n      type: 'string',\n      description: 'Crash restart accounting window in milliseconds.',\n      valueHint: 'number',\n    },\n    maxRestartsPerWindow: {\n      type: 'string',\n      description: 'Maximum worker restarts allowed per restart window.',\n      valueHint: 'number',\n    },\n  },\n  async run({ args }) {\n    const moduleUrl = resolveServerModuleFileUrl(String(args.serverModuleFile))\n    const mod = (await import(moduleUrl.href)) as ServeModule\n    const serve = mod.default\n    if (typeof serve !== 'function') {\n      throw new Error('Server module must default-export a serve function')\n    }\n\n    await runServeFunction({\n      serve: serve as ServeFunction,\n      mode: args.mode as ServerMode | undefined,\n      host: args.host,\n      port: parseCliPortArg(args.port),\n      loggerPrefix: args.loggerPrefix,\n      workerCount: parseCliMinIntArg('workerCount', args.workerCount, 1),\n      shutdownGraceMs: parseCliMinIntArg('shutdownGraceMs', args.shutdownGraceMs, 1),\n      restartWindowMs: parseCliMinIntArg('restartWindowMs', args.restartWindowMs, 1),\n      maxRestartsPerWindow: parseCliMinIntArg('maxRestartsPerWindow', args.maxRestartsPerWindow, 1),\n    })\n  },\n})\n"],"mappings":"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"}

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { t as nodeClusterServeCommand } from "./cli-b8DR3vy7.mjs";
+import { runMain } from "citty";
+//#region src/cli.ts
+await runMain(nodeClusterServeCommand);
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { runMain } from 'citty'\nimport { nodeClusterServeCommand } from './lib/cli.ts'\n\nawait runMain(nodeClusterServeCommand)\n"],"mappings":";;;;AAKA,MAAM,QAAQ,wBAAwB"}

package/dist/index.d.mts

@@ -0,0 +1,84 @@
+import * as _$citty from "citty";
+
+//#region src/lib/server.d.ts
+type ClosableServer = {
+  close?: ((callback: (error?: unknown) => void) => void) | (() => void | Promise<void>);
+};
+type ServerMode = 'development' | 'production' | 'test';
+type ServeContext = Omit<ServeOptions, 'serve'>;
+type ServeFunction = (context: Omit<ServeOptions, 'serve'>) => Promise<ClosableServer | void>;
+interface ServeOptions {
+  serve: ServeFunction;
+  mode?: ServerMode;
+  host?: string;
+  port?: number;
+  loggerPrefix?: string;
+  workerCount?: number;
+  shutdownGraceMs?: number;
+  restartWindowMs?: number;
+  maxRestartsPerWindow?: number;
+}
+/** Module shape the CLI loads: `default` must be a `ServeFunction`. */
+type ServeModule = {
+  default: ServeFunction;
+};
+declare function resolveServerMode(mode?: string): ServerMode;
+/**
+ * Runs `options.serve` in the current process, or supervises a cluster when `workerCount > 1`.
+ * - **Single worker:** resolves after your `serve` function resolves (e.g. after listen).
+ * - **Cluster primary:** resolves after workers are forked and handlers are registered; workers
+ *   call `serve` on their own afterward.
+ * The promise does not wait for process exit.
+ */
+declare function runServeFunction(options: ServeOptions): Promise<ServeContext>;
+//#endregion
+//#region src/lib/cli.d.ts
+declare const nodeClusterServeCommand: _$citty.CommandDef<{
+  readonly serverModuleFile: {
+    readonly type: "positional";
+    readonly description: "Path or file URL to a server module that exports a default serve function.";
+    readonly required: true;
+    readonly valueHint: "file";
+  };
+  readonly mode: {
+    readonly type: "enum";
+    readonly description: "Server mode (defaults to NODE_ENV).";
+    readonly options: ["development", "production", "test"];
+  };
+  readonly host: {
+    readonly type: "string";
+    readonly description: "Host to bind to (defaults to HOST or first local IPv4).";
+  };
+  readonly port: {
+    readonly type: "string";
+    readonly description: "Port to bind to (defaults to PORT or 3000).";
+    readonly valueHint: "number";
+  };
+  readonly loggerPrefix: {
+    readonly type: "string";
+    readonly description: "Log prefix for startup and lifecycle messages.";
+  };
+  readonly workerCount: {
+    readonly type: "string";
+    readonly description: "Server worker count (defaults to WORKER_COUNT, WEB_CONCURRENCY or 1).";
+    readonly valueHint: "number";
+  };
+  readonly shutdownGraceMs: {
+    readonly type: "string";
+    readonly description: "Graceful shutdown timeout in milliseconds.";
+    readonly valueHint: "number";
+  };
+  readonly restartWindowMs: {
+    readonly type: "string";
+    readonly description: "Crash restart accounting window in milliseconds.";
+    readonly valueHint: "number";
+  };
+  readonly maxRestartsPerWindow: {
+    readonly type: "string";
+    readonly description: "Maximum worker restarts allowed per restart window.";
+    readonly valueHint: "number";
+  };
+}>;
+//#endregion
+export { ClosableServer, ServeContext, ServeFunction, ServeModule, ServeOptions, ServerMode, nodeClusterServeCommand, resolveServerMode, runServeFunction };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { n as resolveServerMode, r as runServeFunction, t as nodeClusterServeCommand } from "./cli-b8DR3vy7.mjs";
+export { nodeClusterServeCommand, resolveServerMode, runServeFunction };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "node-cluster-serve",
+  "version": "0.9.0",
+  "description": "Run a Node.js serve() function with optional node:cluster workers, graceful shutdown, and worker restart limits.",
+  "keywords": [
+    "graceful-shutdown",
+    "http-server",
+    "node-cluster",
+    "process-supervisor"
+  ],
+  "bugs": {
+    "url": "https://github.com/itsjavi/node-cluster-serve/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itsjavi/node-cluster-serve.git"
+  },
+  "bin": {
+    "node-cluster-serve": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "node": {
+        "types": "./dist/index.d.mts",
+        "module-sync": "./dist/index.mjs"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "postbuild": "pnpm dlx publint",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "pnpm typecheck",
+    "lint:circular": "pnpm dlx madge --circular src/index.ts src/cli.ts",
+    "prepublishOnly": "pnpm build",
+    "test": "vitest --run",
+    "test:coverage": "vitest --run --coverage",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "citty": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "oxfmt": "^0.43.0",
+    "publint": "^0.3.18",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}