js-heuristics

heuristics

Useful heuristics, type checks, and validation helpers for JavaScript

js-heuristics is a library of useful heuristics, type checks, and validation helpers for JavaScript. Instead of repeatedly checking types, evaluating whether or not an API response is null (or indeed an object, only entirely empty), you can depend on this tested, consistent library API to get the job done.

using this lib

Table of Contents

• Supported Environments
• Installation + Usage
• Documentation / API
  • Type Checks
  • Validators
  • Contracts
  • Iterators

Supported Environments

heuristics currently supports UMD, CommonJS (node versions >= 10), and ESM build-targets. Is your preferred build not supported? Open an issue!

Installation + Usage

npm install js-heuristics
# OR
yarn add js-heuristics

Commonjs:

const { isObject } = require('js-heuristics');

console.log(isObject({})); // true

ESM:

import { isObject } from 'js-heuristics';

Documentation / Core API

Type Checks

isFunction (arg: any): boolean

evaluate whether the provided argument is a function

Example

import { isFunction } from 'js-heuristics';

var fn = () => ({});

var t = isFunction(fn);

console.log(t); // true

isGenerator (arg: any): boolean

evaluate whether the provided argument is a generator function

Example

import { isGenerator } from 'js-heuristics';

var gen = function* () { yield true; };

var t = isGenerator(gen);

console.log(t); // true

isAsyncFunction (arg: any): boolean

evaluate whether the provided argument is an async function

Example

import { isAsyncFunction } from 'js-heuristics';

var fn = async function () { ... };

var t = isAsyncFunction(fn);

console.log(t); // true

isAnonymousFunction (arg: any): boolean

evaluate whether the provided argument is an anonymous function

Example

import { isAnonymousFunction } from 'js-heuristics';

var fn = function () { ... };

var t = isAnonymousFunction(fn);

console.log(t); // true

isRegularFunction (arg: any): boolean

evaluate whether the provided argument is a named, synchronous function

Example

import { isRegularFunction } from 'js-heuristics';

var fn = function name () { ... };

var t = isRegularFunction(fn);

console.log(t); // true

isString (arg: any): boolean

evaluate whether the provided argument is a string

Example

import { isFunction } from 'js-heuristics';

var fn = () => ({});

var t = isFunction(fn);

console.log(t); // true

isBoolean (arg: any) boolean

evaluate whether the provided argument is a Boolean

Example

import { isBoolean } from 'js-heuristics';

...
if (isBoolean(true)) // true

isError (arg: any): boolean

evaluate whether the provided argument is an Error object

Example

import { isError } from 'js-heuristics';

...
var result = await fetchData();
...
if (isError(result)) this.error = true;
else this.data = result.data;

isObject (arg: any): boolean

evaluate whether the provided argument is an object

Example

import { isObject } from 'js-heuristics';

const r = corneliusCardewIsDaBeezKnees();

if (isObject(r)) ...

isArray (arg: any): boolean

evaluate whether the provided argument is an array

Example

import { isArray } from 'js-heuristics';

var notAnArr = '';

console.log(isArray(notAnArr)); // false

isNumber (arg: any): boolean

evaluate whether the provided argument is a number Note Will return false for NaN and single element Arrays (see: toString gotchas)

Example

import { isNumber } from 'js-heuristics';

console.log(isNumber(9)); // true

console.log(isNumber(NaN)); // false

isFloat (arg: any): boolean

evaluate whether the provided argument is a floating point number

Example

import { isFloat } from 'js-heuristics';

console.log(isFloat(9.1)); // true

console.log(isFloat(1)); // false

Validators

not (arg: any): boolean

convert any expression or value to a negated boolean

Example

import { not } from 'js-heuristics';

if (not(obj)) ...

if (not(bool)) ...

if (not(expr)) ...

notEmpty (arg: (string|array|object)): boolean

evaluate whether the provided argument is not empty Note Will return undefined for non array, object, or string arguments

Example

import { notEmpty } from 'js-heuristics';

if (notEmpty(obj)) ...

objNotEmpty (arg: any): boolean

evaluate whether the provided object is not empty (no keys)

Example

import { objNotEmpty } from 'js-heuristics';

if (objNotEmpty(obj)) ...

objNotEmptyDeep (arg: any): boolean

evaluate whether the provided object is not empty, no matter how nested

Note Object's values are not null, NaN, or undefined

Example

import { objNotEmptyDeep } from 'js-heuristics';

var o = {
  a: {
    b: {
      c: {
        d: 1
      }
    }
  }
}

if (objNotEmptyDeep(o)) ... // true

notNullOrUndefined (arg: any): boolean

Explicitly determine if given value is not null or undefined

Example

import { notNullOrUndefined } from 'js-heuristics';

if (notNullOrUndefined(o)) ...

notInPrototype (target: object, prop: string): boolean

Determine if a property does not exist on an object or its prototype chain

Example

import { notInPrototype } from 'js-heuristics';

var proto = { foo: 'foo' };
var obj = Object.create(proto);

if (notInPrototype(obj, 'foo')) ... // false

if (notInPrototype(obj, 'bar')) ... // true

Contracts

contract (predicate: Function, message?: string): Function

Generate a predicate-bound contract; either returns true or throws a violation

Example

import { contract, isObject } from 'js-heuristics';

const mustBeObject = contract(isObject);

var o = {};
var a = [];

if (mustBeObject(o)) ... // true

if (mustBeObject(a)) ... // throws


const contractWithMessage = contract(isObject, 'Must be an object');

try {
  contractWithMessage('str');
} catch ({ message }) {
  console.log(message); // 'Must be an object'
}

testForEach (...predicates: Function[]): boolean

Generate a reducer that enforces all provided predicates on a given argument

Example

import { testForEach, isObject } from 'js-heuristics';

function hasData () { ... }

const isApiData = testForEach(isObject, hasData);

if (isApiData(response)) ...

Iterators

range (start: (number|string), end: (number|string)): IterableIterator

Generate an iterable range

Example

import { range } from 'js-heuristics';

const enumValue = 10;

const enumChar = 'E';

if (enumValue in range(1, 20)) ... // true

if (enumValue in range(1, 5)) ... // false

if (enumChar in range('A', 'z')) ... // true

if (enumChar in range('a', 'd')) ... // false