TypeScript Essentials

Common errors

• Type instantiation is excessively deep and possibly infinite. (2589)

  cause Using `PathValue` or `Paths` with an older TypeScript version, particularly below 4.2.0, which lacks optimizations for deep type calculations.
  fix Upgrade your TypeScript version to `4.2.0` or higher. The library officially requires `4.5.0` or higher for full functionality.

• Property 'someOptionalProperty' does not exist on type 'Required<MyType>'.

  cause Attempting to assign an object that is missing a formerly optional property to a type transformed by `Required` or `DeepRequired`, especially when `strictNullChecks` is not enabled, leading to incorrect type inference.
  fix Ensure `strictNullChecks` is enabled in your `tsconfig.json`. Also, verify that the object being assigned indeed has all required properties as non-nullable.

• Argument of type '(...)' is not assignable to parameter of type 'never'.

  cause Incorrectly attempting to use a stricter utility type like `StrictExclude` or `StrictOmit` with a union type that does not align with its strict exclusion rules, leading to unintended type narrowing.
  fix Carefully review the `UnionType` and `ExcludedMembers` parameters for `StrictExclude`, or `Type` and `Keys` for `StrictOmit`, ensuring they precisely match the desired exclusion logic. These strict types are less forgiving than their built-in counterparts.

Warnings

• breaking `ts-essentials` versions prior to v10.0.0 supported older TypeScript versions. Since v10.0.0, the minimum required TypeScript version is `^4.2.0` due to advanced type features like `PathValue` and `Paths`. From v10.0.0 onward, specifically for `Mark*` utility types, `typescript>=4.5` is required.
  Fix: Upgrade your project's TypeScript version to `4.5.0` or higher. Ensure your `package.json` reflects `"typescript": ">=4.5.0"` as a devDependency or peerDependency.
• gotcha The library explicitly requires `strictNullChecks` to be enabled in your `tsconfig.json`. Disabling this option can lead to unexpected type behaviors and diminish the strictness and correctness of the provided utility types.
  Fix: Add or ensure `'strictNullChecks': true` is set in your `compilerOptions` in `tsconfig.json`.
• deprecated The `DictionaryValues` utility type has been deprecated since version 10.0.2. Users should migrate to the `ValueOf` utility type for equivalent functionality.
  Fix: Replace `DictionaryValues<Type>` with `ValueOf<Type>` in your codebase. For example, `type MyValues = ValueOf<MyDictionary>`.
• breaking In v10.0.0, the generic constraint on the second type parameter of `DeepOmit` and `DeepPick` was removed, and new `StrictDeepOmit` and `StrictDeepPick` types were introduced with generic constraints. This changes how these types are used.
  Fix: Review existing usages of `DeepOmit` and `DeepPick`. If you relied on the previous generic constraints or need stricter behavior, consider migrating to `StrictDeepOmit` or `StrictDeepPick`.
• gotcha To prevent excessively deep type instantiation, the `Paths` utility type now limits the depth of path generation to 7 by default. While this improves performance, it might truncate paths for extremely deeply nested objects.
  Fix: If you require paths for objects nested deeper than 7 levels, you might need to reconsider your object structure or explore custom type solutions, as there's currently no direct way to configure this depth via options within the type.

Install

• npm install ts-essentials npm
• yarn add ts-essentials yarn
• pnpm add ts-essentials pnpm

Imports

• Prettify

  import { Prettify } from 'ts-essentials'

  A widely used type to flatten and improve the readability of complex intersection types in IDE tooltips.
• DeepReadonly

  import { DeepReadonly } from 'ts-essentials'

  Applies readonly recursively to all properties, making entire object structures immutable at the type level.
• Paths

  import { Paths } from 'ts-essentials'

  Generates a union of all possible string paths to properties within a given object type. Its performance is depth-limited to 7 by default since v10.0.3.
• StrictOmit

  import { StrictOmit } from 'ts-essentials'

  A stricter version of TypeScript's built-in Omit utility, preventing common mistakes with union types.

Quickstart

Demonstrates the usage of `Prettify` for readability, `DeepReadonly` for immutability, `StrictOmit` for precise property exclusion, and `Paths`/`PathValue` for advanced path-based type introspection on a complex object.

import { Prettify, DeepReadonly, StrictOmit, Paths, PathValue } from 'ts-essentials';

interface User {
  id: string;
  name: string;
  email?: string;
  address: {
    street: string;
    city: string;
    zip: number;
    coordinates?: [number, number];
  };
  preferences: {
    theme: 'dark' | 'light';
    notifications: boolean;
  };
  roles: ('admin' | 'editor' | 'viewer')[];
}

// Prettify: Flattens and makes types more readable in IDE tooltips
type PrettyUser = Prettify<User>;

// DeepReadonly: Makes all properties and nested properties readonly
type ImmutableUser = DeepReadonly<User>;
// ImmutableUser.address.street = 'New Street'; // Type Error: Cannot assign to 'street' because it is a read-only property.

// StrictOmit: Constructs a type by picking all properties from Type and then removing Keys.
// It is a stricter version of TypeScript's built-in Omit.
type UserWithoutSensitiveInfo = StrictOmit<User, 'email' | 'address.coordinates' | 'roles'>;

const newUser: UserWithoutSensitiveInfo = {
  id: 'abc-123',
  name: 'Jane Doe',
  address: { street: 'Main St', city: 'Anytown', zip: 12345 },
  preferences: { theme: 'dark', notifications: true }
  // email: 'jane@example.com' // Type Error: Object literal may only specify known properties
};

// Paths: Generates a union of all possible string paths within an object type
type UserPathExamples = Paths<User>;
// UserPathExamples could include 'id' | 'address.city' | 'preferences.theme' | 'roles.0'

// PathValue: Retrieves the type of the value at a specific path
type AddressCityType = PathValue<User, 'address.city'>; // string
type FirstRoleType = PathValue<User, 'roles.0'>; // 'admin' | 'editor' | 'viewer'