effect 4.0.0-beta.70 → 4.0.0-beta.72

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
@@ -68,9 +66,9 @@
  *
  * **See also**
  *
- * - {@link HashSet} for immutable sets backed by hash semantics
+ * - `HashSet` for immutable sets backed by hash semantics
  * - {@link Equal} for structural equality
- * - {@link Hash} for hash implementations used by hashed collections
+ * - `Hash` for hash implementations used by hashed collections
  *
  * @since 2.0.0
  */
@@ -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

@@ -73,6 +73,11 @@ const TypeId = "~effect/cluster/HashRing" as const
  * A weighted consistent-hashing ring for assigning inputs to nodes with stable
  * remapping as nodes are added or removed.
  *
+ * **When to use**
+ *
+ * Use to maintain a mutable weighted hash ring for routing keys or shards to
+ * nodes identified by `PrimaryKey`.
+ *
  * **Details**
  *
  * Nodes are identified by their `PrimaryKey` value and can be iterated from the
@@ -92,6 +97,24 @@ export interface HashRing<A extends PrimaryKey.PrimaryKey> extends Pipeable, Ite
 /**
  * Checks whether a value is a `HashRing`.
  *
+ * **When to use**
+ *
+ * Use to narrow an `unknown` value before treating it as a `HashRing`, such as
+ * values crossing an untyped boundary.
+ *
+ * **Details**
+ *
+ * The guard checks for the module's internal `TypeId` property and narrows to
+ * `HashRing<any>`.
+ *
+ * **Gotchas**
+ *
+ * This is a structural type-id check; it does not validate the ring's `nodes`,
+ * `ring`, or weight state.
+ *
+ * @see {@link HashRing} for the type narrowed by this guard
+ * @see {@link make} for creating an empty `HashRing`
+ *
  * @category guards
  * @since 3.19.0
  */
@@ -100,11 +123,19 @@ export const isHashRing = (u: unknown): u is HashRing<any> => hasProperty(u, Typ
 /**
  * Creates an empty `HashRing`.
  *
+ * **When to use**
+ *
+ * Use to create an empty weighted consistent-hashing ring with the default or
+ * custom virtual-point density.
+ *
  * **Details**
  *
  * `baseWeight` controls how many virtual points are added for a node with
  * weight `1`; it defaults to `128` and is clamped to at least `1`.
  *
+ * @see {@link add} for registering one node after creation
+ * @see {@link addMany} for registering several nodes after creation
+ *
  * @category constructors
  * @since 3.19.0
  */
@@ -135,17 +166,25 @@ 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**
+ *
+ * Use to register or update several nodes in a `HashRing` at the same weight.
+ *
  * @category combinators
  * @since 3.19.0
  */
 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**
+   *
+   * Use to register or update several nodes in a `HashRing` at the same weight.
+   *
    * @category combinators
    * @since 3.19.0
    */
@@ -156,9 +195,13 @@ 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**
+   *
+   * Use to register or update several nodes in a `HashRing` at the same weight.
+   *
    * @category combinators
    * @since 3.19.0
    */
@@ -215,17 +258,53 @@ 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**
+ *
+ * Use to register one node in a `HashRing` so lookups and shard assignments can
+ * return it, or to update that node's weight.
+ *
+ * **Details**
+ *
+ * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
+ * clamped to at least `0.1`.
+ *
+ * **Gotchas**
+ *
+ * This mutates and returns the same ring instance.
+ *
+ * @see {@link addMany} for adding or updating several nodes
+ * @see {@link remove} for unregistering a node
+ * @see {@link has} for checking primary-key membership
+ *
  * @category combinators
  * @since 3.19.0
  */
 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**
+   *
+   * Use to register one node in a `HashRing` so lookups and shard assignments can
+   * return it, or to update that node's weight.
+   *
+   * **Details**
+   *
+   * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
+   * clamped to at least `0.1`.
+   *
+   * **Gotchas**
+   *
+   * This mutates and returns the same ring instance.
+   *
+   * @see {@link addMany} for adding or updating several nodes
+   * @see {@link remove} for unregistering a node
+   * @see {@link has} for checking primary-key membership
+   *
    * @category combinators
    * @since 3.19.0
    */
@@ -236,9 +315,27 @@ 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**
+   *
+   * Use to register one node in a `HashRing` so lookups and shard assignments can
+   * return it, or to update that node's weight.
+   *
+   * **Details**
+   *
+   * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
+   * clamped to at least `0.1`.
+   *
+   * **Gotchas**
+   *
+   * This mutates and returns the same ring instance.
+   *
+   * @see {@link addMany} for adding or updating several nodes
+   * @see {@link remove} for unregistering a node
+   * @see {@link has} for checking primary-key membership
+   *
    * @category combinators
    * @since 3.19.0
    */
@@ -256,6 +353,23 @@ export const add: {
 /**
  * Removes the node from the ring. No-op's if the node does not exist.
  *
+ * **When to use**
+ *
+ * Use to remove a node that has left the pool so future lookups and shard
+ * assignments stop returning it.
+ *
+ * **Details**
+ *
+ * Removal matches by `PrimaryKey.value`, so any value with the same primary key
+ * removes the same ring member.
+ *
+ * **Gotchas**
+ *
+ * This mutates and returns the same ring instance.
+ *
+ * @see {@link add} for registering or updating a node
+ * @see {@link has} for checking membership by primary key
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -263,6 +377,23 @@ export const remove: {
   /**
    * Removes the node from the ring. No-op's if the node does not exist.
    *
+   * **When to use**
+   *
+   * Use to remove a node that has left the pool so future lookups and shard
+   * assignments stop returning it.
+   *
+   * **Details**
+   *
+   * Removal matches by `PrimaryKey.value`, so any value with the same primary key
+   * removes the same ring member.
+   *
+   * **Gotchas**
+   *
+   * This mutates and returns the same ring instance.
+   *
+   * @see {@link add} for registering or updating a node
+   * @see {@link has} for checking membership by primary key
+   *
    * @category combinators
    * @since 3.19.0
    */
@@ -270,6 +401,23 @@ export const remove: {
   /**
    * Removes the node from the ring. No-op's if the node does not exist.
    *
+   * **When to use**
+   *
+   * Use to remove a node that has left the pool so future lookups and shard
+   * assignments stop returning it.
+   *
+   * **Details**
+   *
+   * Removal matches by `PrimaryKey.value`, so any value with the same primary key
+   * removes the same ring member.
+   *
+   * **Gotchas**
+   *
+   * This mutates and returns the same ring instance.
+   *
+   * @see {@link add} for registering or updating a node
+   * @see {@link has} for checking membership by primary key
+   *
    * @category combinators
    * @since 3.19.0
    */
@@ -288,6 +436,20 @@ export const remove: {
 /**
  * Checks whether the ring contains a node with the same `PrimaryKey` value.
  *
+ * **When to use**
+ *
+ * Use to check whether a node value is already registered in a ring by its
+ * `PrimaryKey` value.
+ *
+ * **Details**
+ *
+ * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
+ * matching is by primary key, not object identity or weight.
+ *
+ * @see {@link add} for registering or updating nodes
+ * @see {@link remove} for removing nodes by the same primary-key identity
+ * @see {@link get} for routing an input string to a node
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -295,6 +457,20 @@ export const has: {
   /**
    * Checks whether the ring contains a node with the same `PrimaryKey` value.
    *
+   * **When to use**
+   *
+   * Use to check whether a node value is already registered in a ring by its
+   * `PrimaryKey` value.
+   *
+   * **Details**
+   *
+   * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
+   * matching is by primary key, not object identity or weight.
+   *
+   * @see {@link add} for registering or updating nodes
+   * @see {@link remove} for removing nodes by the same primary-key identity
+   * @see {@link get} for routing an input string to a node
+   *
    * @category combinators
    * @since 3.19.0
    */
@@ -302,6 +478,20 @@ export const has: {
   /**
    * Checks whether the ring contains a node with the same `PrimaryKey` value.
    *
+   * **When to use**
+   *
+   * Use to check whether a node value is already registered in a ring by its
+   * `PrimaryKey` value.
+   *
+   * **Details**
+   *
+   * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
+   * matching is by primary key, not object identity or weight.
+   *
+   * @see {@link add} for registering or updating nodes
+   * @see {@link remove} for removing nodes by the same primary-key identity
+   * @see {@link get} for routing an input string to a node
+   *
    * @category combinators
    * @since 3.19.0
    */
@@ -315,6 +505,14 @@ export const has: {
  * Gets the node which should handle the given input. Returns undefined if
  * the hashring has no elements with weight.
  *
+ * **When to use**
+ *
+ * Use to route a single string input key to the current ring member responsible
+ * for that key.
+ *
+ * @see {@link getShards} for assigning fixed shard indexes instead of routing
+ * one input string at a time
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -328,9 +526,12 @@ 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**
+ *
+ * Use to precompute ownership for a fixed number of shard indexes across the
+ * current ring members.
  *
  * @category combinators
  * @since 3.19.0