TypeScript Miscellaneous Utilities

Common errors

• Cannot find name 'Dict'.

  cause The utility type was not imported into the current file.
  fix Add the necessary import statement: `import { Dict } from 'typescript-miscellaneous';` (or the specific type you are using).

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

  cause An incorrect input type was provided to one of the utility types, or the resulting type was misused.
  fix Carefully review the documentation for the specific utility type you are using and ensure your input types and usage patterns align with its expected behavior.

• An import path cannot end with a '.js' extension when 'resolveJsonModule' is enabled. Consider importing 'foo' instead.

  cause This package primarily exports TypeScript types. While the error might be generic to module resolution, it could imply misconfiguration if you're trying to import types from a `.js` output or incorrectly configuring module resolution for type files.
  fix Ensure your `tsconfig.json` `moduleResolution` is set to `node` or `bundler` and `allowSyntheticDefaultImports` and `esModuleInterop` are enabled if using default imports (though this library primarily uses named type imports). Avoid adding `.js` extensions to type import paths.

Warnings

• breaking This library explicitly requires TypeScript version 3.0.0 or higher. Using it with older TypeScript compilers will result in compilation errors due to reliance on newer type system features.
  Fix: Upgrade your project's TypeScript dependency to version 3.0.0 or newer in `package.json` and ensure your `tsconfig.json` targets an appropriate ES version.
• gotcha As a library in its 0.x.x version, the API surface might undergo breaking changes in minor or patch releases before a stable 1.0.0 version is published. Always review the changelog when upgrading.
  Fix: Pin the exact version (e.g., `0.1.1`) or a compatible range (e.g., `^0.1.0`) in your `package.json` and regularly review release notes for updates.
• gotcha Advanced utility types, especially when deeply nested or heavily composed, can sometimes lead to increased TypeScript compilation times and memory usage. Monitor build performance in large codebases.
  Fix: Optimize other parts of your TypeScript configuration, consider breaking down overly complex types, or use performance profiling tools for TypeScript compilation to identify bottlenecks.
• gotcha Some complex type manipulations might result in unexpected type inference behavior when combined with other highly generic types or specific TypeScript strictness settings. Debug type issues using TypeScript's `--traceResolution` or IDE type inspection tools.
  Fix: Simplify surrounding types, provide explicit type arguments where inference struggles, or consult the TypeScript documentation for advanced type compatibility rules.

Install

• npm install typescript-miscellaneous npm
• yarn add typescript-miscellaneous yarn
• pnpm add typescript-miscellaneous pnpm

Imports

• Dict
  wrong:

  const Dict = require('typescript-miscellaneous').Dict;

  correct:

  import { Dict } from 'typescript-miscellaneous';

  This is a TypeScript type export and cannot be imported or used as a runtime value. Attempting to use `require` will result in a runtime error or a type-related compilation failure.
• UnionToIntersection
  wrong:

  const UnionToIntersection = require('typescript-miscellaneous').UnionToIntersection;

  correct:

  import { UnionToIntersection } from 'typescript-miscellaneous';

  This is a TypeScript type export, used for compile-time type manipulation. It has no runtime representation and cannot be imported via `require`.
• ElementOf
  wrong:

  import * as Lib from 'typescript-miscellaneous'; type El = Lib.ElementOf<any>;

  correct:

  import { ElementOf } from 'typescript-miscellaneous';

  While importing the entire module might work for types in some configurations, the direct named import `import { ElementOf } from 'typescript-miscellaneous';` is the idiomatic and clearer way for type-only imports.

Quickstart

This quickstart demonstrates the usage of `Dict` for creating flexible object types, `ElementOf` for inferring types from tuples/arrays, and `ParametersOf`/`ReturnOf` for extracting function signature details.

import { Dict, ElementOf, ParametersOf, ReturnOf } from 'typescript-miscellaneous';

// Example 1: Dict - create a dictionary-like type with mixed keys and values
type MyComplexDict = Dict<
  'id' | 'name' | 'age' | 0 | 1,
  string | number
>;

const user: MyComplexDict = {
  id: 'uuid-123',
  name: 'Alice',
  age: 30,
  0: 'first_val',
  1: 123
};

console.log(`User ID: ${user.id}, Age: ${user.age}`);

// Example 2: ElementOf - extract the union type of elements from an array/tuple
type Colors = ['red', 'green', 'blue'];
type Color = ElementOf<Colors>; // Expected: 'red' | 'green' | 'blue'

const favoriteColor: Color = 'green';
// const invalidColor: Color = 'yellow'; // This would correctly cause a TypeScript error

console.log(`Favorite color: ${favoriteColor}`);

// Example 3: ParametersOf and ReturnOf - infer parts of a function signature
function greet(name: string, age: number): string {
  return `Hello, ${name}! You are ${age} years old.`;
}

type GreetParams = ParametersOf<typeof greet>; // Expected: [name: string, age: number]
type GreetReturn = ReturnOf<typeof greet>;   // Expected: string

const params: GreetParams = ['Bob', 25];
const greeting: GreetReturn = greet(...params);

console.log(greeting);