effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Hash.ts

@@ -1,9 +1,53 @@
 /**
- * This module provides utilities for hashing values in TypeScript.
+ * The `Hash` module computes Effect hash values and defines the interface for
+ * objects that want to provide their own hash implementation. Hashes are small
+ * numeric fingerprints used by Effect data structures to bucket values quickly;
+ * they are not cryptographic digests and they are not proof that two values are
+ * equal.
+ *
+ * **Mental model**
+ *
+ * - {@link hash} dispatches by JavaScript type and handles primitives,
+ *   arrays, typed arrays, maps, sets, plain objects, dates, regular
+ *   expressions, and custom hashable objects
+ * - Objects can implement {@link Hash} by defining a method at {@link symbol}
+ * - Structural object hashes are cached, so repeated hashing of the same object
+ *   is cheap after the first computation
+ * - {@link random} gives reference-stable hash values for values that should
+ *   be hashed by identity
+ * - Lower-level helpers such as {@link combine}, {@link string},
+ *   {@link number}, {@link structure}, {@link structureKeys}, and
+ *   {@link array} are useful when implementing custom hashes
+ *
+ * **Quickstart**
+ *
+ * **Example** (Implementing a custom hash)
  *
- * Hashing is the process of converting data into a fixed-size numeric value,
- * typically used for data structures like hash tables, equality comparisons,
- * and efficient data storage.
+ * ```ts
+ * import { Hash } from "effect"
+ *
+ * class UserKey implements Hash.Hash {
+ *   constructor(
+ *     readonly id: string,
+ *     readonly region: string
+ *   ) {}
+ *
+ *   [Hash.symbol](): number {
+ *     return Hash.combine(Hash.string(this.region))(Hash.string(this.id))
+ *   }
+ * }
+ *
+ * const value = Hash.hash(new UserKey("user-1", "eu"))
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - Hash collisions are possible; hash-based collections also need equality
+ *   semantics to decide whether two values are actually the same
+ * - Do not mutate an object after hashing it structurally, because the cached
+ *   hash can become stale
+ * - Use {@link random} or a custom {@link Hash} implementation for mutable
+ *   objects that should be compared by reference identity
  *
  * @since 2.0.0
  */
@@ -14,6 +58,15 @@ import { hasProperty } from "./Predicate.ts"
 /**
  * The unique identifier used to identify objects that implement the Hash interface.
  *
+ * **When to use**
+ *
+ * Use as the computed property key for the method that supplies a custom hash
+ * value on a `Hash` implementor.
+ *
+ * @see {@link Hash} for the interface implemented with this symbol
+ * @see {@link isHash} for checking whether a value implements `Hash`
+ * @see {@link hash} for computing hash values
+ *
  * @category symbols
  * @since 2.0.0
  */
@@ -22,6 +75,10 @@ export const symbol = "~effect/interfaces/Hash"
 /**
  * A type that represents an object that can be hashed.
  *
+ * **When to use**
+ *
+ * Use to let a custom type provide its own stable hash value.
+ *
  * **Details**
  *
  * Objects implementing this interface provide a method to compute their hash value,
@@ -54,6 +111,11 @@ export interface Hash {
 /**
  * Computes a hash value for any given value.
  *
+ * **When to use**
+ *
+ * Use to compute an Effect hash for primitives, collections, and hashable
+ * objects.
+ *
  * **Details**
  *
  * This function can hash primitives (numbers, strings, booleans, etc.) as well as
@@ -144,6 +206,10 @@ export const hash: <A>(self: A) => number = <A>(self: A) => {
 /**
  * Generates a random hash value for an object and caches it.
  *
+ * **When to use**
+ *
+ * Use to hash an object by reference identity instead of structural content.
+ *
  * **Details**
  *
  * This function creates a random hash value for objects that don't have their own
@@ -178,11 +244,15 @@ export const random: <A extends object>(self: A) => number = (self) => {
 /**
  * Combines two hash values into a single hash value.
  *
+ * **When to use**
+ *
+ * Use to build a hash for a composite value by folding together hash values for
+ * its parts.
+ *
  * **Details**
  *
- * This function takes two hash values and combines them using a mathematical
- * operation to produce a new hash value. It's useful for creating hash values
- * of composite structures.
+ * Supports both direct and pipeable usage. The implementation combines two
+ * hash values with `(self * 53) ^ b`.
  *
  * **Example** (Combining hash values)
  *
@@ -200,6 +270,9 @@ export const random: <A extends object>(self: A) => number = (self) => {
  * const result = pipe(hash1, Hash.combine(hash2))
  * ```
  *
+ * @see {@link hash} for computing hash values from arbitrary inputs
+ * @see {@link structureKeys} for hashing selected object fields without manual combination
+ *
  * @category hashing
  * @since 2.0.0
  */
@@ -207,11 +280,15 @@ export const combine: {
   /**
    * Combines two hash values into a single hash value.
    *
+   * **When to use**
+   *
+   * Use to build a hash for a composite value by folding together hash values for
+   * its parts.
+   *
    * **Details**
    *
-   * This function takes two hash values and combines them using a mathematical
-   * operation to produce a new hash value. It's useful for creating hash values
-   * of composite structures.
+   * Supports both direct and pipeable usage. The implementation combines two
+   * hash values with `(self * 53) ^ b`.
    *
    * **Example** (Combining hash values)
    *
@@ -229,6 +306,9 @@ export const combine: {
    * const result = pipe(hash1, Hash.combine(hash2))
    * ```
    *
+   * @see {@link hash} for computing hash values from arbitrary inputs
+   * @see {@link structureKeys} for hashing selected object fields without manual combination
+   *
    * @category hashing
    * @since 2.0.0
    */
@@ -236,11 +316,15 @@ export const combine: {
   /**
    * Combines two hash values into a single hash value.
    *
+   * **When to use**
+   *
+   * Use to build a hash for a composite value by folding together hash values for
+   * its parts.
+   *
    * **Details**
    *
-   * This function takes two hash values and combines them using a mathematical
-   * operation to produce a new hash value. It's useful for creating hash values
-   * of composite structures.
+   * Supports both direct and pipeable usage. The implementation combines two
+   * hash values with `(self * 53) ^ b`.
    *
    * **Example** (Combining hash values)
    *
@@ -258,6 +342,9 @@ export const combine: {
    * const result = pipe(hash1, Hash.combine(hash2))
    * ```
    *
+   * @see {@link hash} for computing hash values from arbitrary inputs
+   * @see {@link structureKeys} for hashing selected object fields without manual combination
+   *
    * @category hashing
    * @since 2.0.0
    */
@@ -267,6 +354,10 @@ export const combine: {
 /**
  * Optimizes a hash value by applying bit manipulation techniques.
  *
+ * **When to use**
+ *
+ * Use to improve the bit distribution of a raw numeric hash value.
+ *
  * **Details**
  *
  * This function takes a hash value and applies bitwise operations to improve
@@ -293,6 +384,10 @@ export const optimize = (n: number): number => (n & 0xbfffffff) | ((n >>> 1) & 0
 /**
  * Checks if a value implements the Hash interface.
  *
+ * **When to use**
+ *
+ * Use to detect whether an unknown value provides a custom hash implementation.
+ *
  * **Details**
  *
  * This function determines whether a given value has the Hash symbol property,
@@ -323,6 +418,10 @@ export const isHash = (u: unknown): u is Hash => hasProperty(u, symbol)
 /**
  * Computes a hash value for a number.
  *
+ * **When to use**
+ *
+ * Use to hash a JavaScript number with Effect's numeric hash semantics.
+ *
  * **Details**
  *
  * This function creates a hash value for numeric inputs, handling special cases
@@ -369,6 +468,10 @@ export const number = (n: number) => {
 /**
  * Computes a hash value for a string using the djb2 algorithm.
  *
+ * **When to use**
+ *
+ * Use to hash a string directly.
+ *
  * **Details**
  *
  * This function implements a variation of the djb2 hash algorithm, which is
@@ -402,6 +505,10 @@ export const string = (str: string) => {
 /**
  * Computes a hash value for an object using only the specified keys.
  *
+ * **When to use**
+ *
+ * Use to hash an object by a selected set of property keys.
+ *
  * **Details**
  *
  * This function allows you to hash an object by considering only specific keys,
@@ -442,6 +549,10 @@ export const structureKeys = (o: object, keys: Iterable<PropertyKey>) => {
 /**
  * Computes a structural hash for an object using Effect's object key collection.
  *
+ * **When to use**
+ *
+ * Use to hash an object from all structural keys collected by Effect.
+ *
  * **Details**
  *
  * The hash is based on the object's structural keys and their values, including
@@ -478,13 +589,21 @@ const iterableWith = (seed: number, f: (el: any) => number) => (iter: Iterable<a
 }
 
 /**
- * Computes a hash value for an array by hashing all of its elements.
+ * Computes a hash value for an iterable by hashing all of its elements.
+ *
+ * **When to use**
+ *
+ * Use to hash the values yielded by an iterable with Effect hash semantics.
  *
  * **Details**
  *
- * This function creates a hash value based on all elements in the array.
- * The order of elements matters, so arrays with the same elements in different
- * orders will produce different hash values.
+ * The implementation folds element hashes from the seed `6151` with XOR and
+ * then optimizes the final hash.
+ *
+ * **Gotchas**
+ *
+ * A hash is not an equality proof. Because this implementation uses XOR,
+ * reordered inputs can produce the same hash.
  *
  * **Example** (Hashing arrays)
  *
@@ -497,13 +616,14 @@ const iterableWith = (seed: number, f: (el: any) => number) => (iter: Iterable<a
  *
  * console.log(Hash.array(arr1)) // hash of [1, 2, 3]
  * console.log(Hash.array(arr2)) // same hash as arr1
- * console.log(Hash.array(arr3)) // different hash (different order)
+ * console.log(Hash.array(arr3)) // may match reordered inputs
  *
- * // Arrays with same elements in same order produce same hash
  * console.log(Hash.array(arr1) === Hash.array(arr2)) // true
- * console.log(Hash.array(arr1) === Hash.array(arr3)) // false
+ * console.log(Hash.array(arr1) === Hash.array(arr3)) // true
  * ```
  *
+ * @see {@link hash} for the general-purpose hash dispatcher
+ *
  * @category hashing
  * @since 2.0.0
  */

package/src/HashMap.ts

@@ -68,9 +68,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
  */

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
  */
@@ -138,6 +169,10 @@ const Proto = {
  * Add 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
  */
@@ -146,6 +181,10 @@ export const addMany: {
    * Add 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
    */
@@ -159,6 +198,10 @@ export const addMany: {
    * Add 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
    */
@@ -218,6 +261,24 @@ 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
  * 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
  */
@@ -226,6 +287,24 @@ export const add: {
    * Add 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
    */
@@ -239,6 +318,24 @@ export const add: {
    * Add 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
  */
@@ -332,6 +530,11 @@ export const get = <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, input: s
  * balance the number of shards allocated to each node. Returns undefined if
  * the hashring has no elements with weight.
  *
+ * **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
  */