effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/HashRing.ts

@@ -1,61 +1,11 @@
 /**
- * The `HashRing` module provides a weighted consistent-hashing data structure
- * for assigning arbitrary string inputs to a changing set of nodes. A hash ring
- * minimizes remapping when nodes are added, removed, or reweighted, which makes
- * it useful for routing requests, partitioning keys, and distributing shards
- * across service instances or storage backends.
- *
- * **Mental model**
- *
- * - Each node is identified by its {@link PrimaryKey.PrimaryKey} value
- * - {@link add} and {@link addMany} place weighted virtual points on the ring
- * - {@link get} hashes an input string and returns the nearest node on the ring
- * - {@link getShards} assigns a fixed number of shard indexes across the nodes
- * - Higher weights receive proportionally more virtual points and shard
- *   allocations
- * - Operations mutate and return the same ring instance
- *
- * **Common tasks**
- *
- * - Create an empty ring: {@link make}
- * - Add or update nodes: {@link add}, {@link addMany}
- * - Remove nodes: {@link remove}
- * - Check membership by primary key: {@link has}
- * - Route an input key to a node: {@link get}
- * - Precompute shard ownership: {@link getShards}
- * - Guard unknown values: {@link isHashRing}
+ * Assigns string inputs to nodes with weighted consistent hashing.
  *
- * **Gotchas**
- *
- * - Empty rings return `undefined` from {@link get} and {@link getShards}
- * - Nodes with the same primary key represent the same ring member
- * - Weights are clamped to a positive minimum so a node remains represented
- * - Mutating a ring in place is intentional; create a new ring when independent
- *   snapshots are required
- *
- * **Quickstart**
- *
- * **Example** (Routing keys across nodes)
- *
- * ```ts
- * import { HashRing, PrimaryKey } from "effect"
- *
- * class Node implements PrimaryKey.PrimaryKey {
- *   constructor(readonly id: string) {}
- *
- *   [PrimaryKey.symbol](): string {
- *     return this.id
- *   }
- * }
- *
- * const ring = HashRing.make<Node>().pipe(
- *   HashRing.add(new Node("node-a")),
- *   HashRing.add(new Node("node-b"), { weight: 2 })
- * )
- *
- * const owner = HashRing.get(ring, "user:123")
- * console.log(owner ? PrimaryKey.value(owner) : undefined)
- * ```
+ * A hash ring minimizes remapping when nodes are added, removed, or reweighted.
+ * This makes it useful for routing requests, partitioning keys, and
+ * distributing shards across service instances or storage backends. This module
+ * can create rings, add or remove nodes by `PrimaryKey`, route an input string
+ * to a node, and compute shard assignments.
  *
  * @since 4.0.0
  */

package/src/HashSet.ts

@@ -1,40 +1,11 @@
 /**
- * The `HashSet` module provides an immutable set data structure for storing
- * unique values with efficient membership checks, additions, removals, and set
- * operations. A `HashSet<A>` contains at most one value for each equality class
- * as determined by Effect's `Equal` / `Hash` semantics.
- *
- * **Mental model**
- *
- * - `HashSet<A>` is an immutable collection of unique values of type `A`
- * - Operations such as {@link add}, {@link remove}, {@link union}, and
- *   {@link difference} return new sets; the input set is never mutated
- * - Membership is checked with {@link has}, using Effect equality and hashing
- *   rather than array-style linear scanning
- * - Duplicate values are collapsed when using {@link make}, {@link fromIterable},
- *   {@link add}, or {@link map}
- * - `HashSet` is iterable, but iteration order is not a sorting guarantee
- *
- * **Common tasks**
- *
- * - Create sets: {@link empty}, {@link make}, {@link fromIterable}
- * - Check membership and size: {@link has}, {@link size}, {@link isEmpty}
- * - Add or remove values: {@link add}, {@link remove}
- * - Combine sets: {@link union}, {@link intersection}, {@link difference}
- * - Compare sets: {@link isSubset}
- * - Transform or select values: {@link map}, {@link filter}
- * - Test values: {@link some}, {@link every}
- * - Fold values: {@link reduce}
- *
- * **Gotchas**
- *
- * - Values that should compare structurally should implement compatible
- *   `Equal` and `Hash` behavior; otherwise object identity may affect whether
- *   values are considered distinct
- * - {@link map} may reduce the set size when multiple input values map to the
- *   same output value
- * - Do not rely on iteration order for deterministic presentation; sort the
- *   values after converting to an array when order matters
+ * Stores unique values in an immutable hash set.
+ *
+ * A `HashSet<A>` contains at most one value for each equality class according
+ * to Effect's `Equal` and `Hash` rules. Membership checks, additions, removals,
+ * and set operations return new sets. This module also includes constructors,
+ * union, intersection, difference, subset checks, mapping, filtering, and
+ * reducing helpers.
  *
  * @since 2.0.0
  */

package/src/Inspectable.ts

@@ -1,65 +1,11 @@
 /**
- * Inspection protocol for stable string, JSON, and Node.js representations.
+ * Controls how values appear in logs and debugging output.
  *
- * This module is the small bridge used by Effect data types to explain
- * themselves in logs, REPLs, test failures, and JSON-like diagnostics. Implement
- * `Inspectable` or extend {@link Class} when a value should expose one
- * representation to `toString`, `toJSON`, and Node's `util.inspect`; use
- * {@link toJson} and {@link toStringUnknown} when formatting values supplied by
- * user code.
- *
- * ## Mental model
- *
- * Inspectable values choose their own JSON representation. {@link BaseProto}
- * and {@link Class} derive `toString()` from that representation with the
- * formatter and expose the same value through {@link NodeInspectSymbol}.
- * {@link toJson} is defensive: it calls zero-argument `toJSON` methods,
- * recurses through arrays, returns `"[toJSON threw]"` if a custom serializer
- * fails, and applies redaction to other values.
- *
- * ## Common tasks
- *
- * - Extend {@link Class} for classes that only need to define `toJSON`.
- * - Reuse {@link BaseProto} for object prototypes that should share standard
- *   inspection behavior.
- * - Format unknown diagnostic values with {@link toStringUnknown}.
- * - Implement {@link NodeInspectSymbol} when integrating directly with
- *   Node.js inspection.
- *
- * ## Gotchas
- *
- * `toJson` is meant for inspection, not canonical persistence. It catches
- * `toJSON` failures, does not deeply traverse arbitrary objects, and may
- * replace redactable values according to current redaction behavior. Keep
- * custom `toJSON` implementations side-effect free so logging and debugging do
- * not change program state.
- *
- * **Example** (Creating inspectable values)
- *
- * ```ts
- * import { Inspectable } from "effect"
- *
- * class User extends Inspectable.Class {
- *   constructor(
- *     readonly id: number,
- *     readonly name: string
- *   ) {
- *     super()
- *   }
- *
- *   toJSON() {
- *     return {
- *       _tag: "User",
- *       id: this.id,
- *       name: this.name,
- *     }
- *   }
- * }
- *
- * const user = new User(1, "Alice")
- * console.log(user.toString())
- * console.log(user[Inspectable.NodeInspectSymbol]())
- * ```
+ * Effect data types use `Inspectable` to provide stable string, JSON, and
+ * Node.js inspection output. This keeps custom values readable in logs, REPLs,
+ * test failures, and diagnostics. This module defines the Node inspect symbol,
+ * the `Inspectable` interface, safe conversion helpers, and shared prototype or
+ * class implementations for custom values.
  *
  * @since 2.0.0
  */

package/src/Iterable.ts

@@ -1,55 +1,10 @@
 /**
- * The `Iterable` module works with any JavaScript value that implements
- * `[Symbol.iterator]`, including arrays, strings, generators, sets, and custom
- * lazy sequences. It provides constructors, transformations, searches, grouping,
- * and folding helpers that can be used without converting to an array first.
- *
- * **Mental model**
- *
- * - An `Iterable<A>` creates an `Iterator<A>` when it is consumed.
- * - Transformations such as {@link map}, {@link filter}, {@link flatMap},
- *   {@link take}, and {@link drop} return new iterables and usually do no work
- *   until the result is iterated.
- * - Consumers such as {@link reduce}, {@link size}, {@link head},
- *   {@link findFirst}, and `Array.from` pull values from an iterator.
- * - Constructors such as {@link range}, {@link makeBy}, {@link repeat},
- *   {@link forever}, and {@link unfold} can represent unbounded sequences.
- *
- * **Common tasks**
- *
- * - Create sequences: {@link empty}, {@link of}, {@link range}, {@link makeBy},
- *   {@link replicate}, {@link unfold}
- * - Transform values: {@link map}, {@link flatMap}, {@link flatten},
- *   {@link filter}, {@link filterMap}
- * - Slice and search: {@link take}, {@link drop}, {@link takeWhile},
- *   {@link findFirst}, {@link findLast}, {@link contains}
- * - Combine and group: {@link appendAll}, {@link zipWith}, {@link chunksOf},
- *   {@link groupBy}, {@link cartesian}
- * - Fold or collect: {@link reduce}, {@link scan}, {@link countBy},
- *   `Array.from`
+ * Works with JavaScript values that implement `[Symbol.iterator]`.
  *
- * **Gotchas**
- *
- * - Laziness depends on the operation. Functions such as {@link size} and
- *   {@link reduce} consume the iterable immediately.
- * - Some JavaScript iterables are single-use iterators. Reusing the same value
- *   after it has been consumed may produce no elements.
- * - Unbounded iterables must be limited before full collection, for example
- *   with {@link take}.
- *
- * **Example** (Building a lazy pipeline)
- *
- * ```ts
- * import { Iterable } from "effect"
- *
- * const naturals = Iterable.range(1)
- * const squares = Iterable.map(naturals, (n) => n * n)
- * const evenSquares = Iterable.filter(squares, (n) => n % 2 === 0)
- * const firstFive = Iterable.take(evenSquares, 5)
- *
- * console.log(Array.from(firstFive))
- * // [4, 16, 36, 64, 100]
- * ```
+ * Iterables include arrays, strings, generators, sets, and custom lazy
+ * sequences. The helpers in this module let code transform, search, group, and
+ * fold iterable values while preserving the input as an iterable instead of
+ * forcing an array first.
  *
  * @since 2.0.0
  */

package/src/JsonPatch.ts

@@ -5,59 +5,6 @@
  * difference between two JSON documents, serialize that difference, and replay
  * it without mutating the original input.
  *
- * **Mental model**
- *
- * - A {@link JsonPatch} is applied from left to right; each operation observes
- *   the document produced by the operations before it.
- * - Paths use JSON Pointer syntax. The empty path `""` targets the whole
- *   document, and `/users/0/name` targets a nested property or array element.
- * - This module implements the deterministic `add`, `remove`, and `replace`
- *   subset of RFC 6902. It does not model `test`, `move`, or `copy`.
- * - {@link get} compares JSON structure, not domain meaning. It can detect that
- *   a value changed, but it does not infer semantic edits such as array moves.
- * - {@link apply} copies changed containers and returns a new JSON value. An
- *   empty patch returns the original document reference.
- *
- * **Common tasks**
- *
- * - Compute a structural diff between two JSON values with {@link get}.
- * - Apply generated or hand-written operations with {@link apply}.
- * - Accept, store, or serialize complete patch documents as {@link JsonPatch}.
- * - Type individual operations with {@link JsonPatchOperation}.
- *
- * **Gotchas**
- *
- * - Generated patches are deterministic, but not guaranteed to be minimal.
- * - Array removals are emitted from highest index to lowest so later removals do
- *   not shift earlier targets.
- * - `"-"` is valid only as the final token for array append operations.
- * - Invalid paths, missing properties, and out-of-bounds array indices throw.
- * - Root `add` and `replace` operations replace the whole document; root
- *   `remove` is unsupported.
- *
- * **Example** (Computing and applying a patch)
- *
- * ```ts
- * import { JsonPatch } from "effect"
- *
- * const before = { title: "draft", tags: ["fp"] }
- * const after = { title: "published", tags: ["fp", "effect"] }
- *
- * const patch = JsonPatch.get(before, after)
- * // [
- * //   { op: "add", path: "/tags/1", value: "effect" },
- * //   { op: "replace", path: "/title", value: "published" }
- * // ]
- *
- * const updated = JsonPatch.apply(patch, before)
- * // { title: "published", tags: ["fp", "effect"] }
- * ```
- *
- * **See also**
- *
- * - `JsonPointer` for escaping and unescaping JSON Pointer path tokens.
- * - {@link Schema.Json} for the JSON value shape accepted by this module.
- *
  * @since 4.0.0
  */
 import { format } from "./Formatter.ts"

package/src/JsonPointer.ts

@@ -1,53 +1,8 @@
 /**
- * Utilities for escaping and unescaping JSON Pointer reference tokens according to RFC 6901.
- *
- * JSON Pointer (RFC 6901) defines a string syntax for identifying a specific value within a JSON document.
- * A JSON Pointer is a sequence of reference tokens separated by forward slashes (`/`). Each reference token
- * must be escaped when it contains special characters (`~` or `/`).
- *
- * ## Mental model
- *
- * - **Reference token**: A single segment of a JSON Pointer path (e.g., `"foo"`, `"bar/baz"`, `"key~with~tilde"`)
- * - **Escaping**: Encoding special characters in a token so it can be safely used in a JSON Pointer (`~` → `~0`, `/` → `~1`)
- * - **Unescaping**: Decoding escaped characters back to their original form (`~0` → `~`, `~1` → `/`)
- * - **RFC 6901 compliance**: These functions implement the standard escaping rules for JSON Pointer reference tokens
- * - **Pure functions**: Both operations are pure, immutable, and have no side effects
- *
- * ## Common tasks
- *
- * - Building JSON Pointers from path segments → {@link escapeToken}
- * - Parsing JSON Pointers to extract original token values → {@link unescapeToken}
- * - Escaping object keys or path segments before constructing JSON Pointers → {@link escapeToken}
- * - Extracting unescaped identifiers from JSON Pointer strings → {@link unescapeToken}
- *
- * ## Gotchas
- *
- * - These functions operate on **reference tokens**, not full JSON Pointers. A full JSON Pointer like `/foo/bar` must be split into tokens (`["foo", "bar"]`) before escaping/unescaping
- * - The order of replacement operations matters: `escapeToken` replaces `~` before `/` to avoid double-escaping
- * - Empty strings are valid tokens and are returned unchanged
- * - These functions do not validate JSON Pointer syntax; they only handle token-level escaping
- *
- * ## Quickstart
- *
- * **Example** (Building and parsing a JSON Pointer)
- *
- * ```ts
- * import { JsonPointer } from "effect"
- *
- * // Build a JSON Pointer from path segments
- * const segments = ["users", "name/alias", "value"]
- * const pointer = "/" + segments.map(JsonPointer.escapeToken).join("/")
- * // "/users/name~1alias/value"
- *
- * // Parse a JSON Pointer back to segments
- * const tokens = pointer.split("/").slice(1).map(JsonPointer.unescapeToken)
- * // ["users", "name/alias", "value"]
- * ```
- *
- * ## See also
- *
- * - {@link JsonPatch} - Uses these utilities for JSON Patch operations
- * - {@link JsonSchema} - Uses these utilities for schema reference resolution
+ * Helpers for escaping and unescaping JSON Pointer path segments. JSON Pointer
+ * uses `/` to separate path tokens inside a JSON document, so token text must
+ * encode literal `~` and `/` characters. This module provides the two RFC 6901
+ * token conversions used by JSON Patch and related path handling.
  *
  * @since 4.0.0
  */

package/src/JsonSchema.ts

@@ -1,86 +1,10 @@
 /**
- * Convert JSON Schema documents between dialects (Draft-07, Draft-2020-12,
- * OpenAPI 3.0, OpenAPI 3.1). All dialects are normalized to an internal
- * `Document<"draft-2020-12">` representation before optional conversion to
- * an output dialect.
- *
- * ## Mental model
- *
- * - **JsonSchema** — a plain object with string keys; represents any single
- *   JSON Schema node.
- * - **Dialect** — one of `"draft-07"`, `"draft-2020-12"`, `"openapi-3.1"`,
- *   or `"openapi-3.0"`.
- * - **Document** — a structured container holding a root `schema`, its
- *   companion `definitions`, and the target `dialect`. Definitions are
- *   stored separately from the root schema so they can be relocated when
- *   converting between dialects.
- * - **MultiDocument** — same as `Document` but carries multiple root
- *   schemas (at least one). Useful when generating several schemas that
- *   share a single definitions pool.
- * - **Definitions** — a `Record<string, JsonSchema>` keyed by definition
- *   name. The ref pointer prefix depends on the dialect.
- * - **`from*` functions** — parse a raw JSON Schema object into the
- *   canonical `Document<"draft-2020-12">`.
- * - **`to*` functions** — convert from the canonical representation to a
- *   specific output dialect.
- *
- * ## Common tasks
- *
- * - Parse a Draft-07 schema → {@link fromSchemaDraft07}
- * - Parse a Draft-2020-12 schema → {@link fromSchemaDraft2020_12}
- * - Parse an OpenAPI 3.1 schema → {@link fromSchemaOpenApi3_1}
- * - Parse an OpenAPI 3.0 schema → {@link fromSchemaOpenApi3_0}
- * - Convert to Draft-07 output → {@link toDocumentDraft07}
- * - Convert to OpenAPI 3.1 output → {@link toMultiDocumentOpenApi3_1}
- * - Resolve a `$ref` against definitions → {@link resolve$ref}
- * - Inline the root `$ref` of a document → {@link resolveTopLevel$ref}
- *
- * ## Gotchas
- *
- * - All `from*` functions normalize to `Document<"draft-2020-12">`
- *   regardless of the input dialect.
- * - Unsupported or unrecognized JSON Schema keywords are silently dropped
- *   during conversion.
- * - Draft-07 tuple syntax (`items` as array + `additionalItems`) is
- *   converted to 2020-12 form (`prefixItems` + `items`), and vice-versa.
- * - OpenAPI 3.0 `nullable: true` is expanded into `type` arrays or
- *   `anyOf` unions. The `nullable` keyword is removed.
- * - OpenAPI 3.0 singular `example` is converted to `examples` (array).
- * - {@link resolve$ref} only looks up the last segment of the ref path in
- *   the definitions map; it does not follow arbitrary JSON Pointer paths.
- *
- * ## Quickstart
- *
- * **Example** (Parse a Draft-07 schema and convert to Draft-07 output)
- *
- * ```ts
- * import { JsonSchema } from "effect"
- *
- * const raw: JsonSchema.JsonSchema = {
- *   type: "object",
- *   properties: {
- *     name: { type: "string" }
- *   },
- *   required: ["name"]
- * }
- *
- * // Parse into canonical form
- * const doc = JsonSchema.fromSchemaDraft07(raw)
- *
- * // Convert back to Draft-07
- * const draft07 = JsonSchema.toDocumentDraft07(doc)
- *
- * console.log(draft07.dialect) // "draft-07"
- * console.log(draft07.schema) // { type: "object", properties: { name: { type: "string" } }, required: ["name"] }
- * ```
- *
- * ## See also
- *
- * - {@link Document}
- * - {@link MultiDocument}
- * - {@link fromSchemaDraft07}
- * - {@link toDocumentDraft07}
- * - {@link resolve$ref}
+ * Helpers for normalizing and converting JSON Schema and OpenAPI schema
+ * documents. Supported inputs include JSON Schema Draft-07, Draft 2020-12,
+ * OpenAPI 3.0, and OpenAPI 3.1; conversions normalize through
+ * `Document<"draft-2020-12">` before emitting another dialect. The module also
+ * defines document types, meta-schema constants, OpenAPI component-key helpers,
+ * and `$ref` resolution utilities.
  *
  * @since 4.0.0
  */

package/src/Latch.ts

@@ -1,35 +1,9 @@
 /**
- * The `Latch` module provides a reusable synchronization primitive for
- * coordinating fibers. A `Latch` is either open or closed: when it is closed,
- * fibers that use {@link _await await} or {@link whenOpen} suspend until the latch is
- * opened or the current waiters are released.
- *
- * **Mental model**
- *
- * - An open latch lets current and future waiters continue immediately
- * - A closed latch causes `await` and `whenOpen` to suspend
- * - {@link open} permanently opens the latch until it is closed again
- * - {@link release} wakes only the fibers currently waiting and leaves the
- *   latch closed for future waiters
- * - {@link close} resets the latch so later waiters suspend again
- *
- * **Common tasks**
- *
- * - Create a latch inside `Effect`: {@link make}
- * - Create a latch synchronously: {@link makeUnsafe}
- * - Wait for a signal before continuing: {@link _await await}
- * - Guard an effect so it runs only after the latch is open: {@link whenOpen}
- * - Let all current and future waiters proceed: {@link open}
- * - Let only the current waiters proceed: {@link release}
- * - Re-enable waiting after opening: {@link close}
- *
- * **Gotchas**
- *
- * - `release` is not the same as `open`; new waiters still suspend after the
- *   current waiters are released
- * - `open` and `close` report whether they changed the latch state
- * - Prefer the effectful APIs unless synchronous allocation or mutation is
- *   required
+ * Reusable synchronization primitives for coordinating fibers. A `Latch` is
+ * either open or closed: when it is closed, `await` and `whenOpen` suspend
+ * until the latch opens or the current waiters are released. The module
+ * includes effectful and synchronous constructors plus helpers to open, release,
+ * close, wait, and gate effects behind the latch.
  *
  * @since 4.0.0
  */

package/src/Layer.ts

@@ -1,43 +1,11 @@
 /**
- * The `Layer` module provides the dependency-injection building blocks for
- * Effect applications. A {@link Layer} describes how to acquire one or more
- * services, which dependencies are needed to acquire them, and which errors can
- * occur during acquisition.
- *
- * **Mental model**
- *
- * - Application effects ask for services through context tags.
- * - Layer code builds those services, often from configuration, clients,
- *   connection pools, or other services.
- * - The application boundary provides a final layer to the program.
- * - Layers are lazy: acquisition starts only when a layer is provided, built, or
- *   launched.
- * - Layer acquisition is scoped, so finalizers run when the owning scope closes.
- * - A layer value is memoized by default; reusing the same layer value shares
- *   the acquired service instance.
- *
- * **Common tasks**
- *
- * - Provide an existing service value with {@link succeed}.
- * - Build a service lazily with {@link sync}, {@link effect}, or
- *   {@link effectContext}.
- * - Run setup work that provides no services with {@link effectDiscard}.
- * - Combine independent layers with {@link merge} or {@link mergeAll}.
- * - Feed one layer's output into another layer's requirements with
- *   {@link provide}.
- * - Keep dependency services in the final output with {@link provideMerge}.
- * - Materialize a layer manually with {@link build} or {@link buildWithScope}.
+ * Builds and wires services for Effect applications.
  *
- * **Gotchas**
- *
- * - Sharing is tied to layer identity. Constructing the same layer twice creates
- *   two distinct values and can acquire two service instances.
- * - Use {@link fresh} when a layer must be rebuilt even if the same value is
- *   provided more than once.
- * - Scoped resources belong in layers when construction and release are part of
- *   the service lifecycle.
- * - Normal application code should request services; layer code should create
- *   services.
+ * A `Layer<ROut, E, RIn>` describes how to acquire one or more services, which
+ * services are required to build them, and which errors can occur during
+ * acquisition. Layers can manage scoped resources, memoize shared services,
+ * combine with other layers, provide services to effects or streams, and attach
+ * error handling, tracing, or lifecycle hooks.
  *
  * @since 2.0.0
  */

package/src/LayerMap.ts

@@ -1,36 +1,11 @@
 /**
- * The `LayerMap` module provides utilities for managing scoped resources that
- * are selected by key and built from `Layer` values. A `LayerMap<K, I, E>` turns
- * a key into a cached service `Context<I>`, so applications can lazily acquire
- * and reuse different resource instances such as tenant clients, regional
- * connections, environment-specific services, or other keyed infrastructure.
- *
- * **Mental model**
- *
- * - A `LayerMap` is a scoped, reference-counted cache of contexts produced by layers
- * - Keys identify which layer-backed resource set should be acquired
- * - Resources are acquired on demand when a key is requested
- * - The same key reuses the cached context while it remains live
- * - Cached resources are finalized when invalidated, when their scope closes, or after idle expiration
- * - The layers built by a `LayerMap` share the current layer memoization map
- *
- * **Common tasks**
- *
- * - Create from a lookup function: {@link make}
- * - Create from a fixed record of layers: {@link fromRecord}
- * - Define a service wrapper with accessor helpers: {@link Service}
- * - Retrieve a layer for a key: {@link LayerMap.get}
- * - Retrieve a scoped context directly: {@link LayerMap.contextEffect}
- * - Force a cached entry to be rebuilt later: {@link LayerMap.invalidate}
- * - Remove idle entries automatically with the `idleTimeToLive` option
- * - Eagerly build known entries with `preloadKeys` or `preload`
- *
- * **Gotchas**
- *
- * - `contextEffect` requires a `Scope.Scope` because it exposes the acquired context directly
- * - `get` returns a `Layer` that can be provided to programs expecting the keyed services
- * - Invalidating a key finalizes the current cached resources for that key; the next access rebuilds them
- * - Preloading moves layer construction errors to `LayerMap` creation instead of first use
+ * Caches scoped services selected by key and built from layers.
+ *
+ * A `LayerMap<K, I, E>` turns a key into a cached service `Context<I>` and
+ * exposes that context as either a `Layer` or a scoped effect. Entries can be
+ * invalidated explicitly or released after they sit unused. This is useful for
+ * keyed resource families such as tenant clients, regional connections, or
+ * environment-specific services.
  *
  * @since 3.14.0
  */

package/src/LogLevel.ts

@@ -1,39 +1,8 @@
 /**
- * The `LogLevel` module defines the levels used by Effect logging and the
- * ordering operations used to compare, filter, and enable log output.
- *
- * **Mental model**
- *
- * - A `LogLevel` is one of `All`, `Fatal`, `Error`, `Warn`, `Info`, `Debug`,
- *   `Trace`, or `None`
- * - `Fatal` is the most severe concrete level and `Trace` is the least severe
- * - `All` and `None` are sentinel levels: `All` enables every message and
- *   `None` disables every message
- * - Ordering follows logging severity, so higher levels are more important and
- *   lower levels are more verbose
- * - Filtering is usually expressed as "log this message when its level is
- *   greater than or equal to the configured minimum"
- *
- * **Common tasks**
- *
- * - Enumerate levels with {@link values}
- * - Compare exact levels with {@link Equivalence}
- * - Sort or compare by severity with {@link Order} and {@link getOrdinal}
- * - Check thresholds with {@link isGreaterThanOrEqualTo} and
- *   {@link isLessThanOrEqualTo}
- * - Test whether a level is enabled for the current fiber with
- *   {@link isEnabled}
- *
- * **Gotchas**
- *
- * - `All` and `None` are useful for configuration boundaries, but they are not
- *   concrete message severities; use {@link Severity} when only emitted message
- *   levels are valid
- * - The comparison helpers compare severity, not declaration position in source
- *   code or alphabetical order
- * - `isEnabled` reads the current fiber's `MinimumLogLevel` reference, so it is
- *   context-sensitive; use the pure comparison helpers when checking an
- *   explicit threshold
+ * Log-level types and helpers used by Effect logging. The module defines all
+ * accepted log levels, the concrete emitted severities, the ordered level list,
+ * equality and ordering instances, threshold comparison helpers, and an effect
+ * for checking whether a level is enabled by the current logging settings.
  *
  * @since 2.0.0
  */