@f5xc-salesdemos/pi-utils 14.0.2

package/src/ptree.ts

@@ -0,0 +1,386 @@
+/**
+ * Process tree management utilities for Bun subprocesses.
+ *
+ * - Track managed child processes for cleanup on shutdown (postmortem).
+ * - Drain stdout/stderr to avoid subprocess pipe deadlocks.
+ * - Cross-platform tree kill for process groups (Windows taskkill, Unix -pid).
+ * - Convenience helpers: captureText / execText, AbortSignal, timeouts.
+ */
+import type { Spawn, Subprocess } from "bun";
+import { terminate } from "./procmgr";
+
+type InMask = "pipe" | "ignore" | Buffer | Uint8Array | null;
+
+/** A Bun subprocess with stdout/stderr always piped (stdin may vary). */
+type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe">;
+
+// ── Exceptions ───────────────────────────────────────────────────────────────
+
+/**
+ * Base for all exceptions representing child process nonzero exit, killed, or
+ * cancellation.
+ */
+export abstract class Exception extends Error {
+	constructor(
+		message: string,
+		public readonly exitCode: number,
+		public readonly stderr: string,
+	) {
+		super(message);
+		this.name = this.constructor.name;
+	}
+	abstract readonly aborted: boolean;
+}
+
+/** Exception for nonzero exit codes (not cancellation). */
+export class NonZeroExitError extends Exception {
+	static readonly MAX_TRACE = 32 * 1024;
+
+	constructor(exitCode: number, stderr: string) {
+		super(`Process exited with code ${exitCode}:\n${stderr}`, exitCode, stderr);
+	}
+	get aborted() {
+		return false;
+	}
+}
+
+/** Exception for explicit process abortion (via signal). */
+export class AbortError extends Exception {
+	constructor(
+		public readonly reason: unknown,
+		stderr: string,
+	) {
+		const msg = reason instanceof Error ? reason.message : String(reason ?? "aborted");
+		super(`Operation cancelled: ${msg}`, -1, stderr);
+	}
+	get aborted() {
+		return true;
+	}
+}
+
+/** Exception for process timeout. */
+export class TimeoutError extends AbortError {
+	constructor(timeout: number, stderr: string) {
+		super(new Error(`Timed out after ${Math.round(timeout / 1000)}s`), stderr);
+	}
+}
+
+// ── Wait / Exec types ────────────────────────────────────────────────────────
+
+/** Options for waiting for process exit and capturing output. */
+export interface WaitOptions {
+	allowNonZero?: boolean;
+	allowAbort?: boolean;
+	stderr?: "full" | "buffer";
+}
+
+/** Result from wait and exec. */
+export interface ExecResult {
+	stdout: string;
+	stderr: string;
+	exitCode: number | null;
+	ok: boolean;
+	exitError?: Exception;
+}
+
+// ── ChildProcess ─────────────────────────────────────────────────────────────
+
+/**
+ * ChildProcess wraps a managed subprocess, capturing stderr tail, providing
+ * cross-platform kill/detach logic plus AbortSignal integration.
+ *
+ * Stdout is exposed directly from the underlying Bun subprocess; consumers
+ * must read it (via text(), wait(), etc.) to prevent pipe deadlock.
+ * Stderr is eagerly drained into an internal buffer.
+ */
+export class ChildProcess<In extends InMask = InMask> {
+	#nothrow = false;
+	#stderrTail = "";
+	#stderrChunks: Uint8Array[] = [];
+	#exitReason?: Exception;
+	#exitReasonPending?: Exception;
+	#stderrDone: Promise<void>;
+	#exited: Promise<number>;
+	#stderrStream?: ReadableStream<Uint8Array>;
+
+	constructor(
+		readonly proc: PipedSubprocess<In>,
+		readonly exposeStderr: boolean,
+	) {
+		// Eagerly drain stderr into a truncated tail string + raw chunks.
+		const dec = new TextDecoder();
+		const trim = () => {
+			if (this.#stderrTail.length > NonZeroExitError.MAX_TRACE)
+				this.#stderrTail = this.#stderrTail.slice(-NonZeroExitError.MAX_TRACE);
+		};
+		let stderrStream = proc.stderr;
+		if (exposeStderr) {
+			const [teeStream, drainStream] = stderrStream.tee();
+			this.#stderrStream = teeStream;
+			stderrStream = drainStream;
+		}
+		this.#stderrDone = (async () => {
+			try {
+				for await (const chunk of stderrStream) {
+					this.#stderrChunks.push(chunk);
+					this.#stderrTail += dec.decode(chunk, { stream: true });
+					trim();
+				}
+			} catch {}
+			this.#stderrTail += dec.decode();
+			trim();
+		})();
+
+		// Normalize Bun's exited promise into our exitReason / exitedCleanly model.
+		const { promise, resolve, reject } = Promise.withResolvers<number>();
+		this.#exited = promise;
+
+		proc.exited
+			.catch(() => null)
+			.then(async exitCode => {
+				if (this.#exitReasonPending) {
+					this.#exitReason = this.#exitReasonPending;
+					reject(this.#exitReasonPending);
+					return;
+				}
+				if (exitCode === 0) {
+					resolve(0);
+					return;
+				}
+
+				await this.#stderrDone;
+
+				if (exitCode !== null) {
+					this.#exitReason = new NonZeroExitError(exitCode, this.#stderrTail);
+					resolve(exitCode);
+					return;
+				}
+
+				const ex = this.proc.killed
+					? new AbortError(new Error("process killed"), this.#stderrTail)
+					: new NonZeroExitError(-1, this.#stderrTail);
+				this.#exitReason = ex;
+				reject(ex);
+			});
+	}
+
+	// ── Properties ───────────────────────────────────────────────────────
+
+	get pid() {
+		return this.proc.pid;
+	}
+	get exited() {
+		return this.#exited;
+	}
+	get exitCode() {
+		return this.proc.exitCode;
+	}
+	get exitReason() {
+		return this.#exitReason;
+	}
+	get killed() {
+		return this.proc.killed;
+	}
+	get stdin(): Bun.SpawnOptions.WritableToIO<In> {
+		return this.proc.stdin;
+	}
+
+	/** Raw stdout stream. Must be consumed to prevent pipe deadlock. */
+	get stdout() {
+		return this.proc.stdout;
+	}
+
+	/** Optional stderr stream (only when requested in spawn options). */
+	get stderr() {
+		return this.#stderrStream;
+	}
+
+	get exitedCleanly(): Promise<number> {
+		if (this.#nothrow) return this.#exited;
+		return this.#exited.then(code => {
+			if (code !== 0) throw new NonZeroExitError(code, this.#stderrTail);
+			return code;
+		});
+	}
+
+	/** Returns the truncated stderr tail (last 32KB). */
+	peekStderr() {
+		return this.#stderrTail;
+	}
+
+	nothrow(): this {
+		this.#nothrow = true;
+		return this;
+	}
+
+	kill(reason?: Exception) {
+		if (reason && !this.#exitReasonPending) this.#exitReasonPending = reason;
+		if (!this.proc.killed) void terminate({ target: this.proc });
+	}
+
+	// ── Output helpers ───────────────────────────────────────────────────
+
+	async text(): Promise<string> {
+		const p = new Response(this.stdout).text();
+		if (this.#nothrow) return p;
+		const [text] = await Promise.all([p, this.exitedCleanly]);
+		return text;
+	}
+
+	async blob(): Promise<Blob> {
+		const p = new Response(this.stdout).blob();
+		if (this.#nothrow) return p;
+		const [blob] = await Promise.all([p, this.exitedCleanly]);
+		return blob;
+	}
+
+	async json(): Promise<unknown> {
+		return new Response(this.stdout).json();
+	}
+
+	async arrayBuffer(): Promise<ArrayBuffer> {
+		return new Response(this.stdout).arrayBuffer();
+	}
+
+	async bytes(): Promise<Uint8Array> {
+		return new Response(this.stdout).bytes();
+	}
+
+	// ── Wait ─────────────────────────────────────────────────────────────
+
+	async wait(opts?: WaitOptions): Promise<ExecResult> {
+		const { allowNonZero = false, allowAbort = false, stderr: stderrMode = "buffer" } = opts ?? {};
+
+		const stdoutP = new Response(this.stdout).text();
+		const stderrP =
+			stderrMode === "full"
+				? this.#stderrDone.then(() => new TextDecoder().decode(Buffer.concat(this.#stderrChunks)))
+				: this.#stderrDone.then(() => this.#stderrTail);
+
+		const [stdout, stderr] = await Promise.all([stdoutP, stderrP]);
+
+		let exitError: Exception | undefined;
+		try {
+			await this.#exited;
+		} catch (err) {
+			if (err instanceof Exception) exitError = err;
+			else throw err;
+		}
+
+		if (!exitError) exitError = this.exitReason;
+		if (!exitError && this.exitCode !== null && this.exitCode !== 0) {
+			exitError = new NonZeroExitError(this.exitCode, this.#stderrTail);
+		}
+
+		const exitCode = this.exitCode ?? (exitError && !exitError.aborted ? exitError.exitCode : null);
+		const ok = exitCode === 0;
+
+		if (exitError) {
+			if ((exitError.aborted && !allowAbort) || (!exitError.aborted && !allowNonZero)) throw exitError;
+		}
+
+		return { stdout, stderr, exitCode, ok, exitError };
+	}
+
+	// ── Signal / timeout ─────────────────────────────────────────────────
+
+	attachSignal(signal: AbortSignal): void {
+		const onAbort = () => this.kill(new AbortError(signal.reason, "<cancelled>"));
+		if (signal.aborted) return void onAbort();
+		signal.addEventListener("abort", onAbort, { once: true });
+		this.#exited.catch(() => {}).finally(() => signal.removeEventListener("abort", onAbort));
+	}
+
+	attachTimeout(ms: number): void {
+		if (ms <= 0 || this.proc.killed) return;
+		Promise.race([
+			Bun.sleep(ms).then(() => true),
+			this.proc.exited.then(
+				() => false,
+				() => false,
+			),
+		]).then(timedOut => {
+			if (timedOut) this.kill(new TimeoutError(ms, this.#stderrTail));
+		});
+	}
+
+	[Symbol.dispose](): void {
+		if (this.proc.exitCode !== null) return;
+		this.kill(new AbortError("process disposed", this.#stderrTail));
+	}
+}
+
+// ── Spawn / exec ─────────────────────────────────────────────────────────────
+
+/** Options for child spawn. Always pipes stdout/stderr. */
+type ChildSpawnOptions<In extends InMask = InMask> = Omit<
+	Spawn.SpawnOptions<In, "pipe", "pipe">,
+	"stdout" | "stderr" | "detached"
+> & {
+	signal?: AbortSignal;
+	detached?: boolean;
+	stderr?: "full" | null;
+};
+
+/** Spawn a child process with piped stdout/stderr. */
+export function spawn<In extends InMask = InMask>(cmd: string[], opts?: ChildSpawnOptions<In>): ChildProcess<In> {
+	const { timeout = -1, signal, stderr, ...rest } = opts ?? {};
+	const child = Bun.spawn(cmd, {
+		stdin: "ignore",
+		stdout: "pipe",
+		stderr: "pipe",
+		windowsHide: true,
+		...rest,
+	});
+	const cp = new ChildProcess(child, stderr === "full");
+	if (signal) cp.attachSignal(signal);
+	if (timeout > 0) cp.attachTimeout(timeout);
+	return cp;
+}
+
+/** Options for exec. */
+export interface ExecOptions extends Omit<ChildSpawnOptions, "stderr" | "stdin">, WaitOptions {
+	input?: string | Buffer | Uint8Array;
+}
+
+/** Spawn, wait, and return captured output. */
+export async function exec(cmd: string[], opts?: ExecOptions): Promise<ExecResult> {
+	const { input, stderr, allowAbort, allowNonZero, ...spawnOpts } = opts ?? {};
+	const stdin = typeof input === "string" ? Buffer.from(input) : input;
+	const resolved: ChildSpawnOptions = stdin === undefined ? spawnOpts : { ...spawnOpts, stdin };
+	using child = spawn(cmd, resolved);
+	return await child.wait({ stderr, allowAbort, allowNonZero });
+}
+
+// ── Signal combinators ───────────────────────────────────────────────────────
+
+type SignalValue = AbortSignal | number | null | undefined;
+
+/** Combine AbortSignals and timeout values into a single signal. */
+export function combineSignals(...signals: SignalValue[]): AbortSignal | undefined {
+	let timeout: number | undefined;
+
+	let n = 0;
+	for (let i = 0; i < signals.length; i++) {
+		const s = signals[i];
+		if (s instanceof AbortSignal) {
+			if (s.aborted) return s;
+			if (i !== n) signals[n] = s;
+			n++;
+		} else if (typeof s === "number" && s > 0) {
+			timeout = timeout === undefined ? s : Math.min(timeout, s);
+		}
+	}
+	if (timeout !== undefined) {
+		signals[n] = AbortSignal.timeout(timeout);
+		n++;
+	}
+	switch (n) {
+		case 0:
+			return undefined;
+		case 1:
+			return signals[0] as AbortSignal;
+		default:
+			return AbortSignal.any(signals.slice(0, n) as AbortSignal[]);
+	}
+}

package/src/ring.ts

@@ -0,0 +1,169 @@
+/**
+ * A fixed-capacity circular buffer that supports efficient push/pop/shift/unshift operations.
+ * When the buffer is full, adding new items overwrites the oldest items (FIFO behavior).
+ *
+ * @template T The type of elements stored in the buffer.
+ */
+export class RingBuffer<T> {
+	#buf: (T | undefined)[];
+	#head = 0;
+	#size = 0;
+
+	/**
+	 * Creates a new ring buffer with the specified capacity.
+	 *
+	 * @param capacity - The maximum number of elements the buffer can hold. Must be positive.
+	 */
+	constructor(public readonly capacity: number) {
+		this.#buf = new Array(capacity);
+	}
+
+	/**
+	 * The number of elements currently in the buffer.
+	 */
+	get length(): number {
+		return this.#size;
+	}
+
+	/**
+	 * Whether the buffer is at full capacity.
+	 */
+	get isFull(): boolean {
+		return this.#size === this.capacity;
+	}
+
+	/**
+	 * Whether the buffer is empty (contains no elements).
+	 */
+	get isEmpty(): boolean {
+		return this.#size === 0;
+	}
+
+	/**
+	 * Adds an item to the end of the buffer.
+	 * If the buffer is full, the oldest item is overwritten and returned.
+	 *
+	 * @param item - The item to add.
+	 * @returns The overwritten item if the buffer was full, otherwise `undefined`.
+	 */
+	push(item: T): T | undefined {
+		const idx = (this.#head + this.#size) % this.capacity;
+		const overwritten = this.#size === this.capacity ? this.#buf[idx] : undefined;
+		this.#buf[idx] = item;
+		if (this.#size === this.capacity) {
+			this.#head = (this.#head + 1) % this.capacity;
+		} else {
+			this.#size++;
+		}
+		return overwritten;
+	}
+
+	/**
+	 * Removes and returns the first (oldest) item from the buffer.
+	 *
+	 * @returns The removed item, or `undefined` if the buffer is empty.
+	 */
+	shift(): T | undefined {
+		if (this.#size === 0) return undefined;
+		const item = this.#buf[this.#head];
+		this.#buf[this.#head] = undefined;
+		this.#head = (this.#head + 1) % this.capacity;
+		this.#size--;
+		return item;
+	}
+
+	/**
+	 * Removes and returns the last (newest) item from the buffer.
+	 *
+	 * @returns The removed item, or `undefined` if the buffer is empty.
+	 */
+	pop(): T | undefined {
+		if (this.#size === 0) return undefined;
+		const idx = (this.#head + this.#size - 1) % this.capacity;
+		const item = this.#buf[idx];
+		this.#buf[idx] = undefined;
+		this.#size--;
+		return item;
+	}
+
+	/**
+	 * Adds an item to the beginning of the buffer.
+	 * If the buffer is full, the newest item is overwritten and returned.
+	 *
+	 * @param item - The item to add.
+	 * @returns The overwritten item if the buffer was full, otherwise `undefined`.
+	 */
+	unshift(item: T): T | undefined {
+		this.#head = (this.#head - 1 + this.capacity) % this.capacity;
+		const overwritten = this.#size === this.capacity ? this.#buf[this.#head] : undefined;
+		this.#buf[this.#head] = item;
+		if (this.#size < this.capacity) this.#size++;
+		return overwritten;
+	}
+
+	/**
+	 * Returns the element at the specified index without removing it.
+	 * Supports negative indices (e.g., `-1` for the last element).
+	 *
+	 * @param index - The zero-based index, or negative index from the end.
+	 * @returns The element at the index, or `undefined` if the index is out of bounds.
+	 */
+	at(index: number): T | undefined {
+		if (index < 0) index += this.#size;
+		if (index < 0 || index >= this.#size) return undefined;
+		return this.#buf[(this.#head + index) % this.capacity];
+	}
+
+	/**
+	 * Returns the first (oldest) element without removing it.
+	 *
+	 * @returns The first element, or `undefined` if the buffer is empty.
+	 */
+	peek(): T | undefined {
+		return this.at(0);
+	}
+
+	/**
+	 * Returns the last (newest) element without removing it.
+	 *
+	 * @returns The last element, or `undefined` if the buffer is empty.
+	 */
+	peekBack(): T | undefined {
+		return this.at(this.#size - 1);
+	}
+
+	/**
+	 * Removes all elements from the buffer, resetting it to an empty state.
+	 */
+	clear(): void {
+		this.#buf.fill(undefined, 0, this.capacity);
+		this.#head = 0;
+		this.#size = 0;
+	}
+
+	/**
+	 * Returns an iterator that yields elements in logical order (oldest to newest).
+	 * Allows the buffer to be used with `for...of` loops and spread syntax.
+	 *
+	 * @yields Elements in FIFO order.
+	 */
+	*[Symbol.iterator](): Iterator<T> {
+		for (let i = 0; i < this.#size; i++) {
+			yield this.#buf[(this.#head + i) % this.capacity] as T;
+		}
+	}
+
+	/**
+	 * Creates a new array containing all elements in logical order (oldest to newest).
+	 *
+	 * @returns A new array with all buffer elements.
+	 */
+	toArray(): T[] {
+		if (this.#head + this.#size <= this.capacity) {
+			return this.#buf.slice(this.#head, this.#head + this.#size) as T[];
+		}
+		const tail = this.#buf.slice(this.#head, this.capacity);
+		const head = this.#buf.slice(0, (this.#head + this.#size) % this.capacity);
+		return tail.concat(head) as T[];
+	}
+}

package/src/snowflake.ts

@@ -0,0 +1,136 @@
+// 16-bit hex lookup table (65536 entries) for fast conversion
+const HEX4 = Array.from({ length: 65536 }, (_, i) => i.toString(16).padStart(4, "0"));
+
+function randu32() {
+	return crypto.getRandomValues(new Uint32Array(1))[0];
+}
+
+const EPOCH = 1420070400000;
+const MAX_SEQ = 0x3fffff;
+
+// Snowflake as a hex string (16 chars, zero-padded).
+//
+// Since this is not distributed (no machine ID needed), we use an extended
+// 22-bit sequence instead of the standard 10-bit machine ID + 12-bit sequence.
+//
+type Snowflake = string & { readonly __brand: unique symbol };
+
+namespace Snowflake {
+	// Hex string validation pattern (16 lowercase hex chars).
+	//
+	export const PATTERN = /^[0-9a-f]{16}$/;
+
+	// Epoch timestamp.
+	//
+	export const EPOCH_TIMESTAMP = EPOCH;
+
+	// Maximum sequence number.
+	//
+	export const MAX_SEQUENCE = MAX_SEQ;
+
+	// Parses a hex string or bigint to bigint.
+	//
+	function toBigInt(value: Snowflake): bigint {
+		const hi = Number.parseInt(value.substring(0, 8), 16);
+		const lo = Number.parseInt(value.substring(8, 16), 16);
+		return (BigInt(hi) << 32n) | BigInt(lo);
+	}
+
+	// Formats a sequence and timestamp into a snowflake hex string.
+	//
+	export function formatParts(dt: number, seq: number): Snowflake {
+		// Split dt into hi/lo to avoid exceeding Number.MAX_SAFE_INTEGER.
+		// dt is ~39 bits; dt<<22 would be ~61 bits, so we split at bit 10:
+		//   lo32 = (dtLo << 22) | seq   (10+22 = 32 bits, no overlap)
+		//   hi32 = dtHi                 (~29 bits)
+		const dtLo = dt % 1024;
+		const hi = (dt - dtLo) / 1024; // dt >>> 10
+		const lo = ((dtLo << 22) | seq) >>> 0;
+		const hi1 = (hi >>> 16) & 0xffff;
+		const hi2 = hi & 0xffff;
+		const lo1 = (lo >>> 16) & 0xffff;
+		const lo2 = lo & 0xffff;
+		return `${HEX4[hi1]}${HEX4[hi2]}${HEX4[lo1]}${HEX4[lo2]}` as Snowflake;
+	}
+
+	// Snowflake generator type.
+	//
+	export class Source {
+		#seq = 0;
+		constructor(sequence: number = randu32() & MAX_SEQ) {
+			this.#seq = sequence & MAX_SEQ;
+		}
+
+		// Sequence number.
+		//
+		get sequence() {
+			return this.#seq & MAX_SEQ;
+		}
+		set sequence(v: number) {
+			this.#seq = v & MAX_SEQ;
+		}
+		reset() {
+			this.#seq = 0;
+		}
+
+		// Generates the next value as a hex string.
+		//
+		generate(timestamp: number): Snowflake {
+			const seq = (this.#seq + 1) & MAX_SEQ;
+			const dt = timestamp - EPOCH;
+			this.#seq = seq;
+			return formatParts(dt, seq);
+		}
+	}
+
+	// Gets the next snowflake given the timestamp.
+	//
+	const defaultSource = new Source();
+	export function next(timestamp = Date.now()): Snowflake {
+		return defaultSource.generate(timestamp);
+	}
+
+	// Validates a snowflake hex string.
+	//
+	export function valid(value: string): value is Snowflake {
+		return value.length === 16 && PATTERN.test(value);
+	}
+
+	// Returns the upper/lower boundaries for the given timestamp.
+	//
+	export function lowerbound(timelike: Date | number | Snowflake): Snowflake {
+		switch (typeof timelike) {
+			case "object": // Date
+				return formatParts(timelike.getTime() - EPOCH, 0);
+			case "number":
+				return formatParts(timelike - EPOCH, 0);
+			case "string": // Snowflake hex string
+				return timelike;
+		}
+	}
+	export function upperbound(timelike: Date | number | Snowflake): Snowflake {
+		switch (typeof timelike) {
+			case "object": // Date
+				return formatParts(timelike.getTime() - EPOCH, MAX_SEQ);
+			case "number":
+				return formatParts(timelike - EPOCH, MAX_SEQ);
+			case "string": // Snowflake hex string
+				return timelike;
+		}
+	}
+
+	// Returns the individual bits given the snowflake.
+	//
+	export function getSequence(value: Snowflake) {
+		return Number.parseInt(value.substring(8, 16), 16) & MAX_SEQ;
+	}
+	export function getTimestamp(value: Snowflake) {
+		const n = toBigInt(value) >> 22n;
+		return Number(n + BigInt(EPOCH));
+	}
+	export function getDate(value: Snowflake) {
+		return new Date(getTimestamp(value));
+	}
+}
+
+export { Snowflake };