@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)