DEV Community: Aldwin Vlasblom

JavaScript's Missed Opportunity: Async/Await, Optional Chaining, and flatMap are the same thing

Aldwin Vlasblom — Wed, 19 Feb 2025 12:12:03 +0000

Someone asked me some time ago to share my thoughts on Async/Await in JavaScript. It is my belief that Async/Await (and to some extent*, Optional Chaining Syntax) is a missed opportunity in the evolution of the language.

Consider the following three programs:

const f = () => foo ?. bar ?. baz;
const nullableResult = f();

const f = async () => { return await (await (await foo).bar).baz }
const thennableResult = f();

const f = () => foo.flatMap(x => x.bar).flatMap(x => x.baz);
const manyResults = f();

In the first program, we assume that foo is a Nullable object with a bar property, that's a Nullable object with a baz property, that's a Nullable value.
In the second, we assume that foo is a Thenable (also known as Promise) of an object with a bar property, that's a Thenable of an object with a baz property, that's a Thenable of a value.
In the third, we assume that foo is a "Manyable" (also known as Array) of objects with bar properties, that are Manyables of objects with baz properties, that are Manyables of values.

I'm sure you can already see the pattern here. But what if I told you that JavaScript could have evolved so that these three programs would be exactly the same, and work polymorphically on inputs of type Nullable<T>*, Thenable<T>, and Manyable<T>?

type Nullable<T> = T | null;
type Thenable<T> = Promise<T>;
type Manyable<T> = T[];

All that would be needed for that, is a common interface (like the Promise .then function) that the language syntax could build on (like they did with Async/Await).

In fact, valid implementations of that potential interface already exist. It's just flatMap. We can also implement flatMap for Thenable and for Nullable:

const Nullable = {
  flatMap(nullable, next){
    return nullable === null ? null : next(nullable);
  }
}

const Thenable = {
  flatMap(thenable, next){
    return thenable.then(value => next(value));
  }
}

const Manyable = {
  flatMap(manyable, next){
    return manyable.flatMap(value => next(value));
  }
}

So we have our three flatMaps that have exactly the same interface.

At this point, we're already able to create a function like the f we started with, but polymorphic (working on "anythingable" with a flatMap):

const f = (Somethingable) => (
  Somethingable.flatMap(foo, ({bar}) => (
    Somethingable.flatMap(bar, ({baz}) => baz)
  ))
);

ℹ️ Try it out with nullableResult = f(Nullable)

If we'd associate these functions with the right prototypes, then we wouldn't even need to pass the correct interface implementation:

Promise.prototype.flatMap = function(next){
  return Thenable.flatMap(this, next);
}

// f now works on Arrays, and on Promises:
const f = () => foo.flatMap(x => x.bar).flatMap(x => x.baz);

To some extent*, JavaScript could have adopted this approach, and given us a single syntax for flatMap that would be able to work with anything that's flat-mappable:

const foo = Promise.resolve({
  bar: Promise.resolve({ baz: Promise.resolve("hello") })
});

foo ?. bar ?. baz
//=> Promise<"hello">

const foo = [{ bar: [{ baz: ["hello"] }] }];

foo ?. bar ?. baz
//=> [ "hello" ]

Or, like a more async-awaitey one:

const f = flattening () => {
  const a = flatten foo;
  const b = flatten a.bar;
  return flatten b.baz;
}

Take a moment to let that sink in. This version of Async/Await looks exactly the same, but works on anything that's flattenable, not just Promises. It could have even integrated with custom types that have flatMap functions, like Observables, Iterables, Tasks, and whatnot.

Instead, we're slowly getting a new special syntax for every new flatmappable type that's introduced to the language, in a process that's unfolding over the course of years, if not decades 😞

(This was one of the purposes of the Fantasy Land specification, to define common interfaces for generalized operations that could benefit from language-syntax-support.)

* The extent to which this is possible with Nullable is very limited, due to the nature of Nullable values.

While Arrays and Promises are explicit wrappers around a value, any value can potentially be null implicitly, so you wouldn't know what to do when flat-mapping over a Nullable Promise, for example.

To get around this, modern languages have a Nullable type (typically called Option) that wraps a value, as opposed to living alongside it.

This somewhat validates the existence of Optional Chaining syntax, although I would've preferred seeing a flatMap syntax (and an Option type), over a commitment to the problematic Nullable type through the succinct Optional Chaining syntax.

Nixpkgs: A community-maintained package lock file for all of Unix

Aldwin Vlasblom — Wed, 16 Aug 2023 10:20:15 +0000

Disclaimer
I wrote this article a few years ago but never published it. A few things may be a little outdated (especially the lack of info on Nix Flakes), but it's still a nice little intro to Nixpkgs.

Meet Nix

Nix is the name of the programming language that the NixPkgs project is written in. NixPkgs can be thought of in a lot of ways; One of those ways is as a lazily evaluated, community-maintained, programmable package lock file for all of Unix. Let me explain:

A package lock file for all of Unix

Many programming languages come with their own package managers. For example, Node has npm, Python has pip, etc. When you write code that depends on some packages, you want to make sure that if someone else runs that code, they have the same packages at the same versions. This is where package lock files come in. They specify exactly which versions of which packages are needed to run some piece of code. For Node, that takes the form of package-lock.json, and for Python it's requirements.txt.

The NixPkgs repository is kind of like one of these package lock files, but huge: It specifies exactly which versions of which packages you need, for everything. Seriously; It's an effort to put pretty much everything in a single package lock file - kind of like the everything module for Node. But not just for Node, but for any software you'll find for any Unix system.

"But why would I ever install from this lock file?", you might ask, because you don't ever need "all the things". Well, as opposed to most lockfile formats, Nix lockfiles let you evaluate only part of it, making it so you only install one, or a few, of the packages it locks. It achieves this through lazy evaluation.

Lazily-evaluated

Some programming languages are evaluated eagerly (for example JavaScript), and some lazily (for example Haskell). Nix is of the latter sort. When I think about this difference, I usually think of it as the "order" in which the evaluator goes through the language. Take this JavaScript code, for example:

const one = 1;
const two = 2;

const added = one + two;
const multiplied = one * two;

const answer = multiplied + one;

Here, the evaluation of the statements goes from top to bottom. First, the values of one and two are evaluated, then added and multiplied, and finally answer. If I end up only using the value of answer, then added will still have been evaluated even though it was not used to compute answer*.

A lazily evaluated programming language kind of evaluates in backwards order. For example, here's some similar code in Nix:

rec {
  one = 1;
  two = 2;

  added = one + two;
  multiplied = one * two;

  answer = multiplied + one;
}

Here, if I ask for the value of answer, then the language will see that multiplied and one are needed, and when evaluating multiplied, it will see that one and two are needed, finally evaluating one and two, and completely skipping over added. The downside is that one may have been evaluated twice, because it was used in two distinct places*.

If we bring that back to our massive package lock file, we can see how this lazy evaluation strategy is helpful: Let's say we're just interested in the evaluation of a cowsay property, because we want a cow to tell us who we are:

$ cowsay $USER
 ______ 
< avaq >
 ------ 
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Because of lazy evaluation, the thousands upon thousands of other properties in the giant lockfile don't need to be evaluated. Nix will start with the cowsay property, and traverse its dependency tree as needed.

* Let's pretend that neither programming language has any kind of optimizer in place, for the sake of illustration.

Programmable

Once you start maintaining a lockfile of this magnitude it becomes a little unwieldy. Luckily, Nix is a programming language, not just a data format. So it allows us to define functions, and create abstractions. These can then be used for things like customization of the lockfile, deriving development environments, deriving new lockfiles from existing ones, deriving entire operating systems from the lockfile, and much more.

Community Maintained

Instead of letting this package lock file be the result of a process that generates it from a smaller specification, the NixPkgs "lockfile" is manually created, maintained, and peer reviewed by a community of enthusiasts who each use their own slice of this lockfile to manage their package installations. Every change to it comes in the form of a pull-request, and every pull request is reviewed and exposed to a test suite.

As a result, you have more certainty (compared to a traditional lockfile which is updated automatically) that any given version of the lockfile will result in a valid installation of the software you want.

Using Nix

The NixPkgs project already defines some 80,000 Linux packages that can be installed through it. Nix can be easily installed using the Determinate Nix Installer on Linux and Mac. To learn more about Nix, check out the Learning Resources on nixos.com.

Application Bootstrapping with fp-ts

Aldwin Vlasblom — Fri, 23 Jun 2023 16:34:12 +0000

This article assumes familiarity with fp-ts and/or functional programming with algebraic data types.

UPDATE: I've released a library that packages the approach described below, and solves the problem mentioned at the end: fp-ts-bootstrap

🛫 Application Bootstrapping 🛬

I'm using the term bootstrapping here to refer to the "start-up phase" (and "shut-down phase", as we'll get to) of a piece of software. This is any of the code that runs once, just after booting a system, to ensure that everything needed for the program to do its job is in place. 🐣

This task commonly involves setting up database connection (pools), file handlers, socket bindings, timing intervals, etc.

Managing the complexity of such a task is no easy feat, especially when you consider that:

resource acquisition could be asynchronous;
some resources may depend on others;
acquisition of a resource may fail; and
a process may eventually want to de-allocate / dispose the resources after it completed the task that needed them.

There are a lot of solutions out there to help you manage this complexity. Typically, you'll find dependency injection frameworks utilizing some form of Inversion of Control. In this space you'll find factories, singletons, decorators, middleware, and any pattern we can throw at it. That's because there are demanding requirements for these tools. Here's my wishlist for a bootstrapping solution:

🛬 Resources should be disposed gracefully, so that I don't have to kill my process to restore it to a clean state after consuming a resource.
🧑‍🤝‍🧑 My resource disposal logic should live nearby my resource acquisition logic.
🚦 It should be easy to manage asynchronous acquisition and disposal of resources.
🏗 When one resource depends on another, I want to express that dependency in a convenient way, and the system should take care of sequencing acquisition and disposal between the two resources in the correct order.
🪂 When acquisition of a resource fails, the resources it depended on should be neatly disposed.
📦 The program that consumes my resources should be defined separately from the bootstrapping logic, so that I can run the program with a custom set of resources (for example mocks).
🚚 I want to be able to use a "stack" of resources and expand upon it / use it as a resource within another stack.

🧃 Solving it with Monads 😎

fp-ts, a library that caters to functional programming in TypeScript, comes with some micro-abstractions that already solve a few of our needs.

The Task Monad can help us sequence asynchronous operations, like the "acquisition ➡ consumption ➡ disposal" of resources.
The Either Monad can model failure. Failure to acquire resources, consume resources, or dispose resources.
The combination of Task and Either give us the TaskEither Monad which we'll get back to because it comes with a very useful utility for what we're trying to do.
The Reader Monad is all about managing injected dependencies, so we can use it to model the requirement for service dependencies.
There's one more Monad we'll use to tie it all together, but I'll keep you in suspense as we build up to it! 👀

Bracket

We'll start with that useful TaskEither utility I mentioned: I was referring to TaskEither.bracket, of course!

declare const bracket: <E, A, B>(
  acquire: TaskEither<E, A>,
  use: (a: A) => TaskEither<E, B>,
  release: (a: A, e: E.Either<E, B>) => TaskEither<E, void>
) => TaskEither<E, B>

The bracket function is basically our "acquisition ➡ consumption ➡ disposal" need completely met 💪! Let's look at how we can utilize it. In the example below, I'm wrapping a Node.js HTTP server in a bracket call that handles its acquisition and disposal. The use function is where we consume the resource, and in this case we're just delaying the program for 30 seconds so that the resource is "held" for a bit before it's disposed.

import * as HTTP from 'node:http';
import * as E from 'fp-ts/lib/Either';
import * as T from 'fp-ts/lib/Task';
import * as TE from 'fp-ts/lib/TaskEither';

// These are the dependencies of our http server. Eventually,
// we'd want these to live elsewhere in our codebase, but for
// now we'll just define them here.
const port = 3000;
const app = (_: unknown, response: HTTP.ServerResponse) => {
  response.writeHead(200);
  response.end('hello world\n');
};

// We define the acquisition of our http server as a TaskEither.
// That's a lazy Promise that resolves with an Either.
const acquireServer: TE.TaskEither<Error, HTTP.Server> = () => (
  new Promise(res => {
    const server = HTTP.createServer(app);
    server.once('error', e => res(E.left(e)));
    server.listen(port, () => res(E.right(server)));
  })
);

// The consumption of our server is just a TaskEither that delays
// the program for 30 seconds. Note that we're not using the
// server here, but we could!
const consumeServer = () => T.delay(30000)(TE.of('done'));

// To dispose of our server, we unbind event listeners and close the server.
const disposeServer = (server: HTTP.Server): TE.TaskEither<Error, void> => (
  () => new Promise(res => {
    server.removeAllListeners('error');
    server.close((e: unknown) => res(
      e instanceof Error ? E.left(e) : E.right(undefined)
    ));
  })
);

// We can now use bracket to sequence the acquisition,
// consumption, and disposal of our http server. The
// result is a TaskEither that resolves with the result
// of the consumption.
const program = TE.bracket(
  acquireServer,
  consumeServer,
  disposeServer
);

// Since all of our functions are lazy, we need to run
// the program to get a Promise that resolves with the
// result of the consumption. The Promise only rejects
// in case of an unexpected runtime error. Otherwise, it
// resolves with the Either that represents the success or
// failure of the program.
program().then(E.fold(console.error, console.log), console.error);

🧑‍💻 If you want to follow along, you can run the code snippet above by saving it to example.ts, installing fp-ts with npm i fp-ts, and running it with npx ts-node example.ts

Running the code above will cause our "hello world"-app to run for 30 seconds, during which curl localhost:3000 should output hello world. After 30 seconds, the server resource consumption is done, which causes it to be disposed. We know that this cleaned everything up properly because afterwards, the process exits. When there are no remaining resources in use, Node just exits, because there's nothing left to do or to cause any events.

At the end, we see done in the terminal because that's the value returned from the consumption, and logged on the last line.

The type of our program is Task<Either<Error, string>>. We can handle asynchronous acquisition, consumption, and disposal of resources through the Task Monad, handling possible failure along the way with the Either Monad.

🌗 We're halfway to a solution, but there's a few things missing:

Injecting Dependencies

In our example above, the app and port are baked into the acquireServer function. But if they themselves were resources, we'd want to inject them into acquireServer instead. We can do that with the Reader Monad:

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

// We capture the dependencies from earlier in a type.
type Dependencies = {
  app: HTTP.RequestListener,
  port: number,
};

// And we use the Reader Monad to inject them into our
// acquireServer function. A Reader is really just a standard
// function. We use the Reader type alias to encourage users
// to use the Reader Monad's composition utilities.
const acquireServer: R.Reader<Dependencies, TE.TaskEither<Error, HTTP.Server>> = (
  deps => () => new Promise(res => {
    const server = HTTP.createServer(deps.app);
    server.once('error', e => res(E.left(e)));
    server.listen(deps.port, () => res(E.right(server)));
  })
);

// For example, here we can use Reader.map to defer the
// injection of the dependencies to the caller of the withServer
// function.
const withServer = pipe(
  acquireServer,
  R.map(acquire => TE.bracket(acquire, consumeServer, disposeServer))
);

// Now, to define our program, we first need to inject the
// dependencies, and they'll be threaded along to the
// acquireServer function.
const program = withServer({app, port});

The type of withServer has become Reader<Dependencies, Task<Either<Error, string>>>. We can now inject dependencies, and threading them along is made easy using the Reader Monad!

🌖 We're almost there, but there's one more thing missing:

De-coupling the Consumption

The bracket function takes acquire, consume, and dispose all at the same time. If we want to de-couple the consumption from the acquisition and disposal, we can create a curried a version of bracket that takes the consume function separately:

const createService = <E, Resource, Output = unknown>(
  acquire: TE.TaskEither<E, Resource>,
  dispose: (a: Resource) => TE.TaskEither<E, void>
) => (consume: (a: Resource) => TE.TaskEither<E, Output>) => (
  TE.bracket(acquire, consume, dispose)
);

We can use createService to create a withServer function that takes a consume function and returns a program function that can be run to acquire, consume, and dispose the server:

const withServer = pipe(
  acquireServer,
  R.map(acquire => createService<Error, HTTP.Server, string>(acquire, disposeServer))
);

const program = withServer({app, port})(consumeServer);

You can imagine how one module might export a withServer function, and another module might import it to create a program function that uses it.

Tying it Together with the Cont Monad

In the previous step, we curried the bracket function and created something that doesn't really look like it'll compose nicely. What if we want to use multiple resources in our program? We will find ourselves in a kind of callback hell, and our consumption function is nested inside again:

// Imagine we have these functions:
const program = withLogger({transport})(logger => (
  withDatabase({url, logger})(database => (
    withCache({database, logger})(cache => (
      withServer({app, port, logger})(server => (
        consumeServices({database, server, logger, cache})
      ))
    ))
  ))
));

But we missed an opportunity when we curried bracket! If we look closely at its type, we can see that it actually returns a Cont Monad. fp-ts doesn't have a Cont Monad built in, so we can use fp-ts-cont:

import * as C from 'fp-ts-cont/lib/Cont';

const createService = <E, Resource, Output = unknown>(
  acquire: TE.TaskEither<E, Resource>,
  dispose: (a: Resource) => TE.TaskEither<E, void>
): C.Cont<TE.TaskEither<E, Output>, Resource> => consume => (
  TE.bracket(acquire, consume, dispose)
);

This new createService definition has the same type as the old one, but it uses the Cont type alias to signal that it returns a Cont Monad which we can use to compose our programs. As with the Reader type we used earlier, it's just an alias that encourages users to use the Cont Monad's composition utilities.

One of these composition utilities is the set of functions used fo Do-notation in FP-TS. Using bindTo and bind, we can flatten our nested services, combining them into a new service that we'll call withServices:

const withServices = pipe(
  withLogger({transport}),
  C.bindTo('logger'),
  C.bind('database', ({logger}) => withDatabase({url, logger})),
  C.bind('cache', withCache),
  C.bind('server', ({logger}) => withServer({app, port, logger})),
);

const program = withServices(consumeServices);

With the new createService function, the type of our services is now:

type Service<Dependencies, Resource, Output = unknown> = (
  Reader<Dependencies, Cont<Task<Either<Error, Output>>, Resource>>
)

🌕 Despite being a pretty simple type (a function that takes dependencies and an async callback), it becomes powerful because we've identified a Monad instance for each of its components. We can use those Monad instances to compose our services together, manage their dependencies, and control their asynchronous flow, all using the same interface. Let's check our requirements:

🛬 Resources are disposed gracefully after consumption thanks to bracket.
🧑‍🤝‍🧑 Definition of a service with its acquisition and disposal lives in isolation from its consumption, thanks to createService.
🚦 Managing asynchronous resources is easy thanks to TaskEither.
🏗 Building larger services out of several smaller ones is easy thanks to Cont, and sequencing of acquisition and disposal is handled automatically.
🪂 When a service fails to acquire, the whole program fails, and the disposals of all acquired services are run, thanks to how we've built up our program by composing bracket calls using Cont.
📦 The consumption of my final service is fully decoupled, and I could easily swap consumotion functions, or swap service definitions.
🚚 The larger services built using Cont are themselves services which could be composed into even larger services, and so on.

Conclusion

I've been using this approach to application bootstrapping in my projects for some time now, and I'm very happy with it. It gives me the flexibility to split up my application into smaller services, and compose them into larger services, all while allowing each service to be used and tested in isolation.

I hope you find this approach useful, and I'd love to hear your feedback!

Here's the full, executable code after making all the changes suggested above:

import * as HTTP from 'node:http';
import * as E from 'fp-ts/lib/Either';
import * as T from 'fp-ts/lib/Task';
import * as TE from 'fp-ts/lib/TaskEither';
import * as R from 'fp-ts/lib/Reader';
import * as C from 'fp-ts-cont/lib/Cont';
import {pipe} from 'fp-ts/lib/function';

const createService = <E, Resource>(
  acquire: TE.TaskEither<E, Resource>,
  dispose: (a: Resource) => TE.TaskEither<E, void>
) => <T>(consume: (resource: Resource) => TE.TaskEither<E, T>) => (
  TE.bracket(acquire, consume, dispose)
);

type Dependencies = {
  app: HTTP.RequestListener,
  port: number,
};

const acquireServer: R.Reader<Dependencies, TE.TaskEither<Error, HTTP.Server>> = (
  deps => () => new Promise(res => {
    const server = HTTP.createServer(deps.app);
    server.once('error', e => res(E.left(e)));
    server.listen(deps.port, () => res(E.right(server)));
  })
);

const disposeServer = (server: HTTP.Server): TE.TaskEither<Error, void> => (
  () => new Promise(res => {
    server.removeAllListeners('error');
    server.close((e: unknown) => res(
      e instanceof Error ? E.left(e) : E.right(undefined)
    ));
  })
);

const withServer = pipe(
  acquireServer,
  R.map(acquire => createService(acquire, disposeServer))
);

// Possibly in another module:

const port = 3000;
const app = (_: unknown, response: HTTP.ServerResponse) => {
  response.writeHead(200);
  response.end('hello world\n');
};

const program = withServer({app, port})(() => T.delay(30000)(TE.of('done')));

program().then(E.fold(console.error, console.log), console.error);

This approach is based on the booture library that I created for Fluture some time ago, with its ideas ported to fp-ts and fp-ts-cont.

Hey! You're still here? If you paid a lot of attention, you might have noticed the bit of type-cheating I did. You see, due to the Output type being embedded in the Service type, our service consumption isn't truly decoupled from our service definition: The service definition is already deciding what the consumption must return. I'm working on some ideas to fix this. In the meantime, I've been just setting Output to unknown, and not using the output after disposal of the service.

UPDATE: fp-ts-bootstrap was released, which solves this!

A Fallback for the JavaScript Pipeline Operator

Aldwin Vlasblom — Wed, 06 Jan 2021 12:11:58 +0000

Background

As I've also mentioned in my Introduction to Fluture, there's a tc39 proposal for inclusion of a "pipeline operator" into the JavaScript language.

This is great news for functionally-minded libraries such as Ramda, Sanctuary, Fluture, and many more. It also makes some vanilla JavaScript nicer, for example:

const input = '{"data": 1765}';

const answer = String(
  Math.floor(
    Math.sqrt(
      JSON.parse(input).data
    )
  )
);

Becomes

const input = '{"data": 1765}';

const answer = input
  |> JSON.parse
  |> (x => x.data)
  |> Math.sqrt
  |> Math.floor
  |> String;

Pretty neat, right? Well, sadly not everyone agrees. And it is because of this disagreement that the operator has still not made it into the language. What's worse, chances are that when it does make it -- if it does -- it will be in a form that is not half as useful for functional programming. I have argued as to why here, here, here in more depth, and very extensively over here.

The Fallback

That brings me to a small idea I had that allows us to write code much like the above, but in today's JavaScript. You can use it now, while waiting for a consensus to be reached, and in the future, in case the committee decides against the functional variant of the operator. This is what it looks like:

const input = '{"data": 1765}';

const answer = input
  [o] (JSON.parse)
  [o] (x => x.data)
  [o] (Math.sqrt)
  [o] (Math.floor)
  [o] (String);

Very similar to the pipeline example from above! :)

This is how it can be achieved:

const key = Symbol('pipe');

global.o = key;

function pipe(f){ return f(this) };

Object.defineProperty(Object.prototype, key, {value: pipe});

Let's break this down.

Symbol('pipe'): We define a unique symbol. We can use this to mutate existing objects without stepping on anyone's toes.
global.o: This is an optional convenience. In the browser, this should be window.o. But you may just as well export const o instead and import it where needed, so not to pollute the global scope. I chose o as the name because it looks a bit like the mathematical composition operator (∘).
function pipe: All that the (simple) pipe operator does is to apply a function to its context.
Object.defineProperty(...): We attach our pipe method to the Object prototype using our symbol as a key. This immediately retrofits almost all possible values (all the ones that inherit from Object) with our pipeline capabilities.

Alright, well, that's all there is to it. Let's hope that we won't have to use this trick (much longer).

Introduction to Fluture - A Functional Alternative to Promises

Aldwin Vlasblom — Mon, 06 Apr 2020 14:50:53 +0000

fluture-js / Fluture

🦋 Fantasy Land compliant (monadic) alternative to Promises

Fluture offers a control structure similar to Promises, Tasks, Deferreds, and what-have-you. Let's call them Futures.

Much like Promises, Futures represent the value arising from the success or failure of an asynchronous operation (I/O). Though unlike Promises, Futures are lazy and adhere to the monadic interface.

Some of the features provided by Fluture include:

For more information:

Installation

With NPM

$ npm install --save fluture

Bundled from a CDN

To load Fluture directly into a browser, a code pen, or Deno, use one of the following downloads from the JSDelivr content delivery network. These are single…

View on GitHub

In this piece we'll be going over how to use Futures, assuming the why has been covered sufficiently by Broken Promises.

Broken Promises. The unspoken flaws of JavaScript… | by Aldwin Vlasblom | Medium

Aldwin Vlasblom ・ Sep 2, 2024 ・
Medium

We'll be going over Fluture's five major concepts:

Functional Programming: How functional programming patterns determine the Fluture API.
Future Instances: What a Future instance represents, and the ways to create one.
Future Consumption: What consumption of a Future is, and when and how we apply it.
Future Transformation: What we can do with a Future before we've consumed it, and why that's important.
Branching and Error Handling: Introduction to Fluture's "rejection branch", and how it differs from rejected Promises.

A Functional API

The Fluture API was designed to play well with the functional programming paradigm, and libraries within this ecosystem (such as Ramda and Sanctuary). Because of this you'll find that there are almost no methods, and that all functions provided by the library use Function Currying.

So where a piece of Promises-based code might look like this:

promiseInstance
.then(promiseReturningFunction1)
.then(promiseReturningFunction2)

A naive translation to Fluture-based code (using chain) makes that:

chain (futureReturningFunction2)
      (chain (futureReturningFunction1)
             (futureInstance))

And although I'm using Functional Style Indentation to make this code a little more readable, I have to admit that the Promise-based code reads better.

But there's a method to the madness: The API was carefully designed to work well with Function Composition. For example, we can use flow from Lodash* to make the same program look much more like the Promise-based code:

_.flow ([
  chain (futureReturningFunction1),
  chain (futureReturningFunction2),
]) (futureInstance)

^{* There's also pipe from Sanctuary, pipe from Ramda, and many more.}

Better yet, function composition is going to be included as the Pipeline Operator in a future version of JavaScript. Once this is in the language, the code we can write looks identical to the Promise-based code.

futureInstance
|> chain (futureReturningFunction1)
|> chain (futureReturningFunction2)

And whilst looking identical, this function-based code is more decoupled and easier to refactor. For example, I can just grab a piece of that pipeline and extract it to a function:

+const myFunction = chain (futureReturningFunction1)
+
 futureInstance
-|> chain (futureReturningFunction1)
+|> myFunction
 |> chain (futureReturningFunction2)

Doing that to a fluent method chain is not as straightforward:

+const myFunction = promise => promise.then(promiseReturningFunction1)
+
+(
 promiseInstance
-.then(promiseReturningFunction1)
+|> myFunction
+)
 .then(promiseReturningFunction2)

Since the Pipeline Operator is still a language proposal, we might be working in an environment where it's not available. Fluture ships with a pipe method to simulate what working with the pipeline operator would be like. It has all the mechanical advantages of the pipeline operator, but it's a little more verbose.

futureInstance
.pipe (chain (futureReturningFunction1))
.pipe (chain (futureReturningFunction2))

Creating Future Instances

Future instances are slightly different from Promise instances, in that they represent an asynchronous computation as opposed to an asynchronously acquired value. Creating a Future instance is very similar to creating a Promise, however. The simplest way is by using the resolve or reject functions, which create resolved or rejected Futures respectively. For now through, we'll focus on the general constructor function: Future, and how it compares to Promise construction.

const promiseInstance = new Promise ((res, rej) => {
  setTimeout (res, 1000, 42)
})

const futureInstance = Future ((rej, res) => {
  const job = setTimeout (res, 1000, 42)
  return function cancel(){
    clearTimeout (job)
  }
})

Some notable differences:

The new keyword is not required. In functional programming, we make no distinction between functions that return objects, and functions that return any other kind of data.
The rej and res arguments are flipped, this has to do with some conventions in the functional programming world, where the "more important" generic type is usually placed on the rightmost side.
We return a cancellation function (cancel) into the Future constructor. This allows Fluture to clean up when a running computation is no longer needed. More on that in the section about Consuming Futures.

The Future constructor used above is the most flexible way to create a new Future, but there's also more specific ways of Creating Futures. For example, to create a Future from a node-style callback function, we can use Fluture's node function:

const readText = path => node (done => {
  fs.readFile (path, 'utf8', done)
})

Here we've created a function readText, which given a file path returns a Future which might reject with an Error, or resolve with the contents of the corresponding file decoded from utf8.

Doing the same using the flexible Future constructor is more work:

const readText = path => Future ((rej, res) => {
  fs.readFile (path, 'utf8', (err, val) => err ? rej (err) : res (val))
  return () => {}
})

As we can see, node took care of the empty cancellation function, and juggling with the callback arguments. There's also Future constructors that reduce the boilerplate when working with underlying Promise functions, or functions that throw exceptions. Feel free to explore. All of them are listed under the Creating Futures section of the Fluture docs.

In day-to-day use, you should find that the Future constructor is needed only for the most specific of cases and you can get very far using the more specialized ones.

Consuming Futures

In contrast to a Promise, a Future will have to be eventually "consumed". This is because - as I mentioned earlier - Futures represent a computation as opposed to a value. And as such, there has to be a moment where we tell the computation to run. "Telling the Future to run" is what we refer to as consumption of a Future.

The go-to way to consume a Future is through the use of fork. This function takes two continuations (or callbacks), one for when the Future rejects, and one for when it resolves.

const answer = resolve (42)

const consume = fork (reason => {
  console.error ('The Future rejected with reason:', reason)
}) (value => {
  console.log ('The Future resolved with value:', value)
})

consume (answer)

When we instantiated the answer Future, nothing happened. This holds true for any Future we instantiate through any means. The Futures remain "cold" until they are consumed. This contrasts with Promises, which eagerly evaluate their computation as soon as they are created. So only the last line in the example above actually kicked off the computation represented by the answer Future.

In this case, if we would run this code, we would see the answer immediately. That's because resolve (42) knew the answer up-front. But many Futures could take some time before they get to an answer - maybe they're downloading it over a slow connection, or spawning a botnet to compute the answer. This also means that it might take too long, for example if the user got bored, or another satisfactory answer has come in from another source. For those cases, we can unsubscribe from the consumption of a Future:

const slowAnswer = after (2366820000000000000) (42)
const consume = value (console.log)
const unsubscribe = consume (slowAnswer)

setTimeout (unsubscribe, 3000)

In this example, we use after to create a Future which takes approximately seven and a half million years to compute the answer. And we're using value to consume the Future, assigning its output to unsubscribe.

Then we got bored waiting for the answer after three seconds, and unsubscribed. We were able to do so because most consumption functions return their own unsubscription function. When we unsubscribe, Fluture uses the cancellation functions defined inside the underlying constructors (in our example, that would be the cancellation function created by after) to stop any running computations. More about this in the Cancellation section of the Fluture README.

Consumption of a Future can be thought of as turning the asynchronous computation into the eventual value that it'll hold. There's also other ways besides fork to consume a Future. For example, the promise function consumes the Future and returns a Promise of its eventual result.

Not Consuming Futures

Unlike with a Promise, we can choose not to consume a Future (just yet). As long as a Future hasn't been consumed yet, we can extend, compose, combine, pass-around, and otherwise transform it as much as we like. This means we're treating our asynchronous computations as regular values to be manipulated in all the same ways we're used to manipulate values.

Manipulating Futures (as the Time-Lords we are) is what the Fluture library is all about - I'll list some of the possibilities here. You don't have to read too much into these: they're just to give you an idea of the sort of things you can do. We'll also be using these functions in some of the examples further down.

chain transforms the value inside a Future using a function that returns another Future.
map transforms the value inside a Future using a function to determine the new value it should hold.
both takes two Futures and returns a new Future which runs the two in parallel, resolving with a pair containing their values.
and takes two Futures and returns a new Future which runs them in sequence, resolving with the value from the second Future run.
lastly takes two Futures and returns a new Future which runs them in sequence, resolving with the value from the first Future run.
parallel takes a list of Futures, and returns a new Future which runs them all in parallel, with a user-chosen limit, and finally resolves with a list of each of their resolution values.

And many more. The purpose of all of these functions is to give us ultimate control over our asynchronous computations. To sequence or to parallelize, to run or not to run, to recover from failure. As long as the Future has not yet been consumed, we can modify it in any way we want.

Representing asynchronous computations as regular values - or "first-class citizens", if you will - gives us a level flexibility and control difficult to convey, but I will try. I'll demonstrate a problem similar to one I faced some time ago, and show that the solution I came up with was only made possible by first class asynchronous computations. Suppose we have an async program like the one below:

//This is our readText function from before, reading the utf8 from a file.
const readText = path => node (done => fs.readFile (path, 'utf8', done))

//Here we read the index file, and split out its lines into an Array.
const eventualLines = readText ('index.txt')
                      .pipe (map (x => x.split ('\n')))

//Here we take each line in eventualLines, and use the line as the path to
//additional files to read. Then, using parallel, we run up to 10 of those
//file-reads in parallel, obtaining a list of all of their texts.
const eventualTexts = eventualLines
                      .pipe (map (xs => xs.map (readText)))
                      .pipe (chain (parallel (10)))

//And at the end we consume the eventualTexts by logging them to the console.
eventualTexts .pipe (value (console.log))

^{The problem solved in this example is based on the Async Problem.}

And what if it's taking a really long time, and we want to find out which part of the program is taking the longest. Traditionally, we would have to go in and modify the transformation functions, adding in calls to console.time. With Futures, I could define a function that does this automatically:

const time = tag => future => (
  encase (console.time) (tag)
  .pipe (and (future))
  .pipe (lastly (encase (console.timeEnd) (tag)))
)

Let's go over the function line by line to see how it uses async computation as first-class citizens to achieve what it does.

We're taking two arguments, tag and future. The one to pay attention to is future. This function demonstrates something we rarely do with Promises and that is to pass them around as function arguments.
We use encase to wrap the console.time call in a Future. This prevents it from running right away, and makes it so we can combine it with other Futures. This is a common pattern when using Futures. Wrapping any code that has a side-effect in a Future will make it easier to manage the side-effect and control where, when, and if it will happen.
We use and to combine the future which came in as an argument with the Future that starts the timer.
We use lastly to combine the computation (which now consists of starting a timer, followed by an arbitrary task) with a final step for writing the timing result to the console using console.timeEnd.

Effectively what we've created is a function that takes in any Future, and returns a new Future which has the same type, but is wrapped in two side-effects: the initialization and finalization of a timer.

With it, we can sprinkle our code with timers freely, without having to worry that the side-effects (represented by the return values of the time function) will happen at the wrong moments:

//Simply pipe every file-read Future through 'time'.
const readText = path => node (done => fs.readFile (path, 'utf8', done))
                         .pipe (time (`reading ${path}`))

//Measure reading and processing the index as a whole.
const eventualLines = readText ('index.txt')
                      .pipe (map (s => s.split ('\n')))
                      .pipe (time ('getting the lines'))

const eventualTexts = eventualLines
                      .pipe (map (ss => ss.map (readText)))
                      .pipe (chain (parallel (10)))

//And finally we insert an "everything" timer just before consumption.
eventualTexts .pipe (time ('everything')) .pipe (value (console.log))

The time function just transforms a computation from one "list of instructions" to another, and the new computation will always have the timing instructions inserted exactly before and after the instruction we want to measure.

The purpose of all of this was to illustrate the benefit of "first-class asynchronous computations"; A utility like this time function would not have been possible without them. For example with Promises, by the time a Promise would be passed into the time function, it would already be running, and so the timing would be off.

The header of this section was "Not Consuming Futures", and it highlights an idea that I really want to drive home: in order to modify computations, they should not be running yet. And so we should refrain from consuming our computation for as long as possible.

In general, and as a rule-of-thumb, every program only has a single place where a Future is consumed, near the entry-point of the program.

Branching and Error Handling

Until this point in the article we've only covered the "happy paths" of asynchronous computation. But as we know, asynchronous computations occasionally fail; That's because "asynchronous" in JavaScript usually means I/O, and I/O can go wrong. This is why Fluture comes with a "rejection branch", enabling it's use for a style of programming sometimes referred to as Railway Oriented Programming.

When transforming a Future using transformation functions such as the aforementioned map or chain, we'll affect one of the branches without affecting the other. For example map (f) (reject (42)) equals reject (42): the transformation had no effect, because the value of the Future was in the rejection branch.

There's also functions that affect only the rejection branch, such as mapRej and chainRej. The following program prints the answer 42, because we start with a rejected Future, and apply transformations to the rejection branch. In the last transformation using chainRej, we switch it back to the resolution branch by returning a resolved Future.

const future = reject (20)
               .pipe (mapRej (x => x + 1))
               .pipe (chainRej (x => resolve (x + x)))

future .pipe (value (console.log))

Finally, there's also some functions that affect both branches, like bimap and coalesce. They definitely have their uses, but you'll need them less often.

I sometimes think of the two branches of a Future as two railway tracks parallel to each other, with the various transformation functions represented by junctions affecting the tracks and the payload of the train. I'll draw it. Imagine both lines being railway tracks, with the train driving from top to bottom on one of either track.

                 reject (x)  resolve (y)
                       \      /
                  :     |    |     :
         map (f)  :     |   f y    :  The 'map' function affects the value in
                  :     |    |     :  the resolution track, but if the train
                  :     |    |     :  would've been on the rejection track,
                  :     |    |     :  nothing would've happened.
                  :     |    |     :
                  :     |    |     :
       chain (f)  :     |   f y    :  The 'chain' function affects the value in
                  :     |   /|     :  the resolution track, and allowed the
                  :     |  / |     :  train to change tracks, unless it was
                  :     | /  |     :  already on the rejection track.
                  :     |/   |     :
                  :     |    |     :
coalesce (f) (g)  :    f x  g y    :  The 'coalesce' function affects both
                  :      \   |     :  tracks, but forces the train to switch
                  :       \  |     :  from the rejection track back to the
                  :     _  \ |     :  resolution track.
                  :     |   \|     :
                  :     |    |     :
         and (m)  :     |    m     :  The 'and' function replaces a train on
                  :     |   /|     :  the resolution track with another one,
                  :     |  / |     :  allowing it to switch tracks.
                  :     | /  |     :
                  :     |/   |     :
                  :     |    |     :
    chainRej (f)  :    f y   |     :  The 'chainRej' function is the opposite
                  :     |\   |     :  of the 'chain' function, affecting the
                  :     | \  |     :  rejection branch and allowing a change
                  :     |  \ |     :  back to the resolution track.
                  :     |   \|     :
                  :     |    |     :
                        V    V

This model of programming is somewhat similar to pipelines in Bash scripting, with stderr and stdout being analogous to the rejection and resolution branches respectively. It lets us program for the happy path, without having to worry about the unhappy path getting in the way.

Promises have this too, in a way, but Fluture takes a slightly different stance on what the rejection branch should be used for. This difference is most obvious in the way thrown exceptions are treated. With Promises, if we throw an exception, it ends up in the rejection branch, mixing it in with whatever other thing we might have had there. This means that fundamentally, the rejection branch of a Promise has no strict type. This makes the Promise rejection branch a place in our code that could produce any surprise value, and as such, not the ideal place for "railway oriented" control flow.

Fluture's rejection branch was designed to facilitate control flow, and as such, does not mix in thrown exceptions. This also means the rejection branch of a Future can be strictly typed and produces values of the type we expect.

When using Fluture - and functional programming methodologies in general - exceptions don't really have a place as constructs for control flow. Instead, the only good reason to throw an exception is if a developer did something wrong, usually a type error. Fluture, being functionally minded, will happily let those exceptions propagate.

The philosophy is that an exception means a bug, and a bug should affect the behaviour of our code as little as possible. In compiled languages, this classification of failure paths is much more obvious, with one happening during compile time, and the other at runtime.

In Summary

The Fluture API design is based in the functional programming paradigm. It heavily favours function composition over fluent method chains and plays well with other functional libraries.
Fluture provides several specific functions, and a general constructor, to create Futures. Futures represent asynchronous computations as opposed to eventual values. Because of this, they are cancellable and can be used to encase side-effects.
The asynchronous computations represented by Futures can be turned into their eventual values by means of consumption of the Future.
But it's much more interesting not to consume a Future, because as long as we have unconsumed Future instances we can transform, combine, and otherwise manipulate them in interesting and useful ways.
Futures have a type-safe failure branch to describe, handle, and recover from runtime I/O failures. TypeErrors and bugs don't belong there, and can only be handled during consumption of the Future.

And that's all there really is to know about Fluture. Enjoy!

Composable Callbacks

Aldwin Vlasblom — Wed, 20 Dec 2017 12:23:24 +0000

A Promise implementation in under sixty characters

You’ve heard it before: nested callbacks don't scale, and leave you in callback hell. So in this article, we will see how far we can push the callbacks approach, and see if we can reach a point where they're just as scalable/composable as Promises.

Let’s start by thinking about how we define functions for a moment. A regular addition function might be defined as such:

//    add :: (Number, Number) -> Number
const add = (a, b) => a + b

But we can also define it slightly differently, as a function that takes a single argument, and returns a function that takes another argument, which in turn returns the result of adding the two arguments together:

//    add :: Number -> Number -> Number
const add = a => b => a + b

Many of you will recognise the latter as being the "curried" variant of the first. You can read up on currying in Chapter 4 of the Mostly Adequate Guide.

Defining the function this way unlocks some new ways of using the function. For example, we can easily define a new add5 function by applying add to 5, for mapping over an Array, for example:

[1, 2, 3, 4, 5] .map (add (5))
//> [6, 7, 8, 9, 10]

We are going to define all of our functions in the curried way, which is the first step to making callbacks more managable.

Let’s take a basic example of an asynchronous program using callbacks:

fs.readFile ('input.txt', 'utf8', (e, input) => {
  if (e) console.error (e)
  else fs.readFile (`${input}-file.txt`, 'utf8', (e, result) => {
    if (e) console.error (e)
    else console.log (result)
  })
})

When we do it like this, it sends us straight to callback hell. Let’s see what we can do after creating a curried version of readFile. (I'll also simplify the callback a little bit by taking away the error argument. We’ll get back to this near the end of this article.)

//    readFile :: String -> String -> (String -> Undefined) -> Undefined
const readFile = encoding => filename => callback => {
  fs.readFile (filename, encoding, (e, contents) => {
    if (e) console.error (e)
    else callback (contents)
  })
}

By now you might be wondering what those ::-comments are doing above every function. They are type definitions in a neat type language called Hindley Milner. The "HM" language is very succinct when describing curried functions in particular. If you take a short moment to understand how it works, it’ll help you to see more clearly what’s happening with our functions. You can read more about it in Chapter 7 of the Mostly Adequate Guide.

You may also have noticed that I’ve shuffled the argument order a little bit. This is to be more optimised for partial application. This new definition of readFile allows us to partially apply it, and not pass the callback yet.

//    readText :: String -> (String -> Undefined) -> Undefined
const readText = readFile ('utf8')

//    step1 :: (String -> Undefined) -> Undefined
const step1 = readText ('input.txt')

//    step2 :: String -> (String -> Undefined) -> Undefined
const step2 = input => readText (`${input}-file.txt`)

//    step3 :: String -> Undefined
const step3 = console.log

Let’s look at what we’ve created here:

readText: A partial application of readFile, with the encoding. We can just reuse it without having to pass 'utf8' everywhere.
step1: A partial application of readText. The only argument left now is the actual callback. So step1 becomes a function that takes a callback to which the contents of input.txt will be passed.
step2: A function that takes some input and uses it to read a file with a name containing said input. It doesn’t actually read any files though, it just partially applies readText again and returns the function waiting for a callback.
step3: Just an alias to console.log for illustrative purposes. It used to be nested inside the callback to step2.

Now if we study the signatures of each of these functions, we’ll find that they all plug into each other quite nicely. step3 could be used as a callback for step2, and the entirety of step2 could be used as the argument to step1. Doing that would require a lot of nesting, but we can define a helper function which "flattens" the nesting. Let’s call it then ;)

//    then :: (a -> (b -> Undefined) -> Undefined)
//         -> (     (a -> Undefined) -> Undefined)
//         ->       (b -> Undefined) -> Undefined
const then = transform => run => callback => run (value => transform (value) (callback))

Our then function takes three arguments:

A transform function, which receives a value and produces a function waiting for its callback. Our step2 actually fits this description.
A function still waiting for its callback. Our step1 fits this.
A callback. Our step3 fits this one.

What’s cool about this function, is that when we partially apply it with its first two arguments, we get back a function that fits precisely into the second argument of then again. This is what will allow us to stick multiple "steps" next to one another, rather then nested within each other.

You might have noticed from the signature that there are three instances of (a -> Undefined) -> Undefined. It would become a lot more clear if we gave this particular type a special name, and use that in our types instead. Let’s create a simple alias (Future) for the callback-taking function. The constructor for this type has no implementation: it just returns the input (because it’s an alias). But it will help to make our code clearer. Let’s redefine our then function with more clearly named types.

//    Future :: ((a -> Undefined) -> Undefined) -> Future a
const Future = x => x

//    then :: (a -> Future b) -> Future a -> Future b
const then = transform => future => Future (callback => {
  future (value => transform (value) (callback))
})

This new then function is exactly the same as the previous one, but it suddenly becomes a lot clearer what it’s doing: It takes a function that creates a Future, and it takes a Future and finally returns a new Future. Speaking in these terms, step1 is a Future of a String, and step2 returns a Future of a String, after taking a String.

Equipped with our then function and type alias, we can rewrite our callback hell program.

//    Future :: ((a -> Undefined) -> Undefined) -> Future a
const Future = x => x

//    then :: (a -> Future b) -> Future a -> Future b
const then = transform => future => Future (callback => {
  future (value => transform (value) (callback))
})

//    readFile :: String -> String -> Future String
const readFile = encoding => filename => Future (callback => {
  fs.readFile (filename, encoding, (e, contents) => {
    if (e) console.error (e)
    else callback (contents)
  })
})

//    readText :: String -> Future String
const readText = readFile ('utf8')

//    step1 :: Future String
const step1 = readText ('input.txt')

//    step2 :: String -> Future String
const step2 = input => readText (`${input}-file.txt`)

//    program :: Future String
const program = then (step2) (step1)


program (console.log)

Our then function is actually doing mathematically accurate flat-mapping. Just see what happens if we replace Future by Array in the type signature. The abstract interface behind flat-map-able types is called "Monad" (because the mathematicians beat us to it).

The fact that we could use program as an argument to then in order to compose a bigger program means we have achieved our goal of making callbacks composable just like Promises.

Let’s get back to this console.error-bit though, because we’ve lost the ability to manually handle errors. We can add that back, simply by having our function take two callbacks instead of one.

//    Future :: (((a -> Undefined) -> Undefined)
//           -> ((b -> Undefined) -> Undefined))
//           -> Future a b
const Future = x => x

//    then :: (b -> Future a c) -> Future a b -> Future a c
const then = transform => future => Future (reject => resolve => {
  future (reject) (value => transform (value) (reject) (resolve))
})

//    readFile :: String -> String -> Future Error String
const readFile = encoding => filename => Future (reject => resolve => {
  fs.readFile (filename, encoding, (e, contents) => {
    if (e) reject (e)
    else resolve (contents)
  })
})

//    readText :: String -> Future Error String
const readText = readFile ('utf8')

//    step1 :: Future Error String
const step1 = readText ('input.txt')

//    step2 :: String -> Future Error String
const step2 = input => readText (`${input}-file.txt`)

//    program :: Future Error String
const program = then (step2) (step1)


program (console.error) (console.log)

The then function in our last example gives us similar asynchronous function composition and error handling benefits to those that Promises give us, in a function that can be written in under sixty characters:

const then = f => m => l => r => m (l) (x => f (x) (l) (r))

It even does away with many of the problems that Promises have. But it does leave some things to be desired, such as good performance and stack safety. For our purpose though, it will do just fine: to solve the Async Problem and demonstrate that callbacks are just as composable as synchronous code.

The original version of Fluture was pretty much implemented like this, except that then is called chain.

Solving the Async Problem

The Async Problem is a little challenge set to identify how well an abstraction allows the user to break an asynchronous algorithm into small, manageable sub-problems. To conclude this post, let’s dive into the depths and solve it with callbacks.

//    pipe :: Array (Any -> Any) -> Any -> Any
const pipe = fs => x => fs.reduce ((y, f) => f (y), x)

//    lmap :: (a -> b) -> Array a -> Array b
const lmap = f => xs => xs.map (f)

//    append :: a -> Array a -> Array a
const append = x => xs => [...xs, x]



//    pure :: b -> Future a b
const pure = x => l => r => r (x)

//    then :: (b -> Future a c) -> Future a b -> Future a c
const then = f => m => l => r => m (l) (x => f (x) (l) (r))

//    fmap :: (b -> c) -> Future a b -> Future a c
const fmap = f => then (x => pure (f (x)))

//    all :: Array (Future a b) -> Future a (Array b)
//        -- Note: This implementation resolves things in sequence for brevity.
const all = ms => ms.reduce
  ((mxs, mx) => then (x => fmap (append (x)) (mxs)) (mx), pure ([]))



const filesystem = require ('fs')
const path = require ('path')

//    readFile :: String -> String -> Future Error String
const readFile = encoding => filename => l => r => {
  filesystem.readFile (filename, encoding, (e, contents) => {
    if (e) l (e)
    else r (contents)
  })
}

//    readText :: String -> Future Error String
const readText = readFile ('utf8')

//    lines :: String -> Array String
const lines = s => s.split ('\n')

//    unlines :: Array String -> String
const unlines = ss => ss.join ('\n')

//concatFiles :: (String -> String) -> Future Error String
const concatFiles = path =>
  pipe ([ path
        , readText
        , fmap (lines)
        , fmap (lmap (path))
        , fmap (lmap (readText))
        , then (all)
        , fmap (unlines) ])
       ('index.txt')


const main = () => {
  concatFiles (x => path.resolve (process.argv[2], x))
              (e => { process.stderr.write (e.message); process.exit (1) })
              (x => { process.stdout.write (x); process.exit (0) })
}

main()