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
Install / Import
Deno
import * as runExclusive from "https://deno.land/x/run_exclusive/mod.ts";Other javascript runtime environnement:
$ npm install --save run-exclusiveimport * as runExclusive from "run-exclusive";Import from HTML, with CDN
Expose a global (wider browser support):
<script src="//unpkg.com/run-exclusive/bundle.min.js"></script>
<script>
runExclusive.build(...);
</script>You can import a specific version unpkg.com
Try it now
Thanks to Stackblitz you can try this lib within your browser like if you where in VSCode.
Table of content
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>;