ts-essentials

What is ts-essentials?

The ts-essentials package provides a set of TypeScript types to enhance the TypeScript typing experience, offering more strict and powerful type definitions. It includes utility types, type guards, and other helpers that are not available in the standard TypeScript library.

What are ts-essentials's main functionalities?

DeepReadonly

Makes all properties of an object type recursively readonly. It is useful for defining immutable state or configurations.

type MyObject = { a: { b: { c: number } } };\nconst readonlyObject: DeepReadonly<MyObject> = { a: { b: { c: 1 } } };\n// readonlyObject.a.b.c = 2; // Error: Cannot assign to 'c' because it is a read-only property.

Writable

Converts a readonly object into a writable one, removing the readonly modifier from all properties.

type MyReadOnlyObject = { readonly a: number };\nconst writable: Writable<MyReadOnlyObject> = { a: 1 };\nwritable.a = 2; // No error, 'a' is writable.

StrictOmit

Creates a type by omitting the keys provided from the given object type, ensuring that only keys that exist on the type are specified.

interface MyObject { a: number; b: string; c: boolean; }\nconst myObject: StrictOmit<MyObject, 'a' | 'b'> = { c: true };\n// myObject.a or myObject.b does not exist.

LiteralUnion

Allows for a union type to include specific literal types as well as additional types, typically used for string literals with an escape hatch for other values.

type Direction = LiteralUnion<'left' | 'right', string>;\nconst direction: Direction = 'any string'; // No error, can be 'left', 'right', or any other string.

MarkRequired

Marks certain properties of an object type as required, changing them from optional to mandatory.

type MyObject = { a?: number; b: string; }\nconst required: MarkRequired<MyObject, 'a'> = { a: 1, b: 'string' };\n// Property 'a' is required in 'required'.

Other packages similar to ts-essentials

utility-types

Provides a collection of utility types for TypeScript, similar to ts-essentials. It includes types for operations like picking, omitting, and mapping properties of object types.

type-fest

A comprehensive library of utility types for TypeScript, with a wide range of type helpers. It covers more ground than ts-essentials and is regularly updated with new types.

typesafe-actions

Focused on Redux action creators, typesafe-actions provides utility types and functions for creating and handling actions in a type-safe manner, which is a more specific use case compared to the general utilities provided by ts-essentials.

README

ts-essentials

All essential TypeScript types in one place 🤙

Install

npm add --save-dev ts-essentials

or

yarn add --dev ts-essentials

What's inside?

• Basic
  • Primitive
  • NonNullable
• Dictionaries
  • Dictionary
  • DictionaryValues
• Deep Partial & DeepRequired & Deep Readonly
• Omit
• Merge
• Opaque types
• Literal types
• Exhaustive switch cases
• ValueOf

Basic:

• Primitive type matching all primitive values.
• NonNullable remove null and undefined from union type.

Dictionaries

const stringDict: Dictionary<string> = {
  a: "A",
  b: "B",
};

// Specify second type argument to change dictionary keys type
const dictOfNumbers: Dictionary<string, number> = {
  420: "four twenty",
  1337: "HAX",
};

// You may specify union types as key to cover all possible cases. It acts the same as Record from TS's standard library
export type DummyOptions = "open" | "closed" | "unknown";
const dictFromUnionType: Dictionary<number, DummyOptions> = {
  closed: 1,
  open: 2,
  unknown: 3,
};

// and get dictionary values
type stringDictValues = DictionaryValues<typeof stringDict>;

Deep Partial & Deep Required & Deep Readonly

type ComplexObject = {
  simple: number;
  nested: {
    a: string;
    array: [{ bar: number }];
  };
};

type ComplexObjectPartial = DeepPartial<ComplexObject>;
const samplePartial: ComplexObjectPartial = {
  nested: {
    array: [{}],
  },
};

type ComplexObjectAgain = DeepRequired<ComplexObjectPartial>;
const sampleRequired: ComplexObjectAgain = {
  simple: 5,
  nested: {
    a: "test",
    array: [],
  },
};

type ComplexObjectReadonly = DeepReadonly<ComplexObject>;

Omit

type SimplifiedComplexObject = Omit<ComplexObject, "nested">;

Merge

type Foo = {
  a: number,
  b: string
};

type Bar = {
  b: number
};

const xyz: Merge<Foo, Bar> = { a: 4, b: 2 };

Opaque types

type PositiveNumber = Opaque<number, "positive-number">;

function makePositiveNumber(n: number): PositiveNumber {
  if (n <= 0) {
    throw new Error("Value not positive !!!");
  }
  return (n as any) as PositiveNumber; // this ugly cast is required but only when "producing" opaque types
}

Literal types

// prevent type widening https://blog.mariusschulz.com/2017/02/04/typescript-2-1-literal-type-widening
const t = {
  letter: literal("a"), // type stays "a" not string
  digit: literal(5), // type stays 5 not number
};

Exhaustive switch cases

function actOnDummyOptions(options: DummyOptions): string {
  switch (options) {
    case "open":
      return "it's open!";
    case "closed":
      return "it's closed";
    case "unknown":
      return "i have no idea";
    default:
      // if you would add another option to DummyOptions, you'll get error here!
      throw new UnreachableCaseError(options);
  }
}

ValueOf type

const obj = {
  id: "123e4567-e89b-12d3-a456-426655440000",
  name: "Test object",
  timestamp: 1548768231486,
};

type objKeys = ValueOf<typeof obj>; // string | number

Contributing

All contributions are welcomed Read more