Zu Deutsch wechseln

@type-check/guards

Straightforward to use (one example):

import {isFloat} from "@type-check/guards";

isFloat(1337); // false

Table of contents: runtime type checks and guards

• What is @type-check/guards?
• Why should I use @type-check/guards?
  • Browsersupport
  • Performance & efficiency
  • Runtime safety
  • Design-time testing
  • API consistency
• How to use @type-check/guards?
  • Prerequisites
  • Installation
  • package.json
  • tsconfig.json
  • Import
    • Local function imports (Node.js)
    • Local object import (Node.js)
    • Global function imports (Node.js)
    • Browser import & CDN (jsDelivr)
  • Usage
  • Examples
  • Example with tree-shakable functions
  • Example with object export
• Exported TypeScript types
• Functions / Methods
  • Type determination
  • Type checks
    • Basic and primitive types
    • Numeric checks
    • Objects and collections
    • Specialized instances and logic
• The @js-augment ecosystem
• The @type-check ecosystem
• Other helpful tools
• Support & Error Reporting
• Contributing

What is @type-check/guards?

@type-check/guards provides powerful, safety-oriented runtime type checks according to 2026 best practices, written in TypeScript by Roland Milto.

This package is designed for professional TypeScript, Node.js, and modern browser environments, offering precise and efficient type-checking functions with continuous development.

The module exports an object containing all type-checking functions while also providing tree-shakable exports for each function. Additionally, types within arrays can be validated.

Why should I use @type-check/guards?

Unlike heavy frameworks like Chai, Jest, or Vitest, which are primarily designed for isolated testing environments, @type-check/guards was developed for maximum efficiency in production (runtime) and the highest precision during design-time testing.

Browsersupport

@type-check/guards supports all modern browsers, including Chrome, Edge, Firefox, Opera, and Safari.

Maximum performance and resource efficiency

• Minimal footprint: Through consistent tree-shaking and zero dependencies, the bundle size remains minimal. This saves memory (RAM) and reduces loading times.

• CPU optimization: The guards (such as isOfType) internally use "fast-path" shortcuts for primitive types. This avoids unnecessary function calls and processing load, even with millions of validations per second.

• Simple syntax: No more complex assertion chains. A clear, functional API (e.g., isString(value)) ensures more readable code and faster development.

Runtime safety and design-time power

This package protects the application during execution from corrupt data while offering enormous benefits during development:

• Strict validation: JavaScript design flaws are natively corrected (e.g., typeof null === 'object' or typeof NaN === 'number'). The guards check what you mean, not what JavaScript claims.

• Content validation: While testing frameworks often only check if an array exists, functions like areStrings or areIntegers efficiently validate the entire content – deep and secure.

• Intelligent type guards: Every function is a true TypeScript Type Guard. Once a check passes, TypeScript automatically recognizes the type in the following code block. This replaces unsafe type casting (as string) with real logic.

// Without type guards:
function process(value: unknown) {
  if (typeof value === 'string') {
    (value as string).toUpperCase(); // Manual casting often required
  }
}

// With type guards:
if (isString(value)) {
  value.toUpperCase(); // TypeScript recognizes the type immediately
}

Excellent for design-time testing

Although optimized for runtime, @type-check/guards is the perfect addition to your test suites:

• Use the same valid checking mechanisms in your unit tests as in your production logic.
• No complex configuration of tests is required – the guards work everywhere: Node.js, browser, edge runtimes, or serverless functions.

API consistency

To minimize errors during comparisons, @type-check/guards follows a strict camelCase strategy. All strings returned by getTypeOf, as well as the type identifiers in isOfType, are consistently lowercase (e.g., "nan" instead of "NaN", "bigint" instead of "BigInt").

How to use @type-check/guards?

Prerequisites

The package is designed as a native ES module (ESM) and supports all modern environments from ES2020+ (Node.js 16+, current browsers, and edge runtimes) to ensure maximum efficiency without unnecessary polyfills.

Installation

To install @type-check/guards, use the following command in your terminal:

npm install @type-check/guards

package.json

Ensure that @type-check/guards is included in your package.json dependencies and always use the latest version:

{
	"dependencies": {
		"@type-check/guards": "*"
	}
}

You can leave the asterisk (*) to ensure that the latest version is installed. However, it is recommended that you specify an exact version, as any errors in the library could directly affect your project.

tsconfig.json

Since @type-check/guards is exported as an ESM module, it is necessary to adjust the moduleResolution option in the tsconfig.json file to avoid error messages from the TypeScript compiler:

{
	"compilerOptions": {
		"moduleResolution": "NodeNext"
	}
}

Import

Local function imports

Individual import of specific functions (Tree-Shaking):

import {isInteger} from "@type-check/guards";

isInteger(1337); // true

Local object import

Importing the type-check object:

import {type} from "@type-check/guards/as-object";

type.isInteger(42); // true

Using a different name or alias:

import {type as values} from "@type-check/guards/as-object";

values.areIntegers([42, 1337]); // true

Global function imports

Use @type-check/guards as a global import for all functions, so you only need to include the libary once in your project:

import '@type-check/guards/register-global';

isPlainObject({}); // true

If your IDE does not automatically recognize the types, you can manually register them in tsconfig.json:

{
	"compilerOptions": {
		"types": [
			"@type-check/guards/register-global"
		]
	}
}

Browser import

If the bundle is to be hosted locally, the minified bundle can be found at dist/index.min.mjs in the package directory.

For rapid prototyping or direct browser usage (without a build step), you can load @type-check/guards via the Delivery Network (CDN) jsDelivr or unpkg:

<script type="module">
  import {isFloat, areStrings} from 'https://cdn.jsdelivr.net/npm/@type-check/guards/dist/index.min.mjs';

  console.log(isFloat(1337)); // false
 console.log(areStrings(["TS", "JS"])); // true
</script>

For unpkg use: https://unpkg.com/@type-check/guards/dist/index.min.mjs

Usage

All functions or methods take one argument and return a boolean value, except the functions or methods isEqual, isOfType, isOneOfType, areEqual, areOfType, and areOneOfType, which take two arguments.

The first argument is always the value to be checked, the second argument is the expected type. For __OneOfType functions, the types must be provided in an array.

import {areStrings, getTypeOf, isBigInt, isInteger, isOfType} from "@type-check/guards";

console.log(getTypeOf(42)); // string 'number'

console.log(isOfType("Written by Roland Milto", "string")); // true

console.log(isInteger(42)); // true

console.log(isBigInt(42));  // false

console.log(areStrings(["Made", "by", "Roland", "Milto"])); // true

Examples

Example data

const user1 = {
  id: 1337,
  name: "Roland Milto",
  email: "[email protected]",
  isManager: true,
  locations: [
    "Berlin",
    "Hamburg",
    "Munich"
  ]
}

Example with tree-shakable functions:

import {areStrings, isBoolean, isInteger, isPlainObject, isString} from "@type-check/guards";

function checkAccountDetails(options) {
  if (!isPlainObject(options))
    throw new TypeError("options must be a plain object");

  if (!isInteger(options.id))
    throw new TypeError("options.id must be an integer");

  if (isString(options.name))
    console.log("Account:", options.name ?? "No name provided");

  if (isString(options.email))
    console.log("Contact Email:", options.email ?? "No email provided");

  console.log("Manager:", options.isManager ? "Yes" : "No");

  // Arrays are supported:
  if (areStrings(options.locations)) {
    for (const location of options.locations) {
      console.log("Location:", location);
    }
  }
}

checkAccountDetails(user1);

Example with object export:

import {type} from "@type-check/guards/as-object";

function checkAccountDetails(options) {
  if (!type.isPlainObject(options))
    throw new TypeError("options must be a plain object");

  if (!type.isInteger(options.id))
    throw new TypeError("options.id must be an integer");

  if (type.isString(options.name))
    console.log("Account:", options.name ?? "No name provided");

  if (type.isString(options.email))
    console.log("Contact Email:", options.email ?? "No email provided");

  console.log("Manager:", options.isManager ? "Yes" : "No");

  // Also arrays are supported:
  if (type.areStrings(options.locations)) {
    for (const location of options.locations) {
      console.log("Location:", location);
    }
  }
}

checkAccountDetails(user1);

Exported TypeScript types

For seamless integration into your TypeScript projects, @type-check/guards exports helpful union types. You can use these to type your own variables or ensure your logic only uses the type identifiers supported by this library.

Importing types

import type {DataType, Primitive, NonPrimitive, NumberType} from "@type-check/guards";

• DataType: The master union of Primitive and NonPrimitive. It covers all identifiers that can be returned by getTypeOf.

• Primitive: Includes all basic data types such as string, number, boolean, bigInt, symbol, integer, float, nan, null, and undefined.

• NonPrimitive: Includes complex structures like array, object, date, error, function, map, set, promise, regExp, stream", buffer, weakMap", and weakSet.

• NumericType: A specialized selection for numerical classifications (bigInt, binary, decimal, float, hexadecimal, integer, number, and octal).

Functions / Methods

All functions are designed to provide precise results and can be used either via the type object or as an individual import.

Type determination

getTypeOf(value) returns a string describing the type of the given value (always camelCase).

Type checks

All methods return a boolean value. The Single Value Check column validates an individual value, while the Check Array Elements column ensures that every element in the provided array meets the condition.

Basic and primitive types

| Single Value Check | Check Array Elements | Description | |:----------------------------------------------------------|:------------------------------------------------------------|:----------------------------------| | isBoolean(value) | areBooleans(array) | Checks for boolean. | | isFalse(value) | areFalse(array) | Checks for strictly false. | | isNull(value) | areNull(array) | Checks for null. | | isNullOrUndefined(value) | areNullOrUndefined(array) | Checks for null or undefined. | | isPrimitive(value) | arePrimitives(array) | Checks for primitive type. | | isString(value) | areStrings(array) | Checks for string. | | isSymbol(value) | areSymbols(array) | Checks for symbol. | | isTrue(value) | areTrue(array) | Checks for strictly true. | | isUndefined(value) | areUndefined(array) | Checks for undefined. |

Numeric checks

| Single Value Check | Check Array Elements | Description | |:--------------------------------------------------|:------------------------------------------------------|:---------------------------------------------------------| | isBigInt(value) | areBigInts(array) | Checks for bigint. | | isBinary(value) | areBinaries(array) | Checks for binary notation (string, optional 0b/0B). | | isDecimal(value) | areDecimals(array) | Checks for decimal number as string. | | isFinite(value) | areFinite(array) | Checks for finite number. | | isFloat(value) | areFloats(array) | Checks for floating-point (non-integer). | | isHexadecimal(value) | areHexadecimals(array) | Checks for hexadecimal notation (string with 0x/0X). | | isInteger(value) | areIntegers(array) | Checks for integer. | | isNaN(value) | areNaNs(array) | Checks for NaN. | | isNumber(value) | areNumbers(array) | Checks for number. | | isNumeric | areNumerics(array) | Checks for numeric values e.g. float, octal etc. | | isOctal(value) | areOctals(array) | Checks for octal notation (string with 0o/0O). |

Objects and collections

| Single Value Check | Check Array Elements | Description | |:--------------------------------------------------------------|:------------------------------------------------------------------|:------------------------------------------| | isArray(value) | areArrays(array) | Checks for array. | | isEnumeration(value, option) | areEnumerations(array, option) | Checks if it is an enum value. | | isEnumerationObject(value) | areEnumerationObjects(array) | Checks if it is an enum object. | | isFilledArray(value) | areFilledArrays(array) | Checks for non-empty array. | | isMap(value) | areMaps(array) | Checks for Map. | | isObject(value) | areObjects(array) | Checks for object. | | isPlainObject(value) | arePlainObjects(array) | Checks for plain object (object literal). | | isSet(value) | areSets(array) | Checks for Set. | | isWeakMap(value) | areWeakMaps(array) | Checks for WeakMap. | | isWeakSet(value) | areWeakSets(array) | Checks for WeakSet. |

Specialized instances and logic

| Single Value Check | Check Array Elements | Description | |:-----------------------------------------------------|:-------------------------------------------------------|:-----------------------------------| | isBuffer(value) | areBuffers(array) | Checks for Node.js Buffer. | | isDate(value) | areDates(array) | Checks for Date instance. | | isEmpty(value) | areEmpty(array) | Checks for empty values. | | isEqual(value, expected) | areEqual(value, expected) | Checks for equality to expected. | | isError(value) | areErrors(array) | Checks for Error object. | | isFunction(value) | areFunctions(array) | Checks for function. | | isOfType(value, type) | areOfType(array, type) | Checks for the given type. | | isOneOfType(value, types) | areOneOfType(array, types) | Checks for any of the given types. | | isPromise(value) | arePromises(array) | Checks for Promise. | | isRegEx(value) | areRegExes(array) | Checks for RegExp. | | isStream(value) | areStreams(array) | Checks for stream. | | isValidDate(value) | areValidDates(array) | Checks whether Date is valid. |