fx-ts

Capabilities & Effects for TypeScript

Features • Install • Examples • Documentation

Features

• Do-notation for effects: Write imperative-looking code that's fully referentially transparent
• Asychronous effects with cancelation: Seamlessly mix synchronous and asynchronous effects without worry
• Effect inference: Effects can be inferred without explicit type annotations
• Extensible: Implement new effects in user land
• Testable: Code to interfaces, and easily use different implementations for development, production, and testing
• Efficient: Synchronous and Asynchronous effects run in constant stack

Install

npm install --save fx-ts

Examples

These examples are intended to be run against master using ts-node. For example:

$ ./node_modules/.bin/ts-node -O '{ "module": "commonjs" }' ./examples/echo-console.ts

• echo-console: A simple read-print loop. A good introduction to the basics of capabilities and effects.
• fp-to-the-max: A more involved example number guessing game example from https://www.youtube.com/watch?v=sxudIMiOo68

This example runs on AWS Lambda. If you have a serverless account and have setup your AWS credentials, you can deploy it using serverless:

$ cd examples/lambda-pets
$ ./node_modules/.bin/serverless deploy

• lambda-pets: A realistic AWS Lambda application that shows adoptable pets near the user's IP Address using https://ipstack.com and https://petfinder.com

Running the examples

The

Documentation

Pure functions are easy to reason about and test because they aren't entangled with the environment in which they're called. They always give the same answer for the same inputs. Nevertheless, useful programs need to interact with their environment. They need access to databases, external services, or configuration, and need to perform effects like reading and writing files, updating databases, etc.

The goal of fx-ts is to help in writing programs that interact with their environment and are easy to reason about and test.

// Abstract Print & Read capabilities

type Print = { print(s: string): Fx<unknown, void> }

type Read = { read: Fx<Async, string> }

const main = doFx(function* () {
  const { print, read } = yield* get<Print & Read>()
  while (true) {
    yield* print('> ')
    const s = yield* read
    yield* print(`${s}${EOL}`)
  }
})

const capabilities = {
  // ...Concrete implementation of Print and Read...
}

runFx(main(), capabilities)

API

Coming soon

Inspiration

• koka
• ZIO
• forgefx
• ambient