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

package/dist/Context.d.ts

@@ -18,20 +18,33 @@ import * as Option from "./Option.ts";
 import type { Pipeable } from "./Pipeable.ts";
 import type * as Types from "./Types.ts";
 /**
- * @since 4.0.0
+ * String literal type used as the runtime type identifier for `Context`
+ * service keys.
+ *
  * @category Type Identifiers
+ * @since 4.0.0
  */
 export type ServiceTypeId = "~effect/Context/Service";
 /**
- * @since 4.0.0
+ * Runtime type identifier attached to `Context` service keys and used by
+ * `isKey` to recognize them.
+ *
  * @category Type Identifiers
+ * @since 4.0.0
  */
 export declare const ServiceTypeId: ServiceTypeId;
 /**
- * The base type used for all Context keys.
+ * Typed identifier for a service stored in a `Context`.
  *
+ * **Details**
+ *
+ * `Identifier` tracks the requirement in Effect types, while `Shape` is the
+ * service implementation retrieved by the key. A key is also an Effect value,
+ * so yielding it inside `Effect.gen` retrieves the service from the current
+ * fiber context.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Key<out Identifier, out Shape> extends Effect<Shape, never, Identifier> {
     readonly [ServiceTypeId]: ServiceTypeId;
@@ -41,7 +54,16 @@ export interface Key<out Identifier, out Shape> extends Effect<Shape, never, Ide
     readonly stack?: string | undefined;
 }
 /**
- * @example
+ * Context key with helper methods for working with a service.
+ *
+ * **Details**
+ *
+ * `context` creates a one-service `Context`, `use` and `useSync` retrieve the
+ * service from the current Effect context before applying a function, and `of`
+ * is a type-level helper for service values.
+ *
+ * **Example** (Defining a service key)
+ *
  * ```ts
  * import { Context } from "effect"
  *
@@ -54,8 +76,8 @@ export interface Key<out Identifier, out Shape> extends Effect<Shape, never, Ide
  * const context = Context.make(Database, { query: (sql) => `Result: ${sql}` })
  * ```
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Service<in out Identifier, in out Shape> extends Key<Identifier, Shape> {
     of(this: void, self: Shape): Shape;
@@ -64,21 +86,33 @@ export interface Service<in out Identifier, in out Shape> extends Key<Identifier
     useSync<A>(f: (service: Shape) => A): Effect<A, never, Identifier>;
 }
 /**
+ * Class-style service key produced by `Context.Service<Self, Shape>()("Id")`.
+ *
+ * **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.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface ServiceClass<in out Self, in out Identifier extends string, in out Shape> extends Service<Self, Shape> {
     new (_: never): ServiceClass.Shape<Identifier, Shape>;
     readonly key: Identifier;
 }
 /**
+ * Namespace containing helper types for class-style `Context.Service`
+ * declarations.
+ *
  * @since 4.0.0
- * @category Models
  */
 export declare namespace ServiceClass {
     /**
+     * Runtime and type-level metadata carried by a class-style service key,
+     * including its service type identifier, string key, and service shape.
+     *
+     * @category models
      * @since 4.0.0
-     * @category Models
      */
     interface Shape<Identifier extends string, Service> {
         readonly [ServiceTypeId]: typeof ServiceTypeId;
@@ -87,7 +121,17 @@ export declare namespace ServiceClass {
     }
 }
 /**
- * @example
+ * Creates a `Context` service key.
+ *
+ * **Details**
+ *
+ * Call `Context.Service("Key")` for a function-style key, or use the two-stage
+ * form `Context.Service<Self, Shape>()("Key")` for class-style service
+ * declarations. The returned key can be yielded as an Effect and passed to
+ * `Context.make`, `Context.add`, and the Context getter functions.
+ *
+ * **Example** (Creating service keys)
+ *
  * ```ts
  * import { Context } from "effect"
  *
@@ -108,12 +152,22 @@ export declare namespace ServiceClass {
  * const config = Context.make(Config, { port: 8080 })
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const Service: {
     /**
-     * @example
+     * Creates a `Context` service key.
+     *
+     * **Details**
+     *
+     * Call `Context.Service("Key")` for a function-style key, or use the two-stage
+     * form `Context.Service<Self, Shape>()("Key")` for class-style service
+     * declarations. The returned key can be yielded as an Effect and passed to
+     * `Context.make`, `Context.add`, and the Context getter functions.
+     *
+     * **Example** (Creating service keys)
+     *
      * ```ts
      * import { Context } from "effect"
      *
@@ -134,12 +188,22 @@ export declare const Service: {
      * const config = Context.make(Config, { port: 8080 })
      * ```
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <Identifier, Shape = Identifier>(key: string): Service<Identifier, Shape>;
     /**
-     * @example
+     * Creates a `Context` service key.
+     *
+     * **Details**
+     *
+     * Call `Context.Service("Key")` for a function-style key, or use the two-stage
+     * form `Context.Service<Self, Shape>()("Key")` for class-style service
+     * declarations. The returned key can be yielded as an Effect and passed to
+     * `Context.make`, `Context.add`, and the Context getter functions.
+     *
+     * **Example** (Creating service keys)
+     *
      * ```ts
      * import { Context } from "effect"
      *
@@ -160,8 +224,8 @@ export declare const Service: {
      * const config = Context.make(Config, { port: 8080 })
      * ```
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <Self, Shape>(): <const Identifier extends string, E, R = Types.unassigned, Args extends ReadonlyArray<any> = never>(id: Identifier, options?: {
         readonly make: ((...args: Args) => Effect<Shape, E, R>) | Effect<Shape, E, R> | undefined;
@@ -169,7 +233,17 @@ export declare const Service: {
         readonly make: [Args] extends [never] ? Effect<Shape, E, R> : (...args: Args) => Effect<Shape, E, R>;
     });
     /**
-     * @example
+     * Creates a `Context` service key.
+     *
+     * **Details**
+     *
+     * Call `Context.Service("Key")` for a function-style key, or use the two-stage
+     * form `Context.Service<Self, Shape>()("Key")` for class-style service
+     * declarations. The returned key can be yielded as an Effect and passed to
+     * `Context.make`, `Context.add`, and the Context getter functions.
+     *
+     * **Example** (Creating service keys)
+     *
      * ```ts
      * import { Context } from "effect"
      *
@@ -190,8 +264,8 @@ export declare const Service: {
      * const config = Context.make(Config, { port: 8080 })
      * ```
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <Self>(): <const Identifier extends string, Make extends Effect<any, any, any> | ((...args: any) => Effect<any, any, any>)>(id: Identifier, options: {
         readonly make: Make;
@@ -201,7 +275,16 @@ export declare const Service: {
 };
 declare const ReferenceTypeId: "~effect/Context/Reference";
 /**
- * @example
+ * Service key with a lazily computed default value.
+ *
+ * **Details**
+ *
+ * When a `Reference` is requested from a `Context` that does not contain an
+ * override, Context getters that resolve references return the cached default
+ * value instead of failing.
+ *
+ * **Example** (Defining a reference with a default value)
+ *
  * ```ts
  * import { Context } from "effect"
  *
@@ -216,8 +299,8 @@ declare const ReferenceTypeId: "~effect/Context/Reference";
  * const logger = Context.get(context, LoggerRef) // Uses default value
  * ```
  *
- * @since 4.0.0
- * @category Models
+ * @category models
+ * @since 3.11.0
  */
 export interface Reference<in out Shape> extends Service<never, Shape> {
     readonly [ReferenceTypeId]: typeof ReferenceTypeId;
@@ -226,7 +309,10 @@ export interface Reference<in out Shape> extends Service<never, Shape> {
     new (_: never): {};
 }
 /**
- * @example
+ * Namespace containing utility types for `Context` service keys.
+ *
+ * **Example** (Extracting service types)
+ *
  * ```ts
  * import { Context } from "effect"
  *
@@ -241,12 +327,15 @@ export interface Reference<in out Shape> extends Service<never, Shape> {
  * type DatabaseId = Context.Service.Identifier<typeof Database>
  * ```
  *
- * @since 4.0.0
- * @category Models
+ * @since 2.0.0
  */
 export declare namespace Service {
     /**
-     * @example
+     * Type that matches any `Context` service key regardless of its identifier or
+     * service shape.
+     *
+     * **Example** (Typing any service key)
+     *
      * ```ts
      * import { Context } from "effect"
      *
@@ -257,12 +346,16 @@ export declare namespace Service {
      * ]
      * ```
      *
+     * @category models
      * @since 4.0.0
-     * @category Models
      */
     type Any = Key<never, any> | Key<any, any>;
     /**
-     * @example
+     * Extracts the service implementation type stored behind a `Context` service
+     * key.
+     *
+     * **Example** (Extracting a service shape)
+     *
      * ```ts
      * import { Context } from "effect"
      *
@@ -275,12 +368,16 @@ export declare namespace Service {
      * // DatabaseService is { query: (sql: string) => string }
      * ```
      *
+     * @category models
      * @since 4.0.0
-     * @category Models
      */
     type Shape<T> = T extends Key<infer _I, infer S> ? S : never;
     /**
-     * @example
+     * Extracts the identifier, or requirement type, associated with a `Context`
+     * service key.
+     *
+     * **Example** (Extracting a service identifier)
+     *
      * ```ts
      * import { Context } from "effect"
      *
@@ -293,14 +390,23 @@ export declare namespace Service {
      * // DatabaseId is the identifier type
      * ```
      *
-     * @since 4.0.0
-     * @category Models
+     * @category models
+     * @since 2.0.0
      */
     type Identifier<T> = T extends Key<infer I, infer _S> ? I : never;
 }
 declare const TypeId: "~effect/Context";
 /**
- * @example
+ * Immutable collection of service implementations used for dependency
+ * injection in Effect programs.
+ *
+ * **Details**
+ *
+ * The type parameter tracks the service identifiers available in the context.
+ * At runtime, services are stored by each key's string `key`.
+ *
+ * **Example** (Creating a context with multiple services)
+ *
  * ```ts
  * import { Context } from "effect"
  *
@@ -316,8 +422,8 @@ declare const TypeId: "~effect/Context";
  *   .pipe(Context.add(Database, { query: (sql) => `Result: ${sql}` }))
  * ```
  *
- * @since 4.0.0
- * @category Models
+ * @category models
+ * @since 2.0.0
  */
 export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable {
     readonly [TypeId]: {
@@ -327,7 +433,17 @@ export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable
     mutable: boolean;
 }
 /**
- * @example
+ * Creates a `Context` from an existing service map without validating or
+ * copying it.
+ *
+ * **Notes**
+ *
+ * This is unsafe because later mutation of the provided map can affect the
+ * created `Context`. Prefer `empty`, `make`, `add`, or `merge` for normal
+ * Context construction.
+ *
+ * **Example** (Creating a context from a map)
+ *
  * ```ts
  * import { Context } from "effect"
  *
@@ -339,14 +455,15 @@ export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable
  * const context = Context.makeUnsafe(map)
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const makeUnsafe: <Services = never>(mapUnsafe: ReadonlyMap<string, any>) => Context<Services>;
 /**
  * Checks if the provided argument is a `Context`.
  *
- * @example
+ * **Example** (Checking for contexts)
+ *
  * ```ts
  * import { Context } from "effect"
  * import * as assert from "node:assert"
@@ -354,14 +471,15 @@ export declare const makeUnsafe: <Services = never>(mapUnsafe: ReadonlyMap<strin
  * assert.strictEqual(Context.isContext(Context.empty()), true)
  * ```
  *
- * @since 4.0.0
- * @category Guards
+ * @category guards
+ * @since 2.0.0
  */
 export declare const isContext: (u: unknown) => u is Context<never>;
 /**
  * Checks if the provided argument is a `Key`.
  *
- * @example
+ * **Example** (Checking for keys)
+ *
  * ```ts
  * import { Context } from "effect"
  * import * as assert from "node:assert"
@@ -369,14 +487,15 @@ export declare const isContext: (u: unknown) => u is Context<never>;
  * assert.strictEqual(Context.isKey(Context.Service("Service")), true)
  * ```
  *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export declare const isKey: (u: unknown) => u is Key<any, any>;
 /**
  * Checks if the provided argument is a `Reference`.
  *
- * @example
+ * **Example** (Checking for references)
+ *
  * ```ts
  * import { Context } from "effect"
  * import * as assert from "node:assert"
@@ -389,14 +508,15 @@ export declare const isKey: (u: unknown) => u is Key<any, any>;
  * assert.strictEqual(Context.isReference(Context.Service("Key")), false)
  * ```
  *
- * @since 4.0.0
- * @category Guards
+ * @category guards
+ * @since 3.11.0
  */
 export declare const isReference: (u: unknown) => u is Reference<any>;
 /**
  * Returns an empty `Context`.
  *
- * @example
+ * **Example** (Creating an empty context)
+ *
  * ```ts
  * import { Context } from "effect"
  * import * as assert from "node:assert"
@@ -404,14 +524,15 @@ export declare const isReference: (u: unknown) => u is Reference<any>;
  * assert.strictEqual(Context.isContext(Context.empty()), true)
  * ```
  *
- * @since 4.0.0
- * @category Constructors
+ * @category constructors
+ * @since 2.0.0
  */
 export declare const empty: () => Context<never>;
 /**
  * Creates a new `Context` with a single service associated to the key.
  *
- * @example
+ * **Example** (Creating a context with one service)
+ *
  * ```ts
  * import { Context } from "effect"
  * import * as assert from "node:assert"
@@ -423,16 +544,17 @@ export declare const empty: () => Context<never>;
  * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
  * ```
  *
- * @since 4.0.0
- * @category Constructors
+ * @category constructors
+ * @since 2.0.0
  */
 export declare const make: <I, S>(key: Key<I, S>, service: Types.NoInfer<S>) => Context<I>;
 /**
  * Adds a service to a given `Context`.
  *
- * @example
+ * **Example** (Adding a service to a context)
+ *
  * ```ts
- * import { pipe, Context } from "effect"
+ * import { Context, pipe } from "effect"
  * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
@@ -449,16 +571,17 @@ export declare const make: <I, S>(key: Key<I, S>, service: Types.NoInfer<S>) =>
  * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
  * ```
  *
- * @since 4.0.0
  * @category Adders
+ * @since 2.0.0
  */
 export declare const add: {
     /**
      * Adds a service to a given `Context`.
      *
-     * @example
+     * **Example** (Adding a service to a context)
+     *
      * ```ts
-     * import { pipe, Context } from "effect"
+     * import { Context, pipe } from "effect"
      * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
@@ -475,16 +598,17 @@ export declare const add: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @since 4.0.0
      * @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`.
      *
-     * @example
+     * **Example** (Adding a service to a context)
+     *
      * ```ts
-     * import { pipe, Context } from "effect"
+     * import { Context, pipe } from "effect"
      * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
@@ -501,35 +625,61 @@ export declare const add: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @since 4.0.0
      * @category Adders
+     * @since 2.0.0
      */
     <Services, I, S>(self: Context<Services>, key: Key<I, S>, service: Types.NoInfer<S>): Context<Services | I>;
 };
 /**
- * @since 4.0.0
+ * Adds or removes a service depending on an `Option`.
+ *
+ * **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
+ * @since 4.0.0
  */
 export declare const addOrOmit: {
     /**
-     * @since 4.0.0
+     * Adds or removes a service depending on an `Option`.
+     *
+     * **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
+     * @since 4.0.0
      */
     <I, S>(key: Key<I, S>, service: Option.Option<Types.NoInfer<S>>): <Services>(self: Context<Services>) => Context<Services | I>;
     /**
-     * @since 4.0.0
+     * Adds or removes a service depending on an `Option`.
+     *
+     * **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
+     * @since 4.0.0
      */
     <Services, I, S>(self: Context<Services>, key: Key<I, S>, service: Option.Option<Types.NoInfer<S>>): Context<Services | I>;
 };
 /**
- * Get a service from the context that corresponds to the given key, or
- * use the fallback value.
+ * Gets the service for a key, or evaluates the fallback when a non-reference
+ * key is absent.
+ *
+ * **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.
+ *
+ * **Example** (Falling back for missing services)
  *
- * @example
  * ```ts
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
  * const Database = Context.Service<{ query: (sql: string) => string }>(
@@ -547,22 +697,27 @@ export declare const addOrOmit: {
  *   () => ({ query: () => "fallback" })
  * )
  *
- * assert.deepStrictEqual(logger, { log: (msg: string) => console.log(msg) })
- * assert.deepStrictEqual(database, { query: () => "fallback" })
+ * console.log(logger === Context.get(context, Logger)) // true
+ * console.log(database.query("SELECT 1")) // "fallback"
  * ```
  *
- * @since 4.0.0
- * @category Getters
+ * @category getters
+ * @since 3.7.0
  */
 export declare const getOrElse: {
     /**
-     * Get a service from the context that corresponds to the given key, or
-     * use the fallback value.
+     * Gets the service for a key, or evaluates the fallback when a non-reference
+     * key is absent.
+     *
+     * **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.
+     *
+     * **Example** (Falling back for missing services)
      *
-     * @example
      * ```ts
      * import { Context } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
      * const Database = Context.Service<{ query: (sql: string) => string }>(
@@ -580,22 +735,27 @@ export declare const getOrElse: {
      *   () => ({ query: () => "fallback" })
      * )
      *
-     * assert.deepStrictEqual(logger, { log: (msg: string) => console.log(msg) })
-     * assert.deepStrictEqual(database, { query: () => "fallback" })
+     * console.log(logger === Context.get(context, Logger)) // true
+     * console.log(database.query("SELECT 1")) // "fallback"
      * ```
      *
-     * @since 4.0.0
-     * @category Getters
+     * @category getters
+     * @since 3.7.0
      */
     <S, I, B>(key: Key<I, S>, orElse: LazyArg<B>): <Services>(self: Context<Services>) => S | B;
     /**
-     * Get a service from the context that corresponds to the given key, or
-     * use the fallback value.
+     * Gets the service for a key, or evaluates the fallback when a non-reference
+     * key is absent.
+     *
+     * **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.
+     *
+     * **Example** (Falling back for missing services)
      *
-     * @example
      * ```ts
      * import { Context } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
      * const Database = Context.Service<{ query: (sql: string) => string }>(
@@ -613,43 +773,69 @@ export declare const getOrElse: {
      *   () => ({ query: () => "fallback" })
      * )
      *
-     * assert.deepStrictEqual(logger, { log: (msg: string) => console.log(msg) })
-     * assert.deepStrictEqual(database, { query: () => "fallback" })
+     * console.log(logger === Context.get(context, Logger)) // true
+     * console.log(database.query("SELECT 1")) // "fallback"
      * ```
      *
-     * @since 4.0.0
-     * @category Getters
+     * @category getters
+     * @since 3.7.0
      */
     <Services, S, I, B>(self: Context<Services>, key: Key<I, S>, orElse: LazyArg<B>): S | B;
 };
 /**
+ * Returns the service currently stored for a key, or `undefined` when the key
+ * is absent.
+ *
+ * **Notes**
+ *
+ * This is a raw lookup and does not resolve default values for
+ * `Context.Reference` keys.
+ *
+ * @category getters
  * @since 4.0.0
- * @category Getters
  */
 export declare const getOrUndefined: {
     /**
+     * Returns the service currently stored for a key, or `undefined` when the key
+     * is absent.
+     *
+     * **Notes**
+     *
+     * This is a raw lookup and does not resolve default values for
+     * `Context.Reference` keys.
+     *
+     * @category getters
      * @since 4.0.0
-     * @category Getters
      */
     <S, I>(key: Key<I, S>): <Services>(self: Context<Services>) => S | undefined;
     /**
+     * Returns the service currently stored for a key, or `undefined` when the key
+     * is absent.
+     *
+     * **Notes**
+     *
+     * This is a raw lookup and does not resolve default values for
+     * `Context.Reference` keys.
+     *
+     * @category getters
      * @since 4.0.0
-     * @category Getters
      */
     <Services, S, I>(self: Context<Services>, key: Key<I, S>): S | undefined;
 };
 /**
- * Get a service from the context that corresponds to the given key.
+ * Gets the service for a key, throwing if an absent non-reference key cannot be
+ * resolved.
+ *
+ * **Details**
  *
- * This function is unsafe because if the key is not present in the context, a
- * runtime error will be thrown.
+ * 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}.
  *
- * @param self - The `Context` to search for the service.
- * @param service - The `Service` of the service to retrieve.
+ * **Example** (Getting services unsafely)
  *
- * @example
  * ```ts
  * import { Context } from "effect"
  * import * as assert from "node:assert"
@@ -663,22 +849,24 @@ export declare const getOrUndefined: {
  * assert.throws(() => Context.getUnsafe(context, Timeout))
  * ```
  *
- * @since 4.0.0
  * @category unsafe
+ * @since 4.0.0
  */
 export declare const getUnsafe: {
     /**
-     * Get a service from the context that corresponds to the given key.
+     * Gets the service for a key, throwing if an absent non-reference key cannot be
+     * resolved.
+     *
+     * **Details**
      *
-     * This function is unsafe because if the key is not present in the context, a
-     * runtime error will be thrown.
+     * 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}.
      *
-     * @param self - The `Context` to search for the service.
-     * @param service - The `Service` of the service to retrieve.
+     * **Example** (Getting services unsafely)
      *
-     * @example
      * ```ts
      * import { Context } from "effect"
      * import * as assert from "node:assert"
@@ -692,22 +880,24 @@ export declare const getUnsafe: {
      * assert.throws(() => Context.getUnsafe(context, Timeout))
      * ```
      *
-     * @since 4.0.0
      * @category unsafe
+     * @since 4.0.0
      */
     <S, I>(service: Key<I, S>): <Services>(self: Context<Services>) => S;
     /**
-     * Get a service from the context that corresponds to the given key.
+     * Gets the service for a key, throwing if an absent non-reference key cannot be
+     * resolved.
+     *
+     * **Details**
      *
-     * This function is unsafe because if the key is not present in the context, a
-     * runtime error will be thrown.
+     * 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}.
      *
-     * @param self - The `Context` to search for the service.
-     * @param service - The `Service` of the service to retrieve.
+     * **Example** (Getting services unsafely)
      *
-     * @example
      * ```ts
      * import { Context } from "effect"
      * import * as assert from "node:assert"
@@ -721,20 +911,18 @@ export declare const getUnsafe: {
      * assert.throws(() => Context.getUnsafe(context, Timeout))
      * ```
      *
-     * @since 4.0.0
      * @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.
  *
- * @param self - The `Context` to search for the service.
- * @param service - The `Service` of the service to retrieve.
+ * **Example** (Getting a service from a context)
  *
- * @example
  * ```ts
- * import { pipe, Context } from "effect"
+ * import { Context, pipe } from "effect"
  * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
@@ -748,19 +936,17 @@ export declare const getUnsafe: {
  * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
  * ```
  *
- * @since 4.0.0
- * @category Getters
+ * @category getters
+ * @since 2.0.0
  */
 export declare const get: {
     /**
      * Get a service from the context that corresponds to the given key.
      *
-     * @param self - The `Context` to search for the service.
-     * @param service - The `Service` of the service to retrieve.
+     * **Example** (Getting a service from a context)
      *
-     * @example
      * ```ts
-     * import { pipe, Context } from "effect"
+     * import { Context, pipe } from "effect"
      * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
@@ -774,19 +960,17 @@ export declare const get: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @since 4.0.0
-     * @category Getters
+     * @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.
      *
-     * @param self - The `Context` to search for the service.
-     * @param service - The `Service` of the service to retrieve.
+     * **Example** (Getting a service from a context)
      *
-     * @example
      * ```ts
-     * import { pipe, Context } from "effect"
+     * import { Context, pipe } from "effect"
      * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
@@ -800,16 +984,19 @@ export declare const get: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @since 4.0.0
-     * @category Getters
+     * @category getters
+     * @since 2.0.0
      */
     <Services, I extends Services, S>(self: Context<Services>, service: Key<I, S>): S;
 };
 /**
- * @example
+ * Gets the value for a `Context.Reference`, returning its cached default when
+ * the context does not contain an override.
+ *
+ * **Example** (Getting reference defaults unsafely)
+ *
  * ```ts
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const LoggerRef = Context.Reference("Logger", {
  *   defaultValue: () => ({ log: (msg: string) => console.log(msg) })
@@ -818,24 +1005,26 @@ export declare const get: {
  * const context = Context.empty()
  * const logger = Context.getReferenceUnsafe(context, LoggerRef)
  *
- * assert.deepStrictEqual(logger, { log: (msg: string) => console.log(msg) })
+ * console.log(typeof logger.log) // "function"
  * ```
  *
- * @since 4.0.0
  * @category unsafe
+ * @since 4.0.0
  */
 export declare const getReferenceUnsafe: <Services, S>(self: Context<Services>, service: Reference<S>) => S;
 /**
- * Get the value associated with the specified key from the context wrapped in
- * an `Option` object. If the key is not found, the `Option` object will be
- * `None`.
+ * Gets the service for a key wrapped in an `Option`.
+ *
+ * **Details**
+ *
+ * Returns `Option.some` when the service is stored in the context. If the key
+ * is a `Context.Reference` and no override is stored, returns `Option.some` of
+ * the cached default value. Missing non-reference keys return `Option.none`.
  *
- * @param self - The `Context` to search for the service.
- * @param service - The `Service` of the service to retrieve.
+ * **Example** (Getting optional services)
  *
- * @example
  * ```ts
- * import { Option, Context } from "effect"
+ * import { Context, Option } from "effect"
  * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
@@ -850,21 +1039,23 @@ export declare const getReferenceUnsafe: <Services, S>(self: Context<Services>,
  * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
  * ```
  *
- * @since 4.0.0
- * @category Getters
+ * @category getters
+ * @since 2.0.0
  */
 export declare const getOption: {
     /**
-     * Get the value associated with the specified key from the context wrapped in
-     * an `Option` object. If the key is not found, the `Option` object will be
-     * `None`.
+     * Gets the service for a key wrapped in an `Option`.
+     *
+     * **Details**
+     *
+     * Returns `Option.some` when the service is stored in the context. If the key
+     * is a `Context.Reference` and no override is stored, returns `Option.some` of
+     * the cached default value. Missing non-reference keys return `Option.none`.
      *
-     * @param self - The `Context` to search for the service.
-     * @param service - The `Service` of the service to retrieve.
+     * **Example** (Getting optional services)
      *
-     * @example
      * ```ts
-     * import { Option, Context } from "effect"
+     * import { Context, Option } from "effect"
      * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
@@ -879,21 +1070,23 @@ export declare const getOption: {
      * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
      * ```
      *
-     * @since 4.0.0
-     * @category Getters
+     * @category getters
+     * @since 2.0.0
      */
     <S, I>(service: Key<I, S>): <Services>(self: Context<Services>) => Option.Option<S>;
     /**
-     * Get the value associated with the specified key from the context wrapped in
-     * an `Option` object. If the key is not found, the `Option` object will be
-     * `None`.
+     * Gets the service for a key wrapped in an `Option`.
+     *
+     * **Details**
+     *
+     * Returns `Option.some` when the service is stored in the context. If the key
+     * is a `Context.Reference` and no override is stored, returns `Option.some` of
+     * the cached default value. Missing non-reference keys return `Option.none`.
      *
-     * @param self - The `Context` to search for the service.
-     * @param service - The `Service` of the service to retrieve.
+     * **Example** (Getting optional services)
      *
-     * @example
      * ```ts
-     * import { Option, Context } from "effect"
+     * import { Context, Option } from "effect"
      * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
@@ -908,18 +1101,21 @@ export declare const getOption: {
      * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
      * ```
      *
-     * @since 4.0.0
-     * @category Getters
+     * @category getters
+     * @since 2.0.0
      */
     <Services, S, I>(self: Context<Services>, service: Key<I, S>): Option.Option<S>;
 };
 /**
- * Merges two `Context`s, returning a new `Context` containing the services of both.
+ * Merges two `Context`s into one.
+ *
+ * **Details**
  *
- * @param self - The first `Context` to merge.
- * @param that - The second `Context` to merge.
+ * When both contexts contain the same service key, the service from `that`
+ * overrides the service from `self`.
+ *
+ * **Example** (Merging two contexts)
  *
- * @example
  * ```ts
  * import { Context } from "effect"
  * import * as assert from "node:assert"
@@ -936,17 +1132,20 @@ export declare const getOption: {
  * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
  * ```
  *
- * @since 4.0.0
  * @category Utils
+ * @since 2.0.0
  */
 export declare const merge: {
     /**
-     * Merges two `Context`s, returning a new `Context` containing the services of both.
+     * Merges two `Context`s into one.
      *
-     * @param self - The first `Context` to merge.
-     * @param that - The second `Context` to merge.
+     * **Details**
+     *
+     * When both contexts contain the same service key, the service from `that`
+     * overrides the service from `self`.
+     *
+     * **Example** (Merging two contexts)
      *
-     * @example
      * ```ts
      * import { Context } from "effect"
      * import * as assert from "node:assert"
@@ -963,17 +1162,20 @@ export declare const merge: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @since 4.0.0
      * @category Utils
+     * @since 2.0.0
      */
     <R1>(that: Context<R1>): <Services>(self: Context<Services>) => Context<R1 | Services>;
     /**
-     * Merges two `Context`s, returning a new `Context` containing the services of both.
+     * Merges two `Context`s into one.
      *
-     * @param self - The first `Context` to merge.
-     * @param that - The second `Context` to merge.
+     * **Details**
+     *
+     * When both contexts contain the same service key, the service from `that`
+     * overrides the service from `self`.
+     *
+     * **Example** (Merging two contexts)
      *
-     * @example
      * ```ts
      * import { Context } from "effect"
      * import * as assert from "node:assert"
@@ -990,15 +1192,21 @@ export declare const merge: {
      * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
      * ```
      *
-     * @since 4.0.0
      * @category Utils
+     * @since 2.0.0
      */
     <Services, R1>(self: Context<Services>, that: Context<R1>): Context<Services | R1>;
 };
 /**
- * Merges any number of `Context`s, returning a new `Context` containing the services of all.
+ * Merges any number of `Context`s into one.
+ *
+ * **Details**
+ *
+ * When multiple contexts contain the same service key, the service from the
+ * last context with that key is kept.
+ *
+ * **Example** (Merging multiple contexts)
  *
- * @example
  * ```ts
  * import { Context } from "effect"
  * import * as assert from "node:assert"
@@ -1022,18 +1230,17 @@ export declare const merge: {
  * assert.deepStrictEqual(Context.get(context, Host), { HOST: "localhost" })
  * ```
  *
+ * @category combining
  * @since 3.12.0
  */
 export declare const mergeAll: <T extends Array<unknown>>(...ctxs: [...{ [K in keyof T]: Context<T[K]>; }]) => Context<T[number]>;
 /**
  * Returns a new `Context` that contains only the specified services.
  *
- * @param self - The `Context` to prune services from.
- * @param services - The list of `Service`s to be included in the new `Context`.
+ * **Example** (Picking services from a context)
  *
- * @example
  * ```ts
- * import { Option, pipe, Context } from "effect"
+ * import { Context, Option, pipe } from "effect"
  * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
@@ -1053,14 +1260,17 @@ export declare const mergeAll: <T extends Array<unknown>>(...ctxs: [...{ [K in k
  * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
  * ```
  *
- * @since 4.0.0
  * @category Utils
+ * @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]>>;
 /**
- * @example
+ * Returns a new `Context` with the specified service keys removed.
+ *
+ * **Example** (Omitting services from a context)
+ *
  * ```ts
- * import { Option, pipe, Context } from "effect"
+ * import { Context, Option, pipe } from "effect"
  * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
@@ -1080,32 +1290,32 @@ export declare const pick: <S extends ReadonlyArray<Key<any, any>>>(...services:
  * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
  * ```
  *
- * @since 4.0.0
  * @category Utils
+ * @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
  * of the underlying map when multiple mutations are needed.
  *
- * @since 4.0.0
  * @category Utils
+ * @since 4.0.0
  */
 export declare const mutate: {
     /**
      * Perform a series of mutations on a `Context`. Prevents unnecessary copying
      * of the underlying map when multiple mutations are needed.
      *
-     * @since 4.0.0
      * @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
      * of the underlying map when multiple mutations are needed.
      *
-     * @since 4.0.0
      * @category Utils
+     * @since 4.0.0
      */
     <Services, B>(self: Context<Services>, f: (context: Context<Services>) => Context<B>): Context<B>;
 };
@@ -1119,7 +1329,8 @@ export declare const mutate: {
  * when the context is accessed, or override it with a custom implementation
  * when needed.
  *
- * @example
+ * **Example** (Creating references with default values)
+ *
  * ```ts
  * import { Context } from "effect"
  *
@@ -1139,8 +1350,8 @@ export declare const mutate: {
  * const customLogger = Context.get(customContext, LoggerRef)
  * ```
  *
- * @since 4.0.0
- * @category References
+ * @category references
+ * @since 3.11.0
  */
 export declare const Reference: <Service>(key: string, options: {
     readonly defaultValue: () => Service;