@oh-my-pi/pi-utils 12.18.3 → 12.19.2

package/package.json

@@ -1,10 +1,10 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "12.18.3",
+	"version": "12.19.2",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://github.com/can1357/oh-my-pi",
-	"author": "Can Bölük",
+	"author": "Can Boluk",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -27,11 +27,11 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"winston": "^3.19.0",
-		"winston-daily-rotate-file": "^5.0.0"
+		"winston": "^3.19",
+		"winston-daily-rotate-file": "^5.0"
 	},
 	"devDependencies": {
-		"@types/bun": "^1.3.9"
+		"@types/bun": "^1.3"
 	},
 	"engines": {
 		"bun": ">=1.3.7"

package/src/async.ts

@@ -0,0 +1,50 @@
+/**
+ * Wrap a promise with a timeout and optional abort signal.
+ * Rejects with the given message if the timeout fires first.
+ * Cleans up all listeners on settlement.
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T> {
+	if (signal?.aborted) {
+		const reason = signal.reason instanceof Error ? signal.reason : new Error("Aborted");
+		return Promise.reject(reason);
+	}
+
+	const { promise: wrapped, resolve, reject } = Promise.withResolvers<T>();
+	let settled = false;
+	const timeoutId = setTimeout(() => {
+		if (settled) return;
+		settled = true;
+		if (signal) signal.removeEventListener("abort", onAbort);
+		reject(new Error(message));
+	}, ms);
+
+	const onAbort = () => {
+		if (settled) return;
+		settled = true;
+		clearTimeout(timeoutId);
+		reject(signal?.reason instanceof Error ? signal.reason : new Error("Aborted"));
+	};
+
+	if (signal) {
+		signal.addEventListener("abort", onAbort, { once: true });
+	}
+
+	promise.then(
+		value => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeoutId);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		},
+		err => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeoutId);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			reject(err);
+		},
+	);
+
+	return wrapped;
+}

package/src/color.ts

@@ -3,10 +3,9 @@
  *
  * @example
  * ```ts
- * import { shiftHue, hexToHsv, hsvToHex } from "@oh-my-pi/pi-utils";
+ * import { hexToHsv, hsvToHex } from "@oh-my-pi/pi-utils";
  *
- * // Shift green toward blue for colorblind accessibility
- * const blue = shiftHue("#4ade80", 90); // ~90° shift
+ * // Work with HSV directly
  *
  * // Or work with HSV directly
  * const hsv = hexToHsv("#4ade80");
@@ -160,16 +159,6 @@ export function hsvToHex(hsv: HSV): string {
 
 /**
  * Shift the hue of a hex color by a given number of degrees.
- *
- * @param hex - Hex color string (#RGB or #RRGGBB)
- * @param degrees - Degrees to shift (positive = toward blue, negative = toward red)
- * @returns New hex color string
- *
- * @example
- * ```ts
- * // Shift green 90° toward blue (for colorblind accessibility)
- * shiftHue("#4ade80", 90) // Returns a cyan/blue color
- * ```
  */
 export function shiftHue(hex: string, degrees: number): string {
 	const hsv = hexToHsv(hex);
@@ -177,7 +166,6 @@ export function shiftHue(hex: string, degrees: number): string {
 	if (hsv.h < 0) hsv.h += 360;
 	return hsvToHex(hsv);
 }
-
 export interface HSVAdjustment {
 	/** Hue shift in degrees (additive) */
 	h?: number;

package/src/format.ts

@@ -0,0 +1,106 @@
+const SEC = 1_000;
+const MIN = 60 * SEC;
+const HOUR = 60 * MIN;
+const DAY = 24 * HOUR;
+
+/**
+ * Format a duration in milliseconds to a short human-readable string.
+ * Examples: "123ms", "1.5s", "30m15s", "2h30m", "3d2h"
+ */
+export function formatDuration(ms: number): string {
+	if (ms < SEC) return `${ms}ms`;
+	if (ms < MIN) return `${(ms / SEC).toFixed(1)}s`;
+	if (ms < HOUR) {
+		const mins = Math.floor(ms / MIN);
+		const secs = Math.floor((ms % MIN) / SEC);
+		return secs > 0 ? `${mins}m${secs}s` : `${mins}m`;
+	}
+	if (ms < DAY) {
+		const hours = Math.floor(ms / HOUR);
+		const mins = Math.floor((ms % HOUR) / MIN);
+		return mins > 0 ? `${hours}h${mins}m` : `${hours}h`;
+	}
+	const days = Math.floor(ms / DAY);
+	const hours = Math.floor((ms % DAY) / HOUR);
+	return hours > 0 ? `${days}d${hours}h` : `${days}d`;
+}
+
+/**
+ * Format a number with K/M/B suffix for compact display.
+ * Uses 1 decimal for small leading digits, rounded otherwise.
+ * Examples: "999", "1.5K", "25K", "1.5M", "25M", "1.5B"
+ */
+export function formatNumber(n: number): string {
+	if (n < 1_000) return n.toString();
+	if (n < 10_000) return `${(n / 1_000).toFixed(1)}K`;
+	if (n < 1_000_000) return `${Math.round(n / 1_000)}K`;
+	if (n < 10_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n < 1_000_000_000) return `${Math.round(n / 1_000_000)}M`;
+	if (n < 10_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B`;
+	return `${Math.round(n / 1_000_000_000)}B`;
+}
+
+/**
+ * Format a byte count to a human-readable string.
+ * Examples: "512B", "1.5KB", "2.3MB", "1.2GB"
+ */
+export function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+}
+
+/**
+ * Truncate a string to maxLen characters, appending an ellipsis if truncated.
+ * For display-width-aware truncation (terminals), use truncateToWidth from @oh-my-pi/pi-tui.
+ */
+export function truncate(str: string, maxLen: number, ellipsis = "…"): string {
+	if (str.length <= maxLen) return str;
+	const sliceLen = Math.max(0, maxLen - ellipsis.length);
+	return `${str.slice(0, sliceLen)}${ellipsis}`;
+}
+
+/**
+ * Format count with pluralized label (e.g., "3 files", "1 error").
+ */
+export function formatCount(label: string, count: number): string {
+	const safeCount = Number.isFinite(count) ? count : 0;
+	return `${safeCount} ${pluralize(label, safeCount)}`;
+}
+
+/**
+ * Format age from seconds to human-readable string.
+ */
+export function formatAge(ageSeconds: number | null | undefined): string {
+	if (!ageSeconds) return "";
+	const mins = Math.floor(ageSeconds / 60);
+	const hours = Math.floor(mins / 60);
+	const days = Math.floor(hours / 24);
+	const weeks = Math.floor(days / 7);
+	const months = Math.floor(days / 30);
+
+	if (months > 0) return `${months}mo ago`;
+	if (weeks > 0) return `${weeks}w ago`;
+	if (days > 0) return `${days}d ago`;
+	if (hours > 0) return `${hours}h ago`;
+	if (mins > 0) return `${mins}m ago`;
+	return "just now";
+}
+
+/**
+ * Pluralize a label based on the count.
+ */
+export function pluralize(label: string, count: number): string {
+	if (count === 1) return label;
+	if (/(?:ch|sh|s|x|z)$/i.test(label)) return `${label}es`;
+	if (/[^aeiou]y$/i.test(label)) return `${label.slice(0, -1)}ies`;
+	return `${label}s`;
+}
+
+/**
+ * Format a ratio as a percentage.
+ */
+export function formatPercent(ratio: number): string {
+	return `${(ratio * 100).toFixed(1)}%`;
+}

package/src/index.ts

@@ -1,6 +1,8 @@
 export * from "./abortable";
+export * from "./async";
 export * from "./color";
 export * from "./env";
+export * from "./format";
 export * from "./fs-error";
 export * from "./glob";
 export * as logger from "./logger";
@@ -12,3 +14,4 @@ export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
 export { Snowflake } from "./snowflake";
 export * from "./stream";
 export * from "./temp";
+export * from "./type-guards";

package/src/procmgr.ts

@@ -50,7 +50,7 @@ function buildSpawnEnv(shell: string): Record<string, string> {
  */
 function getShellArgs(): string[] {
 	const noLogin = $env.PI_BASH_NO_LOGIN || $env.CLAUDE_BASH_NO_LOGIN;
-	return noLogin ? ["-l", "-c"] : ["-l", "-c"];
+	return noLogin ? ["-c"] : ["-l", "-c"];
 }
 
 /**

package/src/stream.ts

@@ -1,9 +1,6 @@
 import { createAbortableStream } from "./abortable";
 
 const LF = 0x0a;
-const CR = 0x0d;
-const decoder = new TextDecoder();
-
 type JsonlChunkResult = {
 	values: unknown[];
 	error: unknown;
@@ -11,107 +8,17 @@ type JsonlChunkResult = {
 	done: boolean;
 };
 
-function hasBunJsonlParseChunk(): boolean {
-	return typeof Bun !== "undefined" && typeof Bun.JSONL !== "undefined" && typeof Bun.JSONL.parseChunk === "function";
-}
-
-function parseJsonLine(lineBytes: Uint8Array): unknown {
-	let end = lineBytes.length;
-	if (end > 0 && lineBytes[end - 1] === CR) {
-		end--;
-	}
-	const text = decoder.decode(lineBytes.subarray(0, end)).trim();
-	if (text.length === 0) return undefined;
-	return JSON.parse(text);
-}
-
-function parseJsonlChunkFallbackBytes(bytes: Uint8Array, beg = 0, end = bytes.length): JsonlChunkResult {
-	const values: unknown[] = [];
-	let lineStart = beg;
-
-	for (let i = beg; i < end; i++) {
-		if (bytes[i] !== LF) continue;
-		const line = bytes.subarray(lineStart, i);
-		try {
-			const parsed = parseJsonLine(line);
-			if (parsed !== undefined) values.push(parsed);
-		} catch (error) {
-			return { values, error, read: lineStart, done: false };
-		}
-		lineStart = i + 1;
-	}
-
-	if (lineStart >= end) {
-		return { values, error: null, read: end, done: true };
-	}
-
-	const tail = bytes.subarray(lineStart, end);
-	const tailText = decoder.decode(tail).trim();
-	if (tailText.length === 0) {
-		return { values, error: null, read: end, done: true };
-	}
-	try {
-		values.push(JSON.parse(tailText));
-		return { values, error: null, read: end, done: true };
-	} catch {
-		// In streaming mode this is usually a partial line/object.
-		return { values, error: null, read: lineStart, done: false };
-	}
-}
-
-function parseJsonlChunkFallbackString(buffer: string): JsonlChunkResult {
-	const values: unknown[] = [];
-	let lineStart = 0;
-
-	for (let i = 0; i < buffer.length; i++) {
-		if (buffer.charCodeAt(i) !== LF) continue;
-		const rawLine = buffer.slice(lineStart, i);
-		const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
-		const trimmed = line.trim();
-		if (trimmed.length > 0) {
-			try {
-				values.push(JSON.parse(trimmed));
-			} catch (error) {
-				return { values, error, read: lineStart, done: false };
-			}
-		}
-		lineStart = i + 1;
-	}
-
-	if (lineStart >= buffer.length) {
-		return { values, error: null, read: buffer.length, done: true };
-	}
-
-	const tail = buffer.slice(lineStart).trim();
-	if (tail.length === 0) {
-		return { values, error: null, read: buffer.length, done: true };
-	}
-	try {
-		values.push(JSON.parse(tail));
-		return { values, error: null, read: buffer.length, done: true };
-	} catch {
-		return { values, error: null, read: lineStart, done: false };
-	}
-}
-
 function parseJsonlChunkCompat(input: Uint8Array, beg?: number, end?: number): JsonlChunkResult;
 function parseJsonlChunkCompat(input: string): JsonlChunkResult;
 function parseJsonlChunkCompat(input: Uint8Array | string, beg?: number, end?: number): JsonlChunkResult {
-	if (hasBunJsonlParseChunk()) {
-		if (typeof input === "string") {
-			const { values, error, read, done } = Bun.JSONL.parseChunk(input);
-			return { values, error, read, done };
-		}
-		const start = beg ?? 0;
-		const stop = end ?? input.length;
-		const { values, error, read, done } = Bun.JSONL.parseChunk(input, start, stop);
-		return { values, error, read, done };
-	}
-
 	if (typeof input === "string") {
-		return parseJsonlChunkFallbackString(input);
+		const { values, error, read, done } = Bun.JSONL.parseChunk(input);
+		return { values, error, read, done };
 	}
-	return parseJsonlChunkFallbackBytes(input, beg, end);
+	const start = beg ?? 0;
+	const stop = end ?? input.length;
+	const { values, error, read, done } = Bun.JSONL.parseChunk(input, start, stop);
+	return { values, error, read, done };
 }
 
 export async function* readLines(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Uint8Array> {

package/src/type-guards.ts

@@ -0,0 +1,11 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+	return isRecord(value) ? value : null;
+}
+
+export function toError(value: unknown): Error {
+	return value instanceof Error ? value : new Error(String(value));
+}