Typedetection NPM

typedetection

A collection of helper methods for easing up type-checking. Typed with flow and built with ES-modules. Well-tested and with a teeny tiny footprint.

Installation

Simply do: npm install typedetection.

What is it?

This simply sports a few helper methods for detecting the type of elements such as isString() and isObject(). It's much like lodash's lang methods, except it comes at a much smaller size, is Flow-typed and supports ES-modules.

Changelog:

v0.13:

BREAKING: Typescript support and new file structure:
- typedetection.legacy.js is the new "main" script. There is also a typedetection.legacy.min.js that comes minified.
- typedetection.js is the new "jsnext:main" script. This one will load if you have configured your build tool (e.g. rollup or webpack) to load modules using newer language features such as ES-modules. There is also a typedetection.min.js version that comes minified.
- typedetection.ts is written in Typescript and will be loaded by default if you import this library in Typescript projects.
- flow.js is written with Flow typings and can be imported from typedetection/flow. There is also automatic generation of *.js.flow files now for all supported versions.

v0.12:

isUTypedObject() used Object.values() which is experimental and wasn't supported in Safari. Changed implementation to a cross-browser compatible solution.

v0.11:

Added a new method: isUTypedObject.

v0.09:

Fixed a bug in the isEventListenable method.

v0.07:

Added a new method: isPrimitivePrototype(item: any): boolean.

v0.06:

Fixed a typing bug.

v0.05:

Added two new methods: isUTypedArray(items: any, U: Class<any>): boolean and isInstanceOf(prototype: Class<any>, item: any): boolean.
Added tests for new methods in v0.04 and v0.05. A total of 560 tests is now written.

v0.04:

Added three new methods: isSameType(x: any, y: any): boolean, isTypedArray(items: any): boolean and getTypeof(item: any): string.

v0.01:

First release. 457 passing tests makes me comfortable that you can start using this now!

Usage

Import it in your project like this:

import {isString, isBoolean, ...} from "typedetection"        // Transpiled to ES5 with (UMD)
// or

import {isString, isBoolean, ...} from "typedetection/typed"  // With Flow typings and ES-modules;
// or

import {isString, isBoolean, ...} from "typedetection/native" // With ES-modules.

Methods

isBoolean(item: any): boolean

Returns true if the given item is a boolean. That means that it has a value of true or false.

isString(item: any): boolean

Returns true if the given item is a string. Handles string primitives as well as String objects. (which means that new String("hi") will return true).

isNumber(item: any): boolean

Returns true if the given item is a number. That means that it is an integer, double or float. NaN will not return true.

isArray(item: any): boolean

Returns true if the given item is an Array. Based upon Array.isArray which means that NodeList and HTMLCollection will return false.

isObject(item: any): boolean

Returns true if the given item is a plain Javascript object (such as: {a: "foo", b: "bar"}). Won't return true for any other non-primitive types.

isPrimitive(item: any): boolean

Returns true if the given item is a primitive value. Primitive values are non-object types such as number, boolean and undefined. Be aware that null will return true, even though it has a typeof value of object. This is because it is considered an official bug and language quirk and should be a primitive value.

isPrimitivePrototype(item: any): boolean

Returns true if the given item is a prototype for a primitive type. Values that will return true is String, Number, Boolean and Symbol.

isFunction(item: any): boolean

Returns true if the given item is a function. Because class objects is functions too in JavaScript, classes as well as functions will return true.

isElement(item: any): boolean

Returns true if the given item is an HTMLElement or an element that extends it.

isEventListenable(item: any): boolean

Returns true if the given item implements the EventTarget interface. Does not return true for EventTargets such as XMLHttpRequest and AudioContext even though they implement the interface. This is because more often than not, the expected behavior would be for the function to return false in that case.

isSet(item: any): boolean

Returns true if the given item is a Set collection.

isMap(item: any): boolean

Returns true if the given item is a Map collection.

isSameType(x: any, y: any): boolean

Returns true if the given two items has the same type.

getTypeOf(item: any): string

Returns a string representation of the item type. Works like the native 'typeof' except that it returns the values you'd expect. For instance, an array returns 'array' instead of 'object'.

isInstanceOf(prototype: Class<any>, item: any): boolean

Checks if the given item is an instance of the given prototype. Works for primitive types too. So, for instance, a valid call could be: isInstanceOf(Number, 12);

isTypedArray(items: any): boolean

Returns true if given argument is an array of values with the same type. Returns true for empty arrays too.

isUTypedArray(items: any, U: Class<any>): boolean

Checks if the given item is an array where all values are of the given type U. U is a prototype such as Number, Array or String or event custom classes. So for instance, a valid call would be: isUTypedArray([12, 14], Number).

isUTypedObject(item: any, U: Class<any>): boolean

Checks if the given item is an object where all values are of the given type U. U is a prototype such as Number, Array or String or event custom classes. So for instance, a valid call would be: isUTypedObject({a: 1, b: 2}, Number).

isEqual(x: any, y: any): boolean

Returns true if the given items are equal, either referential or if all of their values are identical.

Important

If You are considering replacing your lodash imports with this library, you need to be aware of the following:

isObject() does not behave like lodash. Lodash detects if the provided item is an Object-type where this library checks if it is a proper Javascript object (like this: {a: "foo", b: "bar"}). Instead you can use the isPrimitive() method.
isEqual() may behave differently than lodash' implementation. This library will check if their referential equality is truthy first and otherwise deep check.