chenglou/freerange

Freerange is a command-line tool that analyzes TypeScript code and tracks the possible range of every number in your project, so it can catch bugs like division by zero, NaN values, infinite values, and array indexes that go out of bounds. It does this at compile time, meaning it checks your code before you ever run it in a browser, similar to how the regular TypeScript compiler catches type errors before runtime. Freerange works directly on top of the official TypeScript compiler API rather than being a new language or a fork of TypeScript, so there are no special annotations or library functions to learn. You install it as a dev dependency with a package manager like bun or npm, then run its command, called fr, which prints errors and warnings about your code, or fr audit, which prints a fuller report of each function's assumptions along with suggestions for restructuring code so Freerange can analyze it more effectively. One notable feature is that it gives new meaning to a lesser-known JavaScript function called console.assert. Normally that function only checks conditions while your code is actually running, but Freerange reads certain simple console.assert statements at compile time and proves whether they could ever be false, catching the mistake before the code ships, without needing to start the app. Freerange intentionally supports a specific, well-defined subset of TypeScript rather than every possible pattern the language allows, since some code patterns make this kind of numeric analysis mathematically very hard or even impossible to solve. The README explains this subset in detail and recommends restructuring important numeric calculations into small, named, synchronous functions with clear inputs and outputs, a style similar to functional programming, since that shape is what Freerange can reason about best. The authors note this restructuring is a good task to hand to an AI coding agent, since it is mechanical and Freerange's audit command gives explicit, actionable guidance for what needs to change.