npm package: @ikornilow/ts-union-utils
Description: A lightweight TypeScript utility library for handling union types with ease.
Latest version: 1.1.0

# ts-union-utils

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

![npm version](https://img.shields.io/npm/v/@ikornilow/ts-union-utils?style=flat-square)
![License](https://img.shields.io/npm/l/@ikornilow/ts-union-utils?style=flat-square)

## Installation

```sh
npm install @ikornilow/ts-union-utils
```

or

```sh
yarn add @ikornilow/ts-union-utils
```

or

```sh
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.

```ts
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.

```ts
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).

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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](./LICENSE) file.