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

package/src/Context.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
  */
@@ -27,7 +66,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"
@@ -36,7 +75,7 @@ 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 const ServiceTypeId: ServiceTypeId = "~effect/Context/Service"
@@ -44,6 +83,11 @@ export const ServiceTypeId: ServiceTypeId = "~effect/Context/Service"
 /**
  * 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
@@ -51,6 +95,9 @@ export const ServiceTypeId: ServiceTypeId = "~effect/Context/Service"
  * 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
  */
@@ -98,10 +145,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
@@ -137,6 +191,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
@@ -144,6 +203,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
@@ -166,6 +231,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
  */
@@ -173,6 +240,11 @@ export 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
@@ -180,6 +252,12 @@ export 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
@@ -202,6 +280,8 @@ export const Service: {
    * const config = Context.make(Config, { port: 8080 })
    * ```
    *
+   * @see {@link Reference} for service keys with default values
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -209,6 +289,11 @@ export 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
@@ -216,6 +301,12 @@ export 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
@@ -238,6 +329,8 @@ export const Service: {
    * const config = Context.make(Config, { port: 8080 })
    * ```
    *
+   * @see {@link Reference} for service keys with default values
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -258,6 +351,11 @@ export 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
@@ -265,6 +363,12 @@ export 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
@@ -287,6 +391,8 @@ export const Service: {
    * const config = Context.make(Config, { port: 8080 })
    * ```
    *
+   * @see {@link Reference} for service keys with default values
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -604,7 +710,22 @@ const Proto: Omit<Context<never>, "mapUnsafe" | "mutable"> = {
 }
 
 /**
- * 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)
  *
@@ -615,13 +736,16 @@ const Proto: Omit<Context<never>, "mapUnsafe" | "mutable"> = {
  * 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 const isContext = (u: unknown): u is Context<never> => hasProperty(u, TypeId)
 
 /**
- * Checks if the provided argument is a `Key`.
+ * Checks whether the provided argument is a `Key`.
  *
  * **Example** (Checking for keys)
  *
@@ -638,7 +762,7 @@ export const isContext = (u: unknown): u is Context<never> => hasProperty(u, Typ
 export const isKey = (u: unknown): u is Key<any, any> => hasProperty(u, ServiceTypeId)
 
 /**
- * Checks if the provided argument is a `Reference`.
+ * Checks whether the provided argument is a `Reference`.
  *
  * **Example** (Checking for references)
  *
@@ -704,6 +828,16 @@ export const make = <I, 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
@@ -724,13 +858,25 @@ export const make = <I, 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 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
@@ -751,13 +897,25 @@ export 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
@@ -778,7 +936,9 @@ export 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>
@@ -794,36 +954,105 @@ export 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 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>(
@@ -848,11 +1077,21 @@ export 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
@@ -878,6 +1117,8 @@ export 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
  */
@@ -886,11 +1127,21 @@ export 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
@@ -916,6 +1167,8 @@ export 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
    */
@@ -924,11 +1177,21 @@ export 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
@@ -954,6 +1217,8 @@ export 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
    */
@@ -969,11 +1234,18 @@ export 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
  */
@@ -982,11 +1254,18 @@ export 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
    */
@@ -995,11 +1274,18 @@ export 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
    */
@@ -1013,14 +1299,18 @@ export 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
@@ -1036,6 +1326,9 @@ export 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
  */
@@ -1044,14 +1337,18 @@ export 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
@@ -1067,6 +1364,9 @@ export 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
    */
@@ -1075,14 +1375,18 @@ export 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
@@ -1098,6 +1402,9 @@ export 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
    */
@@ -1114,7 +1421,12 @@ export const getUnsafe: {
 )
 
 /**
- * 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)
  *
@@ -1133,12 +1445,20 @@ export 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 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)
    *
@@ -1157,12 +1477,20 @@ export 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)
    *
@@ -1181,6 +1509,9 @@ export 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
    */
@@ -1191,6 +1522,21 @@ export 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
@@ -1206,6 +1552,10 @@ export 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
  */
@@ -1247,7 +1597,12 @@ const serviceNotFoundError = (service: Key<any, any>) => {
 }
 
 /**
- * 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**
  *
@@ -1273,12 +1628,19 @@ const serviceNotFoundError = (service: Key<any, any>) => {
  * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
  * ```
  *
+ * @see {@link getOrElse} for returning a fallback value directly
+ *
  * @category getters
  * @since 2.0.0
  */
 export 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**
    *
@@ -1304,12 +1666,19 @@ export 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**
    *
@@ -1335,6 +1704,8 @@ export 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
    */
@@ -1349,6 +1720,11 @@ export 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`
@@ -1372,13 +1748,20 @@ export 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 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`
@@ -1402,13 +1785,20 @@ export 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`
@@ -1432,7 +1822,9 @@ export 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>
@@ -1447,6 +1839,11 @@ export 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
@@ -1477,6 +1874,8 @@ export const merge: {
  * assert.deepStrictEqual(Context.get(context, Host), { HOST: "localhost" })
  * ```
  *
+ * @see {@link merge} for merging two contexts
+ *
  * @category combining
  * @since 3.12.0
  */
@@ -1495,6 +1894,11 @@ export const mergeAll = <T extends Array<unknown>>(
 /**
  * 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
@@ -1518,7 +1922,9 @@ export const mergeAll = <T extends Array<unknown>>(
  * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
  * ```
  *
- * @category Utils
+ * @see {@link omit} for removing selected services
+ *
+ * @category filtering
  * @since 2.0.0
  */
 export const pick = <S extends ReadonlyArray<Key<any, any>>>(
@@ -1536,6 +1942,11 @@ export const pick = <S extends ReadonlyArray<Key<any, any>>>(
 /**
  * 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
@@ -1559,7 +1970,9 @@ export const pick = <S extends ReadonlyArray<Key<any, any>>>(
  * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
  * ```
  *
- * @category Utils
+ * @see {@link pick} for keeping selected services
+ *
+ * @category filtering
  * @since 2.0.0
  */
 export const omit = <S extends ReadonlyArray<Key<any, any>>>(
@@ -1573,26 +1986,59 @@ export const omit = <S extends ReadonlyArray<Key<any, any>>>(
   })
 
 /**
- * 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 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>
@@ -1600,10 +2046,21 @@ export const mutate: {
   2,
   <Services, B>(self: Context<Services>, f: (context: Context<Services>) => Context<B>): Context<B> => {
     const next = makeUnsafe</**
-     * 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>(new Map(self.mapUnsafe))
@@ -1627,12 +2084,19 @@ const withMapUnsafe = <Services, B>(self: Context<Services>, f: (map: Map<string
 /**
  * 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)
  *
@@ -1655,6 +2119,8 @@ const withMapUnsafe = <Services, B>(self: Context<Services>, f: (map: Map<string
  * const customLogger = Context.get(customContext, LoggerRef)
  * ```
  *
+ * @see {@link Service} for required services without default values
+ *
  * @category references
  * @since 3.11.0
  */