Reader overview

The Reader monad (also called the Environment monad). Represents a computation, which can read values from a shared environment, pass values from function to function, and execute sub-computations in a modified environment. Using Reader monad for such computations is often clearer and easier than using the State monad.

In this example the Reader monad provides access to variable bindings. Bindings are a map of number variables. The variable count contains number of variables in the bindings. You can see how to run a Reader monad and retrieve data from it, how to access the Reader data with ask and asks.

Example

import { pipe } from 'fp-ts/function'
import * as O from 'fp-ts/Option'
import * as R from 'fp-ts/Reader'
import * as RR from 'fp-ts/ReadonlyRecord'

interface Bindings extends RR.ReadonlyRecord<string, number> {}

// The Reader monad, which implements this complicated check.
const isCountCorrect: R.Reader<Bindings, boolean> = pipe(
  R.Do,
  R.bind('count', () => R.asks(lookupVar('count'))),
  R.bind('bindings', () => R.ask()),
  R.map(({ count, bindings }) => count === RR.size(bindings))
)

// The selector function to use with 'asks'.
// Returns value of the variable with specified name.
const lookupVar =
  (name: string) =>
  (bindings: Bindings): number =>
    pipe(
      bindings,
      RR.lookup(name),
      O.getOrElse(() => 0)
    )

const sampleBindings: Bindings = { count: 3, a: 1, b: 2 }

assert.deepStrictEqual(isCountCorrect(sampleBindings), true)

Added in v2.0.0

---

Table of contents

• combinators
  • tap
• constructors
  • ask
  • asks
  • asksReader
  • asksReaderW
  • id
  • of
• do notation
  • Do
  • apS
  • apSW
  • bind
  • bindTo
  • bindW
  • let
• instances
  • Applicative
  • Apply
  • Category
  • Chain
  • Choice
  • Functor
  • Monad
  • Pointed
  • Profunctor
  • Strong
• legacy
  • chain
  • chainFirst
  • chainFirstW
  • chainW
• mapping
  • flap
  • map
• model
  • Reader (interface)
• sequencing
  • flatMap
  • flatten
  • flattenW
• traversing
  • sequenceArray
  • traverseArray
  • traverseArrayWithIndex
  • traverseReadonlyArrayWithIndex
  • traverseReadonlyNonEmptyArrayWithIndex
• type lambdas
  • URI
  • URI (type alias)
• utils
  • ApT
  • ap
  • apFirst
  • apFirstW
  • apSecond
  • apSecondW
  • apW
  • compose
  • first
  • left
  • local
  • promap
  • right
  • second
• zone of death
  • getMonoid
  • getSemigroup
  • reader

---

combinators

tap

Composes computations in sequence, using the return value of one computation to determine the next computation and keeping only the result of the first.

Signature

export declare const tap: {
  <R1, A, R2, _>(self: Reader<R1, A>, f: (a: A) => Reader<R2, _>): Reader<R1 & R2, A>
  <A, R2, _>(f: (a: A) => Reader<R2, _>): <R1>(self: Reader<R1, A>) => Reader<R2 & R1, A>
}

Added in v2.15.0

constructors

ask

Reads the current context

Signature

export declare const ask: <R>() => Reader<R, R>

Added in v2.0.0

asks

Projects a value from the global context in a Reader

Signature

export declare const asks: <R, A>(f: (r: R) => A) => Reader<R, A>

Added in v2.0.0

asksReader

Effectfully accesses the environment.

Signature

export declare const asksReader: <R, A>(f: (r: R) => Reader<R, A>) => Reader<R, A>

Added in v2.11.0

asksReaderW

Less strict version of asksReader.

The W suffix (short for Widening) means that the environment types will be merged.

Signature

export declare const asksReaderW: <R1, R2, A>(f: (r1: R1) => Reader<R2, A>) => Reader<R1 & R2, A>

Added in v2.11.0

id

Signature

export declare const id: <A>() => Reader<A, A>

Added in v2.0.0

of

Signature

export declare const of: <R = unknown, A = never>(a: A) => Reader<R, A>

Added in v2.0.0

do notation

Do

Signature

export declare const Do: Reader<unknown, {}>

Added in v2.9.0

apS

Signature

export declare const apS: <N, A, E, B>(
  name: Exclude<N, keyof A>,
  fb: Reader<E, B>
) => (fa: Reader<E, A>) => Reader<E, { readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }>

Added in v2.8.0

apSW

Less strict version of apS.

The W suffix (short for Widening) means that the environment types will be merged.

Signature

export declare const apSW: <A, N extends string, R2, B>(
  name: Exclude<N, keyof A>,
  fb: Reader<R2, B>
) => <R1>(fa: Reader<R1, A>) => Reader<R1 & R2, { readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }>

Added in v2.8.0

bind

Signature

export declare const bind: <N, A, E, B>(
  name: Exclude<N, keyof A>,
  f: (a: A) => Reader<E, B>
) => (ma: Reader<E, A>) => Reader<E, { readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }>

Added in v2.8.0

bindTo

Signature

export declare const bindTo: <N>(name: N) => <E, A>(fa: Reader<E, A>) => Reader<E, { readonly [K in N]: A }>

Added in v2.8.0

bindW

The W suffix (short for Widening) means that the environment types will be merged.

Signature

export declare const bindW: <N extends string, A, R2, B>(
  name: Exclude<N, keyof A>,
  f: (a: A) => Reader<R2, B>
) => <R1>(fa: Reader<R1, A>) => Reader<R1 & R2, { readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }>

Added in v2.8.0

let

Signature

export declare const let: <N, A, B>(
  name: Exclude<N, keyof A>,
  f: (a: A) => B
) => <E>(fa: Reader<E, A>) => Reader<E, { readonly [K in N | keyof A]: K extends keyof A ? A[K] : B }>

Added in v2.13.0

instances

Applicative

Signature

export declare const Applicative: Applicative2<'Reader'>

Added in v2.7.0

Apply

Signature

export declare const Apply: Apply2<'Reader'>

Added in v2.10.0

Category

Signature

export declare const Category: Category2<'Reader'>

Added in v2.7.0

Chain

Signature

export declare const Chain: chainable.Chain2<'Reader'>

Added in v2.10.0

Choice

Signature

export declare const Choice: Choice2<'Reader'>

Added in v2.8.3

Functor

Signature

export declare const Functor: Functor2<'Reader'>

Added in v2.7.0

Monad

Signature

export declare const Monad: Monad2<'Reader'>

Added in v2.7.0

Pointed

Signature

export declare const Pointed: Pointed2<'Reader'>

Added in v2.10.0

Profunctor

Signature

export declare const Profunctor: Profunctor2<'Reader'>

Added in v2.7.0

Strong

Signature

export declare const Strong: Strong2<'Reader'>

Added in v2.8.3

legacy

chain

Alias of flatMap.

Signature

export declare const chain: <A, R, B>(f: (a: A) => Reader<R, B>) => (ma: Reader<R, A>) => Reader<R, B>

Added in v2.0.0

chainFirst

Alias of tap.

Signature

export declare const chainFirst: <A, R, B>(f: (a: A) => Reader<R, B>) => (first: Reader<R, A>) => Reader<R, A>

Added in v2.0.0

chainFirstW

Alias of tap.

Signature

export declare const chainFirstW: <R2, A, B>(
  f: (a: A) => Reader<R2, B>
) => <R1>(ma: Reader<R1, A>) => Reader<R1 & R2, A>

Added in v2.11.0

chainW

Alias of flatMap.

Signature

export declare const chainW: <R2, A, B>(f: (a: A) => Reader<R2, B>) => <R1>(ma: Reader<R1, A>) => Reader<R1 & R2, B>

Added in v2.6.0

mapping

flap

Signature

export declare const flap: <A>(a: A) => <E, B>(fab: Reader<E, (a: A) => B>) => Reader<E, B>

Added in v2.10.0

map

map can be used to turn functions (a: A) => B into functions (fa: F<A>) => F<B> whose argument and return types use the type constructor F to represent some computational context.

Signature

export declare const map: <A, B>(f: (a: A) => B) => <R>(fa: Reader<R, A>) => Reader<R, B>

Added in v2.0.0

model

Reader (interface)

Signature

export interface Reader<R, A> {
  (r: R): A
}

Added in v2.0.0

sequencing

flatMap

Signature

export declare const flatMap: {
  <A, R2, B>(f: (a: A) => Reader<R2, B>): <R1>(ma: Reader<R1, A>) => Reader<R1 & R2, B>
  <R1, A, R2, B>(ma: Reader<R1, A>, f: (a: A) => Reader<R2, B>): Reader<R1 & R2, B>
}

Added in v2.14.0

flatten

Signature

export declare const flatten: <R, A>(mma: Reader<R, Reader<R, A>>) => Reader<R, A>

Added in v2.0.0

flattenW

Less strict version of flatten.

The W suffix (short for Widening) means that the environment types will be merged.

Signature

export declare const flattenW: <R1, R2, A>(mma: Reader<R1, Reader<R2, A>>) => Reader<R1 & R2, A>

Added in v2.11.0

traversing

sequenceArray

Equivalent to ReadonlyArray#sequence(Applicative).

Signature

export declare const sequenceArray: <R, A>(arr: readonly Reader<R, A>[]) => Reader<R, readonly A[]>

Added in v2.9.0

traverseArray

Equivalent to ReadonlyArray#traverse(Applicative).

Signature

export declare const traverseArray: <R, A, B>(
  f: (a: A) => Reader<R, B>
) => (as: readonly A[]) => Reader<R, readonly B[]>

Added in v2.9.0

traverseArrayWithIndex

Equivalent to ReadonlyArray#traverseWithIndex(Applicative).

Signature

export declare const traverseArrayWithIndex: <R, A, B>(
  f: (index: number, a: A) => Reader<R, B>
) => (as: readonly A[]) => Reader<R, readonly B[]>

Added in v2.9.0

traverseReadonlyArrayWithIndex

Equivalent to ReadonlyArray#traverseWithIndex(Applicative).

Signature

export declare const traverseReadonlyArrayWithIndex: <A, R, B>(
  f: (index: number, a: A) => Reader<R, B>
) => (as: readonly A[]) => Reader<R, readonly B[]>

Added in v2.11.0

traverseReadonlyNonEmptyArrayWithIndex

Equivalent to ReadonlyNonEmptyArray#traverseWithIndex(Applicative).

Signature

export declare const traverseReadonlyNonEmptyArrayWithIndex: <A, R, B>(
  f: (index: number, a: A) => Reader<R, B>
) => (as: ReadonlyNonEmptyArray<A>) => Reader<R, ReadonlyNonEmptyArray<B>>

Added in v2.11.0

type lambdas

URI

Signature

export declare const URI: 'Reader'

Added in v2.0.0

URI (type alias)

Signature

export type URI = typeof URI

Added in v2.0.0

utils

ApT

Signature

export declare const ApT: Reader<unknown, readonly []>

Added in v2.11.0

ap

Signature

export declare const ap: <R, A>(fa: Reader<R, A>) => <B>(fab: Reader<R, (a: A) => B>) => Reader<R, B>

Added in v2.0.0

apFirst

Combine two effectful actions, keeping only the result of the first.

Signature

export declare const apFirst: <E, B>(second: Reader<E, B>) => <A>(first: Reader<E, A>) => Reader<E, A>

Added in v2.0.0

apFirstW

Less strict version of apFirst.

The W suffix (short for Widening) means that the environment types will be merged.

Signature

export declare const apFirstW: <R2, B>(second: Reader<R2, B>) => <R1, A>(first: Reader<R1, A>) => Reader<R1 & R2, A>

Added in v2.12.0

apSecond

Combine two effectful actions, keeping only the result of the second.

Signature

export declare const apSecond: <E, B>(second: Reader<E, B>) => <A>(first: Reader<E, A>) => Reader<E, B>

Added in v2.0.0

apSecondW

Less strict version of apSecond.

The W suffix (short for Widening) means that the environment types will be merged.

Signature

export declare const apSecondW: <R2, B>(second: Reader<R2, B>) => <R1, A>(first: Reader<R1, A>) => Reader<R1 & R2, B>

Added in v2.12.0

apW

Less strict version of ap.

The W suffix (short for Widening) means that the environment types will be merged.

Signature

export declare const apW: <R2, A>(fa: Reader<R2, A>) => <R1, B>(fab: Reader<R1, (a: A) => B>) => Reader<R1 & R2, B>

Added in v2.8.0

compose

Signature

export declare const compose: <A, B>(ab: Reader<A, B>) => <C>(bc: Reader<B, C>) => Reader<A, C>

Added in v2.0.0

first

Signature

export declare const first: <A, B, C>(pab: Reader<A, B>) => Reader<[A, C], [B, C]>

Added in v2.10.0

left

Signature

export declare const left: <A, B, C>(pab: Reader<A, B>) => Reader<E.Either<A, C>, E.Either<B, C>>

Added in v2.10.0

local

Changes the value of the local context during the execution of the action ma (similar to Contravariant’s contramap).

Signature

export declare const local: <R2, R1>(f: (r2: R2) => R1) => <A>(ma: Reader<R1, A>) => Reader<R2, A>

Example

import { pipe } from 'fp-ts/function'
import * as R from 'fp-ts/Reader'
import * as string from 'fp-ts/string'

const calculateContentLen: R.Reader<string, number> = pipe(
  R.Do,
  R.bind('content', () => R.ask<string>()),
  R.map(({ content }) => string.size(content))
)

// Calls calculateContentLen after adding a prefix to the Reader content.
const calculateModifiedContentLen: R.Reader<string, number> = pipe(
  calculateContentLen,
  R.local((s) => 'Prefix ' + s)
)

const s = '12345'

assert.deepStrictEqual(
  "Modified 's' length: " + calculateModifiedContentLen(s) + '\n' + "Original 's' length: " + calculateContentLen(s),
  "Modified 's' length: 12\nOriginal 's' length: 5"
)

Added in v2.0.0

promap

Signature

export declare const promap: <E, A, D, B>(f: (d: D) => E, g: (a: A) => B) => (fea: Reader<E, A>) => Reader<D, B>

Added in v2.0.0

right

Signature

export declare const right: <A, B, C>(pbc: Reader<B, C>) => Reader<E.Either<A, B>, E.Either<A, C>>

Added in v2.10.0

second

Signature

export declare const second: <A, B, C>(pab: Reader<B, C>) => Reader<[A, B], [A, C]>

Added in v2.10.0

zone of death

getMonoid

Use getApplicativeMonoid instead.

Signature

export declare const getMonoid: <R, A>(M: Monoid<A>) => Monoid<Reader<R, A>>

Added in v2.0.0

getSemigroup

Use getApplySemigroup instead.

Signature

export declare const getSemigroup: <R, A>(S: Semigroup<A>) => Semigroup<Reader<R, A>>

Added in v2.0.0

reader

This instance is deprecated, use small, specific instances instead. For example if a function needs a Functor instance, pass R.Functor instead of R.reader (where R is from import R from 'fp-ts/Reader')

Signature

export declare const reader: Monad2<'Reader'> &
  Profunctor2<'Reader'> &
  Category2<'Reader'> &
  Strong2<'Reader'> &
  Choice2<'Reader'>

Added in v2.0.0