effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Context.d.ts

@@ -1,12 +1,51 @@
 /**
- * This module provides a data structure called `Context` that can be used
- * for dependency injection in effectful programs. It is essentially a table
- * mapping `Service`s identifiers to their implementations, and can be used to
- * manage dependencies in a type-safe way. The `Context` data structure is
- * essentially a way of providing access to a set of related services that can
- * be passed around as a single unit. This module provides functions to create,
- * modify, and query the contents of a `Context`, as well as a number of
- * utility types for working with a `Context`.
+ * The `Context` module implements Effect's typed service environment. A
+ * `Context<Services>` is an immutable collection of service implementations,
+ * keyed by `Context.Service` or `Context.Reference` values. The type parameter
+ * records which service identifiers are present so effects can require
+ * dependencies without passing every implementation as an argument.
+ *
+ * **Mental model**
+ *
+ * - A service key is both a runtime identifier and a typed handle for one
+ *   dependency
+ * - `Context.Service` creates keys for dependencies that must be provided by
+ *   the surrounding context
+ * - `Context.Reference` creates keys that have a cached default value when no
+ *   explicit implementation is stored
+ * - A `Context` value stores implementations, while Effect fibers carry the
+ *   active context used to satisfy service requirements
+ * - Context operations such as {@link add}, {@link merge}, {@link pick}, and
+ *   {@link omit} return new contexts instead of mutating the original one
+ *
+ * **Common tasks**
+ *
+ * - Create service keys: {@link Service}, {@link Reference}
+ * - Build contexts: {@link empty}, {@link make}, {@link add}, {@link merge}
+ * - Read services: {@link get}, {@link getOption}, {@link getOrElse}
+ * - Keep or remove selected services: {@link pick}, {@link omit}
+ *
+ * **Example** (Building and reading a context)
+ *
+ * ```ts
+ * import { Context } from "effect"
+ *
+ * const Logger = Context.Service<{ log: (message: string) => void }>("Logger")
+ *
+ * const context = Context.make(Logger, {
+ *   log: (message) => console.log(message)
+ * })
+ *
+ * const logger = Context.get(context, Logger)
+ * logger.log("started")
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - The service key string is the runtime identity; reusing the same string for
+ *   unrelated services makes them occupy the same slot
+ * - `Context.Reference` defaults are used only when no explicit value is stored
+ *   for that key
  *
  * @since 4.0.0
  */
@@ -21,7 +60,7 @@ import type * as Types from "./Types.ts";
  * String literal type used as the runtime type identifier for `Context`
  * service keys.
  *
- * @category Type Identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export type ServiceTypeId = "~effect/Context/Service";
@@ -29,13 +68,18 @@ export type ServiceTypeId = "~effect/Context/Service";
  * Runtime type identifier attached to `Context` service keys and used by
  * `isKey` to recognize them.
  *
- * @category Type Identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export declare const ServiceTypeId: ServiceTypeId;
 /**
  * Typed identifier for a service stored in a `Context`.
  *
+ * **When to use**
+ *
+ * Use as the typed handle for storing, retrieving, and requiring a specific
+ * service in a `Context`.
+ *
  * **Details**
  *
  * `Identifier` tracks the requirement in Effect types, while `Shape` is the
@@ -43,6 +87,9 @@ export declare const ServiceTypeId: ServiceTypeId;
  * so yielding it inside `Effect.gen` retrieves the service from the current
  * fiber context.
  *
+ * @see {@link Service} for creating required service keys
+ * @see {@link Reference} for creating service keys with default values
+ *
  * @category models
  * @since 4.0.0
  */
@@ -88,10 +135,17 @@ export interface Service<in out Identifier, in out Shape> extends Key<Identifier
 /**
  * Class-style service key produced by `Context.Service<Self, Shape>()("Id")`.
  *
+ * **When to use**
+ *
+ * Use when declaring a service as a class so the class value can serve as the
+ * `Context` key.
+ *
  * **Details**
  *
- * Use this shape when declaring services as classes. The class itself is the
- * Context key, and its string `key` identifies the service at runtime.
+ * The class itself is the `Context` key, and its string `key` identifies the
+ * service at runtime.
+ *
+ * @see {@link Service} for creating function-style keys or class-style service keys
  *
  * @category models
  * @since 4.0.0
@@ -123,6 +177,11 @@ export declare namespace ServiceClass {
 /**
  * Creates a `Context` service key.
  *
+ * **When to use**
+ *
+ * Use when a dependency must be provided by the surrounding context. Use
+ * `Reference` when a dependency should have a default value.
+ *
  * **Details**
  *
  * Call `Context.Service("Key")` for a function-style key, or use the two-stage
@@ -130,6 +189,12 @@ export declare namespace ServiceClass {
  * declarations. The returned key can be yielded as an Effect and passed to
  * `Context.make`, `Context.add`, and the Context getter functions.
  *
+ * **Gotchas**
+ *
+ * The string key is the runtime identity of the service. Reusing the same key
+ * string for unrelated services makes them occupy the same slot in a
+ * `Context`.
+ *
  * **Example** (Creating service keys)
  *
  * ```ts
@@ -152,6 +217,8 @@ export declare namespace ServiceClass {
  * const config = Context.make(Config, { port: 8080 })
  * ```
  *
+ * @see {@link Reference} for service keys with default values
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -159,6 +226,11 @@ export declare const Service: {
     /**
      * Creates a `Context` service key.
      *
+     * **When to use**
+     *
+     * Use when a dependency must be provided by the surrounding context. Use
+     * `Reference` when a dependency should have a default value.
+     *
      * **Details**
      *
      * Call `Context.Service("Key")` for a function-style key, or use the two-stage
@@ -166,6 +238,12 @@ export declare const Service: {
      * declarations. The returned key can be yielded as an Effect and passed to
      * `Context.make`, `Context.add`, and the Context getter functions.
      *
+     * **Gotchas**
+     *
+     * The string key is the runtime identity of the service. Reusing the same key
+     * string for unrelated services makes them occupy the same slot in a
+     * `Context`.
+     *
      * **Example** (Creating service keys)
      *
      * ```ts
@@ -188,6 +266,8 @@ export declare const Service: {
      * const config = Context.make(Config, { port: 8080 })
      * ```
      *
+     * @see {@link Reference} for service keys with default values
+     *
      * @category constructors
      * @since 4.0.0
      */
@@ -195,6 +275,11 @@ export declare const Service: {
     /**
      * Creates a `Context` service key.
      *
+     * **When to use**
+     *
+     * Use when a dependency must be provided by the surrounding context. Use
+     * `Reference` when a dependency should have a default value.
+     *
      * **Details**
      *
      * Call `Context.Service("Key")` for a function-style key, or use the two-stage
@@ -202,6 +287,12 @@ export declare const Service: {
      * declarations. The returned key can be yielded as an Effect and passed to
      * `Context.make`, `Context.add`, and the Context getter functions.
      *
+     * **Gotchas**
+     *
+     * The string key is the runtime identity of the service. Reusing the same key
+     * string for unrelated services makes them occupy the same slot in a
+     * `Context`.
+     *
      * **Example** (Creating service keys)
      *
      * ```ts
@@ -224,6 +315,8 @@ export declare const Service: {
      * const config = Context.make(Config, { port: 8080 })
      * ```
      *
+     * @see {@link Reference} for service keys with default values
+     *
      * @category constructors
      * @since 4.0.0
      */
@@ -235,6 +328,11 @@ export declare const Service: {
     /**
      * Creates a `Context` service key.
      *
+     * **When to use**
+     *
+     * Use when a dependency must be provided by the surrounding context. Use
+     * `Reference` when a dependency should have a default value.
+     *
      * **Details**
      *
      * Call `Context.Service("Key")` for a function-style key, or use the two-stage
@@ -242,6 +340,12 @@ export declare const Service: {
      * declarations. The returned key can be yielded as an Effect and passed to
      * `Context.make`, `Context.add`, and the Context getter functions.
      *
+     * **Gotchas**
+     *
+     * The string key is the runtime identity of the service. Reusing the same key
+     * string for unrelated services makes them occupy the same slot in a
+     * `Context`.
+     *
      * **Example** (Creating service keys)
      *
      * ```ts
@@ -264,6 +368,8 @@ export declare const Service: {
      * const config = Context.make(Config, { port: 8080 })
      * ```
      *
+     * @see {@link Reference} for service keys with default values
+     *
      * @category constructors
      * @since 4.0.0
      */
@@ -460,7 +566,22 @@ export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable
  */
 export declare const makeUnsafe: <Services = never>(mapUnsafe: ReadonlyMap<string, any>) => Context<Services>;
 /**
- * Checks if the provided argument is a `Context`.
+ * Checks whether the provided argument is a `Context`.
+ *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before passing it to APIs that require a
+ * `Context`.
+ *
+ * **Details**
+ *
+ * This checks the runtime `Context` marker and does not inspect which services
+ * the context contains.
+ *
+ * **Gotchas**
+ *
+ * This guard only proves that the value is a `Context`; it does not prove that
+ * any specific service is present.
  *
  * **Example** (Checking for contexts)
  *
@@ -471,12 +592,15 @@ export declare const makeUnsafe: <Services = never>(mapUnsafe: ReadonlyMap<strin
  * assert.strictEqual(Context.isContext(Context.empty()), true)
  * ```
  *
+ * @see {@link isKey} for checking service keys
+ * @see {@link isReference} for checking references with defaults
+ *
  * @category guards
  * @since 2.0.0
  */
 export declare const isContext: (u: unknown) => u is Context<never>;
 /**
- * Checks if the provided argument is a `Key`.
+ * Checks whether the provided argument is a `Key`.
  *
  * **Example** (Checking for keys)
  *
@@ -492,7 +616,7 @@ export declare const isContext: (u: unknown) => u is Context<never>;
  */
 export declare const isKey: (u: unknown) => u is Key<any, any>;
 /**
- * Checks if the provided argument is a `Reference`.
+ * Checks whether the provided argument is a `Reference`.
  *
  * **Example** (Checking for references)
  *
@@ -551,6 +675,16 @@ export declare const make: <I, S>(key: Key<I, S>, service: Types.NoInfer<S>) =>
 /**
  * Adds a service to a given `Context`.
  *
+ * **When to use**
+ *
+ * Use when you always have a service value to store. Use `addOrOmit`
+ * when the value is optional and a missing value should remove the service.
+ *
+ * **Details**
+ *
+ * If the context already contains the same service key, the new service
+ * replaces the previous one.
+ *
  * **Example** (Adding a service to a context)
  *
  * ```ts
@@ -571,13 +705,25 @@ export declare const make: <I, S>(key: Key<I, S>, service: Types.NoInfer<S>) =>
  * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
  * ```
  *
- * @category Adders
+ * @see {@link addOrOmit} for adding or removing a service from an `Option`
+ *
+ * @category adders
  * @since 2.0.0
  */
 export declare const add: {
     /**
      * Adds a service to a given `Context`.
      *
+     * **When to use**
+     *
+     * Use when you always have a service value to store. Use `addOrOmit`
+     * when the value is optional and a missing value should remove the service.
+     *
+     * **Details**
+     *
+     * If the context already contains the same service key, the new service
+     * replaces the previous one.
+     *
      * **Example** (Adding a service to a context)
      *
      * ```ts
@@ -598,13 +744,25 @@ export declare const add: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @category Adders
+     * @see {@link addOrOmit} for adding or removing a service from an `Option`
+     *
+     * @category adders
      * @since 2.0.0
      */
     <I, S>(key: Key<I, S>, service: Types.NoInfer<S>): <Services>(self: Context<Services>) => Context<Services | I>;
     /**
      * Adds a service to a given `Context`.
      *
+     * **When to use**
+     *
+     * Use when you always have a service value to store. Use `addOrOmit`
+     * when the value is optional and a missing value should remove the service.
+     *
+     * **Details**
+     *
+     * If the context already contains the same service key, the new service
+     * replaces the previous one.
+     *
      * **Example** (Adding a service to a context)
      *
      * ```ts
@@ -625,7 +783,9 @@ export declare const add: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @category Adders
+     * @see {@link addOrOmit} for adding or removing a service from an `Option`
+     *
+     * @category adders
      * @since 2.0.0
      */
     <Services, I, S>(self: Context<Services>, key: Key<I, S>, service: Types.NoInfer<S>): Context<Services | I>;
@@ -633,36 +793,105 @@ export declare const add: {
 /**
  * Adds or removes a service depending on an `Option`.
  *
+ * **When to use**
+ *
+ * Use when service presence is already represented as an `Option`.
+ * Use `add` when you always want to store a service value.
+ *
  * **Details**
  *
  * When `service` is `Option.some`, the value is stored for the key. When it is
  * `Option.none`, the key is removed from the returned `Context`.
  *
- * @category Adders
+ * **Example** (Adding optional services)
+ *
+ * ```ts
+ * import { Context, Option } from "effect"
+ *
+ * const Port = Context.Service<{ PORT: number }>("Port")
+ *
+ * const withPort = Context.empty().pipe(
+ *   Context.addOrOmit(Port, Option.some({ PORT: 8080 }))
+ * )
+ *
+ * const withoutPort = withPort.pipe(
+ *   Context.addOrOmit(Port, Option.none())
+ * )
+ * ```
+ *
+ * @see {@link add} for always storing a service value
+ *
+ * @category adders
  * @since 4.0.0
  */
 export declare const addOrOmit: {
     /**
      * Adds or removes a service depending on an `Option`.
      *
+     * **When to use**
+     *
+     * Use when service presence is already represented as an `Option`.
+     * Use `add` when you always want to store a service value.
+     *
      * **Details**
      *
      * When `service` is `Option.some`, the value is stored for the key. When it is
      * `Option.none`, the key is removed from the returned `Context`.
      *
-     * @category Adders
+     * **Example** (Adding optional services)
+     *
+     * ```ts
+     * import { Context, Option } from "effect"
+     *
+     * const Port = Context.Service<{ PORT: number }>("Port")
+     *
+     * const withPort = Context.empty().pipe(
+     *   Context.addOrOmit(Port, Option.some({ PORT: 8080 }))
+     * )
+     *
+     * const withoutPort = withPort.pipe(
+     *   Context.addOrOmit(Port, Option.none())
+     * )
+     * ```
+     *
+     * @see {@link add} for always storing a service value
+     *
+     * @category adders
      * @since 4.0.0
      */
     <I, S>(key: Key<I, S>, service: Option.Option<Types.NoInfer<S>>): <Services>(self: Context<Services>) => Context<Services | I>;
     /**
      * Adds or removes a service depending on an `Option`.
      *
+     * **When to use**
+     *
+     * Use when service presence is already represented as an `Option`.
+     * Use `add` when you always want to store a service value.
+     *
      * **Details**
      *
      * When `service` is `Option.some`, the value is stored for the key. When it is
      * `Option.none`, the key is removed from the returned `Context`.
      *
-     * @category Adders
+     * **Example** (Adding optional services)
+     *
+     * ```ts
+     * import { Context, Option } from "effect"
+     *
+     * const Port = Context.Service<{ PORT: number }>("Port")
+     *
+     * const withPort = Context.empty().pipe(
+     *   Context.addOrOmit(Port, Option.some({ PORT: 8080 }))
+     * )
+     *
+     * const withoutPort = withPort.pipe(
+     *   Context.addOrOmit(Port, Option.none())
+     * )
+     * ```
+     *
+     * @see {@link add} for always storing a service value
+     *
+     * @category adders
      * @since 4.0.0
      */
     <Services, I, S>(self: Context<Services>, key: Key<I, S>, service: Option.Option<Types.NoInfer<S>>): Context<Services | I>;
@@ -671,11 +900,21 @@ export declare const addOrOmit: {
  * Gets the service for a key, or evaluates the fallback when a non-reference
  * key is absent.
  *
+ * **When to use**
+ *
+ * Use when you want a fallback value for a missing regular
+ * service. Use `getOption` when you need to distinguish presence from absence.
+ *
  * **Details**
  *
  * If the key is a `Context.Reference` and no override is stored in the
  * context, its cached default value is returned instead of the fallback.
  *
+ * **Gotchas**
+ *
+ * The fallback is not evaluated for missing `Context.Reference` keys because
+ * references resolve to their default value.
+ *
  * **Example** (Falling back for missing services)
  *
  * ```ts
@@ -701,6 +940,8 @@ export declare const addOrOmit: {
  * console.log(database.query("SELECT 1")) // "fallback"
  * ```
  *
+ * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
+ *
  * @category getters
  * @since 3.7.0
  */
@@ -709,11 +950,21 @@ export declare const getOrElse: {
      * Gets the service for a key, or evaluates the fallback when a non-reference
      * key is absent.
      *
+     * **When to use**
+     *
+     * Use when you want a fallback value for a missing regular
+     * service. Use `getOption` when you need to distinguish presence from absence.
+     *
      * **Details**
      *
      * If the key is a `Context.Reference` and no override is stored in the
      * context, its cached default value is returned instead of the fallback.
      *
+     * **Gotchas**
+     *
+     * The fallback is not evaluated for missing `Context.Reference` keys because
+     * references resolve to their default value.
+     *
      * **Example** (Falling back for missing services)
      *
      * ```ts
@@ -739,6 +990,8 @@ export declare const getOrElse: {
      * console.log(database.query("SELECT 1")) // "fallback"
      * ```
      *
+     * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
+     *
      * @category getters
      * @since 3.7.0
      */
@@ -747,11 +1000,21 @@ export declare const getOrElse: {
      * Gets the service for a key, or evaluates the fallback when a non-reference
      * key is absent.
      *
+     * **When to use**
+     *
+     * Use when you want a fallback value for a missing regular
+     * service. Use `getOption` when you need to distinguish presence from absence.
+     *
      * **Details**
      *
      * If the key is a `Context.Reference` and no override is stored in the
      * context, its cached default value is returned instead of the fallback.
      *
+     * **Gotchas**
+     *
+     * The fallback is not evaluated for missing `Context.Reference` keys because
+     * references resolve to their default value.
+     *
      * **Example** (Falling back for missing services)
      *
      * ```ts
@@ -777,6 +1040,8 @@ export declare const getOrElse: {
      * console.log(database.query("SELECT 1")) // "fallback"
      * ```
      *
+     * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
+     *
      * @category getters
      * @since 3.7.0
      */
@@ -786,11 +1051,18 @@ export declare const getOrElse: {
  * Returns the service currently stored for a key, or `undefined` when the key
  * is absent.
  *
- * **Details**
+ * **When to use**
+ *
+ * Use when you need raw map-style lookup. Use `getOption` when you want the
+ * usual `Context.Reference` default-value behavior.
+ *
+ * **Gotchas**
  *
  * This is a raw lookup and does not resolve default values for
  * `Context.Reference` keys.
  *
+ * @see {@link getOption} for a reference-aware optional lookup
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -799,11 +1071,18 @@ export declare const getOrUndefined: {
      * Returns the service currently stored for a key, or `undefined` when the key
      * is absent.
      *
-     * **Details**
+     * **When to use**
+     *
+     * Use when you need raw map-style lookup. Use `getOption` when you want the
+     * usual `Context.Reference` default-value behavior.
+     *
+     * **Gotchas**
      *
      * This is a raw lookup and does not resolve default values for
      * `Context.Reference` keys.
      *
+     * @see {@link getOption} for a reference-aware optional lookup
+     *
      * @category getters
      * @since 4.0.0
      */
@@ -812,11 +1091,18 @@ export declare const getOrUndefined: {
      * Returns the service currently stored for a key, or `undefined` when the key
      * is absent.
      *
-     * **Details**
+     * **When to use**
+     *
+     * Use when you need raw map-style lookup. Use `getOption` when you want the
+     * usual `Context.Reference` default-value behavior.
+     *
+     * **Gotchas**
      *
      * This is a raw lookup and does not resolve default values for
      * `Context.Reference` keys.
      *
+     * @see {@link getOption} for a reference-aware optional lookup
+     *
      * @category getters
      * @since 4.0.0
      */
@@ -826,14 +1112,18 @@ export declare const getOrUndefined: {
  * Gets the service for a key, throwing if an absent non-reference key cannot be
  * resolved.
  *
+ * **When to use**
+ *
+ * Use when the context type cannot prove that the service is present. Use
+ * `get` when the service requirement is tracked in the context type, or
+ * `getOption` when absence is expected.
+ *
  * **Details**
  *
  * If the key is a `Context.Reference` and no override is stored in the
  * context, its cached default value is returned. For absent non-reference keys,
  * this function throws a runtime error.
  *
- * For a safer version see {@link getOption}.
- *
  * **Example** (Getting services unsafely)
  *
  * ```ts
@@ -849,6 +1139,9 @@ export declare const getOrUndefined: {
  * assert.throws(() => Context.getUnsafe(context, Timeout))
  * ```
  *
+ * @see {@link get} for type-checked service access
+ * @see {@link getOption} for optional service access
+ *
  * @category unsafe
  * @since 4.0.0
  */
@@ -857,14 +1150,18 @@ export declare const getUnsafe: {
      * Gets the service for a key, throwing if an absent non-reference key cannot be
      * resolved.
      *
+     * **When to use**
+     *
+     * Use when the context type cannot prove that the service is present. Use
+     * `get` when the service requirement is tracked in the context type, or
+     * `getOption` when absence is expected.
+     *
      * **Details**
      *
      * If the key is a `Context.Reference` and no override is stored in the
      * context, its cached default value is returned. For absent non-reference keys,
      * this function throws a runtime error.
      *
-     * For a safer version see {@link getOption}.
-     *
      * **Example** (Getting services unsafely)
      *
      * ```ts
@@ -880,6 +1177,9 @@ export declare const getUnsafe: {
      * assert.throws(() => Context.getUnsafe(context, Timeout))
      * ```
      *
+     * @see {@link get} for type-checked service access
+     * @see {@link getOption} for optional service access
+     *
      * @category unsafe
      * @since 4.0.0
      */
@@ -888,14 +1188,18 @@ export declare const getUnsafe: {
      * Gets the service for a key, throwing if an absent non-reference key cannot be
      * resolved.
      *
+     * **When to use**
+     *
+     * Use when the context type cannot prove that the service is present. Use
+     * `get` when the service requirement is tracked in the context type, or
+     * `getOption` when absence is expected.
+     *
      * **Details**
      *
      * If the key is a `Context.Reference` and no override is stored in the
      * context, its cached default value is returned. For absent non-reference keys,
      * this function throws a runtime error.
      *
-     * For a safer version see {@link getOption}.
-     *
      * **Example** (Getting services unsafely)
      *
      * ```ts
@@ -911,13 +1215,21 @@ export declare const getUnsafe: {
      * assert.throws(() => Context.getUnsafe(context, Timeout))
      * ```
      *
+     * @see {@link get} for type-checked service access
+     * @see {@link getOption} for optional service access
+     *
      * @category unsafe
      * @since 4.0.0
      */
     <Services, S, I>(self: Context<Services>, services: Key<I, S>): S;
 };
 /**
- * Get a service from the context that corresponds to the given key.
+ * Gets a service from the context that corresponds to the given key.
+ *
+ * **When to use**
+ *
+ * Use when the context type proves that the service is present. Use
+ * `getOption` or `getOrElse` when a service may be absent.
  *
  * **Example** (Getting a service from a context)
  *
@@ -936,12 +1248,20 @@ export declare const getUnsafe: {
  * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
  * ```
  *
+ * @see {@link getOption} for optional service access
+ * @see {@link getOrElse} for fallback values
+ *
  * @category getters
  * @since 2.0.0
  */
 export declare const get: {
     /**
-     * Get a service from the context that corresponds to the given key.
+     * Gets a service from the context that corresponds to the given key.
+     *
+     * **When to use**
+     *
+     * Use when the context type proves that the service is present. Use
+     * `getOption` or `getOrElse` when a service may be absent.
      *
      * **Example** (Getting a service from a context)
      *
@@ -960,12 +1280,20 @@ export declare const get: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
+     * @see {@link getOption} for optional service access
+     * @see {@link getOrElse} for fallback values
+     *
      * @category getters
      * @since 2.0.0
      */
     <Services, I extends Services, S>(service: Key<I, S>): (self: Context<Services>) => S;
     /**
-     * Get a service from the context that corresponds to the given key.
+     * Gets a service from the context that corresponds to the given key.
+     *
+     * **When to use**
+     *
+     * Use when the context type proves that the service is present. Use
+     * `getOption` or `getOrElse` when a service may be absent.
      *
      * **Example** (Getting a service from a context)
      *
@@ -984,6 +1312,9 @@ export declare const get: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
+     * @see {@link getOption} for optional service access
+     * @see {@link getOrElse} for fallback values
+     *
      * @category getters
      * @since 2.0.0
      */
@@ -993,6 +1324,21 @@ export declare const get: {
  * Gets the value for a `Context.Reference`, returning its cached default when
  * the context does not contain an override.
  *
+ * **When to use**
+ *
+ * Use to resolve a `Context.Reference` against a context when you want either
+ * the stored override or the reference's default value.
+ *
+ * **Details**
+ *
+ * Stored overrides take precedence. If no override is present, the reference's
+ * default value is computed lazily and cached on the reference itself.
+ *
+ * **Gotchas**
+ *
+ * Mutable default values can be shared across contexts unless an override is
+ * provided, because the default is cached on the `Context.Reference`.
+ *
  * **Example** (Getting reference defaults unsafely)
  *
  * ```ts
@@ -1008,12 +1354,21 @@ export declare const get: {
  * console.log(typeof logger.log) // "function"
  * ```
  *
+ * @see {@link getUnsafe} for unsafe access with any service key
+ * @see {@link get} for type-checked reference-aware access
+ * @see {@link getOption} for optional access to non-reference keys
+ *
  * @category unsafe
  * @since 4.0.0
  */
 export declare const getReferenceUnsafe: <Services, S>(self: Context<Services>, service: Reference<S>) => S;
 /**
- * Gets the service for a key wrapped in an `Option`.
+ * Gets the service for a key safely wrapped in an `Option`.
+ *
+ * **When to use**
+ *
+ * Use when service absence is expected and should be represented
+ * as data. Use `getOrElse` when you want to provide a fallback value directly.
  *
  * **Details**
  *
@@ -1039,12 +1394,19 @@ export declare const getReferenceUnsafe: <Services, S>(self: Context<Services>,
  * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
  * ```
  *
+ * @see {@link getOrElse} for returning a fallback value directly
+ *
  * @category getters
  * @since 2.0.0
  */
 export declare const getOption: {
     /**
-     * Gets the service for a key wrapped in an `Option`.
+     * Gets the service for a key safely wrapped in an `Option`.
+     *
+     * **When to use**
+     *
+     * Use when service absence is expected and should be represented
+     * as data. Use `getOrElse` when you want to provide a fallback value directly.
      *
      * **Details**
      *
@@ -1070,12 +1432,19 @@ export declare const getOption: {
      * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
      * ```
      *
+     * @see {@link getOrElse} for returning a fallback value directly
+     *
      * @category getters
      * @since 2.0.0
      */
     <S, I>(service: Key<I, S>): <Services>(self: Context<Services>) => Option.Option<S>;
     /**
-     * Gets the service for a key wrapped in an `Option`.
+     * Gets the service for a key safely wrapped in an `Option`.
+     *
+     * **When to use**
+     *
+     * Use when service absence is expected and should be represented
+     * as data. Use `getOrElse` when you want to provide a fallback value directly.
      *
      * **Details**
      *
@@ -1101,6 +1470,8 @@ export declare const getOption: {
      * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
      * ```
      *
+     * @see {@link getOrElse} for returning a fallback value directly
+     *
      * @category getters
      * @since 2.0.0
      */
@@ -1109,6 +1480,11 @@ export declare const getOption: {
 /**
  * Merges two `Context`s into one.
  *
+ * **When to use**
+ *
+ * Use when combining two contexts. Use `mergeAll` when combining a
+ * variadic list of contexts.
+ *
  * **Details**
  *
  * When both contexts contain the same service key, the service from `that`
@@ -1132,13 +1508,20 @@ export declare const getOption: {
  * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
  * ```
  *
- * @category Utils
+ * @see {@link mergeAll} for merging more than two contexts at once
+ *
+ * @category combining
  * @since 2.0.0
  */
 export declare const merge: {
     /**
      * Merges two `Context`s into one.
      *
+     * **When to use**
+     *
+     * Use when combining two contexts. Use `mergeAll` when combining a
+     * variadic list of contexts.
+     *
      * **Details**
      *
      * When both contexts contain the same service key, the service from `that`
@@ -1162,13 +1545,20 @@ export declare const merge: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @category Utils
+     * @see {@link mergeAll} for merging more than two contexts at once
+     *
+     * @category combining
      * @since 2.0.0
      */
     <R1>(that: Context<R1>): <Services>(self: Context<Services>) => Context<R1 | Services>;
     /**
      * Merges two `Context`s into one.
      *
+     * **When to use**
+     *
+     * Use when combining two contexts. Use `mergeAll` when combining a
+     * variadic list of contexts.
+     *
      * **Details**
      *
      * When both contexts contain the same service key, the service from `that`
@@ -1192,7 +1582,9 @@ export declare const merge: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @category Utils
+     * @see {@link mergeAll} for merging more than two contexts at once
+     *
+     * @category combining
      * @since 2.0.0
      */
     <Services, R1>(self: Context<Services>, that: Context<R1>): Context<Services | R1>;
@@ -1200,6 +1592,11 @@ export declare const merge: {
 /**
  * Merges any number of `Context`s into one.
  *
+ * **When to use**
+ *
+ * Use when the number of contexts is variadic. Use `merge` when
+ * combining exactly two contexts.
+ *
  * **Details**
  *
  * When multiple contexts contain the same service key, the service from the
@@ -1230,6 +1627,8 @@ export declare const merge: {
  * assert.deepStrictEqual(Context.get(context, Host), { HOST: "localhost" })
  * ```
  *
+ * @see {@link merge} for merging two contexts
+ *
  * @category combining
  * @since 3.12.0
  */
@@ -1237,6 +1636,11 @@ export declare const mergeAll: <T extends Array<unknown>>(...ctxs: [...{ [K in k
 /**
  * Returns a new `Context` that contains only the specified services.
  *
+ * **When to use**
+ *
+ * Use when you want to keep a small allowlist of services. Use `omit`
+ * when it is easier to name the services to remove.
+ *
  * **Example** (Picking services from a context)
  *
  * ```ts
@@ -1260,13 +1664,20 @@ export declare const mergeAll: <T extends Array<unknown>>(...ctxs: [...{ [K in k
  * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
  * ```
  *
- * @category Utils
+ * @see {@link omit} for removing selected services
+ *
+ * @category filtering
  * @since 2.0.0
  */
 export declare const pick: <S extends ReadonlyArray<Key<any, any>>>(...services: S) => <Services>(self: Context<Services>) => Context<Services & Service.Identifier<S[number]>>;
 /**
  * Returns a new `Context` with the specified service keys removed.
  *
+ * **When to use**
+ *
+ * Use when you want to remove a small denylist of services. Use `pick`
+ * when it is easier to name the services to keep.
+ *
  * **Example** (Omitting services from a context)
  *
  * ```ts
@@ -1290,31 +1701,66 @@ export declare const pick: <S extends ReadonlyArray<Key<any, any>>>(...services:
  * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
  * ```
  *
- * @category Utils
+ * @see {@link pick} for keeping selected services
+ *
+ * @category filtering
  * @since 2.0.0
  */
 export declare const omit: <S extends ReadonlyArray<Key<any, any>>>(...keys: S) => <Services>(self: Context<Services>) => Context<Exclude<Services, Service.Identifier<S[number]>>>;
 /**
- * Perform a series of mutations on a `Context`. Prevents unnecessary copying
+ * Performs a series of mutations on a `Context`. Prevents unnecessary copying
  * of the underlying map when multiple mutations are needed.
  *
- * @category Utils
+ * **When to use**
+ *
+ * Use to apply several `Context` transformations in one callback while copying
+ * the underlying service map only once.
+ *
+ * @see {@link add} for adding or replacing a service
+ * @see {@link addOrOmit} for adding or removing a service from an `Option`
+ * @see {@link merge} for combining two contexts
+ * @see {@link pick} for keeping selected services
+ * @see {@link omit} for removing selected services
+ *
+ * @category utils
  * @since 4.0.0
  */
 export declare const mutate: {
     /**
-     * Perform a series of mutations on a `Context`. Prevents unnecessary copying
+     * Performs a series of mutations on a `Context`. Prevents unnecessary copying
      * of the underlying map when multiple mutations are needed.
      *
-     * @category Utils
+     * **When to use**
+     *
+     * Use to apply several `Context` transformations in one callback while copying
+     * the underlying service map only once.
+     *
+     * @see {@link add} for adding or replacing a service
+     * @see {@link addOrOmit} for adding or removing a service from an `Option`
+     * @see {@link merge} for combining two contexts
+     * @see {@link pick} for keeping selected services
+     * @see {@link omit} for removing selected services
+     *
+     * @category utils
      * @since 4.0.0
      */
     <Services, B>(f: (context: Context<Services>) => Context<B>): <Services>(self: Context<Services>) => Context<B>;
     /**
-     * Perform a series of mutations on a `Context`. Prevents unnecessary copying
+     * Performs a series of mutations on a `Context`. Prevents unnecessary copying
      * of the underlying map when multiple mutations are needed.
      *
-     * @category Utils
+     * **When to use**
+     *
+     * Use to apply several `Context` transformations in one callback while copying
+     * the underlying service map only once.
+     *
+     * @see {@link add} for adding or replacing a service
+     * @see {@link addOrOmit} for adding or removing a service from an `Option`
+     * @see {@link merge} for combining two contexts
+     * @see {@link pick} for keeping selected services
+     * @see {@link omit} for removing selected services
+     *
+     * @category utils
      * @since 4.0.0
      */
     <Services, B>(self: Context<Services>, f: (context: Context<Services>) => Context<B>): Context<B>;
@@ -1322,12 +1768,19 @@ export declare const mutate: {
 /**
  * Creates a context key with a default value.
  *
+ * **When to use**
+ *
+ * Use when a service should be available even if it is not
+ * explicitly stored in the `Context`. Use `Service` when the service must be
+ * provided by the surrounding context.
+ *
  * **Details**
  *
  * `Context.Reference` allows you to create a key that can hold a value. You
  * can provide a default value for the service, which will automatically be used
  * when the context is accessed, or override it with a custom implementation
- * when needed.
+ * when needed. The default value is computed lazily and cached on the
+ * reference.
  *
  * **Example** (Creating references with default values)
  *
@@ -1350,6 +1803,8 @@ export declare const mutate: {
  * const customLogger = Context.get(customContext, LoggerRef)
  * ```
  *
+ * @see {@link Service} for required services without default values
+ *
  * @category references
  * @since 3.11.0
  */