effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/LogLevel.ts

@@ -45,7 +45,10 @@ import * as Ord from "./Order.ts"
 import * as References from "./References.ts"
 
 /**
- * Represents the severity level of a log message.
+ * Represents every level used by Effect logging, including concrete message
+ * severities and the `All` and `None` sentinel levels.
+ *
+ * **Details**
  *
  * The levels are ordered from most severe to least severe:
  * - `All` - Special level that allows all messages
@@ -103,6 +106,8 @@ export const values: ReadonlyArray<LogLevel> = ["All", "Fatal", "Error", "Warn",
 /**
  * An `Order` instance for `LogLevel` that defines the severity ordering.
  *
+ * **Details**
+ *
  * This order treats "All" as the least restrictive level and "None" as the most restrictive,
  * with Fatal being the most severe actual log level.
  *
@@ -150,8 +155,14 @@ export const getOrdinal = (self: LogLevel): number => effect.logLevelToOrder(sel
 /**
  * Determines if the first log level is more severe than the second.
  *
+ * **When to use**
+ *
+ * Use this for strict severity comparisons when filtering logs based on minimum
+ * severity requirements.
+ *
+ * **Details**
+ *
  * Returns `true` if `self` represents a more severe level than `that`.
- * This is useful for filtering logs based on minimum severity requirements.
  *
  * **Example** (Checking higher severity)
  *
@@ -183,8 +194,14 @@ export const isGreaterThan: {
   /**
    * Determines if the first log level is more severe than the second.
    *
+   * **When to use**
+   *
+   * Use this for strict severity comparisons when filtering logs based on minimum
+   * severity requirements.
+   *
+   * **Details**
+   *
    * Returns `true` if `self` represents a more severe level than `that`.
-   * This is useful for filtering logs based on minimum severity requirements.
    *
    * **Example** (Checking higher severity)
    *
@@ -216,8 +233,14 @@ export const isGreaterThan: {
   /**
    * Determines if the first log level is more severe than the second.
    *
+   * **When to use**
+   *
+   * Use this for strict severity comparisons when filtering logs based on minimum
+   * severity requirements.
+   *
+   * **Details**
+   *
    * Returns `true` if `self` represents a more severe level than `that`.
-   * This is useful for filtering logs based on minimum severity requirements.
    *
    * **Example** (Checking higher severity)
    *
@@ -251,8 +274,13 @@ export const isGreaterThan: {
 /**
  * Determines if the first log level is more severe than or equal to the second.
  *
+ * **When to use**
+ *
+ * Use this for implementing minimum log level filtering.
+ *
+ * **Details**
+ *
  * Returns `true` if `self` represents a level that is more severe than or equal to `that`.
- * This is the most common function for implementing minimum log level filtering.
  *
  * **Example** (Filtering by minimum log level)
  *
@@ -292,8 +320,13 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Determines if the first log level is more severe than or equal to the second.
    *
+   * **When to use**
+   *
+   * Use this for implementing minimum log level filtering.
+   *
+   * **Details**
+   *
    * Returns `true` if `self` represents a level that is more severe than or equal to `that`.
-   * This is the most common function for implementing minimum log level filtering.
    *
    * **Example** (Filtering by minimum log level)
    *
@@ -333,8 +366,13 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Determines if the first log level is more severe than or equal to the second.
    *
+   * **When to use**
+   *
+   * Use this for implementing minimum log level filtering.
+   *
+   * **Details**
+   *
    * Returns `true` if `self` represents a level that is more severe than or equal to `that`.
-   * This is the most common function for implementing minimum log level filtering.
    *
    * **Example** (Filtering by minimum log level)
    *
@@ -376,8 +414,14 @@ export const isGreaterThanOrEqualTo: {
 /**
  * Determines if the first log level is less severe than the second.
  *
+ * **When to use**
+ *
+ * Use this for strict severity comparisons when filtering out logs that are too
+ * verbose.
+ *
+ * **Details**
+ *
  * Returns `true` if `self` represents a less severe level than `that`.
- * This is useful for filtering out logs that are too verbose.
  *
  * **Example** (Checking lower severity)
  *
@@ -409,8 +453,14 @@ export const isLessThan: {
   /**
    * Determines if the first log level is less severe than the second.
    *
+   * **When to use**
+   *
+   * Use this for strict severity comparisons when filtering out logs that are too
+   * verbose.
+   *
+   * **Details**
+   *
    * Returns `true` if `self` represents a less severe level than `that`.
-   * This is useful for filtering out logs that are too verbose.
    *
    * **Example** (Checking lower severity)
    *
@@ -442,8 +492,14 @@ export const isLessThan: {
   /**
    * Determines if the first log level is less severe than the second.
    *
+   * **When to use**
+   *
+   * Use this for strict severity comparisons when filtering out logs that are too
+   * verbose.
+   *
+   * **Details**
+   *
    * Returns `true` if `self` represents a less severe level than `that`.
-   * This is useful for filtering out logs that are too verbose.
    *
    * **Example** (Checking lower severity)
    *
@@ -477,8 +533,13 @@ export const isLessThan: {
 /**
  * Determines if the first log level is less severe than or equal to the second.
  *
+ * **When to use**
+ *
+ * Use this for implementing maximum log level filtering.
+ *
+ * **Details**
+ *
  * Returns `true` if `self` represents a level that is less severe than or equal to `that`.
- * This is useful for implementing maximum log level filtering.
  *
  * **Example** (Filtering by maximum log level)
  *
@@ -516,8 +577,13 @@ export const isLessThanOrEqualTo: {
   /**
    * Determines if the first log level is less severe than or equal to the second.
    *
+   * **When to use**
+   *
+   * Use this for implementing maximum log level filtering.
+   *
+   * **Details**
+   *
    * Returns `true` if `self` represents a level that is less severe than or equal to `that`.
-   * This is useful for implementing maximum log level filtering.
    *
    * **Example** (Filtering by maximum log level)
    *
@@ -555,8 +621,13 @@ export const isLessThanOrEqualTo: {
   /**
    * Determines if the first log level is less severe than or equal to the second.
    *
+   * **When to use**
+   *
+   * Use this for implementing maximum log level filtering.
+   *
+   * **Details**
+   *
    * Returns `true` if `self` represents a level that is less severe than or equal to `that`.
-   * This is useful for implementing maximum log level filtering.
    *
    * **Example** (Filtering by maximum log level)
    *
@@ -596,6 +667,8 @@ export const isLessThanOrEqualTo: {
 /**
  * Checks whether a given log level is enabled for the current fiber.
  *
+ * **Details**
+ *
  * A log level is enabled when it is greater than or equal to
  * `References.MinimumLogLevel`.
  *

package/src/Logger.ts

@@ -108,6 +108,7 @@ const TypeId = "~effect/Logger"
  * A logger that transforms a runtime log event into an output value.
  *
  * **Details**
+ *
  * The runtime calls `log` with the message, level, cause, fiber, and timestamp
  * for each log event. Use `Logger.layer` to install one or more loggers for an
  * effect.
@@ -145,6 +146,7 @@ export interface Logger<in Message, out Output> extends Pipeable {
  * Information supplied to a `Logger` for a single log event.
  *
  * **Details**
+ *
  * Includes the logged message, log level, cause, current fiber, and timestamp.
  *
  * **Example** (Accessing logger options)
@@ -206,6 +208,7 @@ export const isLogger = (u: unknown): u is Logger<unknown, unknown> => Predicate
  * 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.
@@ -248,6 +251,8 @@ export const LogToStderr: Context.Reference<boolean> = effect.LogToStderr
 /**
  * Transforms the output of a `Logger` using the provided function.
  *
+ * **When to use**
+ *
  * This allows you to modify, enhance, or completely change the output format
  * of an existing logger without recreating the entire logging logic.
  *
@@ -283,6 +288,8 @@ export const map = dual<
   /**
    * Transforms the output of a `Logger` using the provided function.
    *
+   * **When to use**
+   *
    * This allows you to modify, enhance, or completely change the output format
    * of an existing logger without recreating the entire logging logic.
    *
@@ -320,6 +327,8 @@ export const map = dual<
   /**
    * Transforms the output of a `Logger` using the provided function.
    *
+   * **When to use**
+   *
    * This allows you to modify, enhance, or completely change the output format
    * of an existing logger without recreating the entire logging logic.
    *
@@ -358,6 +367,8 @@ export const map = dual<
  * Returns a new `Logger` that writes all output of the specified `Logger` to
  * the console using `console.log`.
  *
+ * **When to use**
+ *
  * This is useful for taking any logger that produces string or object output
  * and routing it to the console for development or debugging purposes.
  *
@@ -393,6 +404,8 @@ export const withConsoleLog = <Message, Output>(
  * Returns a new `Logger` that writes all output of the specified `Logger` to
  * the console using `console.error`.
  *
+ * **When to use**
+ *
  * This is particularly useful for error logging where you want to ensure
  * log messages appear in the error stream (stderr) rather than standard output.
  *
@@ -428,6 +441,8 @@ export const withConsoleError = <Message, Output>(
  * Returns a new `Logger` that writes all output of the specified `Logger` to
  * the console.
  *
+ * **Details**
+ *
  * Will use the appropriate console method (i.e. `console.log`, `console.error`,
  * etc.) based upon the current `LogLevel`.
  *
@@ -546,6 +561,8 @@ const format = (
 /**
  * Creates a new `Logger` from a log function.
  *
+ * **Details**
+ *
  * The log function receives an options object containing the message, log level,
  * cause, fiber information, and timestamp, and should return the desired output.
  *
@@ -622,10 +639,10 @@ export const defaultLogger: Logger<unknown, void> = effect.defaultLogger
 /**
  * A `Logger` which outputs logs as a string.
  *
- * For example:
- * ```
- * timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=hello
- * ```
+ * **Details**
+ *
+ * For example, a simple log entry is rendered as
+ * `timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=hello`.
  *
  * **Example** (Formatting logs as simple strings)
  *
@@ -658,10 +675,10 @@ export const formatSimple = effect.loggerMake(format(escapeDoubleQuotes))
  * A `Logger` which outputs logs using the [logfmt](https://brandur.org/logfmt)
  * style.
  *
- * For example:
- * ```
- * timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=hello
- * ```
+ * **Details**
+ *
+ * For example, a logfmt entry is rendered as
+ * `timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=hello`.
  *
  * **Example** (Formatting logs as logfmt)
  *
@@ -696,17 +713,12 @@ export const formatLogFmt = effect.loggerMake(format(JSON.stringify, 0))
 /**
  * A `Logger` which outputs logs using a structured format.
  *
- * For example:
- * ```
- * {
- *   message: [ 'hello' ],
- *   level: 'INFO',
- *   timestamp: '2025-01-03T14:25:39.666Z',
- *   annotations: { key: 'value' },
- *   spans: { label: 0 },
- *   fiberId: '#1'
- * }
- * ```
+ * **Details**
+ *
+ * For example, a structured entry can contain `message: [ "hello" ]`,
+ * `level: "INFO"`, `timestamp: "2025-01-03T14:25:39.666Z"`,
+ * `annotations: { key: "value" }`, `spans: { label: 0 }`, and
+ * `fiberId: "#1"`.
  *
  * **Example** (Formatting logs as structured objects)
  *
@@ -780,10 +792,11 @@ export const formatStructured: Logger<unknown, {
  * A `Logger` which outputs logs using a structured format serialized as JSON
  * on a single line.
  *
- * For example:
- * ```
- * {"message":["hello"],"level":"INFO","timestamp":"2025-01-03T14:28:57.508Z","annotations":{"key":"value"},"spans":{"label":0},"fiberId":"#1"}
- * ```
+ * **Details**
+ *
+ * For example, a JSON entry can render as `{"message":["hello"],"level":"INFO",
+ * "timestamp":"2025-01-03T14:28:57.508Z","annotations":{"key":"value"},
+ * "spans":{"label":0},"fiberId":"#1"}`.
  *
  * **Example** (Formatting logs as JSON)
  *
@@ -827,6 +840,7 @@ export const formatJson = map(formatStructured, Formatter.formatJson)
  * Creates, in a scope, a logger that batches the output of another logger.
  *
  * **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.
@@ -880,6 +894,7 @@ export const batched = dual<
    * Creates, in a scope, a logger that batches the output of another logger.
    *
    * **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.
@@ -940,6 +955,7 @@ export const batched = dual<
    * Creates, in a scope, a logger that batches the output of another logger.
    *
    * **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.
@@ -1036,11 +1052,11 @@ export const batched = dual<
  * A `Logger` which outputs logs in a "pretty" format and writes them to the
  * console.
  *
- * For example:
- * ```
- * [09:37:17.579] INFO (#1) label=0ms: hello
- *   key: value
- * ```
+ * **Details**
+ *
+ * For example, pretty output can render as
+ * `[09:37:17.579] INFO (#1) label=0ms: hello` followed by an annotation line
+ * such as `key: value`.
  *
  * **Example** (Logging with pretty console output)
  *
@@ -1091,10 +1107,10 @@ export const consolePretty: (
  * A `Logger` which outputs logs using the [logfmt](https://brandur.org/logfmt)
  * style and writes them to the console.
  *
- * For example:
- * ```
- * timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=info
- * ```
+ * **Details**
+ *
+ * For example, a console logfmt entry is rendered as
+ * `timestamp=2025-01-03T14:22:47.570Z level=INFO fiber=#1 message=info`.
  *
  * **Example** (Logging logfmt output to the console)
  *
@@ -1133,20 +1149,16 @@ export const consolePretty: (
 export const consoleLogFmt: Logger<unknown, void> = withConsoleLog(formatLogFmt)
 
 /**
- * A `Logger` which outputs logs using a strctured format and writes them to
+ * A `Logger` which outputs logs using a structured format and writes them to
  * the console.
  *
- * For example:
- * ```
- * {
- *   message: [ 'info', 'message' ],
- *   level: 'INFO',
- *   timestamp: '2025-01-03T14:25:39.666Z',
- *   annotations: { key: 'value' },
- *   spans: { label: 0 },
- *   fiberId: '#1'
- * }
- * ```
+ * **Details**
+ *
+ * For example, console structured output can contain
+ * `message: [ "info", "message" ]`, `level: "INFO"`,
+ * `timestamp: "2025-01-03T14:25:39.666Z"`,
+ * `annotations: { key: "value" }`, `spans: { label: 0 }`, and
+ * `fiberId: "#1"`.
  *
  * **Example** (Logging structured output to the console)
  *
@@ -1196,10 +1208,11 @@ export const consoleStructured: Logger<unknown, void> = withConsoleLog(formatStr
  * A `Logger` which outputs logs using a structured format serialized as JSON
  * on a single line and writes them to the console.
  *
- * For example:
- * ```
- * {"message":["hello"],"level":"INFO","timestamp":"2025-01-03T14:28:57.508Z","annotations":{"key":"value"},"spans":{"label":0},"fiberId":"#1"}
- * ```
+ * **Details**
+ *
+ * For example, console JSON output can render as
+ * `{"message":["hello"],"level":"INFO","timestamp":"2025-01-03T14:28:57.508Z",
+ * "annotations":{"key":"value"},"spans":{"label":0},"fiberId":"#1"}`.
  *
  * **Example** (Logging JSON output to the console)
  *
@@ -1253,13 +1266,15 @@ export const consoleJson: Logger<unknown, void> = withConsoleLog(formatJson)
 /**
  * A `Logger` which includes log messages as tracer span events.
  *
+ * **Details**
+ *
  * This logger integrates logging with distributed tracing by recording
  * all log messages as events on the current trace span, making them visible
  * in tracing tools like OpenTelemetry, Jaeger, or Zipkin.
  *
- * **Note**: This logger is included in the default set of loggers for all
- * Effect programs, so log messages automatically appear as span events unless
- * you override the default loggers.
+ * This logger is included in the default set of loggers for all Effect programs,
+ * so log messages automatically appear as span events unless you override the
+ * default loggers.
  *
  * **Example** (Recording logs as trace span events)
  *
@@ -1308,6 +1323,8 @@ export const tracerLogger: Logger<unknown, void> = effect.tracerLogger
  * Creates a `Layer` which will overwrite the current set of loggers with the
  * specified array of `loggers`.
  *
+ * **Details**
+ *
  * If the specified array of `loggers` should be _merged_ with the current set
  * of loggers (instead of overwriting them), set `mergeWithExisting` to `true`.
  *
@@ -1374,6 +1391,7 @@ export const layer = <
  * Creates, in a scope, a logger that writes string logger output to a file.
  *
  * **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.
@@ -1472,6 +1490,7 @@ export const toFile = dual<
    * Creates, in a scope, a logger that writes string logger output to a file.
    *
    * **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.
@@ -1579,6 +1598,7 @@ export const toFile = dual<
    * Creates, in a scope, a logger that writes string logger output to a file.
    *
    * **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.

package/src/ManagedRuntime.ts

@@ -87,6 +87,7 @@ export declare namespace ManagedRuntime {
  * services.
  *
  * **Details**
+ *
  * The runtime builds and caches its service context, owns the scope for
  * resources acquired by the layer, and should be disposed with `dispose` or
  * `disposeEffect` when it is no longer needed.
@@ -117,6 +118,8 @@ export interface ManagedRuntime<in R, out ER> {
   /**
    * Executes the effect synchronously returning the exit.
    *
+   * **When to use**
+   *
    * This method is effectful and should only be invoked at the edges of your
    * program.
    */
@@ -125,6 +128,8 @@ export interface ManagedRuntime<in R, out ER> {
   /**
    * Executes the effect synchronously throwing in case of errors or async boundaries.
    *
+   * **When to use**
+   *
    * This method is effectful and should only be invoked at the edges of your
    * program.
    */
@@ -134,6 +139,8 @@ export interface ManagedRuntime<in R, out ER> {
    * Executes the effect asynchronously, eventually passing the exit value to
    * the specified callback.
    *
+   * **When to use**
+   *
    * This method is effectful and should only be invoked at the edges of your
    * program.
    */
@@ -151,6 +158,8 @@ export interface ManagedRuntime<in R, out ER> {
    * with the value of the effect once the effect has been executed, or will be
    * rejected with the first error or exception throw by the effect.
    *
+   * **When to use**
+   *
    * This method is effectful and should only be used at the edges of your
    * program.
    */
@@ -160,6 +169,8 @@ export interface ManagedRuntime<in R, out ER> {
    * Runs the `Effect`, returning a JavaScript `Promise` that will be resolved
    * with the `Exit` state of the effect once the effect has been executed.
    *
+   * **When to use**
+   *
    * This method is effectful and should only be used at the edges of your
    * program.
    */
@@ -183,6 +194,7 @@ export interface ManagedRuntime<in R, out ER> {
  * Creates a `ManagedRuntime` from a layer.
  *
  * **Details**
+ *
  * The layer is built lazily on first use and its context is cached for
  * subsequent runs. Resources acquired by the layer are owned by the runtime and
  * are released when `dispose` or `disposeEffect` is run.