Advanced utilities for deep manipulation of objects and nested types in TypeScript. These types allow you to merge, transform, filter, select, omit, and modify properties at any depth in a type-safe and expressive way.

Deep Utilities

Installation

npm i -D @halvaradop/ts-utility-types

Usage

import type { DeepMerge, DeepPartial, DeepReadonly } from "@halvaradop/ts-utility-types/deep"

import type * as Deep from "@halvaradop/ts-utility-types/deep"


type Utilities = Deep.DeepFilter
DeepGet
DeepKeys
DeepMerge
DeepMergeAll
DeepMutable
DeepNonNullable
DeepNonNullish
DeepNullable
DeepOmit
DeepPartial
DeepPick
DeepReadonly
DeepReplace
DeepRequired
DeepSet
DeepTruncate
DeepUnion

`DeepMerge<Obj1, Obj2, ByUnion, PriorityObject>`

Recursively merges two objects. If a property exists in both, the one from Obj1 takes priority (unless otherwise specified). You can merge as a union (ByUnion) or prioritize objects (PriorityObject).

Argument	Type	Description
`Obj1`	`object`	The first object to merge.
`Obj2`	`object`	The second object to merge.
`ByUnion`	`boolean` (default `false`)	If `true`, conflicting properties are combined as unions.
`PriorityObject`	`boolean` (default `true`)	If `true`, `Obj1` properties take priority over `Obj2` properties.

Related: DeepMergeAll, DeepUnion

Performance Note

Deep utilities work with recursive types and may have performance implications with deeply nested structures. Most operations are limited to reasonable depths (typically 10-20 levels).

import type { DeepMerge } from "@halvaradop/ts-utility-types/deep"

interface Config {
  api: {
    timeout: number
  }
  features: {
    darkMode: boolean
  }
}

interface UserConfig {
  api: {
    retries: number
  }
  features: {
    analytics: boolean
  }
}

type AppConfig = DeepMerge<Config, UserConfig>       
type AppConfig = {
    api: {
        timeout: number;
        retries: number;
    };
    features: {
        darkMode: boolean;
        analytics: boolean;
    };
}

const config: AppConfig = {
  api: {
    timeout: 5000,
    retries: 3,
  },
  features: {
    darkMode: true,
    analytics: false,
  },
}

`DeepUnion<Obj1, Obj2>`

Argument	Type	Description
`Obj1`	`object`	The first object to merge.
`Obj2`	`object`	The second object to merge.

import type { DeepUnion } from "@halvaradop/ts-utility-types/deep"

interface BaseController {
  baseUrl: string
  routes: string[]
}

interface ConfigBase {
  baseUrl: string[]
  routes: Array<{ url: string; name: string }>
}

type Union = DeepUnion<BaseController, ConfigBase>
     
type Union = {
    baseUrl: string | string[];
    routes: string[] | {
        url: string;
        name: string;
    }[];
}

`DeepMergeAll<Array, ByUnion, PriorityObject>`

Argument	Type	Description
`Array`	`unknown[]`	The tuple of object types to merge.
`ByUnion`	`boolean` (default `false`)	If `true`, conflicting properties are combined as unions.
`PriorityObject`	`boolean` (default `true`)	If `true`, earlier objects take priority over later ones.

import type { DeepMergeAll } from "@halvaradop/ts-utility-types/deep"

interface Foo {
  foo: string
}

interface Bar {
  bar: string
}

interface FooBar {
  bar: number
  foo: boolean
  foobar: string
}

type Merge = DeepMergeAll<[Foo, Bar, FooBar], true>
     
type Merge = {
    foo: string;
    bar: string;
    foobar: string;
}

`DeepMutable<Obj>`

Argument	Type	Description
`Obj`	`object`	The object to make mutable deeply.

import type { DeepMutable } from "@halvaradop/ts-utility-types/deep"

interface Foo {
  readonly foo: { readonly bar: { readonly foobar: number } }
}

type NonReadonlyFoo = DeepMutable<Foo>
          
type NonReadonlyFoo = {
    foo: {
        bar: {
            foobar: number;
        };
    };
}

`DeepReadonly<Obj>`

Argument	Type	Description
`Obj`	`object`	The object to make deeply readonly.

import type { DeepReadonly } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  address: { street: string; avenue: string }
}

type ReadonlyUser = DeepReadonly<User>
         
type ReadonlyUser = {
    readonly name: string;
    readonly address: {
        readonly street: string;
        readonly avenue: string;
    };
}

`DeepKeys<Obj, Depth>`

Argument	Type	Description
`Obj`	`object`	The object to extract keys from.
`Depth`	`number` (default `6`)	The maximum depth to traverse for keys.

import type { DeepKeys } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  address: { street: string; avenue: string }
}

type UserKeys = DeepKeys<User>
       
type UserKeys = "name" | "address" | "address.street" | "address.avenue"

`DeepOmit<Obj, Path>`

Argument	Type	Description
`Obj`	`object`	The object to omit a property from.
`Path`	`string`	The dot-separated path to omit.

import type { DeepOmit } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  address: { street: string; avenue: string }
}

type WithoutStreet = DeepOmit<User, "address.street">
         
type WithoutStreet = {
    name: string;
    address: {
        avenue: string;
    };
}

`DeepGet<Obj, Path>`

Argument	Type	Description
`Obj`	`object`	The object to get a value from.
`Path`	`string`	The dot-separated path to retrieve.

import type { DeepGet } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  address: { street: string; avenue: string }
}

type UserName = DeepGet<User, "name">       
type UserName = string

type UserStreet = DeepGet<User, "address.street">
        
type UserStreet = string

`DeepTruncate<Obj, Depth>`

Argument	Type	Description
`Obj`	`object`	The object to truncate.
`Depth`	`number`	The depth at which to truncate.

import type { DeepTruncate } from "@halvaradop/ts-utility-types/deep"

interface Foo {
  foo: string
  bar: number
  foobar: {
    foo: boolean
    bar: string
    foobar: {
      foo: number
    }
  }
}

type TruncatedFoo = DeepTruncate<Foo, 1>
         
type TruncatedFoo = {
    foo: string;
    bar: number;
    foobar: {};
}

`DeepPartial<Obj>`

Argument	Type	Description
`Obj`	`object`	The object to make deeply optional.

import type { DeepPartial } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  address: { street: string; avenue: string }
}

type UserOptional = DeepPartial<User>
         
type UserOptional = {
    name?: string | undefined;
    address?: {
        street?: string | undefined;
        avenue?: string | undefined;
    } | undefined;
}

`DeepRequired<Obj>`

Argument	Type	Description
`Obj`	`object`	The object to make deeply required.

import type { DeepRequired } from "@halvaradop/ts-utility-types/deep"

interface User {
  name?: string
  address?: {
    street?: string
    avenue?: string
  }
}

type UserRequired = DeepRequired<User>
         
type UserRequired = {
    name: string;
    address: {
        street: string;
        avenue: string;
    };
}

`DeepPick<Obj, Path>`

Argument	Type	Description
`Obj`	`object`	The object to pick a property from.
`Path`	`string`	The dot-separated path to pick.

import type { DeepPick } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  address: { street: string; avenue: string }
}

type UserPick = DeepPick<User, "address.street">
       
type UserPick = {
    address: {
        street: string;
    };
}

`DeepNullable<Obj>`

Argument	Type	Description
`Obj`	`object`	The object to make deeply nullable.

import type { DeepNullable } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  address: { street: string; avenue: string }
}

type UserNullable = DeepNullable<User>
         
type UserNullable = {
    name: string | null;
    address: {
        street: string | null;
        avenue: string | null;
    } | null;
}

`DeepNonNullable<Obj>`

Argument	Type	Description
`Obj`	`object`	The object to make deeply non-nullable.

import type { DeepNonNullable } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string | null
  address: {
    street: string | null
    avenue: string | null
  } | null
}

type UserNonNullable = DeepNonNullable<User>
          
type UserNonNullable = {
    name: string;
    address: {
        street: string;
        avenue: string;
    };
}

`DeepFilter<Obj, Predicate>`

Argument	Type	Description
`Obj`	`object`	The object to filter.
`Predicate`	`unknown`	The type to filter properties by.

import type { DeepFilter } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  age: number
  address: { street: string; avenue: string }
}

type Filtered = DeepFilter<User, string>
       
type Filtered = {
    name: string;
}

`DeepReplace<Obj, From, To>`

Argument	Type	Description
`Obj`	`object`	The object to replace types in.
`From`	`unknown`	The type to replace.
`To`	`unknown`	The type to use as a replacement.

import type { DeepReplace } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  age: number
  address: { street: string; avenue: string }
}

type Replaced = DeepReplace<User, string, number>
       
type Replaced = {
    name: number;
    age: number;
    address: {
        street: number;
        avenue: number;
    };
}

`DeepSet<Obj, Path, Value>`

Argument	Type	Description
`Obj`	`object`	The object to set a value in.
`Path`	`string`	The dot-separated path to set.
`Value`	`unknown`	The value type to set at the path.

import type { DeepSet } from "@halvaradop/ts-utility-types/deep"

interface User {
  name: string
  address: { street: string; avenue: string }
}

type Updated = DeepSet<User, "address.street", number>
      
type Updated = {
    name: string;
    address: {
        street: number;
        avenue: string;
    };
}

Deep Utilities

On this page