State

State: object

Type Declaration

apply

apply: <S, A>(arg) => <B>(state) => State<S, B>

Applies a function wrapped in a State to a value wrapped in a State. The function computation runs first; its output state is the input to the argument computation.

Type Parameters

S

S

A

A

Parameters

arg

State<S, A>

Returns

<B>(state) => State<S, B>

See

chain to sequence dependent State transitions.

Example

const addCounted = (n: number) => (m: number) => n + m;
const program = pipe(
  State.make<number, typeof addCounted>(addCounted),
  State.apply(pipe(State.get<number>(), State.map((s) => s * 2))),
  State.apply(State.get<number>()),
);

State.evaluate(3)(program); // 6 + 3 = 9

assign

assign: <K, S, A, B>(key, transform) => (state) => State<S, A & { [P in string]: B }>

Evaluates a new State using the current accumulator and attaches the output to a new key.

Type Parameters

K

K extends string

S

S

A

A

B

B

Parameters

key

K

transform

(value) => State<S, B>

Returns

(state) => State<S, A & { [P in string]: B }>

See

assignTo to initialize the accumulator record.

Example

pipe(
  State.make({ a: 1 }),
  State.assign("b", ({ a }) => State.make(a + 1))
); // State({ a: 1, b: 2 })

assignTo

assignTo: <K>(key) => <S, A>(state) => State<S, { [P in string]: A }>

Lifts a State value into an accumulator object.

Type Parameters

K

K extends string

Parameters

key

K

Returns

<S, A>(state) => State<S, { [P in string]: A }>

See

assign to accumulate subsequent State values into the object.

Example

pipe(State.make(42), State.assignTo("value")); // State({ value: 42 })

chain

chain: <A, S, B>(transform) => (state) => State<S, B> = chainState

Sequences two State computations. The state output of the first is passed as the state input to the second.

Data-last — the first computation is the data being piped.

Type Parameters

A

A

S

S

B

B

Parameters

transform

(value) => State<S, B>

Returns

(state) => State<S, B>

See

map to transform the produced value without changing the state transition.

Example

const push = (item: string): State<string[], undefined> =>
  State.modify(stack => [...stack, item]);

const program = pipe(
  push("a"),
  State.chain(() => push("b")),
  State.chain(() => State.get<string[]>()),
);

State.evaluate([])(program); // ["a", "b"]

evaluate

evaluate: <S>(initialState) => <A>(state) => A

Runs a State computation with an initial state, returning only the produced value (discarding the final state).

Type Parameters

S

S

Parameters

initialState

S

Returns

<A>(state) => A

See

run to obtain both the value and final state, or execute for only the state.

Example

State.evaluate([])(pipe(
  State.modify<string[]>(s => [...s, "x"]),
  State.chain(() => State.get<string[]>()),
)); // ["x"]

execute

execute: <S>(initialState) => <A>(state) => S

Runs a State computation with an initial state, returning only the final state (discarding the produced value).

Type Parameters

S

S

Parameters

initialState

S

Returns

<A>(state) => S

See

run to obtain both the value and final state, or evaluate for only the value.

Example

State.execute(0)(pipe(
  State.modify<number>(n => n + 10),
  State.chain(() => State.modify<number>(n => n * 2)),
)); // 20

focus

focus: <S, SubState>(lens) => <A>(state) => State<S, A>

Focuses a State computation on a sub-state using a Lens.

Type Parameters

S

S

SubState

SubState

Parameters

lens

Lens<S, SubState>

Returns

<A>(state) => State<S, A>

See

modify to update state directly without a Lens.

Example

type AppState = { count: number; name: string };
const countLens = Lens.from.property<AppState>()("count");
const increment = State.modify((c: number) => c + 1);
const focusedProgram = pipe(increment, State.focus(countLens));

get

get: <S>() => State<S, S>

Produces the current state as the value, without modifying it.

Type Parameters

S

S

Returns

State<S, S>

See

put to replace the state, or modify to transform it with a function.

Example

const readStack: State<string[], string[]> = State.get();
State.run(["a", "b"])(readStack); // [["a", "b"], ["a", "b"]]

make

make: <S, A>(value) => State<S, A>

Lifts a pure value into a State computation. The state passes through unchanged.

Type Parameters

S

S

A

A

Parameters

value

A

Returns

State<S, A>

See

get to produce the current state instead of a static value.

Example

State.run(10)(State.make(42)); // [42, 10] — value 42, state unchanged

map

map: <A, B>(transform) => <S>(state) => State<S, B> = mapState

Transforms the value produced by a State computation. The state transformation is unchanged.

Type Parameters

A

A

B

B

Parameters

transform

(value) => B

Returns

<S>(state) => State<S, B>

See

chain to sequence a computation that produces a new State.

Example

const readLength: State<string[], number> = pipe(
  State.get<string[]>(),
  State.map(stack => stack.length),
);

State.run(["a", "b", "c"])(readLength); // [3, ["a", "b", "c"]]

modify

modify: <S>(transform) => State<S, undefined>

Applies a function to the current state to produce the next state. Produces no meaningful value.

Type Parameters

S

S

Parameters

transform

(state) => S

Returns

State<S, undefined>

See

put to replace the state with a constant value, or get to read it.

Example

const push = (item: string): State<string[], undefined> =>
  State.modify(stack => [...stack, item]);

State.run(["a"])(push("b")); // [undefined, ["a", "b"]]

put

put: <S>(newState) => State<S, undefined>

Replaces the current state with a new value. Produces no meaningful value.

Type Parameters

S

S

Parameters

newState

S

Returns

State<S, undefined>

See

get to read the current state, or modify to transform it.

Example

const reset: State<number, undefined> = State.put(0);
State.run(99)(reset); // [undefined, 0]

run

run: <S>(initialState) => <A>(state) => readonly [A, S]

Runs a State computation with an initial state, returning both the produced value and the final state as a pair.

Data-last — the computation is the data being piped.

Type Parameters

S

S

Parameters

initialState

S

Returns

<A>(state) => readonly [A, S]

See

evaluate to discard the final state, or execute to discard the produced value.

Example

const program = pipe(
  State.modify<number>(n => n + 1),
  State.chain(() => State.get<number>()),
);

State.run(0)(program); // [1, 1]

tap

tap: <A>(sideEffect) => <S>(state) => State<S, A>

Runs a side effect on the produced value without changing the State computation.

Type Parameters

A

A

Parameters

sideEffect

(value) => void

Returns

<S>(state) => State<S, A>

See

map to transform the value instead of executing a side effect.

Example

pipe(
  State.get<number>(),
  State.tap(n => console.log("current:", n)),
  State.chain(() => State.modify(n => n + 1)),
);