Merge branch '0.5-maintenance'

.github/workflows/main.yaml

@@ -112,10 +112,14 @@ jobs:
         set -ex
         bun install
         if [[ "$GITHUB_REF_TYPE" = "tag" ]]; then
+          bun add -D "@logtape/logtape@$GITHUB_REF_NAME"
+          bun add -D @logtape/otel@latest
           EXTRA_NAV_TEXT=Unstable \
           EXTRA_NAV_LINK="$UNSTABLE_DOCS_URL" \
           bun run build
         else
+          bun add -D @logtape/logtape@dev
+          bun add -D @logtape/otel@dev
           EXTRA_NAV_TEXT=Stable \
           EXTRA_NAV_LINK="$STABLE_DOCS_URL" \
           bun run build

docs/.vitepress/config.mts

@@ -1,6 +1,7 @@
 import { Presets, SingleBar } from "cli-progress";
 import { jsrRef } from "markdown-it-jsr-ref";
 import { defineConfig } from "vitepress";
+import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
 
 const progress = new SingleBar({}, Presets.shades_classic);
 let started = false;
@@ -110,6 +111,21 @@ export default defineConfig({
   },
   head: plausibleScript,
   markdown: {
+    codeTransformers: [
+      transformerTwoslash({
+        twoslashOptions: {
+          compilerOptions: {
+            lib: ["dom", "dom.iterable", "esnext"],
+            types: [
+              "dom",
+              "dom.iterable",
+              "esnext",
+              "@teidesu/deno-types/full",
+            ],
+          },
+        },
+      }),
+    ],
     config(md) {
       md.use(jsrRefPlugin);
     },

docs/.vitepress/theme/index.mts

@@ -1,4 +1,13 @@
-import DefaultTheme from 'vitepress/theme'
+import TwoslashFloatingVue from "@shikijs/vitepress-twoslash/client";
+import type { EnhanceAppContext } from "vitepress";
+import Theme from "vitepress/theme";
+
+import "@shikijs/vitepress-twoslash/style.css";
 import './custom.css'
 
-export default DefaultTheme
+export default {
+  extends: Theme,
+  enhanceApp({ app }: EnhanceAppContext) {
+    app.use(TwoslashFloatingVue);
+  },
+};

docs/manual/categories.md

@@ -14,7 +14,7 @@ the log level of loggers at different levels of the category hierarchy.
 
 Here's an example of setting log levels for different categories:
 
-~~~~ typescript{9-10}
+~~~~ typescript{9-10} twoslash
 import { configure, getConsoleSink } from "@logtape/logtape";
 
 await configure({
@@ -35,15 +35,19 @@ Child loggers
 
 You can get a child logger from a parent logger by calling `~Logger.getChild()`:
 
-~~~~ typescript
+~~~~ typescript twoslash
+import { getLogger } from "@logtape/logtape";
+// ---cut-before---
 const logger = getLogger(["my-app"]);
 const childLogger = logger.getChild("my-module");
 // equivalent: const childLogger = getLogger(["my-app", "my-module"]);
 ~~~~
 
 The `~Logger.getChild()` method can take an array of strings as well:
 
-~~~~ typescript
+~~~~ typescript twoslash
+import { getLogger } from "@logtape/logtape";
+// ---cut-before---
 const logger = getLogger(["my-app"]);
 const childLogger = logger.getChild(["my-module", "foo"]);
 // equivalent: const childLogger = getLogger(["my-app", "my-module", "foo"]);
@@ -75,7 +79,17 @@ to an empty array.
 > if there's an issue with your main sink, you can still receive meta logs about
 > the issue:
 >
-> ~~~~ typescript
+> ~~~~ typescript twoslash
+> // @noErrors: 2307
+> import { type Sink } from "@logtape/logtape";
+> /**
+>  * A hypothetical function to get your main sink.
+>  * @returns The main sink.
+>  */
+> function getYourMainSink(): Sink {
+>   return 0 as unknown as Sink;
+> }
+> // ---cut-before---
 > import { configure, getConsoleSink } from "@logtape/logtape";
 > import { getYourMainSink } from "./your-main-sink.ts";
 >

docs/manual/config.md

@@ -19,7 +19,7 @@ At its core, configuring LogTape involves three main components:
 
 Here's a simple configuration to get you started:
 
-~~~~ typescript
+~~~~ typescript twoslash
 import { configure, getConsoleSink } from "@logtape/logtape";
 
 await configure({
@@ -53,7 +53,8 @@ Crafting your configuration
 [Sinks](./sinks.md) determine where your logs end up. You can have multiple
 sinks for different purposes:
 
-~~~~ typescript
+~~~~ typescript twoslash
+// @noErrors: 2345
 import { configure, getConsoleSink, getFileSink } from "@logtape/logtape";
 
 await configure({
@@ -71,7 +72,10 @@ await configure({
 [Filters](./filters.md) allow you to fine-tune which logs are processed. They
 can be based on log levels, content, or custom logic:
 
-~~~~ typescript
+~~~~ typescript twoslash
+// @noErrors: 2345
+import { configure } from "@logtape/logtape";
+// ---cut-before---
 await configure({
   // ... sinks configuration
   filters: {
@@ -82,7 +86,9 @@ await configure({
       return record.level === "error" || record.level === "fatal";
     },
     containsUserData(record) {
-      return record.message.some(part => part.includes("user"));
+      return record.message.some(
+        part => typeof part === "string" && part.includes("user")
+      );
     },
   },
   // ... loggers configuration
@@ -94,7 +100,10 @@ await configure({
 Loggers are where you bring everything together.  You can set up different
 loggers for different parts of your application:
 
-~~~~ typescript
+~~~~ typescript twoslash
+// @noErrors: 2345
+import { configure } from "@logtape/logtape";
+// ---cut-before---
 await configure({
   // ... sinks and filters configuration
   loggers: [
@@ -139,7 +148,9 @@ Here's how you might do that:
 
 ::: code-group
 
-~~~~ typescript{1,6,11-12} [Deno]
+~~~~ typescript{1,6,11-12} twoslash [Deno]
+import { configure, getConsoleSink, getFileSink } from "@logtape/logtape";
+// ---cut-before---
 const isDevelopment = Deno.env.get("DENO_DEPLOYMENT_ID") == null;
 
 await configure({
@@ -157,7 +168,11 @@ await configure({
 });
 ~~~~
 
-~~~~ typescript{1,6,11-12} [Node]
+~~~~ typescript{1,6,11-12} twoslash [Node.js]
+import "@types/node";
+import process from "node:process";
+import { configure, getConsoleSink, getFileSink } from "@logtape/logtape";
+// ---cut-before---
 const isDevelopment = process.env.NODE_ENV === "development";
 
 await configure({
@@ -183,7 +198,10 @@ Remember that calling `configure()` with `reset: true` option will reset any
 existing configuration.  If you need to change the configuration at runtime,
 you can call `configure()` again with `reset: true` and the new settings:
 
-~~~~ typescript
+~~~~ typescript twoslash
+import { type Config, configure } from "@logtape/logtape";
+const initialConfig = {} as unknown as Config<string, string>;
+// ---cut-before---
 // Initial configuration
 await configure(initialConfig);
 
@@ -204,7 +222,10 @@ await configure({
 
 Or you can explicitly call `reset()` to clear the existing configuration:
 
-~~~~ typescript
+~~~~ typescript twoslash
+import { type Config } from "@logtape/logtape";
+const initialConfig = {} as unknown as Config<string, string>;
+// ---cut-before---
 import { configure, reset } from "@logtape/logtape";
 
 await configure(initialConfig);

docs/manual/contexts.md

@@ -8,7 +8,9 @@ messages.  A context is a key-value map.  You can set a context for a logger
 and log messages `~Logger.with()` the context.  Here's an example of setting
 a context for a logger:
 
-~~~~ typescript
+~~~~ typescript twoslash
+import { getLogger } from "@logtape/logtape";
+// ---cut-before---
 const logger = getLogger(["my-app", "my-module"]);
 const ctx = logger.with({ userId: 1234, requestId: "abc" });
 ctx.info `This log message will have the context (userId & requestId).`;
@@ -18,10 +20,12 @@ ctx.warn("Context can be used inside message template: {userId}, {requestId}.");
 The context is inherited by child loggers.  Here's an example of setting a
 context for a parent logger and logging messages with a child logger:
 
-~~~~ typescript
+~~~~ typescript twoslash
+import { getLogger } from "@logtape/logtape";
+// ---cut-before---
 const logger = getLogger(["my-app"]);
 const parentCtx = logger.with({ userId: 1234, requestId: "abc" });
-const childCtx = parentCtx.getLogger(["my-module"]);
+const childCtx = parentCtx.getChild(["my-module"]);
 childCtx.debug("This log message will have the context: {userId} {requestId}.");
 ~~~~
 

docs/manual/filters.md

@@ -6,7 +6,9 @@ and returns a boolean value.  If the filter returns `true`, the log record is
 passed to the sinks; otherwise, the log record is discarded.  The signature of
 `Filter` is:
 
-~~~~ typescript
+~~~~ typescript twoslash
+import type { LogRecord } from "@logtape/logtape";
+// ---cut-before---
 export type Filter = (record: LogRecord) => boolean;
 ~~~~
 
@@ -17,14 +19,17 @@ the `~Config.loggers` object to assign filters to loggers.
 For example, the following filter discards log messages whose property `elapsed`
 is less than 100 milliseconds:
 
-~~~~ typescript {5-9}
+~~~~ typescript{5-9} twoslash
+// @noErrors: 2345
 import { configure, type LogRecord } from "@logtape/logtape";
 
 await configure({
   // Omitted for brevity
   filters: {
     tooSlow(record: LogRecord) {
-      return "elapsed" in record.properties && record.properties.elapsed >= 100;
+      return "elapsed" in record.properties
+        && typeof record.properties.elapsed === "number"
+        && record.properties.elapsed >= 100;
     },
   },
   loggers: [
@@ -47,12 +52,13 @@ filter log messages by their log levels.  The level filter factory takes
 a `LogLevel` string and returns a level filter.  For example, the following
 level filter discards log messages whose log level is less than `info`:
 
-~~~~ typescript
-import { getLevelFilter } from "@logtape/logtape";
+~~~~ typescript twoslash
+// @noErrors: 2345
+import { configure, getLevelFilter } from "@logtape/logtape";
 
 await configure({
   filters: {
-    infoOrHigher: getLevelFilter("info");  // [!code highlight]
+    infoOrHigher: getLevelFilter("info"),  // [!code highlight]
   },
   // Omitted for brevity
 });
@@ -65,14 +71,17 @@ Sink filter
 A sink filter is a filter that is applied to a specific [sink](./sinks.md).
 You can add a sink filter to a sink by decorating the sink with `withFilter()`:
 
-~~~~ typescript {5-8}
-import { getConsoleSink, withFilter } from "@logtape/logtape";
+~~~~ typescript{5-8} twoslash
+// @noErrors: 2345
+import { configure, getConsoleSink, withFilter } from "@logtape/logtape";
 
 await configure({
   sinks: {
     filteredConsole: withFilter(
       getConsoleSink(),
-      log => "elapsed" in log.properties && log.properties.elapsed >= 100,
+      log => "elapsed" in log.properties &&
+        typeof log.properties.elapsed === "number" &&
+        log.properties.elapsed >= 100,
     ),
   },
   // Omitted for brevity

docs/manual/formatters.md

@@ -241,7 +241,9 @@ Fully customized text formatter
 A text formatter is just a function that takes a log record and returns
 a string.  The type of a text formatter is `TextFormatter`:
 
-~~~~ typescript
+~~~~ typescript twoslash
+import type { LogRecord } from "@logtape/logtape";
+// ---cut-before---
 export type TextFormatter = (record: LogRecord) => string;
 ~~~~
 
@@ -250,7 +252,9 @@ a function that takes a log record and returns a string.  For example,
 the following function is a text formatter that formats log records into
 [JSON Lines]:
 
-~~~~ typescript
+~~~~ typescript twoslash
+import type { LogRecord } from "@logtape/logtape";
+// ---cut-before---
 function jsonLinesFormatter(record: LogRecord): string {
   return JSON.stringify(record) + "\n";
 }