TypeScript Academy · Lesson

What Is a Type-Level DSL

Use types to constrain a fluent API to valid programs.

What Is a Type-Level DSL is a free TypeScript Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the TypeScript Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What Is a Type-Level DSL?

A type-level DSL (domain-specific language) uses TypeScript types to constrain an API so that only valid programs compile. The types act as a grammar: invalid combinations are rejected before the code ever runs.

Embedded DSLs

An embedded DSL lives inside the host language (here, TypeScript) rather than being a separate parser. You write ordinary TS, but the type system enforces the DSL rules.

A Familiar Example

You have already used type-level DSLs: a query builder that only allows valid column names, or a router that infers params from a path. The types encode what the API permits.

Constraining a Fluent API

The core idea: each method returns a type that limits which methods you can call next. Calling things in the wrong order fails to compile.

interface Empty { from(t: string): HasFrom; }
interface HasFrom { where(c: string): HasFrom; select(): string; }

declare const q: Empty;
q.from("users").select();      // ok
q.select();                    // Error: select not on Empty

State Machines in Types

That pattern is a type-level state machine: each interface is a state, each method a transition to another state. The compiler walks the machine as you chain calls.

Why Not Just Runtime Checks?

Runtime checks fail late, in production, with users present. A type-level DSL fails early, in the editor, with a red squiggle, before code ships. Same rules, much cheaper feedback.

Phantom Type Parameters

DSLs often carry information in phantom type parameters: generics that exist only at compile time to track accumulated state (selected columns, bound variables) without runtime cost.

interface Query<Selected extends string> {
  select<C extends string>(c: C): Query<Selected | C>;
}

Literal Types as Tokens

String literal types act as DSL tokens. Combined with template literals and unions, they let the type system reason about the textual content of your DSL.

type Direction = "asc" | "desc";
declare function orderBy(col: string, dir: Direction): void;
orderBy("age", "asc");   // ok
orderBy("age", "up");    // Error: not a Direction

The Building Blocks

Type-level DSLs combine: generics for state, conditional types for branching, template literals for parsing strings, and mapped types for transforming shapes. Later lessons use each of these.

Trade-offs

Type-level DSLs give strong guarantees but can produce cryptic errors and slower compiles if overused. Good DSLs balance safety against readable error messages (a later lesson tackles this).

Why This Matters

Encoding domain rules in types means the compiler becomes a domain expert: it rejects nonsense automatically. This is how query builders, form libraries, and effect systems offer such strong guarantees.

Quick Check

Test your understanding of type-level DSLs.

Recap

A type-level DSL uses TypeScript types as a grammar so only valid programs compile. Fluent APIs model state machines where each method returns a state-restricting type, using phantom generics, literal-type tokens, conditional, template-literal, and mapped types as building blocks, giving early, editor-time feedback.

Frequently asked questions

Is the “What Is a Type-Level DSL” lesson free?

Yes — the full text of “What Is a Type-Level DSL” is free to read here on the web, and the TypeScript Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the TypeScript Academy course, upgrade to CoddyKit PRO.

What will I learn in “What Is a Type-Level DSL”?

Use types to constrain a fluent API to valid programs. You practise TypeScript Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start TypeScript Academy?

No prior experience is required. TypeScript Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “What Is a Type-Level DSL” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this TypeScript Academy lesson?

Yes. Every TypeScript Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to TypeScript Academy