{"id":14634,"library":"is-immutable-type","title":"TypeScript Type Immutability Checker","description":"is-immutable-type is a TypeScript utility library designed to statically analyze the immutability of TypeScript types within a given program context. It provides detailed classifications for types, distinguishing between `Immutable` (deeply read-only, no modifications possible), `ReadonlyDeep` (deeply immutable data, but methods are not), `ReadonlyShallow` (shallowly immutable, but deep values are not), `Mutable` (shallowly mutable), and `Unknown` (immutability could not be determined). The library is currently on version 5.0.1 and maintains an active release cadence, with several major and minor versions released recently, indicating continuous development. Its key differentiators include precise immutability definitions and a robust override mechanism, allowing developers to specify immutability for types where static analysis alone might be insufficient. It is typically integrated into TypeScript tooling like ESLint plugins for advanced type-aware linting.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/RebeccaStevens/is-immutable-type","tags":["javascript","readonly","immutable","type","typescript"],"install":[{"cmd":"npm install is-immutable-type","lang":"bash","label":"npm"},{"cmd":"yarn add is-immutable-type","lang":"bash","label":"yarn"},{"cmd":"pnpm add is-immutable-type","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, often used in conjunction for linting rules.","package":"eslint","optional":false},{"reason":"Peer dependency, required for type analysis, specifically versions >=4.7.4.","package":"typescript","optional":false},{"reason":"Used in examples for robust TypeScript API interaction, though not a direct peer dependency of the package itself, it's a practical dependency for common usage.","package":"ts-api-utils","optional":true}],"imports":[{"note":"Primary function for checking type immutability; the package is ESM-first.","wrong":"const getTypeImmutability = require('is-immutable-type').getTypeImmutability;","symbol":"getTypeImmutability","correct":"import { getTypeImmutability } from 'is-immutable-type';"},{"note":"TypeScript enum representing different levels of immutability.","wrong":"const Immutability = require('is-immutable-type').Immutability;","symbol":"Immutability","correct":"import { Immutability } from 'is-immutable-type';"},{"note":"Helper function for checking if an `Immutability` value is `ReadonlyDeep` or `Immutable`. All utilities are named exports from the main package.","wrong":"import isReadonlyDeep from 'is-immutable-type/isReadonlyDeep';","symbol":"isReadonlyDeep","correct":"import { isReadonlyDeep } from 'is-immutable-type';"},{"note":"Helper function specifically designed for checking `Immutability.Unknown`, as direct `===` comparison might yield unexpected results.","symbol":"isUnknown","correct":"import { isUnknown } from 'is-immutable-type';"}],"quickstart":{"code":"import { Immutability, getTypeImmutability, isReadonlyDeep, isUnknown } from 'is-immutable-type';\nimport { hasType } from 'ts-api-utils';\nimport type ts from 'typescript';\n\n/**\n * Demonstrates how to get and interpret the immutability of a TypeScript type.\n * This example requires a TypeScript Program instance and a Node from its AST.\n * @param program The TypeScript program instance.\n * @param node The AST node whose type's immutability is to be checked.\n */\nfunction checkNodeImmutability(program: ts.Program, node: ts.Node) {\n  const typeNodeOrType = hasType(node)\n    ? // Use the TypeNode if it's available.\n      node.type\n    : // Otherwise, get the Type from the checker.\n      program.getTypeChecker().getTypeAtLocation(node);\n\n  // Ensure a type was found before proceeding\n  if (!typeNodeOrType) {\n    console.log(`Could not determine type for node at position ${node.pos}.`);\n    return;\n  }\n\n  const immutability = getTypeImmutability(program, typeNodeOrType);\n\n  if (isUnknown(immutability)) {\n    console.log(`Node at ${node.pos} has 'Unknown' immutability.`);\n  } else if (isReadonlyDeep(immutability)) {\n    console.log(`Node at ${node.pos} has 'ReadonlyDeep' or 'Immutable' immutability.`);\n  } else if (immutability === Immutability.ReadonlyShallow) {\n    console.log(`Node at ${node.pos} has 'ReadonlyShallow' immutability.`);\n  } else if (immutability === Immutability.Mutable) {\n    console.log(`Node at ${node.pos} has 'Mutable' immutability.`);\n  } else {\n    console.log(`Node at ${node.pos} has an unexpected immutability state.`);\n  }\n}\n\n// Example usage within a dummy context (requires a real ts.Program and ts.Node)\n// For a runnable example, you'd typically run this within an ESLint rule or custom TS transform.\n// const dummyProgram = /* A real ts.Program instance */; \n// const dummyNode = /* A real ts.Node instance */; \n// if (dummyProgram && dummyNode) {\n//   checkNodeImmutability(dummyProgram, dummyNode);\n// } else {\n//   console.log(\"Please provide a valid TypeScript program and node for this example.\");\n// }","lang":"typescript","description":"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."},"warnings":[{"fix":"Update `typescript-eslint` to v8 or higher in your project's dependencies.","message":"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`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Review the official documentation or migration guides for v4.0.0 to understand specific changes to function signatures involving type parameters.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Replace `immutability === Immutability.Unknown` with `isUnknown(immutability)`.","message":"When checking for `Immutability.Unknown`, direct comparison using `===` will always return `false`. Always use the `isUnknown()` helper function provided by the library.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your usage context provides a valid `ts.Program` instance, typically derived from a `typescript.createProgram()` call or an ESLint parser context.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"Using `is-immutable-type` v5.x or newer with an older `typescript-eslint` installation.","error":"Error: \"is-immutable-type\" requires \"typescript-eslint\" v8.x but found v7.x."},{"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.","cause":"The `program` argument passed to `getTypeImmutability` (or similar functions) is `undefined` or not a valid `ts.Program` instance.","error":"TypeError: Cannot read properties of undefined (reading 'getTypeChecker')"},{"fix":"Use the `isUnknown(immutability)` helper function instead of direct `immutability === Immutability.Unknown` comparison.","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.","error":"TS2345: Argument of type 'boolean' is not assignable to parameter of type 'Immutability'."}],"ecosystem":"npm"}