Skip to content

Latest commit

 

History

History
1177 lines (811 loc) · 19.3 KB

README.md

File metadata and controls

1177 lines (811 loc) · 19.3 KB
Raw

🦕 dis

Originally by Sindre Sorhus for Node, ported by Nicholas Berlette for Deno.

Usage

import * as is from "https://deno.land/x/[email protected]/mod.ts";

Type Checking

is("🦕");
// 'string'

is(new Map());
// 'Map'

is.number(6);
// true

Assertions

Assertions perform the same type checks, but throw an error if the type does not match.

import { assert } from "https://deno.land/x/[email protected]/mod.ts";

assert.string(2);
// => Error: Expected value which is `string`, received value of type `number`.

Assertions with TypeScript

import { assert } from "https://deno.land/x/[email protected]/mod.ts";

assert.string(foo);
// `foo` is now typed as a `string`.

Highlights

API

is(value)

Attempts to ascertain the type of the value it receives. Accepts only one argument.

is("🦕");
// 'string'

is(new Map());
// 'Map'

Returns: the type of value.

is.{method}

All the below methods accept a value and returns a boolean for whether the value is of the desired type.

is.number(6);
// true

is.undefined(true);
// false

Primitives

Note: Primitives are lowercase and object types are camelCase.

Examples of Primitives
  • 'undefined'
  • 'null'
  • 'string'
  • 'symbol'
  • 'Array'
  • 'Function'
  • 'Object'

Note: It will throw an error if you try to feed it object-wrapped primitives, as that's a bad practice (e.g. new String('foo'))

API Methods

undefined

is.undefined(value);

null

is.null(value);

Note: TypeScript users must use .null_() because of a TypeScript naming limitation.

string

is.string(value);

number

is.number(value);

Note: is.number(NaN) returns false. This intentionally deviates from typeof behavior to increase user-friendliness of is type checks.

boolean

is.boolean(value);

symbol

is.symbol(value);

bigint

is.bigint(value);

Builtins

API Methods

array

is.array(value, assertion?)

Returns: true if value is an array and all of its items match the assertion (if provided).

Examples

is.array(value); // Validate `value` is an array.
is.array(value, is.number); // Validate `value` is an array and all of its items are numbers.

function

is.function(value);

Note: TypeScript users must use .function_() because of a TypeScript naming limitation.

buffer

is.buffer(value);

blob

is.blob(value);

object

is.object(value);

Important: Keep in mind that functions are objects too.

numericString

is.numericString(value);

Returns: true for a string that represents a number satisfying is.number, for example, '42' and '-8.3'.

Important: 'NaN' returns false, but 'Infinity' and '-Infinity' return true.

regExp

is.regExp(value);

date

is.date(value);

error

is.error(value);

nativePromise

is.nativePromise(value);

promise

is.promise(value);

Returns: true for any object with a .then() and .catch() method. Prefer this one over .nativePromise() as you usually want to allow userland promise implementations too.

generator

is.generator(value);

Returns: true for any object that implements its own .next() and .throw() methods and has a function definition for Symbol.iterator.

generatorFunction

is.generatorFunction(value);

asyncFunction

is.asyncFunction(value);

Returns: true for any async function that can be called with the await operator.

Examples

is.asyncFunction(async () => {});
// true

is.asyncFunction(() => {});
// false

asyncGenerator

is.asyncGenerator(value);

Examples

is.asyncGenerator(
  (async function* () {
    yield 4;
  })(),
);
// true

is.asyncGenerator(
  (function* () {
    yield 4;
  })(),
);
// false

asyncGeneratorFunction

is.asyncGeneratorFunction(value);

Examples

is.asyncGeneratorFunction(async function* () {
  yield 4;
});
// true

is.asyncGeneratorFunction(function* () {
  yield 4;
});
// false

boundFunction

is.boundFunction(value);

Returns: true for any bound function.

is.boundFunction(() => {});
// true

is.boundFunction(function () {}.bind(null));
// true

is.boundFunction(function () {});
// false

map

is.map(value);

set

is.set(value);

weakMap

is.weakMap(value);

weakSet

is.weakSet(value);

weakRef

is.weakRef(value);

TypedArrays

API Methods

int8Array

is.int8Array(value);

uint8Array

is.uint8Array(value);

uint8ClampedArray

is.uint8ClampedArray(value);

int16Array

is.int16Array(value);

uint16Array

is.uint16Array(value);

int32Array

is.int32Array(value);

uint32Array

is.uint32Array(value);

float32Array

is.float32Array(value);

float64Array

is.float64Array(value);

bigInt64Array

is.bigInt64Array(value);

bigUint64Array

is.bigUint64Array(value);

Structured Data

API Methods

arrayBuffer

is.arrayBuffer(value);

sharedArrayBuffer

is.sharedArrayBuffer(value);

dataView

is.dataView(value);

enumCase

is.enumCase(value, enum)

Note: TypeScript-only. Returns true if value is a member of enum.

enum Direction {
  Ascending = "ascending",
  Descending = "descending",
}
is.enumCase("ascending", Direction);
// true
is.enumCase("other", Direction);
// false

Emptiness

API Methods

emptyString

is.emptyString(value);

Returns: true if the value is a string and the .length is 0.

emptyStringOrWhitespace

is.emptyStringOrWhitespace(value);

Returns: true if is.emptyString(value) or if it's a string that is all whitespace.

nonEmptyString

is.nonEmptyString(value);

Returns: true if the value is a string and the .length is more than 0.

nonEmptyStringAndNotWhitespace

is.nonEmptyStringAndNotWhitespace(value);

Returns: true if the value is a string that is not empty and not whitespace.

const values = ["property1", "", null, "property2", "    ", undefined];
values.filter(is.nonEmptyStringAndNotWhitespace);
// ['property1', 'property2']

emptyArray

is.emptyArray(value);

Returns: true if the value is an Array and the .length is 0.

nonEmptyArray

is.nonEmptyArray(value);

Returns: true if the value is an Array and the .length is more than 0.

emptyObject

is.emptyObject(value);

Returns: true if the value is an Object and Object.keys(value).length is 0.

Note: Object.keys returns only own enumerable properties. Hence something like this can happen:

const object1 = {};
Object.defineProperty(object1, "property1", {
  value: 42,
  writable: true,
  enumerable: false,
  configurable: true,
});
is.emptyObject(object1);
// true

nonEmptyObject

is.nonEmptyObject(value);

Returns: true if the value is an Object and Object.keys(value).length is more than 0.

emptySet

is.emptySet(value);

Returns: true if the value is a Set and the .size is 0.

nonEmptySet

is.nonEmptySet(Value);

Returns: true if the value is a Set and the .size is more than 0.

emptyMap

is.emptyMap(value);

Returns: true if the value is a Map and the .size is 0.

nonEmptyMap

is.nonEmptyMap(value);

Returns: true if the value is a Map and the .size is more than 0.

Everything Else

API Methods

directInstanceOf

is.directInstanceOf(value, class)

Returns: true if value is a direct instance of class.

is.directInstanceOf(new Error(), Error);
// true
class UnicornError extends Error {}
is.directInstanceOf(new UnicornError(), Error);
// false

urlInstance

is.urlInstance(value);

Returns: true if value is an instance of the URL class.

const url = new URL("https://example.com");
is.urlInstance(url);
// true

urlString

is.urlString(value);

Returns: true if value is a URL string.

Note: this only does basic checking using the URL class constructor.

const url = "https://example.com";
is.urlString(url);
// true
is.urlString(new URL(url));
// false

truthy

is.truthy(value);

Returns: true for all values that evaluate to true in a boolean context:

is.truthy("🦕");
// true
is.truthy(undefined);
// false

falsy

is.falsy(value);

Returns: true if value is one of: false, 0, '', null, undefined, NaN.

NaN

is.nan(value);

nullOrUndefined

is.nullOrUndefined(value);

primitive

is.primitive(value);

JavaScript primitives are as follows: null, undefined, string, number, boolean, symbol.

integer

is.integer(value);

safeInteger

is.safeInteger(value);

Returns: true if value is a safe integer.

plainObject

is.plainObject(value);

An object is plain if it's created by either {}, new Object(), or Object.create(null).

iterable

is.iterable(value);

asyncIterable

is.asyncIterable(value);

class

is.class(value);

Returns: true for instances created by a class.

Note: TypeScript users must use .class_() because of a TypeScript naming limitation.

typedArray

is.typedArray(value);

arrayLike

is.arrayLike(value);

A value is array-like if it is not a function and has a value.length that is a safe integer greater than or equal to 0.

is.arrayLike(document.forms);
// true

function foo() {
  is.arrayLike(arguments);
  // true
}
foo();

inRange

is.inRange(value, range);

Check if value (number) is in the given range. The range is an array of two values, lower bound and upper bound, in no specific order.

is.inRange(3, [0, 5]);
is.inRange(3, [5, 0]);
is.inRange(0, [-2, 2]);

inRange

is.inRange(value, upperBound);

Check if value (number) is in the range of 0 to upperBound.

is.inRange(3, 10);

domElement

is.domElement(value);

Returns: true if value is a DOM Element.

nodeStream

is.nodeStream(value);

Returns: true if value is a Node.js stream.

import fs from "node:fs";
is.nodeStream(fs.createReadStream("unicorn.png"));
// true

observable

is.observable(value);

Returns: true if value is an Observable.

import { Observable } from "rxjs";
is.observable(new Observable());
// true

infinite

is.infinite(value);

Check if value is Infinity or -Infinity.

evenInteger

is.evenInteger(value);

Returns: true if value is an even integer.

oddInteger

is.oddInteger(value);

Returns: true if value is an odd integer.

propertyKey

is.propertyKey(value);

Returns: true if value can be used as an object property key (either string, number, or symbol).

formData

is.formData(value);

Returns: true if value is an instance of the FormData class.

const data = new FormData();
is.formData(data);
// true

urlSearchParams

is.urlSearchParams(value);

Returns: true if value is an instance of the URLSearchParams class.

const searchParams = new URLSearchParams();
is.urlSearchParams(searchParams);
// true

any

is.any(predicate | predicate[], ...values)

Using a single predicate argument, returns true if any of the input values returns true in the predicate:

is.any(is.string, {}, true, "🦕");
// true
is.any(is.boolean, "denosaurs", [], new Map());
// false

Using an array of predicate[], returns true if any of the input values returns true for any of the predicates provided in an array:

is.any([is.string, is.number], {}, true, "🦕");
// true
is.any([is.boolean, is.number], "denosaurs", [], new Map());
// false

all

is.all(predicate, ...values);

Returns: true if all of the input values returns true in the predicate:

is.all(is.object, {}, new Map(), new Set());
// true
is.all(is.string, "🦕", [], "denosaurs");
// false

Type Guards

When using is together with TypeScript, type guards are being used extensively to infer the correct type inside if-else statements.

Examples 
import is from "https://deno.land/x/[email protected]/mod.ts";
const padLeft = (value: string, padding: string | number) => {
  if (is.number(padding)) {
    // `padding` is typed as `number`
    return Array(padding + 1).join(" ") + value;
  }

  if (is.string(padding)) {
    // `padding` is typed as `string`
    return padding + value;
  }

  throw new TypeError(
    `Expected 'padding' to be of type 'string' or 'number', got '${
      is(padding)
    }'.`,
  );
};
padLeft("🦕", 3);
// '   🦕'

padLeft("🦕", "🌈");
// '🌈🦕'

Type Assertions

The type guards are also available as type assertions, which throw an error for unexpected types. It is a convenient one-line version of the often repetitive "if-not-expected-type-throw" pattern.

Examples 
import { assert } from "https://deno.land/x/[email protected]/mod.ts";

const handleMovieRatingApiResponse = (response: unknown) => {
  assert.plainObject(response);
  // `response` is now typed as a plain `object` with `unknown` properties.

  assert.number(response.rating);
  // `response.rating` is now typed as a `number`.

  assert.string(response.title);
  // `response.title` is now typed as a `string`.

  return `${response.title} (${response.rating * 10})`;
};
handleMovieRatingApiResponse({ rating: 0.87, title: "The Matrix" });
// 'The Matrix (8.7)'

// This throws an error.
handleMovieRatingApiResponse({ rating: "🦕" });

Generic type parameters

More Information

The type guards and type assertions are aware of generic type parameters, such as Promise<T> and Map<Key, Value>. The default is unknown for most cases, since is cannot check them at runtime. If the generic type is known at compile-time, either implicitly (inferred) or explicitly (provided), is propagates the type so it can be used later.

Use generic type parameters with caution. They are only checked by the TypeScript compiler, and not checked by is at runtime. This can lead to unexpected behavior, where the generic type is assumed at compile-time, but actually is something completely different at runtime. It is best to use unknown (default) and type-check the value of the generic type parameter at runtime with is or assert.

Examples 
import { assert } from "https://deno.land/x/[email protected]/mod.ts";
async function badNumberAssumption(input: unknown) {
  // Bad assumption about the generic type parameter fools the compile-time type system.
  assert.promise<number>(input);
  // `input` is a `Promise` but only assumed to be `Promise<number>`.
  const resolved = await input;
  // `resolved` is typed as `number` but was not actually checked at runtime.
  // Multiplication will return NaN if the input promise did not actually contain a number.
  return 2 * resolved;
}
async function goodNumberAssertion(input: unknown) {
  assert.promise(input);
  // `input` is typed as `Promise<unknown>`
  const resolved = await input;
  // `resolved` is typed as `unknown`
  assert.number(resolved);
  // `resolved` is typed as `number`
  // Uses runtime checks so only numbers will reach the multiplication.
  return 2 * resolved;
}
badNumberAssumption(Promise.resolve("An unexpected string"));
// NaN
// This correctly throws an error because of the unexpected string value.
goodNumberAssertion(Promise.resolve("An unexpected string"));

Frequently Asked Questions

Why yet another type checking module?

There are hundreds of type checking modules on npm, unfortunately, I couldn't find any that fit my needs:

  • Includes both type methods and ability to get the type
  • Types of primitives returned as lowercase and object types as camelcase
  • Covers all built-ins
  • Unsurprising behavior
  • Well-maintained
  • Comprehensive test suite

For the ones I found, pick 3 of these.

The most common mistakes I noticed in these modules was using instanceof for type checking, forgetting that functions are objects, and omitting symbol as a primitive.

Why not just use `instanceof` instead of this package?

instanceof does not work correctly for all types and it does not work across realms. Examples of realms are iframes, windows, web workers, and the vm module in Node.js.

MIT License. Originally by Sindre Sorhus. Ported by Nicholas Berlette for Deno.