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
• Dictionaries
  • Dictionary
  • DictionaryValues
• Deep Partial & DeepRequired & Deep Readonly
• Writable
• Omit
• Merge
• Opaque types
• Tuple constraint
• Literal types
• Exhaustive switch cases
• ValueOf

Basic:

• Primitive type matching all primitive values.

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>;

Writable

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

const foo: Foo = { a: 1, b: 'b' }

(foo as Writable<typeof foo>).a = 42

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
}

Tuple constraint

function foo<T extends Tuple>(tuple: T): T {
    return tuple;
}

const ret = foo(["s", 1]);
// return type of [string, number]

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