@logtape/logtape 0.12.0-dev.184 → 0.12.0-dev.186

package/logger.ts

@@ -10,6 +10,7 @@ import type { Sink } from "./sink.ts";
  *
  * ```typescript
  * const logger = getLogger("category");
+ * logger.trace `A trace message with ${value}`
  * logger.debug `A debug message with ${value}.`;
  * logger.info `An info message with ${value}.`;
  * logger.warn `A warning message with ${value}.`;
@@ -79,6 +80,94 @@ export interface Logger {
    */
   with(properties: Record<string, unknown>): Logger;
 
+  /**
+   * Log a trace message.  Use this as a template string prefix.
+   *
+   * ```typescript
+   * logger.trace `A trace message with ${value}.`;
+   * ```
+   *
+   * @param message The message template strings array.
+   * @param values The message template values.
+   * @since 0.12.0
+   */
+  trace(message: TemplateStringsArray, ...values: readonly unknown[]): void;
+
+  /**
+   * Log a trace message with properties.
+   *
+   * ```typescript
+   * logger.trace('A trace message with {value}.', { value });
+   * ```
+   *
+   * If the properties are expensive to compute, you can pass a callback that
+   * returns the properties:
+   *
+   * ```typescript
+   * logger.trace(
+   *   'A trace message with {value}.',
+   *   () => ({ value: expensiveComputation() })
+   * );
+   * ```
+   *
+   * @param message The message template.  Placeholders to be replaced with
+   *                `values` are indicated by keys in curly braces (e.g.,
+   *                `{value}`).
+   * @param properties The values to replace placeholders with.  For lazy
+   *                   evaluation, this can be a callback that returns the
+   *                   properties.
+   * @since 0.12.0
+   */
+  trace(
+    message: string,
+    properties?: Record<string, unknown> | (() => Record<string, unknown>),
+  ): void;
+
+  /**
+   * Log a trace values with no message.  This is useful when you
+   * want to log properties without a message, e.g., when you want to log
+   * the context of a request or an operation.
+   *
+   * ```typescript
+   * logger.trace({ method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * Note that this is a shorthand for:
+   *
+   * ```typescript
+   * logger.trace('{*}', { method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * If the properties are expensive to compute, you cannot use this shorthand
+   * and should use the following syntax instead:
+   *
+   * ```typescript
+   * logger.trace('{*}', () => ({
+   *   method: expensiveMethod(),
+   *   url: expensiveUrl(),
+   * }));
+   * ```
+   *
+   * @param properties The values to log.  Note that this does not take
+   *                   a callback.
+   * @since 0.12.0
+   */
+  trace(properties: Record<string, unknown>): void;
+
+  /**
+   * Lazily log a trace message.  Use this when the message values are expensive
+   * to compute and should only be computed if the message is actually logged.
+   *
+   * ```typescript
+   * logger.trace(l => l`A trace message with ${expensiveValue()}.`);
+   * ```
+   *
+   * @param callback A callback that returns the message template prefix.
+   * @throws {TypeError} If no log record was made inside the callback.
+   * @since 0.12.0
+   */
+  trace(callback: LogCallback): void;
+
   /**
    * Log a debug message.  Use this as a template string prefix.
    *
@@ -336,6 +425,95 @@ export interface Logger {
    */
   warn(callback: LogCallback): void;
 
+  /**
+   * Log a warning message.  Use this as a template string prefix.
+   *
+   * ```typescript
+   * logger.warning `A warning message with ${value}.`;
+   * ```
+   *
+   * @param message The message template strings array.
+   * @param values The message template values.
+   * @since 0.12.0
+   */
+  warning(message: TemplateStringsArray, ...values: readonly unknown[]): void;
+
+  /**
+   * Log a warning message with properties.
+   *
+   * ```typescript
+   * logger.warning('A warning message with {value}.', { value });
+   * ```
+   *
+   * If the properties are expensive to compute, you can pass a callback that
+   * returns the properties:
+   *
+   * ```typescript
+   * logger.warning(
+   *   'A warning message with {value}.',
+   *   () => ({ value: expensiveComputation() })
+   * );
+   * ```
+   *
+   * @param message The message template.  Placeholders to be replaced with
+   *                `values` are indicated by keys in curly braces (e.g.,
+   *                `{value}`).
+   * @param properties The values to replace placeholders with.  For lazy
+   *                   evaluation, this can be a callback that returns the
+   *                   properties.
+   * @since 0.12.0
+   */
+  warning(
+    message: string,
+    properties?: Record<string, unknown> | (() => Record<string, unknown>),
+  ): void;
+
+  /**
+   * Log a warning values with no message.  This is useful when you
+   * want to log properties without a message, e.g., when you want to log
+   * the context of a request or an operation.
+   *
+   * ```typescript
+   * logger.warning({ method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * Note that this is a shorthand for:
+   *
+   * ```typescript
+   * logger.warning('{*}', { method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * If the properties are expensive to compute, you cannot use this shorthand
+   * and should use the following syntax instead:
+   *
+   * ```typescript
+   * logger.warning('{*}', () => ({
+   *   method: expensiveMethod(),
+   *   url: expensiveUrl(),
+   * }));
+   * ```
+   *
+   * @param properties The values to log.  Note that this does not take
+   *                   a callback.
+   * @since 0.12.0
+   */
+  warning(properties: Record<string, unknown>): void;
+
+  /**
+   * Lazily log a warning message.  Use this when the message values are
+   * expensive to compute and should only be computed if the message is actually
+   * logged.
+   *
+   * ```typescript
+   * logger.warning(l => l`A warning message with ${expensiveValue()}.`);
+   * ```
+   *
+   * @param callback A callback that returns the message template prefix.
+   * @throws {TypeError} If no log record was made inside the callback.
+   * @since 0.12.0
+   */
+  warning(callback: LogCallback): void;
+
   /**
    * Log an error message.  Use this as a template string prefix.
    *
@@ -568,7 +746,7 @@ export class LoggerImpl implements Logger {
   readonly sinks: Sink[];
   parentSinks: "inherit" | "override" = "inherit";
   readonly filters: Filter[];
-  lowestLevel: LogLevel | null = "debug";
+  lowestLevel: LogLevel | null = "trace";
   contextLocalStorage?: ContextLocalStorage<Record<string, unknown>>;
 
   static getLogger(category: string | readonly string[] = []): LoggerImpl {
@@ -626,7 +804,7 @@ export class LoggerImpl implements Logger {
     while (this.sinks.length > 0) this.sinks.shift();
     this.parentSinks = "inherit";
     while (this.filters.length > 0) this.filters.shift();
-    this.lowestLevel = "debug";
+    this.lowestLevel = "trace";
   }
 
   /**
@@ -783,6 +961,25 @@ export class LoggerImpl implements Logger {
     });
   }
 
+  trace(
+    message:
+      | TemplateStringsArray
+      | string
+      | LogCallback
+      | Record<string, unknown>,
+    ...values: unknown[]
+  ): void {
+    if (typeof message === "string") {
+      this.log("trace", message, (values[0] ?? {}) as Record<string, unknown>);
+    } else if (typeof message === "function") {
+      this.logLazily("trace", message);
+    } else if (!Array.isArray(message)) {
+      this.log("trace", "{*}", message as Record<string, unknown>);
+    } else {
+      this.logTemplate("trace", message as TemplateStringsArray, values);
+    }
+  }
+
   debug(
     message:
       | TemplateStringsArray
@@ -844,6 +1041,17 @@ export class LoggerImpl implements Logger {
     }
   }
 
+  warning(
+    message:
+      | TemplateStringsArray
+      | string
+      | LogCallback
+      | Record<string, unknown>,
+    ...values: unknown[]
+  ): void {
+    this.warn(message, ...values);
+  }
+
   error(
     message:
       | TemplateStringsArray
@@ -946,6 +1154,25 @@ export class LoggerCtx implements Logger {
     this.logger.logTemplate(level, messageTemplate, values, this.properties);
   }
 
+  trace(
+    message:
+      | TemplateStringsArray
+      | string
+      | LogCallback
+      | Record<string, unknown>,
+    ...values: unknown[]
+  ): void {
+    if (typeof message === "string") {
+      this.log("trace", message, (values[0] ?? {}) as Record<string, unknown>);
+    } else if (typeof message === "function") {
+      this.logLazily("trace", message);
+    } else if (!Array.isArray(message)) {
+      this.log("trace", "{*}", message as Record<string, unknown>);
+    } else {
+      this.logTemplate("trace", message as TemplateStringsArray, values);
+    }
+  }
+
   debug(
     message:
       | TemplateStringsArray
@@ -1007,6 +1234,17 @@ export class LoggerCtx implements Logger {
     }
   }
 
+  warning(
+    message:
+      | TemplateStringsArray
+      | string
+      | LogCallback
+      | Record<string, unknown>,
+    ...values: unknown[]
+  ): void {
+    this.warn(message, ...values);
+  }
+
   error(
     message:
       | TemplateStringsArray

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/logtape",
-  "version": "0.12.0-dev.184+ca9e936b",
+  "version": "0.12.0-dev.186+8c242544",
   "description": "Simple logging library with zero dependencies for Deno/Node.js/Bun/browsers",
   "keywords": [
     "logging",

package/sink.test.ts

@@ -2,7 +2,7 @@ import { suite } from "@hongminhee/suite";
 import { assertEquals } from "@std/assert/equals";
 import { assertThrows } from "@std/assert/throws";
 import makeConsoleMock from "consolemock";
-import { debug, error, fatal, info, warning } from "./fixtures.ts";
+import { debug, error, fatal, info, trace, warning } from "./fixtures.ts";
 import { defaultTextFormatter } from "./formatter.ts";
 import type { LogLevel } from "./level.ts";
 import type { LogRecord } from "./record.ts";
@@ -13,6 +13,7 @@ const test = suite(import.meta);
 test("withFilter()", () => {
   const buffer: LogRecord[] = [];
   const sink = withFilter(buffer.push.bind(buffer), "warning");
+  sink(trace);
   sink(debug);
   sink(info);
   sink(warning);
@@ -36,6 +37,7 @@ test("getStreamSink()", async () => {
       },
     }),
   );
+  sink(trace);
   sink(debug);
   sink(info);
   sink(warning);
@@ -45,6 +47,7 @@ test("getStreamSink()", async () => {
   assertEquals(
     buffer,
     `\
+2023-11-14 22:13:20.000 +00:00 [TRC] my-app·junk: Hello, 123 & 456!
 2023-11-14 22:13:20.000 +00:00 [DBG] my-app·junk: Hello, 123 & 456!
 2023-11-14 22:13:20.000 +00:00 [INF] my-app·junk: Hello, 123 & 456!
 2023-11-14 22:13:20.000 +00:00 [WRN] my-app·junk: Hello, 123 & 456!
@@ -58,12 +61,25 @@ test("getConsoleSink()", () => {
   // @ts-ignore: consolemock is not typed
   const mock: ConsoleMock = makeConsoleMock();
   const sink = getConsoleSink({ console: mock });
+  sink(trace);
   sink(debug);
   sink(info);
   sink(warning);
   sink(error);
   sink(fatal);
   assertEquals(mock.history(), [
+    {
+      DEBUG: [
+        "%c22:13:20.000 %cTRC%c %cmy-app·junk %cHello, %o & %o!",
+        "color: gray;",
+        "background-color: gray; color: white;",
+        "background-color: default;",
+        "color: gray;",
+        "color: default;",
+        123,
+        456,
+      ],
+    },
     {
       DEBUG: [
         "%c22:13:20.000 %cDBG%c %cmy-app·junk %cHello, %o & %o!",
@@ -138,12 +154,18 @@ test("getConsoleSink()", () => {
     console: mock2,
     formatter: defaultTextFormatter,
   });
+  sink2(trace);
   sink2(debug);
   sink2(info);
   sink2(warning);
   sink2(error);
   sink2(fatal);
   assertEquals(mock2.history(), [
+    {
+      DEBUG: [
+        "2023-11-14 22:13:20.000 +00:00 [TRC] my-app·junk: Hello, 123 & 456!",
+      ],
+    },
     {
       DEBUG: [
         "2023-11-14 22:13:20.000 +00:00 [DBG] my-app·junk: Hello, 123 & 456!",
@@ -176,6 +198,7 @@ test("getConsoleSink()", () => {
   const sink3 = getConsoleSink({
     console: mock3,
     levelMap: {
+      trace: "log",
       debug: "log",
       info: "log",
       warning: "log",
@@ -184,12 +207,18 @@ test("getConsoleSink()", () => {
     },
     formatter: defaultTextFormatter,
   });
+  sink3(trace);
   sink3(debug);
   sink3(info);
   sink3(warning);
   sink3(error);
   sink3(fatal);
   assertEquals(mock3.history(), [
+    {
+      LOG: [
+        "2023-11-14 22:13:20.000 +00:00 [TRC] my-app·junk: Hello, 123 & 456!",
+      ],
+    },
     {
       LOG: [
         "2023-11-14 22:13:20.000 +00:00 [DBG] my-app·junk: Hello, 123 & 456!",

package/sink.ts

@@ -117,6 +117,7 @@ export interface ConsoleSinkOptions {
    *
    * ```typescript
    * {
+   *   trace: "trace",
    *   debug: "debug",
    *   info: "info",
    *   warning: "warn",
@@ -143,6 +144,7 @@ export interface ConsoleSinkOptions {
 export function getConsoleSink(options: ConsoleSinkOptions = {}): Sink {
   const formatter = options.formatter ?? defaultConsoleFormatter;
   const levelMap: Record<LogLevel, ConsoleMethod> = {
+    trace: "debug",
     debug: "debug",
     info: "info",
     warning: "warn",