procband 0.3.6 → 0.3.7

package/README.md

@@ -85,6 +85,24 @@ 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:

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
 /**
@@ -110,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.
  */
@@ -311,6 +325,29 @@ declare class ProcessExitError extends Error {
   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.
@@ -341,4 +378,4 @@ declare class ProcessExitError extends Error {
  */
 declare function supervise(config: ProcessConfig): ProcbandProcess;
 //#endregion
-export { type MatchCallback, type MatchEvent, type MatchOptions, type ProcbandProcess, type ProcessConfig, ProcessExitError, type ProcessResult, type RestartPolicy, type RgbColor, type Unsubscribe, type WaitForOptions, type WaitOptions, 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,8 +1,10 @@
+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
@@ -109,24 +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) {
-	const prefix = label == null ? "" : formatPrefix(label, color);
-	target.write(prefix + 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();
@@ -809,4 +874,4 @@ function propagateFailure(exitCode) {
 	});
 }
 //#endregion
-export { ProcessExitError, supervise };
+export { ProcessExitError, createPrefixStream, supervise };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procband",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Supervise subprocesses from TypeScript: prefix logs, wait for output patterns, and manage lifecycle/restarts.",
   "packageManager": "pnpm@11.5.1",
   "license": "MIT",