procband 0.3.5 → 0.3.7

package/README.md

@@ -1,38 +1,120 @@
 # procband
 
-## Purpose
+> Supervise subprocesses from TypeScript when a script needs prefixed output,
+> readiness matching, restart policy, and process-tree shutdown without becoming
+> a standalone process manager.
 
-`procband` supervises subprocesses from TypeScript. It prefixes child output,
-matches future log lines, waits for terminal exit, optionally restarts failed
-processes, tree-kills descendants during shutdown, and propagates unobserved
-terminal failures to the parent process.
+`procband` wraps one child process per `supervise()` call. It starts the child
+immediately, prefixes `stdout` and `stderr`, lets your script wait for future
+log lines, and resolves to a final `ProcessResult` when no more restart attempt
+will run.
 
-## Installation
+## Install
 
 ```sh
 pnpm add procband
 ```
 
-## Quick Example
+## First Process
+
+Use `waitFor()` when the next step depends on output that the child will print
+after supervision starts:
 
 ```ts
 import process from 'node:process'
 import { supervise } from 'procband'
 
 const proc = supervise({
+  name: 'worker',
   command: process.execPath,
   args: ['-e', 'console.log("ready")'],
 })
 
-await proc.waitFor('ready')
+const ready = await proc.waitFor('ready')
+console.log(`matched ${ready.line}`)
+
 const result = await proc
-console.log(result)
+console.log(result.exitCode)
 ```
 
-## Documentation Map
+The child output is written to the parent process with a `worker` prefix, the
+readiness wait resolves when a future line contains `ready`, and `await proc`
+returns the terminal result.
+
+## Choose the Failure Behavior
+
+By default, a failed terminal exit resolves to `ProcessResult`. Use this when a
+supervisor script needs to inspect the outcome:
+
+```ts
+import process from 'node:process'
+import { supervise } from 'procband'
+
+const result = await supervise({
+  name: 'job',
+  command: process.execPath,
+  args: ['-e', 'process.exit(1)'],
+})
+
+if (result.exitCode !== 0) {
+  console.error(`job failed with ${result.exitCode}`)
+}
+```
+
+Use `expectSuccess()` for foreground command-runner steps where a failed exit
+should reject:
+
+```ts
+import { ProcessExitError, supervise } from 'procband'
+
+try {
+  await supervise({
+    name: 'db',
+    command: 'pnpm',
+    args: ['db', 'ensure'],
+  }).expectSuccess()
+} catch (error) {
+  if (error instanceof ProcessExitError) {
+    console.error(error.command, error.args, error.exitCode)
+  }
+  throw error
+}
+```
+
+If your script never awaits the process or calls `wait()`, an unobserved failed
+terminal exit sets the parent `process.exitCode` and starts stopping other live
+`procband` processes in the same parent script.
+
+## Prefix an Existing Stream
+
+Use `createPrefixStream()` when another API already owns a process lifecycle
+but its output should use procband's label and color formatting:
+
+```ts
+import { createPrefixStream } from 'procband'
+
+const output = createPrefixStream({ label: 'postgres' })
+output.pipe(process.stdout)
+postgres.stdout.pipe(output)
+```
+
+The transform preserves stream backpressure, buffers partial lines and UTF-8
+characters across chunks, and flushes a final unterminated line when input ends.
+Pass `color: [red, green, blue]` to select a prefix color; otherwise procband
+assigns the next color from its shared palette.
+
+## Documentation
+
+Start with the page that matches the decision in front of you:
+
+| Page                                                      | Use it when                                                      |
+| --------------------------------------------------------- | ---------------------------------------------------------------- |
+| [Docs overview](docs/index.md)                            | You need the moving parts, boundaries, and next page to read.    |
+| [Readiness and matching](docs/guides/readiness.md)        | A script must wait for output or react to repeated log lines.    |
+| [Restart failed processes](docs/guides/restarts.md)       | A child can fail transiently and should be retried with limits.  |
+| [Foreground commands](docs/guides/foreground-commands.md) | A script step should reject when a command exits unsuccessfully. |
+| [Concepts and lifecycle](docs/context.md)                 | You need lifecycle, shutdown, error, and invariant details.      |
 
-- Concepts and lifecycle: [docs/context.md](docs/context.md)
-- Minimal usage example: [examples/basic-usage.ts](examples/basic-usage.ts)
-- Restart example: [examples/restart-on-failure.ts](examples/restart-on-failure.ts)
-- Sequencing example: [examples/sequenced-processes.ts](examples/sequenced-processes.ts)
-- Exact exported signatures: [dist/index.d.mts](dist/index.d.mts)
+Runnable examples live in [`examples/`](examples/). Exact public signatures are
+generated from the TypeScript source and published through
+[`dist/index.d.mts`](dist/index.d.mts).

package/dist/index.d.mts

@@ -1,5 +1,5 @@
+import { Readable, Transform, Writable } from "node:stream";
 import { ChildProcess } from "node:child_process";
-import { Readable, Writable } from "node:stream";
 
 //#region src/types.d.ts
 /**
@@ -62,6 +62,12 @@ interface ProcessConfig {
    * Defaults to `name`.
    */
   label?: string;
+  /**
+   * Whether child output should be prefixed with the process label.
+   *
+   * Defaults to `true`. Set to `false` for raw child output.
+   */
+  prefix?: boolean;
   /**
    * RGB color for this process's `stdout` prefix.
    *
@@ -104,6 +110,20 @@ interface ProcessConfig {
  * A 24-bit RGB color tuple.
  */
 type RgbColor = readonly [red: number, green: number, blue: number];
+/**
+ * Options for `createPrefixStream()`.
+ */
+interface PrefixStreamOptions {
+  /** Human-facing label added to each output line. */
+  label: string;
+  /**
+   * RGB color for the prefix.
+   *
+   * When omitted, `procband` assigns the next color from its default palette.
+   * The reserved `stderr` red cannot be used here.
+   */
+  color?: RgbColor;
+}
 /**
  * Controls whether and how a supervised process restarts after exit.
  */
@@ -221,6 +241,18 @@ interface ProcessResult {
    */
   restartSuppressed: boolean;
 }
+/**
+ * Options for `wait()`.
+ */
+interface WaitOptions {
+  /**
+   * Reject with `ProcessExitError` when the process exits unsuccessfully.
+   *
+   * Defaults to `false`, preserving procband's supervision-oriented behavior
+   * where terminal failures resolve to `ProcessResult`.
+   */
+  rejectOnFailure?: boolean;
+}
 /**
  * A supervised child-process handle.
  *
@@ -257,11 +289,16 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
   /**
    * Wait for the process to become terminal with no further restart pending.
    *
-   * Unlike many process helpers, this resolves for both success and failure.
-   * Inspect the returned `ProcessResult` instead of relying on promise
-   * rejection for non-zero exits.
+   * By default this resolves for both success and failure. Pass
+   * `rejectOnFailure: true` to reject failed exits with `ProcessExitError`.
    */
-  wait(): Promise<ProcessResult>;
+  wait(options?: WaitOptions): Promise<ProcessResult>;
+  /**
+   * Wait for the process to become terminal and reject if it fails.
+   *
+   * This is equivalent to `wait({ rejectOnFailure: true })`.
+   */
+  expectSuccess(): Promise<ProcessResult>;
   /**
    * Disable future restarts and terminate the active process tree.
    *
@@ -273,6 +310,44 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
   kill(signal?: KillSignal): boolean;
 }
 //#endregion
+//#region src/errors.d.ts
+/**
+ * Error thrown when a process was expected to exit successfully but did not.
+ */
+declare class ProcessExitError extends Error {
+  readonly config: ProcessConfig;
+  readonly result: ProcessResult;
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly code: number | null;
+  readonly exitCode: number;
+  readonly signal: NodeJS.Signals | null;
+  constructor(config: ProcessConfig, result: ProcessResult);
+}
+//#endregion
+//#region src/prefix-stream.d.ts
+/**
+ * Create a transform that prefixes arbitrary output with a procband label.
+ *
+ * The transform buffers incomplete lines and UTF-8 sequences across chunks.
+ * CRLF input is normalized to LF, matching supervised process output, and a
+ * final unterminated line is emitted when the writable side ends.
+ *
+ * @param options Label and optional prefix color.
+ * @returns A backpressure-aware Node.js transform stream.
+ * @throws When `options.color` is invalid or uses procband's reserved stderr
+ * color.
+ * @example
+ * ```ts
+ * import { createPrefixStream } from 'procband'
+ *
+ * const output = createPrefixStream({ label: 'postgres' })
+ * output.pipe(process.stdout)
+ * postgres.stdout.pipe(output)
+ * ```
+ */
+declare function createPrefixStream(options: PrefixStreamOptions): Transform;
+//#endregion
 //#region src/process.d.ts
 /**
  * Start supervising a single subprocess.
@@ -303,4 +378,4 @@ interface ProcbandProcess extends ChildProcess, PromiseLike<ProcessResult> {
  */
 declare function supervise(config: ProcessConfig): ProcbandProcess;
 //#endregion
-export { type MatchCallback, type MatchEvent, type MatchOptions, type ProcbandProcess, type ProcessConfig, type ProcessResult, type RestartPolicy, type RgbColor, type Unsubscribe, type WaitForOptions, supervise };
+export { type MatchCallback, type MatchEvent, type MatchOptions, type PrefixStreamOptions, type ProcbandProcess, type ProcessConfig, ProcessExitError, type ProcessResult, type RestartPolicy, type RgbColor, type Unsubscribe, type WaitForOptions, type WaitOptions, createPrefixStream, supervise };

package/dist/index.mjs

@@ -1,10 +1,51 @@
+import { StringDecoder } from "node:string_decoder";
+import { Transform } from "node:stream";
+import ansiStyles from "ansi-styles";
 import { spawn } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { constants } from "node:os";
 import process from "node:process";
-import ansiStyles from "ansi-styles";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import treeKill, { treeKillSync } from "@alloc/tree-kill";
+//#region src/errors.ts
+/**
+* Error thrown when a process was expected to exit successfully but did not.
+*/
+var ProcessExitError = class extends Error {
+	config;
+	result;
+	command;
+	args;
+	code;
+	exitCode;
+	signal;
+	constructor(config, result) {
+		super(formatProcessExitMessage(config, result));
+		this.name = "ProcessExitError";
+		this.config = config;
+		this.result = result;
+		this.command = config.command;
+		this.args = [...config.args ?? []];
+		this.code = result.code;
+		this.exitCode = result.exitCode;
+		this.signal = result.signal;
+	}
+};
+function formatProcessExitMessage(config, result) {
+	const command = formatCommand(config);
+	const prefix = `Process "${result.name}" failed: ${command}`;
+	if (result.signal) return `${prefix} exited by signal ${result.signal} (exit code ${result.exitCode})`;
+	if (result.code != null) return `${prefix} exited with code ${result.code}`;
+	return `${prefix} exited unsuccessfully (exit code ${result.exitCode})`;
+}
+function formatCommand(config) {
+	return [config.command, ...config.args ?? []].map(formatCommandPart).join(" ");
+}
+function formatCommandPart(value) {
+	if (/^[\w./:=@%+,-]+$/.test(value)) return value;
+	return JSON.stringify(value);
+}
+//#endregion
 //#region src/colors.ts
 const prefixPalette = [
 	[
@@ -70,23 +111,87 @@ function resolveProcessColor(color) {
 	nextPaletteIndex += 1;
 	return [...paletteColor];
 }
-function validateProcessColor(color) {
+function validateProcessColor(color, optionName = "ProcessConfig.color") {
 	if (!color) return;
 	const [red, green, blue] = color;
 	for (const value of [
 		red,
 		green,
 		blue
-	]) if (!Number.isInteger(value) || value < 0 || value > 255) throw new Error("ProcessConfig.color must contain integer RGB values between 0 and 255");
-	if (red === stderrColor[0] && green === stderrColor[1] && blue === stderrColor[2]) throw new Error("ProcessConfig.color cannot use the reserved stderr color");
+	]) if (!Number.isInteger(value) || value < 0 || value > 255) throw new Error(`${optionName} must contain integer RGB values between 0 and 255`);
+	if (red === stderrColor[0] && green === stderrColor[1] && blue === stderrColor[2]) throw new Error(`${optionName} cannot use the reserved stderr color`);
 }
 function writePrefixedLine(target, label, color, line, appendNewline) {
-	target.write(formatPrefix(label, color) + line + (appendNewline ? "\n" : ""));
+	target.write(formatPrefixedLine(label, color, line, appendNewline));
+}
+function formatPrefixedLine(label, color, line, appendNewline) {
+	return (label == null ? "" : formatPrefix(label, color)) + line + (appendNewline ? "\n" : "");
 }
 function formatPrefix(label, color) {
 	return `${ansiStyles.color.ansi16m(...color)}[${label}]${ansiStyles.color.close} `;
 }
 //#endregion
+//#region src/prefix-stream.ts
+/**
+* Create a transform that prefixes arbitrary output with a procband label.
+*
+* The transform buffers incomplete lines and UTF-8 sequences across chunks.
+* CRLF input is normalized to LF, matching supervised process output, and a
+* final unterminated line is emitted when the writable side ends.
+*
+* @param options Label and optional prefix color.
+* @returns A backpressure-aware Node.js transform stream.
+* @throws When `options.color` is invalid or uses procband's reserved stderr
+* color.
+* @example
+* ```ts
+* import { createPrefixStream } from 'procband'
+*
+* const output = createPrefixStream({ label: 'postgres' })
+* output.pipe(process.stdout)
+* postgres.stdout.pipe(output)
+* ```
+*/
+function createPrefixStream(options) {
+	validateProcessColor(options.color, "PrefixStreamOptions.color");
+	return new PrefixTransform(options.label, resolveProcessColor(options.color));
+}
+var PrefixTransform = class extends Transform {
+	decoder = new StringDecoder("utf8");
+	label;
+	color;
+	bufferedText = "";
+	constructor(label, color) {
+		super();
+		this.label = label;
+		this.color = color;
+	}
+	_transform(chunk, _encoding, callback) {
+		this.consume(this.decoder.write(chunk));
+		callback();
+	}
+	_flush(callback) {
+		this.consume(this.decoder.end());
+		if (this.bufferedText.length > 0) {
+			this.push(formatPrefixedLine(this.label, this.color, this.bufferedText, false));
+			this.bufferedText = "";
+		}
+		callback();
+	}
+	consume(decodedText) {
+		let text = this.bufferedText + decodedText;
+		let newlineIndex = text.indexOf("\n");
+		while (newlineIndex >= 0) {
+			const rawLine = text.slice(0, newlineIndex);
+			const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+			this.push(formatPrefixedLine(this.label, this.color, line, true));
+			text = text.slice(newlineIndex + 1);
+			newlineIndex = text.indexOf("\n");
+		}
+		this.bufferedText = text;
+	}
+};
+//#endregion
 //#region src/matching.ts
 var MatchRegistry = class {
 	subscriptions = /* @__PURE__ */ new Set();
@@ -400,6 +505,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	config;
 	name;
 	label;
+	prefix;
 	color;
 	matches;
 	restart;
@@ -422,6 +528,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		this.config = config;
 		this.name = name;
 		this.label = config.label ?? name;
+		this.prefix = config.name === "" ? false : config.prefix ?? true;
 		this.color = resolveProcessColor(config.color);
 		this.matches = new MatchRegistry(this.name);
 		this.restart = new RestartController(config.restart);
@@ -480,10 +587,14 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	waitFor(pattern, options) {
 		return this.matches.waitFor(pattern, options);
 	}
-	wait() {
+	wait(options) {
 		this.markTerminalResultObserved();
+		if (options?.rejectOnFailure) return this.finalPromise.then((result) => this.expectSuccessfulResult(result));
 		return this.finalPromise;
 	}
+	expectSuccess() {
+		return this.wait({ rejectOnFailure: true });
+	}
 	then(onfulfilled, onrejected) {
 		this.markTerminalResultObserved();
 		return this.finalPromise.then(onfulfilled, onrejected);
@@ -626,7 +737,7 @@ var ProcbandProcessImpl = class extends EventEmitter {
 		buffer.text = text;
 	}
 	handleLine(stream, line, appendNewline) {
-		writePrefixedLine(stream === "stdout" ? process.stdout : process.stderr, this.label, stream === "stdout" ? this.color : stderrColor, line, appendNewline);
+		writePrefixedLine(stream === "stdout" ? process.stdout : process.stderr, this.prefix ? this.label : null, stream === "stdout" ? this.color : stderrColor, line, appendNewline);
 		this.matches.emit(stream, line);
 	}
 	async handleAttemptClose(code, signal) {
@@ -669,12 +780,16 @@ var ProcbandProcessImpl = class extends EventEmitter {
 	}
 	closeMatches() {
 		const error = /* @__PURE__ */ new Error(`Process "${this.name}" exited before a matching line was observed`);
-		if (this.matches.hasPendingWait()) writePrefixedLine(process.stderr, this.label, stderrColor, error.message, true);
+		if (this.matches.hasPendingWait()) writePrefixedLine(process.stderr, this.prefix ? this.label : null, stderrColor, error.message, true);
 		this.matches.close(error);
 	}
 	markTerminalResultObserved() {
 		this.terminalResultObserved = true;
 	}
+	expectSuccessfulResult(result) {
+		if (isFailedResult(result)) throw new ProcessExitError(this.config, result);
+		return result;
+	}
 	shouldPropagateFailure(result) {
 		return result.exitCode !== 0 && !this.shutdownRequested && !this.terminalResultObserved;
 	}
@@ -734,7 +849,7 @@ let propagatedFailure = false;
 function validateProcessConfig(config) {
 	if (!config.command) throw new Error("ProcessConfig.command is required");
 	validateProcessColor(config.color);
-	const name = config.name || inferProcessName(config.command);
+	const name = config.name === void 0 || config.name === "" ? inferProcessName(config.command) : config.name;
 	if (!name) throw new Error("ProcessConfig.name is required when command does not match /[-\\w]+$/");
 	return name;
 }
@@ -746,6 +861,9 @@ function getResultExitCode(code, signal) {
 	if (signal) return 128 + (constants.signals[signal] ?? 0);
 	return 1;
 }
+function isFailedResult(result) {
+	return result.exitCode !== 0 || result.signal != null;
+}
 function propagateFailure(exitCode) {
 	if (propagatedFailure) return;
 	propagatedFailure = true;
@@ -756,4 +874,4 @@ function propagateFailure(exitCode) {
 	});
 }
 //#endregion
-export { supervise };
+export { ProcessExitError, createPrefixStream, supervise };