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

package/src/LayerMap.ts

@@ -1,4 +1,37 @@
 /**
+ * The `LayerMap` module provides utilities for managing scoped resources that
+ * are selected by key and built from `Layer` values. A `LayerMap<K, I, E>` turns
+ * a key into a cached service `Context<I>`, so applications can lazily acquire
+ * and reuse different resource instances such as tenant clients, regional
+ * connections, environment-specific services, or other keyed infrastructure.
+ *
+ * **Mental model**
+ *
+ * - A `LayerMap` is a scoped, reference-counted cache of contexts produced by layers
+ * - Keys identify which layer-backed resource set should be acquired
+ * - Resources are acquired on demand when a key is requested
+ * - The same key reuses the cached context while it remains live
+ * - Cached resources are finalized when invalidated, when their scope closes, or after idle expiration
+ * - The layers built by a `LayerMap` share the current layer memoization map
+ *
+ * **Common tasks**
+ *
+ * - Create from a lookup function: {@link make}
+ * - Create from a fixed record of layers: {@link fromRecord}
+ * - Define a service wrapper with accessor helpers: {@link Service}
+ * - Retrieve a layer for a key: {@link LayerMap.get}
+ * - Retrieve a scoped context directly: {@link LayerMap.contextEffect}
+ * - Force a cached entry to be rebuilt later: {@link LayerMap.invalidate}
+ * - Remove idle entries automatically with the `idleTimeToLive` option
+ * - Eagerly build known entries with `preloadKeys` or `preload`
+ *
+ * **Gotchas**
+ *
+ * - `contextEffect` requires a `Scope.Scope` because it exposes the acquired context directly
+ * - `get` returns a `Layer` that can be provided to programs expecting the keyed services
+ * - Invalidating a key finalizes the current cached resources for that key; the next access rebuilds them
+ * - Preloading moves layer construction errors to `LayerMap` creation instead of first use
+ *
  * @since 3.14.0
  */
 import * as Context from "./Context.ts"
@@ -15,11 +48,17 @@ const TypeId = "~effect/LayerMap"
 type IdleTimeToLiveInput<K> = Duration.Input | ((key: K) => Duration.Input)
 
 /**
- * @since 3.14.0
- * @category Models
- * @example
+ * A scoped, keyed map of layer-built service contexts.
+ *
+ * **Details**
+ *
+ * A `LayerMap` builds resources for a key on demand, exposes them as a `Layer`
+ * or scoped `Context`, and can invalidate cached resources for a key.
+ *
+ * **Example** (Managing keyed layers)
+ *
  * ```ts
- * import { Effect, Layer, LayerMap, Context } from "effect"
+ * import { Context, Effect, Layer, LayerMap } from "effect"
  *
  * // Define a service key
  * const DatabaseService = Context.Service<{
@@ -47,6 +86,9 @@ type IdleTimeToLiveInput<K> = Duration.Input | ((key: K) => Duration.Input)
  *   yield* layerMap.invalidate("development")
  * })
  * ```
+ *
+ * @category models
+ * @since 3.14.0
  */
 export interface LayerMap<in out K, in out I, in out E = never> {
   readonly [TypeId]: typeof TypeId
@@ -73,15 +115,13 @@ export interface LayerMap<in out K, in out I, in out E = never> {
 }
 
 /**
- * @since 3.14.0
- * @category Constructors
- *
  * A `LayerMap` allows you to create a map of Layer's that can be used to
  * dynamically access resources based on a key.
  *
- * @example
+ * **Example** (Creating a layer map)
+ *
  * ```ts
- * import { Effect, Layer, LayerMap, Context } from "effect"
+ * import { Context, Effect, Layer, LayerMap } from "effect"
  *
  * // Define a service key
  * const DatabaseService = Context.Service<{
@@ -113,6 +153,9 @@ export interface LayerMap<in out K, in out I, in out E = never> {
  *   console.log(result) // "development: SELECT * FROM users"
  * })
  * ```
+ *
+ * @category constructors
+ * @since 3.14.0
  */
 export const make: <
   K,
@@ -155,11 +198,17 @@ export const make: <
 })
 
 /**
- * @since 3.14.0
- * @category Constructors
- * @example
+ * Creates a `LayerMap` from a record of predefined layers.
+ *
+ * **Details**
+ *
+ * The record keys become the keys accepted by the returned `LayerMap`, and the
+ * record values are the layers built for those keys.
+ *
+ * **Example** (Creating a layer map from a record)
+ *
  * ```ts
- * import { Effect, Layer, LayerMap, Context } from "effect"
+ * import { Context, Effect, Layer, LayerMap } from "effect"
  *
  * // Define service keys
  * const DevDatabase = Context.Service<{
@@ -193,6 +242,9 @@ export const make: <
  *   console.log("LayerMap created from record")
  * })
  * ```
+ *
+ * @category constructors
+ * @since 3.14.0
  */
 export const fromRecord = <
   const Layers extends Record<string, Layer.Layer<any, any, any>>,
@@ -218,8 +270,15 @@ export const fromRecord = <
   }) as any
 
 /**
+ * Service class shape produced by `LayerMap.Service`.
+ *
+ * **Details**
+ *
+ * It combines a `Context.Service` tag for the `LayerMap` with default layers
+ * and helper accessors for retrieving, using, and invalidating keyed resources.
+ *
+ * @category services
  * @since 3.14.0
- * @category Service
  */
 export interface TagClass<
   in out Self,
@@ -263,15 +322,13 @@ export interface TagClass<
 }
 
 /**
- * @since 3.14.0
- * @category Service
- *
  * Create a `LayerMap` service that provides a dynamic set of resources based on
  * a key.
  *
- * @example
+ * **Example** (Defining a layer map service)
+ *
  * ```ts
- * import { Console, Effect, Layer, LayerMap, Context } from "effect"
+ * import { Console, Context, Effect, Layer, LayerMap } from "effect"
  *
  * // Define a service key
  * const Greeter = Context.Service<{
@@ -303,6 +360,9 @@ export interface TagClass<
  *   Effect.provide(GreeterMap.layer)
  * )
  * ```
+ *
+ * @category services
+ * @since 3.14.0
  */
 export const Service = <Self>() =>
 <
@@ -373,41 +433,54 @@ export const Service = <Self>() =>
 }
 
 /**
+ * Type helpers for values created with `LayerMap.Service`.
+ *
  * @since 3.14.0
- * @category Service
  */
 export declare namespace Service {
   /**
+   * Extracts the key type accepted by a `LayerMap.Service` definition.
+   *
+   * @category services
    * @since 3.14.0
-   * @category Service
    */
   export type Key<Options> = Options extends { readonly lookup: (key: infer K) => any } ? K
     : Options extends { readonly layers: infer Layers } ? keyof Layers
     : never
 
   /**
+   * Extracts the layer type produced by a `LayerMap.Service` definition.
+   *
+   * @category services
    * @since 3.14.0
-   * @category Service
    */
   export type Layers<Options> = Options extends { readonly lookup: (key: infer _K) => infer Layers } ? Layers
     : Options extends { readonly layers: infer Layers } ? Layers[keyof Layers]
     : never
 
   /**
+   * Extracts the services provided by the layers in a `LayerMap.Service`
+   * definition.
+   *
+   * @category services
    * @since 3.14.0
-   * @category Service
    */
   export type Success<Options> = Layers<Options> extends Layer.Layer<infer _A, infer _E, infer _R> ? _A : never
 
   /**
+   * Extracts the error type of the layers in a `LayerMap.Service` definition.
+   *
+   * @category services
    * @since 3.14.0
-   * @category Service
    */
   export type Error<Options> = Layers<Options> extends Layer.Layer<infer _A, infer _E, infer _R> ? _E : never
 
   /**
-   * @since 3.14.0
-   * @category Service
+   * Extracts the service requirements of the layers in a `LayerMap.Service`
+   * definition.
+   *
+   * @category services
+   * @since 4.0.0
    */
   export type Services<Options> = Layers<Options> extends Layer.Layer<infer _A, infer _E, infer _R> ? _R : never
 }

package/src/LogLevel.ts

@@ -1,102 +1,41 @@
 /**
- * @since 2.0.0
- *
- * The `LogLevel` module provides utilities for managing log levels in Effect applications.
- * It defines a hierarchy of log levels and provides functions for comparing and filtering logs
- * based on their severity.
- *
- * ## Log Level Hierarchy
- *
- * The log levels are ordered from most severe to least severe:
- *
- * 1. **All** - Special level that allows all messages
- * 2. **Fatal** - System is unusable, immediate attention required
- * 3. **Error** - Error conditions that should be investigated
- * 4. **Warn** - Warning conditions that may indicate problems
- * 5. **Info** - Informational messages about normal operation
- * 6. **Debug** - Debug information useful during development
- * 7. **Trace** - Very detailed trace information
- * 8. **None** - Special level that suppresses all messages
- *
- * ## Basic Usage
- *
- * ```ts
- * import { Effect } from "effect"
- *
- * // Basic log level usage
- * const program = Effect.gen(function*() {
- *   yield* Effect.logFatal("System is shutting down")
- *   yield* Effect.logError("Database connection failed")
- *   yield* Effect.logWarning("Memory usage is high")
- *   yield* Effect.logInfo("User logged in")
- *   yield* Effect.logDebug("Processing request")
- *   yield* Effect.logTrace("Variable value: xyz")
- * })
- * ```
- *
- * ## Level Comparison
- *
- * ```ts
- * import { LogLevel } from "effect"
- *
- * // Check if one level is more severe than another
- * console.log(LogLevel.isGreaterThan("Error", "Info")) // true
- * console.log(LogLevel.isGreaterThan("Debug", "Error")) // false
- *
- * // Check if level meets minimum threshold
- * console.log(LogLevel.isGreaterThanOrEqualTo("Info", "Debug")) // true
- * console.log(LogLevel.isLessThan("Trace", "Info")) // true
- * ```
- *
- * ## Filtering by Level
- *
- * ```ts
- * import { Logger, LogLevel } from "effect"
- *
- * // Create a logger that only logs Error and above
- * const errorLogger = Logger.make((options) => {
- *   if (LogLevel.isGreaterThanOrEqualTo(options.logLevel, "Error")) {
- *     console.log(`[${options.logLevel}] ${options.message}`)
- *   }
- * })
- *
- * // Production logger - Info and above
- * const productionLogger = Logger.make((options) => {
- *   if (LogLevel.isGreaterThanOrEqualTo(options.logLevel, "Info")) {
- *     console.log(
- *       `${options.date.toISOString()} [${options.logLevel}] ${options.message}`
- *     )
- *   }
- * })
- *
- * // Development logger - Debug and above
- * const devLogger = Logger.make((options) => {
- *   if (LogLevel.isGreaterThanOrEqualTo(options.logLevel, "Debug")) {
- *     console.log(`[${options.logLevel}] ${options.message}`)
- *   }
- * })
- * ```
+ * The `LogLevel` module defines the levels used by Effect logging and the
+ * ordering operations used to compare, filter, and enable log output.
+ *
+ * **Mental model**
+ *
+ * - A `LogLevel` is one of `All`, `Fatal`, `Error`, `Warn`, `Info`, `Debug`,
+ *   `Trace`, or `None`
+ * - `Fatal` is the most severe concrete level and `Trace` is the least severe
+ * - `All` and `None` are sentinel levels: `All` enables every message and
+ *   `None` disables every message
+ * - Ordering follows logging severity, so higher levels are more important and
+ *   lower levels are more verbose
+ * - Filtering is usually expressed as "log this message when its level is
+ *   greater than or equal to the configured minimum"
+ *
+ * **Common tasks**
+ *
+ * - Enumerate levels with {@link values}
+ * - Compare exact levels with {@link Equivalence}
+ * - Sort or compare by severity with {@link Order} and {@link getOrdinal}
+ * - Check thresholds with {@link isGreaterThanOrEqualTo} and
+ *   {@link isLessThanOrEqualTo}
+ * - Test whether a level is enabled for the current fiber with
+ *   {@link isEnabled}
+ *
+ * **Gotchas**
+ *
+ * - `All` and `None` are useful for configuration boundaries, but they are not
+ *   concrete message severities; use {@link Severity} when only emitted message
+ *   levels are valid
+ * - The comparison helpers compare severity, not declaration position in source
+ *   code or alphabetical order
+ * - `isEnabled` reads the current fiber's `MinimumLogLevel` reference, so it is
+ *   context-sensitive; use the pure comparison helpers when checking an
+ *   explicit threshold
  *
- * ## Runtime Configuration
- *
- * ```ts
- * import { Config, Effect, Logger, LogLevel } from "effect"
- *
- * // Configure log level from environment
- * const logLevelConfig = Config.string("LOG_LEVEL").pipe(
- *   Config.withDefault("Info")
- * )
- *
- * const configurableLogger = Effect.gen(function*() {
- *   const minLevel = yield* logLevelConfig
- *
- *   return Logger.make((options) => {
- *     if (LogLevel.isGreaterThanOrEqualTo(options.logLevel, minLevel)) {
- *       console.log(`[${options.logLevel}] ${options.message}`)
- *     }
- *   })
- * })
- * ```
+ * @since 2.0.0
  */
 import type * as Effect from "./Effect.ts"
 import * as Equ from "./Equivalence.ts"
@@ -118,7 +57,8 @@ import * as References from "./References.ts"
  * - `Trace` - Very detailed trace information
  * - `None` - Special level that suppresses all messages
  *
- * @example
+ * **Example** (Using log levels)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -137,20 +77,26 @@ import * as References from "./References.ts"
  * const debugLevel = "Debug" // LogLevel
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 2.0.0
  */
 export type LogLevel = "All" | "Fatal" | "Error" | "Warn" | "Info" | "Debug" | "Trace" | "None"
 
 /**
- * @since 4.0.0
+ * Log levels that represent actual message severities, excluding the `All` and
+ * `None` sentinel levels.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Severity = "Fatal" | "Error" | "Warn" | "Info" | "Debug" | "Trace"
 
 /**
- * @since 4.0.0
+ * All `LogLevel` values in order from `All` through the concrete severities to
+ * `None`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export const values: ReadonlyArray<LogLevel> = ["All", "Fatal", "Error", "Warn", "Info", "Debug", "Trace", "None"]
 
@@ -160,7 +106,8 @@ export const values: ReadonlyArray<LogLevel> = ["All", "Fatal", "Error", "Warn",
  * This order treats "All" as the least restrictive level and "None" as the most restrictive,
  * with Fatal being the most severe actual log level.
  *
- * @example
+ * **Example** (Ordering log levels)
+ *
  * ```ts
  * import { LogLevel } from "effect"
  *
@@ -170,15 +117,16 @@ export const values: ReadonlyArray<LogLevel> = ["All", "Fatal", "Error", "Warn",
  * console.log(LogLevel.Order("Info", "Info")) // 0 (Info == Info)
  * ```
  *
- * @since 2.0.0
  * @category ordering
+ * @since 2.0.0
  */
 export const Order: Ord.Order<LogLevel> = effect.LogLevelOrder
 
 /**
  * An `Equivalence` instance for log levels using strict equality (`===`).
  *
- * @example
+ * **Example** (Comparing log levels)
+ *
  * ```ts
  * import { LogLevel } from "effect"
  *
@@ -194,8 +142,8 @@ export const Equivalence: Equ.Equivalence<LogLevel> = Equ.strictEqual<LogLevel>(
 /**
  * Returns the ordinal value of the log level.
  *
- * @since 4.0.0
  * @category ordering
+ * @since 4.0.0
  */
 export const getOrdinal = (self: LogLevel): number => effect.logLevelToOrder(self)
 
@@ -205,7 +153,8 @@ export const getOrdinal = (self: LogLevel): number => effect.logLevelToOrder(sel
  * Returns `true` if `self` represents a more severe level than `that`.
  * This is useful for filtering logs based on minimum severity requirements.
  *
- * @example
+ * **Example** (Checking higher severity)
+ *
  * ```ts
  * import { LogLevel } from "effect"
  *
@@ -227,8 +176,8 @@ export const getOrdinal = (self: LogLevel): number => effect.logLevelToOrder(sel
  * console.log(isMoreSevereThanInfo("Debug")) // false
  * ```
  *
- * @since 2.0.0
  * @category ordering
+ * @since 4.0.0
  */
 export const isGreaterThan: {
   /**
@@ -237,7 +186,8 @@ export const isGreaterThan: {
    * Returns `true` if `self` represents a more severe level than `that`.
    * This is useful for filtering logs based on minimum severity requirements.
    *
-   * @example
+   * **Example** (Checking higher severity)
+   *
    * ```ts
    * import { LogLevel } from "effect"
    *
@@ -259,8 +209,8 @@ export const isGreaterThan: {
    * console.log(isMoreSevereThanInfo("Debug")) // false
    * ```
    *
-   * @since 2.0.0
    * @category ordering
+   * @since 4.0.0
    */
   (that: LogLevel): (self: LogLevel) => boolean
   /**
@@ -269,7 +219,8 @@ export const isGreaterThan: {
    * Returns `true` if `self` represents a more severe level than `that`.
    * This is useful for filtering logs based on minimum severity requirements.
    *
-   * @example
+   * **Example** (Checking higher severity)
+   *
    * ```ts
    * import { LogLevel } from "effect"
    *
@@ -291,8 +242,8 @@ export const isGreaterThan: {
    * console.log(isMoreSevereThanInfo("Debug")) // false
    * ```
    *
-   * @since 2.0.0
    * @category ordering
+   * @since 4.0.0
    */
   (self: LogLevel, that: LogLevel): boolean
 } = effect.isLogLevelGreaterThan
@@ -303,7 +254,8 @@ export const isGreaterThan: {
  * 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
+ * **Example** (Filtering by minimum log level)
+ *
  * ```ts
  * import { Logger, LogLevel } from "effect"
  *
@@ -333,8 +285,8 @@ export const isGreaterThan: {
  * const shouldLog = isInfoOrAbove("Error") // true
  * ```
  *
- * @since 2.0.0
  * @category ordering
+ * @since 4.0.0
  */
 export const isGreaterThanOrEqualTo: {
   /**
@@ -343,7 +295,8 @@ export const isGreaterThanOrEqualTo: {
    * 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
+   * **Example** (Filtering by minimum log level)
+   *
    * ```ts
    * import { Logger, LogLevel } from "effect"
    *
@@ -373,8 +326,8 @@ export const isGreaterThanOrEqualTo: {
    * const shouldLog = isInfoOrAbove("Error") // true
    * ```
    *
-   * @since 2.0.0
    * @category ordering
+   * @since 4.0.0
    */
   (that: LogLevel): (self: LogLevel) => boolean
   /**
@@ -383,7 +336,8 @@ export const isGreaterThanOrEqualTo: {
    * 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
+   * **Example** (Filtering by minimum log level)
+   *
    * ```ts
    * import { Logger, LogLevel } from "effect"
    *
@@ -413,8 +367,8 @@ export const isGreaterThanOrEqualTo: {
    * const shouldLog = isInfoOrAbove("Error") // true
    * ```
    *
-   * @since 2.0.0
    * @category ordering
+   * @since 4.0.0
    */
   (self: LogLevel, that: LogLevel): boolean
 } = Ord.isGreaterThanOrEqualTo(Order)
@@ -425,7 +379,8 @@ export const isGreaterThanOrEqualTo: {
  * Returns `true` if `self` represents a less severe level than `that`.
  * This is useful for filtering out logs that are too verbose.
  *
- * @example
+ * **Example** (Checking lower severity)
+ *
  * ```ts
  * import { LogLevel } from "effect"
  *
@@ -447,8 +402,8 @@ export const isGreaterThanOrEqualTo: {
  * console.log(isLessSevereThanError("Fatal")) // false
  * ```
  *
- * @since 2.0.0
  * @category ordering
+ * @since 4.0.0
  */
 export const isLessThan: {
   /**
@@ -457,7 +412,8 @@ export const isLessThan: {
    * Returns `true` if `self` represents a less severe level than `that`.
    * This is useful for filtering out logs that are too verbose.
    *
-   * @example
+   * **Example** (Checking lower severity)
+   *
    * ```ts
    * import { LogLevel } from "effect"
    *
@@ -479,8 +435,8 @@ export const isLessThan: {
    * console.log(isLessSevereThanError("Fatal")) // false
    * ```
    *
-   * @since 2.0.0
    * @category ordering
+   * @since 4.0.0
    */
   (that: LogLevel): (self: LogLevel) => boolean
   /**
@@ -489,7 +445,8 @@ export const isLessThan: {
    * Returns `true` if `self` represents a less severe level than `that`.
    * This is useful for filtering out logs that are too verbose.
    *
-   * @example
+   * **Example** (Checking lower severity)
+   *
    * ```ts
    * import { LogLevel } from "effect"
    *
@@ -511,8 +468,8 @@ export const isLessThan: {
    * console.log(isLessSevereThanError("Fatal")) // false
    * ```
    *
-   * @since 2.0.0
    * @category ordering
+   * @since 4.0.0
    */
   (self: LogLevel, that: LogLevel): boolean
 } = Ord.isLessThan(Order)
@@ -523,7 +480,8 @@ export const isLessThan: {
  * 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
+ * **Example** (Filtering by maximum log level)
+ *
  * ```ts
  * import { Logger, LogLevel } from "effect"
  *
@@ -551,8 +509,8 @@ export const isLessThan: {
  * const shouldLog = isInfoOrBelow("Debug") // true
  * ```
  *
- * @since 2.0.0
  * @category ordering
+ * @since 4.0.0
  */
 export const isLessThanOrEqualTo: {
   /**
@@ -561,7 +519,8 @@ export const isLessThanOrEqualTo: {
    * 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
+   * **Example** (Filtering by maximum log level)
+   *
    * ```ts
    * import { Logger, LogLevel } from "effect"
    *
@@ -589,8 +548,8 @@ export const isLessThanOrEqualTo: {
    * const shouldLog = isInfoOrBelow("Debug") // true
    * ```
    *
-   * @since 2.0.0
    * @category ordering
+   * @since 4.0.0
    */
   (that: LogLevel): (self: LogLevel) => boolean
   /**
@@ -599,7 +558,8 @@ export const isLessThanOrEqualTo: {
    * 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
+   * **Example** (Filtering by maximum log level)
+   *
    * ```ts
    * import { Logger, LogLevel } from "effect"
    *
@@ -627,8 +587,8 @@ export const isLessThanOrEqualTo: {
    * const shouldLog = isInfoOrBelow("Debug") // true
    * ```
    *
-   * @since 2.0.0
    * @category ordering
+   * @since 4.0.0
    */
   (self: LogLevel, that: LogLevel): boolean
 } = Ord.isLessThanOrEqualTo(Order)
@@ -639,7 +599,8 @@ export const isLessThanOrEqualTo: {
  * A log level is enabled when it is greater than or equal to
  * `References.MinimumLogLevel`.
  *
- * @example
+ * **Example** (Checking current fiber log level)
+ *
  * ```ts
  * import { Effect, LogLevel, References } from "effect"
  *
@@ -655,8 +616,8 @@ export const isLessThanOrEqualTo: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category filtering
+ * @since 4.0.0
  */
 export const isEnabled = (self: LogLevel): Effect.Effect<boolean> =>
   core.withFiber((fiber) => effect.succeed(!isGreaterThan(fiber.getRef(References.MinimumLogLevel), self)))