effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/Filter.ts

@@ -512,8 +512,8 @@ export const symbol: Filter<unknown, symbol> = fromPredicate(Predicate.isSymbol)
  *
  * **When to use**
  *
- * Use when narrowing unknown input to JavaScript `Date` instances with a
- * reusable `Filter`.
+ * Use when you need to narrow unknown input to JavaScript `Date` instances with
+ * a reusable `Filter`.
  *
  * **Details**
  *
@@ -1147,8 +1147,8 @@ export const composePassthrough: {
  *
  * **When to use**
  *
- * Use when adapting a `Filter` to `Option`-based code and you only need the
- * passed value, with filtered-out inputs represented as `None`.
+ * Use when adapting a `Filter` to `Option`-based code where passed values
+ * become `Some` and filtered-out inputs become `None`.
  *
  * @see {@link toResult} for keeping the filter failure value
  * @see {@link toPredicate} for plain boolean pass/fail checks

package/src/Formatter.ts

@@ -91,16 +91,16 @@ export interface Formatter<in Value, out Format = string> {
  *
  * **When to use**
  *
- * Use to pretty-print values for debugging, logging, or error messages.
- * - You need to handle `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`,
- *   or class instances that `JSON.stringify` cannot represent.
- * - You want circular references shown as `"[Circular]"` instead of
- *   throwing.
+ * Use when you need to format arbitrary JavaScript values for debugging,
+ * logging, or error messages.
  *
  * **Details**
  *
  * - Output is **not** valid JSON; use {@link formatJson} when you need
  *   parseable JSON.
+ * - Handles `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`, and class
+ *   instances that `JSON.stringify` cannot represent.
+ * - Circular references are shown as `"[Circular]"` instead of throwing.
  * - Primitives: stringified naturally (`null`, `undefined`, `123`, `true`).
  *   Strings are JSON-quoted.
  * - Objects with a custom `toString` (not `Object.prototype.toString`):
@@ -112,7 +112,6 @@ export interface Formatter<in Value, out Format = string> {
  * - `Redactable` values are automatically redacted.
  * - Arrays/objects with 0–1 entries are inline; larger ones are
  *   pretty-printed when `space` is set.
- * - Circular references are replaced with `"[Circular]"`.
  * - `space` — indentation unit (number of spaces, or a string like
  *   `"\t"`). Defaults to `0` (compact).
  * - `ignoreToString` — skip calling `toString()`. Defaults to `false`.
@@ -288,22 +287,18 @@ function safeToString(input: any): string {
  *
  * **When to use**
  *
- * Use when you need valid JSON output (unlike {@link format}).
- * - The input may contain circular references and you want them silently
- *   omitted rather than throwing a `TypeError`.
+ * Use when you need valid JSON output, unlike `format`, and the input may
+ * contain circular references that should be silently omitted rather than
+ * throwing a `TypeError`.
  *
  * **Details**
  *
- * - Uses `JSON.stringify` internally with a replacer that tracks the
- *   current object ancestry.
- * - Circular references are replaced with `undefined` (omitted from
- *   output).
- * - `Redactable` values are automatically redacted before serialization.
- * - Types not supported by JSON (`BigInt`, `Symbol`, `undefined`,
- *   functions) follow standard `JSON.stringify` behavior (omitted or
- *   `null` in arrays).
- * - `space` — indentation unit (number of spaces, or a string like
- *   `"\t"`). Defaults to `0` (compact).
+ * Uses `JSON.stringify` internally with a replacer that tracks the current
+ * object ancestry. Circular references are replaced with `undefined`, which
+ * omits them from object output. `Redactable` values are automatically redacted
+ * before serialization. Values not supported by JSON, such as `BigInt`,
+ * `Symbol`, `undefined`, and functions, follow standard `JSON.stringify`
+ * behavior. The `space` parameter controls indentation and defaults to `0`.
  *
  * **Example** (Compact JSON)
  *

package/src/Function.ts

@@ -54,7 +54,8 @@ import { pipeArguments } from "./Pipeable.ts"
  *
  * **When to use**
  *
- * Use to represent unary function types in higher-kinded type operations.
+ * Use when defining higher-kinded abstractions that must accept function types
+ * as one of their type-lambda inputs.
  *
  * **Example** (Creating a function type with a type lambda)
  *
@@ -460,8 +461,8 @@ export const cast: <A, B>(a: A) => B = identity as any
  *
  * **When to use**
  *
- * Use when an API expects a thunk or callback and every invocation
- * should return the same value.
+ * Use when you need a thunk or callback that returns the same value on every
+ * invocation.
  *
  * **Example** (Creating a constant thunk)
  *
@@ -485,7 +486,7 @@ export const constant = <A>(value: A): LazyArg<A> => () => value
  *
  * **When to use**
  *
- * Use when an API expects a thunk and every invocation should return `true`.
+ * Use when you need a thunk that returns `true` on every invocation.
  *
  * **Example** (Returning true from a thunk)
  *
@@ -506,7 +507,7 @@ export const constTrue: LazyArg<boolean> = constant(true)
  *
  * **When to use**
  *
- * Use when an API expects a thunk and every invocation should return `false`.
+ * Use when you need a thunk that returns `false` on every invocation.
  *
  * **Example** (Returning false from a thunk)
  *
@@ -527,7 +528,7 @@ export const constFalse: LazyArg<boolean> = constant(false)
  *
  * **When to use**
  *
- * Use when an API expects a thunk and every invocation should return `null`.
+ * Use when you need a thunk that returns `null` on every invocation.
  *
  * **Example** (Returning null from a thunk)
  *
@@ -548,8 +549,7 @@ export const constNull: LazyArg<null> = constant(null)
  *
  * **When to use**
  *
- * Use when an API expects a thunk and every invocation should return
- * `undefined`.
+ * Use when you need a thunk that returns `undefined` on every invocation.
  *
  * **Example** (Returning undefined from a thunk)
  *
@@ -570,7 +570,7 @@ export const constUndefined: LazyArg<undefined> = constant(undefined)
  *
  * **When to use**
  *
- * Use when an API expects a thunk used only for its call effect and not for a
+ * Use when you need a thunk that is called only for its effect and has no
  * meaningful return value.
  *
  * **Example** (Returning void from a thunk)
@@ -704,8 +704,8 @@ export const compose: {
  *
  * **When to use**
  *
- * Use when exhaustive checks prove a branch cannot be reached, but
- * TypeScript still needs a return value.
+ * Use when you need a return value in a branch that exhaustive checks prove
+ * cannot be reached.
  *
  * **Gotchas**
  *
@@ -785,14 +785,13 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  *
  * **When to use**
  *
- * Use when you use `pipe` with data-last functions to build readable transformation
- * pipelines and to write method-style chains as ordinary function calls.
+ * Use when you need to compose data-last functions into readable
+ * transformation pipelines instead of method-style chains.
  *
  * **Details**
  *
- * `pipe` takes an initial value, passes it to the first function, then passes
- * each result to the next function in order. The final function result is
- * returned.
+ * Takes an initial value, passes it to the first function, then passes each
+ * result to the next function in order. The final function result is returned.
  *
  * **Gotchas**
  *

package/src/Graph.ts

@@ -119,8 +119,8 @@ export type EdgeIndex = number
  *
  * **When to use**
  *
- * Use as the graph edge value returned by `getEdge` and `edges` when you need
- * the source node, target node, and stored edge data together.
+ * Use as the graph edge value that carries source node, target node, and stored
+ * edge data together.
  *
  * @see {@link getEdge} for reading a single edge by identifier
  * @see {@link addEdge} for adding edges to a graph

package/src/HKT.ts

@@ -58,8 +58,8 @@ import type * as Types from "./Types.ts"
  *
  * **When to use**
  *
- * Use when defining a custom type class that needs to expose the `TypeLambda` it
- * operates on.
+ * Use when you need to define a custom type class that exposes the `TypeLambda`
+ * it operates on.
  *
  * **Details**
  *

package/src/Hash.ts

@@ -470,7 +470,8 @@ export const number = (n: number) => {
  *
  * **When to use**
  *
- * Use to hash a string directly.
+ * Use when you need a string field to contribute to a custom structural hash
+ * implementation.
  *
  * **Details**
  *

package/src/HashMap.ts

@@ -578,6 +578,11 @@ export const getHash: {
  * Looks up the value for the specified key in the `HashMap` unsafely using the
  * internal hashing function.
  *
+ * **When to use**
+ *
+ * Use when reading from a `HashMap` by a key known to exist, and throwing is an
+ * acceptable programming error for a missing key.
+ *
  * **Gotchas**
  *
  * This function throws an error if the key is not found. Use `HashMap.get` for
@@ -616,6 +621,11 @@ export const getUnsafe: {
    * Looks up the value for the specified key in the `HashMap` unsafely using the
    * internal hashing function.
    *
+   * **When to use**
+   *
+   * Use when reading from a `HashMap` by a key known to exist, and throwing is an
+   * acceptable programming error for a missing key.
+   *
    * **Gotchas**
    *
    * This function throws an error if the key is not found. Use `HashMap.get` for
@@ -654,6 +664,11 @@ export const getUnsafe: {
    * Looks up the value for the specified key in the `HashMap` unsafely using the
    * internal hashing function.
    *
+   * **When to use**
+   *
+   * Use when reading from a `HashMap` by a key known to exist, and throwing is an
+   * acceptable programming error for a missing key.
+   *
    * **Gotchas**
    *
    * This function throws an error if the key is not found. Use `HashMap.get` for

package/src/HashRing.ts

@@ -264,7 +264,7 @@ function addNodesToRing<A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, keys
  * **When to use**
  *
  * Use to register one node in a `HashRing` so lookups and shard assignments can
- * return it, or to update that node's weight.
+ * return it, or update that node's weight.
  *
  * **Details**
  *
@@ -290,7 +290,7 @@ export const add: {
    * **When to use**
    *
    * Use to register one node in a `HashRing` so lookups and shard assignments can
-   * return it, or to update that node's weight.
+   * return it, or update that node's weight.
    *
    * **Details**
    *
@@ -321,7 +321,7 @@ export const add: {
    * **When to use**
    *
    * Use to register one node in a `HashRing` so lookups and shard assignments can
-   * return it, or to update that node's weight.
+   * return it, or update that node's weight.
    *
    * **Details**
    *
@@ -438,8 +438,8 @@ export const remove: {
  *
  * **When to use**
  *
- * Use to check whether a node value is already registered in a ring by its
- * `PrimaryKey` value.
+ * Use when you need to know whether registering a node would update an existing
+ * ring member because another node already has the same primary-key identity.
  *
  * **Details**
  *
@@ -459,8 +459,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to check whether a node value is already registered in a ring by its
-   * `PrimaryKey` value.
+   * Use when you need to know whether registering a node would update an existing
+   * ring member because another node already has the same primary-key identity.
    *
    * **Details**
    *
@@ -480,8 +480,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to check whether a node value is already registered in a ring by its
-   * `PrimaryKey` value.
+   * Use when you need to know whether registering a node would update an existing
+   * ring member because another node already has the same primary-key identity.
    *
    * **Details**
    *

package/src/Iterable.ts

@@ -933,7 +933,16 @@ export const head = <A>(self: Iterable<A>): Option<A> => {
 }
 
 /**
- * Gets the first element of a `Iterable`, or throw an error if the `Iterable` is empty.
+ * Gets the first element of an `Iterable` without returning an `Option`.
+ *
+ * **When to use**
+ *
+ * Use when the `Iterable` is known to be non-empty and direct access to the
+ * first element is preferred over handling `Option.none`.
+ *
+ * **Gotchas**
+ *
+ * Throws if the `Iterable` is empty.
  *
  * **Example** (Getting the first element unsafely)
  *
@@ -3081,8 +3090,8 @@ const constEmptyIterator: Iterator<never> = {
  *
  * **When to use**
  *
- * Use as a base case for operations or when you
- * need to represent "no data" in a type-safe way.
+ * Use when you need an empty iterable as a typed "no data" value or a base
+ * case for iterable operations.
  *
  * **Example** (Creating an empty iterable)
  *
@@ -3149,7 +3158,7 @@ export const of = <A>(a: A): Iterable<A> => [a]
  *
  * This is one of the most fundamental operations for working with iterables.
  * It applies a transformation function to each element, creating a new iterable
- * with the transformed values. The operation is lazy - elements are only
+ * with the transformed values. The operation is lazy, so elements are only
  * transformed when the iterable is consumed.
  *
  * **Example** (Mapping elements)
@@ -3185,7 +3194,7 @@ export const map: {
    *
    * This is one of the most fundamental operations for working with iterables.
    * It applies a transformation function to each element, creating a new iterable
-   * with the transformed values. The operation is lazy - elements are only
+   * with the transformed values. The operation is lazy, so elements are only
    * transformed when the iterable is consumed.
    *
    * **Example** (Mapping elements)
@@ -3221,7 +3230,7 @@ export const map: {
    *
    * This is one of the most fundamental operations for working with iterables.
    * It applies a transformation function to each element, creating a new iterable
-   * with the transformed values. The operation is lazy - elements are only
+   * with the transformed values. The operation is lazy, so elements are only
    * transformed when the iterable is consumed.
    *
    * **Example** (Mapping elements)
@@ -3449,8 +3458,9 @@ export const flatten = <A>(self: Iterable<Iterable<A>>): Iterable<A> => ({
  *
  * **Details**
  *
- * This combines mapping and filtering in a single operation - the function is applied to each element,
- * and only elements that result in `Result.succeed` are included in the result.
+ * This combines mapping and filtering in a single operation. The function is
+ * applied to each element, and only elements that result in `Result.succeed`
+ * are included in the result.
  *
  * **Example** (Filtering and transforming Result values)
  *
@@ -3497,8 +3507,9 @@ export const filterMap: {
    *
    * **Details**
    *
-   * This combines mapping and filtering in a single operation - the function is applied to each element,
-   * and only elements that result in `Result.succeed` are included in the result.
+   * This combines mapping and filtering in a single operation. The function is
+   * applied to each element, and only elements that result in `Result.succeed`
+   * are included in the result.
    *
    * **Example** (Filtering and transforming Result values)
    *
@@ -3545,8 +3556,9 @@ export const filterMap: {
    *
    * **Details**
    *
-   * This combines mapping and filtering in a single operation - the function is applied to each element,
-   * and only elements that result in `Result.succeed` are included in the result.
+   * This combines mapping and filtering in a single operation. The function is
+   * applied to each element, and only elements that result in `Result.succeed`
+   * are included in the result.
    *
    * **Example** (Filtering and transforming Result values)
    *

package/src/JsonPatch.ts

@@ -194,9 +194,8 @@ export type JsonPatch = ReadonlyArray<JsonPatchOperation>
  *
  * **When to use**
  *
- * Use to compute differences between JSON documents, detect structural
- * changes, or create deterministic update operations from before and after
- * states.
+ * Use to compute a JSON Patch from before and after JSON documents, detect
+ * structural changes, or create deterministic update operations.
  *
  * **Details**
  *

package/src/JsonPointer.ts

@@ -57,9 +57,7 @@
  *
  * **When to use**
  *
- * Use to build JSON Pointers from object keys or path segments that may contain special characters
- * - Escaping tokens before joining them with `/` to form a complete JSON Pointer
- * - Preparing reference tokens for use in JSON Patch operations or schema references
+ * Use when you need to escape a single JSON Pointer path segment.
  *
  * **Details**
  *
@@ -95,9 +93,7 @@ export function escapeToken(token: string): string {
  *
  * **When to use**
  *
- * Use to parse JSON Pointers to extract the original token values from escaped segments
- * - Converting escaped tokens back to their original form for use as object keys or identifiers
- * - Resolving schema references or JSON Patch paths that use escaped tokens
+ * Use when you need to decode a single escaped JSON Pointer path segment.
  *
  * **Details**
  *

package/src/JsonSchema.ts

@@ -259,8 +259,8 @@ export const META_SCHEMA_URI_DRAFT_07 = "http://json-schema.org/draft-07/schema"
  *
  * **When to use**
  *
- * Use to populate the `$schema` field when emitting a JSON Schema document that
- * should declare JSON Schema Draft 2020-12.
+ * Use when you need to populate the `$schema` field while emitting a JSON
+ * Schema document that should declare JSON Schema Draft 2020-12.
  *
  * **Details**
  *
@@ -283,8 +283,8 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/
  *
  * **When to use**
  *
- * Use when you have a JSON Schema that follows Draft-07 conventions and
- * need the canonical Draft-2020-12 document representation.
+ * Use when you have a raw JSON Schema object that follows Draft-07 conventions
+ * and need the canonical Draft-2020-12 document representation.
  *
  * **Details**
  *
@@ -436,7 +436,7 @@ export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
  *
  * **When to use**
  *
- * Use when you already have a schema in Draft-2020-12 format.
+ * Use when you already have a raw JSON Schema object in Draft-2020-12 format.
  *
  * **Details**
  *
@@ -478,7 +478,8 @@ export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"
  *
  * **When to use**
  *
- * Use when consuming schemas from an OpenAPI 3.1 specification.
+ * Use when you need to consume raw JSON Schema objects from an OpenAPI 3.1
+ * specification.
  *
  * **Details**
  *
@@ -517,7 +518,8 @@ export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12">
  *
  * **When to use**
  *
- * Use when consuming schemas from an OpenAPI 3.0 specification.
+ * Use when you need to consume raw JSON Schema objects from an OpenAPI 3.0
+ * specification.
  *
  * **Details**
  *
@@ -556,7 +558,8 @@ export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-1
  *
  * **When to use**
  *
- * Use when you need to output a schema in Draft-07 format.
+ * Use when you need to output a canonical JSON Schema document in Draft-07
+ * format.
  *
  * **Details**
  *
@@ -706,7 +709,8 @@ function toSchemaDraft07(schema: JsonSchema): JsonSchema {
  *
  * **When to use**
  *
- * Use when generating an OpenAPI 3.1 specification from internal schemas.
+ * Use when you need to emit an OpenAPI 3.1 multi-document from canonical JSON
+ * Schema documents.
  *
  * **Details**
  *
@@ -930,8 +934,8 @@ function widen_type(node: Record<string, unknown>): Record<string, unknown> {
  *
  * **When to use**
  *
- * Use when you need to dereference a `$ref` pointer to get the actual
- * schema it points to.
+ * Use when you need to dereference a `$ref` pointer to get the JSON Schema
+ * object it points to.
  *
  * **Details**
  *
@@ -979,8 +983,8 @@ export function resolve$ref($ref: string, definitions: Definitions): JsonSchema
  *
  * **When to use**
  *
- * Use to dereference a top-level `$ref` before inspecting the root
- * schema's properties directly.
+ * Use when you need to dereference a top-level `$ref` before inspecting the
+ * root JSON Schema object's properties directly.
  *
  * **Details**
  *

package/src/Latch.ts

@@ -146,7 +146,8 @@ export interface Latch {
  *
  * **When to use**
  *
- * Use when synchronous allocation is required outside an Effect workflow.
+ * Use when you need to allocate a `Latch` synchronously outside an Effect
+ * workflow.
  *
  * **Details**
  *
@@ -248,8 +249,8 @@ export const open = (self: Latch): Effect.Effect<boolean> => self.open
  *
  * **When to use**
  *
- * Use when synchronous code needs to open a latch immediately and release the
- * fibers waiting on it.
+ * Use when you need synchronous code to open a latch immediately and release
+ * the fibers waiting on it.
  *
  * **Details**
  *