ts-extras   

> Essential utilities for TypeScript projects

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

Install

``sh
npm install ts-extras
`

Usage

`js
import {isDefined} from 'ts-extras';

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

API

General

- asWritable - Cast the given value to be Writable.
- 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).
- 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.
- 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.

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.
- 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().
- 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?"

`typescript
// 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`)