{"canonical_url":"https://engineer.company/glossary/typescript/","content_markdown":"# TypeScript\n\n## What it is\n\nTypeScript is a programming language from Microsoft that adds type annotations to JavaScript,\ntogether with a compiler, `tsc`, that checks them. People shorten the name to TS, and its files end\nin `.ts`, or `.tsx` when they contain JSX markup. JavaScript syntax is legal TypeScript, which is\nwhy the language is called a superset of JavaScript. The compiler is open source under the Apache\nLicense 2.0.\n\nThe types last only as long as the checking. Ordinary type annotations are\nerased when TypeScript emits JavaScript; they do not provide runtime validation\nor require a type-checking runtime library. Type annotations do not change how\nthe JavaScript code behaves when it runs. That one fact explains both its value\nand its limits: the checker reasons about the types described in the source;\nit does not validate data that arrives while the program is running.\n\nThe type system is structural. Two types are compatible when their shapes match, whatever they are\ncalled, which suits JavaScript's habit of passing plain objects around; C# and Java compare declared\nnames instead. Much of the typing is inferred, so annotations sit mostly on function signatures and\nexported values. The system is also deliberately unsound in a few places. `any` switches checking\noff for a value, and an assertion written with `as` tells the compiler to take the programmer's word\nfor a type. Both disappear from the output along with everything else.\n\nThere are three common ways to run it. `tsc` checks a project and emits JavaScript. Bundlers such as\nesbuild strip the types without checking them, and leave checking to a separate `tsc --noEmit` run.\nNode.js, since v23.6.0 and v22.18.0, runs `.ts` files directly by replacing the type syntax with\nwhitespace, again with no type checking, and accepts only syntax that can be erased that way.\nTypeScript 7.0, announced in July 2026, is a native Go version of the compiler, which the team\nreports as typically 8 to 12 times faster on full builds.\n\n## Why it matters\n\nThe question a team answers is whether a build step and a checker earn their keep by catching errors\nbefore the code runs. In a codebase that several people change every week they usually do. Renaming\na field shows every place that used it, the editor completes and explains code from the types, and a\nmodule's signature becomes a contract its callers cannot quietly break. The cost is a check in every\nbuild, a configuration file with many options, and type definitions that have to keep pace with the\nlibraries they describe.\n\nStrictness is the setting that matters most. The `strict` flag turns on a family of checks, among\nthem `strictNullChecks` and `noImplicitAny`, and the handbook describes the result as a dial rather\nthan a switch. Since TypeScript 6.0 that flag is on by default, so a new project starts strict; an\nolder one may still set it to false, and turning it on later means working through every file it\ntouches. Two useful checks sit outside the family and have to be enabled separately:\n`noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`.\n\nErasure sets the limit. A program that reads JSON from a network request, a file, a queue or a form\nhas only the programmer's word for that data's shape, because the types are gone by the time the\ndata arrives. Boundaries therefore need validation at runtime, ideally generated from the same\ndefinition as the types, so the check and the type cannot disagree. TypeScript makes the inside of a\nprogram consistent and leaves the edges to code.\n\nThe checker also feeds other tools. A linter such as typescript-eslint can ask the compiler for type\ninformation, so that a rule can flag a promise nobody awaits or a value of type `any` spreading\nthrough a module. That is how a team turns its own conventions into errors rather than review\ncomments.\n\n## What it looks like in practice\n\nIn the projects shown on this site, TypeScript is kept honest by generated code and by tooling\nrather than by convention. Three pages show how.\n\nOn one platform the frontend's TypeScript client is never written by hand. [It\nis generated from the API's own\ndescription](/portfolio/generated-the-api-contract-from-the-database-out/),\nwhich Huma emits from the Go types, which in turn follow the database schema and\nits functions. At the documented implementation stage, the client came to 44,076\nlines, and 61 mock handlers generated alongside it let the frontend's tests run\nagainst the real contract instead of a hand-written fixture. Every hop has its\nown guard. A contract check in CI compares what the frontend sends with what the\nAPI expects and fails the build when they diverge, with a schema probe\nunderneath that inspects the real shapes. It covers optional body fields, where\nmissing and null are easily confused, and enums in query parameters. A field\nthat changes on one side now fails a build minutes after the change, rather than\nshowing up as a 422 in the browser after the mismatch has shipped. In exchange,\na change to the contract reaches the client's types only by running the chain\nagain, and regenerating is a chore.\n\nAnother page sets one bar for six languages, TypeScript among them.\n[Every diagnostic ESLint reports is an error](/portfolio/set-a-zero-warnings-bar-across-six-languages/),\nthere is no warning tier to hide in, and inline suppressions are banned, so a finding has to be\nfixed rather than silenced. Pre-commit and pre-push hooks run the linters and the tests, and\nfunction- and file-length limits keep modules readable.\n\nThe linters that ship with a language stop short of a project's own rules, so\n[fifteen custom ESLint\nrules](/portfolio/built-a-268-check-guard-engine-for-the-repo/) held that\nrepository's house patterns in TypeScript at the documented implementation\nstage. They belonged to a guard engine of 274 check scripts, 268 of them\nregistered in the commit hooks, and the guards carried 146 tests of their own,\nbecause a broken guard passes everything without anyone noticing. One rule\nconcerns tests rather than types: a commit prefixed `fix:` must include a test\nthat fails without the fix. Review time moved from mechanics to design, and\ncommitting became slow in exchange.\n\n## Where it goes wrong\n\nMost TypeScript failures come from trusting the types further than the compiler can see.\n\n**A field typed as a string turns out to be undefined at runtime.** The data came from outside the\nprogram and was given a type rather than checked. The DOM library types `res.json()` as a promise of\n`any`, so the compiler accepts whatever the code does with the result, and an assertion makes the\ntrust explicit without making it safe:\n\n```ts\nconst res = await fetch(\"/api/user\");\nconst user = (await res.json()) as User; // trusted, never checked\nuser.email.toLowerCase(); // TypeError if email is missing\n```\n\nTreat external data as `unknown`, validate it at the boundary with a runtime schema, and generate\nthe type from that schema so the two stay in step. A typed lint rule can then flag any `any` that\nslips past.\n\n**Code with type errors reaches production anyway.** `tsc` still writes JavaScript when it reports\nerrors, because `noEmitOnError` defaults to false, and bundlers and Node.js strip types without\nchecking them at all. Run `tsc --noEmit` as a required step in CI and in the pre-commit hook, and\nfail the build on its exit code.\n\n**An index lookup returns undefined that the type ruled out.** Reading an array element or a key\nthrough an index signature is typed as always present, even past the end of the array. Turn on\n`noUncheckedIndexedAccess`, which adds `undefined` to those reads and makes the code handle it. Pair\nit with `exactOptionalPropertyTypes`, which tells an absent property apart from one set to\n`undefined`.\n\n**A file that compiles with tsc fails when Node.js runs it.** Type stripping removes only syntax\nwith no runtime meaning. Enums and namespaces that hold values make Node.js stop with\n`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`, and a type imported without the `type` keyword is treated as a\nvalue import that fails at runtime. Turn on `erasableSyntaxOnly` and `verbatimModuleSyntax` so the\ncompiler reports both before Node.js does, write `import type` for types, and replace enums with\nobject literals marked `as const`.\n\n## Further reading\n\n- [TypeScript Documentation](https://www.typescriptlang.org/docs/) — the handbook, the reference\n  pages and the release notes, maintained by the TypeScript team.\n- [The Basics](https://www.typescriptlang.org/docs/handbook/2/basic-types.html) — the handbook\n  chapter on static checking, emitting with errors, erased types and strictness.\n- [TSConfig Reference: strict](https://www.typescriptlang.org/tsconfig/#strict) — every compiler\n  option with its default, including the checks the strict flag turns on.\n- [Type Compatibility](https://www.typescriptlang.org/docs/handbook/type-compatibility.html) —\n  structural subtyping, and the places where the type system is unsound on purpose.\n- [Node.js: Modules: TypeScript](https://nodejs.org/api/typescript.html) — type stripping, the\n  syntax it rejects and the compiler settings Node.js recommends.\n- [Linting with Type Information](https://typescript-eslint.io/getting-started/typed-linting/) — how\n  typescript-eslint gives lint rules access to the type checker.\n\n\u003chttps://engineer.company/glossary/typescript/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"What TypeScript checks and what it erases, how strict to set it, how Node.js runs it, and where its types stop protecting a program.","formats":{"gemtext":"https://engineer.company/glossary/typescript/index.gmi","gopher":"https://engineer.company/glossary/typescript/gophermap","html":"https://engineer.company/glossary/typescript/","json":"https://engineer.company/glossary/typescript/index.json","markdown":"https://engineer.company/glossary/typescript/index.md","pdf":"https://engineer.company/glossary/typescript/index.pdf"},"kind":"page","language":"en","title":"What is TypeScript?","url":"https://engineer.company/glossary/typescript/","version":1}