TypeScript icon, indicating that this package has built-in type declarations

    0.0.2 • Public • Published

    State machines

    This is a research prototype. Please see the main GitHub page.

    A library for building and testing applications using state machines in TypeScript/JavaScript.

    $ npm install state-machines


    The library provide the following key features:

    • TypeScript and JavaScript APIs for building applications using state machines.
    • A testing runtime that uses systematic concurrency testing to control all asynchrony and explore unexpected interleavings, exposing concurrency heisenbugs before release.

    State machines

    The state machines API enables developers to elegantly express workflows that contain asynchronous operations using state machines. The "states" of a machine are just functions that are executed; they return an object indicating what should happen next, such as transitioning to another state.

    For example, the following JavaScript state machine lists the files and directories in the given input directory:

    exports.SMLoadDirInfo = class {
      // The initial state.
      stateInit(input) {
        // Store the input (a path) to a field/property for later. = input[0];
        // Transition to (i.e. execute) `stateReaddir`.
      stateReaddir() {
        // Create another state machine that will get the files in 
        // ``.
        const m =,;
        // Execute the state machine and transition to `stateProcessReaddir` on 
        // success, or to `stateFailure` on failure.
        return, this.stateProcessReaddir, this.stateFailure);
      stateProcessReaddir(files) {
        // Create several machines to get information on each file.
        const stats = =>, f));
        // Execute all the machines, transitioning to `stateProcessStats` once all
        // machines succeed, or to `stateFailure` as soon as *any* machine fails.
        return, this.stateProcessStats, this.stateFailure);
      stateProcessStats(stats) {
        // Process the file information.
        // Complete this state machine with `stats` as the result.
        // The code that executed this machine will receive the result.
      stateFailure(ex) {
        // Complete this state machine with an error.


    The library also supports thorough testing of different interleavings. For example, the following TypeScript test harness aims to test what happens when a file is renamed at the same time as executing the above state machine:

    // Renames `file.txt` to `file2.txt`.
    const smRenamer = sm.create(new SMRenamer(/*...omitted...*/), undefined);
    // Read our (virtual) `test_directory`, which contains `file.txt`.
    const o = new SMLoadDirInfo();
    const smLoadDir = sm.create(o, ["test_directory"]);
    const dir = await sm.execute(smLoadDir);

    If the file is renamed between the calls to readdir and stat, an error will occur. This is very unlikely to happen when running normally. However, when using the testing runtime, the error is seen every time because all possible interleavings are explored.

    The state machine library is built on top of typed actors.


    Please see the main GitHub page


    npm i state-machines

    DownloadsWeekly Downloads






    Last publish


    • paulthomson