From 7e8352ed2ad1992acf7a8424e0db04edbe2ff26b Mon Sep 17 00:00:00 2001
From: ztimson <zaktimson@gmail.com>
Date: Sat, 18 Oct 2025 16:34:07 -0400
Subject: [PATCH] Added console wrapper

---
 package.json  |  2 +-
 src/logger.ts |  2 ++
 src/misc.ts   | 29 +++++++++++++++++++++++++++++
 src/time.ts   | 44 ++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 4ff7ef3..5b93928 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@ztimson/utils",
-	"version": "0.27.5",
+	"version": "0.27.6",
 	"description": "Utility library",
 	"author": "Zak Timson",
 	"license": "MIT",
diff --git a/src/logger.ts b/src/logger.ts
index 84951a1..c3075d4 100644
--- a/src/logger.ts
+++ b/src/logger.ts
@@ -42,6 +42,8 @@ export const CliBackground = {
 	GREY: "\x1b[100m",
 }
 
+export type LogLevels = 'debug' | 'log' | 'info' | 'warn' | 'error';
+
 export enum LOG_LEVEL {
 	ERROR = 0,
 	WARN = 1,
diff --git a/src/misc.ts b/src/misc.ts
index f1da0ab..85e43de 100644
--- a/src/misc.ts
+++ b/src/misc.ts
@@ -1,3 +1,4 @@
+import {LogLevels} from './logger.ts';
 import {PathEvent} from './path-events.ts';
 import {md5} from './string';
 
@@ -14,6 +15,34 @@ export function compareVersions(target: string, vs: string): -1 | 0 | 1 {
 		(tMajor < vMajor || tMinor < vMinor || tPatch < vPatch) ? -1 : 0;
 }
 
+/**
+ * Create a console object to intercept logs with optional passthrough
+ * @param {null | {debug: Function, log: Function, info: Function, warn: Function, error: Function}} out Passthrough logs, null to silence
+ * @param {{[K in LogLevels]?: LogLevels | "none"}} map Map log levels: {log: 'debug', warn: 'error'} = Suppress debug logs, elevate warnings
+ * @returns {{debug: Function, log: Function, info: Function, warn: Function, error: Function, stderr: string[], stdout: string[]}}
+ */
+export function consoleInterceptor(
+	out: null | {debug: Function, log: Function, info: Function, warn: Function, error: Function} = console,
+	map?: {[K in LogLevels]?: LogLevels | 'none'}
+): {debug: Function, log: Function, info: Function, warn: Function, error: Function, stderr: string[], stdout: string[]} {
+	const stderr: any[] = [], stdout: any[] = [];
+	const cWrapper = (type: 'debug' | 'log' | 'info' | 'warn' | 'error') => ((...args: any[]) => {
+		if(out) out[type](...args);
+		if(type == 'error') stderr.push(...args);
+		else stdout.push(...args);
+	});
+	return {
+		debug: map?.debug != 'none' ? cWrapper(map?.debug || 'debug') : () => {},
+		log: map?.log != 'none' ? cWrapper(map?.log || 'log') : () => {},
+		info: map?.info != 'none' ? cWrapper(map?.info || 'info') : () => {},
+		warn: map?.warn != 'none' ? cWrapper(map?.warn || 'warn') : () => {},
+		error: map?.error != 'none' ? cWrapper(map?.error || 'error') : () => {},
+		stderr,
+		stdout,
+	}
+}
+
+
 /**
  * Escape any regex special characters to avoid misinterpretation during search
  * @param {string} value String which should be escaped
diff --git a/src/time.ts b/src/time.ts
index 08f1987..c07b3c5 100644
--- a/src/time.ts
+++ b/src/time.ts
@@ -34,6 +34,50 @@ export function dayOfYear(date: Date): number {
 /**
  * Format date
  *
+ * Year:
+ * - YYYY = 2025 (4-digit year)
+ * - YY = 25 (2-digit year)
+ *
+ * Month:
+ * - MMMM = January (full month name)
+ * - MMM = Jan (abbreviated month name)
+ * - MM = 01 (zero-padded month number)
+ * - M = 1 (month number)
+ *
+ * Day:
+ * - DDD = 123 (day of year)
+ * - DD = 01 (zero-padded day)
+ * - Do = 1st (day with ordinal suffix)
+ * - D = 1 (day number)
+ * - dddd = Monday (full day name)
+ * - ddd = Mon (abbreviated day name)
+ *
+ * Hour:
+ * - HH = 13 (24-hour format, zero-padded)
+ * - H = 13 (24-hour format)
+ * - hh = 01 (12-hour format, zero-padded)
+ * - h = 1 (12-hour format)
+ *
+ * Minute:
+ * - mm = 05 (zero-padded minutes)
+ * - m = 5 (minutes)
+ *
+ * Second:
+ * - ss = 09 (zero-padded seconds)
+ * - s = 9 (seconds)
+ *
+ * Millisecond:
+ * - SSS = 123 (3-digit milliseconds)
+ *
+ * AM/PM:
+ * - A = AM/PM (uppercase)
+ * - a = am/pm (lowercase)
+ *
+ * Timezone:
+ * - ZZ = +0500 (timezone offset without colon)
+ * - Z = +05:00 (timezone offset with colon)
+ * - z = EST (timezone abbreviation)
+ *
  * @param {string} format How date string will be formatted, default: `YYYY-MM-DD H:mm A`
  * @param {Date | number | string} date Date or timestamp, defaults to now
  * @param tz Set timezone offset