@adriangalilea/utils 2.27.0 → 2.28.0

package/README.md

@@ -123,6 +123,54 @@ money(100, 'EUR')   // "€100.00"
 usdIntlOptions(0.43387) // { style: 'currency', currency: 'USD', minimumFractionDigits: 3, ... }
 ```
 
+### ANSI primitives (`ansi`)
+
+Raw escape codes, ALWAYS ON — the vocabulary under the TTY-aware layers. The
+logger and `cli` palettes decide *whether* to color (TTY, `NO_COLOR`,
+`FORCE_COLOR`); this module is for output whose consumer renders ANSI
+regardless of what stdout is: Claude Code status lines, tmux status strings,
+files a terminal will cat. 256-color first (`fg`/`bg` — stable across
+terminals and multiplexers); `rgb` for known-truecolor consumers. Out-of-range
+indices panic.
+
+```typescript
+import { fg, bg, rgb, BOLD, RESET, stripAnsi, ANSI_RE } from '@adriangalilea/utils/ansi'
+
+`${BOLD}${fg(171)}Fable 5${RESET}`   // bold bright violet
+fg(196)                              // red foreground
+bg(238)                              // dark gray background
+rgb(173, 127, 168)                   // 24-bit, when the consumer renders it
+stripAnsi(styled)                    // the string minus its escapes
+```
+
+`cli`'s ANSI-aware `width()` / `clip()` measure strings styled with these
+(they share `ANSI_RE`).
+
+### Time (`time`)
+
+Humanized time — three questions, three functions: how long is a duration
+(`span`), how long ago was an instant (`ago`, raw-duration twin `since`), how
+long until an instant (`until`). `ago` degrades by distance instead of
+stacking units: fresh instants stay relative, older ones snap to the clock the
+reader would check. Accepts `Date | ISO string | epoch ms | null | undefined`
+(null renders `"—"`); epoch numbers are milliseconds only, by design — a
+seconds heuristic would silently shift dates near the boundary.
+
+```typescript
+import { span, since, ago, until } from '@adriangalilea/utils/time'
+
+span(6_000_000)                    // "1h 40m"  (also "45s", "47m", "2d 3h")
+since(sessionStart)                // "47m" — elapsed, no "ago"
+ago(twoMinutesAgo)                 // "2m ago"  ("now" under a minute)
+ago(fiveHoursAgo)                  // "5h 12m ago"  (relative up to 6h)
+ago(thisMorning)                   // "10:30"       (clock time, today)
+ago(lastNight)                     // "yst 22:15"
+ago(fourDaysAgo)                   // "Mon 09:00"   (within a week)
+ago(lastMonth)                     // "07/28"
+until(weeklyReset)                 // "in 3d 13h"   ("now" if passed)
+ago(null)                          // "—" (every function)
+```
+
 ### URL (`url`)
 
 URLs, from user-typed text to cache identity. The whole funnel — *is there a

package/dist/cli/text.d.ts

@@ -4,7 +4,8 @@
  * (`cli/index` — table/kv/tree) and the live layer (`cli/live` — pinned
  * region/spinner) build on these; keeping them here avoids an import cycle.
  */
-export declare const ANSI_RE: RegExp;
+import { ANSI_RE } from "../universal/ansi.js";
+export { ANSI_RE };
 /** Visible width of a string — ANSI escapes stripped, counted by grapheme cluster. */
 export declare const width: (s: string) => number;
 /**

package/dist/cli/text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/cli/text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,eAAO,MAAM,OAAO,QAAoB,CAAC;AAazC,sFAAsF;AACtF,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,KAAG,MACoB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAwBjD;AAED,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MACL,CAAC;AAC3C,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MACP,CAAC;AAE3C,gFAAgF;AAChF,eAAO,MAAM,EAAE;cACJ,MAAM;gBACJ,MAAM;eACP,MAAM;YACT,MAAM;cACJ,MAAM;aACP,MAAM;IACf,+CAA+C;aACtC,MAAM;CACf,CAAC"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/cli/text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,CAAC;AAanB,sFAAsF;AACtF,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,KAAG,MACoB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAwBjD;AAED,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MACL,CAAC;AAC3C,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MACP,CAAC;AAE3C,gFAAgF;AAChF,eAAO,MAAM,EAAE;cACJ,MAAM;gBACJ,MAAM;eACP,MAAM;YACT,MAAM;cACJ,MAAM;aACP,MAAM;IACf,+CAA+C;aACtC,MAAM;CACf,CAAC"}

package/dist/cli/text.js

@@ -4,9 +4,9 @@
  * (`cli/index` — table/kv/tree) and the live layer (`cli/live` — pinned
  * region/spinner) build on these; keeping them here avoids an import cycle.
  */
+import { ANSI_RE } from "../universal/ansi.js";
 import { bold, cyan, dim, gray, green, red, yellow } from "../universal/log.js";
-// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escapes is the point
-export const ANSI_RE = /\x1b\[[0-9;]*m/g;
+export { ANSI_RE };
 // biome-ignore lint/suspicious/noControlCharactersInRegex: split on ANSI escapes, keeping them
 const ANSI_SPLIT_RE = /(\x1b\[[0-9;]*m)/;
 // Grapheme clusters, not code points: what the terminal renders as ONE symbol

package/dist/cli/text.js.map

@@ -1 +1 @@
-{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/cli/text.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/cli/text.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -13,8 +13,10 @@ export * from "./platform/xdg.js";
 export type { RuntimeCapabilities } from "./runtime.js";
 export { ProcessExitError, runtime } from "./runtime.js";
 export * from "./say/index.js";
+export * from "./universal/ansi.js";
 export * from "./universal/currency/index.js";
 export * from "./universal/format.js";
 export * from "./universal/log.js";
+export * from "./universal/time.js";
 export * from "./universal/url/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEzD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AAEtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEzD,cAAc,gBAAgB,CAAC;AAE/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -17,9 +17,11 @@ export * from "./platform/xdg.js";
 export { ProcessExitError, runtime } from "./runtime.js";
 // Polyglot strings — TS-enforced multi-language values
 export * from "./say/index.js";
+// Universal utilities - work everywhere
+export * from "./universal/ansi.js";
 export * from "./universal/currency/index.js";
 export * from "./universal/format.js";
-// Universal utilities - work everywhere
 export * from "./universal/log.js";
+export * from "./universal/time.js";
 export * from "./universal/url/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,yDAAyD;AACzD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,8BAA8B;AAC9B,mEAAmE;AACnE,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAElC,8CAA8C;AAC9C,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACzD,uDAAuD;AACvD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,wCAAwC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,yDAAyD;AACzD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,8BAA8B;AAC9B,mEAAmE;AACnE,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAElC,8CAA8C;AAC9C,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACzD,uDAAuD;AACvD,cAAc,gBAAgB,CAAC;AAC/B,wCAAwC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}

package/dist/universal/ansi.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Raw ANSI escape primitives — ALWAYS ON, no TTY detection, no env checks.
+ * The vocabulary, not the policy: ./log and ../cli decide WHETHER to color
+ * (TTY, NO_COLOR, FORCE_COLOR) and build semantics on top; this module is for
+ * output whose consumer renders ANSI regardless of what stdout is — Claude
+ * Code status lines, tmux status strings, files a terminal will cat. A
+ * TTY-gated palette emits nothing through those pipes, which is exactly wrong.
+ *
+ * 256-color escapes (`fg`/`bg`) over 24-bit as the house default: the xterm
+ * cube is stable across every terminal/multiplexer, while 24-bit gets
+ * quantized or dropped by tmux/screen configs. `rgb` exists for when the
+ * consumer is known to render truecolor.
+ */
+export declare const RESET = "\u001B[0m";
+export declare const BOLD = "\u001B[1m";
+export declare const DIM = "\u001B[2m";
+export declare const ITALIC = "\u001B[3m";
+export declare const UNDERLINE = "\u001B[4m";
+/** Foreground, xterm-256 palette index. */
+export declare function fg(n: number): string;
+/** Background, xterm-256 palette index. */
+export declare function bg(n: number): string;
+/** Foreground, 24-bit — only when the consumer is known to render truecolor. */
+export declare function rgb(r: number, g: number, b: number): string;
+export declare const ANSI_RE: RegExp;
+/** The string minus its ANSI style escapes. */
+export declare const stripAnsi: (s: string) => string;
+//# sourceMappingURL=ansi.d.ts.map

package/dist/universal/ansi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi.d.ts","sourceRoot":"","sources":["../../src/universal/ansi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,eAAO,MAAM,KAAK,cAAY,CAAC;AAC/B,eAAO,MAAM,IAAI,cAAY,CAAC;AAC9B,eAAO,MAAM,GAAG,cAAY,CAAC;AAC7B,eAAO,MAAM,MAAM,cAAY,CAAC;AAChC,eAAO,MAAM,SAAS,cAAY,CAAC;AAEnC,2CAA2C;AAC3C,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpC;AAED,2CAA2C;AAC3C,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpC;AAED,gFAAgF;AAChF,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAS3D;AAGD,eAAO,MAAM,OAAO,QAAoB,CAAC;AAEzC,+CAA+C;AAC/C,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAgC,CAAC"}

package/dist/universal/ansi.js

@@ -0,0 +1,39 @@
+/**
+ * Raw ANSI escape primitives — ALWAYS ON, no TTY detection, no env checks.
+ * The vocabulary, not the policy: ./log and ../cli decide WHETHER to color
+ * (TTY, NO_COLOR, FORCE_COLOR) and build semantics on top; this module is for
+ * output whose consumer renders ANSI regardless of what stdout is — Claude
+ * Code status lines, tmux status strings, files a terminal will cat. A
+ * TTY-gated palette emits nothing through those pipes, which is exactly wrong.
+ *
+ * 256-color escapes (`fg`/`bg`) over 24-bit as the house default: the xterm
+ * cube is stable across every terminal/multiplexer, while 24-bit gets
+ * quantized or dropped by tmux/screen configs. `rgb` exists for when the
+ * consumer is known to render truecolor.
+ */
+import { assert } from "../offensive.js";
+export const RESET = "\x1b[0m";
+export const BOLD = "\x1b[1m";
+export const DIM = "\x1b[2m";
+export const ITALIC = "\x1b[3m";
+export const UNDERLINE = "\x1b[4m";
+/** Foreground, xterm-256 palette index. */
+export function fg(n) {
+    assert(Number.isInteger(n) && n >= 0 && n <= 255, "xterm-256 index:", n);
+    return `\x1b[38;5;${n}m`;
+}
+/** Background, xterm-256 palette index. */
+export function bg(n) {
+    assert(Number.isInteger(n) && n >= 0 && n <= 255, "xterm-256 index:", n);
+    return `\x1b[48;5;${n}m`;
+}
+/** Foreground, 24-bit — only when the consumer is known to render truecolor. */
+export function rgb(r, g, b) {
+    assert([r, g, b].every((v) => Number.isInteger(v) && v >= 0 && v <= 255), "rgb components:", r, g, b);
+    return `\x1b[38;2;${r};${g};${b}m`;
+}
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escapes is the point
+export const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** The string minus its ANSI style escapes. */
+export const stripAnsi = (s) => s.replace(ANSI_RE, "");
+//# sourceMappingURL=ansi.js.map

package/dist/universal/ansi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi.js","sourceRoot":"","sources":["../../src/universal/ansi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,CAAC,MAAM,KAAK,GAAG,SAAS,CAAC;AAC/B,MAAM,CAAC,MAAM,IAAI,GAAG,SAAS,CAAC;AAC9B,MAAM,CAAC,MAAM,GAAG,GAAG,SAAS,CAAC;AAC7B,MAAM,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC;AAChC,MAAM,CAAC,MAAM,SAAS,GAAG,SAAS,CAAC;AAEnC,2CAA2C;AAC3C,MAAM,UAAU,EAAE,CAAC,CAAS;IAC3B,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC;IACzE,OAAO,aAAa,CAAC,GAAG,CAAC;AAC1B,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,EAAE,CAAC,CAAS;IAC3B,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC;IACzE,OAAO,aAAa,CAAC,GAAG,CAAC;AAC1B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS;IAClD,MAAM,CACL,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,EACjE,iBAAiB,EACjB,CAAC,EACD,CAAC,EACD,CAAC,CACD,CAAC;IACF,OAAO,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACpC,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,MAAM,OAAO,GAAG,iBAAiB,CAAC;AAEzC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC"}

package/dist/universal/time.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Humanized time. Three questions, three functions: how long is this
+ * duration (`span`), how long ago was this instant (`ago` — and its raw-
+ * duration twin `since`), how long until this instant (`until`).
+ *
+ * `ago` degrades by distance instead of stacking units: fresh instants are
+ * relative ("now", "3m ago", "2h 15m ago"), older ones snap to the clock the
+ * reader would check — "10:30" earlier today, "yst 22:15" yesterday,
+ * "Mon 09:00" within a week, "07/28" beyond. Relative wording past a few
+ * hours ("19h ago") makes the reader do calendar math; a clock time doesn't.
+ *
+ * Accepts `Date | ISO string | epoch ms | null | undefined` and renders "—"
+ * for null/undefined, same contract as ./format. Epoch numbers are
+ * MILLISECONDS only — a seconds heuristic would silently misread dates near
+ * the boundary, and a wrong timestamp should scream, not shift by 1000×.
+ * Weekday/date fallbacks are en-pinned like every formatter here.
+ */
+export type Dateish = Date | string | number | null | undefined;
+/** Duration in ms → "45s", "47m", "1h 40m", "2d 3h". Negative clamps to "0s". */
+export declare function span(ms: number): string;
+/** Elapsed since an instant, as a bare duration: "47m", "1h 40m" (no "ago"). */
+export declare function since(d: Dateish, now?: Dateish): string;
+/**
+ * Past instant, humanized: "now" (<1m), "3m ago", "2h 15m ago" (<6h), then
+ * clock time — "10:30" today, "yst 22:15" yesterday, "Mon 09:00" within 7
+ * days, "07/28" beyond. Future inputs render "now".
+ */
+export declare function ago(d: Dateish, now?: Dateish): string;
+/** Future instant, humanized: "now", "in 40m", "in 5h 12m", "in 3d 13h". */
+export declare function until(d: Dateish, now?: Dateish): string;
+//# sourceMappingURL=time.d.ts.map

package/dist/universal/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/universal/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAuBhE,iFAAiF;AACjF,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAOvC;AAED,gFAAgF;AAChF,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,GAAE,OAAoB,GAAG,MAAM,CAKnE;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,GAAE,OAAoB,GAAG,MAAM,CAejE;AAED,4EAA4E;AAC5E,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,GAAE,OAAoB,GAAG,MAAM,CAOnE"}

package/dist/universal/time.js

@@ -0,0 +1,95 @@
+/**
+ * Humanized time. Three questions, three functions: how long is this
+ * duration (`span`), how long ago was this instant (`ago` — and its raw-
+ * duration twin `since`), how long until this instant (`until`).
+ *
+ * `ago` degrades by distance instead of stacking units: fresh instants are
+ * relative ("now", "3m ago", "2h 15m ago"), older ones snap to the clock the
+ * reader would check — "10:30" earlier today, "yst 22:15" yesterday,
+ * "Mon 09:00" within a week, "07/28" beyond. Relative wording past a few
+ * hours ("19h ago") makes the reader do calendar math; a clock time doesn't.
+ *
+ * Accepts `Date | ISO string | epoch ms | null | undefined` and renders "—"
+ * for null/undefined, same contract as ./format. Epoch numbers are
+ * MILLISECONDS only — a seconds heuristic would silently misread dates near
+ * the boundary, and a wrong timestamp should scream, not shift by 1000×.
+ * Weekday/date fallbacks are en-pinned like every formatter here.
+ */
+import { NO_DATA } from "./format.js";
+const MIN = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+const WEEK = 604_800_000;
+const WEEKDAY = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+function toMs(d) {
+    if (d == null)
+        return null;
+    if (d instanceof Date)
+        return d.getTime();
+    const ms = typeof d === "number" ? d : Date.parse(d);
+    return Number.isNaN(ms) ? null : ms;
+}
+const pad = (n) => String(n).padStart(2, "0");
+const clock = (d) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+const sameDay = (a, b) => a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate();
+/** Duration in ms → "45s", "47m", "1h 40m", "2d 3h". Negative clamps to "0s". */
+export function span(ms) {
+    if (ms < 0)
+        ms = 0;
+    if (ms < MIN)
+        return `${Math.floor(ms / 1000)}s`;
+    if (ms < HOUR)
+        return `${Math.floor(ms / MIN)}m`;
+    if (ms < DAY)
+        return `${Math.floor(ms / HOUR)}h ${Math.floor((ms % HOUR) / MIN)}m`;
+    return `${Math.floor(ms / DAY)}d ${Math.floor((ms % DAY) / HOUR)}h`;
+}
+/** Elapsed since an instant, as a bare duration: "47m", "1h 40m" (no "ago"). */
+export function since(d, now = Date.now()) {
+    const ms = toMs(d);
+    const ref = toMs(now);
+    if (ms == null || ref == null)
+        return NO_DATA;
+    return span(ref - ms);
+}
+/**
+ * Past instant, humanized: "now" (<1m), "3m ago", "2h 15m ago" (<6h), then
+ * clock time — "10:30" today, "yst 22:15" yesterday, "Mon 09:00" within 7
+ * days, "07/28" beyond. Future inputs render "now".
+ */
+export function ago(d, now = Date.now()) {
+    const ms = toMs(d);
+    const ref = toMs(now);
+    if (ms == null || ref == null)
+        return NO_DATA;
+    const delta = ref - ms;
+    if (delta < MIN)
+        return "now";
+    if (delta < HOUR)
+        return `${Math.floor(delta / MIN)}m ago`;
+    if (delta < 6 * HOUR)
+        return `${Math.floor(delta / HOUR)}h ${Math.floor((delta % HOUR) / MIN)}m ago`;
+    const date = new Date(ms);
+    const refDate = new Date(ref);
+    if (sameDay(date, refDate))
+        return clock(date);
+    if (sameDay(date, new Date(ref - DAY)))
+        return `yst ${clock(date)}`;
+    if (delta < WEEK)
+        return `${WEEKDAY[date.getDay()]} ${clock(date)}`;
+    return `${pad(date.getMonth() + 1)}/${pad(date.getDate())}`;
+}
+/** Future instant, humanized: "now", "in 40m", "in 5h 12m", "in 3d 13h". */
+export function until(d, now = Date.now()) {
+    const ms = toMs(d);
+    const ref = toMs(now);
+    if (ms == null || ref == null)
+        return NO_DATA;
+    const delta = ms - ref;
+    if (delta < MIN)
+        return "now";
+    return `in ${span(delta)}`;
+}
+//# sourceMappingURL=time.js.map

package/dist/universal/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../../src/universal/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAItC,MAAM,GAAG,GAAG,MAAM,CAAC;AACnB,MAAM,IAAI,GAAG,SAAS,CAAC;AACvB,MAAM,GAAG,GAAG,UAAU,CAAC;AACvB,MAAM,IAAI,GAAG,WAAW,CAAC;AAEzB,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAElE,SAAS,IAAI,CAAC,CAAU;IACvB,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,CAAC,YAAY,IAAI;QAAE,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IAC1C,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACrD,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AACrC,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACtD,MAAM,KAAK,GAAG,CAAC,CAAO,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;AACzE,MAAM,OAAO,GAAG,CAAC,CAAO,EAAE,CAAO,EAAE,EAAE,CACpC,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE;IACnC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,QAAQ,EAAE;IAC7B,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;AAE7B,iFAAiF;AACjF,MAAM,UAAU,IAAI,CAAC,EAAU;IAC9B,IAAI,EAAE,GAAG,CAAC;QAAE,EAAE,GAAG,CAAC,CAAC;IACnB,IAAI,EAAE,GAAG,GAAG;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC;IACjD,IAAI,EAAE,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC;IACjD,IAAI,EAAE,GAAG,GAAG;QACX,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC;IACtE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,GAAG,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;AACrE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,KAAK,CAAC,CAAU,EAAE,MAAe,IAAI,CAAC,GAAG,EAAE;IAC1D,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,EAAE,IAAI,IAAI,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,OAAO,CAAC;IAC9C,OAAO,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,CAAU,EAAE,MAAe,IAAI,CAAC,GAAG,EAAE;IACxD,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,EAAE,IAAI,IAAI,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,OAAO,CAAC;IAC9C,MAAM,KAAK,GAAG,GAAG,GAAG,EAAE,CAAC;IACvB,IAAI,KAAK,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IAC9B,IAAI,KAAK,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC;IAC3D,IAAI,KAAK,GAAG,CAAC,GAAG,IAAI;QACnB,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC;IAChF,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1B,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,OAAO,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;QAAE,OAAO,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;IACpE,IAAI,KAAK,GAAG,IAAI;QAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;IACpE,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,KAAK,CAAC,CAAU,EAAE,MAAe,IAAI,CAAC,GAAG,EAAE;IAC1D,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,EAAE,IAAI,IAAI,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,OAAO,CAAC;IAC9C,MAAM,KAAK,GAAG,EAAE,GAAG,GAAG,CAAC;IACvB,IAAI,KAAK,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IAC9B,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;AAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.27.0",
+	"version": "2.28.0",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -20,10 +20,18 @@
 			"types": "./dist/runtime.d.ts",
 			"default": "./dist/runtime.js"
 		},
+		"./ansi": {
+			"types": "./dist/universal/ansi.d.ts",
+			"default": "./dist/universal/ansi.js"
+		},
 		"./format": {
 			"types": "./dist/universal/format.d.ts",
 			"default": "./dist/universal/format.js"
 		},
+		"./time": {
+			"types": "./dist/universal/time.d.ts",
+			"default": "./dist/universal/time.js"
+		},
 		"./url": {
 			"types": "./dist/universal/url/index.d.ts",
 			"default": "./dist/universal/url/index.js"