eslint-plugin-ts-type-forge
v0.8.28
Published
ESLint rules that steer type declarations toward ts-type-forge idioms.
Downloads
3,499
Maintainers
Readme
eslint-plugin-ts-type-forge
ESLint rules that steer TypeScript type declarations toward
ts-type-forge idioms — replacing
hand-rolled uniform tuple spellings with the library's named length-constrained
tuple types, and the standard library's under-specified Exclude / Extract /
Omit / Pick / Record with counterparts that state what was left implicit.
Every rewrite is type-preserving.
Installation
npm install --save-dev eslint-plugin-ts-type-forgeRequires ESLint 9+ (flat config) and TypeScript. No rule is type-aware, so a configured TypeScript project is not required.
Usage (flat config)
The plugin ships a recommended config preset that registers the plugin and
turns on every rule at error:
// eslint.config.mts
import { eslintPluginTsTypeForge } from 'eslint-plugin-ts-type-forge';
export default [eslintPluginTsTypeForge.configs.recommended];Since the preset is a plain flat-config object, individual rules can be adjusted by a later config entry — for instance to pass options:
// eslint.config.mts
import {
eslintPluginTsTypeForge,
type EslintTsTypeForgeRules,
} from 'eslint-plugin-ts-type-forge';
export default [
eslintPluginTsTypeForge.configs.recommended,
{
rules: {
'ts-type-forge/prefer-canonical-length-constrained-tuple': [
'error',
{ importStyle: 'global' },
],
} satisfies Partial<EslintTsTypeForgeRules>,
},
];Or register the plugin yourself and pick the rules one by one:
// eslint.config.mts
import {
eslintPluginTsTypeForge,
type EslintTsTypeForgeRules,
} from 'eslint-plugin-ts-type-forge';
export default [
{
plugins: { 'ts-type-forge': eslintPluginTsTypeForge },
rules: {
'ts-type-forge/no-side-effect-import': 'error',
// A rule with options is typed to be given them.
'ts-type-forge/prefer-canonical-length-constrained-tuple': [
'error',
{},
],
} satisfies Partial<EslintTsTypeForgeRules>,
},
];Rules
| Rule | Fix | Description |
| :------------------------------------------ | :--------- | :--------------------------------------------------------------------------------------------------------------------- |
| prefer-canonical-length-constrained-tuple | autofix | Replace hand-rolled uniform tuple spellings with the canonical ts-type-forge tuple type. |
| prefer-canonical-mutable-record | autofix | Replace Mutable<Record<K, V>> with the canonical MutableRecord<K, V>. |
| prefer-strict-or-relaxed-utility-type | suggestion | Replace Exclude / Extract / Omit / Pick with the Strict* or Relaxed* variant. |
| prefer-readonly-or-mutable-record | suggestion | Replace Record with ReadonlyRecord or MutableRecord. |
| no-side-effect-import | autofix | Remove a side-effect-only import 'ts-type-forge';, which binds no name and has no runtime entry point to resolve to. |
prefer-canonical-length-constrained-tuple
It covers the whole uniform-tuple family:
| spelling | readonly target | mutable target |
| :------------------------- | :----------------------- | :------------------------------ |
| [V, ...V[]] | NonEmptyTuple<V> | MutableNonEmptyTuple<V> |
| [V, …×N, ...V[]] (N ≥ 2) | MinLengthTuple<N, V> | MutableMinLengthTuple<N, V> |
| [V, …×N] (N ≥ 2) | FixedLengthTuple<N, V> | MutableFixedLengthTuple<N, V> |
Why the *Tuple types and not NonEmptyArray / MinLengthArray
The *Array family (NonEmptyArray, MinLengthArray, FixedLengthArray, …)
encodes its length constraint in a brand: NonEmptyArray<V> is
MinLengthTuple<1, V> & Brand<…>, a strict subtype of readonly [V, ...V[]].
Rewriting a declaration to it would narrow the type — an array literal is not
assignable to a branded type — so the autofix could break call sites.
The *Tuple family is structural and therefore exactly equal to the spelled-out
tuple, which makes every fix in this plugin a pure rename.
Examples
// ❌
type Names = readonly [string, ...string[]];
type Queue = [number, ...number[]];
type Rgb = readonly [number, number, number];
type AtLeastTwo = [string, string, ...string[]];
// ✅
type Names = NonEmptyTuple<string>;
type Queue = MutableNonEmptyTuple<number>;
type Rgb = FixedLengthTuple<3, number>;
type AtLeastTwo = MutableMinLengthTuple<2, string>;Single-element tuples without a rest (readonly [V]) are left alone — they read
better as-is than FixedLengthTuple<1, V>.
The rule deliberately leaves alone
- heterogeneous tuples (
readonly [string, number]); - labelled members (
readonly [head: V, ...tail: V[]]), because rewriting them would silently drop the labels; - optional members (
readonly [V, V?]) and rest-only tuples ([...V[]]); - files that already bind the target name to something else (a local alias, or an import from another module);
- tuples whose element types lead back to the declaration they sit in — a type
alias, an interface, a class, a function or a variable — directly or through
other declarations of the file, because the rewrite can make that type
circular (and every use of it
any). Any such cycle counts, so a few tuples whose rewrite would compile, such asinterface Tree { kids: readonly [Tree, Tree] }, are left alone too. A cycle closed through a module this file does not declare itself (withdeclare module) is not followed, and such a tuple is still rewritten unless a name it reaches happens to match a declaration of this file.
prefer-canonical-mutable-record
Mutable strips the readonly modifier from every property, so applied to a
record utility it spells in two steps what MutableRecord says in one. The
rewrite is exactly type-preserving, so this rule is an autofix. Mutable
applied to ReadonlyRecord or (redundantly) to MutableRecord collapses to
the same type and is normalized the same way.
// ❌
type Counters = Mutable<Record<string, number>>;
type Draft = Mutable<ReadonlyRecord<string, Item>>;
// ✅
type Counters = MutableRecord<string, number>;
type Draft = MutableRecord<string, Item>;Qualified names (Utils.Mutable<…>) and files that declare or import their own
Mutable / Record / … are left alone — those spellings do not denote the
ts-type-forge (or standard-library) types this rule reasons about.
prefer-strict-or-relaxed-utility-type
Exclude<T, U>, Extract<T, U>, Omit<T, K> and Pick<T, K> do not constrain
their second argument, so a member or key that is not part of T is silently
accepted — typically producing an empty result instead of the compile error that
would have pointed at the leftover of a rename.
ts-type-forge splits each one in two, and this rule makes the choice explicit:
| built-in | checks the second argument | keeps the built-in behavior |
| :-------------- | :------------------------- | :-------------------------- |
| Exclude<T, U> | StrictExclude<T, U> | RelaxedExclude<T, U> |
| Extract<T, U> | StrictExtract<T, U> | RelaxedExtract<T, U> |
| Omit<T, K> | StrictOmit<T, K> | RelaxedOmit<T, K> |
| Pick<T, K> | StrictPick<T, K> | RelaxedPick<T, K> |
// ❌
type Remaining = Exclude<'a' | 'b' | 'c', 'a'>;
type PublicInfo = Omit<Person, 'email'>;
// ✅ — the key is checked against the union / `keyof T`
type Remaining = StrictExclude<'a' | 'b' | 'c', 'a'>;
type PublicInfo = StrictOmit<Person, 'email'>;
// ✅ — deliberately unchecked (the subtrahend need not be part of `T`)
type NonStrings = RelaxedExclude<string | number | boolean, string>;Reach for Relaxed* when the second argument genuinely need not be part of the
first — a key set computed from a still deferred type parameter, or a subtraction
whose subtrahend is only partly present.
prefer-readonly-or-mutable-record
Record<K, V> says nothing about whether the properties may be reassigned, so
the mutability of every record spelled with it is decided by whoever reads it.
// ❌
type Config = Record<string, string | number>;
// ✅
type Config = ReadonlyRecord<string, string | number>;
type Counters = MutableRecord<string, number>;Both rules deliberately leave alone
- qualified names (
Utils.Pick<…>) — they never denote the standard-library type; - files that declare or import their own
Pick/Record/ …, for the same reason; - the choice itself: replacing
ExcludewithStrictExcludecan turn working code into a compile error, andRecordmaps onto two different types, so these rules report suggestions rather than an autofix. Editors offer both replacements;--fixchanges nothing.
no-side-effect-import
ts-type-forge ships declarations and nothing else — its exports map offers
no runtime condition — so import 'ts-type-forge'; binds no name and fails to
resolve the moment the module graph is loaded. A side-effect import is the one
kind TypeScript never elides, so the line survives compilation: a runtime error
sitting in a file that type-checks.
// ❌
import 'ts-type-forge';
// ✅ types are reached by name
import type { NonEmptyArray } from 'ts-type-forge';The fix deletes the import along with its line. Only the bare specifier matches:
ts-type-forge/global — the ambient globals, usually brought in through
compilerOptions.types or /// <reference types="ts-type-forge/global" /> — is
left alone, as is every other module.
Options
importStyle is accepted by every rule that rewrites a type; maxLength only
by prefer-canonical-length-constrained-tuple. no-side-effect-import takes no
options.
| Option | Type | Default | Description |
| :------------ | :-------------------- | :-------- | :------------------------------------------------------------------ |
| importStyle | 'global' \| 'named' | 'named' | How the ts-type-forge type is brought into scope. |
| maxLength | integer | 10 | Longest tuple prefer-canonical-length-constrained-tuple rewrites. |
'global'— the ambient globals ofts-type-forge/globalare in use (/// <reference types="ts-type-forge/global" />), so the fix only rewrites the type and never touches imports.'named'— the fix additionally imports the name when the file does not import it yet: added to an existingimport type { … }fromts-type-forge, else to animport { … }from it (astype X, empty braces included), else after a lone default import, and otherwise as a newimport { type … } from 'ts-type-forge';.
Either way, if the file already imports the target type from ts-type-forge
(possibly under an alias), the fix reuses that binding.
'ts-type-forge/prefer-canonical-length-constrained-tuple': [
'error',
{ importStyle: 'named', maxLength: 6 },
],