effect 3.8.4 → 3.9.0

package/src/HashMap.ts

@@ -66,6 +66,22 @@ export declare namespace HashMap {
    * @category type-level
    */
   export type Value<T extends HashMap<any, any>> = [T] extends [HashMap<infer _K, infer _V>] ? _V : never
+
+  /**
+   * This type-level utility extracts the entry type `[K, V]` from a `HashMap<K, V>` type.
+   *
+   * @example
+   * import { HashMap } from "effect"
+   *
+   * declare const hm: HashMap.HashMap<string, number>
+   *
+   * // $ExpectType [string, number]
+   * type V = HashMap.HashMap.Entry<typeof hm>
+   *
+   * @since 3.9.0
+   * @category type-level
+   */
+  export type Entry<T extends HashMap<any, any>> = [Key<T>, Value<T>]
 }
 
 /**
@@ -73,7 +89,15 @@ export declare namespace HashMap {
  * @category refinements
  */
 export const isHashMap: {
+  /**
+   * @since 2.0.0
+   * @category refinements
+   */
   <K, V>(u: Iterable<readonly [K, V]>): u is HashMap<K, V>
+  /**
+   * @since 2.0.0
+   * @category refinements
+   */
   (u: unknown): u is HashMap<unknown, unknown>
 } = HM.isHashMap
 
@@ -122,7 +146,21 @@ export const isEmpty: <K, V>(self: HashMap<K, V>) => boolean = HM.isEmpty
  * @category elements
  */
 export const get: {
+  /**
+   * Safely lookup the value for the specified key in the `HashMap` using the
+   * internal hashing function.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K1>(key: K1): <K, V>(self: HashMap<K, V>) => Option<V>
+  /**
+   * Safely lookup the value for the specified key in the `HashMap` using the
+   * internal hashing function.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, K1>(self: HashMap<K, V>, key: K1): Option<V>
 } = HM.get
 
@@ -133,7 +171,19 @@ export const get: {
  * @category elements
  */
 export const getHash: {
+  /**
+   * Lookup the value for the specified key in the `HashMap` using a custom hash.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K1>(key: K1, hash: number): <K, V>(self: HashMap<K, V>) => Option<V>
+  /**
+   * Lookup the value for the specified key in the `HashMap` using a custom hash.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, K1>(self: HashMap<K, V>, key: K1, hash: number): Option<V>
 } = HM.getHash
 
@@ -145,7 +195,21 @@ export const getHash: {
  * @category unsafe
  */
 export const unsafeGet: {
+  /**
+   * Unsafely lookup the value for the specified key in the `HashMap` using the
+   * internal hashing function.
+   *
+   * @since 2.0.0
+   * @category unsafe
+   */
   <K1>(key: K1): <K, V>(self: HashMap<K, V>) => V
+  /**
+   * Unsafely lookup the value for the specified key in the `HashMap` using the
+   * internal hashing function.
+   *
+   * @since 2.0.0
+   * @category unsafe
+   */
   <K, V, K1>(self: HashMap<K, V>, key: K1): V
 } = HM.unsafeGet
 
@@ -156,7 +220,19 @@ export const unsafeGet: {
  * @category elements
  */
 export const has: {
+  /**
+   * Checks if the specified key has an entry in the `HashMap`.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K1>(key: K1): <K, V>(self: HashMap<K, V>) => boolean
+  /**
+   * Checks if the specified key has an entry in the `HashMap`.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, K1>(self: HashMap<K, V>, key: K1): boolean
 } = HM.has
 
@@ -168,7 +244,21 @@ export const has: {
  * @category elements
  */
 export const hasHash: {
+  /**
+   * Checks if the specified key has an entry in the `HashMap` using a custom
+   * hash.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K1>(key: K1, hash: number): <K, V>(self: HashMap<K, V>) => boolean
+  /**
+   * Checks if the specified key has an entry in the `HashMap` using a custom
+   * hash.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, K1>(self: HashMap<K, V>, key: K1, hash: number): boolean
 } = HM.hasHash
 
@@ -179,7 +269,19 @@ export const hasHash: {
  * @since 2.0.0
  */
 export const set: {
+  /**
+   * Sets the specified key to the specified value using the internal hashing
+   * function.
+   *
+   * @since 2.0.0
+   */
   <K, V>(key: K, value: V): (self: HashMap<K, V>) => HashMap<K, V>
+  /**
+   * Sets the specified key to the specified value using the internal hashing
+   * function.
+   *
+   * @since 2.0.0
+   */
   <K, V>(self: HashMap<K, V>, key: K, value: V): HashMap<K, V>
 } = HM.set
 
@@ -251,7 +353,17 @@ export const endMutation: <K, V>(self: HashMap<K, V>) => HashMap<K, V> = HM.endM
  * @since 2.0.0
  */
 export const mutate: {
+  /**
+   * Mutates the `HashMap` within the context of the provided function.
+   *
+   * @since 2.0.0
+   */
   <K, V>(f: (self: HashMap<K, V>) => void): (self: HashMap<K, V>) => HashMap<K, V>
+  /**
+   * Mutates the `HashMap` within the context of the provided function.
+   *
+   * @since 2.0.0
+   */
   <K, V>(self: HashMap<K, V>, f: (self: HashMap<K, V>) => void): HashMap<K, V>
 } = HM.mutate
 
@@ -266,7 +378,27 @@ export const mutate: {
  * @since 2.0.0
  */
 export const modifyAt: {
+  /**
+   * Set or remove the specified key in the `HashMap` using the specified
+   * update function. The value of the specified key will be computed using the
+   * provided hash.
+   *
+   * The update function will be invoked with the current value of the key if it
+   * exists, or `None` if no such value exists.
+   *
+   * @since 2.0.0
+   */
   <K, V>(key: K, f: HashMap.UpdateFn<V>): (self: HashMap<K, V>) => HashMap<K, V>
+  /**
+   * Set or remove the specified key in the `HashMap` using the specified
+   * update function. The value of the specified key will be computed using the
+   * provided hash.
+   *
+   * The update function will be invoked with the current value of the key if it
+   * exists, or `None` if no such value exists.
+   *
+   * @since 2.0.0
+   */
   <K, V>(self: HashMap<K, V>, key: K, f: HashMap.UpdateFn<V>): HashMap<K, V>
 } = HM.modifyAt
 
@@ -283,7 +415,31 @@ export const modifyAt: {
  * @since 2.0.0
  */
 export const modifyHash: {
+  /**
+   * Alter the value of the specified key in the `HashMap` using the specified
+   * update function. The value of the specified key will be computed using the
+   * provided hash.
+   *
+   * The update function will be invoked with the current value of the key if it
+   * exists, or `None` if no such value exists.
+   *
+   * This function will always either update or insert a value into the `HashMap`.
+   *
+   * @since 2.0.0
+   */
   <K, V>(key: K, hash: number, f: HashMap.UpdateFn<V>): (self: HashMap<K, V>) => HashMap<K, V>
+  /**
+   * Alter the value of the specified key in the `HashMap` using the specified
+   * update function. The value of the specified key will be computed using the
+   * provided hash.
+   *
+   * The update function will be invoked with the current value of the key if it
+   * exists, or `None` if no such value exists.
+   *
+   * This function will always either update or insert a value into the `HashMap`.
+   *
+   * @since 2.0.0
+   */
   <K, V>(self: HashMap<K, V>, key: K, hash: number, f: HashMap.UpdateFn<V>): HashMap<K, V>
 } = HM.modifyHash
 
@@ -293,7 +449,17 @@ export const modifyHash: {
  * @since 2.0.0
  */
 export const modify: {
+  /**
+   * Updates the value of the specified key within the `HashMap` if it exists.
+   *
+   * @since 2.0.0
+   */
   <K, V>(key: K, f: (v: V) => V): (self: HashMap<K, V>) => HashMap<K, V>
+  /**
+   * Updates the value of the specified key within the `HashMap` if it exists.
+   *
+   * @since 2.0.0
+   */
   <K, V>(self: HashMap<K, V>, key: K, f: (v: V) => V): HashMap<K, V>
 } = HM.modify
 
@@ -303,7 +469,17 @@ export const modify: {
  * @since 2.0.0
  */
 export const union: {
+  /**
+   * Performs a union of this `HashMap` and that `HashMap`.
+   *
+   * @since 2.0.0
+   */
   <K1, V1>(that: HashMap<K1, V1>): <K0, V0>(self: HashMap<K0, V0>) => HashMap<K1 | K0, V1 | V0>
+  /**
+   * Performs a union of this `HashMap` and that `HashMap`.
+   *
+   * @since 2.0.0
+   */
   <K0, V0, K1, V1>(self: HashMap<K0, V0>, that: HashMap<K1, V1>): HashMap<K0 | K1, V0 | V1>
 } = HM.union
 
@@ -314,7 +490,19 @@ export const union: {
  * @since 2.0.0
  */
 export const remove: {
+  /**
+   * Remove the entry for the specified key in the `HashMap` using the internal
+   * hashing function.
+   *
+   * @since 2.0.0
+   */
   <K>(key: K): <V>(self: HashMap<K, V>) => HashMap<K, V>
+  /**
+   * Remove the entry for the specified key in the `HashMap` using the internal
+   * hashing function.
+   *
+   * @since 2.0.0
+   */
   <K, V>(self: HashMap<K, V>, key: K): HashMap<K, V>
 } = HM.remove
 
@@ -324,7 +512,17 @@ export const remove: {
  * @since 2.0.0
  */
 export const removeMany: {
+  /**
+   * Removes all entries in the `HashMap` which have the specified keys.
+   *
+   * @since 2.0.0
+   */
   <K>(keys: Iterable<K>): <V>(self: HashMap<K, V>) => HashMap<K, V>
+  /**
+   * Removes all entries in the `HashMap` which have the specified keys.
+   *
+   * @since 2.0.0
+   */
   <K, V>(self: HashMap<K, V>, keys: Iterable<K>): HashMap<K, V>
 } = HM.removeMany
 
@@ -335,7 +533,19 @@ export const removeMany: {
  * @category mapping
  */
 export const map: {
+  /**
+   * Maps over the entries of the `HashMap` using the specified function.
+   *
+   * @since 2.0.0
+   * @category mapping
+   */
   <A, V, K>(f: (value: V, key: K) => A): (self: HashMap<K, V>) => HashMap<K, A>
+  /**
+   * Maps over the entries of the `HashMap` using the specified function.
+   *
+   * @since 2.0.0
+   * @category mapping
+   */
   <K, V, A>(self: HashMap<K, V>, f: (value: V, key: K) => A): HashMap<K, A>
 } = HM.map
 
@@ -348,7 +558,23 @@ export const map: {
  * @category sequencing
  */
 export const flatMap: {
+  /**
+   * Chains over the entries of the `HashMap` using the specified function.
+   *
+   * **NOTE**: the hash and equal of both maps have to be the same.
+   *
+   * @since 2.0.0
+   * @category sequencing
+   */
   <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.
+   *
+   * **NOTE**: the hash and equal of both maps have to be the same.
+   *
+   * @since 2.0.0
+   * @category sequencing
+   */
   <K, A, B>(self: HashMap<K, A>, f: (value: A, key: K) => HashMap<K, B>): HashMap<K, B>
 } = HM.flatMap
 
@@ -359,7 +585,19 @@ export const flatMap: {
  * @category traversing
  */
 export const forEach: {
+  /**
+   * Applies the specified function to the entries of the `HashMap`.
+   *
+   * @since 2.0.0
+   * @category traversing
+   */
   <V, K>(f: (value: V, key: K) => void): (self: HashMap<K, V>) => void
+  /**
+   * Applies the specified function to the entries of the `HashMap`.
+   *
+   * @since 2.0.0
+   * @category traversing
+   */
   <V, K>(self: HashMap<K, V>, f: (value: V, key: K) => void): void
 } = HM.forEach
 
@@ -370,7 +608,19 @@ export const forEach: {
  * @category folding
  */
 export const reduce: {
+  /**
+   * Reduces the specified state over the entries of the `HashMap`.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <Z, V, K>(zero: Z, f: (accumulator: Z, value: V, key: K) => Z): (self: HashMap<K, V>) => Z
+  /**
+   * Reduces the specified state over the entries of the `HashMap`.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <K, V, Z>(self: HashMap<K, V>, zero: Z, f: (accumulator: Z, value: V, key: K) => Z): Z
 } = HM.reduce
 
@@ -381,9 +631,33 @@ export const reduce: {
  * @category filtering
  */
 export const filter: {
+  /**
+   * Filters entries out of a `HashMap` using the specified predicate.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <K, A, B extends A>(f: (a: NoInfer<A>, k: K) => a is B): (self: HashMap<K, A>) => HashMap<K, B>
+  /**
+   * Filters entries out of a `HashMap` using the specified predicate.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <K, A>(f: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => HashMap<K, A>
+  /**
+   * Filters entries out of a `HashMap` using the specified predicate.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <K, A, B extends A>(self: HashMap<K, A>, f: (a: A, k: K) => a is B): HashMap<K, B>
+  /**
+   * Filters entries out of a `HashMap` using the specified predicate.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <K, A>(self: HashMap<K, A>, f: (a: A, k: K) => boolean): HashMap<K, A>
 } = HM.filter
 
@@ -403,7 +677,21 @@ export const compact: <K, A>(self: HashMap<K, Option<A>>) => HashMap<K, A> = HM.
  * @category filtering
  */
 export const filterMap: {
+  /**
+   * Maps over the entries of the `HashMap` using the specified partial function
+   * and filters out `None` values.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <A, K, B>(f: (value: A, key: K) => Option<B>): (self: HashMap<K, A>) => HashMap<K, B>
+  /**
+   * Maps over the entries of the `HashMap` using the specified partial function
+   * and filters out `None` values.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <K, A, B>(self: HashMap<K, A>, f: (value: A, key: K) => Option<B>): HashMap<K, B>
 } = HM.filterMap
 
@@ -415,8 +703,36 @@ export const filterMap: {
  * @since 2.0.0
  */
 export const findFirst: {
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <K, A, B extends A>(predicate: (a: NoInfer<A>, k: K) => a is B): (self: HashMap<K, A>) => Option<[K, B]>
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => Option<[K, A]>
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <K, A, B extends A>(self: HashMap<K, A>, predicate: (a: A, k: K) => a is B): Option<[K, B]>
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): Option<[K, A]>
 } = HM.findFirst