@justinc/sequence

sequence

This package exports a function similar to Ramda's sequence function.

Note that it is strictly curried (see demo usage below).

Known issue

For this package to work, the Applicative (see below) ADT value you use must have the following sematics for the .ap method: fnApplicative.ap(valueApplicative). This is Fantasy Land pre-v1.0.0 semantics.

Folktale 2's Applicative ADTs have this behaviour for their .ap method (and support v1.0.0+ semantics of .ap via valueApplicative['fantasy-land/ap'](fnApplicative)).

sequence uses the .ap method. This means sequence will work with Folktale 2 ADTs (as well as Folktale 1 mico-libs like data.maybe etc…).

In the future, it is likely that a major version update of this package will take a config Object as the first curried function which can configure which sematics of .ap to use. Apart from this, it will be possible to add to this config enabling/disabling of "basic type checking" to make sure we have the required methods that make up an "Applicative". This "basic type checking" is on by force in version ^1.0.0 - which could get expensive for large iterables.

Install

npm i @justinc/sequence

Demo

(See tests for more example usage). Also, there's a REPL file you can run with node repl.js.

const Maybe = require('folktale/data/maybe')
const sequence = require('@justinc/sequence')

const { Just, Nothing } = Maybe

// "strictly curried" means you cannot use short-hands like `sequence(Maybe.of, [Just(1), Just(2), Just(3)])`.
// That's extra functionality provided by Ramda (not provided here).
sequence(Maybe.of)([Just(1), Just(2), Just(3)]) // ==> Just([1, 2, 3])

Functions

sequence([applicativeReturningFn], [iterable]) ⇒ Applicative.<Array.<T>>

This function is curried.

The applicativeReturningFn is expected to return a value of type Applicative. Also, it is expected that the Applicative returned by applicativeReturningFn is of the same kind as the Applicatives in the given iterable (2nd curried param). e.g. if applicativeReturningFn returns a Maybe, iterable is expected to have Maybe values.

Just like the Ramda function with the same name, this function:

"Transforms a Traversable of Applicative into an Applicative of Traversable."

e.g. if applicativeReturningFn returns a Maybe, and iterable is made up of Maybe T values, then this function returns a Maybe<Array<T>> where T is a type like String etc…

Typedefs

Applicative : Object

This is a value as specified in the Fantasy Land spec for Applicative. This means that a value of this type needs to have of, ap and map methods with the properties specified in the Fantasy Land spec.

sequence([applicativeReturningFn], [iterable]) ⇒ Applicative.<Array.<T>>

This function is curried.

The applicativeReturningFn is expected to return a value of type Applicative. Also, it is expected that the Applicative returned by applicativeReturningFn is of the same kind as the Applicatives in the given iterable (2nd curried param). e.g. if applicativeReturningFn returns a Maybe, iterable is expected to have Maybe values.

Just like the Ramda function with the same name, this function:

"Transforms a Traversable of Applicative into an Applicative of Traversable."

e.g. if applicativeReturningFn returns a Maybe, and iterable is made up of Maybe T values, then this function returns a Maybe<Array<T>> where T is a type like String etc…

Kind: global function
See: Applicative

Param	Type	Description
[applicativeReturningFn]	function	A function that returns an Applicative
[iterable]	Iterable.<Applicative>	An iterable of Applicatives

Applicative : Object

This is a value as specified in the Fantasy Land spec for Applicative. This means that a value of this type needs to have of, ap and map methods with the properties specified in the Fantasy Land spec.

Kind: global typedef