Merge tag '0.7.1'

LogTape 0.7.1

CHANGES.md

@@ -9,6 +9,16 @@ Version 0.8.0
 To be released.
 
 
+Version 0.7.1
+-------------
+
+Released on October 30, 2024.
+
+ -  The `withContext()` function no more throws an error
+    even if no `contextLocalStorage` is configured.  Instead,  it will log
+    a warning message to the `["logtape", "meta"]` logger.
+
+
 Version 0.7.0
 -------------
 

docs/manual/contexts.md

@@ -55,8 +55,8 @@ across multiple log messages made by different loggers in different modules.
 > [!CAUTION]
 > In order to use implicit context, your JavaScript runtime must support
 > context-local states (like Node.js's [`node:async_hooks`] module).  If your
-> JavaScript runtime doesn't support context-local states, LogTape will throw
-> an error when you try to use implicit contexts.
+> JavaScript runtime doesn't support context-local states, LogTape will silently
+> ignore implicit contexts and log messages will not have implicit contexts.
 >
 > As of October 2024, Node.js, Deno, and Bun support implicit contexts.
 > Web browsers don't support implicit contexts yet.

logtape/context.test.ts

@@ -1,5 +1,4 @@
 import { assertEquals } from "@std/assert/assert-equals";
-import { assertThrows } from "@std/assert/assert-throws";
 import { delay } from "@std/async/delay";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { configure, reset } from "./config.ts";
@@ -131,21 +130,57 @@ Deno.test("withContext()", async (t) => {
     await reset();
   });
 
+  const metaBuffer: LogRecord[] = [];
+
   await t.step("set up", async () => {
     await configure({
       sinks: {
         buffer: buffer.push.bind(buffer),
+        metaBuffer: metaBuffer.push.bind(metaBuffer),
       },
       loggers: [
         { category: "my-app", sinks: ["buffer"], level: "debug" },
-        { category: ["logtape", "meta"], sinks: [], level: "warning" },
+        {
+          category: ["logtape", "meta"],
+          sinks: ["metaBuffer"],
+          level: "warning",
+        },
       ],
       reset: true,
     });
   });
 
   await t.step("without settings", () => {
-    assertThrows(() => withContext({}, () => {}), TypeError);
+    while (buffer.length > 0) buffer.pop();
+    const rv = withContext({ foo: 1 }, () => {
+      getLogger("my-app").debug("hello", { bar: 2 });
+      return 123;
+    });
+    assertEquals(rv, 123);
+    assertEquals(buffer, [
+      {
+        category: ["my-app"],
+        level: "debug",
+        message: ["hello"],
+        rawMessage: "hello",
+        properties: { bar: 2 },
+        timestamp: buffer[0].timestamp,
+      },
+    ]);
+    assertEquals(metaBuffer, [
+      {
+        category: ["logtape", "meta"],
+        level: "warning",
+        message: [
+          "Context-local storage is not configured.  " +
+          "Specify contextLocalStorage option in the configure() function.",
+        ],
+        properties: {},
+        rawMessage: "Context-local storage is not configured.  " +
+          "Specify contextLocalStorage option in the configure() function.",
+        timestamp: metaBuffer[0].timestamp,
+      },
+    ]);
   });
 
   await t.step("tear down", async () => {

logtape/context.ts

@@ -26,6 +26,10 @@ export interface ContextLocalStorage<T> {
 /**
  * Runs a callback with the given implicit context.  Every single log record
  * in the callback will have the given context.
+ *
+ * If no `contextLocalStorage` is configured, this function does nothing and
+ * just returns the return value of the callback.  It also logs a warning to
+ * the `["logtape", "meta"]` logger in this case.
  * @param context The context to inject.
  * @param callback The callback to run.
  * @returns The return value of the callback.
@@ -37,10 +41,11 @@ export function withContext<T>(
 ): T {
   const rootLogger = LoggerImpl.getLogger();
   if (rootLogger.contextLocalStorage == null) {
-    throw new TypeError(
+    LoggerImpl.getLogger(["logtape", "meta"]).warn(
       "Context-local storage is not configured.  " +
         "Specify contextLocalStorage option in the configure() function.",
     );
+    return callback();
   }
   const parentContext = rootLogger.contextLocalStorage.getStore() ?? {};
   return rootLogger.contextLocalStorage.run(