Errors as values for TypeScript, enforced by the compiler and the linter.
Rust and Go make failure part of a function's return type, so a caller cannot use a value before checking whether the call failed. neverthrow brings a Result type to TypeScript. strict-ts adds the configuration that makes a whole project follow it: the strictest compiler flags, lint rules that reject type assertions, any, discarded Results and throwing outside boundary files, and non-throwing replacements for built-ins such as JSON.parse, fetch and new URL.
const user = parseWith(User, input);
if (!user.ok) return sendError(res, 400, user.error);npx github:wingravity/strict-ts init
npm install
npx strict-ts report --next 20init adds the configuration and the coding-agent instructions to the project. report lists what needs attention, most dangerous first. npm run check runs the compiler and ESLint and fails on any finding; use it in CI.
flowchart LR
A["Code written by you<br/>or a coding agent"] --> B["npm run check<br/>tsc + ESLint"]
B -- passes --> C["Merge"]
B -- fails --> D["strict-ts report<br/>findings ranked P0 to P4"]
D --> E["Fix the highest<br/>priority first"]
E --> A
F["AGENTS.md<br/>written by init"] -.-> A
strict-ts report runs the TypeScript compiler and ESLint together and orders every finding by the worst realistic runtime consequence of its rule. On an existing codebase, this shows where to start.
| Priority | Meaning | Examples |
|---|---|---|
| P0: Process can go down | can stop the whole process | floating promises, async callbacks where a void callback is expected |
| P1: Silent wrong result | wrong data or behavior with no error raised | as casts, any, ignored Results, Dog[] used as a mutable Animal[], truthiness checks on numbers, non-exhaustive switches |
| P2: Request fails | throws at runtime and fails one request | possibly undefined access, !, throwing built-ins |
| P3: Weak error handling | makes failures likelier or harder to handle | throw/try outside boundaries, unbounded schemas and loops, truthiness checks on strings and booleans |
| P4: No runtime effect | clarity only | bracket access, unused code, redundant expressions |
npx strict-ts report # writes strict-ts-report.md
npx strict-ts report --next 20 # the 20 highest-priority findings, with fix instructions
npx strict-ts report --format json # all findings as JSONEach rule in the report states why it matters and how to fix it. Production code is listed before tests, and the report lists the files with the most P0 to P2 findings and any strict-ts rule or compiler flag that the project's configuration turns off or downgrades.
Report options
--project <tsconfig>selects the tsconfig.- The report includes findings recorded in
eslint-suppressions.json.--respect-suppressionsleaves them out (requires ESLint 10.1 or later). - The command always exits with code 0. Use
npm run checkas the CI gate. - Add
strict-ts-report.mdto.gitignoreif it should not be committed.
strict-ts is designed for projects where coding agents such as Claude Code, Codex, Copilot and Cursor write much of the code.
- Instructions:
initadds a strict-ts section toAGENTS.md, the instruction file these agents read. It covers Results, the banned constructs, the safe replacements, boundary files, and the requirement that the check passes. - Work queue:
npx strict-ts report --next 20gives an agent a short, prioritized list of findings with a fix instruction for each.--format jsongives the same data in a stable shape. - API reference:
node_modules/strict-ts/docs/api.mdlists every function, its error kinds and the expected code patterns. - No shortcuts:
// eslint-disablecomments have no effect, and the report shows any rule or compiler flag weakened in the configuration.
The AGENTS.md section sits between <!-- strict-ts:start --> and <!-- strict-ts:end -->, and running init again refreshes it without touching the rest of the file. Claude Code reads AGENTS.md unless the project has a CLAUDE.md, so init adds an @AGENTS.md import to an existing CLAUDE.md.
Requires Node 20.3 or later, TypeScript 5.8 to 6.0, ESLint 9.35 or later (or ESLint 10) and typescript-eslint 8.
What init changes
| File | Change |
|---|---|
tsconfig.json |
adds strict-ts/tsconfig.json to extends (comments and formatting are kept) |
eslint.config.js |
creates it, or prints the lines to merge if one exists |
package.json |
adds a check script and strict-ts as a dependency pinned to the release tag |
AGENTS.md |
adds a strict-ts section with instructions for coding agents, or creates the file |
CLAUDE.md |
if it exists, adds @AGENTS.md so Claude Code also reads those instructions; never created |
.vscode/extensions.json |
recommends the ESLint extension |
.vscode/settings.json |
uses the project's TypeScript version and, with ESLint 10.1 or later, applies bulk suppressions in the editor |
It also prints the install command for any missing peer dependency (typescript, eslint, typescript-eslint). Running it again changes nothing.
--dry-runpreviews the changes without writing.--forceoverwrites an existing ESLint config.npx "github:wingravity/strict-ts#v0.2.0" initruns a specific release.
Adopting on an existing codebase
- Run
init. - Run
npx eslint . --suppress-alland commiteslint-suppressions.json. New code must be clean; shrink the file as you fix code withnpx eslint . --prune-suppressions. - Run
npx strict-ts reportto see which findings to fix first. - Fix the TypeScript errors. Bulk suppressions only cover ESLint. Most fixes are mechanical: handle the
undefinedfrom index access, use bracket access on dynamic objects, leave optional properties out instead of passingundefined. - Wrap throwing SDKs in boundary files and list them in
throwingModules. - Add
installProcessGuardsat startup.
init sets "eslint.options": { "applySuppressions": true } in .vscode/settings.json so the VS Code ESLint extension hides suppressed findings the same way CI does.
Manual setup
npm install "github:wingravity/strict-ts#v0.2.0"
npm install -D typescript eslint typescript-eslint// eslint.config.js
import strictTs from "strict-ts/eslint";
export default [
{ ignores: ["dist/**"] },
...strictTs({ tsconfigRootDir: import.meta.dirname }),
];// package.json
"scripts": { "check": "tsc --noEmit && eslint ." }Continuous integration
npm run check exits with a non-zero code on any finding. For GitHub Actions, add .github/workflows/check.yml:
name: Check
on:
pull_request:
push:
branches: [main]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
cache: npm
- run: npm ci
- run: npm run checkTo block merging on failures, mark the Check job as required in the branch protection rules. For pnpm, Yarn or Bun, replace the install and run commands.
Results
import { ok, err, type Result } from "strict-ts";
type ParseError = { kind: "Empty" } | { kind: "TooLong"; max: number };
function parseName(input: string): Result<string, ParseError> {
if (input === "") return err({ kind: "Empty" });
if (input.length > 100) return err({ kind: "TooLong", max: 100 });
return ok(input.trim());
}A Result is a plain readonly object, { ok: true, value } or { ok: false, error }, never a class instance. It survives JSON.stringify, structuredClone, postMessage, and Next.js and Astro action boundaries.
| Function | Purpose |
|---|---|
ok(value), err(error) |
build a Result |
map, mapErr, andThen |
transform or chain without unwrapping |
match(r, { ok, err }) |
handle both cases and return a value |
unwrapOr(r, fallback) |
the value, or a fallback on error |
all(results) |
all values in order, or the first error |
attempt(fn, toError) |
call code that may throw (boundary files only) |
attemptAsync(fn, toError) |
the same for promises; never rejects |
AsyncResult<T, E> is Promise<Result<T, E>>; functions returning it must never reject. Model errors as unions with a kind field so switch (error.kind) is checked for exhaustiveness.
Replacements for throwing built-ins
strict-ts/safe has a non-throwing replacement for each banned built-in:
| Banned | Use |
|---|---|
JSON.parse |
safeJsonParse(text, { maxLength, maxDepth }) |
JSON.stringify |
safeJsonStringify(value, indent?) |
new URL |
safeUrl(input, base?) |
decodeURIComponent and friends |
safeDecodeURIComponent, safeEncodeURIComponent, safeDecodeURI, safeEncodeURI |
BigInt() |
safeBigInt |
structuredClone |
safeStructuredClone |
atob, btoa |
safeAtob, safeBtoa |
new RegExp |
a regex literal, or safeRegExp(pattern, flags?) |
fetch |
safeFetch(url, { timeoutMs, ...init }) |
response.json() |
readBody(response, { maxBytes }) + safeJsonParse, or fetchJson |
Validate external data with any Standard Schema library (Zod, Valibot, ArkType):
import { z } from "zod";
import { fetchJson } from "strict-ts/safe";
const User = z.object({ id: z.number(), name: z.string().max(200) });
const user = await fetchJson("https://api.example.com/me", User, { timeoutMs: 5_000 });
if (!user.ok) {
if (user.error.kind === "HttpStatusError") return handleStatus(user.error.status);
return reportFailure(user.error);
}fetchJson requests with a timeout, checks the HTTP status, reads the body with a size cap, parses with a depth cap and validates.
Boundary files
Put code that touches throwing APIs in a boundary file (*.boundary.ts or a boundary/ folder), where try, throw and the banned built-ins are allowed, and expose functions that return Results:
// billing.boundary.ts
import Stripe from "stripe";
import { attemptAsync, type AsyncResult } from "strict-ts";
const stripe = new Stripe(apiKey);
export function createCustomer(email: string): AsyncResult<Stripe.Customer, BillingError> {
return attemptAsync(
() => stripe.customers.create({ email }),
(cause) => ({ kind: "StripeError", message: String(cause), cause }),
);
}Add the SDK to throwingModules so the rest of the code can only reach it through the boundary. List clients that throw, not helpers that don't (for Drizzle, your db client throws; drizzle-orm query builders do not).
Node: filesystem and process handlers
import { readTextFile, installProcessGuards } from "strict-ts/node";
const config = await readTextFile("config.json", { maxBytes: 100_000 });
installProcessGuards({
log: (event) => logger.error(event),
onFatal: () => Sentry.flush(2_000),
onShutdown: () => server.close(),
timeoutMs: 5_000,
});readTextFile,writeTextFile,readDir,statandensureDirreturn Results with the Node error code and path.- On an uncaught exception or unhandled rejection,
installProcessGuardslogs it, runsonFatal, and exits 1 so the supervisor restarts a clean process. - On
SIGTERMorSIGINTit runsonShutdownand exits 0, or exits 1 if the hook fails or hangs pasttimeoutMs.
Compiler flags
strict-ts/tsconfig.json sets only strictness flags. It does not set module, target, jsx, lib or types.
| Flag | Catches |
|---|---|
strict |
the TypeScript baseline |
noUncheckedIndexedAccess |
rows[0].id when rows may be empty |
exactOptionalPropertyTypes |
passing undefined where a property should be left out |
noPropertyAccessFromIndexSignature |
body.key on a dynamic object; write body["key"] so the lookup is visible |
noImplicitReturns, noFallthroughCasesInSwitch |
missing returns, accidental fallthrough |
noImplicitOverride |
overriding a method without override |
useUnknownInCatchVariables |
treating a caught value as an Error without checking |
noUnusedLocals, noUnusedParameters, allowUnreachableCode: false |
dead code |
verbatimModuleSyntax, noUncheckedSideEffectImports, forceConsistentCasingInFileNames |
import mistakes |
A project's own compilerOptions override inherited ones. Setting one of these flags to false locally disables it.
Lint rules
Built on typescript-eslint strictTypeChecked plus ESLint's full recommended set.
- Type assertions and
any:as(exceptas const),!,any,@ts-ignore,@ts-expect-error,@ts-nocheck, allno-unsafe-*rules. - Correctness:
- Exhaustive switches: every case of a union must be listed, and
defaultdoes not count. - No truthiness checks on strings or numbers, no unnecessary conditions.
- Floating and misused promises.
===only.- Numbers allowed in template strings.
- Exhaustive switches: every case of a union must be listed, and
- Never throw (outside boundary files):
throw,try,Promise.reject,new Promise, throwing built-ins andthrowingModulesimports. - Unsafe array widening:
strict-ts/no-mutable-array-wideningreports a mutable array used as a mutable array of a wider type, such as aDog[]assigned or passed where anAnimal[]is expected. TypeScript allows this, and code holding theAnimal[]can then add a non-Dog to the original array. Readonly targets and copies are allowed. - Ignored errors:
strict-ts/must-use-resultreports a discarded Result, such assave();oritems.forEach((x) => save(x)). This is the equivalent of Go'serrcheck. - Bounded input and loops:
strict-ts/bounded-schemasrequires.max()on Zod strings and arrays.while,do...while,for(;;), generators andsetIntervalare banned. - No escape hatches in source:
// eslint-disablecomments have no effect; exceptions go ineslint.config.js.
Options
strictTs({
tsconfigRootDir: import.meta.dirname,
throwingModules: ["stripe", "minio", "resend"],
boundary: ["**/*.boundary.ts", "**/boundary/**"],
tests: ["**/*.test.ts", "**/*.spec.ts", "**/__tests__/**"],
files: ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
allowInlineDisable: false,
});| Option | Purpose |
|---|---|
throwingModules |
packages importable only from boundary files (matches the package and its subpaths) |
boundary |
files where throwing code is allowed |
tests |
test files, where type-safety and boundary rules are relaxed |
files |
files the config applies to |
allowInlineDisable |
true makes // eslint-disable comments work again |
Tests
Test code never reaches production, so in files matching tests the type-safety and boundary rules are off (no-unsafe-*, as, !, truthiness, throw and try bans, restricted imports). Rules that catch real test bugs stay on: floating promises (an un-awaited assertion passes silently), must-use-result, eqeqeq and ESLint's recommended set.
Compiler flags apply to every file in a tsconfig. If tests need looser compiler settings, give them their own tsconfig.
Adopting on an existing codebase
- Run
init. - Run
npx eslint . --suppress-alland commiteslint-suppressions.json. New code must be clean; shrink the file as you fix code withnpx eslint . --prune-suppressions. - Run
npx strict-ts reportto see which findings to fix first. - Fix the TypeScript errors. Bulk suppressions only cover ESLint. Most fixes are mechanical: handle the
undefinedfrom index access, use bracket access on dynamic objects, leave optional properties out instead of passingundefined. - Wrap throwing SDKs in boundary files and list them in
throwingModules. - Add
installProcessGuardsat startup.
init sets "eslint.options": { "applySuppressions": true } in .vscode/settings.json so the VS Code ESLint extension hides suppressed findings the same way CI does.
See CONTRIBUTING.md for development and releases.
MIT
