//  ) )     
    ___      ___      ___   __//__         
  //   ) ) //   ) ) ((   ) ) //   //   / / 
 //       //___/ /   \ \    //   ((___/ /  
((____   //       //   ) ) //        / /   

(Generated with http://patorjk.com/software/taag)

cpsfy

Tiny but powerful goodies for Continuation-Passing-Style (CPS) functions with functional composability backed by category theory foundations.

1npm install cpsfy

(Or pnpm install cpsfy to save disc space.)

No dependency policy. For maximum security, this package is intended to be kept minimal and transparent with no dependencies ever.

Quick demo

We want to read the content of name.txt into string str and remove spaces from both ends of str. If the resulting str is nonempty, we read the content of the file with that name into string content, otherwise do nothing. Finally we split the content string into array of lines. If there are any errors on the way, we want to handle them at the very end in a separate function without any change to our main code.

1//function returning CPS function with 2 callbacks
2const readFileCps = file => (onRes, onErr) =>  
3  require('fs').readFile(file, (err, content) => {
4    err ? onErr(err) : onRes(content)
5  })
6
7// the provided `CPS` operator wraps a CPS function to provide the API methods
8const getLines = CPS(readFileCps('name.txt'))
9  // map applies function to the file content
10  .map(file => file.trim()) 
11  .filter(file => file.length > 0)
12  // chain applies function that returns a CPS function
13  .chain(file => readFileCps(file))
14  .map(text => text.split('\n'))
15// => CPS function with 2 callbacks
16
17// To use, simply pass callbacks in the same order
18getLines(
19  lines => console.log(lines),  // onRes callback
20  err => console.error(err)  // onErr callback
21)

Note how we handle error at the end without affecting the main logic!

But can't I do it with promises?

Ok, let us have another example where you can't.:wink: Reading from static files is easy but boring. Data is rarely static. What if we have to react to data changing in real time? Like our file names arriving as data stream? Let us use the popular websocket library:

1const WebSocket = require('ws')
2// general purpose CPS function listening to websocket
3const wsMessageListenerCps = url => cb => 
4  new WebSocket(url).on('message', cb)

And here is the crux:

wsMessageListenerCps(url) is just another CPS function!

So we can simply drop it instead of readFileCps('name.txt') into exactly the same code and be done with it:

1const getLinesFromWS = CPS(wsMessageListenerCps(someUrl))
2  .map(file => file.trim()) 
3  .filter(file => file.length > 0)
4  .chain(file => readFileCps(file))
5  .map(text => text.split('\n'))
6

The new CPS function has only one callback, while the old one had two! Yet we have used exactly the same code! How so? Because we haven't done anything to other callbacks. The only difference is in how the final function is called - with one callback instead of two. As wsMessageListenerCps(url) accepts one callback, so does getLinesFromWS when we call it:

1getLinesFromWS(lines => console.log(lines))

That will print all lines for all files whose names we receive from our websocket. And if we feel overwhelmed and only want to see lines containing say "breakfast", nothing can be easier:

1// just add a filter
2const breakfastLines = CPS(getLinesFromWS)
3  .filter(line => /[Bb]reakfast/.test(line))
4// call it exactly the same way
5breakfastLines(lines => console.log(lines))

And from now on we'll never miss a breakfast.:smile:

CPS function

Any function

1const cpsFn = (cb1, cb2, ...) => { ... } 

that expects to be called with several (possibly zero) functions (callbacks) as arguments. The number of callbacks may vary each time cpsFn is called. Once called and running, cpsFn may call any of its callbacks any (possibly zero) number of times with any number m of arguments (x1, ..., xm), where m may also vary from call to call. The m-tuple (vector) (x1, ..., xm) is regarded as the output of cpsFn from the nth callback cbn:

1// (x1, ..., xm) becomes output from nth callback whenever
2cbn(x1, ..., xm)  // is called, where n = 1, 2, ..., m

In other words, a CPS function receives any number of callbacks that it may call in any order any number of times at any moments immediately or in the future with any number of arguments.

API in brief

1const { map, chain, filter, scan, ap, CPS, pipeline } 
2  = require('cpsfy')

Each of the map, chain, filter, scan operators can be used in 3 ways:

1// 'map' as curried function
2map(f)(cpsFn)
3// 'map' method provided by the 'CPS' wrapper
4CPS(cpsFn).map(f)
5// 'cpsFn' is piped into 'map(f)' via 'pipeline' operator
6pipeline(cpsFn)(map(f))

The wrapped CPS function CPS(cpsFn) has all operators available as methods, while it remains a plain CPS function, i.e. can be called with the same callbacks:

1CPS(cpsFn)(f1, f2, ...) // is equivalent to
2cpsFn(f1, f2, ...)

pipeline(...arguments)(...functions)

Pass any number of arguments to a sequence of functions, one after another, similar to the UNIX pipe (x1, ..., xn) | f1 | f2 | ... | fm. Allows to write functional composition in the intiutive linear way.

Examples of pipeline

1pipeline(1, 2)(
2  (x, y) => x + y,
3  sum => sum * 2,
4  doubleSum => -doubleSum
5) //=> -6

chaining

The CPS factory provides the same methods for simple chaining:

1CPS(cpsFn).map(f).chain(g).filter(h)

However, the need to wrap a plain function might feel as overhead. The pipeline operator allows to write the same code in functional style without the need to wrap:

1// pass cpsFn directly as argument
2pipeline(cpsFn)(
3  map(f),
4  chain(g),
5  filter(h)
6)

But the most important advantage of the pipeline style is that you can drop there arbitrary functions without any need to patch object prototypes. For instance, using the above example, we can start our pipe with url or even insert some intermediate function to compute the correct url for us:

1pipeline(path)(               // begin with path
2  path => 'https://' + path  // compute url on the spot
3  url => {console.log(url); return url} // check for debugging
4  wsMessageListenerCps,       // return CPS function
5  map(f),                     // use CPS operators as usual
6  chain(g),
7  filter(h)
8)
9

map(...functions)(cpsFunction)

1// these are equivalent
2map(f1, f2, ...)(cpsFn)
3CPS(cpsFn).map(f1, f2, ...)
4pipeline(cpsFn)(map(f1, f2, ...))

For each n, apply fn to each output from the nth callback of cpsFn.

Result of applying map

New CPS function that calls its nth callback cbn as

1cbn(fn(x1, x2, ...))

whenever cpsFn calls its nth callback.

Example of map

Using readFileCps as above.

1// read file and convert all letters to uppercase
2const getCaps = map(str => str.toUpperCase())(
3  readFileCps('message.txt')
4)
5// or
6const getCaps = CPS(readFileCps('message.txt'))
7  .map(str => str.toUpperCase())
8// or
9const getCaps = pipeline(readFileCps('message.txt'))(
10  map(str => str.toUpperCase())
11)
12
13// getCaps is CPS function, call with any callback
14getCaps((err, data) => err 
15  ? console.error(err) 
16  : console.log(data)
17) // => file content is capitalized and printed

chain(...functions)(cpsFunction)

1// these are equivalent
2chain(f1, f2, ...)(cpsFn)
3CPS(cpsFn).chain(f1, f2, ...)
4pipeline(cpsFn)(chain(f1, f2, ...))

where each fn is a curried function

1// fn is expected to return a CPS function
2const fn = (x1, x2, ...) => (cb1, cb2, ...) => { ... }

The chain operator applies each fn to each output from the nth callback of cpsFn, however, the CPS ouptup of fn is passed ahead instead of the return value.

Result of applying chain

New CPS function newCpsFn that calls fn(x1, x2, ...) whenever cpsFn passes output (x1, x2, ...) into its nth callback, and collects all outputs from all callbacks of all fns. Then for each fixed m, outputs from the mth callbacks of all fns are collected and passed into the mth callback cbm of newCpsFn:

1cbm(y1, y2, ...)  // is called whenever 
2cbmFn(y1, y2, ...)  // is called where
3// cbmFn is the mth callback of fn

Example of chain

Using readFileCps as above.

1// write version of readFileCps
2const writeFileCps = (file, content) => (onRes, onErr) =>  
3  require('fs').writeFile(file, content, (err, message) => {
4    err ? onErr(err) : onRes(message)
5  })
6
7const copy = chain(
8  // function that returns CPS function
9  text => writeFileCps('target.txt', text)
10)(
11  readFileCps('source.txt')  // CPS function
12)
13// or as method
14const copy = CPS(readFileCps('source.txt'))
15  .chain(text => writeFileCps('target.txt', text))
16// or with pipeline operator
17const copy = pipeline(readFileCps('source.txt'))(
18  chain(text => writeFileCps('target.txt', text))
19)
20
21// copy is a CPS function, call it with any callback
22copy((err, data) => err 
23  ? console.error(err) 
24  : console.log(data)
25) // => file content is capitalized and printed

filter(...predicates)(cpsFunction)

1// these are equivalent
2filter(pred1, pred2, ...)(cpsFn)
3CPS(cpsFn).filter(pred1, pred2, ...)
4pipeline(cpsFn)(filter(pred1, pred2, ...))

where each predn is the nth predicate function used to filter output from the nth callback of cpsFn.

Result of applying filter

New CPS function that calls its nth callback cbn(x1, x2, ...) whenever (x1, x2, ...) is an output from the nth callback of cpsFun and

1predn(x1, x2, ...) == true

Example of filter

Using readFileCps and writeFileCps as above.

1// only copy text if it is not empty
2const copyNotEmpty = CPS(readFileCps('source.txt'))
3  .filter(text => text.length > 0)
4  .chain(text => writeFileCps('target.txt', text))
5
6// copyNotEmpty is CPS function, call with any callback
7copyNotEmpty(err => console.error(err))

scan(...initStates)(...reducers)(cpsFunction)

Similar to reduce, except that each accumulated values is passed into its callback whenever there is new output.

1// these are equivalent
2scan(ini1, init2, ...)(red1, red2, ...)(cpsFn)
3(cpsFn).scan(ini1, init2, ...)(red1, red2, ...)
4pipeline(cpsFn)(scan(ini1, init2, ...)(red1, red2, ...))

where each redn is a reducer and init is the initial accumulated value.

1// compute new accumulator value from the old one 
2// and the tuple of current values (y1, y2, ...)
3const redn = (acc, y1, y2, ...) => ... 

Result of applying scan

New CPS function whose function whose outputs are the accumulated values. For each output (y1, y2, ...) from the nth callback, the nth reducer redn is used to compute the new acculated value redn(acc, y1, y2, ...), where acc starts with the nth initial state initStaten, similar to reduce.

Example of scan

1// CPS function with 2 callbacks, clicking on one
2// of the buttons sends '1' into respective callback
3const getVotes = (onUpvote, onDownvote) => {
4  upvoteButton.addEventListener('click', 
5    ev => onUpvote(1)
6  )
7  downvoteButton.addEventListener('click', 
8    ev => onDownvote(1)
9  )  
10}
11// count numbers of up- and downvotes and 
12// pass into respective callbacks
13const countVotes = CPS(getVotes)
14  .scan(0,0)(
15    ([up, down], upvote) => [up + upvote, down], 
16    ([up, down], downvote) => [up, down + downvote]
17   )
18
19// countVotes is CPS function that we can call 
20// with any callback
21countVotes(
22  upvotes => console.log('Total upvotes: ', upvotes),
23  downvotes => console.log('Total downvotes: ', downvotes),
24)

ap(...cpsFunctions)(cpsFunction)

See running CPS functions in parallel. Inspired by the Applicative Functor interface, see e.g. https://funkia.github.io/jabz/#ap

lift(...functions)(cpsFunction) (TODO)

See lifting functions of multiple arguments The "sister" of ap, apply functions with multiple arguments to outputs of CPS functions running in parallel, derived from ap, see e.g. https://funkia.github.io/jabz/#lift

merge(...cpsFunctions) (TODO)

See CPS.merge. Merge outputs from multiple CPS functions, separately in each callback. E.g. separately merge results and errors from multiple promises running in parallel.

More details?

This README.md is kept minimal to reduce the package size. For more human introduction, motivation, use cases and other details, please see DOCUMENTATION.

License

MIT © Dmitri Zaitsev