.opencode/node_modules/effect/src/Context.ts

/**
 * Stores Effect services in typed maps.
 *
 * A `Context` holds service implementations under `Context.Service` or
 * `Context.Reference` keys, and its type records which keys are present.
 * Effects use contexts as their environment, so services can be provided once
 * instead of passed through every function call. This module includes helpers
 * for creating keys, building contexts, adding and reading services, merging
 * contexts, and selecting or removing services.
 *
 * @since 4.0.0
 */
import type { Effect, EffectIterator } from "./Effect.ts"
import * as Effectable from "./Effectable.ts"
import * as Equal from "./Equal.ts"
import { dual, type LazyArg } from "./Function.ts"
import * as Hash from "./Hash.ts"
import type { Inspectable } from "./Inspectable.ts"
import { exitSucceed, PipeInspectableProto, withFiber } from "./internal/core.ts"
import type { ErrorWithStackTraceLimit } from "./internal/tracer.ts"
import * as Option from "./Option.ts"
import type { Pipeable } from "./Pipeable.ts"
import { hasProperty } from "./Predicate.ts"
import type * as Types from "./Types.ts"

/**
 * String literal type used as the runtime type identifier for `Context`
 * service keys.
 *
 * @category type IDs
 * @since 4.0.0
 */
export type ServiceTypeId = "~effect/Context/Service"

/**
 * Runtime type identifier attached to `Context` service keys and used by
 * `isKey` to recognize them.
 *
 * @category type IDs
 * @since 4.0.0
 */
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
 * 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.
 *
 * @see {@link Service} for creating required service keys
 * @see {@link Reference} for creating service keys with default values
 *
 * @category models
 * @since 4.0.0
 */
export interface Key<out Identifier, out Shape> extends Effect<Shape, never, Identifier> {
  readonly [ServiceTypeId]: ServiceTypeId
  readonly Service: Shape
  readonly Identifier: Identifier
  readonly key: string
  readonly stack?: string | undefined
}

/**
 * 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"
 *
 * // Define an identifier for a database service
 * const Database = Context.Service<{ query: (sql: string) => string }>(
 *   "Database"
 * )
 *
 * // The key can be used to store and retrieve services
 * const context = Context.make(Database, { query: (sql) => `Result: ${sql}` })
 * ```
 *
 * @category models
 * @since 4.0.0
 */
export interface Service<in out Identifier, in out Shape> extends Key<Identifier, Shape> {
  of(this: void, self: Shape): Shape
  context(self: Shape): Context<Identifier>
  use<A, E, R>(f: (service: Shape) => Effect<A, E, R>): Effect<A, E, R | Identifier>
  useSync<A>(f: (service: Shape) => A): Effect<A, never, 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**
 *
 * 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
 */
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
 */
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
   */
  export interface Shape<Identifier extends string, Service> {
    readonly [ServiceTypeId]: typeof ServiceTypeId
    readonly key: Identifier
    readonly Service: Service
  }
}

/**
 * Creates a `Context` service key.
 *
 * **When to use**
 *
 * Use when you need to define a context service key for a dependency that must
 * be provided by the surrounding context.
 *
 * **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.
 *
 * **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
 * import { Context } from "effect"
 *
 * // Create a simple service
 * const Database = Context.Service<{
 *   query: (sql: string) => string
 * }>("Database")
 *
 * // Create a service class
 * class Config extends Context.Service<Config, {
 *   port: number
 * }>()("Config") {}
 *
 * // Use the services to create contexts
 * const db = Context.make(Database, {
 *   query: (sql) => `Result: ${sql}`
 * })
 * const config = Context.make(Config, { port: 8080 })
 * ```
 *
 * @see {@link Reference} for service keys with default values
 *
 * @category constructors
 * @since 4.0.0
 */
export const Service: {
  /**
   * Creates a `Context` service key.
   *
   * **When to use**
   *
   * Use when you need to define a context service key for a dependency that must
   * be provided by the surrounding context.
   *
   * **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.
   *
   * **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
   * import { Context } from "effect"
   *
   * // Create a simple service
   * const Database = Context.Service<{
   *   query: (sql: string) => string
   * }>("Database")
   *
   * // Create a service class
   * class Config extends Context.Service<Config, {
   *   port: number
   * }>()("Config") {}
   *
   * // Use the services to create contexts
   * const db = Context.make(Database, {
   *   query: (sql) => `Result: ${sql}`
   * })
   * const config = Context.make(Config, { port: 8080 })
   * ```
   *
   * @see {@link Reference} for service keys with default values
   *
   * @category constructors
   * @since 4.0.0
   */
  <Identifier, Shape = Identifier>(key: string): Service<Identifier, Shape>
  /**
   * Creates a `Context` service key.
   *
   * **When to use**
   *
   * Use when you need to define a context service key for a dependency that must
   * be provided by the surrounding context.
   *
   * **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.
   *
   * **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
   * import { Context } from "effect"
   *
   * // Create a simple service
   * const Database = Context.Service<{
   *   query: (sql: string) => string
   * }>("Database")
   *
   * // Create a service class
   * class Config extends Context.Service<Config, {
   *   port: number
   * }>()("Config") {}
   *
   * // Use the services to create contexts
   * const db = Context.make(Database, {
   *   query: (sql) => `Result: ${sql}`
   * })
   * const config = Context.make(Config, { port: 8080 })
   * ```
   *
   * @see {@link Reference} for service keys with default values
   *
   * @category constructors
   * @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
    } | 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> })
  /**
   * Creates a `Context` service key.
   *
   * **When to use**
   *
   * Use when you need to define a context service key for a dependency that must
   * be provided by the surrounding context.
   *
   * **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.
   *
   * **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
   * import { Context } from "effect"
   *
   * // Create a simple service
   * const Database = Context.Service<{
   *   query: (sql: string) => string
   * }>("Database")
   *
   * // Create a service class
   * class Config extends Context.Service<Config, {
   *   port: number
   * }>()("Config") {}
   *
   * // Use the services to create contexts
   * const db = Context.make(Database, {
   *   query: (sql) => `Result: ${sql}`
   * })
   * const config = Context.make(Config, { port: 8080 })
   * ```
   *
   * @see {@link Reference} for service keys with default values
   *
   * @category constructors
   * @since 4.0.0
   */
  <Self>(): <
    const Identifier extends string,
    Make extends Effect<any, any, any> | ((...args: any) => Effect<any, any, any>)
  >(
    id: Identifier,
    options: {
      readonly make: Make
    }
  ) =>
    & ServiceClass<
      Self,
      Identifier,
      Make extends
        Effect<infer _A, infer _E, infer _R> | ((...args: infer _Args) => Effect<infer _A, infer _E, infer _R>) ? _A
        : never
    >
    & { readonly make: Make }
} = function() {
  const prevLimit = (Error as ErrorWithStackTraceLimit).stackTraceLimit
  ;(Error as ErrorWithStackTraceLimit)
    .stackTraceLimit = 2
  const err = new Error()
  ;(Error as ErrorWithStackTraceLimit).stackTraceLimit = prevLimit
  function KeyClass() {}
  const self = KeyClass as any as Types.Mutable<Reference<any>>
  Object.setPrototypeOf(self, ServiceProto)
  // @effect-diagnostics-next-line floatingEffect:off
  Object.defineProperty(self, "stack", {
    get() {
      return err.stack
    }
  })
  if (arguments.length > 0) {
    self.key = arguments[0]
    if (arguments[1]?.defaultValue) {
      self[ReferenceTypeId] = ReferenceTypeId
      self.defaultValue = arguments[1].defaultValue
    }
    return self
  }
  return function(key: string, options?: {
    readonly make?: any
  }) {
    self.key = key
    if (options?.make) {
      ;(self as any).make = options.make
    }
    return self
  }
} as any

const ServiceProto: any = {
  [ServiceTypeId]: ServiceTypeId,
  ...Effectable.Prototype<Service<never, any>>({
    label: "Service",
    evaluate(fiber) {
      return exitSucceed(get(fiber.context, this))
    }
  }),
  toJSON<I, A>(this: Service<I, A>) {
    return {
      _id: "Service",
      key: this.key,
      stack: this.stack
    }
  },
  of<Service>(this: void, self: Service): Service {
    return self
  },
  context<Identifier, Shape>(
    this: Service<Identifier, Shape>,
    self: Shape
  ): Context<Identifier> {
    return make(this, self)
  },
  use<A, E, R>(this: Service<never, any>, f: (service: any) => Effect<A, E, R>): Effect<A, E, R> {
    return withFiber((fiber) => f(get(fiber.context, this)))
  },
  useSync<A>(this: Service<never, any>, f: (service: any) => A): Effect<A, never, never> {
    return withFiber((fiber) => exitSucceed(f(get(fiber.context, this))))
  }
}

const ReferenceTypeId = "~effect/Context/Reference" as const

/**
 * 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"
 *
 * // Define a reference with a default value
 * const LoggerRef: Context.Reference<{ log: (msg: string) => void }> =
 *   Context.Reference("Logger", {
 *     defaultValue: () => ({ log: (msg: string) => console.log(msg) })
 *   })
 *
 * // The reference can be used without explicit provision
 * const context = Context.empty()
 * const logger = Context.get(context, LoggerRef) // Uses default value
 * ```
 *
 * @category models
 * @since 3.11.0
 */
export interface Reference<in out Shape> extends Service<never, Shape> {
  readonly [ReferenceTypeId]: typeof ReferenceTypeId
  readonly defaultValue: () => Shape
  [Symbol.iterator](): EffectIterator<Reference<Shape>>
  new(_: never): {}
}

/**
 * Namespace containing utility types for `Context` service keys.
 *
 * **Example** (Extracting service types)
 *
 * ```ts
 * import { Context } from "effect"
 *
 * const Database = Context.Service<{
 *   query: (sql: string) => string
 * }>("Database")
 *
 * // Extract service type from a key
 * type DatabaseService = Context.Service.Shape<typeof Database>
 *
 * // Extract identifier type from a key
 * type DatabaseId = Context.Service.Identifier<typeof Database>
 * ```
 *
 * @since 2.0.0
 */
export declare namespace Service {
  /**
   * Type that matches any `Context` service key regardless of its identifier or
   * service shape.
   *
   * **Example** (Typing any service key)
   *
   * ```ts
   * import { Context } from "effect"
   *
   * // Any represents any possible service type
   * const services: Array<Context.Service.Any> = [
   *   Context.Service<{ log: (msg: string) => void }>("Logger"),
   *   Context.Service<{ query: (sql: string) => string }>("Database")
   * ]
   * ```
   *
   * @category models
   * @since 4.0.0
   */
  export type Any = Key<never, any> | Key<any, any>

  /**
   * Extracts the service implementation type stored behind a `Context` service
   * key.
   *
   * **Example** (Extracting a service shape)
   *
   * ```ts
   * import { Context } from "effect"
   *
   * const Database = Context.Service<{ query: (sql: string) => string }>(
   *   "Database"
   * )
   *
   * // Extract the service shape from the service
   * type DatabaseService = Context.Service.Shape<typeof Database>
   * // DatabaseService is { query: (sql: string) => string }
   * ```
   *
   * @category models
   * @since 4.0.0
   */
  export type Shape<T> = T extends Key<infer _I, infer S> ? S : never

  /**
   * Extracts the identifier, or requirement type, associated with a `Context`
   * service key.
   *
   * **Example** (Extracting a service identifier)
   *
   * ```ts
   * import { Context } from "effect"
   *
   * const Database = Context.Service<{ query: (sql: string) => string }>(
   *   "Database"
   * )
   *
   * // Extract the identifier type from a key
   * type DatabaseId = Context.Service.Identifier<typeof Database>
   * // DatabaseId is the identifier type
   * ```
   *
   * @category models
   * @since 2.0.0
   */
  export type Identifier<T> = T extends Key<infer I, infer _S> ? I : never
}

const TypeId = "~effect/Context" as const

/**
 * 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"
 *
 * // Create a context with multiple services
 * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
 * const Database = Context.Service<{ query: (sql: string) => string }>(
 *   "Database"
 * )
 *
 * const context = Context.make(Logger, {
 *   log: (msg: string) => console.log(msg)
 * })
 *   .pipe(Context.add(Database, { query: (sql) => `Result: ${sql}` }))
 * ```
 *
 * @category models
 * @since 2.0.0
 */
export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable {
  readonly [TypeId]: {
    readonly _Services: Types.Contravariant<Services>
  }
  readonly mapUnsafe: ReadonlyMap<string, any>
  mutable: boolean
}

/**
 * Creates a `Context` from an existing service map.
 *
 * **When to use**
 *
 * Use when constructing a low-level `Context` from a trusted map whose lifecycle
 * you control.
 *
 * **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.
 *
 * **Example** (Creating a context from a map)
 *
 * ```ts
 * import { Context } from "effect"
 *
 * // Create a context from a Map (unsafe)
 * const map = new Map([
 *   ["Logger", { log: (msg: string) => console.log(msg) }]
 * ])
 *
 * const context = Context.makeUnsafe(map)
 * ```
 *
 * @category constructors
 * @since 4.0.0
 */
export const makeUnsafe = <Services = never>(mapUnsafe: ReadonlyMap<string, any>): Context<Services> => {
  const self = Object.create(Proto)
  self.mapUnsafe = mapUnsafe
  self.mutable = false
  return self
}

const Proto: Omit<Context<never>, "mapUnsafe" | "mutable"> = {
  ...PipeInspectableProto,
  [TypeId]: {
    _Services: (_: never) => _
  },
  toJSON(this: Context<never>) {
    return {
      _id: "Context",
      services: Array.from(this.mapUnsafe).map(([key, value]) => ({ key, value }))
    }
  },
  [Equal.symbol]<A>(this: Context<A>, that: unknown): boolean {
    if (
      !isContext(that)
      || this.mapUnsafe.size !== that.mapUnsafe.size
    ) return false
    for (const k of this.mapUnsafe.keys()) {
      if (
        !that.mapUnsafe.has(k) ||
        !Equal.equals(this.mapUnsafe.get(k), that.mapUnsafe.get(k))
      ) {
        return false
      }
    }
    return true
  },
  [Hash.symbol]<A>(this: Context<A>): number {
    return Hash.number(this.mapUnsafe.size)
  }
}

/**
 * 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)
 *
 * ```ts
 * import { Context } from "effect"
 * import * as assert from "node:assert"
 *
 * 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 whether the provided argument is a `Key`.
 *
 * **Example** (Checking for keys)
 *
 * ```ts
 * import { Context } from "effect"
 * import * as assert from "node:assert"
 *
 * assert.strictEqual(Context.isKey(Context.Service("Service")), true)
 * ```
 *
 * @category guards
 * @since 4.0.0
 */
export const isKey = (u: unknown): u is Key<any, any> => hasProperty(u, ServiceTypeId)

/**
 * Checks whether the provided argument is a `Reference`.
 *
 * **Example** (Checking for references)
 *
 * ```ts
 * import { Context } from "effect"
 * import * as assert from "node:assert"
 *
 * const LoggerRef = Context.Reference("Logger", {
 *   defaultValue: () => ({ log: (msg: string) => console.log(msg) })
 * })
 *
 * assert.strictEqual(Context.isReference(LoggerRef), true)
 * assert.strictEqual(Context.isReference(Context.Service("Key")), false)
 * ```
 *
 * @category guards
 * @since 3.11.0
 */
export const isReference = (u: unknown): u is Reference<any> => hasProperty(u, ReferenceTypeId)

/**
 * Returns an empty `Context`.
 *
 * **Example** (Creating an empty context)
 *
 * ```ts
 * import { Context } from "effect"
 * import * as assert from "node:assert"
 *
 * assert.strictEqual(Context.isContext(Context.empty()), true)
 * ```
 *
 * @category constructors
 * @since 2.0.0
 */
export const empty = (): Context<never> => emptyContext
const emptyContext = makeUnsafe(new Map())

/**
 * Creates a new `Context` with a single service associated to the key.
 *
 * **Example** (Creating a context with one service)
 *
 * ```ts
 * 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 })
 * ```
 *
 * @category constructors
 * @since 2.0.0
 */
export const make = <I, S>(
  key: Key<I, S>,
  service: Types.NoInfer<S>
): Context<I> => makeUnsafe(new Map([[key.key, service]]))

/**
 * Adds a service to a given `Context`.
 *
 * **When to use**
 *
 * Use when you need to store a known service value in a `Context`.
 *
 * **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
 * 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")
 *
 * const someContext = Context.make(Port, { PORT: 8080 })
 *
 * const context = pipe(
 *   someContext,
 *   Context.add(Timeout, { TIMEOUT: 5000 })
 * )
 *
 * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
 * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
 * ```
 *
 * @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 need to store a known service value in a `Context`.
   *
   * **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
   * 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")
   *
   * const someContext = Context.make(Port, { PORT: 8080 })
   *
   * const context = pipe(
   *   someContext,
   *   Context.add(Timeout, { TIMEOUT: 5000 })
   * )
   *
   * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
   * ```
   *
   * @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 need to store a known service value in a `Context`.
   *
   * **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
   * 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")
   *
   * const someContext = Context.make(Port, { PORT: 8080 })
   *
   * const context = pipe(
   *   someContext,
   *   Context.add(Timeout, { TIMEOUT: 5000 })
   * )
   *
   * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
   * ```
   *
   * @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>
} = dual(3, <Services, I, S>(
  self: Context<Services>,
  key: Key<I, S>,
  service: Types.NoInfer<S>
): Context<Services | I> =>
  withMapUnsafe(self, (map) => {
    map.set(key.key, service)
  }))

/**
 * Adds or removes a service depending on an `Option`.
 *
 * **When to use**
 *
 * Use when you need to add or omit a `Context` service based 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`.
 *
 * **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 you need to add or omit a `Context` service based 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`.
   *
   * **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 you need to add or omit a `Context` service based 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`.
   *
   * **Example** (Adding optional services)
   *
   * ```ts
   * import { Context, Option } from "effect"
   *
   * const Port = Context.Service<{ PORT: number }>("Port")
   *
   * const withPort = Context.empty().pipe(
   *   Context.addOrOmit(Port, Option.some({ PORT: 8080 }))
   * )
   *
   * const withoutPort = withPort.pipe(
   *   Context.addOrOmit(Port, Option.none())
   * )
   * ```
   *
   * @see {@link add} for always storing a service value
   *
   * @category adders
   * @since 4.0.0
   */
  <Services, I, S>(
    self: Context<Services>,
    key: Key<I, S>,
    service: Option.Option<Types.NoInfer<S>>
  ): Context<Services | I>
} = dual(3, <Services, I, S>(
  self: Context<Services>,
  key: Key<I, S>,
  service: Option.Option<Types.NoInfer<S>>
): Context<Services | I> =>
  withMapUnsafe(self, (map) => {
    if (service._tag === "None") {
      map.delete(key.key)
    } else {
      map.set(key.key, service.value)
    }
  }))

/**
 * Gets the service for a key, or evaluates the fallback when a non-reference
 * key is absent.
 *
 * **When to use**
 *
 * Use when you need a fallback for a missing `Context.Service` key while still
 * resolving `Context.Reference` defaults.
 *
 * **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
 * import { Context } from "effect"
 *
 * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
 * const Database = Context.Service<{ query: (sql: string) => string }>(
 *   "Database"
 * )
 *
 * const context = Context.make(Logger, {
 *   log: (msg: string) => console.log(msg)
 * })
 *
 * const logger = Context.getOrElse(context, Logger, () => ({ log: () => {} }))
 * const database = Context.getOrElse(
 *   context,
 *   Database,
 *   () => ({ query: () => "fallback" })
 * )
 *
 * console.log(logger === Context.get(context, Logger)) // true
 * 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
 */
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 need a fallback for a missing `Context.Service` key while still
   * resolving `Context.Reference` defaults.
   *
   * **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
   * import { Context } from "effect"
   *
   * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
   * const Database = Context.Service<{ query: (sql: string) => string }>(
   *   "Database"
   * )
   *
   * const context = Context.make(Logger, {
   *   log: (msg: string) => console.log(msg)
   * })
   *
   * const logger = Context.getOrElse(context, Logger, () => ({ log: () => {} }))
   * const database = Context.getOrElse(
   *   context,
   *   Database,
   *   () => ({ query: () => "fallback" })
   * )
   *
   * console.log(logger === Context.get(context, Logger)) // true
   * 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
   */
  <S, I, B>(key: Key<I, S>, orElse: LazyArg<B>): <Services>(self: Context<Services>) => S | B
  /**
   * Gets the service for a key, or evaluates the fallback when a non-reference
   * key is absent.
   *
   * **When to use**
   *
   * Use when you need a fallback for a missing `Context.Service` key while still
   * resolving `Context.Reference` defaults.
   *
   * **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
   * import { Context } from "effect"
   *
   * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
   * const Database = Context.Service<{ query: (sql: string) => string }>(
   *   "Database"
   * )
   *
   * const context = Context.make(Logger, {
   *   log: (msg: string) => console.log(msg)
   * })
   *
   * const logger = Context.getOrElse(context, Logger, () => ({ log: () => {} }))
   * const database = Context.getOrElse(
   *   context,
   *   Database,
   *   () => ({ query: () => "fallback" })
   * )
   *
   * console.log(logger === Context.get(context, Logger)) // true
   * 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
   */
  <Services, S, I, B>(self: Context<Services>, key: Key<I, S>, orElse: LazyArg<B>): S | B
} = dual(3, <Services, S, I, B>(self: Context<Services>, key: Key<I, S>, orElse: LazyArg<B>): S | B => {
  if (self.mapUnsafe.has(key.key)) {
    return self.mapUnsafe.get(key.key)! as any
  }
  return isReference(key) ? getDefaultValue(key) : orElse()
})

/**
 * Returns the service currently stored for a key, or `undefined` when the key
 * is absent.
 *
 * **When to use**
 *
 * Use when you need to read the service stored for a key without resolving
 * `Context.Reference` defaults.
 *
 * **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
 */
export const getOrUndefined: {
  /**
   * Returns the service currently stored for a key, or `undefined` when the key
   * is absent.
   *
   * **When to use**
   *
   * Use when you need to read the service stored for a key without resolving
   * `Context.Reference` defaults.
   *
   * **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
   */
  <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.
   *
   * **When to use**
   *
   * Use when you need to read the service stored for a key without resolving
   * `Context.Reference` defaults.
   *
   * **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
   */
  <Services, S, I>(self: Context<Services>, key: Key<I, S>): S | undefined
} = dual(
  2,
  <Services, S, I>(self: Context<Services>, key: Key<I, S>): S | undefined => self.mapUnsafe.get(key.key)
)

/**
 * Gets the service for a key, throwing if an absent non-reference key cannot be
 * resolved.
 *
 * **When to use**
 *
 * Use when you need to read a service from a context whose type does not prove
 * the service is present.
 *
 * **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.
 *
 * **Example** (Getting services unsafely)
 *
 * ```ts
 * import { Context } 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.getUnsafe(context, Port), { PORT: 8080 })
 * 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
 */
export const getUnsafe: {
  /**
   * Gets the service for a key, throwing if an absent non-reference key cannot be
   * resolved.
   *
   * **When to use**
   *
   * Use when you need to read a service from a context whose type does not prove
   * the service is present.
   *
   * **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.
   *
   * **Example** (Getting services unsafely)
   *
   * ```ts
   * import { Context } 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.getUnsafe(context, Port), { PORT: 8080 })
   * 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
   */
  <S, I>(service: Key<I, S>): <Services>(self: Context<Services>) => S
  /**
   * Gets the service for a key, throwing if an absent non-reference key cannot be
   * resolved.
   *
   * **When to use**
   *
   * Use when you need to read a service from a context whose type does not prove
   * the service is present.
   *
   * **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.
   *
   * **Example** (Getting services unsafely)
   *
   * ```ts
   * import { Context } 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.getUnsafe(context, Port), { PORT: 8080 })
   * assert.throws(() => Context.getUnsafe(context, Timeout))
   * ```
   *
   * @see {@link get} for type-checked service access
   * @see {@link getOption} for optional service access
   *
   * @category unsafe
   * @since 4.0.0
   */
  <Services, S, I>(self: Context<Services>, services: Key<I, S>): S
} = dual(
  2,
  <Services, I extends Services, S>(self: Context<Services>, service: Key<I, S>): S => {
    if (!self.mapUnsafe.has(service.key)) {
      if (ReferenceTypeId in service) return getDefaultValue(service as any)
      throw serviceNotFoundError(service)
    }
    return self.mapUnsafe.get(service.key)! as any
  }
)

/**
 * Gets a service from the context that corresponds to the given key.
 *
 * **When to use**
 *
 * Use when you need type-checked access to a service already included in the
 * context type.
 *
 * **Example** (Getting a service from a context)
 *
 * ```ts
 * 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")
 *
 * const context = pipe(
 *   Context.make(Port, { PORT: 8080 }),
 *   Context.add(Timeout, { TIMEOUT: 5000 })
 * )
 *
 * 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: {
  /**
   * Gets a service from the context that corresponds to the given key.
   *
   * **When to use**
   *
   * Use when you need type-checked access to a service already included in the
   * context type.
   *
   * **Example** (Getting a service from a context)
   *
   * ```ts
   * 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")
   *
   * const context = pipe(
   *   Context.make(Port, { PORT: 8080 }),
   *   Context.add(Timeout, { TIMEOUT: 5000 })
   * )
   *
   * 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
  /**
   * Gets a service from the context that corresponds to the given key.
   *
   * **When to use**
   *
   * Use when you need type-checked access to a service already included in the
   * context type.
   *
   * **Example** (Getting a service from a context)
   *
   * ```ts
   * 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")
   *
   * const context = pipe(
   *   Context.make(Port, { PORT: 8080 }),
   *   Context.add(Timeout, { TIMEOUT: 5000 })
   * )
   *
   * 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>(self: Context<Services>, service: Key<I, S>): S
} = getUnsafe

/**
 * 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 const getReferenceUnsafe = <Services, S>(self: Context<Services>, service: Reference<S>): S => {
  if (!self.mapUnsafe.has(service.key)) {
    return getDefaultValue(service as any)
  }
  return self.mapUnsafe.get(service.key)! as any
}

const defaultValueCacheKey = "~effect/Context/defaultValue" as const

const getDefaultValue = (ref: Reference<any>) => {
  if (defaultValueCacheKey in ref) {
    return ref[defaultValueCacheKey] as any
  }
  return (ref as any)[defaultValueCacheKey] = ref.defaultValue()
}

const serviceNotFoundError = (service: Key<any, any>) => {
  const error = new Error(
    `Service not found${service.key ? `: ${String(service.key)}` : ""}`
  )
  if (service.stack) {
    const lines = service.stack.split("\n")
    if (lines.length > 2) {
      const afterAt = lines[2].match(/at (.*)/)
      if (afterAt) {
        error.message = error.message + ` (defined at ${afterAt[1]})`
      }
    }
  }
  if (error.stack) {
    const lines = error.stack.split("\n")
    lines.splice(1, 3)
    error.stack = lines.join("\n")
  }
  return error
}

/**
 * Gets the service for a key safely wrapped in an `Option`.
 *
 * **When to use**
 *
 * Use when you need to read a `Context` service as an `Option` so absence is
 * represented as data.
 *
 * **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`.
 *
 * **Example** (Getting optional services)
 *
 * ```ts
 * 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())
 * ```
 *
 * @see {@link getOrElse} for returning a fallback value directly
 *
 * @category getters
 * @since 2.0.0
 */
export const getOption: {
  /**
   * Gets the service for a key safely wrapped in an `Option`.
   *
   * **When to use**
   *
   * Use when you need to read a `Context` service as an `Option` so absence is
   * represented as data.
   *
   * **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`.
   *
   * **Example** (Getting optional services)
   *
   * ```ts
   * 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())
   * ```
   *
   * @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 safely wrapped in an `Option`.
   *
   * **When to use**
   *
   * Use when you need to read a `Context` service as an `Option` so absence is
   * represented as data.
   *
   * **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`.
   *
   * **Example** (Getting optional services)
   *
   * ```ts
   * 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())
   * ```
   *
   * @see {@link getOrElse} for returning a fallback value directly
   *
   * @category getters
   * @since 2.0.0
   */
  <Services, S, I>(self: Context<Services>, service: Key<I, S>): Option.Option<S>
} = dual(2, <Services, I extends Services, S>(self: Context<Services>, service: Key<I, S>): Option.Option<S> => {
  if (self.mapUnsafe.has(service.key)) {
    return Option.some(self.mapUnsafe.get(service.key)! as any)
  }
  return isReference(service) ? Option.some(getDefaultValue(service as any)) : Option.none()
})

/**
 * Merges two `Context`s into one.
 *
 * **When to use**
 *
 * Use when you need to combine two contexts.
 *
 * **Details**
 *
 * When both contexts contain the same service key, the service from `that`
 * overrides the service from `self`.
 *
 * **Example** (Merging two contexts)
 *
 * ```ts
 * import { Context } from "effect"
 * import * as assert from "node:assert"
 *
 * const Port = Context.Service<{ PORT: number }>("Port")
 * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
 *
 * const firstContext = Context.make(Port, { PORT: 8080 })
 * const secondContext = Context.make(Timeout, { TIMEOUT: 5000 })
 *
 * const context = Context.merge(firstContext, secondContext)
 *
 * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
 * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
 * ```
 *
 * @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 you need to combine two contexts.
   *
   * **Details**
   *
   * When both contexts contain the same service key, the service from `that`
   * overrides the service from `self`.
   *
   * **Example** (Merging two contexts)
   *
   * ```ts
   * import { Context } from "effect"
   * import * as assert from "node:assert"
   *
   * const Port = Context.Service<{ PORT: number }>("Port")
   * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
   *
   * const firstContext = Context.make(Port, { PORT: 8080 })
   * const secondContext = Context.make(Timeout, { TIMEOUT: 5000 })
   *
   * const context = Context.merge(firstContext, secondContext)
   *
   * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
   * ```
   *
   * @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 you need to combine two contexts.
   *
   * **Details**
   *
   * When both contexts contain the same service key, the service from `that`
   * overrides the service from `self`.
   *
   * **Example** (Merging two contexts)
   *
   * ```ts
   * import { Context } from "effect"
   * import * as assert from "node:assert"
   *
   * const Port = Context.Service<{ PORT: number }>("Port")
   * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
   *
   * const firstContext = Context.make(Port, { PORT: 8080 })
   * const secondContext = Context.make(Timeout, { TIMEOUT: 5000 })
   *
   * const context = Context.merge(firstContext, secondContext)
   *
   * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
   * ```
   *
   * @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>
} = dual(2, <Services, R1>(self: Context<Services>, that: Context<R1>): Context<Services | R1> => {
  if (self.mapUnsafe.size === 0) return that as any
  if (that.mapUnsafe.size === 0) return self as any
  return withMapUnsafe(self, (map) => {
    that.mapUnsafe.forEach((value, key) => map.set(key, value))
  })
})

/**
 * Merges any number of `Context`s into one.
 *
 * **When to use**
 *
 * Use when you need to combine a variadic list of contexts.
 *
 * **Details**
 *
 * When multiple contexts contain the same service key, the service from the
 * last context with that key is kept.
 *
 * **Example** (Merging multiple contexts)
 *
 * ```ts
 * import { Context } from "effect"
 * import * as assert from "node:assert"
 *
 * const Port = Context.Service<{ PORT: number }>("Port")
 * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
 * const Host = Context.Service<{ HOST: string }>("Host")
 *
 * const firstContext = Context.make(Port, { PORT: 8080 })
 * const secondContext = Context.make(Timeout, { TIMEOUT: 5000 })
 * const thirdContext = Context.make(Host, { HOST: "localhost" })
 *
 * const context = Context.mergeAll(
 *   firstContext,
 *   secondContext,
 *   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" })
 * ```
 *
 * @see {@link merge} for merging two contexts
 *
 * @category combining
 * @since 3.12.0
 */
export const mergeAll = <T extends Array<unknown>>(
  ...ctxs: [...{ [K in keyof T]: Context<T[K]> }]
): Context<T[number]> => {
  const map = new Map()
  for (let i = 0; i < ctxs.length; i++) {
    ctxs[i].mapUnsafe.forEach((value, key) => {
      map.set(key, value)
    })
  }
  return makeUnsafe(map)
}

/**
 * Returns a new `Context` that contains only the specified services.
 *
 * **When to use**
 *
 * Use when you want to keep an allowlist of services in a `Context`.
 *
 * **Example** (Picking services from a context)
 *
 * ```ts
 * 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")
 *
 * const someContext = pipe(
 *   Context.make(Port, { PORT: 8080 }),
 *   Context.add(Timeout, { TIMEOUT: 5000 })
 * )
 *
 * 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())
 * ```
 *
 * @see {@link omit} for removing selected services
 *
 * @category filtering
 * @since 2.0.0
 */
export const pick = <S extends ReadonlyArray<Key<any, any>>>(
  ...services: S
) =>
<Services>(self: Context<Services>): Context<Services & Service.Identifier<S[number]>> =>
  withMapUnsafe(self, (map) => {
    const keySet = new Set(services.map((key) => key.key))
    map.forEach((_, key) => {
      if (keySet.has(key)) return
      map.delete(key)
    })
  })

/**
 * Returns a new `Context` with the specified service keys removed.
 *
 * **When to use**
 *
 * Use when you want to remove a denylist of services from a `Context`.
 *
 * **Example** (Omitting services from a context)
 *
 * ```ts
 * 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")
 *
 * const someContext = pipe(
 *   Context.make(Port, { PORT: 8080 }),
 *   Context.add(Timeout, { TIMEOUT: 5000 })
 * )
 *
 * 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())
 * ```
 *
 * @see {@link pick} for keeping selected services
 *
 * @category filtering
 * @since 2.0.0
 */
export const omit = <S extends ReadonlyArray<Key<any, any>>>(
  ...keys: S
) =>
<Services>(self: Context<Services>): Context<Exclude<Services, Service.Identifier<S[number]>>> =>
  withMapUnsafe(self, (map) => {
    for (let i = 0; i < keys.length; i++) {
      map.delete(keys[i].key)
    }
  })

/**
 * 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 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>
} = dual(
  2,
  <Services, B>(self: Context<Services>, f: (context: Context<Services>) => Context<B>): Context<B> => {
    const next = makeUnsafe</**
     * 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>(new Map(self.mapUnsafe))
    next.mutable = true
    const result = f(next)
    result.mutable = false
    return result
  }
)

const withMapUnsafe = <Services, B>(self: Context<Services>, f: (map: Map<string, any>) => void): Context<B> => {
  if (self.mutable) {
    f(self.mapUnsafe as any)
    return self as any
  }
  const map = new Map(self.mapUnsafe)
  f(map)
  return makeUnsafe(map)
}

/**
 * Creates a context key with a default value.
 *
 * **When to use**
 *
 * Use when you need to define a context key with a lazily computed default
 * value.
 *
 * **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. The default value is computed lazily and cached on the
 * reference.
 *
 * **Example** (Creating references with default values)
 *
 * ```ts
 * import { Context } from "effect"
 *
 * // Create a reference with a default value
 * const LoggerRef = Context.Reference("Logger", {
 *   defaultValue: () => ({ log: (msg: string) => console.log(msg) })
 * })
 *
 * // The reference provides the default value when accessed from an empty context
 * const context = Context.empty()
 * const logger = Context.get(context, LoggerRef)
 *
 * // You can also override the default value
 * const customContext = Context.make(LoggerRef, {
 *   log: (msg: string) => `Custom: ${msg}`
 * })
 * const customLogger = Context.get(customContext, LoggerRef)
 * ```
 *
 * @see {@link Service} for required services without default values
 *
 * @category references
 * @since 3.11.0
 */
export const Reference: <Service>(
  key: string,
  options: { readonly defaultValue: () => Service }
) => Reference<Service> = Service as any