run-exclusive

⚡🔒 Generate functions that do not allow parallel executions 🔒 ⚡

---

Let you create functions that enforce no more than one execution happens at the same time.
If the function is called again while there is already an execution ongoing the new call will be queued and executed once all the queued calls have completed.

This is a higher-level approach to the problem addressed by DirtyHairy/async-mutex.

Suitable for any JS runtime env (deno, node, old browser, react-native ...)

• ✅ It is both a Deno and an NPM module.
• ✅ Lightweight, no dependency.
• ✅ No polyfills needed, the NPM module is transpiled down to ES3

Examples

Basic example

import * as runExclusive from "run-exclusive";

const f= runExclusive.build(async ()=> {

    await new Promise(resolve=> setTimeout(resolve, 1000));

    console.log("Hello world");

});

f();
f();

Result:

# One second..
Hello World
# One second
Hello World

Group of mutually run exclusive functions

import * as runExclusive from "run-exclusive";

const groupRef= runExclusive.createGroupRef();

const f1= runExclusive.build(groupRef, async ()=> {

    await new Promise(resolve=> setTimeout(resolve, 1000));

    console.log("Hello world 1");

});

const f2= runExclusive.build(groupRef, async ()=> {

    await new Promise(resolve=> setTimeout(resolve, 1000));

    console.log("Hello world 2");

});

f1();
f2();

Result:

# One second..
Hello World 1
# One second
Hello World 2

Install / Import

Deno

import * as runExclusive from "https://deno.land/x/run_exclusive/mod.ts";

Other javascript runtime environnement:

$ npm install --save run-exclusive

import * as runExclusive from "run-exclusive";

Try it now

Thanks to Stackblitz you can try this lib within your browser like if you where in VSCode.

Run the example

Table of content

• Examples
  • Basic example
  • Group of mutually run exclusive functions
• Install / Import
  • Deno
  • Other javascript runtime environnement:
  • Import from HTML, with CDN
• Try it now
• Table of content
• Documentation
  • build()
  • createGroupRef()
  • buildMethod()
  • buildCb() and buildMethodCb()
  • Queued calls
    • getQueuedCallCount()
    • cancelAllQueuedCalls()
    • isRunning()
    • getPrComplete()

Documentation

build()

Let us compare regular functions with run-exclusive functions.

let alphabet= "";

//This function wait a random time then append a letter to alphabet.
async function spell(letter: string): Promise<string>{

    await new Promise(
        resolve=> setTimeout(
            resolve, 
            Math.random()*100
        )
    );

    alphabet+=letter;

    return alphabet;

}

spell("a");
spell("b");
spell("c").then( message => console.log(message)); 
//We cant predict what will be printed to the console,
//it can be "c", "ca", "ac", "cb", "bc", "cab", "cba", "bac", "bca", "acb" or "abc"

Now the same example using run-exclusive:

import * as runExclusive from "run-exclusive";

let alphabet= "";

const spell= runExclusive.build(
    async (letter: string): Promise<string> => {

        await new Promise(
            resolve=>setTimeout(
                resolve, 
                Math.random()*100
            )
        ); 

        alphabet+=letter;

        return alphabet;

    }
);

spell("a");
spell("b");
spell("c").then( message => console.log(message)); // Always prints "abc"

The types definition of the function passed as argument are conserved.

createGroupRef()

To share a unique lock among a group of functions.

import * as runExclusive from "run-exclusive";

let alphabet= "";

const groupSpelling= runExclusive.createGroupRef();

const spellUpperCase= runExclusive.build(groupSpelling
    async (letter: string) => {

        await new Promise<void>(resolve=> setTimeout(resolve, Math.random()*100));

        alphabet+=letter.toUpperCase();

    }
);

const spellLowerCase= runExclusive.build(groupSpelling
    async (letter: string) => {

        await new Promise<void>(resolve=> setTimeout(resolve, Math.random()*100));

        alphabet+=letter.toLowerCase();

    }
);

spell("a");
spellUpperCase("b");
spell("c").then(()=> console.log(alphabet)); //prints "aBc".

buildMethod()

If you define run exclusive class methods chances are you want the lock to be restricted to the class's object instance.
This is what buildMethod()is for.

class Student {

    public alphabet= "";

    public spell= runExclusive.buildMethod(
       async (letter: string) => {

            await new Promise<void>(resolve=> setTimeout(resolve, 1000));

            this.alphabet+=letter.toLowerCase();

        }
    );

}

const alice= new Student();
const bob= new Student();

alice.spell("A");
bob.spell("a");
alice.spell("B");
bob.spell("b");
alice.spell("C").then( ()=> console.log(alice.alphabet)); //prints after 3s: "ABC"
bob.spell("c").then( ()=> console.log(bob.alphabet)); //prints after 3s: "abc"

buildCb() and buildMethodCb()

buildCb() is the pending of build() for creating run exclusive functions that complete by invoking a callback. (Instead of resolving a promise).

The only valid reason to use this instead of build() is to be able to retrieve the result synchronously.

WARNING: If you make the callback optional the argument before it cannot be a function.
Be aware that the compiler won't warn you against it.
Example: (getLetter: ()=> string, callback?: (message: string)=> voidA) => {..}
is NOT a valid function to pass to buildCb() or buildMethodCb(). Thanks @AnyhowStep

WARNING: The function should never throw as the exception wont be catchable.

let alphabet= "";

const spell= runExclusive.buildCb(
    (letter: string, callback?: (message: string)=> void) => {

        setTimeout(()=>{

            alphabet+= letter;

            /*
            Callback must always be called, event if the user 
            does not provide one, it is the only way for the module
            to know that the function has completed it's execution.
            You can assume that the callback function is not undefined.
            To tell if the user has provided à callback you can access (callback as any).hasCallback;
            */
            callback!(alphabet);

        }, Math.rand()*100);

    }
};

spell("a");
spell("b");
spell("c", message => console.log(message)); // prints "abc"

NOTE: runExclusive.buildMethodCb() also available.

Queued calls

It is possible to check, for a given run exclusive function, if there is currently an ongoing execution and how many calls are queued. It is also possible to cancel the queued calls.

getQueuedCallCount()

Get the number of queued call of a run-exclusive function. Note that if you call a runExclusive function and call this directly after it will return 0 as there is one function call execution ongoing but 0 queued.

The classInstanceObject parameter is to provide only for the run-exclusive function created with 'buildMethod[Cb].

export declare function getQueuedCallCount(
    runExclusiveFunction: Function, 
    classInstanceObject?: Object
): number;

cancelAllQueuedCalls()

Cancel all queued calls of a run-exclusive function. Note that the current running call will not be cancelled.

The classInstanceObject parameter is to provide only for the run-exclusive function created with 'buildMethod[Cb].

export declare function cancelAllQueuedCalls(
    runExclusiveFunction: Function, 
    classInstanceObject?: Object
): number;

isRunning()

Tell if a run-exclusive function has an instance of it's call currently being performed.

The classInstanceObject parameter is to provide only for the run-exclusive function created with 'buildMethod[Cb].

export declare function isRunning(
    runExclusiveFunction: Function, 
    classInstanceObject?: Object
): boolean;

getPrComplete()

Return a promise that resolve when all the current queued call of a runExclusive functions have completed.
The classInstanceObject parameter is to provide only for the run-exclusive function created with 'buildMethod[Cb].

export declare function getPrComplete(
    runExclusiveFunction: Function, 
    classInstanceObject?: Object
): Promise<void>;