effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/FileSystem.ts

@@ -778,7 +778,7 @@ export type OpenFlag =
  * )
  * ```
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Service("effect/platform/FileSystem")
@@ -1104,7 +1104,7 @@ export const FileTypeId = "~effect/platform/FileSystem/File"
  * @see {@link File} for the file-handle interface narrowed by this guard
  * @see {@link FileTypeId} for the runtime marker checked by this guard
  *
- * @category File
+ * @category file
  * @since 4.0.0
  */
 export const isFile = (u: unknown): u is File => hasProperty(u, FileTypeId)
@@ -1150,7 +1150,7 @@ export const isFile = (u: unknown): u is File => hasProperty(u, FileTypeId)
  * })
  * ```
  *
- * @category File
+ * @category file
  * @since 4.0.0
  */
 export interface File {
@@ -1181,7 +1181,7 @@ export declare namespace File {
    * File descriptors are numeric handles used by the operating system
    * to identify open files. The branded type ensures type safety.
    *
-   * @category File
+   * @category file
    * @since 4.0.0
    */
   export type Descriptor = Brand.Branded<number, "FileDescriptor">
@@ -1194,7 +1194,7 @@ export declare namespace File {
    * Represents the different types of entries that can exist in a file system,
    * from regular files to special device files and symbolic links.
    *
-   * @category File
+   * @category file
    * @since 4.0.0
    */
   export type Type =
@@ -1249,7 +1249,7 @@ export declare namespace File {
    * })
    * ```
    *
-   * @category File
+   * @category file
    * @since 4.0.0
    */
   export interface Info {

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)
  *
@@ -430,7 +431,7 @@ export const identity = <A>(a: A): A => a
  *
  * @see {@link cast} for changing only the static TypeScript type
  *
- * @category type utils
+ * @category utility types
  * @since 2.0.0
  */
 export const satisfies = <A>() => <B extends A>(b: B) => b
@@ -450,7 +451,7 @@ export const satisfies = <A>() => <B extends A>(b: B) => b
  *
  * @see {@link satisfies} for checking assignability without changing the resulting type
  *
- * @category type utils
+ * @category utility types
  * @since 4.0.0
  */
 export const cast: <A, B>(a: A) => B = identity as any
@@ -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**
  *
@@ -722,7 +722,7 @@ export const compose: {
  * }
  * ```
  *
- * @category utils
+ * @category utility types
  * @since 2.0.0
  */
 export const absurd = <A>(_: never): A => {
@@ -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**
  *
@@ -1561,7 +1560,7 @@ export function flow(
  * console.log(typeof buildUser) // "function"
  * ```
  *
- * @category utils
+ * @category utility types
  * @since 2.0.0
  */
 export const hole: <T>() => T = cast(absurd)
@@ -1610,7 +1609,7 @@ export const SK = <A, B>(_: A, b: B): B => b
  * mutated after its first call, later calls still return the cached result for
  * that reference.
  *
- * @category utils
+ * @category caching
  * @since 4.0.0
  */
 export function memoize<A extends object, O>(f: (a: A) => O): (ast: A) => O {

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
@@ -2493,7 +2493,7 @@ export const neighborsDirected: {
  * }
  * ```
  *
- * @category models
+ * @category options
  * @since 3.18.0
  */
 export interface GraphVizOptions<N, E> {
@@ -2545,7 +2545,7 @@ export interface GraphVizOptions<N, E> {
  * // }
  * ```
  *
- * @category utils
+ * @category converting
  * @since 3.18.0
  */
 export const toGraphViz: {
@@ -2578,7 +2578,7 @@ export const toGraphViz: {
    * // }
    * ```
    *
-   * @category utils
+   * @category converting
    * @since 3.18.0
    */
   <N, E>(options?: GraphVizOptions<N, E>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => string
@@ -2611,7 +2611,7 @@ export const toGraphViz: {
    * // }
    * ```
    *
-   * @category utils
+   * @category converting
    * @since 3.18.0
    */
   <N, E, T extends Kind = "directed">(
@@ -2817,7 +2817,7 @@ export type MermaidDiagramType =
  * }
  * ```
  *
- * @category models
+ * @category options
  * @since 3.18.0
  */
 export interface MermaidOptions<N, E> {
@@ -3082,7 +3082,7 @@ const formatMermaidNode = (
  * //   0 -->|"builds with"| 3
  * ```
  *
- * @category utils
+ * @category converting
  * @since 3.18.0
  */
 export const toMermaid: {
@@ -3262,7 +3262,7 @@ export const toMermaid: {
    * //   0 -->|"builds with"| 3
    * ```
    *
-   * @category utils
+   * @category converting
    * @since 3.18.0
    */
   <N, E>(options?: MermaidOptions<N, E>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => string
@@ -3442,7 +3442,7 @@ export const toMermaid: {
    * //   0 -->|"builds with"| 3
    * ```
    *
-   * @category utils
+   * @category converting
    * @since 3.18.0
    */
   <N, E, T extends Kind = "directed">(
@@ -5263,7 +5263,7 @@ export type EdgeWalker<E> = Walker<EdgeIndex, Edge<E>>
  * console.log(indices) // [0, 1]
  * ```
  *
- * @category utils
+ * @category iterators
  * @since 3.18.0
  */
 export const indices = <T, N>(walker: Walker<T, N>): Iterable<T> => walker.visit((index, _) => index)
@@ -5287,7 +5287,7 @@ export const indices = <T, N>(walker: Walker<T, N>): Iterable<T> => walker.visit
  * console.log(values) // ["A", "B"]
  * ```
  *
- * @category utils
+ * @category iterators
  * @since 3.18.0
  */
 export const values = <T, N>(walker: Walker<T, N>): Iterable<N> => walker.visit((_, data) => data)
@@ -5311,7 +5311,7 @@ export const values = <T, N>(walker: Walker<T, N>): Iterable<N> => walker.visit(
  * console.log(entries) // [[0, "A"], [1, "B"]]
  * ```
  *
- * @category utils
+ * @category iterators
  * @since 3.18.0
  */
 export const entries = <T, N>(walker: Walker<T, N>): Iterable<[T, N]> =>

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**
  *
@@ -235,7 +235,7 @@ export interface TypeLambda {
  * >
  * ```
  *
- * @category type utils
+ * @category utility types
  * @since 2.0.0
  */
 export type Kind<F extends TypeLambda, In, Out2, Out1, Target> = F extends {

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

@@ -197,7 +197,7 @@ export declare namespace HashMap {
    * console.log(getUserById("alice")) // Option.some({ name: "Alice", age: 30 })
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 2.0.0
    */
   export type Key<T extends HashMap<any, any>> = [T] extends [HashMap<infer _K, infer _V>] ? _K : never
@@ -228,7 +228,7 @@ export declare namespace HashMap {
    * // alice has type Option<User> thanks to type extraction
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 2.0.0
    */
   export type Value<T extends HashMap<any, any>> = [T] extends [HashMap<infer _K, infer _V>] ? _V : never
@@ -260,7 +260,7 @@ export declare namespace HashMap {
    * console.log(descriptions) // ["book: $29 (education)", "laptop: $999 (electronics)"]
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 3.9.0
    */
   export type Entry<T extends HashMap<any, any>> = [Key<T>, Value<T>]
@@ -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/HashSet.ts

@@ -125,7 +125,7 @@ export declare namespace HashSet {
    * const processNumber = (n: NumberType) => n * 2
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 4.0.0
    */
   export type Value<T> = T extends HashSet<infer V> ? V : never