af-conditionals Library

Status of Project

Purpose

The af-conditionals library was created to provide a consistent interface from which to create dynamic comparisons, conditional expressions, logical expressions, and operations. Through the interface, expressions can be defined externally to the application code and dynamically executed.

Standard Calling Conventions

All Comparisons, Conditionals, Logicals, and Operators expose the object class and a variable named after the class with the word Instance appended, but starting with a lowercase letter. For example: IsString is exposed as is isStringInstance. The isStringInstance variable is declared with a let so you may subclass the object and then use your version of your class throughout your application easily. Additionally, we expose a function that implements the testing for the class, for example, IsString has a exposed function isString that calls isStringInstance.test(). (This is described in the Release Notes for v0.2.0.)

Comparisons

The Comparison class provides a compare and test public methods.

The compare method takes two values and compares them returning:

• -1 (negative numeral one) when the first value is less than the second value
• 0 (zero) when the first value is equal to the second value
• +1 (positive numeral one) when the first value is greater than the second value

When possible the compare method will compare the values using strict equals (===). When the values are not of the same type, compare will use coerced equality (==).

The test uses the compare method to get the result and then compare that result to an expected result that you supply. test returns:

• true if the returned result and expected result are equal
• false otherwise

Supplied Comparisons are:

• Equal - determines if two values are equal
• GreaterThan - determines if the first value is greater than the second value
• GreaterThanOrEqual - determines if the first value is greater than or equal to the second value
• LessThan - determines if the first value is less than the second value
• LessThanOrEqual - determines if the first value is less than or equal to the second value

Comparisons use shorthand calling function names instead of exposed functions of equal, greaterThan, etc... eq, gt, gte, lt, lte are exposed.

strict

Both the compare and test methods take an optional parameter strict that defaults to true. When the comparison is between two string values the strict parameter is used to indicate if the comparison should be case-insensitive or not. When strict is true the comparison is made taking case into account (i.e. capital letters are greater than lowercase letters).

Conditionals

This library defines a Conditional class that is then subclassed to create standard conditional checks.

Supplied Conditionals are:

• IsArray - determines if a value is an Array (and Array only)
• IsEmpty - determines if a value is empty
  • A string is empty if it is equal to ""
  • A number is empty if it is NaN
  • A boolean is empty if it is false
• IsFalsey - loosely tests if a value is false (coerced using !)
• IsFunction - determines if a value is a Function
• IsNumber - determines if a value is a number
• IsObject - determines if a value is an object. This excludes Array's and Function's
• IsString - determines if a value is a string
• IsTruthy - loosely tests if a value is true (coerced using !!)
• IsUndefinedOrNull - determines if a value is undefined or null
• IsUsable - inverts IsUndefinedOrNull to determine if a value is "usable"

The majority of the conditionals use typeof to determine if a value is of a particular type or not and use non-coerced equality to test the type.

Logicals

Supplied Logicals are:

• And - performs a boolean AND on the supplied operands (can be more than a single test)
• Or - performs a boolean OR on the supplied operands (can be more than a single test)

Operators

Supplied Operators are:

• Not - performs a boolean NOT on the supplied value (which will be cast into truthy or falsey)

Support

To share your comments, provide suggestions, or raise issues, create an issue.

Changelog

v0.1.0 - Initial Release - 2018-08-21

This is the initial alpha release version. The code has been thoroughly tested with 100% coverage. However, the packaging is still under development so a NPM module has not been published.

v0.2.0 - New Signature Format - 2018-11-10

• This release changes the calling methods from using XXXX.test() methods to hiding that test within an exported function from which the classes are actually used. For example:

In v0.1.0, you would write code like this:

if (isUsable.test(someVar)) {
  console.log('It is usable');
}

Starting in v0.2.0, you can now simply say:

if (isUsable(someVar)) {
  console.log('It is usable');
}

• The assert method was moved out of base classes and made very generic across all Comparisons, Conditionals, and Logicals.

v0.3.0 - Intro two new functions - 2018-11-18

• Added IsFalsey and IsTruthy Conditionals.

v0.3.1 - ???

• Updated Conditionals to use type-detect package.
• Updated dependent packages (dev dependencies)
• Updated tsconfig.json to be cleaner (both master src and tests), and to produce js output in dist instead of build
• Updated package.json for NPM publishing

v1.0.0 - Release - 2019-02-18

• Official 1.0.0 release version

v1.1.0 - Update build/tsconfig - 2019-07-20

• Updated dependencies
• Updated package.json for consistent scripts across af-XXXX libraries
• removed .vscode folder
• Updated README.md

Fixes

• v1.1.1 - Updated dependencies / refactored code - 2020-01-04

v1.2.0 - Optimizations / dependencies - 2020-04-22

• Optimize IsArray.test
• Update dependencies

v1.3.0 - Build and process overhaul

• Replace TSlint with ESlint
• Introduce Prettier
• Reformat all code with Prettier
• Update app dependencies to the latest versions, update configs as needed
• Update package.json scripts to better support a consistent build process and better commits

Fixes

• v1.3.1 - Corrected two typos in publish.yml
• v1.3.2 - Fix types key in publish.yml - correct release processing