effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Logger.js

@@ -1,102 +1,87 @@
 /**
- * @since 2.0.0
- *
- * The `Logger` module provides a robust and flexible logging system for Effect applications.
- * It offers structured logging, multiple output formats, and seamless integration with the
- * Effect runtime's tracing and context management.
- *
- * ## Key Features
- *
- * - **Structured Logging**: Built-in support for structured log messages with metadata
- * - **Multiple Formats**: JSON, LogFmt, Pretty, and custom formatting options
- * - **Context Integration**: Automatic capture of fiber context, spans, and annotations
- * - **Batching**: Efficient log aggregation and batch processing
- * - **File Output**: Direct file writing with configurable batch windows
- * - **Composable**: Transform and compose loggers using functional patterns
- *
- * ## Basic Usage
- *
- * ```ts
- * import { Effect } from "effect"
- *
- * // Basic logging
- * const program = Effect.gen(function*() {
- *   yield* Effect.log("Application started")
- *   yield* Effect.logInfo("Processing user request")
- *   yield* Effect.logWarning("Resource limit approaching")
- *   yield* Effect.logError("Database connection failed")
- * })
- *
- * // With structured data
- * const structuredLog = Effect.gen(function*() {
- *   yield* Effect.log("User action", { userId: 123, action: "login" })
- *   yield* Effect.logInfo("Request processed", { duration: 150, statusCode: 200 })
- * })
- * ```
- *
- * ## Custom Loggers
- *
- * ```ts
- * import { Effect, Logger } from "effect"
- *
- * // Create a custom logger
- * const customLogger = Logger.make((options) => {
- *   console.log(`[${options.logLevel}] ${options.message}`)
- * })
- *
- * // Use JSON format for production
- * const jsonLogger = Logger.consoleJson
- *
- * // Pretty format for development
- * const prettyLogger = Logger.consolePretty()
- *
- * const program = Effect.log("Hello World").pipe(
- *   Effect.provide(Logger.layer([jsonLogger]))
- * )
- * ```
- *
- * ## Multiple Loggers
+ * The `Logger` module defines the logging model used by the Effect runtime and
+ * provides constructors for formatting, routing, batching, and installing
+ * loggers. A `Logger<Message, Output>` receives each runtime log event as an
+ * {@link Options} value and transforms it into an output such as a string,
+ * structured object, JSON line, console write, file write, or trace span event.
+ *
+ * **Mental model**
+ *
+ * - Effect programs emit log events with APIs such as `Effect.log`,
+ *   `Effect.logInfo`, `Effect.logWarning`, and `Effect.logError`
+ * - Each event contains a message, log level, cause, fiber, and timestamp
+ * - Loggers are ordinary values created with {@link make} and installed with
+ *   {@link layer}
+ * - Multiple loggers can be active at once by providing a layer with several
+ *   logger values
+ * - Formatter loggers such as {@link formatLogFmt}, {@link formatStructured},
+ *   and {@link formatJson} return formatted data without writing it anywhere
+ * - Console loggers such as {@link consolePretty}, {@link consoleLogFmt},
+ *   {@link consoleStructured}, and {@link consoleJson} write formatted output
+ *   to the active Effect console
+ *
+ * **Log output structure**
+ *
+ * Built-in formatters include the log level, timestamp, fiber identifier, and
+ * logged message. When present, they also include the pretty-printed cause,
+ * active log annotations, and active log spans. Structured and JSON loggers keep
+ * these fields as machine-readable data, while logfmt and pretty loggers render
+ * them as human-readable text.
+ *
+ * **Common tasks**
+ *
+ * - Create a custom logger: {@link make}
+ * - Transform logger output: {@link map}
+ * - Write formatter output to the console: {@link withConsoleLog},
+ *   {@link withConsoleError}, {@link withLeveledConsole}
+ * - Use built-in console loggers: {@link consolePretty}, {@link consoleLogFmt},
+ *   {@link consoleStructured}, {@link consoleJson}
+ * - Use built-in formatter loggers: {@link formatSimple}, {@link formatLogFmt},
+ *   {@link formatStructured}, {@link formatJson}
+ * - Batch logger output before flushing to a sink: {@link batched}
+ * - Write string logger output to a file: {@link toFile}
+ * - Preserve trace correlation by including {@link tracerLogger}
+ * - Install or replace loggers for an effect: {@link layer}
+ *
+ * **Gotchas**
+ *
+ * - {@link layer} replaces the current logger set by default; pass
+ *   `mergeWithExisting: true` when adding loggers to the existing runtime
+ *   loggers
+ * - Formatter loggers only produce values; wrap them with console, file, batch,
+ *   or custom sink loggers when output should be written somewhere
+ * - {@link batched} and {@link toFile} are scoped; keep their scope open while
+ *   logs are being emitted so buffered entries can flush reliably
+ * - {@link toFile} accepts only loggers that output strings, so pair it with
+ *   string formatters such as {@link formatJson} or {@link formatLogFmt}
+ * - The default runtime logger set includes {@link tracerLogger}; replacing
+ *   loggers without merging may remove automatic log-to-trace-span recording
+ *
+ * **Quickstart**
+ *
+ * **Example** (Installing a JSON console logger)
  *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
- * // Combine multiple loggers
- * const CombinedLoggerLive = Logger.layer([
- *   Logger.consoleJson,
- *   Logger.consolePretty()
- * ])
- *
- * const program = Effect.log("Application event").pipe(
- *   Effect.provide(CombinedLoggerLive)
+ * const program = Effect.gen(function*() {
+ *   yield* Effect.logInfo("request started", { method: "GET", path: "/users" })
+ *   yield* Effect.logError("request failed", { status: 500 })
+ * }).pipe(
+ *   Effect.annotateLogs("service", "users-api"),
+ *   Effect.withLogSpan("http.request"),
+ *   Effect.provide(Logger.layer([Logger.consoleJson]))
  * )
  * ```
  *
- * ## Batched Logging
- *
- * ```ts
- * import { Duration, Effect, Logger } from "effect"
+ * **See also**
  *
- * const batchedLogger = Logger.batched(Logger.formatJson, {
- *   window: Duration.seconds(5),
- *   flush: (messages) =>
- *     Effect.sync(() => {
- *       // Process batch of log messages
- *       console.log("Flushing", messages.length, "log entries")
- *     })
- * })
+ * - {@link make} for defining custom loggers
+ * - {@link layer} for installing loggers
+ * - {@link formatJson} and {@link consoleJson} for structured production logs
+ * - {@link consolePretty} for readable local logs
  *
- * const program = Effect.gen(function*() {
- *   const logger = yield* batchedLogger
- *   yield* Effect.provide(
- *     Effect.all([
- *       Effect.log("Event 1"),
- *       Effect.log("Event 2"),
- *       Effect.log("Event 3")
- *     ]),
- *     Logger.layer([logger])
- *   )
- * })
- * ```
+ * @since 2.0.0
  */
 import * as Array from "./Array.js";
 import * as FileSystem from "./FileSystem.js";
@@ -111,7 +96,8 @@ const TypeId = "~effect/Logger";
 /**
  * Returns `true` if the specified value is a `Logger`, otherwise returns `false`.
  *
- * @example
+ * **Example** (Checking logger values)
+ *
  * ```ts
  * import { Logger } from "effect"
  *
@@ -124,12 +110,20 @@ const TypeId = "~effect/Logger";
  * console.log(Logger.isLogger({ log: () => {} })) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isLogger = u => Predicate.hasProperty(u, TypeId);
 /**
- * @example
+ * Context reference containing the active loggers for the current fiber.
+ *
+ * **Details**
+ * By default this set includes the default logger and the tracer logger.
+ * Providing `Logger.layer` replaces or merges with this set depending on its
+ * options.
+ *
+ * **Example** (Accessing current loggers)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -149,13 +143,16 @@ export const isLogger = u => Predicate.hasProperty(u, TypeId);
  * })
  * ```
  *
- * @since 4.0.0
  * @category references
+ * @since 4.0.0
  */
 export const CurrentLoggers = effect.CurrentLoggers;
 /**
- * @since 4.0.0
+ * Context reference that controls whether console-style loggers write to
+ * `console.error` instead of `console.log`.
+ *
  * @category references
+ * @since 4.0.0
  */
 export const LogToStderr = effect.LogToStderr;
 /**
@@ -164,7 +161,8 @@ export const LogToStderr = effect.LogToStderr;
  * This allows you to modify, enhance, or completely change the output format
  * of an existing logger without recreating the entire logging logic.
  *
- * @example
+ * **Example** (Transforming logger output)
+ *
  * ```ts
  * import { Logger } from "effect"
  *
@@ -188,8 +186,8 @@ export const LogToStderr = effect.LogToStderr;
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => effect.loggerMake(options => f(self.log(options))));
 /**
@@ -199,7 +197,8 @@ export const map = /*#__PURE__*/dual(2, (self, f) => effect.loggerMake(options =
  * This is useful for taking any logger that produces string or object output
  * and routing it to the console for development or debugging purposes.
  *
- * @example
+ * **Example** (Writing logger output with console.log)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -216,8 +215,8 @@ export const map = /*#__PURE__*/dual(2, (self, f) => effect.loggerMake(options =
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const withConsoleLog = self => effect.loggerMake(options => {
   const console = options.fiber.getRef(effect.ConsoleRef);
@@ -230,7 +229,8 @@ export const withConsoleLog = self => effect.loggerMake(options => {
  * This is particularly useful for error logging where you want to ensure
  * log messages appear in the error stream (stderr) rather than standard output.
  *
- * @example
+ * **Example** (Writing logger output with console.error)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -247,8 +247,8 @@ export const withConsoleLog = self => effect.loggerMake(options => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const withConsoleError = self => effect.loggerMake(options => {
   const console = options.fiber.getRef(effect.ConsoleRef);
@@ -268,7 +268,8 @@ export const withConsoleError = self => effect.loggerMake(options => {
  * - `Error` and `Fatal` -> `console.error`
  * - Others -> `console.log`
  *
- * @example
+ * **Example** (Writing logs with level-based console methods)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -288,8 +289,8 @@ export const withConsoleError = self => effect.loggerMake(options => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 3.8.0
  */
 export const withLeveledConsole = self => effect.loggerMake(options => {
   const console = options.fiber.getRef(effect.ConsoleRef);
@@ -370,10 +371,10 @@ const format = (quoteValue, space) => ({
  * The log function receives an options object containing the message, log level,
  * cause, fiber information, and timestamp, and should return the desired output.
  *
- * @example
+ * **Example** (Creating loggers from functions)
+ *
  * ```ts
- * import { Effect, Logger } from "effect"
- * import { CurrentLogAnnotations } from "effect/References"
+ * import { Effect, Logger, References } from "effect"
  *
  * // Simple text logger
  * const textLogger = Logger.make((options) =>
@@ -386,7 +387,7 @@ const format = (quoteValue, space) => ({
  *   level: options.logLevel,
  *   message: options.message,
  *   fiberId: options.fiber.id,
- *   annotations: options.fiber.getRef(CurrentLogAnnotations)
+ *   annotations: options.fiber.getRef(References.CurrentLogAnnotations)
  * }))
  *
  * // Custom filtering logger
@@ -402,14 +403,15 @@ const format = (quoteValue, space) => ({
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = effect.loggerMake;
 /**
  * The default logging implementation used by the Effect runtime.
  *
- * @example
+ * **Example** (Using the default logger)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -431,8 +433,8 @@ export const make = effect.loggerMake;
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const defaultLogger = effect.defaultLogger;
 /**
@@ -443,7 +445,8 @@ export const defaultLogger = effect.defaultLogger;
  * timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=hello
  * ```
  *
- * @example
+ * **Example** (Formatting logs as simple strings)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -464,8 +467,8 @@ export const defaultLogger = effect.defaultLogger;
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const formatSimple = /*#__PURE__*/effect.loggerMake(/*#__PURE__*/format(escapeDoubleQuotes));
 /**
@@ -477,7 +480,8 @@ export const formatSimple = /*#__PURE__*/effect.loggerMake(/*#__PURE__*/format(e
  * timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=hello
  * ```
  *
- * @example
+ * **Example** (Formatting logs as logfmt)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -501,8 +505,8 @@ export const formatSimple = /*#__PURE__*/effect.loggerMake(/*#__PURE__*/format(e
  * const productionLogger = Logger.formatLogFmt
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const formatLogFmt = /*#__PURE__*/effect.loggerMake(/*#__PURE__*/format(JSON.stringify, 0));
 /**
@@ -520,7 +524,8 @@ export const formatLogFmt = /*#__PURE__*/effect.loggerMake(/*#__PURE__*/format(J
  * }
  * ```
  *
- * @example
+ * **Example** (Formatting logs as structured objects)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -547,8 +552,8 @@ export const formatLogFmt = /*#__PURE__*/effect.loggerMake(/*#__PURE__*/format(J
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const formatStructured = /*#__PURE__*/effect.loggerMake(({
   cause,
@@ -588,7 +593,8 @@ export const formatStructured = /*#__PURE__*/effect.loggerMake(({
  * {"message":["hello"],"level":"INFO","timestamp":"2025-01-03T14:28:57.508Z","annotations":{"key":"value"},"spans":{"label":0},"fiberId":"#1"}
  * ```
  *
- * @example
+ * **Example** (Formatting logs as JSON)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -611,28 +617,29 @@ export const formatStructured = /*#__PURE__*/effect.loggerMake(({
  *   Effect.provide(Logger.layer([Logger.formatJson]))
  * )
  *
- * // Send to external logging service
- * const externalLogger = Logger.map(Logger.formatJson, (jsonString) => {
- *   // Send to Elasticsearch, CloudWatch, etc.
- *   console.log("Sending to external service:", jsonString)
- *   return jsonString
- * })
+ * // Adapt the JSON string before giving it to an output sink
+ * const envelopedJsonLogger = Logger.map(
+ *   Logger.formatJson,
+ *   (jsonString) => `{"service":"api-server","entry":${jsonString}}`
+ * )
+ *
+ * const envelopedConsoleLogger = Logger.withConsoleLog(envelopedJsonLogger)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const formatJson = /*#__PURE__*/map(formatStructured, Formatter.formatJson);
 /**
- * Returns a new `Logger` which will aggregate logs output by the specified
- * `Logger` over the provided `window`. After the `window` has elapsed, the
- * provided `flush` function will be called with the logs aggregated during
- * the last `window`.
+ * Creates, in a scope, a logger that batches the output of another logger.
  *
- * This is useful for implementing efficient batch processing of logs, such as
- * writing multiple log entries to a database or file in a single operation.
+ * **Details**
+ * The returned effect starts a scoped background process that periodically
+ * passes buffered outputs to `flush`. When the scope closes, the background
+ * process is interrupted and any remaining buffered entries are flushed.
+ *
+ * **Example** (Batching logger output)
  *
- * @example
  * ```ts
  * import { Duration, Effect, Logger } from "effect"
  *
@@ -672,8 +679,8 @@ export const formatJson = /*#__PURE__*/map(formatStructured, Formatter.formatJso
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const batched = /*#__PURE__*/dual(2, (self, options) => effect.flatMap(effect.scope, scope => {
   let buffer = [];
@@ -699,7 +706,8 @@ export const batched = /*#__PURE__*/dual(2, (self, options) => effect.flatMap(ef
  *   key: value
  * ```
  *
- * @example
+ * **Example** (Logging with pretty console output)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -731,8 +739,8 @@ export const batched = /*#__PURE__*/dual(2, (self, options) => effect.flatMap(ef
  * const ciLogger = Logger.consolePretty({ colors: false })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const consolePretty = effect.consolePretty;
 /**
@@ -744,7 +752,8 @@ export const consolePretty = effect.consolePretty;
  * timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=info
  * ```
  *
- * @example
+ * **Example** (Logging logfmt output to the console)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -774,8 +783,8 @@ export const consolePretty = effect.consolePretty;
  * ])
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const consoleLogFmt = /*#__PURE__*/withConsoleLog(formatLogFmt);
 /**
@@ -794,7 +803,8 @@ export const consoleLogFmt = /*#__PURE__*/withConsoleLog(formatLogFmt);
  * }
  * ```
  *
- * @example
+ * **Example** (Logging structured output to the console)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -832,8 +842,8 @@ export const consoleLogFmt = /*#__PURE__*/withConsoleLog(formatLogFmt);
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const consoleStructured = /*#__PURE__*/withConsoleLog(formatStructured);
 /**
@@ -845,7 +855,8 @@ export const consoleStructured = /*#__PURE__*/withConsoleLog(formatStructured);
  * {"message":["hello"],"level":"INFO","timestamp":"2025-01-03T14:28:57.508Z","annotations":{"key":"value"},"spans":{"label":0},"fiberId":"#1"}
  * ```
  *
- * @example
+ * **Example** (Logging JSON output to the console)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -888,8 +899,8 @@ export const consoleStructured = /*#__PURE__*/withConsoleLog(formatStructured);
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const consoleJson = /*#__PURE__*/withConsoleLog(formatJson);
 /**
@@ -903,7 +914,8 @@ export const consoleJson = /*#__PURE__*/withConsoleLog(formatJson);
  * Effect programs, so log messages automatically appear as span events unless
  * you override the default loggers.
  *
- * @example
+ * **Example** (Recording logs as trace span events)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -940,8 +952,8 @@ export const consoleJson = /*#__PURE__*/withConsoleLog(formatJson);
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const tracerLogger = effect.tracerLogger;
 /**
@@ -951,7 +963,8 @@ export const tracerLogger = effect.tracerLogger;
  * If the specified array of `loggers` should be _merged_ with the current set
  * of loggers (instead of overwriting them), set `mergeWithExisting` to `true`.
  *
- * @example
+ * **Example** (Providing logger layers)
+ *
  * ```ts
  * import { Effect, Logger } from "effect"
  *
@@ -982,8 +995,8 @@ export const tracerLogger = effect.tracerLogger;
  * )
  * ```
  *
- * @since 4.0.0
  * @category context
+ * @since 4.0.0
  */
 export const layer = (loggers, options) => Layer.effect(CurrentLoggers, withFiber(effect.fnUntraced(function* (fiber) {
   const currentLoggers = new Set(options?.mergeWithExisting === true ? fiber.getRef(effect.CurrentLoggers) : []);
@@ -993,13 +1006,18 @@ export const layer = (loggers, options) => Layer.effect(CurrentLoggers, withFibe
   return currentLoggers;
 })));
 /**
- * Create a Logger from another string Logger that writes to the specified file.
+ * Creates, in a scope, a logger that writes string logger output to a file.
  *
- * **Example**
+ * **Details**
+ * The returned effect requires `FileSystem` and `Scope`. The file logger batches
+ * string output, writes each batch to the specified path, and flushes remaining
+ * entries when the scope closes.
+ *
+ * **Example** (Writing JSON logs to a file)
  *
  * ```ts
- * import { NodeFileSystem, NodeRuntime } from "@effect/platform-node"
  * import { Effect, Layer, Logger } from "effect"
+ * import { NodeFileSystem, NodeRuntime } from "@effect/platform-node"
  *
  * const fileLogger = Logger.formatJson.pipe(
  *   Logger.toFile("/tmp/log.txt")
@@ -1016,65 +1034,73 @@ export const layer = (loggers, options) => Layer.effect(CurrentLoggers, withFibe
  * )
  * ```
  *
- * @example
+ * **Example** (Writing logs to files)
+ *
  * ```ts
- * import { NodeFileSystem } from "@effect/platform-node"
  * import { Duration, Effect, Logger } from "effect"
+ * import { NodeFileSystem } from "@effect/platform-node"
  *
- * // Basic file logging
- * const basicFileLogger = Effect.gen(function*() {
- *   const fileLogger = yield* Logger.formatJson.pipe(
- *     Logger.toFile("/tmp/app.log")
- *   )
- *
- *   yield* Effect.log("Application started").pipe(
- *     Effect.provide(Logger.layer([fileLogger]))
- *   )
- * }).pipe(
+ * // Basic file logging. The scope keeps the file open while logs are emitted
+ * // and flushes pending entries when it closes.
+ * const basicFileLogger = Effect.scoped(
+ *   Effect.gen(function*() {
+ *     const fileLogger = yield* Logger.formatJson.pipe(
+ *       Logger.toFile("/tmp/app.log")
+ *     )
+ *
+ *     yield* Effect.log("Application started").pipe(
+ *       Effect.provide(Logger.layer([fileLogger]))
+ *     )
+ *   })
+ * ).pipe(
  *   Effect.provide(NodeFileSystem.layer)
  * )
  *
  * // File logger with custom batch window
- * const batchedFileLogger = Effect.gen(function*() {
- *   const fileLogger = yield* Logger.formatLogFmt.pipe(
- *     Logger.toFile("/var/log/myapp.log", {
- *       flag: "a",
- *       batchWindow: Duration.seconds(5)
- *     })
- *   )
- *
- *   yield* Effect.all([
- *     Effect.log("Event 1"),
- *     Effect.log("Event 2"),
- *     Effect.log("Event 3")
- *   ]).pipe(
- *     Effect.provide(Logger.layer([fileLogger]))
- *   )
- * }).pipe(
+ * const batchedFileLogger = Effect.scoped(
+ *   Effect.gen(function*() {
+ *     const fileLogger = yield* Logger.formatLogFmt.pipe(
+ *       Logger.toFile("/var/log/myapp.log", {
+ *         flag: "a",
+ *         batchWindow: Duration.seconds(5)
+ *       })
+ *     )
+ *
+ *     yield* Effect.all([
+ *       Effect.log("Event 1"),
+ *       Effect.log("Event 2"),
+ *       Effect.log("Event 3")
+ *     ]).pipe(
+ *       Effect.provide(Logger.layer([fileLogger]))
+ *     )
+ *   })
+ * ).pipe(
  *   Effect.provide(NodeFileSystem.layer)
  * )
  *
  * // Multiple loggers: console + file
- * const multiLogger = Effect.gen(function*() {
- *   const fileLogger = yield* Logger.formatJson.pipe(
- *     Logger.toFile("/tmp/production.log")
- *   )
- *
- *   const loggerLive = Logger.layer([
- *     Logger.consolePretty(),
- *     fileLogger
- *   ])
- *
- *   yield* Effect.log("Production event").pipe(
- *     Effect.provide(loggerLive)
- *   )
- * }).pipe(
+ * const multiLogger = Effect.scoped(
+ *   Effect.gen(function*() {
+ *     const fileLogger = yield* Logger.formatJson.pipe(
+ *       Logger.toFile("/tmp/production.log")
+ *     )
+ *
+ *     const loggerLive = Logger.layer([
+ *       Logger.consolePretty(),
+ *       fileLogger
+ *     ])
+ *
+ *     yield* Effect.log("Production event").pipe(
+ *       Effect.provide(loggerLive)
+ *     )
+ *   })
+ * ).pipe(
  *   Effect.provide(NodeFileSystem.layer)
  * )
  * ```
  *
- * @since 4.0.0
  * @category file
+ * @since 4.0.0
  */
 export const toFile = /*#__PURE__*/dual(args => isLogger(args[0]), (self, path, options) => effect.gen(function* () {
   const fs = yield* FileSystem.FileSystem;