Feature/filterable

src/Array.ts

@@ -3,7 +3,6 @@ import { Applicative, Applicative1, Applicative2, Applicative2C, Applicative3, A
 import { liftA2 } from './Apply'
 import { Either } from './Either'
 import { Extend1 } from './Extend'
-import { Foldable1 } from './Foldable'
 import { HKT, Type, Type2, Type3, URIS, URIS2, URIS3 } from './HKT'
 import { Monad1 } from './Monad'
 import { Monoid } from './Monoid'
@@ -12,9 +11,11 @@ import { Ord, getSemigroup, ordNumber } from './Ord'
 import { Ordering } from './Ordering'
 import { Plus1 } from './Plus'
 import { Setoid, getArraySetoid } from './Setoid'
-import { Traversable1 } from './Traversable'
 import { Unfoldable1 } from './Unfoldable'
 import { Endomorphism, Predicate, Refinement, concat, identity, tuple } from './function'
+import { wiltDefault, Witherable1, witherDefault } from './Witherable'
+import { separated, Separated } from './Compactable'
+import { eitherBool, optionBool } from './Filterable'
 
 // Adapted from https://github.com/purescript/purescript-arrays
 
@@ -179,25 +180,6 @@ const extend = <A, B>(fa: Array<A>, f: (fa: Array<A>) => B): Array<B> => {
   return fa.map((_, i, as) => f(as.slice(i)))
 }
 
-/**
- * @function
- * @since 1.0.0
- */
-export const partitionMap = <A, L, R>(fa: Array<A>, f: (a: A) => Either<L, R>): { left: Array<L>; right: Array<R> } => {
-  const left: Array<L> = []
-  const right: Array<R> = []
-  const len = fa.length
-  for (let i = 0; i < len; i++) {
-    const v = f(fa[i])
-    if (v.isLeft()) {
-      left.push(v.value)
-    } else {
-      right.push(v.value)
-    }
-  }
-  return { left, right }
-}
-
 /**
  * @example
  * flatten([[1], [2], [3]]) // [1, 2, 3]
@@ -520,23 +502,6 @@ export const findLast = <A>(as: Array<A>, predicate: Predicate<A>): Option<A> =>
   return fromNullable(a)
 }
 
-/**
- * Filter an array, keeping the elements which satisfy a predicate function, creating a new array
- * @function
- * @since 1.0.0
- */
-export const filter = <A>(as: Array<A>, predicate: Predicate<A>): Array<A> => {
-  const l = as.length
-  const r = []
-  for (let i = 0; i < l; i++) {
-    const v = as[i]
-    if (predicate(v)) {
-      r.push(v)
-    }
-  }
-  return r
-}
-
 /**
  * @function
  * @since 1.0.0
@@ -634,33 +599,6 @@ export const reverse = <A>(as: Array<A>): Array<A> => {
   return copy(as).reverse()
 }
 
-/**
- * Apply a function to each element in an array, keeping only the results
- * which contain a value, creating a new array
- * @function
- * @since 1.0.0
- */
-export const mapOption = <A, B>(as: Array<A>, f: (a: A) => Option<B>): Array<B> => {
-  const r: Array<B> = []
-  const len = as.length
-  for (let i = 0; i < len; i++) {
-    const v = f(as[i])
-    if (v.isSome()) {
-      r.push(v.value)
-    }
-  }
-  return r
-}
-
-/**
- * Filter an array of optional values, keeping only the elements which contain a value, creating a new array
- * @function
- * @since 1.0.0
- */
-export const catOptions = <A>(as: Array<Option<A>>): Array<A> => {
-  return mapOption(as, identity)
-}
-
 /**
  * Extracts from a list of `Either` all the `Right` elements. All the `Right` elements are extracted in order
  * @function
@@ -802,21 +740,138 @@ export const sortBy1 = <A>(head: Ord<A>, tail: Array<Ord<A>>): Endomorphism<Arra
   return sort(tail.reduce(getSemigroup<A>().concat, head))
 }
 
+/**
+ * {@link Compactable} implementation
+ * Filters an array of optional values, keeping only the elements which contain a value, creating a new array
+ * @function
+ * @since 1.0.0
+ * @example
+ * assert.deepEqual(compact([some(123), none]), [123])
+ */
+export const compact = <A>(as: Array<Option<A>>): Array<A> => {
+  return filterMap(as, identity)
+}
+
+/**
+ * {@link Compactable} implementation
+ * @function
+ * @since 1.6.3
+ * @example
+ * assert.deepEqual(separate([left(123), right('321')]), { left: [123], right: [321] })
+ */
+export const separate = <L, A>(fa: Either<L, A>[]): Separated<L[], A[]> => {
+  return partitionMap(fa, identity)
+}
+
+/**
+ * {@link Filterable} implementation
+ * @function
+ * @since 1.0.0
+ * @example
+ * assert.deepEqual(partitionMap([], x => x), { left: [], right: [] })
+ * assert.deepEqual(partitionMap([right(1), left('foo'), right(2)], x => x), { left: ['foo'], right: [1, 2] })
+ */
+export const partitionMap = <A, L, R>(fa: Array<A>, f: (a: A) => Either<L, R>): Separated<L[], R[]> => {
+  const left: Array<L> = []
+  const right: Array<R> = []
+  const len = fa.length
+  for (let i = 0; i < len; i++) {
+    const v = f(fa[i])
+    if (v.isLeft()) {
+      left.push(v.value)
+    } else {
+      right.push(v.value)
+    }
+  }
+  return separated(left, right)
+}
+
+/**
+ * {@link Filterable} implementation
+ * @function
+ * @since 1.6.3
+ * @example
+ * const p = (n: number) => n > 2
+ * assert.deepEqual(partition([1, 2, 3], p), separated([1, 2], [3]))
+ */
+export const partition = <A>(fa: Array<A>, p: Predicate<A>): Separated<A[], A[]> => {
+  return partitionMap(fa, eitherBool(p))
+}
+
+/**
+ * {@link Filterable} implementation
+ * Apply a function to each element in an array, keeping only the results which contain a value, creating a new array
+ * @function
+ * @since 1.6.3
+ * @example
+ * const f = (n: number) => n > 2 ? some(`${n}!`) : none
+ * assert.deepEqual(filterMap([1, 2, 3], f), ['3!'])
+ */
+export const filterMap = <A, B>(fa: Array<A>, f: (a: A) => Option<B>): B[] => {
+  const result: B[] = []
+  fa.forEach(a => {
+    const optionB = f(a)
+    if (optionB.isSome()) {
+      result.push(optionB.value)
+    }
+  })
+  return result
+}
+
+/**
+ * Filter an array, keeping the elements which satisfy a predicate function, creating a new array
+ * {@link Filterable} implementation
+ * @function
+ * @since 1.0.0
+ * @example
+ * assert.deepEqual(filter([1, 2, 3], n => n % 2 === 1), [1, 3])
+ */
+export const filter = <A>(as: Array<A>, predicate: Predicate<A>): Array<A> => {
+  return filterMap(as, optionBool(predicate))
+}
+
+/**
+ * Alias for {@link mapOption}
+ * @function
+ * @since 1.0.0
+ */
+export const mapOption = filterMap
+
+/**
+ * Alias for {@link compact}
+ * @function
+ * @since 1.0.0
+ */
+export const catOptions = compact
+
+const wither = <F>(F: Applicative<F>) => witherDefault(array, F)
+const wilt = <F>(F: Applicative<F>) => wiltDefault(array, F)
+
+/**
+ * @instance
+ */
 export const array: Monad1<URI> &
-  Foldable1<URI> &
   Unfoldable1<URI> &
-  Traversable1<URI> &
   Alternative1<URI> &
   Plus1<URI> &
-  Extend1<URI> = {
+  Extend1<URI> &
+  Witherable1<URI> = {
   URI,
   map,
+  reduce,
+  traverse,
+  compact,
+  separate,
+  filter,
+  filterMap,
+  partition,
+  partitionMap,
+  wilt,
+  wither,
   of,
   ap,
   chain,
-  reduce,
   unfoldr,
-  traverse,
   zero,
   alt,
   extend

src/Compactable.ts

@@ -0,0 +1,120 @@
+import { HKT, Type, Type2, Type3, URIS, URIS2, URIS3 } from './HKT'
+import { fromEither, Option } from './Option'
+import { Either, fromOption } from './Either'
+import { Functor, Functor1, Functor2, Functor2C, Functor3, Functor3C } from './Functor'
+
+export type Separated<A, B> = {
+  left: A
+  right: B
+}
+/**
+ * @function
+ * @since 1.6.3
+ */
+export const separated = <A, B>(a: A, b: B): Separated<A, B> => ({
+  left: a,
+  right: b
+})
+
+/**
+ * @typeclass
+ * `Compactable` represents data structures which can be _compacted_/_filtered_.
+ * This is a generalization of catMaybes as a new function `compact`. `compact` has relations with {@link Functor}, {@link Applicative}, {@link Monad}, {@link Plus}, and {@link Traversable} in that we can use these classes to provide the ability to operate on a data type by eliminating intermediate Nones. This is useful for representing the filtering out of values, or failure.
+ * - {@link compact}
+ * - {@link separate}
+ * @see https://github.com/LiamGoodacre/purescript-filterable/blob/master/src/Data/Compactable.purs
+ */
+export interface Compactable<F> {
+  readonly URI: F
+  readonly compact: <A>(fa: HKT<F, Option<A>>) => HKT<F, A>
+  readonly separate: <A, B>(fa: HKT<F, Either<A, B>>) => Separated<HKT<F, A>, HKT<F, B>>
+}
+
+export interface Compactable1<F extends URIS> {
+  readonly URI: F
+  readonly compact: <A>(fa: Type<F, Option<A>>) => Type<F, A>
+  readonly separate: <A, B>(fa: Type<F, Either<A, B>>) => Separated<Type<F, A>, HKT<F, B>>
+}
+
+export interface Compactable2<F extends URIS2> {
+  readonly URI: F
+  readonly compact: <L, A>(fa: Type2<F, L, Option<A>>) => Type2<F, L, A>
+  readonly separate: <L, A, B>(fa: Type2<F, L, Either<A, B>>) => Separated<Type2<F, L, A>, Type2<F, L, B>>
+}
+
+export interface Compactable2C<F extends URIS2, L> {
+  readonly URI: F
+  readonly _L: L
+  readonly compact: <A>(fa: Type2<F, L, Option<A>>) => Type2<F, L, A>
+  readonly separate: <A, B>(fa: Type2<F, L, Either<A, B>>) => Separated<Type2<F, L, A>, Type2<F, L, B>>
+}
+
+export interface Compactable3<F extends URIS3> {
+  readonly URI: F
+  readonly compact: <U, L, A>(fa: Type3<F, U, L, Option<A>>) => Type3<F, U, L, A>
+  readonly separate: <U, L, A, B>(fa: Type3<F, U, L, Either<A, B>>) => Separated<Type3<F, U, L, A>, Type3<F, U, L, B>>
+}
+
+export interface Compactable3C<F extends URIS3, U, L> {
+  readonly URI: F
+  readonly _L: L
+  readonly _U: U
+  readonly compact: <A>(fa: Type3<F, U, L, Option<A>>) => Type3<F, U, L, A>
+  readonly separate: <A, B>(fa: Type3<F, U, L, Either<A, B>>) => Separated<Type3<F, U, L, A>, Type3<F, U, L, B>>
+}
+
+/**
+ * Gets default implementation of {@link Compactable.compact} using {@link Compactable.separate}
+ * @function
+ * @since 1.6.3
+ * @experimental
+ */
+export function getCompact<F extends URIS3, U, L>(
+  F: Functor3C<F, U, L> & Pick<Compactable3C<F, U, L>, 'separate'>
+): Compactable3C<F, U, L>['compact']
+export function getCompact<F extends URIS3>(
+  F: Functor3<F> & Pick<Compactable3<F>, 'separate'>
+): Compactable3<F>['compact']
+export function getCompact<F extends URIS2, L>(
+  F: Functor2C<F, L> & Pick<Compactable2C<F, L>, 'separate'>
+): Compactable2C<F, L>['compact']
+export function getCompact<F extends URIS2>(
+  F: Functor2<F> & Pick<Compactable2<F>, 'separate'>
+): Compactable2<F>['compact']
+export function getCompact<F extends URIS>(
+  F: Functor1<F> & Pick<Compactable1<F>, 'separate'>
+): Compactable1<F>['compact']
+export function getCompact<F>(F: Functor<F> & Pick<Compactable<F>, 'separate'>): Compactable<F>['compact']
+export function getCompact<F>(F: Functor<F> & Pick<Compactable<F>, 'separate'>): Compactable<F>['compact'] {
+  return foa => F.separate(F.map(foa, fromOption(null))).right
+}
+
+/**
+ * Gets default implementation of {@link Compactable.separate} using {@link Compactable.compact}
+ * @function
+ * @since 1.6.3
+ * @experimental
+ */
+export function getSeparate<F extends URIS3, U, L>(
+  F: Functor3C<F, U, L> & Pick<Compactable3C<F, U, L>, 'compact'>
+): Compactable3C<F, U, L>['separate']
+export function getSeparate<F extends URIS3>(
+  F: Functor3<F> & Pick<Compactable3<F>, 'compact'>
+): Compactable3<F>['separate']
+export function getSeparate<F extends URIS2, L>(
+  F: Functor2C<F, L> & Pick<Compactable2C<F, L>, 'compact'>
+): Compactable2C<F, L>['separate']
+export function getSeparate<F extends URIS2>(
+  F: Functor2<F> & Pick<Compactable2<F>, 'compact'>
+): Compactable2<F>['separate']
+export function getSeparate<F extends URIS>(
+  F: Functor1<F> & Pick<Compactable1<F>, 'compact'>
+): Compactable1<F>['separate']
+export function getSeparate<F>(F: Functor<F> & Pick<Compactable<F>, 'compact'>): Compactable<F>['separate']
+export function getSeparate<F>(F: Functor<F> & Pick<Compactable<F>, 'compact'>): Compactable<F>['separate'] {
+  return fela => {
+    const left = F.compact(F.map(fela, ela => fromEither(ela.swap())))
+    const right = F.compact(F.map(fela, fromEither))
+    return separated(left, right)
+  }
+}