type-samurai

Common errors

• Type instantiation is excessively deep and possibly infinite. (2589)

  cause Too many recursive type evaluations or very deep generic type instantiations.
  fix Simplify the type arguments passed to `type-samurai` utilities, or break down a single complex type into multiple intermediate types. Increase TypeScript's `maxNodeModuleJsDepth` (though this is often a band-aid).

• Expression produces a union type that is too complex to represent. (2590)

  cause The resulting union type from a `type-samurai` operation (especially with large number types or string manipulations) exceeds TypeScript's internal complexity limits.
  fix Restructure the types to produce less expansive union types. Consider if the full range of values needs to be strictly typed at compile-time or if some runtime checks are more appropriate.

• Cannot find module 'type-samurai' or its corresponding type declarations. (2307)

  cause The package was likely installed without `--save-dev` or TypeScript is not configured to include `node_modules/@types` or the library's own type declarations.
  fix Ensure `type-samurai` is installed using `npm install --save-dev type-samurai`, and `tsconfig.json` includes `node_modules` in its `include` or `files` array, or that `typeRoots` is correctly configured if custom paths are used.

Warnings

• gotcha Extremely complex or deeply recursive type computations using `type-samurai` utilities can lead to TypeScript compiler errors like 'Type instantiation is excessively deep and possibly infinite' (error TS2589) or 'Expression produces a union type that is too complex to represent' (error TS2590).
  Fix: Refactor complex type logic into smaller, composable types. Consider if the complexity is truly necessary or if a simpler runtime check could suffice.
• gotcha While `type-samurai` is zero-runtime, heavy usage of its advanced types can significantly increase TypeScript compilation times, especially in large codebases.
  Fix: Monitor compilation times. Use these advanced types judiciously for critical type safety needs rather than for every minor type manipulation. Consider creating simpler type aliases for common patterns.
• breaking As a library heavily relying on advanced TypeScript features, `type-samurai` may introduce breaking changes or require specific minimum TypeScript versions for full functionality due to changes in TypeScript's type system.
  Fix: Always consult the library's GitHub releases or `package.json`'s `peerDependencies` (if any) for the officially supported TypeScript version. Pin your TypeScript version to avoid unexpected breaking changes in type inference.

Install

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

Imports

• Sum
  wrong:

  import { Sum } from 'type-samurai'

  correct:

  import type { Sum } from 'type-samurai'

  This library exports only types. Always use `import type` to avoid runtime errors or unnecessary imports.
• If
  wrong:

  const If = require('type-samurai')

  correct:

  import type { If } from 'type-samurai'

  CommonJS `require` syntax is not supported as this is a type-only module for ESM environments, primarily used for compile-time type checking.
• IsAny
  wrong:

  import * as TypeSamurai from 'type-samurai'

  correct:

  import type { IsAny } from 'type-samurai'

  For optimal performance and clarity, prefer named type imports over namespace imports when only a few specific types are needed.

Quickstart

Demonstrates type-level arithmetic, conditional type evaluation, and type introspection, showcasing the library's compile-time utility without generating runtime code.

import type { Sum, IfExtends, IsNever, ReturnItselfIfExtends } from 'type-samurai';

// Example 1: Type-level arithmetic
type Total = Sum<123, 456>; // Evaluates to 579
// console.log(Total); // This is a type, not a runtime value

// Example 2: Conditional types
type ResultBasedOnExtension = IfExtends<string, string | number, 'Is String', 'Not String'>; // 'Is String'
type AnotherResult = IfExtends<number, string, 'Is String', 'Not String'>; // 'Not String'

// Example 3: Type introspection
type CheckNever = IsNever<'hello'>; // false
type CheckNeverActual = IsNever<never>; // true

// Example 4: Returning itself conditionally
type MyType = ReturnItselfIfExtends<{ a: string }, object, { a: string }>; // { a: string }
type FallbackType = ReturnItselfIfExtends<null, object, 'Not an object'>; // 'Not an object'

// These operations are purely compile-time. There is no runtime JavaScript code generated.