@bluemarblepayroll/logicality
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    Logicality

    Build Status

    A common problem that many frameworks have is the ability to give developers an expressive intermediary scripting language or DSL. Logicality helps solve this problem by providing a simple boolean expression evaluator. That way, your developers can create simple scripts for dynamically resolving boolean values such as:

    • a
    • b
    • a && b
    • a || b
    • a && b || c
    • (a && b) || (c && d)
    • (a && b) || (c && (d || e && f))

    Credit

    Deep inspiration was taken from this set of articles. Here, the author gives details around the theory and practical implementation of creating a basic language processor and compiler.

    Installation

    This library could be consumed as either a pure TypeScript library or as its trans-compiled ES2015 JavaScript counterpart.

    To install through NPM:

    npm install --save @bluemarblepayroll/logicality
    

    To install through Yarn:

    yarn add @bluemarblepayroll/logicality
    

    Examples

    A simple object-based example.

    Consider a case where some content should be displayed if it is marked as visible or if the user is an administrator. You can express this as:

    visible || admin
    

    Now you can bind and evaluate this expression against passed in objects:

    import { evaluate } from '@bluemarblepayroll/logicality';
    
    let record = { visible: false, admin: true };
    let expression = 'visible || admin';
    
    let visible =  evaluate(expression, record); // resolves to true.
    

    What is truthy and falsy?

    Logicality uses the same rules for deciding which values are true or false as JavaScript. As a reminder, JavaScript considers the following six things to be false:

    • false
    • undefined
    • null
    • NaN (not a number)
    • 0 (the number, not the string)
    • "" (the empty string)

    Everything evaluates to true.

    Plugging in Immutable.JS

    The above example works just fine using Logic's default object value resolver, but you can also pass in a custom function that will serve as resolver. That way you could use dot notation for value resolution. For example:

    let record = Immutable.fromJS({ visible: false, settings: { admin: true } });
    let expression = 'visible || settings.admin';
    
    let resolver = (value, input) => input && value && !!input.get(value.toString().split('.'));
    
    let visible =  evaluate(expression, record, resolver); // resolves to true.
    

    Contributing

    Development Environment Configuration

    Basic steps to take to get this repository compiling:

    1. Install Node.js (check package.json for versions supported.)
    2. Install Yarn package manager (npm install -g yarn)
    3. Clone the repository (git clone git@github.com:bluemarblepayroll/logicality.git)
    4. Navigate to the root folder (cd logicality)
    5. Install dependencies (yarn)

    Compiling

    To compile the TypeScript source to JavaScript, run:

    yarn run build
    

    You can also run the TypeScript compiler in watch mode with (start developing):

    yarn run start
    

    Running Tests

    To execute the test suite run:

    yarn run test
    

    Linting

    yarn run lint
    

    Publishing

    Note: ensure you have proper authorization before trying to publish new versions.

    After code changes have successfully gone through the Pull Request review process then the following steps should be followed for publishing new versions:

    1. Merge Pull Request into master
    2. Update package.json version number
    3. Update CHANGELOG.md
    4. Push master to remote and ensure CI builds master successfully
    5. Build the project locally: yarn run build
    6. Perform a dry run: npm publish --access public --dry-run. Inspect packaging, ensure all files (including dist) are included.
    7. Publish package to NPM: npm publish --access public
    8. Tag master with new version: git tag <version>
    9. Push tags remotely: git push origin --tags

    License

    This project is MIT Licensed.

    Install

    npm i @bluemarblepayroll/logicality

    DownloadsWeekly Downloads

    1

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    69.8 kB

    Total Files

    58

    Last publish

    Collaborators

    • jbos
    • roeyb
    • normalocity
    • ckattnerpcty