@adriangalilea/utils 2.29.0 → 2.31.0

package/dist/universal/log.d.ts

@@ -1,108 +1,113 @@
 /**
- * A Next.js-style logger for TypeScript applications
- * Provides colored output with Unicode symbols for different log levels
+ * Terminal-first logger with two renderings and one automatic decision.
  *
- * Known limitations:
- * - createLogger() is just a prefix wrapper, not a real scoped instance.
- *   No per-scope level control (can't silence 'bor' but keep 'bdns' verbose).
- * - No withTag/child pattern — consumer can't control library log levels.
+ * Two knobs, never confusing: format = how lines render, time = whether
+ * lines carry time. Each defaults sensibly and independently.
  *
- * Candidate replacement: consola (unjs). Same DX goals, solves all the above:
- *   - consola.level = N at runtime
- *   - consola.withTag('bdns') for scoped loggers that inherit global level
- *   - Pretty dev output, JSON in prod, browser support, 0 deps
- *   - https://github.com/unjs/consola
+ * Format — LOG_FORMAT=human|record, or setLogFormat(). Default by TTY
+ *     detection on the sink: a TTY gets human (symbols, color, a line meant
+ *     for eyes), anything else gets record (level words, plain text, a line
+ *     meant for a file read later). Detection happens on the stream actually
+ *     written to (stderr), never a sibling stream.
  *
- * TODO: test consola in dokploy instance before migrating.
+ * Time — LOG_TIME=1|0, or setLogTime(). Default: on in Node record mode,
+ *     off everywhere else (human eyes don't need stamps; browser and Worker
+ *     consoles stamp lines themselves). Record time opens the line with UTC
+ *     RFC3339; human time prefixes a dim local HH:MM:SS (a human knows
+ *     today's date).
+ *
+ * The record line with time on, identical across go-utils and py-utils by
+ * design:
+ *     2026-08-07T12:34:56Z WARN  [scope] message
+ *     UTC RFC3339 seconds precision · level word padded to 5 · scope brackets
+ *     only when scoped · no color, no symbols. Grep WARN, not ⚠.
+ *
+ * Sinks
+ *     Node/Bun/Deno: every level writes to stderr through console.error, so
+ *     stdout stays clean for data and cli/live's console routing keeps log
+ *     lines above an active region.
+ *     Browser: level-mapped console methods (debug/info/warn/error), human.
+ *     Workers: level-mapped console methods, record.
+ *
+ * Levels vs verbs
+ *     Levels filter: silent < error < warn < info < debug < trace. An unknown
+ *     LOG_LEVEL is a misconfiguration and throws Panic.
+ *     Verbs express outcome and are renderings, never levels:
+ *     error ⨯  fail ⨯ (error) · warn ⚠ (warn) · info · success ✓ · wait ○ ·
+ *     ready ▶ · step • (info) · debug ◦ (debug) · trace » (trace).
+ *     In record mode a verb renders as its level word.
+ *
+ * Scopes
+ *     log.scope('api') returns a child whose lines carry [api]; scopes nest
+ *     and join: log.scope('api').scope('auth') → [api auth]. A scoped logger
+ *     resolves its threshold from {SCOPE}_LOG_LEVEL (upper-cased, joined and
+ *     sanitized to A-Z0-9_: API_AUTH_LOG_LEVEL, then API_LOG_LEVEL), falling
+ *     back to setLogLevel(), then LOG_LEVEL, then info — read live, so one
+ *     subsystem can be silenced or opened up without touching code.
+ *
+ * Config is env plus three runtime setters — setLogLevel(), setLogFormat(),
+ *     setLogTime(). No handlers, no formatters, no init. NO_COLOR /
+ *     FORCE_COLOR override color within human mode. Unknown values of any
+ *     knob throw Panic. All internal memory is bounded.
+ *
+ * Siblings: go-utils and py-utils implement the same doctrine in their own
+ * idioms; the record line format is identical by design.
  */
-export declare const bold: (str: string) => string;
-export declare const dim: (str: string) => string;
-export declare const red: (str: string) => string;
-export declare const green: (str: string) => string;
-export declare const yellow: (str: string) => string;
-export declare const blue: (str: string) => string;
-export declare const magenta: (str: string) => string;
-export declare const cyan: (str: string) => string;
-export declare const white: (str: string) => string;
-export declare const gray: (str: string) => string;
-export declare const purple: (str: string) => string;
-export declare const bgRed: (str: string) => string;
-export declare const bgGreen: (str: string) => string;
-export declare const bgYellow: (str: string) => string;
-export declare const bgBlue: (str: string) => string;
-export declare const bgMagenta: (str: string) => string;
-export declare const bgCyan: (str: string) => string;
-export declare const bgWhite: (str: string) => string;
-type LogLevelName = "error" | "warn" | "info" | "trace";
-/** Set the global log level at runtime. Overrides LOG_LEVEL env var. */
-export declare function setLogLevel(level: LogLevelName): void;
-export declare function bootstrap(...messages: string[]): void;
-export declare function wait(...messages: unknown[]): void;
-export declare function error(...messages: unknown[]): void;
-export declare function warn(...messages: unknown[]): void;
-export declare function ready(...messages: unknown[]): void;
-export declare function info(...messages: unknown[]): void;
-export declare function success(...messages: unknown[]): void;
-export declare function event(...messages: unknown[]): void;
-export declare function trace(...messages: unknown[]): void;
-export declare function warnOnce(...messages: unknown[]): void;
-export declare function time(label: string): void;
-export declare function timeEnd(label: string): void;
-export declare function createLogger(prefix: string): {
-    wait: (...messages: unknown[]) => void;
-    error: (...messages: unknown[]) => void;
-    warn: (...messages: unknown[]) => void;
-    ready: (...messages: unknown[]) => void;
-    info: (...messages: unknown[]) => void;
-    success: (...messages: unknown[]) => void;
-    event: (...messages: unknown[]) => void;
-    trace: (...messages: unknown[]) => void;
-    warnOnce: (...messages: unknown[]) => void;
-    time: (label: string) => void;
-    timeEnd: (label: string) => void;
+export type LogFormat = "human" | "record";
+/** Force human or record rendering at runtime. Wins over LOG_FORMAT and auto-detection. */
+export declare function setLogFormat(format: LogFormat): void;
+/** Force time prefixes on or off at runtime. Wins over LOG_TIME and the defaults. */
+export declare function setLogTime(on: boolean): void;
+declare const LEVELS: {
+    readonly silent: 0;
+    readonly error: 1;
+    readonly warn: 2;
+    readonly info: 3;
+    readonly debug: 4;
+    readonly trace: 5;
 };
-declare const log: {
-    wait: typeof wait;
-    error: typeof error;
-    warn: typeof warn;
-    ready: typeof ready;
-    info: typeof info;
-    success: typeof success;
-    event: typeof event;
-    trace: typeof trace;
-    warnOnce: typeof warnOnce;
-    time: typeof time;
-    timeEnd: typeof timeEnd;
-    bootstrap: typeof bootstrap;
-    createLogger: typeof createLogger;
+export type LogLevel = keyof typeof LEVELS;
+/** Set the global log level at runtime. Wins over LOG_LEVEL; per-scope env vars still win over this. */
+export declare function setLogLevel(level: LogLevel): void;
+export interface Logger {
+    error(...messages: unknown[]): void;
+    fail(...messages: unknown[]): void;
+    warn(...messages: unknown[]): void;
+    /** warn() that fires once per distinct message for the process lifetime. */
+    warnOnce(...messages: unknown[]): void;
+    info(...messages: unknown[]): void;
+    success(...messages: unknown[]): void;
+    wait(...messages: unknown[]): void;
+    ready(...messages: unknown[]): void;
+    /** Indented sub-step bullet under a wait/ready line. */
+    step(...messages: unknown[]): void;
+    debug(...messages: unknown[]): void;
+    trace(...messages: unknown[]): void;
+    /** Start a duration measurement; timeEnd() reports it at trace level. */
+    time(label: string): void;
+    timeEnd(label: string): void;
+    /** Child logger: lines carry [name], level reads {NAME}_LOG_LEVEL first. */
+    scope(name: string): Logger;
+}
+export declare const error: (...messages: unknown[]) => void;
+export declare const fail: (...messages: unknown[]) => void;
+export declare const warn: (...messages: unknown[]) => void;
+export declare const warnOnce: (...messages: unknown[]) => void;
+export declare const info: (...messages: unknown[]) => void;
+export declare const success: (...messages: unknown[]) => void;
+export declare const wait: (...messages: unknown[]) => void;
+export declare const ready: (...messages: unknown[]) => void;
+export declare const step: (...messages: unknown[]) => void;
+export declare const debug: (...messages: unknown[]) => void;
+export declare const trace: (...messages: unknown[]) => void;
+export declare const time: (label: string) => void;
+export declare const timeEnd: (label: string) => void;
+export declare const scope: (name: string) => Logger;
+/** The root logger plus its runtime knobs, for namespace-style consumers. */
+export declare const log: Logger & {
     setLogLevel: typeof setLogLevel;
-    colors: {
-        bold: (str: string) => string;
-        dim: (str: string) => string;
-        red: (str: string) => string;
-        green: (str: string) => string;
-        yellow: (str: string) => string;
-        blue: (str: string) => string;
-        magenta: (str: string) => string;
-        cyan: (str: string) => string;
-        white: (str: string) => string;
-        gray: (str: string) => string;
-        purple: (str: string) => string;
-        bgRed: (str: string) => string;
-        bgGreen: (str: string) => string;
-        bgYellow: (str: string) => string;
-        bgBlue: (str: string) => string;
-        bgMagenta: (str: string) => string;
-        bgCyan: (str: string) => string;
-        bgWhite: (str: string) => string;
-    };
+    setLogFormat: typeof setLogFormat;
+    setLogTime: typeof setLogTime;
 };
-export { log };
-export declare function logAppStartup(options: {
-    name: string;
-    version: string;
-    port: number;
-    host?: string;
-    environment?: string;
-}): void;
+export {};
 //# sourceMappingURL=log.d.ts.map

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

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