Vielzeug

Appearance

VersionSize

is ​

The is utility is a highly flexible and unified type-checking engine. It acts as a single entry point for nearly all type guards and comparison helpers available in the toolkit, supporting a wide range of string-based predicates and constructor-based checks.

Source Code ​

View Source Code
ts
import { isArray } from './isArray';
import { isBoolean } from './isBoolean';
import { isDate } from './isDate';
import { isDefined } from './isDefined';
import { isEmpty } from './isEmpty';
import { isEqual } from './isEqual';
import { isEven } from './isEven';
import { isFunction } from './isFunction';
import { isMatch } from './isMatch';
import { isNegative } from './isNegative';
import { isNil } from './isNil';
import { isNumber } from './isNumber';
import { isObject } from './isObject';
import { isOdd } from './isOdd';
import { isPositive } from './isPositive';
import { isPrimitive } from './isPrimitive';
import { isPromise } from './isPromise';
import { isRegex } from './isRegex';
import { isString } from './isString';
import { isWithin } from './isWithin';
import { isZero } from './isZero';
import { typeOf } from './typeOf';

/**
 * Namespace of type-checking and comparison utilities.
 *
 * @example
 * ```ts
 * is.string('hello');          // true
 * is.array([1, 2, 3]);         // true
 * is.nil(null);                // true
 * is.nil(undefined);           // true
 * is.equal([1, 2], [1, 2]);    // true
 * is.positive(5);              // true
 * is.within(3, 1, 5);          // true
 * is.match({ a: 1, b: 2 }, { a: 1 }); // true
 * is.ge(5, 5);                 // true
 * is.gt(5, 3);                 // true
 * is.typeOf('hello');          // 'string'
 * ```
 */
export const is = {
  /** `true` if value is an array */
  array: isArray,
  /** `true` if value is a boolean */
  boolean: isBoolean,
  /** `true` if value is a valid Date */
  date: isDate,
  /** `true` if value is not `undefined` */
  defined: isDefined,
  /** `true` if value is null, undefined, `''`, `[]`, or `{}` */
  empty: isEmpty,
  /** Deep equality check */
  equal: isEqual,
  /** `true` if value is an even integer */
  even: isEven,
  /** `true` if value is a function */
  fn: isFunction,
  /** `true` if a >= b (numbers only) */
  ge: (a: number, b: number) => a >= b,
  /** `true` if a > b (numbers only) */
  gt: (a: number, b: number) => a > b,
  /** `true` if a <= b (numbers only) */
  le: (a: number, b: number) => a <= b,
  /** `true` if a < b (numbers only) */
  lt: (a: number, b: number) => a < b,
  /** Partial deep-match: `true` if `object` contains all of `source`'s properties */
  match: isMatch,
  /** `true` if value is a negative number */
  negative: isNegative,
  /** `true` if value is null or undefined */
  nil: isNil,
  /** `true` if value is a number (excluding NaN) */
  number: isNumber,
  /** `true` if value is a plain object */
  object: isObject,
  /** `true` if value is an odd integer */
  odd: isOdd,
  /** `true` if value is a positive number */
  positive: isPositive,
  /** `true` if value is a string, number, or boolean */
  primitive: isPrimitive,
  /** `true` if value is a Promise */
  promise: isPromise,
  /** `true` if value is a RegExp */
  regex: isRegex,
  /** `true` if value is a string */
  string: isString,
  /** Returns the runtime type tag of the value */
  typeOf,
  /** `true` if value is within [min, max] (inclusive) */
  within: isWithin,
  /** `true` if value is exactly 0 */
  zero: isZero,
};

Features ​

  • Isomorphic: Works in both Browser and Node.js.
  • Unified API: One function to rule them all — primitives, objects, comparisons, and ranges.
  • Predicate Strings: Use intuitive strings like 'empty', 'even', 'nil', or 'match'.
  • Constructor Support: Check against native constructors like Array, Date, or custom classes.
  • Type Guard: Provides type narrowing for standard types when using string predicates.

API ​

ts
function is(type: string | Function, value: unknown, ...args: any[]): boolean;

TIP

Supports many type checks: 'string', 'number', 'array', 'object', 'nil', 'empty', 'match', 'within', 'gt', 'ge', 'lt', 'le', 'even', 'odd', 'positive', 'negative', 'zero', 'defined', 'promise', 'function', 'boolean', 'date', 'regex', 'primitive', 'equal'

Parameters ​

  • type: A string identifier for the check, or a constructor (e.g., Date).
  • ...args: The values to be checked or compared.

Returns ​

  • true if the condition is met; otherwise, false.

Examples ​

String-based Type Checks ​

ts
import { is } from '@vielzeug/toolkit';

is('array', []); // true
is('string', 'hello'); // true
is('nil', null); // true
is('primitive', true); // true

Using Predicates & Comparisons ​

ts
import { is } from '@vielzeug/toolkit';

is('empty', {}); // true
is('even', 42); // true
is('within', 5, 0, 10); // true
is('gt', 10, 5); // true
is('match', { a: 1 }, { a: 1 }); // true

Constructor-based Checks ​

ts
import { is } from '@vielzeug/toolkit';

is(new Date(), Date); // true
is([], Array); // true

class MyClass {}
is(new MyClass(), MyClass); // true

Implementation Notes ​

  • Performance-optimized registry of predicates.
  • String predicates are case-insensitive.
  • Throws an error if an invalid or unknown type is provided.
  • Internally dispatches to specific utilities like isEmpty, isWithin, isArray, etc.

See Also ​