effect 4.0.0-beta.102 → 4.0.0-beta.103

package/dist/Context.d.ts

@@ -72,7 +72,7 @@ export interface Key<out Identifier, out Shape> extends Effect<Shape, never, Ide
  *
  * **Example** (Defining a service key)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Define an identifier for a database service
@@ -82,9 +82,10 @@ export interface Key<out Identifier, out Shape> extends Effect<Shape, never, Ide
  *
  * // The key can be used to store and retrieve services
  * const context = Context.make(Database, { query: (sql) => `Result: ${sql}` })
+ * Context.get(context, Database).query("SELECT 1") // => "Result: SELECT 1"
  * ```
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface Service<in out Identifier, in out Shape> extends Key<Identifier, Shape> {
@@ -108,7 +109,7 @@ export interface Service<in out Identifier, in out Shape> extends Key<Identifier
  *
  * @see {@link Service} for creating function-style keys or class-style service keys
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface ServiceClass<in out Self, in out Identifier extends string, in out Shape> extends Service<Self, Shape> {
@@ -126,7 +127,7 @@ 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
+     * @category services
      * @since 4.0.0
      */
     interface Shape<Identifier extends string, Service> {
@@ -158,7 +159,7 @@ export declare namespace ServiceClass {
  *
  * **Example** (Creating service keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Create a simple service
@@ -176,11 +177,13 @@ export declare namespace ServiceClass {
  *   query: (sql) => `Result: ${sql}`
  * })
  * const config = Context.make(Config, { port: 8080 })
+ * Context.get(db, Database).query("SELECT 1") // => "Result: SELECT 1"
+ * Context.get(config, Config).port // => 8080
  * ```
  *
  * @see {@link Reference} for service keys with default values
  *
- * @category constructors
+ * @category services
  * @since 4.0.0
  */
 export declare const Service: {
@@ -207,7 +210,7 @@ export declare const Service: {
      *
      * **Example** (Creating service keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
      *
      * // Create a simple service
@@ -225,14 +228,16 @@ export declare const Service: {
      *   query: (sql) => `Result: ${sql}`
      * })
      * const config = Context.make(Config, { port: 8080 })
+     * Context.get(db, Database).query("SELECT 1") // => "Result: SELECT 1"
+     * Context.get(config, Config).port // => 8080
      * ```
      *
      * @see {@link Reference} for service keys with default values
      *
-     * @category constructors
+     * @category services
      * @since 4.0.0
      */
-    <Identifier, Shape = Identifier>(key: string): Service<Identifier, Shape>;
+    <Identifier, Shape = Identifier>(key: string, options?: {} | undefined): Service<Identifier, Shape>;
     /**
      * Creates a `Context` service key.
      *
@@ -256,7 +261,7 @@ export declare const Service: {
      *
      * **Example** (Creating service keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
      *
      * // Create a simple service
@@ -274,15 +279,17 @@ export declare const Service: {
      *   query: (sql) => `Result: ${sql}`
      * })
      * const config = Context.make(Config, { port: 8080 })
+     * Context.get(db, Database).query("SELECT 1") // => "Result: SELECT 1"
+     * Context.get(config, Config).port // => 8080
      * ```
      *
      * @see {@link Reference} for service keys with default values
      *
-     * @category constructors
+     * @category services
      * @since 4.0.0
      */
     <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;
+        readonly make?: ((...args: Args) => Effect<Shape, E, R>) | Effect<Shape, E, R> | undefined;
     } | undefined) => ServiceClass<Self, Identifier, Shape> & ([Types.unassigned] extends [R] ? unknown : {
         readonly make: [Args] extends [never] ? Effect<Shape, E, R> : (...args: Args) => Effect<Shape, E, R>;
     });
@@ -309,7 +316,7 @@ export declare const Service: {
      *
      * **Example** (Creating service keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
      *
      * // Create a simple service
@@ -327,11 +334,13 @@ export declare const Service: {
      *   query: (sql) => `Result: ${sql}`
      * })
      * const config = Context.make(Config, { port: 8080 })
+     * Context.get(db, Database).query("SELECT 1") // => "Result: SELECT 1"
+     * Context.get(config, Config).port // => 8080
      * ```
      *
      * @see {@link Reference} for service keys with default values
      *
-     * @category constructors
+     * @category services
      * @since 4.0.0
      */
     <Self>(): <const Identifier extends string, Make extends Effect<any, any, any> | ((...args: any) => Effect<any, any, any>)>(id: Identifier, options: {
@@ -352,21 +361,24 @@ declare const ReferenceTypeId: "~effect/Context/Reference";
  *
  * **Example** (Defining a reference with a default value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Define a reference with a default value
+ * const messages: Array<string> = []
  * const LoggerRef: Context.Reference<{ log: (msg: string) => void }> =
  *   Context.Reference("Logger", {
- *     defaultValue: () => ({ log: (msg: string) => console.log(msg) })
+ *     defaultValue: () => ({ log: (msg) => { messages.push(msg) } })
  *   })
  *
  * // The reference can be used without explicit provision
  * const context = Context.empty()
  * const logger = Context.get(context, LoggerRef) // Uses default value
+ * logger.log("default logger")
+ * messages // => ["default logger"]
  * ```
  *
- * @category models
+ * @category services
  * @since 3.11.0
  */
 export interface Reference<in out Shape> extends Service<never, Shape> {
@@ -380,7 +392,7 @@ export interface Reference<in out Shape> extends Service<never, Shape> {
  *
  * **Example** (Extracting service types)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * const Database = Context.Service<{
@@ -392,6 +404,8 @@ export interface Reference<in out Shape> extends Service<never, Shape> {
  *
  * // Extract identifier type from a key
  * type DatabaseId = Context.Service.Identifier<typeof Database>
+ *
+ * Database.key // => "Database"
  * ```
  *
  * @since 2.0.0
@@ -403,7 +417,7 @@ export declare namespace Service {
      *
      * **Example** (Typing any service key)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
      *
      * // Any represents any possible service type
@@ -411,9 +425,10 @@ export declare namespace Service {
      *   Context.Service<{ log: (msg: string) => void }>("Logger"),
      *   Context.Service<{ query: (sql: string) => string }>("Database")
      * ]
+     * services.map((service) => service.key) // => ["Logger", "Database"]
      * ```
      *
-     * @category models
+     * @category utility types
      * @since 4.0.0
      */
     type Any = Key<never, any> | Key<any, any>;
@@ -423,7 +438,7 @@ export declare namespace Service {
      *
      * **Example** (Extracting a service shape)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
      *
      * const Database = Context.Service<{ query: (sql: string) => string }>(
@@ -433,9 +448,10 @@ export declare namespace Service {
      * // Extract the service shape from the service
      * type DatabaseService = Context.Service.Shape<typeof Database>
      * // DatabaseService is { query: (sql: string) => string }
+     * Database.key // => "Database"
      * ```
      *
-     * @category models
+     * @category utility types
      * @since 4.0.0
      */
     type Shape<T> = T extends Key<infer _I, infer S> ? S : never;
@@ -445,7 +461,7 @@ export declare namespace Service {
      *
      * **Example** (Extracting a service identifier)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
      *
      * const Database = Context.Service<{ query: (sql: string) => string }>(
@@ -455,9 +471,10 @@ export declare namespace Service {
      * // Extract the identifier type from a key
      * type DatabaseId = Context.Service.Identifier<typeof Database>
      * // DatabaseId is the identifier type
+     * Database.key // => "Database"
      * ```
      *
-     * @category models
+     * @category utility types
      * @since 2.0.0
      */
     type Identifier<T> = T extends Key<infer I, infer _S> ? I : never;
@@ -474,7 +491,7 @@ declare const TypeId: "~effect/Context";
  *
  * **Example** (Creating a context with multiple services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Create a context with multiple services
@@ -483,10 +500,9 @@ declare const TypeId: "~effect/Context";
  *   "Database"
  * )
  *
- * const context = Context.make(Logger, {
- *   log: (msg: string) => console.log(msg)
- * })
+ * const context = Context.make(Logger, { log: (_msg: string) => {} })
  *   .pipe(Context.add(Database, { query: (sql) => `Result: ${sql}` }))
+ * Context.get(context, Database).query("SELECT 1") // => "Result: SELECT 1"
  * ```
  *
  * @category models
@@ -497,7 +513,6 @@ export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable
         readonly _Services: Types.Contravariant<Services>;
     };
     readonly mapUnsafe: ReadonlyMap<string, any>;
-    mutable: boolean;
 }
 /**
  * Creates a `Context` from an existing service map.
@@ -509,21 +524,22 @@ export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable
  *
  * **Gotchas**
  *
- * 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.
+ * The provided map is retained without copying and must not be mutated after
+ * construction. Prefer `empty`, `make`, `add`, or `merge` for normal Context
+ * construction.
  *
  * **Example** (Creating a context from a map)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Create a context from a Map (unsafe)
  * const map = new Map([
- *   ["Logger", { log: (msg: string) => console.log(msg) }]
+ *   ["Logger", { log: (_msg: string) => {} }]
  * ])
  *
  * const context = Context.makeUnsafe(map)
+ * context.mapUnsafe.size // => 1
  * ```
  *
  * @category constructors
@@ -550,11 +566,9 @@ export declare const makeUnsafe: <Services = never>(mapUnsafe: ReadonlyMap<strin
  *
  * **Example** (Checking for contexts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
- *
- * assert.strictEqual(Context.isContext(Context.empty()), true)
+ * Context.isContext(Context.empty()) // => true
  * ```
  *
  * @see {@link isKey} for checking service keys
@@ -569,11 +583,9 @@ export declare const isContext: (u: unknown) => u is Context<never>;
  *
  * **Example** (Checking for keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
- *
- * assert.strictEqual(Context.isKey(Context.Service("Service")), true)
+ * Context.isKey(Context.Service("Service")) // => true
  * ```
  *
  * @category guards
@@ -585,32 +597,29 @@ export declare const isKey: (u: unknown) => u is Key<any, any>;
  *
  * **Example** (Checking for references)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const LoggerRef = Context.Reference("Logger", {
- *   defaultValue: () => ({ log: (msg: string) => console.log(msg) })
+ *   defaultValue: () => ({ log: (_msg: string) => {} })
  * })
  *
- * assert.strictEqual(Context.isReference(LoggerRef), true)
- * assert.strictEqual(Context.isReference(Context.Service("Key")), false)
+ * Context.isReference(LoggerRef) // => true
+ * Context.isReference(Context.Service("Key")) // => false
  * ```
  *
  * @category guards
  * @since 3.11.0
  */
-export declare const isReference: (u: unknown) => u is Reference<any>;
+export declare const isReference: <I, S>(u: Key<I, S>) => u is Reference<S>;
 /**
  * Returns an empty `Context`.
  *
  * **Example** (Creating an empty context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
- *
- * assert.strictEqual(Context.isContext(Context.empty()), true)
+ * Context.empty().mapUnsafe.size // => 0
  * ```
  *
  * @category constructors
@@ -622,15 +631,14 @@ export declare const empty: () => Context<never>;
  *
  * **Example** (Creating a context with one service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  *
  * const context = Context.make(Port, { PORT: 8080 })
  *
- * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
+ * Context.get(context, Port).PORT // => 8080
  * ```
  *
  * @category constructors
@@ -651,9 +659,8 @@ export declare const make: <I, S>(key: Key<I, S>, service: Types.NoInfer<S>) =>
  *
  * **Example** (Adding a service to a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, pipe } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -665,13 +672,13 @@ export declare const make: <I, S>(key: Key<I, S>, service: Types.NoInfer<S>) =>
  *   Context.add(Timeout, { TIMEOUT: 5000 })
  * )
  *
- * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
- * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+ * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+ * values // => [8080, 5000]
  * ```
  *
  * @see {@link addOrOmit} for adding or removing a service from an `Option`
  *
- * @category adders
+ * @category combining
  * @since 2.0.0
  */
 export declare const add: {
@@ -689,9 +696,8 @@ export declare const add: {
      *
      * **Example** (Adding a service to a context)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context, pipe } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -703,13 +709,13 @@ export declare const add: {
      *   Context.add(Timeout, { TIMEOUT: 5000 })
      * )
      *
-     * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
-     * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+     * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+     * values // => [8080, 5000]
      * ```
      *
      * @see {@link addOrOmit} for adding or removing a service from an `Option`
      *
-     * @category adders
+     * @category combining
      * @since 2.0.0
      */
     <I, S>(key: Key<I, S>, service: Types.NoInfer<S>): <Services>(self: Context<Services>) => Context<Services | I>;
@@ -727,9 +733,8 @@ export declare const add: {
      *
      * **Example** (Adding a service to a context)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context, pipe } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -741,13 +746,13 @@ export declare const add: {
      *   Context.add(Timeout, { TIMEOUT: 5000 })
      * )
      *
-     * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
-     * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+     * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+     * values // => [8080, 5000]
      * ```
      *
      * @see {@link addOrOmit} for adding or removing a service from an `Option`
      *
-     * @category adders
+     * @category combining
      * @since 2.0.0
      */
     <Services, I, S>(self: Context<Services>, key: Key<I, S>, service: Types.NoInfer<S>): Context<Services | I>;
@@ -766,7 +771,7 @@ export declare const add: {
  *
  * **Example** (Adding optional services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Option } from "effect"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
@@ -778,11 +783,13 @@ export declare const add: {
  * const withoutPort = withPort.pipe(
  *   Context.addOrOmit(Port, Option.none())
  * )
+ * Context.getOption(withPort, Port) // => Option.some({ PORT: 8080 })
+ * Context.getOption(withoutPort, Port) // => Option.none()
  * ```
  *
  * @see {@link add} for always storing a service value
  *
- * @category adders
+ * @category combining
  * @since 4.0.0
  */
 export declare const addOrOmit: {
@@ -800,7 +807,7 @@ export declare const addOrOmit: {
      *
      * **Example** (Adding optional services)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context, Option } from "effect"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
@@ -812,11 +819,13 @@ export declare const addOrOmit: {
      * const withoutPort = withPort.pipe(
      *   Context.addOrOmit(Port, Option.none())
      * )
+     * Context.getOption(withPort, Port) // => Option.some({ PORT: 8080 })
+     * Context.getOption(withoutPort, Port) // => Option.none()
      * ```
      *
      * @see {@link add} for always storing a service value
      *
-     * @category adders
+     * @category combining
      * @since 4.0.0
      */
     <I, S>(key: Key<I, S>, service: Option.Option<Types.NoInfer<S>>): <Services>(self: Context<Services>) => Context<Services | I>;
@@ -834,7 +843,7 @@ export declare const addOrOmit: {
      *
      * **Example** (Adding optional services)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context, Option } from "effect"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
@@ -846,11 +855,13 @@ export declare const addOrOmit: {
      * const withoutPort = withPort.pipe(
      *   Context.addOrOmit(Port, Option.none())
      * )
+     * Context.getOption(withPort, Port) // => Option.some({ PORT: 8080 })
+     * Context.getOption(withoutPort, Port) // => Option.none()
      * ```
      *
      * @see {@link add} for always storing a service value
      *
-     * @category adders
+     * @category combining
      * @since 4.0.0
      */
     <Services, I, S>(self: Context<Services>, key: Key<I, S>, service: Option.Option<Types.NoInfer<S>>): Context<Services | I>;
@@ -876,7 +887,7 @@ export declare const addOrOmit: {
  *
  * **Example** (Falling back for missing services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
@@ -884,9 +895,7 @@ export declare const addOrOmit: {
  *   "Database"
  * )
  *
- * const context = Context.make(Logger, {
- *   log: (msg: string) => console.log(msg)
- * })
+ * const context = Context.make(Logger, { log: (_msg: string) => {} })
  *
  * const logger = Context.getOrElse(context, Logger, () => ({ log: () => {} }))
  * const database = Context.getOrElse(
@@ -895,8 +904,8 @@ export declare const addOrOmit: {
  *   () => ({ query: () => "fallback" })
  * )
  *
- * console.log(logger === Context.get(context, Logger)) // true
- * console.log(database.query("SELECT 1")) // "fallback"
+ * logger === Context.get(context, Logger) // => true
+ * database.query("SELECT 1") // => "fallback"
  * ```
  *
  * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
@@ -926,7 +935,7 @@ export declare const getOrElse: {
      *
      * **Example** (Falling back for missing services)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
      *
      * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
@@ -934,9 +943,7 @@ export declare const getOrElse: {
      *   "Database"
      * )
      *
-     * const context = Context.make(Logger, {
-     *   log: (msg: string) => console.log(msg)
-     * })
+     * const context = Context.make(Logger, { log: (_msg: string) => {} })
      *
      * const logger = Context.getOrElse(context, Logger, () => ({ log: () => {} }))
      * const database = Context.getOrElse(
@@ -945,8 +952,8 @@ export declare const getOrElse: {
      *   () => ({ query: () => "fallback" })
      * )
      *
-     * console.log(logger === Context.get(context, Logger)) // true
-     * console.log(database.query("SELECT 1")) // "fallback"
+     * logger === Context.get(context, Logger) // => true
+     * database.query("SELECT 1") // => "fallback"
      * ```
      *
      * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
@@ -976,7 +983,7 @@ export declare const getOrElse: {
      *
      * **Example** (Falling back for missing services)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
      *
      * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
@@ -984,9 +991,7 @@ export declare const getOrElse: {
      *   "Database"
      * )
      *
-     * const context = Context.make(Logger, {
-     *   log: (msg: string) => console.log(msg)
-     * })
+     * const context = Context.make(Logger, { log: (_msg: string) => {} })
      *
      * const logger = Context.getOrElse(context, Logger, () => ({ log: () => {} }))
      * const database = Context.getOrElse(
@@ -995,8 +1000,8 @@ export declare const getOrElse: {
      *   () => ({ query: () => "fallback" })
      * )
      *
-     * console.log(logger === Context.get(context, Logger)) // true
-     * console.log(database.query("SELECT 1")) // "fallback"
+     * logger === Context.get(context, Logger) // => true
+     * database.query("SELECT 1") // => "fallback"
      * ```
      *
      * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
@@ -1084,17 +1089,16 @@ export declare const getOrUndefined: {
  *
  * **Example** (Getting services unsafely)
  *
- * ```ts
- * import { Context } from "effect"
- * import * as assert from "node:assert"
+ * ```ts import.meta.vitest
+ * import { Context, Option } from "effect"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
  *
  * const context = Context.make(Port, { PORT: 8080 })
  *
- * assert.deepStrictEqual(Context.getUnsafe(context, Port), { PORT: 8080 })
- * assert.throws(() => Context.getUnsafe(context, Timeout))
+ * Context.getUnsafe(context, Port).PORT // => 8080
+ * Context.getOption(context, Timeout) // => Option.none()
  * ```
  *
  * @see {@link get} for type-checked service access
@@ -1121,17 +1125,16 @@ export declare const getUnsafe: {
      *
      * **Example** (Getting services unsafely)
      *
-     * ```ts
-     * import { Context } from "effect"
-     * import * as assert from "node:assert"
+     * ```ts import.meta.vitest
+     * import { Context, Option } from "effect"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
      *
      * const context = Context.make(Port, { PORT: 8080 })
      *
-     * assert.deepStrictEqual(Context.getUnsafe(context, Port), { PORT: 8080 })
-     * assert.throws(() => Context.getUnsafe(context, Timeout))
+     * Context.getUnsafe(context, Port).PORT // => 8080
+     * Context.getOption(context, Timeout) // => Option.none()
      * ```
      *
      * @see {@link get} for type-checked service access
@@ -1158,17 +1161,16 @@ export declare const getUnsafe: {
      *
      * **Example** (Getting services unsafely)
      *
-     * ```ts
-     * import { Context } from "effect"
-     * import * as assert from "node:assert"
+     * ```ts import.meta.vitest
+     * import { Context, Option } from "effect"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
      *
      * const context = Context.make(Port, { PORT: 8080 })
      *
-     * assert.deepStrictEqual(Context.getUnsafe(context, Port), { PORT: 8080 })
-     * assert.throws(() => Context.getUnsafe(context, Timeout))
+     * Context.getUnsafe(context, Port).PORT // => 8080
+     * Context.getOption(context, Timeout) // => Option.none()
      * ```
      *
      * @see {@link get} for type-checked service access
@@ -1189,9 +1191,8 @@ export declare const getUnsafe: {
  *
  * **Example** (Getting a service from a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, pipe } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1201,7 +1202,7 @@ export declare const getUnsafe: {
  *   Context.add(Timeout, { TIMEOUT: 5000 })
  * )
  *
- * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+ * Context.get(context, Timeout).TIMEOUT // => 5000
  * ```
  *
  * @see {@link getOption} for optional service access
@@ -1221,9 +1222,8 @@ export declare const get: {
      *
      * **Example** (Getting a service from a context)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context, pipe } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1233,7 +1233,7 @@ export declare const get: {
      *   Context.add(Timeout, { TIMEOUT: 5000 })
      * )
      *
-     * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+     * Context.get(context, Timeout).TIMEOUT // => 5000
      * ```
      *
      * @see {@link getOption} for optional service access
@@ -1253,9 +1253,8 @@ export declare const get: {
      *
      * **Example** (Getting a service from a context)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context, pipe } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1265,7 +1264,7 @@ export declare const get: {
      *   Context.add(Timeout, { TIMEOUT: 5000 })
      * )
      *
-     * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+     * Context.get(context, Timeout).TIMEOUT // => 5000
      * ```
      *
      * @see {@link getOption} for optional service access
@@ -1276,48 +1275,6 @@ export declare const get: {
      */
     <Services, I extends Services, S>(self: Context<Services>, service: Key<I, S>): S;
 };
-/**
- * Gets the value for a `Context.Reference`, returning its cached default when
- * the context does not contain an override.
- *
- * **When to use**
- *
- * Use when you need a `Context.Reference` value resolved from either a 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
- * import { Context } from "effect"
- *
- * const LoggerRef = Context.Reference("Logger", {
- *   defaultValue: () => ({ log: (msg: string) => console.log(msg) })
- * })
- *
- * const context = Context.empty()
- * const logger = Context.getReferenceUnsafe(context, LoggerRef)
- *
- * 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 safely wrapped in an `Option`.
  *
@@ -1334,20 +1291,16 @@ export declare const getReferenceUnsafe: <Services, S>(self: Context<Services>,
  *
  * **Example** (Getting optional services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Option } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
  *
  * const context = Context.make(Port, { PORT: 8080 })
  *
- * assert.deepStrictEqual(
- *   Context.getOption(context, Port),
- *   Option.some({ PORT: 8080 })
- * )
- * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+ * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+ * Context.getOption(context, Timeout) // => Option.none()
  * ```
  *
  * @see {@link getOrElse} for returning a fallback value directly
@@ -1372,20 +1325,16 @@ export declare const getOption: {
      *
      * **Example** (Getting optional services)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context, Option } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
      *
      * const context = Context.make(Port, { PORT: 8080 })
      *
-     * assert.deepStrictEqual(
-     *   Context.getOption(context, Port),
-     *   Option.some({ PORT: 8080 })
-     * )
-     * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+     * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+     * Context.getOption(context, Timeout) // => Option.none()
      * ```
      *
      * @see {@link getOrElse} for returning a fallback value directly
@@ -1410,20 +1359,16 @@ export declare const getOption: {
      *
      * **Example** (Getting optional services)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context, Option } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
      *
      * const context = Context.make(Port, { PORT: 8080 })
      *
-     * assert.deepStrictEqual(
-     *   Context.getOption(context, Port),
-     *   Option.some({ PORT: 8080 })
-     * )
-     * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+     * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+     * Context.getOption(context, Timeout) // => Option.none()
      * ```
      *
      * @see {@link getOrElse} for returning a fallback value directly
@@ -1447,9 +1392,8 @@ export declare const getOption: {
  *
  * **Example** (Merging two contexts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1459,8 +1403,8 @@ export declare const getOption: {
  *
  * const context = Context.merge(firstContext, secondContext)
  *
- * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
- * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+ * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+ * values // => [8080, 5000]
  * ```
  *
  * @see {@link mergeAll} for merging more than two contexts at once
@@ -1483,9 +1427,8 @@ export declare const merge: {
      *
      * **Example** (Merging two contexts)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1495,8 +1438,8 @@ export declare const merge: {
      *
      * const context = Context.merge(firstContext, secondContext)
      *
-     * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
-     * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+     * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+     * values // => [8080, 5000]
      * ```
      *
      * @see {@link mergeAll} for merging more than two contexts at once
@@ -1519,9 +1462,8 @@ export declare const merge: {
      *
      * **Example** (Merging two contexts)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Context } from "effect"
-     * import * as assert from "node:assert"
      *
      * const Port = Context.Service<{ PORT: number }>("Port")
      * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1531,8 +1473,8 @@ export declare const merge: {
      *
      * const context = Context.merge(firstContext, secondContext)
      *
-     * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
-     * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+     * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+     * values // => [8080, 5000]
      * ```
      *
      * @see {@link mergeAll} for merging more than two contexts at once
@@ -1556,9 +1498,8 @@ export declare const merge: {
  *
  * **Example** (Merging multiple contexts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1574,9 +1515,7 @@ export declare const merge: {
  *   thirdContext
  * )
  *
- * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
- * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
- * assert.deepStrictEqual(Context.get(context, Host), { HOST: "localhost" })
+ * context.mapUnsafe.size // => 3
  * ```
  *
  * @see {@link merge} for merging two contexts
@@ -1594,9 +1533,8 @@ export declare const mergeAll: <T extends Array<unknown>>(...ctxs: [...{ [K in k
  *
  * **Example** (Picking services from a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Option, pipe } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1608,11 +1546,8 @@ export declare const mergeAll: <T extends Array<unknown>>(...ctxs: [...{ [K in k
  *
  * const context = pipe(someContext, Context.pick(Port))
  *
- * assert.deepStrictEqual(
- *   Context.getOption(context, Port),
- *   Option.some({ PORT: 8080 })
- * )
- * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+ * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+ * Context.getOption(context, Timeout) // => Option.none()
  * ```
  *
  * @see {@link omit} for removing selected services
@@ -1630,9 +1565,8 @@ export declare const pick: <S extends ReadonlyArray<Key<any, any>>>(...services:
  *
  * **Example** (Omitting services from a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Option, pipe } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1644,11 +1578,8 @@ export declare const pick: <S extends ReadonlyArray<Key<any, any>>>(...services:
  *
  * const context = pipe(someContext, Context.omit(Timeout))
  *
- * assert.deepStrictEqual(
- *   Context.getOption(context, Port),
- *   Option.some({ PORT: 8080 })
- * )
- * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+ * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+ * Context.getOption(context, Timeout) // => Option.none()
  * ```
  *
  * @see {@link pick} for keeping selected services
@@ -1657,64 +1588,6 @@ export declare const pick: <S extends ReadonlyArray<Key<any, any>>>(...services:
  * @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]>>>;
-/**
- * Performs a series of mutations on a `Context`. Prevents unnecessary copying
- * of the underlying map when multiple mutations are needed.
- *
- * **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 mutations
- * @since 4.0.0
- */
-export declare const mutate: {
-    /**
-     * Performs a series of mutations on a `Context`. Prevents unnecessary copying
-     * of the underlying map when multiple mutations are needed.
-     *
-     * **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 mutations
-     * @since 4.0.0
-     */
-    <Services, B>(f: (context: Context<Services>) => Context<B>): <Services>(self: Context<Services>) => Context<B>;
-    /**
-     * Performs a series of mutations on a `Context`. Prevents unnecessary copying
-     * of the underlying map when multiple mutations are needed.
-     *
-     * **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 mutations
-     * @since 4.0.0
-     */
-    <Services, B>(self: Context<Services>, f: (context: Context<Services>) => Context<B>): Context<B>;
-};
 /**
  * Creates a context key with a default value.
  *
@@ -1733,12 +1606,13 @@ export declare const mutate: {
  *
  * **Example** (Creating references with default values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Create a reference with a default value
+ * const messages: Array<string> = []
  * const LoggerRef = Context.Reference("Logger", {
- *   defaultValue: () => ({ log: (msg: string) => console.log(msg) })
+ *   defaultValue: () => ({ log: (msg: string) => messages.push(`Default: ${msg}`) })
  * })
  *
  * // The reference provides the default value when accessed from an empty context
@@ -1747,14 +1621,17 @@ export declare const mutate: {
  *
  * // You can also override the default value
  * const customContext = Context.make(LoggerRef, {
- *   log: (msg: string) => `Custom: ${msg}`
+ *   log: (msg: string) => messages.push(`Custom: ${msg}`)
  * })
  * const customLogger = Context.get(customContext, LoggerRef)
+ * logger.log("default")
+ * customLogger.log("message")
+ * messages // => ["Default: default", "Custom: message"]
  * ```
  *
  * @see {@link Service} for required services without default values
  *
- * @category references
+ * @category services
  * @since 3.11.0
  */
 export declare const Reference: <Service>(key: string, options: {