funfix-types/src/monad.js.flow

Sub-package of Funfix defining type classes inspired by Haskell's standard library

/*!
 * Copyright (c) 2017 by The Funfix Project Developers.
 * Some rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/* @flow */

import type { Constructor } from "./kinds"
import { HK, Equiv } from "./kinds"
import { Either } from "funfix-core"
import {
  Apply, ApplyLaws,
  Applicative, ApplicativeLaws,
  ApplicativeError, ApplicativeErrorLaws
} from "./applicative"

export interface FlatMap<F> extends Apply<F>{
  flatMap<A, B>(fa: HK<F, A>, f: (a: A) => HK<F, B>): HK<F, B>;
  tailRecM<A, B>(a: A, f: (a: A) => HK<F, Either<A, B>>): HK<F, B>;
  followedBy<A, B>(fa: HK<F, A>, fb: HK<F, B>): HK<F, B>;
  followedByL<A, B>(fa: HK<F, A>, fb: () => HK<F, B>): HK<F, B>;
  forEffect<A, B>(fa: HK<F, A>, fb: HK<F, B>): HK<F, A>;
  forEffectL<A, B>(fa: HK<F, A>, fb: () => HK<F, B>): HK<F, A>;

  // Implements TypeClass<F>
  static +_funTypeId: string;
  static +_funSupertypeIds: string[];
  static +_funErasure: FlatMap<any>;
}

export interface FlatMapLaws<F> extends ApplyLaws<F> {
  +F: FlatMap<F>;

  flatMapAssociativity<A, B, C>(fa: HK<F, A>, f: (a: A) => HK<F, B>, g: (b: B) => HK<F, C>): Equiv<HK<F, C>>;
  flatMapConsistentApply<A, B>(fa: HK<F, A>, fab: HK<F, (a: A) => B>): Equiv<HK<F, B>>;
  followedByConsistency<A, B>(fa: HK<F, A>, fb: HK<F, B>): Equiv<HK<F, B>>;
  followedByLConsistency<A, B>(fa: HK<F, A>, fb: HK<F, B>): Equiv<HK<F, B>>;
  forEffectConsistency<A, B>(fa: HK<F, A>, fb: HK<F, B>): Equiv<HK<F, A>>;
  forEffectLConsistency<A, B>(fa: HK<F, A>, fb: HK<F, B>): Equiv<HK<F, A>>;
  tailRecMConsistentFlatMap<A>(a: A, f: (a: A) => HK<F, A>): Equiv<HK<F, A>>;
}

declare export function flatMapOf<F>(c: Constructor<F>): FlatMap<F>;
declare export function flatMapLawsOf<F>(instance: FlatMap<F>): FlatMapLaws<F>;

export interface Monad<F> extends FlatMap<F>, Applicative<F> {
  // Implements TypeClass<F>
  static +_funTypeId: string;
  static +_funSupertypeIds: string[];
  static +_funErasure: Monad<any>;
}

export interface MonadLaws<F> extends ApplicativeLaws<F>, FlatMapLaws<F> {
  +F: Monad<F>;

  monadLeftIdentity<A, B>(a: A, f: (a: A) => HK<F, B>): Equiv<HK<F, B>>;
  monadRightIdentity<A, B>(fa: HK<F, A>): Equiv<HK<F, A>>;
  mapFlatMapCoherence<A, B>(fa: HK<F, A>, f: (a: A) => B): Equiv<HK<F, B>>;
  tailRecMStackSafety(): Equiv<HK<F, number>>;
}

declare export function monadOf<F>(c: Constructor<F>): Monad<F>;
declare export function monadLawsOf<F>(instance: Monad<F>): MonadLaws<F>;

export interface MonadError<F, E> extends ApplicativeError<F, E>, Monad<F> {
  // Implements TypeClass<F>
  static +_funTypeId: string;
  static +_funSupertypeIds: string[];
  static +_funErasure: MonadError<any, any>;
}

export interface MonadErrorLaws<F, E> extends ApplicativeErrorLaws<F, E>, MonadLaws<F> {
  +F: MonadError<F, E>;

  monadErrorLeftZero<A, B>(e: E, f: (a: A) => HK<F, B>): Equiv<HK<F, B>>;
}

declare export function monadErrorOf<F, E>(c: Constructor<F>): MonadError<F, E>;
declare export function monadErrorLawsOf<F, E>(instance: MonadError<F, E>): MonadErrorLaws<F, E>;