Essential TypeScript Utility Types

Common errors

• Cannot find module 'util-ts-types' or its corresponding type declarations.

  cause The package is not installed, or your TypeScript configuration (e.g., `compilerOptions.typeRoots`, `paths`) is incorrect, or you are trying to `require()` it in a runtime context.
  fix Ensure 'util-ts-types' is listed in your `package.json` and installed. Verify `tsconfig.json` paths. For type-only imports, ensure `import type` syntax is used.

• 'util-ts-types' has no exported member 'SomeType'. Did you mean to use a default import?

  cause You are trying to import a type that is not actually exported by the library, or the case of the type name is incorrect.
  fix Check the `index.d.ts` file within the `util-ts-types` package to confirm the exact names and exports available. Adjust your import statement accordingly.

• Type 'X' is not assignable to type 'Y'.

  cause A utility type from `util-ts-types` was applied, but the resulting type `Y` is not compatible with the expected type `X` in your assignment or function call.
  fix Review the definition of the utility type and how it transforms `X` into `Y`. Adjust your input type or expected type to match the transformation, or rethink the use of that specific utility type.

Warnings

• gotcha This package is explicitly marked as '(Private)' in its README. While functional, it might not adhere to standard public API stability guarantees. Consumers should be aware that breaking changes might occur without semantic versioning considerations typical for public npm packages.
  Fix: Consider mirroring or vendoring essential types for critical internal projects if long-term stability or public dependency is a concern. Avoid using in external-facing libraries without careful consideration.
• gotcha As a type-only library, `util-ts-types` contains no runtime JavaScript code. Attempting to import it using `require()` in CommonJS environments or directly referencing it as a runtime dependency will lead to module resolution errors or unexpected behavior at runtime.
  Fix: Always use `import type { ... } from 'util-ts-types';` for all imports to explicitly declare them as type-only, which helps bundlers and TypeScript compiler optimize correctly.
• gotcha The specific utility types provided by this package are not detailed in the truncated README. There's a risk that inferred or commonly expected utility types (e.g., `DeepPartial`, `Mutable`) may not actually be exported, leading to 'has no exported member' errors.
  Fix: Consult the package's `index.d.ts` file or source code directly to verify available exports. If specific types are missing, consider contributing to the private repository or implementing them locally.
• gotcha Reliance on specific TypeScript versions: Utility type libraries often leverage advanced TypeScript features. While `1.0.0` suggests stability, older TypeScript versions might not fully support all internal type definitions or lead to unexpected type inference issues.
  Fix: Ensure your project's `typescript` dependency meets or exceeds the version used to develop `util-ts-types`. If issues arise, try updating your TypeScript compiler.

Install

• npm install util-ts-types npm
• yarn add util-ts-types yarn
• pnpm add util-ts-types pnpm

Imports

• DeepPartial
  wrong:

  import { DeepPartial } from 'util-ts-types';

  correct:

  import type { DeepPartial } from 'util-ts-types';

  Always use 'import type' for type-only exports to ensure no runtime code is bundled or executed, improving tree-shaking and preventing module resolution errors in some environments.
• Mutable
  wrong:

  const { Mutable } = require('util-ts-types');

  correct:

  import type { Mutable } from 'util-ts-types';

  This package exports only TypeScript types; attempting to 'require' it in CommonJS will result in a runtime error as there is no corresponding JavaScript module.
• Maybe
  wrong:

  import * as UtilTypes from 'util-ts-types';

  correct:

  import type { Maybe } from 'util-ts-types';

  While 'import * as' syntax might be technically valid for type imports, it's generally best practice to use named type imports for clarity and better tooling support when specific types are known.

Quickstart

This quickstart demonstrates the application of hypothetical `DeepPartial`, `Mutable`, and `Maybe` utility types to transform existing TypeScript interfaces and types, showcasing their primary use cases in data manipulation and type refinement.

import type { DeepPartial, Mutable, Maybe } from 'util-ts-types';

// Imagine util-ts-types provides these utilities:

interface UserProfile {
  readonly id: string;
  name: string;
  email: string;
  settings?: { theme: string; notifications: boolean };
}

// DeepPartial: Makes all properties and sub-properties optional and mutable.
type PartialUserProfile = DeepPartial<UserProfile>;

const updates: PartialUserProfile = {
  name: 'Jane Doe',
  settings: { theme: 'dark' } // 'notifications' is optional
};

// Mutable: Removes 'readonly' modifiers from properties.
type WritableUserProfile = Mutable<UserProfile>;

let user: WritableUserProfile = {
  id: 'abc-123', // 'id' is now writable
  name: 'John Doe',
  email: 'john@example.com'
};
user.id = 'new-id-456'; // This would error without Mutable

// Maybe: Wraps a type to include 'null' or 'undefined'.
type OptionalEmail = Maybe<string>;

const primaryEmail: OptionalEmail = 'user@example.com';
const secondaryEmail: OptionalEmail = null;
const tertiaryEmail: OptionalEmail = undefined;

console.log(`User email: ${primaryEmail ?? 'Not provided'}`);

// Function demonstrating usage
function updateProfile(current: UserProfile, patch: PartialUserProfile): UserProfile {
  return { ...current, ...patch, settings: { ...current.settings, ...patch.settings } };
}

const initialProfile: UserProfile = { id: '1', name: 'Original', email: 'orig@example.com' };
const updated = updateProfile(initialProfile, { name: 'New Name' });
console.log(`Updated profile name: ${updated.name}`);