ts-union-utils

A lightweight TypeScript utility library for handling union types with ease.

Installation

npm install @ikornilow/ts-union-utils

or

yarn add @ikornilow/ts-union-utils

or

pnpm add @ikornilow/ts-union-utils

Usage

This library provides a collection of utility types designed to work with TypeScript unions distributively.

AllKeys

Produces a union of all possible keys across all members of the union.

import { AllKeys } from '@ikornilow/ts-union-utils';

type A = { id: number; name: string };
type B = { id: number; active: boolean };
type U = A | B;

type All = AllKeys<U>;
// Result: 'id' | 'name' | 'active'

CommonKeys

Extracts keys that act as a common intersection across all union members.

import { CommonKeys } from '@ikornilow/ts-union-utils';

type A = { id: number; name: string };
type B = { id: number; active: boolean };
type U = A | B;

type Common = CommonKeys<U>;
// Result: 'id'

NonCommonKeys

Extracts keys that do not exist in all members (the symmetric difference).

import { NonCommonKeys } from '@ikornilow/ts-union-utils';

type A = { id: number; name: string };
type B = { id: number; active: boolean };
type U = A | B;

type NonCommon = NonCommonKeys<U>;
// Result: 'name' | 'active'

MergeUnion

Deeply merges a union of objects into a single object type. Missing keys become nullable (| null). This is perfect for creating a "unified view" of a data structure.

import { MergeUnion } from '@ikornilow/ts-union-utils';

type A = { id: number; name: string; meta: { tags: string[] } };
type B = { id: number; active: boolean; meta: { createdBy: string } };
type U = A | B;

type Merged = MergeUnion<U>;
/*
Result:
{
  id: number;
  name: string | null;
  active: boolean | null;
  meta: {
    tags: string[] | null;
    createdBy: string | null;
  }
}
*/

PickType

Picks the property type of a specific key from a union. If a member does not have the key, it returns null.

import { PickType } from '@ikornilow/ts-union-utils';

type A = { id: number; name: string };
type B = { id: number; active: boolean };
type U = A | B;

type NameType = PickType<U, 'name'>;
// Result: string | null (because B doesn't have 'name')

type IdType = PickType<U, 'id'>;
// Result: number

PickTypeOf

A stricter version of PickType. It only allows picking keys that actually exist in the union of all keys. Returns never for invalid keys.

import { PickTypeOf } from '@ikornilow/ts-union-utils';

type A = { id: number; name: string };
type B = { id: number; active: boolean };
type U = A | B;

type Valid = PickTypeOf<U, 'name'>;
// Result: string | null

type Invalid = PickTypeOf<U, 'doesNotExist'>;
// Result: never

Subtract

Removes members from a union A that are assignable to C. Useful for filtering union types.

import { Subtract } from '@ikornilow/ts-union-utils';

type Keys = 'id' | 'name' | 'active';
type ToRemove = 'id';

type Result = Subtract<Keys, ToRemove>;
// Result: 'name' | 'active'

License

This project is released under the Unlicense. This means you can use it for whatever you want. No attribution required.

For more details, see the LICENSE file.