Cast

Description

Cast is an opinionated TypeScript utility library for safely extracting and casting properties from objects. It exposes a single static Cast class with typed get functions that validate each property and throw descriptive, human-readable error messages (powered by @nuov.io/sentence) when a property is invalid. It eliminates a lot of tedious and repetitive defensive checks.

Installation

npm install @nuov.io/cast

Usage

Raw property access & checks

All get functions are built on top of the property and unknown functions; both return an unknown type. The property function, however, validates for undefined, null, or missing properties:

import { Cast } from "@nuov.io/cast";

const json = {
  undefined: undefined,
  null: null,
};

Cast.unknown(json, "undefined"); // => undefined
Cast.unknown(json, "null"); // => null
Cast.unknown(json, "missing"); // => undefined

Cast.property(json, "undefined");
// throws: "The property 'undefined' is undefined."
Cast.property(json, "null");
// throws: "The property 'null' is null."
Cast.property(json, "missing");
// throws: "The property 'missing' is undefined."

Cast.propertyExists(json, "undefined"); // => true
Cast.propertyExists(json, "null"); // => true
Cast.propertyExists(json, "missing"); // => false

Cast.isUndefined(json, "undefined"); // => true
Cast.isUndefined(json, "null"); // => false
Cast.isUndefined(json, "missing"); // => true

Cast.isNull(json, "undefined"); // => false
Cast.isNull(json, "null"); // => true
Cast.isNull(json, "missing"); // => false

Booleans

import { Cast } from "@nuov.io/cast";

const json = {
  true: true,
  false: false,
  string: "true",
};

Cast.boolean(json, "true"); // => true
Cast.boolean(json, "false"); // => false
Cast.boolean(json, "string");
// throws: "The property 'string' (true) is not a boolean."

Dates

The date function accepts epoch timestamps (an integer in milliseconds within ±100M days) and ISO 8601 with milliseconds (e.g. 2025-07-15T00:00:00.000Z):

import { Cast } from "@nuov.io/cast";

const json = {
  epoch: 1752537600000,
  iso8601: "2025-07-15T00:00:00.000Z",
  date: "2025-07-15",
};

Cast.date(json, "epoch"); // => Date (2025-07-15T00:00:00.000Z)
Cast.date(json, "iso8601"); // => Date (2025-07-15T00:00:00.000Z)
Cast.date(json, "date");
// throws: "The property 'date' (2025-07-15) is not a date."

Enums

The enum function casts a property to an enum member, matching by either the enum key or the enum value. It works with string, numeric, defined numeric, and heterogeneous enums:

import { Cast } from "@nuov.io/cast";

enum Color {
  RED = "Red",
  GREEN = "Green",
  BLUE = "Blue",
}

const byValue = { color: "Green" };
const byKey = { color: "BLUE" };

Cast.enum(byValue, "color", Color); // => Color.GREEN
Cast.enum(byKey, "color", Color); // => Color.BLUE

The enumKey function resolves the key of an enum from a matching key or value:

import { Cast } from "@nuov.io/cast";

Cast.enumKey("Red", Color); // => "RED"
Cast.enumKey("GREEN", Color); // => "GREEN"

Numbers, integers & bigints

The number and integer functions accept number values as well as bigint values within the safe integer range. The bigInt function accepts bigint, number, and string values — including decimal, binary (0b), octal (0o), and hexadecimal (0x) strings:

import { Cast } from "@nuov.io/cast";

const json = {
  bigint: 255n,
  binary: "0b11111111",
  decimal: "255",
  hexadecimal: "0xFF",
  integer: 3675,
  number: -922.762,
  octal: "0o377",
};

Cast.number(json, "bigint"); // => 255
Cast.number(json, "decimal");
// throws: "The property 'decimal' (255) is not a number."
Cast.number(json, "integer"); // => 3675
Cast.number(json, "number"); // => -922.762

Cast.integer(json, "bigint"); // => 255
Cast.integer(json, "decimal");
// throws: "The property 'decimal' (255) is not an integer."
Cast.integer(json, "integer"); // => 3675
Cast.integer(json, "number");
// throws: "The property 'number' (-922.762) is not an integer."

Cast.bigInt(json, "decimal"); // => 255n
Cast.bigInt(json, "binary"); // => 255n
Cast.bigInt(json, "octal"); // => 255n
Cast.bigInt(json, "hexadecimal"); // => 255n

Objects

import { Cast } from "@nuov.io/cast";

const json = { address: { city: "London" } };

Cast.object(json, "address"); // => { city: 'London' }

Strings & UUIDs

The string function returns properties whose values are strings. The uuid function validates that the property is a string in a valid UUID format (powered by @nuov.io/validator):

import { Cast } from "@nuov.io/cast";

const json = {
  string: "The quick brown fox jumped over the lazy dog.",
  uuid: "550e8400-e29b-41d4-a716-446655440000",
};

Cast.string(json, "string"); // => "The quick brown fox jumped over the lazy dog."
Cast.uuid(json, "uuid"); // => "550e8400-e29b-41d4-a716-446655440000"

API Reference

Cast (class)

The main entry point. All methods are static.

Get functions

| Method | Returns | Description | | -------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Cast.bigInt(json, propertyName) | bigint | Gets the property as a bigint. Accepts bigint, number, or string (decimal, binary 0b, octal 0o, hexadecimal 0x) values. | | Cast.boolean(json, propertyName) | boolean | Gets the property as a boolean. Accepts boolean values only. | | Cast.date(json, propertyName) | Date | Gets the property as a date. Accepts epoch timestamp values and ISO 8601 string values with milliseconds. | | Cast.enum<T extends Record<string, string \| number>>(json, propertyName, enumObject: T) | T[keyof T] | Gets the property as an enum member, matching by enum key (preferred) or enum value. Works with string, numeric, defined numeric, and heterogeneous enums. | | Cast.enumKey<T extends Record<string, string \| number>>(value: string \| number, enumObject: T) | keyof T | Gets the key of an enum from a matching key (preferred) or value. | | Cast.integer(json, propertyName) | number | Gets the property as a safe integer. Accepts number values and bigint values (when within the safe integer range). | | Cast.number(json, propertyName) | number | Gets the property as a finite number. Accepts number values and bigint values (when within the safe integer range). | | Cast.object(json, propertyName) | object | Gets the property as an object. | | Cast.property(json, propertyName) | unknown | Gets the property, validating that it is neither undefined, null, or missing. | | Cast.string(json, propertyName) | string | Gets the property as a string. Accepts string values only. | | Cast.unknown(json, propertyName) | unknown | Gets the property without any validation. | | Cast.uuid(json, propertyName) | string | Gets the property as a UUID string, validating the UUID format. Accepts string values only. |

Checks

| Method | Returns | Description | | ----------------------------------------- | --------- | --------------------------------------------------------------------------- | | Cast.isNull(json, propertyName) | boolean | Returns true if the property exists and is null. | | Cast.isUndefined(json, propertyName) | boolean | Returns true if the property is undefined or does not exist. | | Cast.propertyExists(json, propertyName) | boolean | Returns true if the property exists on the object or its prototype chain. |

Parameters

All functions (except the enumKey function) accept the same two base parameters:

| Parameter | Type | Description | | -------------- | ------------------ | ------------------------------------- | | json | Readonly<object> | The object to read the property from. | | propertyName | string | The name of the property to cast. |

The enum and enumKey functions accept the enumObject parameter:

| Parameter | Type | Description | | ------------ | -------------------------------------------- | --------------------------------- | | enumObject | T extends Record<string, string \| number> | The enum object to match against. |

Errors

All get functions (except the unknown and enumKey functions) throw an Error when the property is undefined, null, missing, or of the wrong type.

The enum and enumKey functions throw an Error when the enumObject is not an object, contains duplicate values, or contains broken reverse mappings. Both functions throw an Error when no matching key or value is found in the enumObject.

Some valid TypeScript enums will fail validation. However, this is by design:

// fails duplicate value validation
enum InvalidValuesEnum {
  A = "x",
  B = "x",
  C = "y",
}

// fails reverse mapping validation
enum InvalidMappedEnum {
  A = "a",
  B = "A",
  C = "c",
}

License

MIT License