effect 4.0.0-beta.98 → 4.0.0-rc.108

package/dist/Context.js

@@ -3,7 +3,6 @@ import * as Equal from "./Equal.js";
 import { dual } from "./Function.js";
 import * as Hash from "./Hash.js";
 import { exitSucceed, PipeInspectableProto, withFiber } from "./internal/core.js";
-import { getStackTraceLimit, setStackTraceLimit } from "./internal/stackTraceLimit.js";
 import * as Option from "./Option.js";
 import { hasProperty } from "./Predicate.js";
 /**
@@ -37,7 +36,7 @@ export const ServiceTypeId = "~effect/Context/Service";
  *
  * **Example** (Creating service keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Create a simple service
@@ -55,43 +54,35 @@ export const ServiceTypeId = "~effect/Context/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
  */
 export const Service = function () {
-  const prevLimit = getStackTraceLimit();
-  setStackTraceLimit(2);
-  const err = new Error();
-  setStackTraceLimit(prevLimit);
   function KeyClass() {}
   const self = KeyClass;
   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) {
+  const init = (key, options) => {
+    self.key = key;
+    if (options?.defaultValue) {
       self[ReferenceTypeId] = ReferenceTypeId;
-      self.defaultValue = arguments[1].defaultValue;
+      self.defaultValue = options.defaultValue;
     }
-    return self;
-  }
-  return function (key, options) {
-    self.key = key;
     if (options?.make) {
       ;
       self.make = options.make;
     }
+    if (options?.fiberCached) {
+      cacheKeys.add(key);
+    }
     return self;
   };
+  return arguments.length > 0 ? init(arguments[0], arguments[1]) : init;
 };
 const ServiceProto = {
   [ServiceTypeId]: ServiceTypeId,
@@ -104,8 +95,7 @@ const ServiceProto = {
   toJSON() {
     return {
       _id: "Service",
-      key: this.key,
-      stack: this.stack
+      key: this.key
     };
   },
   of(self) {
@@ -121,8 +111,57 @@ const ServiceProto = {
     return withFiber(fiber => exitSucceed(f(get(fiber.context, this))));
   }
 };
+const cacheKeys = /*#__PURE__*/new Set();
 const ReferenceTypeId = "~effect/Context/Reference";
 const TypeId = "~effect/Context";
+const MaxDepth = 8;
+const FlattenAfterBaseHits = 8;
+const makeImpl = (cacheRoot, base, overlay, depth) => {
+  const self = Object.create(Proto);
+  self.cacheRoot = cacheRoot ?? self;
+  self.base = base;
+  self.overlay = overlay;
+  self.depth = depth;
+  self._flat = undefined;
+  self.baseHits = 0;
+  return self;
+};
+const applyOverlays = (map, overlay) => {
+  if (!overlay) return;
+  applyOverlays(map, overlay.parent);
+  map.set(overlay.key, overlay.value);
+};
+const flatten = self => {
+  if (self._flat) return self._flat;
+  if (!self.overlay) return self._flat = self.base;
+  const map = new Map(self.base);
+  applyOverlays(map, self.overlay);
+  return self._flat = map;
+};
+const withFlat = (self, f) => {
+  const map = new Map(self.mapUnsafe);
+  f(map);
+  return makeUnsafe(map);
+};
+// A private symbol so user code cannot forge a value that reads as absent
+const notFound = /*#__PURE__*/Symbol();
+const lookup = (self, key) => {
+  const impl = self;
+  for (let overlay = impl.overlay; overlay; overlay = overlay.parent) {
+    if (overlay.key === key) return overlay.value;
+  }
+  const value = impl.base.get(key);
+  // Misses must not advance the counter: reference-default lookups miss the
+  // base on every fiber cache refresh, which would flatten every short-lived
+  // request context and reintroduce the O(services) per-request cost
+  if (value === undefined && !impl.base.has(key)) return notFound;
+  if (impl.overlay && ++impl.baseHits >= FlattenAfterBaseHits) {
+    impl.base = flatten(impl);
+    impl.overlay = undefined;
+    impl.depth = 0;
+  }
+  return value;
+};
 /**
  * Creates a `Context` from an existing service map.
  *
@@ -133,37 +172,36 @@ const TypeId = "~effect/Context";
  *
  * **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
  * @since 4.0.0
  */
-export const makeUnsafe = mapUnsafe => {
-  const self = Object.create(Proto);
-  self.mapUnsafe = mapUnsafe;
-  self.mutable = false;
-  return self;
-};
+export const makeUnsafe = mapUnsafe => makeImpl(undefined, mapUnsafe, undefined, 0);
 const Proto = {
   ...PipeInspectableProto,
   [TypeId]: {
     _Services: _ => _
   },
+  get mapUnsafe() {
+    return flatten(this);
+  },
   toJSON() {
     return {
       _id: "Context",
@@ -174,11 +212,12 @@ const Proto = {
     };
   },
   [Equal.symbol](that) {
-    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;
-      }
+    if (!isContext(that)) return false;
+    const self = this.mapUnsafe;
+    const other = that.mapUnsafe;
+    if (self.size !== other.size) return false;
+    for (const [key, value] of self) {
+      if (!other.has(key) || !Equal.equals(value, other.get(key))) return false;
     }
     return true;
   },
@@ -186,6 +225,8 @@ const Proto = {
     return Hash.number(this.mapUnsafe.size);
   }
 };
+/** @internal */
+export const hasSameCache = (self, that) => self.cacheRoot === that.cacheRoot;
 /**
  * Checks whether the provided argument is a `Context`.
  *
@@ -206,11 +247,9 @@ const Proto = {
  *
  * **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
@@ -225,11 +264,9 @@ export const isContext = u => hasProperty(u, TypeId);
  *
  * **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
@@ -241,32 +278,29 @@ export const isKey = u => hasProperty(u, ServiceTypeId);
  *
  * **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 const isReference = u => hasProperty(u, ReferenceTypeId);
+export const isReference = u => !!u[ReferenceTypeId];
 /**
  * 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
@@ -279,15 +313,14 @@ const emptyContext = /*#__PURE__*/makeUnsafe(/*#__PURE__*/new Map());
  *
  * **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
@@ -308,9 +341,8 @@ export const make = (key, service) => makeUnsafe(new Map([[key.key, service]]));
  *
  * **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")
@@ -322,18 +354,31 @@ export const make = (key, service) => makeUnsafe(new Map([[key.key, service]]));
  *   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 const add = /*#__PURE__*/dual(3, (self, key, service) => withMapUnsafe(self, map => {
-  map.set(key.key, service);
-}));
+export const add = /*#__PURE__*/dual(3, (self, key, service) => {
+  const impl = self;
+  const cacheRoot = cacheKeys.has(key.key) ? undefined : impl.cacheRoot;
+  if (impl.depth >= MaxDepth) {
+    // Rebase the overlay chain into a flat map, keeping the cacheRoot so a
+    // rebase on an ordinary key does not invalidate fiber caches
+    const map = new Map(impl.mapUnsafe);
+    map.set(key.key, service);
+    return makeImpl(cacheRoot, map, undefined, 0);
+  }
+  return makeImpl(cacheRoot, impl.base, {
+    key: key.key,
+    value: service,
+    parent: impl.overlay
+  }, impl.depth + 1);
+});
 /**
  * Adds or removes a service depending on an `Option`.
  *
@@ -348,7 +393,7 @@ export const add = /*#__PURE__*/dual(3, (self, key, service) => withMapUnsafe(se
  *
  * **Example** (Adding optional services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Option } from "effect"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
@@ -360,20 +405,16 @@ export const add = /*#__PURE__*/dual(3, (self, key, service) => withMapUnsafe(se
  * 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 const addOrOmit = /*#__PURE__*/dual(3, (self, key, service) => withMapUnsafe(self, map => {
-  if (service._tag === "None") {
-    map.delete(key.key);
-  } else {
-    map.set(key.key, service.value);
-  }
-}));
+export const addOrOmit = /*#__PURE__*/dual(3, (self, key, service) => service._tag === "None" ? omit(key)(self) : add(self, key, service.value));
 /**
  * Gets the service for a key, or evaluates the fallback when a non-reference
  * key is absent.
@@ -395,7 +436,7 @@ export const addOrOmit = /*#__PURE__*/dual(3, (self, key, service) => withMapUns
  *
  * **Example** (Falling back for missing services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
@@ -403,9 +444,7 @@ export const addOrOmit = /*#__PURE__*/dual(3, (self, key, service) => withMapUns
  *   "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(
@@ -414,8 +453,8 @@ export const addOrOmit = /*#__PURE__*/dual(3, (self, key, service) => withMapUns
  *   () => ({ 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
@@ -424,9 +463,8 @@ export const addOrOmit = /*#__PURE__*/dual(3, (self, key, service) => withMapUns
  * @since 3.7.0
  */
 export const getOrElse = /*#__PURE__*/dual(3, (self, key, orElse) => {
-  if (self.mapUnsafe.has(key.key)) {
-    return self.mapUnsafe.get(key.key);
-  }
+  const value = lookup(self, key.key);
+  if (value !== notFound) return value;
   return isReference(key) ? getDefaultValue(key) : orElse();
 });
 /**
@@ -448,7 +486,12 @@ export const getOrElse = /*#__PURE__*/dual(3, (self, key, orElse) => {
  * @category getters
  * @since 4.0.0
  */
-export const getOrUndefined = /*#__PURE__*/dual(2, (self, key) => self.mapUnsafe.get(key.key));
+export const getOrUndefined = /*#__PURE__*/dual(2, (self, key) => getOrUndefinedUnsafe(self, key.key));
+/** @internal */
+export const getOrUndefinedUnsafe = (self, key) => {
+  const value = lookup(self, key);
+  return value === notFound ? undefined : value;
+};
 /**
  * Gets the service for a key, throwing if an absent non-reference key cannot be
  * resolved.
@@ -466,17 +509,16 @@ export const getOrUndefined = /*#__PURE__*/dual(2, (self, key) => self.mapUnsafe
  *
  * **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
@@ -486,11 +528,12 @@ export const getOrUndefined = /*#__PURE__*/dual(2, (self, key) => self.mapUnsafe
  * @since 4.0.0
  */
 export const getUnsafe = /*#__PURE__*/dual(2, (self, service) => {
-  if (!self.mapUnsafe.has(service.key)) {
-    if (ReferenceTypeId in service) return getDefaultValue(service);
+  const value = lookup(self, service.key);
+  if (value === notFound) {
+    if (isReference(service)) return getDefaultValue(service);
     throw serviceNotFoundError(service);
   }
-  return self.mapUnsafe.get(service.key);
+  return value;
 });
 /**
  * Gets a service from the context that corresponds to the given key.
@@ -502,9 +545,8 @@ export const getUnsafe = /*#__PURE__*/dual(2, (self, service) => {
  *
  * **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")
@@ -514,7 +556,7 @@ export const getUnsafe = /*#__PURE__*/dual(2, (self, service) => {
  *   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
@@ -524,53 +566,6 @@ export const getUnsafe = /*#__PURE__*/dual(2, (self, service) => {
  * @since 2.0.0
  */
 export const get = 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 = (self, service) => {
-  if (!self.mapUnsafe.has(service.key)) {
-    return getDefaultValue(service);
-  }
-  return self.mapUnsafe.get(service.key);
-};
 const defaultValueCacheKey = "~effect/Context/defaultValue";
 const getDefaultValue = ref => {
   if (defaultValueCacheKey in ref) {
@@ -580,15 +575,6 @@ const getDefaultValue = ref => {
 };
 const serviceNotFoundError = service => {
   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);
@@ -612,20 +598,16 @@ const serviceNotFoundError = service => {
  *
  * **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
@@ -634,9 +616,8 @@ const serviceNotFoundError = service => {
  * @since 2.0.0
  */
 export const getOption = /*#__PURE__*/dual(2, (self, service) => {
-  if (self.mapUnsafe.has(service.key)) {
-    return Option.some(self.mapUnsafe.get(service.key));
-  }
+  const value = lookup(self, service.key);
+  if (value !== notFound) return Option.some(value);
   return isReference(service) ? Option.some(getDefaultValue(service)) : Option.none();
 });
 /**
@@ -653,9 +634,8 @@ export const getOption = /*#__PURE__*/dual(2, (self, service) => {
  *
  * **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")
@@ -665,8 +645,8 @@ export const getOption = /*#__PURE__*/dual(2, (self, service) => {
  *
  * 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
@@ -677,9 +657,7 @@ export const getOption = /*#__PURE__*/dual(2, (self, service) => {
 export const merge = /*#__PURE__*/dual(2, (self, that) => {
   if (self.mapUnsafe.size === 0) return that;
   if (that.mapUnsafe.size === 0) return self;
-  return withMapUnsafe(self, map => {
-    that.mapUnsafe.forEach((value, key) => map.set(key, value));
-  });
+  return withFlat(self, map => that.mapUnsafe.forEach((value, key) => map.set(key, value)));
 });
 /**
  * Merges any number of `Context`s into one.
@@ -695,9 +673,8 @@ export const merge = /*#__PURE__*/dual(2, (self, that) => {
  *
  * **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")
@@ -713,9 +690,7 @@ export const merge = /*#__PURE__*/dual(2, (self, that) => {
  *   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
@@ -741,9 +716,8 @@ export const mergeAll = (...ctxs) => {
  *
  * **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")
@@ -755,11 +729,8 @@ export const mergeAll = (...ctxs) => {
  *
  * 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
@@ -767,13 +738,12 @@ export const mergeAll = (...ctxs) => {
  * @category filtering
  * @since 2.0.0
  */
-export const pick = (...services) => self => withMapUnsafe(self, map => {
-  const keySet = new Set(services.map(key => key.key));
-  map.forEach((_, key) => {
-    if (keySet.has(key)) return;
-    map.delete(key);
-  });
-});
+export const pick = (...services) => self => {
+  const keep = new Set(services.map(key => key.key));
+  return withFlat(self, map => map.forEach((_, key) => {
+    if (!keep.has(key)) map.delete(key);
+  }));
+};
 /**
  * Returns a new `Context` with the specified service keys removed.
  *
@@ -783,9 +753,8 @@ export const pick = (...services) => self => withMapUnsafe(self, map => {
  *
  * **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")
@@ -797,11 +766,8 @@ export const pick = (...services) => self => withMapUnsafe(self, map => {
  *
  * 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
@@ -809,45 +775,11 @@ export const pick = (...services) => self => withMapUnsafe(self, map => {
  * @category filtering
  * @since 2.0.0
  */
-export const omit = (...keys) => self => withMapUnsafe(self, map => {
+export const omit = (...keys) => self => withFlat(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 = /*#__PURE__*/dual(2, (self, f) => {
-  const next = makeUnsafe(new Map(self.mapUnsafe));
-  next.mutable = true;
-  const result = f(next);
-  result.mutable = false;
-  return result;
-});
-const withMapUnsafe = (self, f) => {
-  if (self.mutable) {
-    f(self.mapUnsafe);
-    return self;
-  }
-  const map = new Map(self.mapUnsafe);
-  f(map);
-  return makeUnsafe(map);
-};
 /**
  * Creates a context key with a default value.
  *
@@ -866,12 +798,13 @@ const withMapUnsafe = (self, f) => {
  *
  * **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
@@ -880,14 +813,17 @@ const withMapUnsafe = (self, f) => {
  *
  * // 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 const Reference = Service;