TypeScript Helper Types Collection

Common errors

• Type instantiation is excessively deep and possibly infinite.

  cause Using complex recursive helper types (like `PartialDeep`, `RequiredDeep`, or `ObjectLookupTuple`) from `helpertypes` on very deeply nested object structures or with older versions of the library, hitting TypeScript's default recursion depth limit.
  fix Upgrade `helpertypes` to the latest version (v0.0.19+), as many recursion issues have been fixed. If the problem persists with extremely deep types, consider manually increasing TypeScript's `--declarationDir` or `--maxNodeModuleJsDepth` compiler options, though this is often a sign of overly complex types.

• TypeError: (0 , helpertypes_1.PartialDeep) is not a function

  cause Attempting to import a type from `helpertypes` as if it were a runtime value in an ESM context, leading to a failed runtime import and execution.
  fix Change the import statement from `import { PartialDeep } from 'helpertypes';` to `import type { PartialDeep } from 'helpertypes';`. This explicitly tells TypeScript to only import the type definition, which is correctly stripped at compile time.

Warnings

• gotcha The `RequiredDeep` and `PartialDeep` types have undergone several bug fixes across minor versions (e.g., v0.0.16, v0.0.17). Users relying on their behavior in older versions might encounter subtle changes in type inference or edge case handling, especially with deeply nested or complex types. Ensure thorough type checking when upgrading.
  Fix: Upgrade to the latest version of `helpertypes` (v0.0.19 or newer) to benefit from the most stable implementations of `RequiredDeep` and `PartialDeep`. Review any complex type definitions that use these helpers after upgrading to ensure desired behavior.
• breaking The implementation of `ObjectLookupTuple` was replaced in v0.0.18 to address issues where it could exceed TypeScript's allowed recursive call limits, leading to compilation errors or incorrect type inference. While a fix, code that might have (erroneously) compiled with the previous, less robust implementation due to recursion limits might now behave differently or resolve types correctly.
  Fix: Upgrade to `helpertypes@0.0.18` or newer. If you were encountering recursion limit errors with `ObjectLookupTuple`, this fix should resolve them. Otherwise, verify that the type inference for paths you use with this helper remains correct.
• gotcha As a type-only library, `helpertypes` exports no runtime values. Attempting to `import { SomeType } from 'helpertypes';` without `type` or using `require()` will result in runtime errors (e.g., `TypeError: (0 , helpertypes_1.PartialDeep) is not a function` in ESM contexts or `undefined` in CJS) or TypeScript compiler warnings.
  Fix: Always use `import type { SomeType } from 'helpertypes';` to explicitly import only the type definitions. This helps prevent accidental runtime imports and ensures correct usage.

Install

• npm install helpertypes npm
• yarn add helpertypes yarn
• pnpm add helpertypes pnpm

Imports

• PartialDeep
  wrong:

  import { PartialDeep } from 'helpertypes';

  correct:

  import type { PartialDeep } from 'helpertypes';

  Always use `import type` as this library exports only TypeScript types, not runtime values.
• RequiredDeep
  wrong:

  const { RequiredDeep } = require('helpertypes');

  correct:

  import type { RequiredDeep } from 'helpertypes';

  Like all types from this package, it should be imported using `import type` and is not available via CommonJS `require`.
• ObjectLookupString

  import type { ObjectLookupString } from 'helpertypes';

  This type, like others in helpertypes, is purely for design-time type checking and has no runtime representation. Use `import type`.

Quickstart

This quickstart demonstrates how to install `helpertypes` and use `PartialDeep`, `RequiredDeep`, and `ObjectLookupString` to create new derived types from existing interfaces, showcasing deep optionality, deep requiredness, and string-based path lookups.

import type { PartialDeep, RequiredDeep, ObjectLookupString } from 'helpertypes';

interface UserProfile {
  id: string;
  name: string;
  settings: {
    theme: 'dark' | 'light';
    notifications: boolean;
  };
  tags?: string[];
}

// Create a deeply partial version of UserProfile
type PartialUserProfile = PartialDeep<UserProfile>;

const partialUser: PartialUserProfile = {
  id: 'abc-123',
  settings: { theme: 'dark' } // Only define some nested properties
};

console.log(partialUser);

// Create a deeply required version, making all optional properties required (if possible)
type FullyRequiredUserProfile = RequiredDeep<UserProfile>;

const fullUser: FullyRequiredUserProfile = {
  id: 'def-456',
  name: 'Jane Doe',
  settings: { theme: 'light', notifications: true },
  tags: [] // 'tags' is now required
};

console.log(fullUser);

interface NestedObject {
  a: { b: { c: string } };
  d: number;
}

// Look up a string path in a nested object type
type PathA_B_C = ObjectLookupString<NestedObject, 'a.b.c'>; // Expected: string
type PathD = ObjectLookupString<NestedObject, 'd'>;         // Expected: number

// Type checking for example usage (won't run in JS)
const val1: PathA_B_C = 'hello';
// @ts-expect-error - Type 'number' is not assignable to type 'string'.
const val2: PathA_B_C = 123;

console.log('Demonstrating type utilities. Check TypeScript compiler for full effect.');