Generics · djuleayo

Generics · djuleayo https://316c0611.personalpage-ahl.pages.dev/tags/generics/ Hugo en TS API Spec https://316c0611.personalpage-ahl.pages.dev/posts/ts-api-spec/ https://316c0611.personalpage-ahl.pages.dev/posts/ts-api-spec/ Sat, 20 Dec 2025 11:13:48 +0200 <h1 id="ts-api-spec"> TS API Spec <a class="heading-link" href="#ts-api-spec"> Link to heading </a> </h1> <ul> <li>npm: <a href="https://www.npmjs.com/package/@apispects/core" class="external-link" target="_blank" rel="noopener">https://www.npmjs.com/package/@apispects/core</a></li> <li>repo: <a href="https://github.com/apispects/core" class="external-link" target="_blank" rel="noopener">https://github.com/apispects/core</a></li> </ul> <hr> <h2 id="ts-first-api-spec-with-superb-dx"> TS-first API spec with superb DX <a class="heading-link" href="#ts-first-api-spec-with-superb-dx"> Link to heading </a> </h2> <figure><img src="/tsapispec.demo.gif"> </figure> Everything is autocompleted and type-checked. As soon as the schema is satisfied, the error disappears. No separate spec file. No generation step. <hr> <h2 id="the-problem-this-targets"> The problem this targets <a class="heading-link" href="#the-problem-this-targets"> Link to heading </a> </h2> Most teams still pay the same tax: <ul> <li>duplicated contracts (controllers, OpenAPI, generated clients)</li> <li>contract drift between backend and frontend</li> <li>stale generated code</li> <li>runtime bugs shipped by “green” builds</li> </ul> The root cause is structural: the contract is treated as an artifact, not as the boundary. <hr> <h2 id="benefits"> Benefits <a class="heading-link" href="#benefits"> Link to heading </a> </h2> <ul> <li>Maximum code sharing between nodes (assuming JS/TS)</li> <li>Fully typed end-to-end, including error cases</li> <li>Uniform error handling across server and client</li> <li>Single source of truth: router and apiClient are generated from the same spec</li> </ul> Optional runtime validation can be enabled in non-prod without changing the contract. <hr> <h2 id="overlap-with-existing-approaches"> Overlap with existing approaches <a class="heading-link" href="#overlap-with-existing-approaches"> Link to heading </a> </h2> This overlaps with: <ul> <li>OpenAPI + codegen</li> <li>RPC frameworks</li> <li>shared schema repos</li> </ul> Difference: those generate code from a spec. Here, the spec is the code boundary. <hr> <h2 id="why-this-is-especially-leveraged-in-jsts"> Why this is especially leveraged in JS/TS <a class="heading-link" href="#why-this-is-especially-leveraged-in-jsts"> Link to heading </a> </h2> JS has an unfair advantage: <ul> <li>same language on backend and frontend</li> <li>TypeScript as the shared type system</li> </ul> That enables: <ul> <li>zero drift</li> <li>zero regeneration</li> <li>no stale specs</li> </ul> <hr> <h2 id="example"> Example <a class="heading-link" href="#example"> Link to heading </a> </h2> Declare your spec once: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ts" data-lang="ts">export const authRouter = { register_post: { bodySchema: registerRequestSchema, responseSchema: z.object({ token: z.string() }), cbErrorSchema: registrationError, }, login_post: { bodySchema: loginRequestSchema, responseSchema: z.object({ token: z.string() }), cbErrorSchema: loginErrors, }, refreshToken_post: { headerSchema: authHeader, cbErrorSchema: z.null(), responseSchema: z.object({ token: z.string() }), } } as const satisfies ApiSpec; export const apiSpec = { api: { auth: authRouter, macro: macroRouter } } as const satisfies ApiSpec; // key line (TS 5) //Generate both router and client from the same spec: const { router: apiRouter } = makeApi(apiSpec, {}, express.Router); //Controller implementation is fully typed by construction: makeController( authRouter.register_post, async ({ body: { email, name, password } }) =&gt; { const user = await registerUser(email, name, password); if (typeof user === &#39;string&#39;) return user; // typed error case return { token: jwtSign({ userId: user.id }) }; } ); //And the client derives from the same contract: export const { apiClient } = makeApi(apiSpec, { baseUrl: &#39;http://localhost:3033&#39; }); </code></pre></div>If you violate the contract on either side, TypeScript complains immediately. <hr> <h2 id="how-its-built"> How it’s built <a class="heading-link" href="#how-its-built"> Link to heading </a> </h2> <ul> <li>Parser types (the core mechanism): <a href="http://djuleayo.com/posts/parser-types/" class="external-link" target="_blank" rel="noopener">http://djuleayo.com/posts/parser-types/</a></li> <li>TypeScript 5 + Vite for clean cross-module sharing</li> </ul> <hr> <h2 id="what-this-optimizes-for"> What this optimizes for <a class="heading-link" href="#what-this-optimizes-for"> Link to heading </a> </h2> <ul> <li>correctness over ceremony</li> <li>DX over documentation</li> <li>contracts that cannot drift by construction</li> </ul> If you can break the contract without TypeScript complaining, the setup is wrong. <h1 id="ts-api-spec"> TS API Spec <a class="heading-link" href="#ts-api-spec"> Link to heading </a> </h1> <ul> <li>npm: <a href="https://www.npmjs.com/package/@apispects/core" class="external-link" target="_blank" rel="noopener">https://www.npmjs.com/package/@apispects/core</a></li> <li>repo: <a href="https://github.com/apispects/core" class="external-link" target="_blank" rel="noopener">https://github.com/apispects/core</a></li> </ul> <hr> <h2 id="ts-first-api-spec-with-superb-dx"> TS-first API spec with superb DX <a class="heading-link" href="#ts-first-api-spec-with-superb-dx"> Link to heading </a> </h2> <figure><img src="/tsapispec.demo.gif"> </figure> Everything is autocompleted and type-checked. As soon as the schema is satisfied, the error disappears. No separate spec file. No generation step. <hr> <h2 id="the-problem-this-targets"> The problem this targets <a class="heading-link" href="#the-problem-this-targets"> Link to heading </a> </h2> Most teams still pay the same tax: <ul> <li>duplicated contracts (controllers, OpenAPI, generated clients)</li> <li>contract drift between backend and frontend</li> <li>stale generated code</li> <li>runtime bugs shipped by “green” builds</li> </ul> The root cause is structural: the contract is treated as an artifact, not as the boundary. <hr> <h2 id="benefits"> Benefits <a class="heading-link" href="#benefits"> Link to heading </a> </h2> <ul> <li>Maximum code sharing between nodes (assuming JS/TS)</li> <li>Fully typed end-to-end, including error cases</li> <li>Uniform error handling across server and client</li> <li>Single source of truth: router and apiClient are generated from the same spec</li> </ul> Optional runtime validation can be enabled in non-prod without changing the contract. <hr> <h2 id="overlap-with-existing-approaches"> Overlap with existing approaches <a class="heading-link" href="#overlap-with-existing-approaches"> Link to heading </a> </h2> This overlaps with: <ul> <li>OpenAPI + codegen</li> <li>RPC frameworks</li> <li>shared schema repos</li> </ul> Difference: those generate code from a spec. Here, the spec is the code boundary. <hr> <h2 id="why-this-is-especially-leveraged-in-jsts"> Why this is especially leveraged in JS/TS <a class="heading-link" href="#why-this-is-especially-leveraged-in-jsts"> Link to heading </a> </h2> JS has an unfair advantage: <ul> <li>same language on backend and frontend</li> <li>TypeScript as the shared type system</li> </ul> That enables: <ul> <li>zero drift</li> <li>zero regeneration</li> <li>no stale specs</li> </ul> <hr> <h2 id="example"> Example <a class="heading-link" href="#example"> Link to heading </a> </h2> Declare your spec once: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ts" data-lang="ts">export const authRouter = { register_post: { bodySchema: registerRequestSchema, responseSchema: z.object({ token: z.string() }), cbErrorSchema: registrationError, }, login_post: { bodySchema: loginRequestSchema, responseSchema: z.object({ token: z.string() }), cbErrorSchema: loginErrors, }, refreshToken_post: { headerSchema: authHeader, cbErrorSchema: z.null(), responseSchema: z.object({ token: z.string() }), } } as const satisfies ApiSpec; export const apiSpec = { api: { auth: authRouter, macro: macroRouter } } as const satisfies ApiSpec; // key line (TS 5) //Generate both router and client from the same spec: const { router: apiRouter } = makeApi(apiSpec, {}, express.Router); //Controller implementation is fully typed by construction: makeController( authRouter.register_post, async ({ body: { email, name, password } }) =&gt; { const user = await registerUser(email, name, password); if (typeof user === &#39;string&#39;) return user; // typed error case return { token: jwtSign({ userId: user.id }) }; } ); //And the client derives from the same contract: export const { apiClient } = makeApi(apiSpec, { baseUrl: &#39;http://localhost:3033&#39; }); </code></pre></div>If you violate the contract on either side, TypeScript complains immediately. <hr> <h2 id="how-its-built"> How it’s built <a class="heading-link" href="#how-its-built"> Link to heading </a> </h2> <ul> <li>Parser types (the core mechanism): <a href="http://djuleayo.com/posts/parser-types/" class="external-link" target="_blank" rel="noopener">http://djuleayo.com/posts/parser-types/</a></li> <li>TypeScript 5 + Vite for clean cross-module sharing</li> </ul> <hr> <h2 id="what-this-optimizes-for"> What this optimizes for <a class="heading-link" href="#what-this-optimizes-for"> Link to heading </a> </h2> <ul> <li>correctness over ceremony</li> <li>DX over documentation</li> <li>contracts that cannot drift by construction</li> </ul> If you can break the contract without TypeScript complaining, the setup is wrong. Parser types https://316c0611.personalpage-ahl.pages.dev/posts/parser-types/ https://316c0611.personalpage-ahl.pages.dev/posts/parser-types/ Thu, 24 Jul 2025 11:13:48 +0200 <h1 id="parser-types"> Parser types <a class="heading-link" href="#parser-types"> Link to heading </a> </h1> <h2 id="intro--formal-languages-and-parsing"> Intro — formal languages and parsing <a class="heading-link" href="#intro--formal-languages-and-parsing"> Link to heading </a> </h2> All programming languages are specified by a grammar. A grammar tells us whether a piece of text is a valid sentence in that language. A parser generator can take such a grammar and produce a parser. Parsing is the “front end” of compilation: it turns raw text into structure. That’s the basis of how formal languages work. Simplistic grammar example: <pre tabindex="0"><code class="language-bison" data-lang="bison">%token &lt;int&gt; NUMBER expression: expression &#39;+&#39; expression | expression &#39;-&#39; expression | expression &#39;*&#39; expression | expression &#39;/&#39; expression | &#39;(&#39; expression &#39;)&#39; | NUMBER ; </code></pre>This grammar can generate a parser for simple arithmetic. Before parsing, the input is just text. After parsing, we both <ul> <li>(a) know whether it’s valid under this grammar and</li> <li>(b) obtain a structured representation of it.</li> </ul> Input: <pre tabindex="0"><code>1 + 2 * (3 - 4) </code></pre>Parsed tree: <pre tabindex="0"><code> + / \ 1 * / \ 2 - / \ 3 4 </code></pre>Operator precedence and associativity are encoded in how the tree “leans.” This is an Abstract Syntax Tree (AST). Every program you’ve ever written is, at some level, an AST. <h2 id="declarative-vs-imperative-why-we-like-trees-as-data"> Declarative vs. imperative (why we like trees-as-data) <a class="heading-link" href="#declarative-vs-imperative-why-we-like-trees-as-data"> Link to heading </a> </h2> An AST is a tree, and a tree is data. Code can be seen as data laid out in a shape that captures meaning. The tree is a constant shape that other parts of the system can consume. That’s powerful. Take an Express router: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-javascript" data-lang="javascript">router.get(&#39;/users&#39;, (req, res) =&gt; { res.send(&#39;Users list&#39;); }); </code></pre></div>You’re not imperatively pushing bytes through sockets; you declare what should happen on /users. The framework consumes that declaration at the right time. Declarative style usually means: you state what you want; the machinery figures out how. The more capable the machinery, the richer the configuration language must be. <h2 id="parser-types-1"> Parser types <a class="heading-link" href="#parser-types-1"> Link to heading </a> </h2> Configurations aren’t always free-form; values often depend on each other. Not every config that “type-checks” at the top level is semantically valid. Think of a configuration as: <blockquote> a constant value that must satisfy a language (expressed as an AST)</blockquote> If that clicks, good. TypeScript lets us enforce such languages at compile time. I call these parser types: recursive TS types that act like a grammar. They don’t parse tokens; they constrain shape the way a grammar constrains sentences. Consider: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Test = Record&lt;string, Test&gt; // ❌ can&#39;t do </code></pre></div>TS sees a naked, non-terminating recursion and bails. Even: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Test = Record&lt;string, Test | string&gt; </code></pre></div>still trips the checker. But: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Test = { [key: string]: Test | string // ✅ can do } </code></pre></div>works. The index signature form delays evaluation enough for TS to accept the recursion. That’s our recursive hook. Depth is unbounded (until compiler limits), so it can “eat” arbitrarily deep objects. The remaining task is to encode your language rules with unions and recursion. TypeScript even nudges us syntactically—the leading pipes look exactly like grammar alternatives: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Literal = | string | number | boolean ; </code></pre></div>Now, your arithmetic example as a type-level grammar: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Literal_t = &#39;number&#39;; const ops = [&#39;+&#39;, &#39;-&#39;, &#39;*&#39;, &#39;/&#39;] as const; type Op = typeof ops[number]; // 1) leaf interface NumberLiteral { type: &#39;number&#39;; value: number; } // 2) binary interface BinaryExpr { type: &#39;binary&#39;; op: Op; left: Expression; right: Expression; } // 3) grouping interface ParenExpr { type: &#39;group&#39;; expression: Expression; } // 4) the one non-recursive alias export type Expression = | NumberLiteral | BinaryExpr | ParenExpr ; // type annotation assures the object matches the grammar as AST const ast: Expression = { type: &#39;binary&#39;, op: &#39;+&#39;, left: { type: &#39;number&#39;, value: 1 }, right: { type: &#39;binary&#39;, test: &#39;asdf&#39;, // ❌ type error op: &#39;*&#39;, left: { type: &#39;number&#39;, value: 2 }, right: { type: &#39;number&#39;, value: 3 }, } }; </code></pre></div>That stray test: &lsquo;asdf&rsquo; is illegal under the grammar and TypeScript tells you immediately. Bonus: editor autocomplete now “knows” exactly what belongs where in your config/AST. <h2 id="why-would-you-care"> Why would you care? <a class="heading-link" href="#why-would-you-care"> Link to heading </a> </h2> Already mentioned: grammar can check more then any type union can. But another area is COMPOSITE PATTERN constants. IE JSX is composite. Child of a node is again JSX node. Composite patterns are omnipresent yet constants of composite patterns are very error prone. Especially written by hand without assistance of language server. Now JSX is solved as it is. Syntax sugar for function calls. Thats runtime in essence and not a constant. I&rsquo;ll hint another example of composite that with some effort of defining proper &ldquo;parser type&rdquo;, we can declare as constants with full type support. Server routers. They are composable. and leafs are controllers. Such constant would be SSOT which is effectively shared contract between server and client. Out of the box both api client and controller functions would have full type support. You can say, well we can use open API spec for that. But such a type would allow full type support just out of declaration and nothing more. No generate types step, code gen, eventual DRY hell retyping schemas and so on. In next post I&rsquo;ll show how to do that with a real example. Stay tuned. <h1 id="parser-types"> Parser types <a class="heading-link" href="#parser-types"> Link to heading </a> </h1> <h2 id="intro--formal-languages-and-parsing"> Intro — formal languages and parsing <a class="heading-link" href="#intro--formal-languages-and-parsing"> Link to heading </a> </h2> All programming languages are specified by a grammar. A grammar tells us whether a piece of text is a valid sentence in that language. A parser generator can take such a grammar and produce a parser. Parsing is the “front end” of compilation: it turns raw text into structure. That’s the basis of how formal languages work. Simplistic grammar example: <pre tabindex="0"><code class="language-bison" data-lang="bison">%token &lt;int&gt; NUMBER expression: expression &#39;+&#39; expression | expression &#39;-&#39; expression | expression &#39;*&#39; expression | expression &#39;/&#39; expression | &#39;(&#39; expression &#39;)&#39; | NUMBER ; </code></pre>This grammar can generate a parser for simple arithmetic. Before parsing, the input is just text. After parsing, we both <ul> <li>(a) know whether it’s valid under this grammar and</li> <li>(b) obtain a structured representation of it.</li> </ul> Input: <pre tabindex="0"><code>1 + 2 * (3 - 4) </code></pre>Parsed tree: <pre tabindex="0"><code> + / \ 1 * / \ 2 - / \ 3 4 </code></pre>Operator precedence and associativity are encoded in how the tree “leans.” This is an Abstract Syntax Tree (AST). Every program you’ve ever written is, at some level, an AST. <h2 id="declarative-vs-imperative-why-we-like-trees-as-data"> Declarative vs. imperative (why we like trees-as-data) <a class="heading-link" href="#declarative-vs-imperative-why-we-like-trees-as-data"> Link to heading </a> </h2> An AST is a tree, and a tree is data. Code can be seen as data laid out in a shape that captures meaning. The tree is a constant shape that other parts of the system can consume. That’s powerful. Take an Express router: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-javascript" data-lang="javascript">router.get(&#39;/users&#39;, (req, res) =&gt; { res.send(&#39;Users list&#39;); }); </code></pre></div>You’re not imperatively pushing bytes through sockets; you declare what should happen on /users. The framework consumes that declaration at the right time. Declarative style usually means: you state what you want; the machinery figures out how. The more capable the machinery, the richer the configuration language must be. <h2 id="parser-types-1"> Parser types <a class="heading-link" href="#parser-types-1"> Link to heading </a> </h2> Configurations aren’t always free-form; values often depend on each other. Not every config that “type-checks” at the top level is semantically valid. Think of a configuration as: <blockquote> a constant value that must satisfy a language (expressed as an AST)</blockquote> If that clicks, good. TypeScript lets us enforce such languages at compile time. I call these parser types: recursive TS types that act like a grammar. They don’t parse tokens; they constrain shape the way a grammar constrains sentences. Consider: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Test = Record&lt;string, Test&gt; // ❌ can&#39;t do </code></pre></div>TS sees a naked, non-terminating recursion and bails. Even: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Test = Record&lt;string, Test | string&gt; </code></pre></div>still trips the checker. But: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Test = { [key: string]: Test | string // ✅ can do } </code></pre></div>works. The index signature form delays evaluation enough for TS to accept the recursion. That’s our recursive hook. Depth is unbounded (until compiler limits), so it can “eat” arbitrarily deep objects. The remaining task is to encode your language rules with unions and recursion. TypeScript even nudges us syntactically—the leading pipes look exactly like grammar alternatives: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Literal = | string | number | boolean ; </code></pre></div>Now, your arithmetic example as a type-level grammar: <div class="highlight"><pre tabindex="0" style="color:#e6edf3;background-color:#0d1117;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-typescript" data-lang="typescript">type Literal_t = &#39;number&#39;; const ops = [&#39;+&#39;, &#39;-&#39;, &#39;*&#39;, &#39;/&#39;] as const; type Op = typeof ops[number]; // 1) leaf interface NumberLiteral { type: &#39;number&#39;; value: number; } // 2) binary interface BinaryExpr { type: &#39;binary&#39;; op: Op; left: Expression; right: Expression; } // 3) grouping interface ParenExpr { type: &#39;group&#39;; expression: Expression; } // 4) the one non-recursive alias export type Expression = | NumberLiteral | BinaryExpr | ParenExpr ; // type annotation assures the object matches the grammar as AST const ast: Expression = { type: &#39;binary&#39;, op: &#39;+&#39;, left: { type: &#39;number&#39;, value: 1 }, right: { type: &#39;binary&#39;, test: &#39;asdf&#39;, // ❌ type error op: &#39;*&#39;, left: { type: &#39;number&#39;, value: 2 }, right: { type: &#39;number&#39;, value: 3 }, } }; </code></pre></div>That stray test: &lsquo;asdf&rsquo; is illegal under the grammar and TypeScript tells you immediately. Bonus: editor autocomplete now “knows” exactly what belongs where in your config/AST. <h2 id="why-would-you-care"> Why would you care? <a class="heading-link" href="#why-would-you-care"> Link to heading </a> </h2> Already mentioned: grammar can check more then any type union can. But another area is COMPOSITE PATTERN constants. IE JSX is composite. Child of a node is again JSX node. Composite patterns are omnipresent yet constants of composite patterns are very error prone. Especially written by hand without assistance of language server. Now JSX is solved as it is. Syntax sugar for function calls. Thats runtime in essence and not a constant. I&rsquo;ll hint another example of composite that with some effort of defining proper &ldquo;parser type&rdquo;, we can declare as constants with full type support. Server routers. They are composable. and leafs are controllers. Such constant would be SSOT which is effectively shared contract between server and client. Out of the box both api client and controller functions would have full type support. You can say, well we can use open API spec for that. But such a type would allow full type support just out of declaration and nothing more. No generate types step, code gen, eventual DRY hell retyping schemas and so on. In next post I&rsquo;ll show how to do that with a real example. Stay tuned.