Deep Utility Types

Common errors

• Cannot find module 'deep-utility-types' or its corresponding type declarations.

  cause The package is not installed, or TypeScript cannot locate its declarations, possibly due to incorrect `tsconfig.json` setup or trying to import in a non-TypeScript file.
  fix Install the package: `npm install --save-dev deep-utility-types` or `yarn add --dev deep-utility-types`. Ensure your files are being processed by TypeScript and `tsconfig.json` includes the relevant directories.

• Type 'Partial<OmittedType>' is not assignable to type 'OmittedType'. Property 'foo2' is missing in type 'Partial<OmittedType>' but required in type 'OmittedType'.

  cause Incorrectly applying the deep utility type, or trying to assign an incomplete object where properties were expected to be optional but remain required by the new type definition.
  fix Carefully review the keys provided to `DeepOmit` or `DeepPick` to ensure they accurately reflect the desired output type. If properties should be optional, consider using `DeepOptional` or explicitly marking the resultant type as `Partial<T>` if the intention is to allow partial assignment.

Warnings

• gotcha This library provides only TypeScript type definitions; it has no runtime JavaScript code. Attempting to use `require()` or expecting runtime behavior will result in errors.
  Fix: Ensure you are using `import` statements and only leveraging these constructs at the TypeScript compilation level, not at runtime.
• breaking When working with `KeysAsDotNotation` and union types, versions prior to v1.3.1 might incorrectly handle the union, leading to unexpected or incomplete key paths.
  Fix: Update to `deep-utility-types@1.3.1` or newer to ensure correct handling of unions within `KeysAsDotNotation`.
• gotcha The `KeysAsDotNotation` and `DefaultIgnoredTypes` were explicitly exposed as exportable types starting from version 1.3.0. If you are on an older version, these types will not be directly importable.
  Fix: Upgrade to `deep-utility-types@1.3.0` or later to access `KeysAsDotNotation` and `DefaultIgnoredTypes`.
• gotcha For types with very large or complex properties (like many built-in JavaScript classes such as `Function`, `Map`, `Promise`), not utilizing the `IgnoredTypes` generic parameter can lead to degraded type-checker performance and cluttered autocompletion suggestions.
  Fix: Pass the specific types to ignore as the third generic argument (e.g., `DeepOmit<MyType, 'key', SomeLargeClass>`) or leverage the exported `DefaultIgnoredTypes`.

Install

• npm install deep-utility-types npm
• yarn add deep-utility-types yarn
• pnpm add deep-utility-types pnpm

Imports

• DeepOmit
  wrong:

  const { DeepOmit } = require('deep-utility-types');

  correct:

  import { DeepOmit } from 'deep-utility-types';

  This library ships only TypeScript types and is intended for ES module imports in modern TypeScript projects. CommonJS 'require' will not work as it's a type-only package.
• DeepPick

  import { DeepPick } from 'deep-utility-types';

  Used for picking nested properties via dot notation. Works identically to DeepOmit in terms of import pattern.
• KeysAsDotNotation

  import { KeysAsDotNotation } from 'deep-utility-types';

  This utility type was exposed publicly in v1.3.0. Users on older versions will not be able to import it directly.

Quickstart

Demonstrates how to use `DeepOmit` to create a new type by removing specified nested properties using dot notation.

import { DeepOmit } from 'deep-utility-types';

type UserProfile = {
  id: string;
  name: string;
  contact: {
    email: string;
    phone: string;
    address: {
      street: string;
      city: string;
      zip: string;
    };
  };
  settings: {
    notifications: boolean;
    theme: 'light' | 'dark';
  };
};

// Create a type that omits the user's phone number and notification setting
type PublicUserProfile = DeepOmit<UserProfile, 'contact.phone' | 'settings.notifications'>;

const user: PublicUserProfile = {
  id: 'user-123',
  name: 'John Doe',
  contact: {
    email: 'john.doe@example.com',
    address: {
      street: '123 Main St',
      city: 'Anytown',
      zip: '12345',
    },
  },
  settings: {
    theme: 'dark',
  },
};

console.log(user);