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.

Implementation ​

View Source Code
ts
import { assert } from '../function/assert';
import { ge } from './ge';
import { gt } from './gt';
import { isDefined } from './isDefined';
import { isEmpty } from './isEmpty';
import { isEqual } from './isEqual';
import { isEven } from './isEven';
import { isMatch } from './isMatch';
import { isNegative } from './isNegative';
import { isNil } from './isNil';
import { isOdd } from './isOdd';
import { isPositive } from './isPositive';
import { isRegex } from './isRegex';
import { isWithin } from './isWithin';
import { isZero } from './isZero';
import { le } from './le';
import { lt } from './lt';
import { type ArgType, typeOf } from './typeOf';

type isType =
  | ArgType
  | 'defined'
  | 'empty'
  | 'eq'
  | 'even'
  | 'ge'
  | 'gt'
  | 'le'
  | 'lt'
  | 'match'
  | 'ne'
  | 'negative'
  | 'nil'
  | 'odd'
  | 'positive'
  | 'regex'
  | 'within'
  | 'zero';

/**
 * @description
 * Checks if the value type of argument.
 *
 * @example
 * ```ts
 * is('array', []);
 * is('boolean', true);
 * is('date', new Date());
 * is('defined', 123);
 * is('empty', []);
 * is('even', 2);
 * is('function', () => {});
 * is('match', { a: 1, b: 2 }, { a: 1 });
 * is('nan', Number.NaN);
 * is('negative', -123);
 * is('nil', null);
 * is('null', null);
 * is('number', 123);
 * is('object', {});
 * is('odd', 3);
 * is('positive', 123);
 * is('string', 'hello');
 * is('symbol', Symbol('test'));
 * is('regex', /abc/);
 * is('string', 'hello world');
 * is('undefined', undefined);
 * is('within', 1, 2, 3);
 * is('zero', 0);
 * is('eq', [1, 2, 3], [1, 2, 3]);
 * is('ne', [1, 2, 3], [1, 2]);
 * is('ge', 5, 5);
 * is('gt', 5, 3);
 * is('le', 5, 5);
 * is('lt', 3, 5);
 * ```
 *
 * @param type - The type to check against.
 * @param args - The argument to be checked.
 *
 * @returns `true` if the value is of the specified type, else `false`.
 */
export function is(type: 'within', ...args: Parameters<typeof isWithin>): boolean;
export function is(type: 'eq', ...args: Parameters<typeof isEqual>): boolean;
export function is(type: 'ne', ...args: Parameters<typeof isEqual>): boolean;
export function is(type: 'gt', ...args: Parameters<typeof gt>): boolean;
export function is(type: 'ge', ...args: Parameters<typeof ge>): boolean;
export function is(type: 'lt', ...args: Parameters<typeof lt>): boolean;
export function is(type: 'le', ...args: Parameters<typeof le>): boolean;
export function is(type: 'match', ...args: Parameters<typeof isMatch>): boolean;
export function is(type: 'empty', ...args: Parameters<typeof isEmpty>): boolean;
export function is(type: 'array', arg: unknown): arg is Array<unknown>;
export function is(type: 'string', arg: unknown): arg is string;
export function is(type: 'number', arg: unknown): arg is number;
export function is(type: 'object', arg: unknown): arg is object;
export function is(type: 'nil', arg: unknown): arg is null | undefined;
export function is(type: 'primitive', arg: unknown): arg is string | number | boolean;
export function is(type: isType, arg: unknown): boolean;
export function is(type: string, arg: unknown): boolean {
  assert(Boolean(type), 'Type must be provided', { args: { type }, type: Error });

  const compare = {
    defined: isDefined,
    empty: isEmpty,
    eq: (args: Parameters<typeof isEqual>) => isEqual(...args),
    even: isEven,
    ge: (args: Parameters<typeof ge>) => ge(...args),
    gt: (args: Parameters<typeof gt>) => gt(...args),
    le: (args: Parameters<typeof le>) => le(...args),
    lt: (args: Parameters<typeof lt>) => lt(...args),
    match: (args: Parameters<typeof isMatch>) => isMatch(...args),
    ne: (args: Parameters<typeof isEqual>) => !isEqual(...args),
    negative: isNegative,
    nil: isNil,
    odd: isOdd,
    positive: isPositive,
    regex: isRegex,
    within: (args: Parameters<typeof isWithin>) => isWithin(...args),
    zero: isZero,
  };

  return compare[type as keyof typeof compare]?.(arg) ?? typeOf(arg) === type;
}

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 ​