rw

Source: /nix/store/mls72plk3raskl1r5afh3cl9ik3rn969-source/nix/rw.nix

Module Description

Reader and Writer effects built on existing primitives.

This module provides clean APIs for two common effect patterns:

Reader: Read-only environment access (built on state.get + provide)
Writer: Append-only output accumulation (built on acc)

Reader Pattern

Reader provides access to immutable environment/configuration without explicit parameter threading. It’s just state.get with nicer names.

Writer Pattern

Writer accumulates output (logs, events, metadata) alongside computation. It’s just acc with monoid semantics and cleaner API.

Example

# Reader: configuration access
runFx (runReader { debug = true; timeout = 30; } (
  asks (cfg: cfg.debug)
))  # => true

# Writer: logging
runFx (runWriter (
  then' (pure 42) (
    then' (tell "Done") (tell "Starting")
  )
))  # => { value = 42; output = ["Starting" "Done"]; }

Combinators

`ask`

Reads the entire Reader environment.

Retrieves the complete environment value that was provided via runReader. This is just state.get with a more semantic name for read-only environment access.

Type Signature

Fx<Env, Env>

Example

runFx (runReader { x = 1; y = 2; } (
  map (env: env.x + env.y) ask
))  # => 3

`asks`

Reads environment with a projection function.

Retrieves a computed value from the environment by applying a function. Useful for extracting specific fields or deriving values from the environment.

Type Signature

(Env -> A) -> Fx<Env, A>

Parameters

f: Projection function from environment to desired value

Example

runFx (runReader { port = 8080; host = "localhost"; } (
  asks (env: env.host + ":" + toString env.port)
))  # => "localhost:8080"

`censor`

Transforms the accumulated output of an effect.

Runs an effect with output accumulation, then applies a transformation to the collected output before returning. The effect’s value is unchanged.

Type Signature

([A] -> [B]) -> Fx<{acc: [A]}, V> -> Fx<{}, {value: V, output: [B]}>

Parameters

f: Function to transform the accumulated output
e: Effect to execute

Example

runFx (censor (output: map toUpper output) (
  then' (pure 42) (
    then' (tell "world") (tell "hello")
  )
))  # => { value = 42; output = ["HELLO" "WORLD"]; }

`execWriter`

Executes a Writer effect and extracts only the accumulated output.

Like runWriter but discards the computed value, returning only the accumulated output. Useful when the accumulation is the goal.

Type Signature

Fx<{acc: [A], state: S}, V> -> Fx<S, [A]>

Parameters

e: Writer effect to execute

Returns

List of all accumulated values from tell calls

Example

runFx (execWriter (
  then' (pure "ignored") (
    then' (tell "event3") (
      then' (tell "event2") (tell "event1")
    )
  )
))  # => ["event1" "event2" "event3"]

`listen`

Runs an effect and captures its accumulated output.

Executes an effect while collecting all tell calls into an output list. Returns both the effect’s value and the accumulated output.

Type Signature

Fx<{acc: [A], state: S}, V> -> Fx<S, {value: V, output: [A]}>

Parameters

e: Effect to execute with output capturing

Returns

{value: V, output: [A]} where output contains all tell values

Example

runFx (listen (
  then' (pure 42) (
    then' (tell "log2") (tell "log1")
  )
))  # => { value = 42; output = ["log1" "log2"]; }

`listens`

Like listen but applies a projection to the captured output.

Executes an effect with output capturing, applies a function to transform the output, and returns both the value and transformed output.

Type Signature

([A] -> B) -> Fx<{acc: [A]}, V> -> Fx<{}, {value: V, output: B}>

Parameters

f: Function to transform captured output
e: Effect to execute

Example

runFx (listens (output: length output) (
  then' (pure 42) (
    then' (tell "b") (tell "a")
  )
))  # => { value = 42; output = 2; }

`local`

Runs an effect with a modified environment.

Executes an effect with a locally transformed environment, without affecting the outer environment. The transformation only applies to the inner effect.

Type Signature

(Env -> Env) -> Fx<Env, V> -> Fx<Env, V>

Parameters

f: Function to transform the environment
e: Effect to run with modified environment

Example

runFx (runReader { debug = false; } (
  local (env: env // { debug = true; }) (
    asks (env: env.debug)
  )
))  # => true (outer remains false)

`pass`

Runs an effect that returns both a value and an output transformer.

Advanced Writer combinator that allows the effect to specify how its own output should be transformed. The effect returns a pair of (value, output-transformer-function).

Type Signature

Fx<{acc: [A]}, (V, [A] -> [B])> -> Fx<{}, {value: V, output: [B]}>

Parameters

e: Effect returning (value, transformation-function)

Example

runFx (pass (
  then' (pure {
    value = 42;
    transform = output: map toUpper output;
  }) (tell "raw")
))  # => { value = 42; output = ["RAW"]; }

`runReader`

Provides an environment for Reader effects.

Supplies the environment that ask and asks will read. This is just provide with a semantic name for Reader pattern.

Type Signature

Env -> Fx<Env, V> -> Fx<{}, V>

Parameters

env: Environment value to provide
e: Effect requiring environment

Example

runFx (runReader { apiKey = "secret"; baseUrl = "api.example.com"; } (
  asks (env: fetchUrl env.baseUrl env.apiKey)
))

e: Writer effect to execute

Returns

{value: V, output: [A]} containing result and accumulated output

Example

runFx (runWriter (
  mapM (verbose:
    if verbose 
    then then' (pure "OK") (tell "Verbose mode")
    else pure "OK"
  ) (asks (cfg: cfg.verbose))
))

value: Value to append to output

Example

runFx (runWriter (
  then' (pure 42) (
    then' (tell "step2") (tell "step1")
  )
))  # => { value = 42; output = ["step1" "step2"]; }

Keyboard shortcuts

nfx