deprecate foldM in favour of reduceM

Author: gcanti

CHANGELOG.md

@@ -34,6 +34,7 @@ high state of flux, you're at risk of it changing without notice.
     - add `getFilterable` (@gcanti)
   - `Foldable`
     - add `toArray`, #1272 (@newswim)
+    - add `reduceM` (@gcanti)
   - `Identity`
     - add `apS` (@gcanti)
     - add `bind` (@gcanti)
@@ -134,6 +135,8 @@ high state of flux, you're at risk of it changing without notice.
     - add `evaluate` (@gcanti)
     - add `execute` (@gcanti)
 - **Deprecation**
+  - `Foldable`
+    - deprecate `foldM` in favour of `reduceM` (@gcanti)
   - `State`
     - deprecate `evalState` in favour of `evaluate` (@gcanti)
     - deprecate `execState` in favour of `execute` (@gcanti)

docs/modules/Foldable.ts.md

@@ -29,11 +29,12 @@ Added in v2.0.0
   - [FoldableComposition22 (interface)](#foldablecomposition22-interface)
   - [FoldableComposition22C (interface)](#foldablecomposition22c-interface)
   - [FoldableComposition2C1 (interface)](#foldablecomposition2c1-interface)
-  - [foldM](#foldm)
   - [getFoldableComposition](#getfoldablecomposition)
   - [intercalate](#intercalate)
+  - [reduceM](#reducem)
   - [toArray](#toarray)
   - [traverse\_](#traverse_)
+  - [~~foldM~~](#foldm)
 
 ---
 
@@ -260,57 +261,6 @@ export interface FoldableComposition2C1<F extends URIS2, G extends URIS, E> {
 
 Added in v2.0.0
 
-## foldM
-
-Similar to 'reduce', but the result is encapsulated in a monad.
-
-Note: this function is not generally stack-safe, e.g., for monads which build up thunks a la `IO`.
-
-**Signature**
-
-```ts
-export declare function foldM<M extends URIS3, F extends URIS>(
-  M: Monad3<M>,
-  F: Foldable1<F>
-): <R, E, A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => Kind3<M, R, E, B>
-export declare function foldM<M extends URIS3, F extends URIS, E>(
-  M: Monad3C<M, E>,
-  F: Foldable1<F>
-): <R, A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => Kind3<M, R, E, B>
-export declare function foldM<M extends URIS2, F extends URIS>(
-  M: Monad2<M>,
-  F: Foldable1<F>
-): <E, A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind2<M, E, B>) => Kind2<M, E, B>
-export declare function foldM<M extends URIS2, F extends URIS, E>(
-  M: Monad2C<M, E>,
-  F: Foldable1<F>
-): <A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind2<M, E, B>) => Kind2<M, E, B>
-export declare function foldM<M extends URIS, F extends URIS>(
-  M: Monad1<M>,
-  F: Foldable1<F>
-): <A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind<M, B>) => Kind<M, B>
-export declare function foldM<M, F>(
-  M: Monad<M>,
-  F: Foldable<F>
-): <A, B>(fa: HKT<F, A>, b: B, f: (b: B, a: A) => HKT<M, B>) => HKT<M, B>
-```
-
-**Example**
-
-```ts
-import { foldM } from 'fp-ts/Foldable'
-import { option, some } from 'fp-ts/Option'
-import { make, tree } from 'fp-ts/Tree'
-
-const t = make(1, [make(2, []), make(3, []), make(4, [])])
-assert.deepStrictEqual(
-  foldM(option, tree)(t, 0, (b, a) => (a > 2 ? some(b + a) : some(b))),
-  some(7)
-)
-```
-
-Added in v2.0.0
-
 ## getFoldableComposition
 
 Returns the composition of two foldables
@@ -400,6 +350,61 @@ assert.strictEqual(intercalate(monoidString, tree)('|', t), 'a|b|c|d')
 
 Added in v2.0.0
 
+## reduceM
+
+Similar to 'reduce', but the result is encapsulated in a monad.
+
+Note: this function is not generally stack-safe, e.g., for monads which build up thunks a la `IO`.
+
+**Signature**
+
+```ts
+export declare function reduceM<M extends URIS3, F extends URIS>(
+  M: Monad3<M>,
+  F: Foldable1<F>
+): <B, A, R, E>(b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => (fa: Kind<F, A>) => Kind3<M, R, E, B>
+export declare function reduceM<M extends URIS3, F extends URIS, E>(
+  M: Monad3C<M, E>,
+  F: Foldable1<F>
+): <B, A, R>(b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => (fa: Kind<F, A>) => Kind3<M, R, E, B>
+export declare function reduceM<M extends URIS2, F extends URIS>(
+  M: Monad2<M>,
+  F: Foldable1<F>
+): <B, A, E>(b: B, f: (b: B, a: A) => Kind2<M, E, B>) => (fa: Kind<F, A>) => Kind2<M, E, B>
+export declare function reduceM<M extends URIS2, F extends URIS, E>(
+  M: Monad2C<M, E>,
+  F: Foldable1<F>
+): <B, A>(b: B, f: (b: B, a: A) => Kind2<M, E, B>) => (fa: Kind<F, A>) => Kind2<M, E, B>
+export declare function reduceM<M extends URIS, F extends URIS>(
+  M: Monad1<M>,
+  F: Foldable1<F>
+): <B, A>(b: B, f: (b: B, a: A) => Kind<M, B>) => (fa: Kind<F, A>) => Kind<M, B>
+export declare function reduceM<M, F>(
+  M: Monad<M>,
+  F: Foldable<F>
+): <B, A>(b: B, f: (b: B, a: A) => HKT<M, B>) => (fa: HKT<F, A>) => HKT<M, B>
+```
+
+**Example**
+
+```ts
+import { reduceM } from 'fp-ts/Foldable'
+import { Monad, some } from 'fp-ts/Option'
+import { make, Foldable } from 'fp-ts/Tree'
+import { pipe } from 'fp-ts/function'
+
+const t = make(1, [make(2, []), make(3, []), make(4, [])])
+assert.deepStrictEqual(
+  pipe(
+    t,
+    reduceM(Monad, Foldable)(0, (b, a) => (a > 2 ? some(b + a) : some(b)))
+  ),
+  some(7)
+)
+```
+
+Added in v2.8.0
+
 ## toArray
 
 Transforms a `Foldable` into a read-only array.
@@ -476,3 +481,38 @@ assert.strictEqual(log, 'abc')
 ```
 
 Added in v2.0.0
+
+## ~~foldM~~
+
+Use `reduceM` instead
+
+**Signature**
+
+```ts
+export declare function foldM<M extends URIS3, F extends URIS>(
+  M: Monad3<M>,
+  F: Foldable1<F>
+): <R, E, A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => Kind3<M, R, E, B>
+export declare function foldM<M extends URIS3, F extends URIS, E>(
+  M: Monad3C<M, E>,
+  F: Foldable1<F>
+): <R, A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => Kind3<M, R, E, B>
+export declare function foldM<M extends URIS2, F extends URIS>(
+  M: Monad2<M>,
+  F: Foldable1<F>
+): <E, A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind2<M, E, B>) => Kind2<M, E, B>
+export declare function foldM<M extends URIS2, F extends URIS, E>(
+  M: Monad2C<M, E>,
+  F: Foldable1<F>
+): <A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind2<M, E, B>) => Kind2<M, E, B>
+export declare function foldM<M extends URIS, F extends URIS>(
+  M: Monad1<M>,
+  F: Foldable1<F>
+): <A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind<M, B>) => Kind<M, B>
+export declare function foldM<M, F>(
+  M: Monad<M>,
+  F: Foldable<F>
+): <A, B>(fa: HKT<F, A>, b: B, f: (b: B, a: A) => HKT<M, B>) => HKT<M, B>
+```
+
+Added in v2.0.0

src/Foldable.ts

@@ -214,42 +214,37 @@ export function getFoldableComposition<F, G>(F: Foldable<F>, G: Foldable<G>): Fo
   }
 }
 
-// TODO: rename to `reduceM` in v3
 /**
- * Similar to 'reduce', but the result is encapsulated in a monad.
- *
- * Note: this function is not generally stack-safe, e.g., for monads which build up thunks a la `IO`.
- *
- * @example
- * import { foldM } from 'fp-ts/Foldable'
- * import { option, some } from 'fp-ts/Option'
- * import { make, tree } from 'fp-ts/Tree'
- *
- * const t = make(1, [make(2, []), make(3, []), make(4, [])])
- * assert.deepStrictEqual(foldM(option, tree)(t, 0, (b, a) => (a > 2 ? some(b + a) : some(b))), some(7))
+ * Use `reduceM` instead
  *
  * @since 2.0.0
+ * @deprecated
  */
 export function foldM<M extends URIS3, F extends URIS>(
   M: Monad3<M>,
   F: Foldable1<F>
 ): <R, E, A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => Kind3<M, R, E, B>
+/** @deprecated */
 export function foldM<M extends URIS3, F extends URIS, E>(
   M: Monad3C<M, E>,
   F: Foldable1<F>
 ): <R, A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => Kind3<M, R, E, B>
+/** @deprecated */
 export function foldM<M extends URIS2, F extends URIS>(
   M: Monad2<M>,
   F: Foldable1<F>
 ): <E, A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind2<M, E, B>) => Kind2<M, E, B>
+/** @deprecated */
 export function foldM<M extends URIS2, F extends URIS, E>(
   M: Monad2C<M, E>,
   F: Foldable1<F>
 ): <A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind2<M, E, B>) => Kind2<M, E, B>
+/** @deprecated */
 export function foldM<M extends URIS, F extends URIS>(
   M: Monad1<M>,
   F: Foldable1<F>
 ): <A, B>(fa: Kind<F, A>, b: B, f: (b: B, a: A) => Kind<M, B>) => Kind<M, B>
+/** @deprecated */
 export function foldM<M, F>(
   M: Monad<M>,
   F: Foldable<F>
@@ -261,6 +256,53 @@ export function foldM<M, F>(
   return (fa, b, f) => F.reduce(fa, M.of(b), (mb, a) => M.chain(mb, (b) => f(b, a)))
 }
 
+/**
+ * Similar to 'reduce', but the result is encapsulated in a monad.
+ *
+ * Note: this function is not generally stack-safe, e.g., for monads which build up thunks a la `IO`.
+ *
+ * @example
+ * import { reduceM } from 'fp-ts/Foldable'
+ * import { Monad, some } from 'fp-ts/Option'
+ * import { make, Foldable } from 'fp-ts/Tree'
+ * import { pipe } from 'fp-ts/function'
+ *
+ * const t = make(1, [make(2, []), make(3, []), make(4, [])])
+ * assert.deepStrictEqual(pipe(t, reduceM(Monad, Foldable)(0, (b, a) => (a > 2 ? some(b + a) : some(b)))), some(7))
+ *
+ * @since 2.8.0
+ */
+export function reduceM<M extends URIS3, F extends URIS>(
+  M: Monad3<M>,
+  F: Foldable1<F>
+): <B, A, R, E>(b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => (fa: Kind<F, A>) => Kind3<M, R, E, B>
+export function reduceM<M extends URIS3, F extends URIS, E>(
+  M: Monad3C<M, E>,
+  F: Foldable1<F>
+): <B, A, R>(b: B, f: (b: B, a: A) => Kind3<M, R, E, B>) => (fa: Kind<F, A>) => Kind3<M, R, E, B>
+export function reduceM<M extends URIS2, F extends URIS>(
+  M: Monad2<M>,
+  F: Foldable1<F>
+): <B, A, E>(b: B, f: (b: B, a: A) => Kind2<M, E, B>) => (fa: Kind<F, A>) => Kind2<M, E, B>
+export function reduceM<M extends URIS2, F extends URIS, E>(
+  M: Monad2C<M, E>,
+  F: Foldable1<F>
+): <B, A>(b: B, f: (b: B, a: A) => Kind2<M, E, B>) => (fa: Kind<F, A>) => Kind2<M, E, B>
+export function reduceM<M extends URIS, F extends URIS>(
+  M: Monad1<M>,
+  F: Foldable1<F>
+): <B, A>(b: B, f: (b: B, a: A) => Kind<M, B>) => (fa: Kind<F, A>) => Kind<M, B>
+export function reduceM<M, F>(
+  M: Monad<M>,
+  F: Foldable<F>
+): <B, A>(b: B, f: (b: B, a: A) => HKT<M, B>) => (fa: HKT<F, A>) => HKT<M, B>
+export function reduceM<M, F>(
+  M: Monad<M>,
+  F: Foldable<F>
+): <B, A>(b: B, f: (b: B, a: A) => HKT<M, B>) => (fa: HKT<F, A>) => HKT<M, B> {
+  return (b, f) => (fa) => F.reduce(fa, M.of(b), (mb, a) => M.chain(mb, (b) => f(b, a)))
+}
+
 // TODO: curry in v3
 /**
  * Fold a data structure, accumulating values in some `Monoid`, combining adjacent elements using the specified separator

test/Foldable.ts

@@ -4,15 +4,16 @@ import * as I from '../src/IO'
 import * as O from '../src/Option'
 import * as T from '../src/Tree'
 import { monoidString } from '../src/Monoid'
-import { foldM, getFoldableComposition, intercalate, traverse_, toArray } from '../src/Foldable'
+import * as _ from '../src/Foldable'
+import { pipe } from '../src/function'
 
 export const ArrayOptionURI = 'ArrayOption'
 
 export type ArrayOptionURI = typeof ArrayOptionURI
 
 describe('Foldable', () => {
   it('getFoldableComposition', () => {
-    const F = getFoldableComposition(A.Foldable, O.Foldable)
+    const F = _.getFoldableComposition(A.Foldable, O.Foldable)
     // reduce
     assert.deepStrictEqual(F.reduce([O.some('a'), O.some('b'), O.some('c')], '', monoidString.concat), 'abc')
     assert.deepStrictEqual(F.reduce([O.none, O.some('b'), O.none], '', monoidString.concat), 'b')
@@ -43,38 +44,65 @@ describe('Foldable', () => {
   })
 
   it('intercalate', () => {
-    assert.deepStrictEqual(intercalate(monoidString, A.Foldable)(',', ['a', 'b', 'c']), 'a,b,c')
+    assert.deepStrictEqual(_.intercalate(monoidString, A.Foldable)(',', ['a', 'b', 'c']), 'a,b,c')
   })
 
   it('toArray', () => {
     // Option
-    const optionToArray = toArray(O.option)
+    const optionToArray = _.toArray(O.option)
     assert.deepStrictEqual(optionToArray(O.some(1)), [1])
     assert.deepStrictEqual(optionToArray(O.none), [])
 
     // Tree
-    const treeToArray = toArray(T.tree)
+    const treeToArray = _.toArray(T.tree)
     assert.deepStrictEqual(treeToArray(T.make(1, [T.make(2, []), T.make(3, []), T.make(4, [])])), [1, 2, 3, 4])
   })
 
   it('traverse_', () => {
     let log = ''
     const append = (s: String) => () => (log += s)
-    traverse_(I.Applicative, A.Foldable)(['a', 'b', 'c'], append)()
+    _.traverse_(I.Applicative, A.Foldable)(['a', 'b', 'c'], append)()
     assert.deepStrictEqual(log, 'abc')
   })
 
   it('foldM', () => {
     assert.deepStrictEqual(
-      foldM(O.Monad, A.Foldable)([], 1, () => O.none),
+      // tslint:disable-next-line: deprecation
+      _.foldM(O.Monad, A.Foldable)([], 1, () => O.none),
       O.some(1)
     )
     assert.deepStrictEqual(
-      foldM(O.Monad, A.Foldable)([2], 1, () => O.none),
+      // tslint:disable-next-line: deprecation
+      _.foldM(O.Monad, A.Foldable)([2], 1, () => O.none),
       O.none
     )
     assert.deepStrictEqual(
-      foldM(O.Monad, A.Foldable)([2], 1, (b, a) => O.some(b + a)),
+      // tslint:disable-next-line: deprecation
+      _.foldM(O.Monad, A.Foldable)([2], 1, (b, a) => O.some(b + a)),
+      O.some(3)
+    )
+  })
+
+  it('reduceM', () => {
+    assert.deepStrictEqual(
+      pipe(
+        [],
+        _.reduceM(O.Monad, A.Foldable)(1, () => O.none)
+      ),
+      O.some(1)
+    )
+    assert.deepStrictEqual(
+      pipe(
+        [2],
+        _.reduceM(O.Monad, A.Foldable)(1, () => O.none)
+      ),
+      O.none
+    )
+    assert.deepStrictEqual(
+      pipe(
+        [2],
+        _.reduceM(O.Monad, A.Foldable)(1, (b, a) => O.some(b + a))
+      ),
       O.some(3)
     )
   })