pio.ts

A monadic library for I/O actions in TypeScript

pio.ts allows you to handle all impure actions of your program, such as reading from standard input or writing to files, as a sequence of (pure) composable actions in a functional way.

import { forever, getLine, putStrLn } from "https://deno.land/x/pio/pio.ts";

// echo = forever (getLine >>= putStrLn)
const echo = forever(getLine.bind(putStrLn));

// Run IO action
echo.runIO();

Note: Some IO actions defined by pio.ts (like getChar) make use of Deno.setRaw which is still unstable, so the library requires the --unstable flag to run.

Downloads

Source code of pio.ts is available on GitHub. You can import the most recent version released from:

https://deno.land/x/pio@v1.0.0/pio.ts

License

pio.ts source code is released under the terms of the BSD 3-Clause License.

Documentation

• IO prototype
• Combinators
• Lifting operators
• Conditional execution
• Effects
• Standard input/output
• Files

---

IO prototype

IO.prototype.map

Map the result of an IO action.

function<A, B>(this: IO<A>, f: (x: A) => B): IO<B>

IO.prototype.ap

Sequential application.

function<A, B>(this: IO<(x: A) => B>, action: IO<A>): IO<B>

IO.prototype.bind

Sequentially compose two IO actions, passing any value produced by the first as an argument to the second.

function<A, B>(this: IO<A>, f: (x: A) => IO<B>): IO<B>

IO.prototype.then

Sequentially compose two IO actions, discarding any value produced by the first.

function<A, B>(this: IO<A>, action: IO<B>): IO<B>

IO.prototype.left

Sequentially compose two IO actions, discarding any value produced by the second.

function<A, B>(this: IO<A>, action: IO<B>): IO<A>

IO.prototype.catch

Execute another IO action when the main action fails. IO internally uses promises to cope with asynchronous tasks, so the handler of the catch method is called when: i) an exception is raised, or ii) a promise is rejected.

Example: file.ts

function<A>(this: IO<A>, handler: (ex: any) => IO<A>): IO<A>

IO.prototype.void

Ignore the result of evaluation.

function<A>(this: IO<A>): IO<void>

---

Combinators

pure

Inject a value into an IO action.

function<A>(x: A): IO<A>

all

Evaluate each IO action in the array in a non-blocking way, and collect the results.

Example: all-sequence.ts

function<A>(xs: Array<IO<A>>): IO<Array<A>>

sequence

Evaluate each IO action in the array from left to right, and collect the results.

Example: all-sequence.ts

function<A>(xs: Array<IO<A>>): IO<Array<A>>

replicate

Perform the action n times, gathering the results.

Example: replicate.ts

function<A>(action: IO<A>): (n: number) => IO<Array<A>>

forever

Repeat an action indefinitely.

Example: echo.ts

function<A>(action: IO<A>): IO<A>

filter

Array-based filter function for IO actions.

Example: filter.ts

function<A>(predicate: (x: A) => IO<boolean>): (xs: Array<A>) => IO<Array<A>>

---

Lifting operators

lift2

Lift a binary function to IO actions.

Example: add.ts

function<A, B, C>(fn: (x: A) => (y: B) => C, a: IO<A>, b: IO<B>): IO<C>

lift3

Lift a ternary function to IO actions.

function<A, B, C, D>(fn: (x: A) => (y: B) => (z: C) => D, a: IO<A>, b: IO<B>, c: IO<C>): IO<D>

---

Conditional execution

guard

Conditional failure of an IO action.

function(cond: boolean): IO<void>

when

Conditional execution of an IO action.

Example: conditional.ts

function(action: IO<void>): (cond: boolean) => IO<void>

unless

The reverse of when.

function(action: IO<void>): (cond: boolean) => IO<void>

---

Effects

delay

Delay the given milliseconds.

Example: all-sequence.ts

function(ms: number): IO<void>

---

Standard input/output

putStr

Write a string to the standard output device.

function(text: string): IO<void>

putStrLn

The same as putStr, but adds a newline character.

function(text: string): IO<void>

print

Output a value of any printable type to the standard output device. Printable types are those that implement a toString method. The print function converts values to strings for output and adds a newline.

function(value: Show): IO<void>

getChar

Read a character from the standard input device. This makes use of Deno.setRaw which is still unstable so the library requires the --unstable flag to run.

Example: password.ts

IO<string>

getLine

Read a line from the standard input device.

IO<string>

---

Files

readFile

Read a file and return the contents of the file as a string.

Example: file.ts

function(path: string): IO<string>

writeFile

Write the string to the file.

Example: file.ts

function(path: string): (content: string) => IO<void>

appendFile

Append the string to the file.

Example: file.ts

function(path: string): (content: string) => IO<void>