strict-ts strict-ts

Catch the bugs TypeScript lets through.

strict-ts is a checker you run in place of tsc --noEmit. It refuses code that compiles and still fails when it runs: any, casts, null, hidden exceptions, data changed behind your back. Your code stays standard TypeScript.

Where it stands: typing and errors have no known hole. Mutability and ownership are in progress. →

invoice.ts:8:10 no-cast `as` cast forbidden.
  help: Use a type guard, `satisfies`, or validate the data in unsafe/.
invoice.ts:8:10 no-any This expression has type `any` (inferred).
  help: Move the call into unsafe/ and return a validated Result<unknown, E>.
invoice.ts:8:10 no-throwing-call `JSON.parse` throws a SyntaxError, as seen with ("").
  help: Call it inside `attempt(() => …, onError)` in an unsafe directory, so that the failure becomes a Result.

as asserts a shape and proves nothing, and JSON.parse gives any and may throw. A schema proves the shape, and both failures are in a Result.

Open the playground →

Does it work? We try to fool it. We write TypeScript that compiles without a warning and still goes wrong when it runs. Each trick that got past strict-ts became a rule that blocks it. The score so far:

32
A value that is not what its type says32 ways to write one were found. All are blocked.
29
A crash that no type announces29 ways to cause one were found. All are blocked.
83
A function that changes your data without saying so83 ways are blocked so far. We still find new ones: this part is not finished.

Blocking every trick we found does not prove there is no other. Known limits says what is left.

How it works

One command, where tsc ran

1

Run one command

npx strict-ts -p ., where tsc --noEmit ran. It reports the errors of the compiler, and adds its own.

2

Read what it refuses

One line per problem, with the file and the place, and a help: line that says what to write instead.

3

Fix it, or fence it off

Make the code conform, or move what cannot to an unsafe/ directory, with a reason. On existing code, a baseline lets you start today: only new problems fail.

What you get

TypeScript, as safe as Rust

Types that tell the truth

No any, no cast, no @ts-ignore: a value is what its type says it is.

Errors you cannot forget

No throw, no null: what may fail returns a Result. A call that throws without saying so, like JSON.parse, is caught where it is written.

No change behind your back

Data is read-only unless a signature says Mut<T>: the call shows what a function may change. This part is still in progress.

Still plain TypeScript

No new language and no new compiler: tsc builds the same JavaScript. What you write with is an ordinary library.

The rules

What it refuses, in 40 rules

Each rule names one way a TypeScript program goes wrong, and says what to write instead. What you write instead comes from an ordinary library.

The rules →

  • no-any
  • no-cast
  • no-non-null
  • no-throw
  • no-null
  • no-external-import
  • must-use
  • exhaustive-switch
  • no-ts-directive
  • unsafe-boundary
  • safety-comment
  • strict-compiler-options
  • no-type-predicate
  • no-ambient
  • no-param-mutation
  • readonly-types
  • pure-domain
  • no-throwing-call
  • no-throwing-operator
  • use-once
  • freeze-fresh
  • mut-from-readonly
  • unread-sources
  • no-overload
  • no-method-signature
  • no-numeric-enum
  • no-default-on-undefined
  • no-unset-capture
  • no-early-this
  • no-unbound-method
  • mut-exact
  • no-resize
  • no-keyed-write
  • no-open-read
  • no-in-narrowing
  • no-loose-spread
  • no-class-lookalike
  • no-stale-narrowing
  • no-reject
  • no-early-read
  • Result
  • Option
  • Mut<T>
  • Once<T>
  • unsafe/

A tour

See it on 4 small programs

Each is TypeScript that tsc --strict accepts, with what strict-ts says of it. The links lead to the same program once it conforms.

Nothing unchecked outside unsafe

A cast asserts a shape and proves nothing. The call that may throw goes to an unsafe directory, and a schema proves the shape.

What it looks like →
invoice.ts
export function parseInvoice(json: string): Invoice {
  return JSON.parse(json) as Invoice;
}
invoice.ts:31:10 no-cast `as` cast forbidden.
  help: Use a type guard, `satisfies`, or validate the data in unsafe/.
invoice.ts:31:10 no-any This expression has type `any` (inferred).
  help: Move the call into unsafe/ and return a validated Result<unknown, E>.

Errors are in the types

What throws without saying so is refused where it is called: JSON.parse, a pattern, a division of bigints.

report: five ways to throw that no type announces →
report.ts
export function average(sales: Sale[]): bigint {
  const total = sales.reduce((sum, sale) => sum + sale.cents, 0n);
  return total / BigInt(sales.length);          // RangeError when there is no sale
}
report.ts:22:10 no-throwing-operator `/` throws a RangeError, as seen with 0n / 0n.
report.ts:22:18 no-throwing-call `BigInt` throws a SyntaxError, as seen with ("%").

Read-only, unless it says Mut

A function changes only what it made, or what says Mut<T> in its signature.

cart: who changes what →
cart.ts
export function cheapestFirst(items: Item[]): Item[] {
  return items.sort((a, b) => a.cents - b.cents);   // sorts the caller's array
}
cart.ts:24:10 no-param-mutation Parameter `items` is mutated by `sort`.

One owner, given away once

A value typed Once<T> has one owner. Forgotten on a path, or used after it was given away, it is refused.

transfer: a transaction with one owner →
transfer.ts
export const begin = (): Once<Transaction> => new Transaction();
export const commit = (tx: Once<Transaction>): readonly string[] => end(tx).written();

const tx = begin();
tx.debit(from, cents);
if (cents <= 0) {
  rollback(tx);                 // without this line: « `tx` is not given away before this `return` »
  return err("nothing-to-move");
}
tx.credit(to, cents);
return ok(commit(tx));          // after this, any use of `tx` is refused

In a project

Three things to know: install, run, configure

How it is installed, what it prints, and the one file that configures it.

install
echo "@strict-ts:registry=https://git.cf.adserver.fr/api/packages/Alex/npm/" >> .npmrc
npm install -D @strict-ts/cli @strict-ts/codemod
npm install @strict-ts/std
check
$ npx strict-ts -p .

invoice.ts:31:10 no-cast `as` cast forbidden.
  help: Use a type guard, `satisfies`, or validate the data in unsafe/.
strict-ts.json
{
  "unsafeDirs": ["src/unsafe"],
  "allowedImports": ["@strict-ts/std"],
  "pureDirs": ["src/domain"]
}

Adopt it on code that was not written for it

A baseline records what is refused today, as a count per rule per file. From then on the gate fails only on what goes beyond the record, and the record can only shrink.

Adopting it on existing code says what that costs, measured on applications.

baseline
strict-ts --update-baseline     # records today's violations, exits with 0
strict-ts                       # from now on, fails only on what goes beyond the record
strict-ts --strict-baseline     # in CI: also fails when the record allows more than what is found

The scoreboard

The five guarantees of Rust, and where each stands

Rust's safety rests on five guarantees. JavaScript already has one, memory, thanks to the garbage collector. strict-ts brings the other four, one rule at a time. This table is the project's scoreboard.

Rust guaranteeEquivalent in TS/JSStatus
Memory safetyThe runtime's garbage collectorAcquired
Safe typing, nothing unchecked outside unsafeNo any, cast, declare or @ts-ignore outside unsafe/; a // SAFETY: reason insideAcquired
No null, errors in the typesOption, Result, no-throw, must-use; a call or an operator that may throw is caught where it is writtenAcquired
Explicit mutabilityTypes read-only unless they say Mut<T>. A function changes only what it made, or what says Mut: a parameter, this, what another function hands outPrototype
Ownership, no uncontrolled concurrent accessA value typed Once<T> has one owner and is given away exactly once (use-once). State shared across await and workers: nothing yetResearch: a first rule, on a small subset

« Acquired » has a narrow meaning here: no way around the guarantee is known in checked code. Each way that was found is a file that fails when it is run, kept in the tests with the rule that refuses it: 32 for safe typing, 29 for errors in the types. It is a list and not a proof, the lists were written by who wrote the rules, and what is taken on trust (the specification as it was read, the browser as it was run, the types of the packages a project allows) is in Known limits. « Prototype » means the rules exist and are tested, and ways around them are still being found: explicit mutability went from 2 known ways refused to 83 in nineteen rounds, the last seventeen after an application had already been made to pass, and no round has yet found nothing.

Asked

Frequently asked questions

Is it a new language, or a new compiler?

No. A program strict-ts accepts is TypeScript that tsc compiles as is, and the JavaScript that comes out is the same. What conforming code is written with, Result, Option, schemas, is an ordinary library, @strict-ts/std.

Can I use it on code that was not written for it?

Yes: record today's refusals in a baseline, and the gate only fails on what is new. A fixer applies the fixes that are mechanical.

How do I silence a rule on one line?

You cannot, by design. What cannot conform goes to an unsafe directory with a // SAFETY: reason, or to the baseline.

Does it replace my linter?

No. It replaces tsc --noEmit in the CI. Three of its rules also exist as an Oxlint plugin, for a quick first answer.

Which versions of TypeScript does it support?

It checks with the TypeScript 6 API, which it brings itself. The editor plugin needs an editor that runs TypeScript 6 or earlier.

Is my program proven safe once it passes?

No. Two guarantees are « Acquired », which says that no way around them is known in checked code, not that there is none: they rest on lists of attacks, not on proofs. What is taken on trust, and what is still accepted, is in Known limits.

Try to get a bug past it.

Write TypeScript that compiles and fails when it runs, and see whether strict-ts lets it through. The checker is in the page, and nothing is sent anywhere.

Esc

    Type a rule, a word of the library, a command: no-cast, Result, baseline.