effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/HKT.ts

@@ -54,16 +54,17 @@
 import type * as Types from "./Types.ts"
 
 /**
- * A unique symbol used to associate `TypeClass` implementations with their `TypeLambda`.
+ * Defines the unique symbol used to associate `TypeClass` implementations with their `TypeLambda`.
  *
  * **When to use**
  *
- * Use to link type class implementations to the `TypeLambda` they operate on.
+ * Use when defining a custom type class that needs to expose the `TypeLambda` it
+ * operates on.
  *
  * **Details**
  *
- * This symbol is used internally by the HKT system to link runtime type class
- * instances with their compile-time type information.
+ * This symbol links a type class shape with its compile-time type lambda. It is
+ * intended for type-class definitions and has no runtime behavior.
  *
  * **Example** (Linking a type class to a type lambda)
  *

package/src/Hash.ts

@@ -56,7 +56,7 @@ import { byReferenceInstances, getAllObjectKeys } from "./internal/equal.ts"
 import { hasProperty } from "./Predicate.ts"
 
 /**
- * The unique identifier used to identify objects that implement the Hash interface.
+ * Defines the unique identifier used to identify objects that implement the Hash interface.
  *
  * **When to use**
  *
@@ -352,7 +352,7 @@ export const combine: {
 } = dual(2, (self: number, b: number): number => (self * 53) ^ b)
 
 /**
- * Optimizes a hash value by applying bit manipulation techniques.
+ * Applies bit manipulation techniques to optimize a hash value.
  *
  * **When to use**
  *
@@ -382,7 +382,7 @@ export const combine: {
 export const optimize = (n: number): number => (n & 0xbfffffff) | ((n >>> 1) & 0x40000000)
 
 /**
- * Checks if a value implements the Hash interface.
+ * Checks whether a value implements the Hash interface.
  *
  * **When to use**
  *

package/src/HashMap.ts

@@ -7,8 +7,6 @@
  * **Mental model**
  *
  * - A `HashMap<Key, Value>` is an immutable collection of key-value pairs
- * - Operations such as {@link set}, {@link remove}, and {@link modifyAt} return
- *   new maps; existing maps are not mutated
  * - Keys are compared using the `Equal` protocol and are grouped by hashes from
  *   the `Hash` protocol
  * - Plain JavaScript primitives work as keys, and custom objects can define
@@ -269,7 +267,7 @@ export declare namespace HashMap {
 }
 
 /**
- * Checks if a value is a HashMap.
+ * Checks whether a value is a HashMap.
  *
  * **Example** (Checking HashMap values)
  *
@@ -289,7 +287,7 @@ export declare namespace HashMap {
  */
 export const isHashMap: {
   /**
-   * Checks if a value is a HashMap.
+   * Checks whether a value is a HashMap.
    *
    * **Example** (Checking HashMap values)
    *
@@ -309,7 +307,7 @@ export const isHashMap: {
    */
   <K, V>(u: Iterable<readonly [K, V]>): u is HashMap<K, V>
   /**
-   * Checks if a value is a HashMap.
+   * Checks whether a value is a HashMap.
    *
    * **Example** (Checking HashMap values)
    *
@@ -411,7 +409,7 @@ export const fromIterable: <K, V>(entries: Iterable<readonly [K, V]>) => HashMap
 export const isEmpty: <K, V>(self: HashMap<K, V>) => boolean = internal.isEmpty
 
 /**
- * Safely lookup the value for the specified key in the `HashMap` using the
+ * Looks up the value for the specified key in the `HashMap` safely using the
  * internal hashing function.
  *
  * **Example** (Looking up values)
@@ -434,7 +432,7 @@ export const isEmpty: <K, V>(self: HashMap<K, V>) => boolean = internal.isEmpty
  */
 export const get: {
   /**
-   * Safely lookup the value for the specified key in the `HashMap` using the
+   * Looks up the value for the specified key in the `HashMap` safely using the
    * internal hashing function.
    *
    * **Example** (Looking up values)
@@ -457,7 +455,7 @@ export const get: {
    */
   <K1 extends K, K>(key: K1): <V>(self: HashMap<K, V>) => Option<V>
   /**
-   * Safely lookup the value for the specified key in the `HashMap` using the
+   * Looks up the value for the specified key in the `HashMap` safely using the
    * internal hashing function.
    *
    * **Example** (Looking up values)
@@ -482,7 +480,7 @@ export const get: {
 } = internal.get
 
 /**
- * Lookup the value for the specified key in the `HashMap` using a custom hash.
+ * Looks up the value for the specified key in the `HashMap` safely using a custom hash.
  *
  * **Example** (Looking up values with a hash)
  *
@@ -513,7 +511,7 @@ export const get: {
  */
 export const getHash: {
   /**
-   * Lookup the value for the specified key in the `HashMap` using a custom hash.
+   * Looks up the value for the specified key in the `HashMap` safely using a custom hash.
    *
    * **Example** (Looking up values with a hash)
    *
@@ -544,7 +542,7 @@ export const getHash: {
    */
   <K1 extends K, K>(key: K1, hash: number): <V>(self: HashMap<K, V>) => Option<V>
   /**
-   * Lookup the value for the specified key in the `HashMap` using a custom hash.
+   * Looks up the value for the specified key in the `HashMap` safely using a custom hash.
    *
    * **Example** (Looking up values with a hash)
    *
@@ -577,7 +575,7 @@ export const getHash: {
 } = internal.getHash
 
 /**
- * Unsafely lookup the value for the specified key in the `HashMap` using the
+ * Looks up the value for the specified key in the `HashMap` unsafely using the
  * internal hashing function.
  *
  * **Gotchas**
@@ -615,7 +613,7 @@ export const getHash: {
  */
 export const getUnsafe: {
   /**
-   * Unsafely lookup the value for the specified key in the `HashMap` using the
+   * Looks up the value for the specified key in the `HashMap` unsafely using the
    * internal hashing function.
    *
    * **Gotchas**
@@ -653,7 +651,7 @@ export const getUnsafe: {
    */
   <K1 extends K, K>(key: K1): <V>(self: HashMap<K, V>) => V
   /**
-   * Unsafely lookup the value for the specified key in the `HashMap` using the
+   * Looks up the value for the specified key in the `HashMap` unsafely using the
    * internal hashing function.
    *
    * **Gotchas**
@@ -693,7 +691,7 @@ export const getUnsafe: {
 } = internal.getUnsafe
 
 /**
- * Checks if the specified key has an entry in the `HashMap`.
+ * Checks whether the specified key has an entry in the `HashMap`.
  *
  * **Example** (Checking for keys)
  *
@@ -715,7 +713,7 @@ export const getUnsafe: {
  */
 export const has: {
   /**
-   * Checks if the specified key has an entry in the `HashMap`.
+   * Checks whether the specified key has an entry in the `HashMap`.
    *
    * **Example** (Checking for keys)
    *
@@ -737,7 +735,7 @@ export const has: {
    */
   <K1 extends K, K>(key: K1): <K, V>(self: HashMap<K, V>) => boolean
   /**
-   * Checks if the specified key has an entry in the `HashMap`.
+   * Checks whether the specified key has an entry in the `HashMap`.
    *
    * **Example** (Checking for keys)
    *
@@ -761,7 +759,7 @@ export const has: {
 } = internal.has
 
 /**
- * Checks if the specified key has an entry in the `HashMap` using a custom
+ * Checks whether the specified key has an entry in the `HashMap` using a custom
  * hash.
  *
  * **Example** (Checking keys with a hash)
@@ -792,7 +790,7 @@ export const has: {
  */
 export const hasHash: {
   /**
-   * Checks if the specified key has an entry in the `HashMap` using a custom
+   * Checks whether the specified key has an entry in the `HashMap` using a custom
    * hash.
    *
    * **Example** (Checking keys with a hash)
@@ -823,7 +821,7 @@ export const hasHash: {
    */
   <K1 extends K, K>(key: K1, hash: number): <V>(self: HashMap<K, V>) => boolean
   /**
-   * Checks if the specified key has an entry in the `HashMap` using a custom
+   * Checks whether the specified key has an entry in the `HashMap` using a custom
    * hash.
    *
    * **Example** (Checking keys with a hash)
@@ -856,7 +854,7 @@ export const hasHash: {
 } = internal.hasHash
 
 /**
- * Checks if an element matching the given predicate exists in the given `HashMap`.
+ * Checks whether an element matching the given predicate exists in the given `HashMap`.
  *
  * **Example** (Checking entries by predicate)
  *
@@ -873,7 +871,7 @@ export const hasHash: {
  */
 export const hasBy: {
   /**
-   * Checks if an element matching the given predicate exists in the given `HashMap`.
+   * Checks whether an element matching the given predicate exists in the given `HashMap`.
    *
    * **Example** (Checking entries by predicate)
    *
@@ -890,7 +888,7 @@ export const hasBy: {
    */
   <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>) => boolean): (self: HashMap<K, V>) => boolean
   /**
-   * Checks if an element matching the given predicate exists in the given `HashMap`.
+   * Checks whether an element matching the given predicate exists in the given `HashMap`.
    *
    * **Example** (Checking entries by predicate)
    *
@@ -1660,7 +1658,7 @@ export const union: {
 } = internal.union
 
 /**
- * Remove the entry for the specified key in the `HashMap` using the internal
+ * Removes the entry for the specified key in the `HashMap` using the internal
  * hashing function.
  *
  * **Example** (Removing a key)
@@ -1681,7 +1679,7 @@ export const union: {
  */
 export const remove: {
   /**
-   * Remove the entry for the specified key in the `HashMap` using the internal
+   * Removes the entry for the specified key in the `HashMap` using the internal
    * hashing function.
    *
    * **Example** (Removing a key)
@@ -1702,7 +1700,7 @@ export const remove: {
    */
   <K>(key: K): <V>(self: HashMap<K, V>) => HashMap<K, V>
   /**
-   * Remove the entry for the specified key in the `HashMap` using the internal
+   * Removes the entry for the specified key in the `HashMap` using the internal
    * hashing function.
    *
    * **Example** (Removing a key)
@@ -1911,7 +1909,7 @@ export const map: {
 } = internal.map
 
 /**
- * Chains over the entries of the `HashMap` using the specified function.
+ * Maps each entry to a `HashMap` and flattens the results.
  *
  * **Gotchas**
  *
@@ -1938,7 +1936,7 @@ export const map: {
  */
 export const flatMap: {
   /**
-   * Chains over the entries of the `HashMap` using the specified function.
+   * Maps each entry to a `HashMap` and flattens the results.
    *
    * **Gotchas**
    *
@@ -1965,7 +1963,7 @@ export const flatMap: {
    */
   <A, K, B>(f: (value: A, key: K) => HashMap<K, B>): (self: HashMap<K, A>) => HashMap<K, B>
   /**
-   * Chains over the entries of the `HashMap` using the specified function.
+   * Maps each entry to a `HashMap` and flattens the results.
    *
    * **Gotchas**
    *
@@ -2341,7 +2339,7 @@ export const findFirst: {
 } = internal.findFirst
 
 /**
- * Checks if any entry in a hashmap meets a specific condition.
+ * Checks whether any entry in a hashmap meets a specific condition.
  *
  * **Example** (Checking for any matching entry)
  *
@@ -2359,7 +2357,7 @@ export const findFirst: {
  */
 export const some: {
   /**
-   * Checks if any entry in a hashmap meets a specific condition.
+   * Checks whether any entry in a hashmap meets a specific condition.
    *
    * **Example** (Checking for any matching entry)
    *
@@ -2377,7 +2375,7 @@ export const some: {
    */
   <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => boolean
   /**
-   * Checks if any entry in a hashmap meets a specific condition.
+   * Checks whether any entry in a hashmap meets a specific condition.
    *
    * **Example** (Checking for any matching entry)
    *
@@ -2397,7 +2395,7 @@ export const some: {
 } = internal.some
 
 /**
- * Checks if all entries in a hashmap meets a specific condition.
+ * Checks whether all entries in a hashmap meets a specific condition.
  *
  * **Example** (Checking all entries)
  *
@@ -2415,7 +2413,7 @@ export const some: {
  */
 export const every: {
   /**
-   * Checks if all entries in a hashmap meets a specific condition.
+   * Checks whether all entries in a hashmap meets a specific condition.
    *
    * **Example** (Checking all entries)
    *
@@ -2433,7 +2431,7 @@ export const every: {
    */
   <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => boolean
   /**
-   * Checks if all entries in a hashmap meets a specific condition.
+   * Checks whether all entries in a hashmap meets a specific condition.
    *
    * **Example** (Checking all entries)
    *

package/src/HashRing.ts

@@ -166,7 +166,7 @@ const Proto = {
 }
 
 /**
- * Add new nodes to the ring. If a node already exists in the ring, it
+ * Adds new nodes to the ring. If a node already exists in the ring, it
  * will be updated. For example, you can use this to update the node's weight.
  *
  * **When to use**
@@ -178,7 +178,7 @@ const Proto = {
  */
 export const addMany: {
   /**
-   * Add new nodes to the ring. If a node already exists in the ring, it
+   * Adds new nodes to the ring. If a node already exists in the ring, it
    * will be updated. For example, you can use this to update the node's weight.
    *
    * **When to use**
@@ -195,7 +195,7 @@ export const addMany: {
     }
   ): (self: HashRing<A>) => HashRing<A>
   /**
-   * Add new nodes to the ring. If a node already exists in the ring, it
+   * Adds new nodes to the ring. If a node already exists in the ring, it
    * will be updated. For example, you can use this to update the node's weight.
    *
    * **When to use**
@@ -258,7 +258,7 @@ function addNodesToRing<A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, keys
 }
 
 /**
- * Add a new node to the ring. If the node already exists in the ring, it
+ * Adds a new node to the ring. If the node already exists in the ring, it
  * will be updated. For example, you can use this to update the node's weight.
  *
  * **When to use**
@@ -284,7 +284,7 @@ function addNodesToRing<A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, keys
  */
 export const add: {
   /**
-   * Add a new node to the ring. If the node already exists in the ring, it
+   * Adds a new node to the ring. If the node already exists in the ring, it
    * will be updated. For example, you can use this to update the node's weight.
    *
    * **When to use**
@@ -315,7 +315,7 @@ export const add: {
     }
   ): (self: HashRing<A>) => HashRing<A>
   /**
-   * Add a new node to the ring. If the node already exists in the ring, it
+   * Adds a new node to the ring. If the node already exists in the ring, it
    * will be updated. For example, you can use this to update the node's weight.
    *
    * **When to use**
@@ -526,9 +526,7 @@ export const get = <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, input: s
 }
 
 /**
- * Distributes `count` shards across the nodes in the ring, attempting to
- * balance the number of shards allocated to each node. Returns undefined if
- * the hashring has no elements with weight.
+ * Computes a balanced shard distribution across the nodes in the ring.
  *
  * **When to use**
  *

package/src/HashSet.ts

@@ -203,7 +203,7 @@ export const make: <Values extends ReadonlyArray<any>>(
 export const fromIterable: <V>(values: Iterable<V>) => HashSet<V> = internal.fromIterable
 
 /**
- * Checks if a value is a HashSet.
+ * Checks whether a value is a HashSet.
  *
  * **Example** (Checking for a HashSet)
  *
@@ -223,7 +223,7 @@ export const fromIterable: <V>(values: Iterable<V>) => HashSet<V> = internal.fro
  */
 export const isHashSet: {
   /**
-   * Checks if a value is a HashSet.
+   * Checks whether a value is a HashSet.
    *
    * **Example** (Checking for a HashSet)
    *
@@ -243,7 +243,7 @@ export const isHashSet: {
    */
   <V>(u: Iterable<V>): u is HashSet<V>
   /**
-   * Checks if a value is a HashSet.
+   * Checks whether a value is a HashSet.
    *
    * **Example** (Checking for a HashSet)
    *
@@ -342,7 +342,7 @@ export const add: {
 >(2, internal.add)
 
 /**
- * Checks if the HashSet contains the specified value.
+ * Checks whether the HashSet contains the specified value.
  *
  * **Example** (Checking HashSet membership)
  *
@@ -377,7 +377,7 @@ export const add: {
  */
 export const has: {
   /**
-   * Checks if the HashSet contains the specified value.
+   * Checks whether the HashSet contains the specified value.
    *
    * **Example** (Checking HashSet membership)
    *
@@ -412,7 +412,7 @@ export const has: {
    */
   <V>(value: V): (self: HashSet<V>) => boolean
   /**
-   * Checks if the HashSet contains the specified value.
+   * Checks whether the HashSet contains the specified value.
    *
    * **Example** (Checking HashSet membership)
    *
@@ -552,7 +552,7 @@ export const remove: {
 export const size: <V>(self: HashSet<V>) => number = internal.size
 
 /**
- * Checks if the HashSet is empty.
+ * Checks whether the HashSet is empty.
  *
  * **Example** (Checking whether a HashSet is empty)
  *
@@ -767,7 +767,7 @@ export const difference: {
 >(2, internal.difference)
 
 /**
- * Checks if a HashSet is a subset of another HashSet.
+ * Checks whether a HashSet is a subset of another HashSet.
  *
  * **Example** (Checking subset relationships)
  *
@@ -789,7 +789,7 @@ export const difference: {
  */
 export const isSubset: {
   /**
-   * Checks if a HashSet is a subset of another HashSet.
+   * Checks whether a HashSet is a subset of another HashSet.
    *
    * **Example** (Checking subset relationships)
    *
@@ -811,7 +811,7 @@ export const isSubset: {
    */
   <V1>(that: HashSet<V1>): <V0>(self: HashSet<V0>) => boolean
   /**
-   * Checks if a HashSet is a subset of another HashSet.
+   * Checks whether a HashSet is a subset of another HashSet.
    *
    * **Example** (Checking subset relationships)
    *
@@ -1021,7 +1021,7 @@ export const filter: {
 >(2, internal.filter)
 
 /**
- * Tests whether at least one value in the HashSet satisfies the predicate.
+ * Checks whether at least one value in the HashSet satisfies the predicate.
  *
  * **Example** (Testing whether some values match)
  *
@@ -1042,7 +1042,7 @@ export const filter: {
  */
 export const some: {
   /**
-   * Tests whether at least one value in the HashSet satisfies the predicate.
+   * Checks whether at least one value in the HashSet satisfies the predicate.
    *
    * **Example** (Testing whether some values match)
    *
@@ -1063,7 +1063,7 @@ export const some: {
    */
   <V>(predicate: Predicate<V>): (self: HashSet<V>) => boolean
   /**
-   * Tests whether at least one value in the HashSet satisfies the predicate.
+   * Checks whether at least one value in the HashSet satisfies the predicate.
    *
    * **Example** (Testing whether some values match)
    *
@@ -1089,7 +1089,7 @@ export const some: {
 >(2, internal.some)
 
 /**
- * Tests whether all values in the HashSet satisfy the predicate.
+ * Checks whether all values in the HashSet satisfy the predicate.
  *
  * **Example** (Testing whether every value matches)
  *
@@ -1110,7 +1110,7 @@ export const some: {
  */
 export const every: {
   /**
-   * Tests whether all values in the HashSet satisfy the predicate.
+   * Checks whether all values in the HashSet satisfy the predicate.
    *
    * **Example** (Testing whether every value matches)
    *
@@ -1131,7 +1131,7 @@ export const every: {
    */
   <V>(predicate: Predicate<V>): (self: HashSet<V>) => boolean
   /**
-   * Tests whether all values in the HashSet satisfy the predicate.
+   * Checks whether all values in the HashSet satisfy the predicate.
    *
    * **Example** (Testing whether every value matches)
    *

package/src/Inspectable.ts

@@ -68,7 +68,7 @@ import * as Predicate from "./Predicate.ts"
 import { redact } from "./Redactable.ts"
 
 /**
- * Symbol used by Node.js for custom object inspection.
+ * Defines the symbol used by Node.js for custom object inspection.
  *
  * **When to use**
  *
@@ -184,7 +184,7 @@ export interface Inspectable {
 }
 
 /**
- * Safely converts a value to a JSON-serializable representation.
+ * Converts a value to a JSON-serializable representation safely.
  *
  * **When to use**
  *
@@ -280,7 +280,7 @@ export const toStringUnknown = (u: unknown, whitespace: number | string | undefi
  * MyClass.prototype.constructor = MyClass
  * ```
  *
- * @category models
+ * @category prototypes
  * @since 2.0.0
  */
 export const BaseProto: Inspectable = {
@@ -296,7 +296,7 @@ export const BaseProto: Inspectable = {
 }
 
 /**
- * Abstract base class that implements the Inspectable interface.
+ * Provides an abstract base class that implements the Inspectable interface.
  *
  * **When to use**
  *