Package Exports

@apexo/type

Readme

@apexo/type

Ever spent hours writing validation code, only to realize you're doing the same thing in every function? Or maybe you've let AI generate it for you, and now your bundle is bloated with duplicate boilerplate?

@apexo/type is a small library that does all your type checking for you. Why do you need it? Because JavaScript's type checking is weird:

typeof null says it's an "object" (but it's not!)
typeof [] says it's an "object" (arrays need different checks)
typeof NaN says it's a "number" (even though NaN means "Not a Number")
No easy way to check for empty values or loops in objects

You could write all the checks yourself:

function processUser(data) {
    if (data === null || data === undefined) {
        throw new Error('Data is required');
    }
    if (typeof data !== 'object' || Array.isArray(data)) {
        throw new Error('Data must be an object');
    }
    if (typeof data.name !== 'string' || data.name.trim() === '') {
        throw new Error('Name must be a non-empty string');
    }
    if (typeof data.age !== 'number' || isNaN(data.age) || data.age < 0) {
        throw new Error('Age must be a positive number');
    }
    // Finally, your actual logic...
}

Or you could use @apexo/type and get it done in 3 lines:

import { isObject, isNotEmpty, isPositive } from '@apexo/type';

function processUser(data) {
    if (!isObject(data)) throw new Error('Data must be an object');
    if (!isNotEmpty(data.name)) throw new Error('Name is required');
    if (!isPositive(data.age)) throw new Error('Age must be positive');
    // Your actual logic, front and center
}

Why would I want that?

JavaScript's typeof operator falls short in many real-world scenarios:

typeof null === 'object' (it's not!)
typeof [] === 'object' (arrays need special handling)
No way to check for NaN, empty values, or validate complex structures

@apexo/type solves these problems by providing:

Runtime Safety: Validate data from APIs, user input, or any untrusted source before processing
TypeScript Integration: Type guards automatically narrow types in your code, giving you full IntelliSense support
Readable Code: Replace verbose checks like if (value !== null && value !== undefined && typeof value === 'string' && value.trim() !== '') with if (isNotEmpty(value))
Edge Case Handling: Correctly handles tricky JavaScript edge cases (null, undefined, NaN, Symbol, BigInt, circular references)

How little is it?

~12KB minified (entire library)
Tree-shakeable: Only bundle what you use. Import just isString? Your bundle won't include date validators or circular reference detection
Zero dependencies: No bloat from external packages
Side-effect free: Marked as "sideEffects": false for optimal tree-shaking

How do I install it?

npm install @apexo/type

Or with your preferred package manager:

pnpm add @apexo/type
yarn add @apexo/type

How do I use it?

Basic Type Guards

Type guards return a boolean and automatically narrow TypeScript types:

import { isString, isNumber, isArray } from '@apexo/type';

function process(input: unknown) {
    if (isString(input)) {
        // TypeScript knows input is string here
        console.log(input.toUpperCase());
    }
    
    if (isArray(input)) {
        // TypeScript knows input is any[] here
        console.log(input.length);
    }
}

Validating Values

Beyond type checking, validate specific properties:

import { isPositive, isEven, isFutureDate, isEmpty } from '@apexo/type';

isPositive(10);  // true
isEven(7);       // false
isEmpty('   ');  // true
isFutureDate(new Date('2050-01-01')); // true

Advanced Utilities

import { whatTypeOf, hasCircularReference } from '@apexo/type';

whatTypeOf(null);        // "null" (not "object"!)
whatTypeOf([]);          // "array"
whatTypeOf(new Date());  // "date"

const obj: any = {};
obj.self = obj;
hasCircularReference(obj); // { hasCircular: true, path: "root.self -> root" }

Loading the library

ES Modules (Recommended)

import { isString, isObject } from '@apexo/type';

CommonJS

const { isString, isObject } = require('@apexo/type');

TypeScript

The library is written in TypeScript and includes full type definitions out of the box.

Are there TypeScript definitions?

Yes! The library is TypeScript-first and includes complete type definitions. All type guards use TypeScript's type predicate syntax (value is Type), providing automatic type narrowing:

function example(input: unknown) {
    if (isString(input)) {
        // input is automatically typed as 'string'
        input.toLowerCase(); // ✅ TypeScript knows this is safe
    }
}

Where can I use it?

Everywhere JavaScript runs:

✅ Node.js (v14+)
✅ Browsers (Modern browsers, IE11+ with polyfills)
✅ Deno
✅ Bun
✅ Edge Functions (Vercel, Cloudflare Workers, etc.)
✅ React Native

The library has zero dependencies and uses only standard JavaScript features, making it universally compatible.

API Reference

Primitives

isString(value) - Checks if value is a string
isNumber(value) - Checks if value is a number (and not NaN)
isNumberStr(value) - Checks if value is a number or numeric string
isBoolean(value) - Checks if value is a boolean
isNil(value) - Checks if value is null or undefined
isNull(value) - Checks if value is null
isUndefined(value) - Checks if value is undefined
isBigInt(value) - Checks if value is a BigInt
isSymbol(value) - Checks if value is a Symbol
isPrimitive(value) - Checks if value is a primitive type

Objects & Structures

isObject(value) - Checks if value is a non-null object (excluding arrays)
isPlainObject(value) - Checks if value is a plain object ({} or new Object())
isArray(value) - Checks if value is an array
isArrayLike(value) - Checks if value is array-like (has length property)
isFunction(value) - Checks if value is a function
isClass(value) - Checks if value is a class constructor
isIterable(value) - Checks if value is iterable
isAsyncIterable(value) - Checks if value is async iterable
isGeneratorFunction(value) - Checks if value is a generator function
isWindow(value) - Checks if value is a Window object

Advanced Types

isPromise(value) - Checks if value is a Promise
isMap(value) - Checks if value is a Map
isSet(value) - Checks if value is a Set
isWeakMap(value) - Checks if value is a WeakMap
isWeakSet(value) - Checks if value is a WeakSet
isRegExp(value) - Checks if value is a RegExp
isDate(value) - Checks if value is a Date object
isError(value) - Checks if value is an Error
isTypeError(value) - Checks if value is a TypeError
isReferenceError(value) - Checks if value is a ReferenceError
isSyntaxError(value) - Checks if value is a SyntaxError
isRangeError(value) - Checks if value is a RangeError
isURIError(value) - Checks if value is a URIError
isEvalError(value) - Checks if value is an EvalError
isAggregateError(value) - Checks if value is an AggregateError
isBuffer(value) - Checks if value is a Buffer (Node.js) or ArrayBuffer/View
isJson(value) - Checks if value is a valid JSON string

Empty Checks

isEmpty(value) - Checks if value is empty (null, undefined, empty string/array/object)
isNotEmpty(value) - Inverse of isEmpty
isEmptyStr(value) - Checks if value is an empty string (or whitespace only)
isEmptyArr(value) - Checks if value is an empty array
isEmptyObj(value) - Checks if value is an empty object

Number Validators

isFiniteNumber(value) - Checks if value is a finite number
isInteger(value) - Checks if value is an integer
isFloat(value) - Checks if value is a float
isSafeInteger(value) - Checks if value is a safe integer
isPositive(value) - Checks if value is > 0
isNegative(value) - Checks if value is < 0
isZero(value) - Checks if value is 0
isEven(value) - Checks if value is even
isOdd(value) - Checks if value is odd
isPrime(value) - Checks if value is a prime number
isInRange(value, min, max) - Checks if value is within [min, max]
isBetween(value, min, max) - Checks if value is strictly between (min, max)

Date Validators

isValidDate(value) - Checks if value is a valid Date (not Invalid Date)
isStrictDate(value) - Alias for isValidDate
isFutureDate(date) - Checks if date is in the future
isPastDate(date) - Checks if date is in the past
isToday(date) - Checks if date is today
isSameDay(a, b) - Checks if two dates are on the same day
isLeapYear(year) - Checks if year is a leap year
isISODateString(value) - Checks if value is an ISO 8601 date string
isValidISODateOnly(value) - Checks if value is a valid YYYY-MM-DD string
isValidTimeString(value) - Checks if value is a valid time string (HH:mm)
isDateTimeString(value) - Checks if value is a valid datetime string
isTimestamp(value) - Checks if value is a valid timestamp
isDateLike(value) - Checks if value can be converted to a valid Date
isForwardTime(date, offset?) - Checks if date is after now + offset
isBackwardTime(date, offset?) - Checks if date is before now - offset

Utilities

whatTypeOf(value) - Returns a specific type string (e.g., "array", "date", "null")
hasCircularReference(obj) - Detects circular references in objects/arrays

Architecture

The library is organized for maximum tree-shaking efficiency:

src/
├── guards/          # Type guards (value is Type)
│   ├── primitives.ts   # Basic types
│   ├── objects.ts      # Object structures
│   ├── advanced.ts     # Promises, Maps, Sets
│   ├── errors.ts       # Error types
│   └── empty.ts        # Empty checks
├── validators/      # Value validators (boolean)
│   ├── number.ts       # Numeric validations
│   └── date.ts         # Date validations
└── utils/           # Helper utilities
    ├── type-of.ts      # Enhanced typeof
    └── circular-ref.ts # Circular reference detection

This structure allows bundlers to eliminate entire categories of checks if you don't use them.

License

MIT

Repository

https://github.com/bytetologic/apexo.js/tree/main/packages/type