TypeScript Type Utils

Common errors

• Module 'typescript-type-utils' has no exported member 'MyType'. Did you mean to use 'import type'?

  cause Attempting to import a type using a standard ES module import without the 'type' keyword, leading TypeScript to expect a runtime export.
  fix Change `import { MyType }` to `import type { MyType }` to specify a type-only import.

• Cannot find name 'ExpectTrue'. Did you mean to import it from 'typescript-type-utils'?

  cause A utility type from the library was used in TypeScript code without being imported first, or with an incorrect name.
  fix Add the necessary type import at the top of your TypeScript file: `import type { ExpectTrue } from 'typescript-type-utils';`.

• TS2307: Cannot find module 'typescript-type-utils' or its corresponding type declarations.

  cause The package is not installed, or TypeScript cannot correctly locate its declaration files based on the project's `tsconfig.json` configuration.
  fix Ensure the package is installed via npm or yarn (`npm install typescript-type-utils` or `yarn add typescript-type-utils`). Verify that your `tsconfig.json` has `moduleResolution` set to a modern value like `NodeNext` or `Bundler` if applicable.

Warnings

• breaking Changes to core utility type definitions can lead to compile-time errors in consuming projects. Since this library contains only types, any modification to a type's signature is a breaking change for type consumers.
  Fix: Review compilation errors and adjust your code to the new type definitions. It is recommended to pin exact versions or use tilde (~) for minor version updates if strict type stability is crucial.
• gotcha Attempting to import types using standard JavaScript import syntax (e.g., `import { Type } from 'pkg'`) or CommonJS `require()` will result in build errors or runtime failures, as this library explicitly contains no runnable JavaScript code.
  Fix: Always use `import type { ... } from 'typescript-type-utils'` for importing utility types from this library to explicitly declare a type-only import.
• gotcha As a 0.1.0 package, while stable in concept, the specific API surface and type definitions might evolve rapidly in future minor versions. Relying on specific internal type structures could be fragile.
  Fix: Consider pinning exact versions for critical projects (`"typescript-type-utils": "0.1.0"`) or contribute to discussions to stabilize desired APIs if you require long-term stability for specific type shapes.

Install

• npm install typescript-type-utils npm
• yarn add typescript-type-utils yarn
• pnpm add typescript-type-utils pnpm

Imports

• ExpectTrue
  wrong:

  import { ExpectTrue } from 'typescript-type-utils'

  correct:

  import type { ExpectTrue } from 'typescript-type-utils'

  As this library ships only type declarations, `import type` is the correct syntax to prevent accidental runtime imports and ensure type-only usage.
• Equal
  wrong:

  const Equal = require('typescript-type-utils').Equal

  correct:

  import type { Equal } from 'typescript-type-utils'

  This package is a pure type library and does not export any runtime values, making CommonJS `require` unsuitable for its types.
• TupleToUnion
  wrong:

  import TupleToUnion from 'typescript-type-utils'

  correct:

  import type { TupleToUnion } from 'typescript-type-utils'

  All utility types are named exports. There is no default export from this library.

Quickstart

Demonstrates how to import and use utility types like `Equal`, `ExpectTrue`, and `TupleToUnion` for compile-time type assertions and transformations, highlighting the library's zero-runtime nature.

import type { Equal, ExpectTrue, TupleToUnion } from 'typescript-type-utils';

// Example 1: Basic equality check at compile time
type StringIsString = ExpectTrue<Equal<string, string>>; // This type assertion will pass
// type StringIsNumber = ExpectTrue<Equal<string, number>>; // Uncommenting this line would cause a compile-time error

// Example 2: Using Equal for structural type comparison
interface User { id: number; name: string; }
type UserAlias = { id: number; name: string; };
type UserTypesAreEqual = ExpectTrue<Equal<User, UserAlias>>; // Asserts structural equality

// Example 3: Transforming tuple types to union types
type MyTuple = [1, 'hello', true];
type UnionFromTuple = TupleToUnion<MyTuple>; // UnionFromTuple will be 1 | "hello" | true

// The types ensure correctness at compile-time. No runtime code is executed.
console.log("All type assertions passed at compile time if there are no errors in your IDE/console.");