The interface versus type argument is one of the oldest in TypeScript, and the honest answer is that it rarely matters. What does matter, and what nobody measures, is the vocabulary a codebase settles into: how many of your types are objects, how many are unions, how deep the generics go, and which of the standard utility types you actually use.

So I counted every type declaration in ours.

The subject is Nakodo, 582 TypeScript files, 72,683 lines, strict mode, no type-generation step other than the ORM's row inference.

The headline

type aliases 357 (262 exported, 95 file-local) interfaces 1 (a global Window augmentation) enums 0 classes 19 (18 of them Error subclasses) generic aliases 2 generic functions 14 

One interface in 72,683 lines, and it is not describing anything of ours. It is here, in the component that draws the bot check on the sign-up box on the home page:

declare global { interface Window { turnstile?: TurnstileApi; } } 

Augmenting an existing declaration is the one job type cannot do, so the single interface in the codebase exists because a third party script attaches itself to window and the compiler has to be told. The shape it points at, TurnstileApi, is a type alias like everything else.

That was not a policy. Nobody wrote "no interfaces" in a contributing guide. The first file used type, and 581 files later it has never been worth the inconsistency to switch.

What the 357 aliases are

Body shape Count
Object literal 207
Union (not all string literals) 35
Union of string literals 30
Function type 27
Alias of a named type 23
ORM row type ($inferSelect) 16
Utility type (Record, Pick, ...) 9
Derived from a function (Awaited<ReturnType<...>>) 5
Inferred from a Zod schema (z.infer) 5

207 object literals is the population that would be interface in most codebases. The 65 unions are the interesting half, because a union is a decision and an object is usually just a description.

26 of the 357 are not written at all, they are derived: 16 ORM row types, 5 from a Zod schema, 5 from the return type of a function. Those are the ones that cannot drift, and the ratio (7% of the type surface) is a reasonable number to try to grow.

By directory, the aliases cluster where the screens are, not where the logic is: 52 in the application routes, then the server modules at 34, 29 and 19. Component props account for most of the first number, which is what you would expect in a codebase where props are declared inline and only the shared ones get a name.

Zero enums, 30 string unions

Not one enum in the codebase. The replacement is the string literal union, 30 times, and they go all the way down to the database: 41 columns in our schema are a union in TypeScript and plain text in Postgres, with a check that the two lists agree. A TypeScript enum would have added a runtime object and a second vocabulary for the same values.

The largest union in the codebase is the audit log's action list, at 68 members over 67 lines, four more than when I wrote about it a fortnight ago. The next largest is the environment variable name list at 19. After those, nothing exceeds 11 members.

31 of the unions carry a discriminant (a kind or type field), which is where the real work happens: a function takes the union, switches on the discriminant, and the compiler checks the cases.

23 switch statements, 18 of them with no default branch

This is my favourite number in the census, because it is a type system fact expressed as a code shape:

switch statements 23 with a default branch 5 without a default branch 18 

A switch over a discriminated union with no default is a compile time exhaustiveness check. Add a new member to the union and every one of those 18 switches becomes a type error at the exact place a decision is now missing. Add a default, and the same change compiles and silently does the wrong thing.

The five that do have a default are switching over values from outside the type system: a provider's webhook event name, a status string off an HTTP response. Those need a default because the input is not ours to enumerate.

If you only take one thing from this post, take this one: the absence of a default: is load-bearing, and it is invisible to a reviewer who does not know that. It belongs in a comment or in a lint rule, and ours is currently neither.

Generics are almost absent

Two generic type aliases and 14 generic functions in 72,683 lines. The 14 are mostly tiny infrastructure:

export async function mapLimit<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> export function withTimeout<T>(promise: Promise<T>, ms: number, error: () => Error): Promise<T> 

plus a lock wrapper, two HTTP clients, a job payload lookup, and four UI components generic over a string union so a set of choice cards stays typed to the values it renders.

The public face of the discriminated-union-plus-exhaustive-switch pattern is the content layer. Every public page is an array of Block values, an eight-member union discriminated by type (p, list, steps, table, template, callout, terms, tags), and the renderer switches on it with no default. Adding a ninth block type breaks the build in three places at once: the renderer, the markdown generator behind llms.txt, and the editorial test, which is the only reason I trust a page I have not read. You are looking at the output of that switch on any guide and on the glossary.

Fourteen call sites for type parameters in a codebase this size says something I like: the generics are in the plumbing, and the application code above them is concrete. Every one of the 14 is either a container (promise, array, row) or a key lookup, which are the two cases where generics earn their complexity.

The utility types we use, and the two we never do

Utility Uses
Record<K, V> 147
Pick<T, K> 49
Partial<T> 35
ReturnType<T> 19
Omit<T, K> 10
Awaited<T> 10
NonNullable<T> 9
Parameters<T> 7
Exclude<T, U> 4
Extract<T, U> 3
Readonly<T> 0
Required<T> 0

Record dominates, and splitting it by key type is the useful cut: 77 of the 147 are keyed by a union or a named type, and 70 by plain string. The 77 are lookup tables that cannot miss a case, because the compiler requires every member of the key union to have an entry. That pattern plus a string union is how this codebase does what an enum plus a map would do elsewhere: labels per status, copy per plan, priority per page kind. Two of those are visible from outside: the plan copy on the pricing page is a Record keyed by the plan union, and the priority value on every URL in the sitemap comes from a Record keyed by the eight page kinds, which is why no page type can ship without one.

Pick at 49 against Omit at 10 is a style I did not notice until it was in a table. Naming the fields you want is more stable than naming the fields you do not, because adding a field to the source type does not quietly widen the derived one.

as const appears 160 times, satisfies 16. A ten to one ratio in favour of the older idiom, in a codebase that could use the newer one in most of those places and get both the literal types and the checked shape. That is the clearest piece of technical debt this census found, and it is a mechanical fix.

Two measurement traps

Grepping for a keyword in a codebase that contains prose. The word never appears 365 times in src. Twenty-six of those are the TypeScript type (: never, as never, Promise<never>). The other 339 are English, in comments and in the 13,660 lines of page copy that live in this repo as TypeScript arrays. Any keyword that is also a word needs its syntax context, or the number is fiction.

Multi-line alias bodies. A regex that reads to the end of the line finds the name of a 67-member union and nothing about it. Matching to the next line that starts in column one is crude, and it was enough to classify all 357 bodies, but it is the step where a census like this usually goes wrong.

What I take from this

  1. Convert the 160 as const sites to satisfies as they are touched. Same literal types, plus a shape check at the declaration instead of at the first use.
  2. Write down the no-default rule. Eighteen exhaustive switches are protecting eighteen decisions, and the protection is a missing line of code that any reviewer could "tidy up".
  3. Grow the derived types. 26 of 357 types are inferred from a schema, a query or a function. Every type that is written by hand next to a source of truth is a type that can disagree with it.
  4. Leave the interface question alone. One interface in 582 files, and it exists for a reason no style guide would have predicted. That is the right amount of debate to have had about it, which is none.

The method is about fifty lines of Python and transfers to any TypeScript repo. The first two numbers I would print on your own are the count of switch statements without a default, and the as const to satisfies ratio. Both of them tell you how much of your type safety is on purpose.