Object Type Guards

Generic Objects

Collection of type-safe utility functions for runtime type checking of objects (including built-in JS objects). These guards enable TypeScript type narrowing and runtime validation.

Import

import { isObject, isNotEmptyObject, isObjectWithKeys, isEmptyObject } from 'toolbox-x/guards';

Type Definitions

/** Generic object with any value */
type GenericObject = Record<string, any>;;

isObject

Determines if a value is a plain JavaScript object (excluding null and arrays). Properly narrows TypeScript type to object with string keys.

Signature

isObject(value: unknown): value is GenericObject

Examples

Notes

• Returns true for any object type except arrays
• Functions are intentionally excluded despite being objects
• Properly handles edge cases like Object.create(null)

isNotEmptyObject

Validates that a value is both an object and contains at least one enumerable property. Useful for checking non-empty configurations or data payloads.

Signature

isNotEmptyObject(value: unknown): value is GenericObject

Examples

// Practical usage
function processConfig(config: unknown) {
  if (isNotEmptyObject(config)) {
    // Safe to access properties
    return {
      ...defaults,
      ...config
    };
  }
  throw new Error('Configuration must be a non-empty object');
}

Use Cases

• Validating API response objects
• Checking for non-empty configurations
• Ensuring payloads contain data
• Input validation for object parameters

isObjectWithKeys

Checks if a value is an object containing all specified keys. The most strict object validation guard, ensuring both the object shape and required properties.

Signature

isObjectWithKeys<Key extends string>(value: unknown, keys: ValidArray<Key>): value is { [K in Key]: unknown }

Examples

Notes

• Only checks for presence of keys, not their types
• Combine with other guards for complete validation
• Works with both string and symbol keys in the check

isEmptyObject

Determines if a value is an object with no enumerable properties of its own. Useful for checking default/empty states.

Signature

isEmptyObject(value: unknown): boolean

Examples

Use Cases

• Checking for empty state objects
• Default parameter handling
• Validating cleaned or stripped objects
• Difference detection in state management

Aliases

Built-in Objects

isSet

Checks if a value is a Set object. Works with native Set and cross-realm instances.

Signature

isSet<T>(value: unknown): value is Set<T>

Examples

Use Cases

• Collection type validation
• Data processing pipelines
• Set operations validation
• Cross-window communication

isMap

Validates if a value is a Map object. Works with native Map and cross-realm instances.

Signature

isMap<K, V>(value: unknown): value is Map<K, V>

Examples

Notes

• Detects both empty and populated Maps
• Works across different JavaScript realms
• Preserves key-value type information

isRegExp

Checks if a value is a RegExp object. Handles both literal and constructor-created regular expressions.

Signature

isRegExp(value: unknown): value is RegExp

Examples

Use Cases

• Input validation patterns
• Dynamic regex construction
• Serialization/deserialization
• Cross-window communication

isError

Determines if a value is an Error object. Works with native errors and custom error classes.

Signature

isError(value: unknown): value is Error

Examples

// Error detection
console.log(isError(new Error()));          // true
console.log(isError(new TypeError()));      // true
console.log(isError(new CustomError()));    // true (if extends Error)

// Non-errors
console.log(isError('error message'));      // false
console.log(isError({ message: 'error' })); // false

// Error handling
try {
  // ...
} catch (e) {
  if (isError(e)) {
    console.error(e.message);  // safely accessible
    Sentry.captureException(e);
  } else {
    console.error('Unknown error:', e);
  }
}

Notes

• Works with all Error subclasses
• Properly handles error-like objects
• Essential for robust error handling

Aliases