Skip to content
Synchronous Promise-like API
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets
README.md
contract.test.js
error.js
index.js
lists.js
package.json
symbols.js

README.md

Contract

Logo

Hello, this is a synchronous continuation monad library, with the following goals:

  • Promise compatibility
  • Flexibility
  • Usability

Think of this as a synchronous Promise-API if it helps

Here is a basic Promise-compatible example to let you know what this library can do for you:

Contract.resolve('He') // Contract { 'He' }
	.then(x => x + 'llo') // Contract { 'Hello' }
	.then(x => x.split('')) // Contract { [ 'H', 'e', 'l', 'l', 'o' ] }
	.map(x => x.charCodeAt(0)) // Contract { [ 72, 101, 108, 108, 111 ] }
	.map(x => x * 3) // Contract { [ 216, 303, 324, 324, 333 ] }
	.filter(x => x % 2 === 0) // Contract { [ 216, 324, 324 ] }
	.tap(console.log) // Contract { [ 216, 324, 324 ] }
	// Logs: [ 216, 324, 324 ]
	.reduce((a, b) => a + b, 0) // Contract { 864 }
	.then(() => {
		throw new Error('Hello World');
	}) // Contract { (rejected) Error<Hello World> }
	.catch(console.error); // Contract { undefined }

It also supports laziness through generators!

function* naturalNumbers() {
	let i = 1;
	while (true)
		yield i++;
}

Contract.of(naturalNumbers())
	.lazy.map(x => x * 3)
	.lazy.filter(x => x % 2 === 0)
	.lazy.take(10)
	.toArray()
	.then(console.log);
	// Logs: [ 6, 12, 18, 24, 30, 36, 42, 48, 54, 60 ]

(This will only start iterating natural numbers after .toArray() has been called)

Installation

npm i @thedevs/contract

Roadmap

  • Make this library fully Promise-compatible (except async stuff)
  • Make it work in browsers
  • Have examples for all methods

Thanks to

@MKRhere for the original idea

API Reference

Contract

This is the complete function signature of the constructor:

Contract(Contract | Promise | Function -> (Contract | Promise | any) | any[, ...args])
-> Contract { any } | Promise { any }

Expressed in english:

  1. If the first argument is already a Contract, it will simply return that.
  2. If the first argument is a Promise, it will return that
  3. If the first argument is not a function, it will return a Contract that resolves to that
  4. Otherwise, it will run the function with the provided rest arguments.
  5. If the function throws, it will return a rejecting Contract
  6. If the return value of the function is a Contract or a Promise, it will return that
  7. Otherwise, it will return Contract { return value }

Contract.resolve

Contract.of

Contract.from

Aliases, these three do the same: Create a contract from a value

Contract.resolve(value) -> Contract { value }

Contract.reject

Create a rejecting Contract from the given error (or value)

Contract.isContract

Checks if the given value is a Contract

Contract.all

Resolves an array of functions, values, or Contracts (rejects if any of the functions throw, return a rejecting Contract, or any Contract in the array is rejected)

Instance methods

All instance methods are also available as thunks, for Promise-interoperability:

Promise.resolve(Contract.of([ 1, 2, 3 ]))
	.then(Contract.map(x => x * 2))
	.then(Contract.reduce((a, b) => a + b, 0))
	.then(Contract.tap(console.log))
	// Promise { Contract { 12 } }

Contract#then

Works just like Promises, maps the existing value to a new value

Contract#catch

Catches a rejected Contract (Resolves it)

Contract#tap

Do something with a value without changing the Contract (useful for logging / debugging)

Contract#map

Map the contents of an array within a Contract easily (Similar to bluebird's map)

Contract#reduce

Similar to bluebird's reduce

Contract#filter

Similar to bluebird's filter

Contract#spread

Similar to bluebird's spread

Contract#take

Slice an array within a contract (take the first N elements)

Contract#toArray

Convert the inner value of a contract to an array (useful with lazy values)

Contract#toString

Convert the inner value of a contract to a string

Contract#lazy.map

Lazily map values (Returns an iterator)

Contract#lazy.filter

Lazily filter values (Returns an iterator)

Contract#lazy.take

Lazily take values (Returns an iterator)

You can’t perform that action at this time.