@oh-my-pi/pi-utils 12.17.2 → 12.18.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "12.17.2",
+	"version": "12.18.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Bölük",

package/src/logger.ts

@@ -5,6 +5,7 @@
  * Each log entry includes process.pid for traceability.
  */
 import * as fs from "node:fs";
+import { RingBuffer } from "@oh-my-pi/pi-utils/ring";
 import winston from "winston";
 import DailyRotateFile from "winston-daily-rotate-file";
 import { getLogsDir } from "./dirs";
@@ -57,13 +58,6 @@ const winstonLogger = winston.createLogger({
 	exitOnError: false,
 });
 
-/** Logger type exposed to plugins and internal code */
-export interface Logger {
-	error(message: string, context?: Record<string, unknown>): void;
-	warn(message: string, context?: Record<string, unknown>): void;
-	debug(message: string, context?: Record<string, unknown>): void;
-}
-
 /**
  * Centralized logger for omp.
  *
@@ -79,6 +73,19 @@ export interface Logger {
  * logger.debug("LSP fallback triggered", { reason });
  * ```
  */
+export interface Logger {
+	error(message: string, context?: Record<string, unknown>): void;
+	warn(message: string, context?: Record<string, unknown>): void;
+	debug(message: string, context?: Record<string, unknown>): void;
+	time<T>(op: string, fn: () => T): T;
+	timeAsync<T>(op: string, fn: () => PromiseLike<T>): Promise<T>;
+}
+
+/**
+ * Log an error message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
 export function error(message: string, context?: Record<string, unknown>): void {
 	try {
 		winstonLogger.error(message, context);
@@ -87,6 +94,11 @@ export function error(message: string, context?: Record<string, unknown>): void
 	}
 }
 
+/**
+ * Log a warning message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
 export function warn(message: string, context?: Record<string, unknown>): void {
 	try {
 		winstonLogger.warn(message, context);
@@ -95,6 +107,11 @@ export function warn(message: string, context?: Record<string, unknown>): void {
 	}
 }
 
+/**
+ * Log a debug message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
 export function debug(message: string, context?: Record<string, unknown>): void {
 	try {
 		winstonLogger.debug(message, context);
@@ -102,3 +119,87 @@ export function debug(message: string, context?: Record<string, unknown>): void
 		// Silently ignore logging failures
 	}
 }
+
+const LOGGED_TIMING_THRESHOLD_MS = 5;
+
+const longOpBuffer = new RingBuffer<[op: string, duration: number]>(1000);
+let longOpRecord = false;
+
+function logTiming(op: string, duration: number): void {
+	if (duration > LOGGED_TIMING_THRESHOLD_MS) {
+		warn(`${op} took ${duration}ms`, { duration, op });
+		if (longOpRecord) {
+			longOpBuffer.push([op, duration]);
+		}
+	} else {
+		debug(`${op} took ${duration}ms`, { duration, op });
+	}
+}
+
+/**
+ * Print all collected long operation timings to stderr.
+ * To be called at the end of a startup or timing window.
+ */
+export function printTimings(): void {
+	// Use stderr for timings output, do not use logger (see AGENTS.md).
+	console.error("\n--- Startup Timings ---");
+	let totalDuration = 0;
+	for (const [op, duration] of longOpBuffer) {
+		console.error(`  ${op}: ${duration}ms`);
+		totalDuration += duration;
+	}
+	console.error(`  TOTAL: ${totalDuration}ms`);
+	console.error("------------------------\n");
+}
+
+/**
+ * Begin recording long operation timings.
+ * Typically called at the beginning of startup.
+ */
+export function startTiming(): void {
+	longOpBuffer.clear();
+	longOpRecord = true;
+}
+
+/**
+ * End timing window and print all timings.
+ * Disables further buffering until next startTiming().
+ */
+export function endTiming(): void {
+	longOpBuffer.clear();
+	longOpRecord = false;
+}
+
+/**
+ * Time a synchronous operation and log the duration.
+ * @param op - The operation name.
+ * @param fn - The function to time.
+ * @returns The result of the function.
+ */
+export function time<T, A extends unknown[]>(op: string, fn: (...args: A) => T, ...args: A): T {
+	const start = performance.now();
+	try {
+		return fn(...args);
+	} finally {
+		logTiming(op, performance.now() - start);
+	}
+}
+
+/**
+ * Time an asynchronous operation and log the duration.
+ * @param op - The operation name.
+ * @param fn - The function to time.
+ * @returns The result of the function.
+ */
+export async function timeAsync<R, A extends unknown[]>(
+	op: string,
+	fn: (...args: A) => R,
+	...args: A
+): Promise<Awaited<R>> {
+	const start = performance.now();
+	try {
+		return await fn(...args);
+	} finally {
+		logTiming(op, performance.now() - start);
+	}
+}

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[];
+	}
+}