⚡🔒 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

``typescript
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:
`bash


One second..

Hello World

One second

Hello World
`

Group of mutually run exclusive functions

`typescript
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:
`bash


One second..

Hello World 1

One second

Hello World 2
`

Install / Import

Deno

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

Other javascript runtime environnement:

`bash
$ npm install --save run-exclusive
`
`typescript
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.

!Screenshot 2020-02-14 at 12 48 04

__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.

``typescript
let alphabet= "";

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

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:

``typescript
import * as runExclusive from "run-exclusive";

let alphabet= "";

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

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.
!Screenshot 2020-02-08 at 15 42 09

createGroupRef()

To share a unique lock among a group of functions.

``typescript
import * as runExclusive from "run-exclusive";

let alphabet= "";

const groupSpelling= runExclusive.createGroupRef();

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

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

alphabet+=letter.toUpperCase();

}
);

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

await new Promise(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.

``typescript

class Student {

public alphabet= "";

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

await new Promise(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.

``typescript

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.

$3

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].

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

$3

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].
`typescript
export declare function cancelAllQueuedCalls(
runExclusiveFunction: Function,
classInstanceObject?: Object
): number;
`


$3

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].
`typescript
export declare function isRunning(
runExclusiveFunction: Function,
classInstanceObject?: Object
): boolean;
`

$3

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].

``typescript
export declare function getPrComplete(
runExclusiveFunction: Function,
classInstanceObject?: Object
): Promise;
```