ts-extras

Essential utilities for TypeScript projects

Ideas for additional essential utilities welcome. Type-only utilities belong in type-fest.

Install

npm install ts-extras

Usage

import {isDefined} from 'ts-extras';

[1, undefined, 2].filter(isDefined);
//=> [1, 2]

API

General

• asWritable - Cast the given value to be Writable.
• objectUpdate - Apply a type-checked partial update to an object in place.
• safeCastTo - Constrain a value to the given type safely.

Type guard

• isDefined - Check whether a value is defined (not undefined).
• isEqualType - Check if two types are equal at compile time.
• isPresent - Check whether a value is present (not null nor undefined).
• isPropertyDefined - Check whether a specific property of a value is defined (not undefined).
• isPropertyPresent - Check whether a specific property of a value is present (not null nor undefined).
• isEmpty - Check whether an array is empty.
• isFinite - A strongly-typed version of Number.isFinite().
• isInfinite - Check whether a value is infinite.
• isInteger - A strongly-typed version of Number.isInteger().
• isSafeInteger - A strongly-typed version of Number.isSafeInteger().
• keyIn - Check if a key is in an object and narrow the key to the object's keys.
• not - Invert a type predicate function.
• objectHasIn - Check if an object has a property (including inherited) and narrow the object type.
• assert - Assert that the given condition is truthy.
• assertDefined - Assert that the given value is defined, meaning it is not undefined.
• assertPresent - Assert that the given value is present (non-nullable), meaning it is neither null nor undefined.
• assertError - Assert that the given value is an Error.
• assertNever - Assert that a code path is unreachable.

Improved builtin

• arrayAt - A strongly-typed version of Array#at() with improved tuple support (supports -1 and positive literal indices for tuples).
• arrayConcat - A strongly-typed version of Array#concat() that properly handles arrays of different types.
• arrayJoin - A strongly-typed version of Array#join() that preserves literal string types.
• arrayFirst - Return the first item of an array with stronger typing for tuples.
• arrayIncludes - A strongly-typed version of Array#includes() that properly acts as a type guard.
• arrayLast - Return the last item of an array with stronger typing for tuples.
• objectAssign - A strongly-typed version of Object.assign().
• objectKeys - A strongly-typed version of Object.keys().
• objectValues - A strongly-typed version of Object.values().
• objectEntries - A strongly-typed version of Object.entries().
• objectFromEntries - A strongly-typed version of Object.fromEntries().
• objectMapValues - Map over an object's values while preserving strongly-typed keys.
• objectHasOwn - A strongly-typed version of Object.hasOwn().
• setHas - A strongly-typed version of Set#has() that properly acts as a type guard.
• stringSplit - A strongly-typed version of String#split() that returns a tuple for literal strings.

FAQ

What is the difference between keyIn, objectHasIn, and objectHasOwn?

These functions solve different problems despite all checking property existence:

keyIn - Key narrowing for union types:

• Uses the in operator, checking the prototype chain
• Narrows the key variable to only keys that exist in the object
• Best for: "Which of these possible keys actually exists?"
• Guards against __proto__ and constructor for security

objectHasIn - Object narrowing with prototype chain:

• Uses the in operator, checking the prototype chain
• Narrows the object type to include the checked property
• Best for: "Can I safely access this property (including inherited)?"
• Guards against __proto__ and constructor for security

objectHasOwn - Object narrowing for own properties:

• Uses Object.hasOwn(), checking only own properties
• Narrows the object type to include the checked property
• Best for: "Can I safely access this own property on this object?"

// keyIn - narrows the key (prototype chain)
const key = 'foo' as 'foo' | 'bar' | 'baz';
if (keyIn(object, key)) {
	// `key` is now: 'foo' | 'bar' (only existing keys)
	console.log(object[key]); // Safe
}

// objectHasIn - narrows the object (prototype chain)
const data: unknown = {foo: 1};
if (objectHasIn(data, 'toString')) {
	// `data` is now: unknown & {toString: unknown}
	console.log(data.toString); // Safe (inherited method)
}

// objectHasOwn - narrows the object (own properties only)
if (objectHasOwn(data, 'foo')) {
	// `data` is now: unknown & {foo: unknown}
	console.log(data.foo); // Safe (own property)
}

What is the difference between this and type-fest?

The type-fest package contains only types, meaning they are only used at compile-time and nothing is ever compiled into actual JavaScript code. This package contains functions that are compiled into JavaScript code and used at runtime.

Related

• type-fest - A collection of essential TypeScript types
• is - Type guards for any situation
• camelcase-keys - Runtime transformation of object properties to camel-case (like type-fest's CamelCasedPropertiesDeep)