@wopjs/cast

@wopjs/cast

Type-safe utilities for filtering and coercing unknown values in TypeScript.

Features

• Three-tier API pattern (is/to/as) for flexible type filtering
• Strong TypeScript type narrowing that preserves complex types (unions, tuples, readonly arrays)
• Zero dependencies and tree-shakeable
• Safe edge case handling (NaN, null, undefined, circular references)

Install

npm add @wopjs/cast

API Pattern

Every type has up to three functions following a consistent naming pattern:

Pattern	Returns	Use Case
is*	boolean	Type guards for conditional narrowing
to*	T | undefined	Optional values, composable with Option types
as*	T	Always returns valid value with fallback

import { isNumber, toNumber, asNumber } from "@wopjs/cast";

// is* - Type guard for conditionals
if (isNumber(value)) {
  value; // type narrowed to number
}

// to* - Returns undefined for invalid input
const num = toNumber(input); // number | undefined

// as* - Always returns a number (0 as fallback)
const safeNum = asNumber(input); // number

Type Narrowing

The library preserves and correctly narrows complex TypeScript types:

import { isArray, toArray, isTruthy } from "@wopjs/cast";

// Preserves array element types
const arr: string[] = ["a", "b"];
if (isArray(arr)) {
  arr; // still string[], not unknown[]
}

// Extracts from unions
const value: string | string[] = getData();
if (isArray(value)) {
  value; // narrowed to string[]
}

// Preserves tuples and readonly arrays
const tuple: [string, number] = ["a", 1];
const result = toArray(tuple); // [string, number] | undefined

// Excludes falsy types
const val: string | null | undefined = "hello";
if (isTruthy(val)) {
  val; // narrowed to string
}

Available Functions

Booleans

Function	Description
isTrue	Returns true if value is exactly true
toTrue	Returns true or undefined
asTrue	Returns true or false
isTruthy	Returns true if Boolean(x) is true
toTruthy	Returns truthy value or undefined
isFalsy	Returns true if Boolean(x) is false
toFalsy	Returns falsy value or undefined
isBoolean	Returns true if value is true or false
toBoolean	Returns boolean or undefined

Numbers

Function	Description
isNumber	Returns true if value is a number (excluding NaN)
toNumber	Returns number or undefined
asNumber	Returns number or 0

Strings

Function	Description
isString	Returns true if value is a string
toString	Returns string or undefined
asString	Returns string or ""
isNonEmptyString	Returns true if value is a non-empty string
toNonEmptyString	Returns non-empty string or undefined

Arrays

Function	Description
isArray	Type guard for arrays (preserves element types)
toArray	Returns array or undefined
asArray	Returns array or []
isNonEmptyArray	Type guard for non-empty arrays
toNonEmptyArray	Returns non-empty array or undefined

Objects

Function	Description
isObject	Returns true for objects (including arrays, excluding null)
toObject	Returns object or undefined
asObject	Returns object or {}
isPlainObject	Returns true for plain objects (excluding arrays)
toPlainObject	Returns plain object or undefined
asPlainObject	Returns plain object or {}
isNonEmptyPlainObject	Returns true for objects with at least one key
toNonEmptyPlainObject	Returns non-empty object or undefined
isNonEmptyJSONObject	Returns true for objects with non-undefined values
toNonEmptyJSONObject	Returns JSON object or undefined

Utilities

Function	Description
isDefined	Returns true if value is not undefined
toPlainObjectOf	Filter object values by type predicate
toPlainObjectOfTrue	Filter object to only true values
print	Safely stringify any value for display

Return Helpers

Constant functions useful for callbacks and default values:

Function	Returns
noop	void
returnsUndefined	undefined
returnsNull	null
returnsFalse	false
returnsTrue	true
returnsEmptyString	""

Usage Example

import {
  asPlainObject,
  asString,
  toNumber,
  asArray,
  toNonEmptyPlainObject,
  toPlainObjectOfTrue,
  isNumber,
  asNumber,
} from "@wopjs/cast";

// Parsing unknown API response
function parseUser(data: unknown) {
  const obj = asPlainObject(data);
  return {
    name: asString(obj.name),
    age: toNumber(obj.age), // undefined if not a number
    tags: asArray(obj.tags),
    settings: toNonEmptyPlainObject(obj.settings),
  };
}

// Filtering object values
const config = { debug: true, verbose: false, enabled: true };
toPlainObjectOfTrue(config); // { debug: true, enabled: true }

// Safe number handling
isNumber(NaN); // false (NaN is excluded)
asNumber(NaN); // 0 (safe fallback)
asNumber("42"); // 0 (not coerced, use parseInt for that)