@effectful/cc

Runtime library for multi-prompt delimited continuations with EffectfulJS.

From v2 the library uses @effectful/debugger for implementation of control effects. This makes the transpilation to be heavier, but many useful features are enabled by default. Such us:

• code is debuggable in VSCode using effectfuk.debugger extension
• continuations and all the functions are serializable
• and more

It's also now only supports one-layer JavaScript (no overriding of async/await and generators syntaxes at the moment). I simply don't need them, but they are quite simple to add if needed. Let me know if you need them.

Async/await and genrators are still available, though, with the same semantics as in JavaScript. However, it's not clear, why you would need them in the presence of delimited continuations.

API documentation

Description

It is the most generic effects API implementation, and it can be converted into any other one. These include JavaScript built-in effects - state, async/await, generators, exception, etc.

Delimited continuations effect is also, probably, the most complex to understand. I'm trying to explain it using exceptions analogy here. It is like an exception, with execution may be resumed from throw point several times.

This library is multi-prompt one. Prompt is a kind of a label. Imagine JavaScript has labeled try-catch and throw statements. The label is specified as another argument of throw and only catch block with the same label catches it. All the others just rethrow to their upper level. In the library the prompt(label) function is created using CC.newPrompt function.

Function CC.pushPrompt is a replacement of try block. Its first argument is a prompt object (specifying which exceptions) to catch, and the second argument is a try body where an exception (with same prompt) may raise. Note, there is no catch block, it is specified with throw replacement.

The throw replacement is CC.withSubCont. Its first argument is a prompt object again, specifying which CC.pushPrompt should catch it. If there are a few CC.pushPrompt with the same prompt, the innermost will be selected. The second argument is a catch block. Unlike try-catch where the block is adjunct of try statement, here it is specified along with throw replacement. Also, there is no exception object.

The catch block is a function taking continuation object. It captures execution path from CC.withSubCont (throw) to CC.pushPrompt (try). In JavaScript exceptions, it is simply dropped. This object allows resuming execution from the CC.withSubCont (throw) several times.

If the captured continuation never executed the library works precisely like exceptions. First executes catch block and continues after try if the catch block doesn't throw anything else.

The continuation object received in CC.withSubCont may be called anywhere using CC.pushSubCont function. Its first argument is the continuation object captured in CC.withSubCont.

When CC.withSubCont is called, like for throw statement, the execution control is suspended (aborted). When CC.pushSubCont is called the execution is resumed with a resulting value of CC.withSubCont on the resume is a result of the second argument of CC.pushSubCont.

After the resumed execution control reaches CC.pushPrompt (try statement), if not interrupted by anything else, it continues from the CC.pushSubCont call. The call result is a result of CC.pushPrompt block.

These four functions are the base. The others are defined using them.

When resuming continuations several times, if they change some variable values, the change is visible on next run by default. However, the continuation object may be cloned in whatever way your program needs (shallow/deep) to restore variables values. Alternatively, it may be Proxy based copy-on-write for better performance.

The continuations are serializable using @effectful/serialization.

Usage

npm install @effectful/cc
npm install --save-dev @effectful/js

Note, if you need to use eval or Function constructor, --save "@effectful/js" too.

Import into your code, and use babel-plugin-macro to transform the whole file:

import ctrl from "@effectful/js/macro";
import * as CC from "@effectful/cc";

WARNING: the babel plugin for the transpilation must run in a separate pass in the preset, for example:

{
  "passPerPreset": true,
  "presets": [
    "some-other-preset",
    {
      "plugins": ["babel-plugin-macro"]
    }
  ]
}

See @effectful/js for more details about alternative ways to transpile the code.

Since the transpiler currently doesn't support import and thus must be pre-transpiled into CommonJS with @babel/plugin-transform-modules-commonjs. And babel-plugin-macros ignores require if it isn't in variable declarations, we cannot use a shorthand syntax with just import. It must be default import (or some variable declaration for CommonJS require), with the actual imported value never used.

Also @babel/plugin-transform-typescript may remove this import since it isn't used. To avoid this pass { "onlyRemoveTypeImports": true } argument.

References

The library implements interface from A Monadic Framework for Delimited Continuations paper.

License

Distributed under the terms of the The MIT License (MIT).