npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

eslint-plugin-ts-type-forge

v0.8.28

Published

ESLint rules that steer type declarations toward ts-type-forge idioms.

Downloads

3,499

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-forge

Requires 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 as interface Tree { kids: readonly [Tree, Tree] }, are left alone too. A cycle closed through a module this file does not declare itself (with declare 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 Exclude with StrictExclude can turn working code into a compile error, and Record maps onto two different types, so these rules report suggestions rather than an autofix. Editors offer both replacements; --fix changes 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 of ts-type-forge/global are 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 existing import type { … } from ts-type-forge, else to an import { … } from it (as type X, empty braces included), else after a lone default import, and otherwise as a new import { 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 },
],

License

Apache-2.0