TypeScript Type Immutability Checker

Common errors

• Error: "is-immutable-type" requires "typescript-eslint" v8.x but found v7.x.

  cause Using `is-immutable-type` v5.x or newer with an older `typescript-eslint` installation.
  fix Upgrade `typescript-eslint` to version 8.x or higher using `npm install --save-dev typescript-eslint@latest` or `yarn add --dev typescript-eslint@latest`.

• TypeError: Cannot read properties of undefined (reading 'getTypeChecker')

  cause The `program` argument passed to `getTypeImmutability` (or similar functions) is `undefined` or not a valid `ts.Program` instance.
  fix Ensure you are passing a properly initialized `ts.Program` object, which is usually obtained from `typescript.createProgram()` or from a tooling context like an ESLint rule's parser services.

• TS2345: Argument of type 'boolean' is not assignable to parameter of type 'Immutability'.

  cause Attempting to compare `Immutability.Unknown` directly with `===`, which returns `false` and might be incorrectly used in a conditional where an `Immutability` value is expected.
  fix Use the `isUnknown(immutability)` helper function instead of direct `immutability === Immutability.Unknown` comparison.

Warnings

• breaking Version 5.0.0 dropped support for `typescript-eslint` v7. Users must upgrade their `typescript-eslint` peer dependency to v8 to continue using `is-immutable-type`.
  Fix: Update `typescript-eslint` to v8 or higher in your project's dependencies.
• breaking Version 4.0.0 introduced breaking changes related to how types are handled, specifically concerning the 'Type' parameter in some core functions, likely due to the new 'allow for ignoring types' feature. While the changelog is terse, it suggests API adjustments for type resolution or processing.
  Fix: Review the official documentation or migration guides for v4.0.0 to understand specific changes to function signatures involving type parameters.
• gotcha When checking for `Immutability.Unknown`, direct comparison using `===` will always return `false`. Always use the `isUnknown()` helper function provided by the library.
  Fix: Replace `immutability === Immutability.Unknown` with `isUnknown(immutability)`.
• gotcha The library operates on a `ts.Program` instance to analyze types. This means it's designed to be used within a TypeScript compiler context, such as an ESLint plugin, a custom transformer, or other tooling that provides access to the full TypeScript AST and type checker.
  Fix: Ensure your usage context provides a valid `ts.Program` instance, typically derived from a `typescript.createProgram()` call or an ESLint parser context.

Install

• npm install is-immutable-type npm
• yarn add is-immutable-type yarn
• pnpm add is-immutable-type pnpm

Imports

• getTypeImmutability
  wrong:

  const getTypeImmutability = require('is-immutable-type').getTypeImmutability;

  correct:

  import { getTypeImmutability } from 'is-immutable-type';

  Primary function for checking type immutability; the package is ESM-first.
• Immutability
  wrong:

  const Immutability = require('is-immutable-type').Immutability;

  correct:

  import { Immutability } from 'is-immutable-type';

  TypeScript enum representing different levels of immutability.
• isReadonlyDeep
  wrong:

  import isReadonlyDeep from 'is-immutable-type/isReadonlyDeep';

  correct:

  import { isReadonlyDeep } from 'is-immutable-type';

  Helper function for checking if an `Immutability` value is `ReadonlyDeep` or `Immutable`. All utilities are named exports from the main package.
• isUnknown

  import { isUnknown } from 'is-immutable-type';

  Helper function specifically designed for checking `Immutability.Unknown`, as direct `===` comparison might yield unexpected results.

Quickstart

This example demonstrates how to use `getTypeImmutability` with a TypeScript program and AST node, showing how to interpret the returned `Immutability` enum value using helper functions.

import { Immutability, getTypeImmutability, isReadonlyDeep, isUnknown } from 'is-immutable-type';
import { hasType } from 'ts-api-utils';
import type ts from 'typescript';

/**
 * Demonstrates how to get and interpret the immutability of a TypeScript type.
 * This example requires a TypeScript Program instance and a Node from its AST.
 * @param program The TypeScript program instance.
 * @param node The AST node whose type's immutability is to be checked.
 */
function checkNodeImmutability(program: ts.Program, node: ts.Node) {
  const typeNodeOrType = hasType(node)
    ? // Use the TypeNode if it's available.
      node.type
    : // Otherwise, get the Type from the checker.
      program.getTypeChecker().getTypeAtLocation(node);

  // Ensure a type was found before proceeding
  if (!typeNodeOrType) {
    console.log(`Could not determine type for node at position ${node.pos}.`);
    return;
  }

  const immutability = getTypeImmutability(program, typeNodeOrType);

  if (isUnknown(immutability)) {
    console.log(`Node at ${node.pos} has 'Unknown' immutability.`);
  } else if (isReadonlyDeep(immutability)) {
    console.log(`Node at ${node.pos} has 'ReadonlyDeep' or 'Immutable' immutability.`);
  } else if (immutability === Immutability.ReadonlyShallow) {
    console.log(`Node at ${node.pos} has 'ReadonlyShallow' immutability.`);
  } else if (immutability === Immutability.Mutable) {
    console.log(`Node at ${node.pos} has 'Mutable' immutability.`);
  } else {
    console.log(`Node at ${node.pos} has an unexpected immutability state.`);
  }
}

// Example usage within a dummy context (requires a real ts.Program and ts.Node)
// For a runnable example, you'd typically run this within an ESLint rule or custom TS transform.
// const dummyProgram = /* A real ts.Program instance */; 
// const dummyNode = /* A real ts.Node instance */; 
// if (dummyProgram && dummyNode) {
//   checkNodeImmutability(dummyProgram, dummyNode);
// } else {
//   console.log("Please provide a valid TypeScript program and node for this example.");
// }