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

    1.0.6 • Public • Published

    lazy-boolean-evaluator

    This library allows for boolean operations over asynchronous functions which return a Promise. This uses short circuit evaluation. Useful in situations where performing certain asynchronous actions is conditional on the results of previous asynchronus actions, and thus can be used to optimize by doing the least amount of work necessary.

    Background

    Programming languages will evaluate boolean expressions to a single boolean: true && false == false. In the case of the R-Query tool, we needed to take this concept and apply it to async functions which return promises of booleans. This is how that tool is able to filter through input and files based on certain conditions. The below code snippet exemplifies the requirement.

    //Normal
    const normalBool = true && false || false;
    console.log(normalBool); // false
    
    //Promise based (ugly and verbose as is here)
    const promiseBool = (await Promise.resolve(true)) && (await Promise.resolve(false)) || (await Promise.resolve(false));
    console.log(promiseBool); //false
    
    //Function which returns promise based (even worse)
    const funcPromiseBool = (await (() => Promise.resolve(true))()) && (await (() => Promise.resolve(false))()) || (await (() => Promise.resolve(false))());
    console.log(funcPromiseBool); //false
    
    /*
    * When the number of boolean variables is dynamic, instead of static like above, the problem is worse.
    */

    In order to be able to implement the R-Query tool without making the codebase immediately unmaintainable, this functionality was created in a separate, generic, and reusable library: lazy-boolean-evaluator.

    Using this Library

    This library provides an interface which resembles normal boolean expressions. The following are the basic tokens:

    • AAND: token which indicates a boolean AND operation (AsyncAND)
    • AOR: token which indicates a boolean OR operation (AsyncOR)
    • AXOR: token which indicates a boolean XOR operation (AsyncXOR)
    • ANOT: token which indicates the value immediately to the right should be negated (pair must exist in its own array)
    • ANAND: token which indicates a boolean ANAND operation (AsyncNand)
    • ANOR: token which indicates a boolean ANOR operation (AsyncNor)
    • TrueA: function which resolves to true: () => Promise.resolve(true);
    • FalseA: function which resolves to false: () => Promise.resolve(false);

    Async boolean expressions can be created by combining these into an array;

    //asyncFunc = a function which returns a promise of a boolean (including TrueA and FalseA)
    //asyncOperator = AAND or AOR
    const phrase = [asyncFunc, ...[asyncOperator, asyncFunc]];
    
    const examplePhrase = [FalseA, AOR, TrueA, AAND, TrueA];

    Phrases can also be nested to any level:

    const phrase = [asyncFunc, AAND, [asyncFunc, AOR, asyncFunc], AOR, [asyncFunc, AAND, [asyncFunc, AOR, asyncFunc]]];

    The async functions are lazily evaluated and short circuted:

    lazyExample = [asyncFuncThatReturnsTrue, AOR, asyncFuncThatReturnsFalse];
    //asyncFuncThatReturnsFalse is never called : lazyExample = true
    
    lazyExample = [asyncFuncThatReturnsTrue, AAND, asyncFuncThatReturnsFalse];
    //asyncFuncThatReturnsFalse is called : lazyExample = false

    The following is an example which shows a normal boolean phrase, then its async counterpart.

    //Normal
    const nResult = true && false || true;
    
    //Lazy
    const phrase = [TrueA, AAND, FalseA, AOR, TrueA];
    const lResult = await new AsyncBooleanEvaluator().evaluate(phrase);
    
    //Practical example
    const minorExpensiveTask = async () => { /* do some task */; return isSuccessful;};
    const majorExpensiveTask = async () => { /* do some task */; return isSuccessful;};
    
    const execution = [minorExpensiveTask, AOR, majorExpensiveTask];
    //evaluate the execution phrase, only call majorExpensiveTask if the minorExpensiveTask failed
    const isSuccessful = await new AsyncBooleanEvaluator().evaluate(execution);
    //that will run through one or both, depending upon the output of the first, then return true if either were successful

    Keywords

    none

    Install

    npm i lazy-boolean-evaluator

    DownloadsWeekly Downloads

    1

    Version

    1.0.6

    License

    ISC

    Unpacked Size

    59.3 kB

    Total Files

    29

    Last publish

    Collaborators

    • brandonqdixon