effect 3.8.4 → 3.8.5

package/src/TDeferred.ts

@@ -65,7 +65,15 @@ export {
  * @category mutations
  */
 export const done: {
+  /**
+   * @since 2.0.0
+   * @category mutations
+   */
   <A, E>(either: Either.Either<A, E>): (self: TDeferred<A, E>) => STM.STM<boolean>
+  /**
+   * @since 2.0.0
+   * @category mutations
+   */
   <A, E>(self: TDeferred<A, E>, either: Either.Either<A, E>): STM.STM<boolean>
 } = internal.done
 
@@ -74,7 +82,15 @@ export const done: {
  * @category mutations
  */
 export const fail: {
+  /**
+   * @since 2.0.0
+   * @category mutations
+   */
   <E>(error: E): <A>(self: TDeferred<A, E>) => STM.STM<boolean>
+  /**
+   * @since 2.0.0
+   * @category mutations
+   */
   <A, E>(self: TDeferred<A, E>, error: E): STM.STM<boolean>
 } = internal.fail
 
@@ -95,6 +111,14 @@ export const poll: <A, E>(self: TDeferred<A, E>) => STM.STM<Option.Option<Either
  * @category mutations
  */
 export const succeed: {
+  /**
+   * @since 2.0.0
+   * @category mutations
+   */
   <A>(value: A): <E>(self: TDeferred<A, E>) => STM.STM<boolean>
+  /**
+   * @since 2.0.0
+   * @category mutations
+   */
   <A, E>(self: TDeferred<A, E>, value: A): STM.STM<boolean>
 } = internal.succeed

package/src/TMap.ts

@@ -74,7 +74,21 @@ export const empty: <K, V>() => STM.STM<TMap<K, V>> = internal.empty
  * @category elements
  */
 export const find: {
+  /**
+   * Finds the key/value pair matching the specified predicate, and uses the
+   * provided function to extract a value out of it.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, A>(pf: (key: K, value: V) => Option.Option<A>): (self: TMap<K, V>) => STM.STM<Option.Option<A>>
+  /**
+   * Finds the key/value pair matching the specified predicate, and uses the
+   * provided function to extract a value out of it.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, A>(self: TMap<K, V>, pf: (key: K, value: V) => Option.Option<A>): STM.STM<Option.Option<A>>
 } = internal.find
 
@@ -86,9 +100,23 @@ export const find: {
  * @category elements
  */
 export const findSTM: {
+  /**
+   * Finds the key/value pair matching the specified predicate, and uses the
+   * provided effectful function to extract a value out of it.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, A, E, R>(
     f: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>
   ): (self: TMap<K, V>) => STM.STM<Option.Option<A>, E, R>
+  /**
+   * Finds the key/value pair matching the specified predicate, and uses the
+   * provided effectful function to extract a value out of it.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, A, E, R>(
     self: TMap<K, V>,
     f: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>
@@ -103,7 +131,21 @@ export const findSTM: {
  * @category elements
  */
 export const findAll: {
+  /**
+   * Finds all the key/value pairs matching the specified predicate, and uses
+   * the provided function to extract values out them.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, A>(pf: (key: K, value: V) => Option.Option<A>): (self: TMap<K, V>) => STM.STM<Array<A>>
+  /**
+   * Finds all the key/value pairs matching the specified predicate, and uses
+   * the provided function to extract values out them.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, A>(self: TMap<K, V>, pf: (key: K, value: V) => Option.Option<A>): STM.STM<Array<A>>
 } = internal.findAll
 
@@ -115,10 +157,27 @@ export const findAll: {
  * @category elements
  */
 export const findAllSTM: {
+  /**
+   * Finds all the key/value pairs matching the specified predicate, and uses
+   * the provided effectful function to extract values out of them..
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, A, E, R>(
     pf: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>
   ): (self: TMap<K, V>) => STM.STM<Array<A>, E, R>
-  <K, V, A, E, R>(self: TMap<K, V>, pf: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>): STM.STM<Array<A>, E, R>
+  /**
+   * Finds all the key/value pairs matching the specified predicate, and uses
+   * the provided effectful function to extract values out of them..
+   *
+   * @since 2.0.0
+   * @category elements
+   */
+  <K, V, A, E, R>(
+    self: TMap<K, V>,
+    pf: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>
+  ): STM.STM<Array<A>, E, R>
 } = internal.findAllSTM
 
 /**
@@ -128,7 +187,19 @@ export const findAllSTM: {
  * @category elements
  */
 export const forEach: {
+  /**
+   * Atomically performs transactional-effect for each binding present in map.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, X, E, R>(f: (key: K, value: V) => STM.STM<X, E, R>): (self: TMap<K, V>) => STM.STM<void, E, R>
+  /**
+   * Atomically performs transactional-effect for each binding present in map.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V, X, E, R>(self: TMap<K, V>, f: (key: K, value: V) => STM.STM<X, E, R>): STM.STM<void, E, R>
 } = internal.forEach
 
@@ -149,7 +220,19 @@ export const fromIterable: <K, V>(
  * @category elements
  */
 export const get: {
+  /**
+   * Retrieves value associated with given key.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K>(key: K): <V>(self: TMap<K, V>) => STM.STM<Option.Option<V>>
+  /**
+   * Retrieves value associated with given key.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V>(self: TMap<K, V>, key: K): STM.STM<Option.Option<V>>
 } = internal.get
 
@@ -161,7 +244,21 @@ export const get: {
  * @category elements
  */
 export const getOrElse: {
+  /**
+   * Retrieves value associated with given key or default value, in case the key
+   * isn't present.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V>(key: K, fallback: LazyArg<V>): (self: TMap<K, V>) => STM.STM<V>
+  /**
+   * Retrieves value associated with given key or default value, in case the key
+   * isn't present.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V>(self: TMap<K, V>, key: K, fallback: LazyArg<V>): STM.STM<V>
 } = internal.getOrElse
 
@@ -172,7 +269,19 @@ export const getOrElse: {
  * @category elements
  */
 export const has: {
+  /**
+   * Tests whether or not map contains a key.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K>(key: K): <V>(self: TMap<K, V>) => STM.STM<boolean>
+  /**
+   * Tests whether or not map contains a key.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <K, V>(self: TMap<K, V>, key: K): STM.STM<boolean>
 } = internal.has
 
@@ -209,7 +318,23 @@ export const make: <K, V>(...entries: Array<readonly [K, V]>) => STM.STM<TMap<K,
  * @category mutations
  */
 export const merge: {
+  /**
+   * If the key is not already associated with a value, stores the provided value,
+   * otherwise merge the existing value with the new one using function `f` and
+   * store the result.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(key: K, value: V, f: (x: V, y: V) => V): (self: TMap<K, V>) => STM.STM<V>
+  /**
+   * If the key is not already associated with a value, stores the provided value,
+   * otherwise merge the existing value with the new one using function `f` and
+   * store the result.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(self: TMap<K, V>, key: K, value: V, f: (x: V, y: V) => V): STM.STM<V>
 } = internal.merge
 
@@ -220,7 +345,19 @@ export const merge: {
  * @category folding
  */
 export const reduce: {
+  /**
+   * Atomically folds using a pure function.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <Z, K, V>(zero: Z, f: (acc: Z, value: V, key: K) => Z): (self: TMap<K, V>) => STM.STM<Z>
+  /**
+   * Atomically folds using a pure function.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <K, V, Z>(self: TMap<K, V>, zero: Z, f: (acc: Z, value: V, key: K) => Z): STM.STM<Z>
 } = internal.reduce
 
@@ -231,8 +368,24 @@ export const reduce: {
  * @category folding
  */
 export const reduceSTM: {
+  /**
+   * Atomically folds using a transactional function.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <Z, V, K, R, E>(zero: Z, f: (acc: Z, value: V, key: K) => STM.STM<Z, E, R>): (self: TMap<K, V>) => STM.STM<Z, E, R>
-  <Z, V, K, R, E>(self: TMap<K, V>, zero: Z, f: (acc: Z, value: V, key: K) => STM.STM<Z, E, R>): STM.STM<Z, E, R>
+  /**
+   * Atomically folds using a transactional function.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
+  <Z, V, K, R, E>(
+    self: TMap<K, V>,
+    zero: Z,
+    f: (acc: Z, value: V, key: K) => STM.STM<Z, E, R>
+  ): STM.STM<Z, E, R>
 } = internal.reduceSTM
 
 /**
@@ -242,7 +395,19 @@ export const reduceSTM: {
  * @category mutations
  */
 export const remove: {
+  /**
+   * Removes binding for given key.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K>(key: K): <V>(self: TMap<K, V>) => STM.STM<void>
+  /**
+   * Removes binding for given key.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(self: TMap<K, V>, key: K): STM.STM<void>
 } = internal.remove
 
@@ -253,7 +418,19 @@ export const remove: {
  * @category mutations
  */
 export const removeAll: {
+  /**
+   * Deletes all entries associated with the specified keys.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K>(keys: Iterable<K>): <V>(self: TMap<K, V>) => STM.STM<void>
+  /**
+   * Deletes all entries associated with the specified keys.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(self: TMap<K, V>, keys: Iterable<K>): STM.STM<void>
 } = internal.removeAll
 
@@ -265,18 +442,39 @@ export const removeAll: {
  * @category mutations
  */
 export const removeIf: {
+  /**
+   * Removes entries from a `TMap` that satisfy the specified predicate and returns the removed entries
+   * (or `void` if `discard = true`).
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(
     predicate: (key: K, value: V) => boolean,
     options: {
       readonly discard: true
     }
   ): (self: TMap<K, V>) => STM.STM<void>
+  /**
+   * Removes entries from a `TMap` that satisfy the specified predicate and returns the removed entries
+   * (or `void` if `discard = true`).
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(
     predicate: (key: K, value: V) => boolean,
     options?: {
       readonly discard: false
     }
   ): (self: TMap<K, V>) => STM.STM<Array<[K, V]>>
+  /**
+   * Removes entries from a `TMap` that satisfy the specified predicate and returns the removed entries
+   * (or `void` if `discard = true`).
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(
     self: TMap<K, V>,
     predicate: (key: K, value: V) => boolean,
@@ -284,6 +482,13 @@ export const removeIf: {
       readonly discard: true
     }
   ): STM.STM<void>
+  /**
+   * Removes entries from a `TMap` that satisfy the specified predicate and returns the removed entries
+   * (or `void` if `discard = true`).
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(
     self: TMap<K, V>,
     predicate: (key: K, value: V) => boolean,
@@ -301,18 +506,39 @@ export const removeIf: {
  * @category mutations
  */
 export const retainIf: {
+  /**
+   * Retains entries in a `TMap` that satisfy the specified predicate and returns the removed entries
+   * (or `void` if `discard = true`).
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(
     predicate: (key: K, value: V) => boolean,
     options: {
       readonly discard: true
     }
   ): (self: TMap<K, V>) => STM.STM<void>
+  /**
+   * Retains entries in a `TMap` that satisfy the specified predicate and returns the removed entries
+   * (or `void` if `discard = true`).
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(
     predicate: (key: K, value: V) => boolean,
     options?: {
       readonly discard: false
     }
   ): (self: TMap<K, V>) => STM.STM<Array<[K, V]>>
+  /**
+   * Retains entries in a `TMap` that satisfy the specified predicate and returns the removed entries
+   * (or `void` if `discard = true`).
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(
     self: TMap<K, V>,
     predicate: (key: K, value: V) => boolean,
@@ -320,6 +546,13 @@ export const retainIf: {
       readonly discard: true
     }
   ): STM.STM<void>
+  /**
+   * Retains entries in a `TMap` that satisfy the specified predicate and returns the removed entries
+   * (or `void` if `discard = true`).
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(
     self: TMap<K, V>,
     predicate: (key: K, value: V) => boolean,
@@ -336,7 +569,19 @@ export const retainIf: {
  * @category mutations
  */
 export const set: {
+  /**
+   * Stores new binding into the map.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(key: K, value: V): (self: TMap<K, V>) => STM.STM<void>
+  /**
+   * Stores new binding into the map.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(self: TMap<K, V>, key: K, value: V): STM.STM<void>
 } = internal.set
 
@@ -347,7 +592,19 @@ export const set: {
  * @category mutations
  */
 export const setIfAbsent: {
+  /**
+   * Stores new binding in the map if it does not already exist.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(key: K, value: V): (self: TMap<K, V>) => STM.STM<void>
+  /**
+   * Stores new binding in the map if it does not already exist.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(self: TMap<K, V>, key: K, value: V): STM.STM<void>
 } = internal.setIfAbsent
 
@@ -366,7 +623,19 @@ export const size: <K, V>(self: TMap<K, V>) => STM.STM<number> = internal.size
  * @category mutations
  */
 export const takeFirst: {
+  /**
+   * Takes the first matching value, or retries until there is one.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, A>(pf: (key: K, value: V) => Option.Option<A>): (self: TMap<K, V>) => STM.STM<A>
+  /**
+   * Takes the first matching value, or retries until there is one.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, A>(self: TMap<K, V>, pf: (key: K, value: V) => Option.Option<A>): STM.STM<A>
 } = internal.takeFirst
 
@@ -377,8 +646,23 @@ export const takeFirst: {
  * @category mutations
  */
 export const takeFirstSTM: {
+  /**
+   * Takes the first matching value, or retries until there is one.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, A, E, R>(pf: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>): (self: TMap<K, V>) => STM.STM<A, E, R>
-  <K, V, A, E, R>(self: TMap<K, V>, pf: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>): STM.STM<A, E, R>
+  /**
+   * Takes the first matching value, or retries until there is one.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
+  <K, V, A, E, R>(
+    self: TMap<K, V>,
+    pf: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>
+  ): STM.STM<A, E, R>
 } = internal.takeFirstSTM
 
 /**
@@ -388,7 +672,19 @@ export const takeFirstSTM: {
  * @category mutations
  */
 export const takeSome: {
+  /**
+   * Takes all matching values, or retries until there is at least one.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, A>(pf: (key: K, value: V) => Option.Option<A>): (self: TMap<K, V>) => STM.STM<[A, ...Array<A>]>
+  /**
+   * Takes all matching values, or retries until there is at least one.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, A>(self: TMap<K, V>, pf: (key: K, value: V) => Option.Option<A>): STM.STM<[A, ...Array<A>]>
 } = internal.takeSome
 
@@ -399,9 +695,21 @@ export const takeSome: {
  * @category mutations
  */
 export const takeSomeSTM: {
+  /**
+   * Takes all matching values, or retries until there is at least one.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, A, E, R>(
     pf: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>
   ): (self: TMap<K, V>) => STM.STM<[A, ...Array<A>], E, R>
+  /**
+   * Takes all matching values, or retries until there is at least one.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, A, E, R>(
     self: TMap<K, V>,
     pf: (key: K, value: V) => STM.STM<A, Option.Option<E>, R>
@@ -447,7 +755,19 @@ export const toMap: <K, V>(self: TMap<K, V>) => STM.STM<ReadonlyMap<K, V>> = int
  * @category mutations
  */
 export const transform: {
+  /**
+   * Atomically updates all bindings using a pure function.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(f: (key: K, value: V) => readonly [K, V]): (self: TMap<K, V>) => STM.STM<void>
+  /**
+   * Atomically updates all bindings using a pure function.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(self: TMap<K, V>, f: (key: K, value: V) => readonly [K, V]): STM.STM<void>
 } = internal.transform
 
@@ -458,7 +778,19 @@ export const transform: {
  * @category mutations
  */
 export const transformSTM: {
+  /**
+   * Atomically updates all bindings using a transactional function.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, R, E>(f: (key: K, value: V) => STM.STM<readonly [K, V], E, R>): (self: TMap<K, V>) => STM.STM<void, E, R>
+  /**
+   * Atomically updates all bindings using a transactional function.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, R, E>(self: TMap<K, V>, f: (key: K, value: V) => STM.STM<readonly [K, V], E, R>): STM.STM<void, E, R>
 } = internal.transformSTM
 
@@ -469,7 +801,19 @@ export const transformSTM: {
  * @category mutations
  */
 export const transformValues: {
+  /**
+   * Atomically updates all values using a pure function.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <V>(f: (value: V) => V): <K>(self: TMap<K, V>) => STM.STM<void>
+  /**
+   * Atomically updates all values using a pure function.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V>(self: TMap<K, V>, f: (value: V) => V): STM.STM<void>
 } = internal.transformValues
 
@@ -480,7 +824,19 @@ export const transformValues: {
  * @category mutations
  */
 export const transformValuesSTM: {
+  /**
+   * Atomically updates all values using a transactional function.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <V, R, E>(f: (value: V) => STM.STM<V, E, R>): <K>(self: TMap<K, V>) => STM.STM<void, E, R>
+  /**
+   * Atomically updates all values using a transactional function.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
   <K, V, R, E>(self: TMap<K, V>, f: (value: V) => STM.STM<V, E, R>): STM.STM<void, E, R>
 } = internal.transformValuesSTM
 
@@ -495,15 +851,28 @@ export const transformValuesSTM: {
  * @category mutations
  */
 export const updateWith: {
-  <K, V>(
-    key: K,
-    f: (value: Option.Option<V>) => Option.Option<V>
-  ): (self: TMap<K, V>) => STM.STM<Option.Option<V>>
-  <K, V>(
-    self: TMap<K, V>,
-    key: K,
-    f: (value: Option.Option<V>) => Option.Option<V>
-  ): STM.STM<Option.Option<V>>
+  /**
+   * Updates the mapping for the specified key with the specified function,
+   * which takes the current value of the key as an input, if it exists, and
+   * either returns `Some` with a new value to indicate to update the value in
+   * the map or `None` to remove the value from the map. Returns `Some` with the
+   * updated value or `None` if the value was removed from the map.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
+  <K, V>(key: K, f: (value: Option.Option<V>) => Option.Option<V>): (self: TMap<K, V>) => STM.STM<Option.Option<V>>
+  /**
+   * Updates the mapping for the specified key with the specified function,
+   * which takes the current value of the key as an input, if it exists, and
+   * either returns `Some` with a new value to indicate to update the value in
+   * the map or `None` to remove the value from the map. Returns `Some` with the
+   * updated value or `None` if the value was removed from the map.
+   *
+   * @since 2.0.0
+   * @category mutations
+   */
+  <K, V>(self: TMap<K, V>, key: K, f: (value: Option.Option<V>) => Option.Option<V>): STM.STM<Option.Option<V>>
 } = internal.updateWith
 
 /**