SSOT · djuleayo

SSOT · djuleayo https://316c0611.personalpage-ahl.pages.dev/tags/ssot/ 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.