Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
getTypeImmutability
✓ import { getTypeImmutability } from 'is-immutable-type';
✗ const getTypeImmutability = require('is-immutable-type').getTypeImmutability;
Primary function for checking type immutability; the package is ESM-first.
Immutability
✓ import { Immutability } from 'is-immutable-type';
✗ const Immutability = require('is-immutable-type').Immutability;
TypeScript enum representing different levels of immutability.
isReadonlyDeep
✓ import { isReadonlyDeep } from 'is-immutable-type';
✗ import isReadonlyDeep from 'is-immutable-type/isReadonlyDeep';
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.
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.");
// }
Errors
Common errors & fixes
Error: "is-immutable-type" requires "typescript-eslint" v8.x but found v7.x.
Using `is-immutable-type` v5.x or newer with an older `typescript-eslint` installation.
fixUpgrade `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')
The `program` argument passed to `getTypeImmutability` (or similar functions) is `undefined` or not a valid `ts.Program` instance.
fixEnsure 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'.
Attempting to compare `Immutability.Unknown` directly with `===`, which returns `false` and might be incorrectly used in a conditional where an `Immutability` value is expected.
fixUse the `isUnknown(immutability)` helper function instead of direct `immutability === Immutability.Unknown` comparison.
Audit
Dependencies
eslintrequiredPeer dependency, often used in conjunction for linting rules.
typescriptrequiredPeer dependency, required for type analysis, specifically versions >=4.7.4.
ts-api-utilsoptionalUsed 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.