Type-Fest

Common errors

• SyntaxError: Named export 'Except' not found. The requested module 'type-fest' does not provide an export named 'Except'

  cause Attempting to import `type-fest` types in a CommonJS environment, or using an incorrect import syntax for ESM.
  fix Ensure your project is configured for ESM and use `import type { Except } from 'type-fest';`. If using `require()`, switch to ESM `import` statements or use `type-fest@4` or earlier.

• Type 'string | undefined' is not assignable to type 'string'.

  cause Your `tsconfig.json` does not have `"strict": true` enabled, leading to less precise type inference, especially when working with optional properties or null/undefined values, which `type-fest` often helps manage in a strict way.
  fix Add `"strict": true` to your `compilerOptions` in `tsconfig.json`. Review and fix any new type errors that appear, as they usually indicate genuine potential runtime issues.

• error TS2307: Cannot find module 'type-fest' or its corresponding type declarations.

  cause TypeScript version is too old, the package is not installed correctly, or module resolution issues.
  fix Ensure `npm install type-fest` has been run. Verify your TypeScript version is `>=5.9`. Check your `tsconfig.json`'s `moduleResolution` and `module` settings are compatible with ESM and modern TypeScript best practices.

Warnings

• breaking Type-Fest versions 4.x and earlier supported CommonJS (CJS) modules. Starting with version 5.0.0, the library is exclusively ESM-first and no longer provides CJS exports. Attempting to `require()` Type-Fest will result in a runtime error.
  Fix: Convert your project to use ECMAScript Modules (ESM) and use `import type { ... } from 'type-fest';`. If unable to convert, you may need to stick to an older major version (e.g., `type-fest@4`).
• breaking Type-Fest requires TypeScript version 5.9 or higher. Using an older TypeScript version will lead to compilation errors due to reliance on newer TypeScript features and syntax.
  Fix: Upgrade your TypeScript compiler to version 5.9 or newer. Ensure your `package.json` and project configuration (e.g., `engines.node`) reflect this requirement.
• gotcha Many Type-Fest types are designed to work optimally and correctly infer types only when `strict: true` is enabled in your `tsconfig.json`. Without strict mode, some types may behave unexpectedly or provide less precise results.
  Fix: Ensure your `tsconfig.json` has `"strict": true` under `"compilerOptions"`. This is a recommended best practice for all modern TypeScript projects.
• gotcha When importing types from `type-fest`, always use the `import type` syntax (`import type { TypeName } from 'type-fest';`). While not strictly an error in all cases, using `import { TypeName } from 'type-fest';` (without `type`) can sometimes lead to runtime import errors in certain build environments or with specific bundlers, as `type-fest` only exports types, not runnable JavaScript values.
  Fix: Always prefix type imports with `type` (e.g., `import type { Except } from 'type-fest';`).

Install

• npm install type-fest npm
• yarn add type-fest yarn
• pnpm add type-fest pnpm

Imports

• Except
  wrong:

  import {Except} from 'type-fest';

  correct:

  import type {Except} from 'type-fest';

  Always use 'import type' for type-only imports to prevent accidental runtime imports and ensure compatibility with ESM-only modules.
• Merge
  wrong:

  const {Merge} = require('type-fest');

  correct:

  import type {Merge} from 'type-fest';

  Type-Fest is an ESM-only package since v5. Using CommonJS 'require()' will result in a runtime error. Ensure 'import type' is used for type-only imports.
• PackageJson
  wrong:

  import {PackageJson} from 'type-fest/source/package-json';

  correct:

  import type {PackageJson} from 'type-fest';

  While individual types are often organized into files, the recommended and stable import path is directly from the main 'type-fest' package. Ensure to use 'import type'.

Quickstart

Demonstrates the usage of 'Except', 'Merge', and 'Simplify' types to create new, refined types from existing interfaces, showcasing type composition.

import type {Except, Merge, Simplify} from 'type-fest';

interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
  updatedAt?: Date;
}

interface UserProfile {
  bio: string;
  website?: string;
}

// Create a new user type that excludes 'id' and 'createdAt'
type NewUser = Except<User, 'id' | 'createdAt'>;

// Merge the new user type with a profile to create a complete user
type FullUser = Simplify<Merge<NewUser, UserProfile>>;

const newUser: FullUser = {
  name: 'Alice Wonderland',
  email: 'alice@example.com',
  bio: 'Exploring type safety in Wonderland.',
  website: 'https://alice.example.com'
};

console.log(newUser);

// Demonstrating a common pattern with strict mode
// Type-fest types are designed with strict mode in mind.
// For example, if 'updatedAt' was not optional and not provided, 
// TypeScript would catch the missing property if strict: true is enabled.
const partialUserUpdate: Partial<NewUser> = { name: 'Alice Smith' };
console.log(partialUserUpdate);