@typokit/server-express 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import type { Express } from "express";
+import type { SerializerMap, TypoKitResponse, ValidatorMap, ValidationFieldError } from "@typokit/types";
+import type { ServerAdapter } from "@typokit/core";
+declare function validationErrorResponse(message: string, fields: ValidationFieldError[]): TypoKitResponse;
+declare function runValidators(routeHandler: {
+    validators?: {
+        params?: string;
+        query?: string;
+        body?: string;
+    };
+}, validatorMap: ValidatorMap | null, params: Record<string, string>, query: Record<string, string | string[] | undefined>, body: unknown): TypoKitResponse | undefined;
+declare function serializeResponse(response: TypoKitResponse, serializerRef: string | undefined, serializerMap: SerializerMap | null): TypoKitResponse;
+export interface ExpressServerOptions {
+    /** Pass an existing Express app instance instead of creating a new one */
+    app?: Express;
+}
+/**
+ * Create an Express server adapter for TypoKit.
+ *
+ * Provides a migration path for teams with existing Express applications.
+ *
+ * ```ts
+ * import { expressServer } from "@typokit/server-express";
+ * const adapter = expressServer();
+ * adapter.registerRoutes(routeTable, handlerMap, middlewareChain, validatorMap);
+ * const handle = await adapter.listen(3000);
+ * ```
+ */
+export declare function expressServer(options?: ExpressServerOptions): ServerAdapter;
+export { serializeResponse, runValidators, validationErrorResponse };
+export { type ServerAdapter } from "@typokit/core";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAkC,MAAM,SAAS,CAAC;AAGvE,OAAO,KAAK,EAOV,aAAa,EAGb,eAAe,EACf,YAAY,EACZ,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,eAAe,CAAC;AA4DpE,iBAAS,uBAAuB,CAC9B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,oBAAoB,EAAE,GAC7B,eAAe,CAajB;AAED,iBAAS,aAAa,CACpB,YAAY,EAAE;IACZ,UAAU,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE,EACD,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACpD,IAAI,EAAE,OAAO,GACZ,eAAe,GAAG,SAAS,CA4D7B;AAID,iBAAS,iBAAiB,CACxB,QAAQ,EAAE,eAAe,EACzB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,aAAa,EAAE,aAAa,GAAG,IAAI,GAClC,eAAe,CA8BjB;AAID,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAqM3E;AAGD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,uBAAuB,EAAE,CAAC;AACrE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,304 @@
+// @typokit/server-express — Express Server Adapter
+//
+// Translates TypoKit's compiled route table into Express-native route
+// registrations. Provides a migration path for teams with existing
+// Express applications.
+import express from "express";
+import { createServer } from "node:http";
+import { createRequestContext, executeMiddlewareChain } from "@typokit/core";
+/**
+ * Recursively walk the compiled radix tree and collect all registered routes
+ * as flat entries with their full paths reconstructed.
+ */
+function collectRoutes(node, prefix, entries) {
+    if (node.handlers) {
+        for (const [method, handler] of Object.entries(node.handlers)) {
+            if (handler) {
+                entries.push({
+                    method: method,
+                    path: prefix || "/",
+                    handlerRef: handler.ref,
+                    validators: handler.validators,
+                    serializer: handler.serializer,
+                    middleware: handler.middleware,
+                });
+            }
+        }
+    }
+    // Static children
+    if (node.children) {
+        for (const [segment, child] of Object.entries(node.children)) {
+            collectRoutes(child, `${prefix}/${segment}`, entries);
+        }
+    }
+    // Param child (:id) — Express uses :param syntax same as TypoKit
+    if (node.paramChild) {
+        const paramNode = node.paramChild;
+        collectRoutes(paramNode, `${prefix}/:${paramNode.paramName}`, entries);
+    }
+    // Wildcard child (*path)
+    if (node.wildcardChild) {
+        const wildcardNode = node.wildcardChild;
+        collectRoutes(wildcardNode, `${prefix}/*`, entries);
+    }
+}
+// ─── Request Validation Pipeline ─────────────────────────────
+function validationErrorResponse(message, fields) {
+    const body = {
+        error: {
+            code: "VALIDATION_ERROR",
+            message,
+            details: { fields },
+        },
+    };
+    return {
+        status: 400,
+        headers: { "content-type": "application/json" },
+        body,
+    };
+}
+function runValidators(routeHandler, validatorMap, params, query, body) {
+    if (!validatorMap || !routeHandler.validators) {
+        return undefined;
+    }
+    const allErrors = [];
+    if (routeHandler.validators.params) {
+        const validator = validatorMap[routeHandler.validators.params];
+        if (validator) {
+            const result = validator(params);
+            if (!result.success && result.errors) {
+                for (const e of result.errors) {
+                    allErrors.push({
+                        path: `params.${e.path}`,
+                        expected: e.expected,
+                        actual: e.actual,
+                    });
+                }
+            }
+        }
+    }
+    if (routeHandler.validators.query) {
+        const validator = validatorMap[routeHandler.validators.query];
+        if (validator) {
+            const result = validator(query);
+            if (!result.success && result.errors) {
+                for (const e of result.errors) {
+                    allErrors.push({
+                        path: `query.${e.path}`,
+                        expected: e.expected,
+                        actual: e.actual,
+                    });
+                }
+            }
+        }
+    }
+    if (routeHandler.validators.body) {
+        const validator = validatorMap[routeHandler.validators.body];
+        if (validator) {
+            const result = validator(body);
+            if (!result.success && result.errors) {
+                for (const e of result.errors) {
+                    allErrors.push({
+                        path: `body.${e.path}`,
+                        expected: e.expected,
+                        actual: e.actual,
+                    });
+                }
+            }
+        }
+    }
+    if (allErrors.length > 0) {
+        return validationErrorResponse("Request validation failed", allErrors);
+    }
+    return undefined;
+}
+// ─── Response Serialization Pipeline ──────────────────────────
+function serializeResponse(response, serializerRef, serializerMap) {
+    if (response.body === null ||
+        response.body === undefined ||
+        typeof response.body === "string") {
+        return response;
+    }
+    const headers = { ...response.headers };
+    if (!headers["content-type"]) {
+        headers["content-type"] = "application/json";
+    }
+    if (serializerRef && serializerMap) {
+        const serializer = serializerMap[serializerRef];
+        if (serializer) {
+            return {
+                ...response,
+                headers,
+                body: serializer(response.body),
+            };
+        }
+    }
+    return {
+        ...response,
+        headers,
+        body: JSON.stringify(response.body),
+    };
+}
+/**
+ * Create an Express server adapter for TypoKit.
+ *
+ * Provides a migration path for teams with existing Express applications.
+ *
+ * ```ts
+ * import { expressServer } from "@typokit/server-express";
+ * const adapter = expressServer();
+ * adapter.registerRoutes(routeTable, handlerMap, middlewareChain, validatorMap);
+ * const handle = await adapter.listen(3000);
+ * ```
+ */
+export function expressServer(options) {
+    const app = options?.app ?? express();
+    // Enable JSON body parsing
+    app.use(express.json());
+    const state = {
+        routeTable: null,
+        handlerMap: null,
+        middlewareChain: null,
+        validatorMap: null,
+        serializerMap: null,
+    };
+    /** Convert Express request to TypoKitRequest */
+    function normalizeRequest(raw) {
+        const req = raw;
+        const headers = {};
+        for (const [key, value] of Object.entries(req.headers)) {
+            headers[key] = value;
+        }
+        const query = {};
+        for (const [key, value] of Object.entries(req.query)) {
+            if (typeof value === "string") {
+                query[key] = value;
+            }
+            else if (Array.isArray(value)) {
+                query[key] = value;
+            }
+        }
+        return {
+            method: req.method.toUpperCase(),
+            path: req.path,
+            headers,
+            body: req.body,
+            query,
+            params: req.params ?? {},
+        };
+    }
+    /** Write TypoKitResponse to Express response */
+    function writeResponse(raw, response) {
+        const res = raw;
+        // Set headers
+        for (const [key, value] of Object.entries(response.headers)) {
+            if (value !== undefined) {
+                res.set(key, value);
+            }
+        }
+        res.status(response.status);
+        if (response.body === null || response.body === undefined) {
+            res.end("");
+        }
+        else {
+            res.send(response.body);
+        }
+    }
+    const adapter = {
+        name: "express",
+        registerRoutes(routeTable, handlerMap, middlewareChain, validatorMap, serializerMap) {
+            state.routeTable = routeTable;
+            state.handlerMap = handlerMap;
+            state.middlewareChain = middlewareChain;
+            state.validatorMap = validatorMap ?? null;
+            state.serializerMap = serializerMap ?? null;
+            // Collect all routes from the compiled radix tree
+            const routes = [];
+            collectRoutes(routeTable, "", routes);
+            // Register each route as an Express-native route
+            for (const route of routes) {
+                const method = route.method.toLowerCase();
+                app[method](route.path, async (req, res) => {
+                    const typoReq = normalizeRequest(req);
+                    // Run request validation pipeline
+                    const validationError = runValidators({ validators: route.validators }, state.validatorMap, typoReq.params, typoReq.query, typoReq.body);
+                    if (validationError) {
+                        writeResponse(res, validationError);
+                        return;
+                    }
+                    const handlerFn = state.handlerMap[route.handlerRef];
+                    if (!handlerFn) {
+                        const errorResp = {
+                            status: 500,
+                            headers: { "content-type": "application/json" },
+                            body: JSON.stringify({
+                                error: "Internal Server Error",
+                                message: `Handler not found: ${route.handlerRef}`,
+                            }),
+                        };
+                        writeResponse(res, errorResp);
+                        return;
+                    }
+                    // Create request context and execute middleware chain
+                    let ctx = createRequestContext();
+                    if (state.middlewareChain &&
+                        state.middlewareChain.entries.length > 0) {
+                        const entries = state.middlewareChain.entries.map((e) => ({
+                            name: e.name,
+                            middleware: {
+                                handler: async (input) => {
+                                    const mwReq = {
+                                        method: typoReq.method,
+                                        path: typoReq.path,
+                                        headers: input.headers,
+                                        body: input.body,
+                                        query: input.query,
+                                        params: input.params,
+                                    };
+                                    const response = await e.handler(mwReq, input.ctx, async () => {
+                                        return { status: 200, headers: {}, body: null };
+                                    });
+                                    return response;
+                                },
+                            },
+                        }));
+                        ctx = await executeMiddlewareChain(typoReq, ctx, entries);
+                    }
+                    // Call the handler
+                    const response = await handlerFn(typoReq, ctx);
+                    // Response serialization pipeline
+                    const serialized = serializeResponse(response, route.serializer, state.serializerMap);
+                    writeResponse(res, serialized);
+                });
+            }
+        },
+        async listen(port) {
+            const server = createServer(app);
+            await new Promise((resolve) => {
+                server.listen(port, "0.0.0.0", () => resolve());
+            });
+            return {
+                async close() {
+                    await new Promise((resolve, reject) => {
+                        server.close((err) => {
+                            if (err)
+                                reject(err);
+                            else
+                                resolve();
+                        });
+                    });
+                },
+                _server: server,
+            };
+        },
+        normalizeRequest,
+        writeResponse,
+        getNativeServer() {
+            return app;
+        },
+    };
+    return adapter;
+}
+// Re-export for convenience
+export { serializeResponse, runValidators, validationErrorResponse };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,sEAAsE;AACtE,mEAAmE;AACnE,wBAAwB;AAExB,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAiBzC,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAa7E;;;GAGG;AACH,SAAS,aAAa,CACpB,IAAmB,EACnB,MAAc,EACd,OAAqB;IAErB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9D,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,IAAI,CAAC;oBACX,MAAM,EAAE,MAAoB;oBAC5B,IAAI,EAAE,MAAM,IAAI,GAAG;oBACnB,UAAU,EAAE,OAAO,CAAC,GAAG;oBACvB,UAAU,EAAE,OAAO,CAAC,UAAU;oBAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;oBAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;iBAC/B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,kBAAkB;IAClB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7D,aAAa,CAAC,KAAK,EAAE,GAAG,MAAM,IAAI,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,iEAAiE;IACjE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,aAAa,CAAC,SAAS,EAAE,GAAG,MAAM,KAAK,SAAS,CAAC,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IACzE,CAAC;IAED,yBAAyB;IACzB,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,aAAa,CAAC,YAAY,EAAE,GAAG,MAAM,IAAI,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED,gEAAgE;AAEhE,SAAS,uBAAuB,CAC9B,OAAe,EACf,MAA8B;IAE9B,MAAM,IAAI,GAAkB;QAC1B,KAAK,EAAE;YACL,IAAI,EAAE,kBAAkB;YACxB,OAAO;YACP,OAAO,EAAE,EAAE,MAAM,EAAE;SACpB;KACF,CAAC;IACF,OAAO;QACL,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI;KACL,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CACpB,YAEC,EACD,YAAiC,EACjC,MAA8B,EAC9B,KAAoD,EACpD,IAAa;IAEb,IAAI,CAAC,YAAY,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC;QAC9C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,SAAS,GAA2B,EAAE,CAAC;IAE7C,IAAI,YAAY,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,YAAY,CAAC,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC/D,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBACrC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;oBAC9B,SAAS,CAAC,IAAI,CAAC;wBACb,IAAI,EAAE,UAAU,CAAC,CAAC,IAAI,EAAE;wBACxB,QAAQ,EAAE,CAAC,CAAC,QAAQ;wBACpB,MAAM,EAAE,CAAC,CAAC,MAAM;qBACjB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,YAAY,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC9D,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;YAChC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBACrC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;oBAC9B,SAAS,CAAC,IAAI,CAAC;wBACb,IAAI,EAAE,SAAS,CAAC,CAAC,IAAI,EAAE;wBACvB,QAAQ,EAAE,CAAC,CAAC,QAAQ;wBACpB,MAAM,EAAE,CAAC,CAAC,MAAM;qBACjB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,YAAY,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC7D,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBACrC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;oBAC9B,SAAS,CAAC,IAAI,CAAC;wBACb,IAAI,EAAE,QAAQ,CAAC,CAAC,IAAI,EAAE;wBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;wBACpB,MAAM,EAAE,CAAC,CAAC,MAAM;qBACjB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,uBAAuB,CAAC,2BAA2B,EAAE,SAAS,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,iEAAiE;AAEjE,SAAS,iBAAiB,CACxB,QAAyB,EACzB,aAAiC,EACjC,aAAmC;IAEnC,IACE,QAAQ,CAAC,IAAI,KAAK,IAAI;QACtB,QAAQ,CAAC,IAAI,KAAK,SAAS;QAC3B,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ,EACjC,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC;IACxC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;IAC/C,CAAC;IAED,IAAI,aAAa,IAAI,aAAa,EAAE,CAAC;QACnC,MAAM,UAAU,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;QAChD,IAAI,UAAU,EAAE,CAAC;YACf,OAAO;gBACL,GAAG,QAAQ;gBACX,OAAO;gBACP,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;aAChC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,QAAQ;QACX,OAAO;QACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;KACpC,CAAC;AACJ,CAAC;AAiBD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,OAA8B;IAC1D,MAAM,GAAG,GAAY,OAAO,EAAE,GAAG,IAAI,OAAO,EAAE,CAAC;IAE/C,2BAA2B;IAC3B,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAExB,MAAM,KAAK,GAAuB;QAChC,UAAU,EAAE,IAAI;QAChB,UAAU,EAAE,IAAI;QAChB,eAAe,EAAE,IAAI;QACrB,YAAY,EAAE,IAAI;QAClB,aAAa,EAAE,IAAI;KACpB,CAAC;IAEF,gDAAgD;IAChD,SAAS,gBAAgB,CAAC,GAAY;QACpC,MAAM,GAAG,GAAG,GAAc,CAAC;QAC3B,MAAM,OAAO,GAAkD,EAAE,CAAC;QAClE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACvD,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACvB,CAAC;QAED,MAAM,KAAK,GAAkD,EAAE,CAAC;QAChE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACrB,CAAC;iBAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAiB,CAAC;YACjC,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,WAAW,EAAgB;YAC9C,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO;YACP,IAAI,EAAE,GAAG,CAAC,IAAe;YACzB,KAAK;YACL,MAAM,EAAG,GAAG,CAAC,MAAiC,IAAI,EAAE;SACrD,CAAC;IACJ,CAAC;IAED,gDAAgD;IAChD,SAAS,aAAa,CAAC,GAAY,EAAE,QAAyB;QAC5D,MAAM,GAAG,GAAG,GAAe,CAAC;QAE5B,cAAc;QACd,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QAED,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAE5B,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC1D,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACd,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAkB;QAC7B,IAAI,EAAE,SAAS;QAEf,cAAc,CACZ,UAA8B,EAC9B,UAAsB,EACtB,eAAgC,EAChC,YAA2B,EAC3B,aAA6B;YAE7B,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC;YAC9B,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC;YAC9B,KAAK,CAAC,eAAe,GAAG,eAAe,CAAC;YACxC,KAAK,CAAC,YAAY,GAAG,YAAY,IAAI,IAAI,CAAC;YAC1C,KAAK,CAAC,aAAa,GAAG,aAAa,IAAI,IAAI,CAAC;YAE5C,kDAAkD;YAClD,MAAM,MAAM,GAAiB,EAAE,CAAC;YAChC,aAAa,CAAC,UAAU,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;YAEtC,iDAAiD;YACjD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAGtC,CAAC;gBAEF,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;oBAC5D,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;oBAEtC,kCAAkC;oBAClC,MAAM,eAAe,GAAG,aAAa,CACnC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,EAChC,KAAK,CAAC,YAAY,EAClB,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,KAAK,EACb,OAAO,CAAC,IAAI,CACb,CAAC;oBACF,IAAI,eAAe,EAAE,CAAC;wBACpB,aAAa,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;wBACpC,OAAO;oBACT,CAAC;oBAED,MAAM,SAAS,GAAG,KAAK,CAAC,UAAW,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;oBACtD,IAAI,CAAC,SAAS,EAAE,CAAC;wBACf,MAAM,SAAS,GAAoB;4BACjC,MAAM,EAAE,GAAG;4BACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;4BAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gCACnB,KAAK,EAAE,uBAAuB;gCAC9B,OAAO,EAAE,sBAAsB,KAAK,CAAC,UAAU,EAAE;6BAClD,CAAC;yBACH,CAAC;wBACF,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;wBAC9B,OAAO;oBACT,CAAC;oBAED,sDAAsD;oBACtD,IAAI,GAAG,GAAG,oBAAoB,EAAE,CAAC;oBAEjC,IACE,KAAK,CAAC,eAAe;wBACrB,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EACxC,CAAC;wBACD,MAAM,OAAO,GACX,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;4BACxC,IAAI,EAAE,CAAC,CAAC,IAAI;4BACZ,UAAU,EAAE;gCACV,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;oCACvB,MAAM,KAAK,GAAmB;wCAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;wCACtB,IAAI,EAAE,OAAO,CAAC,IAAI;wCAClB,OAAO,EAAE,KAAK,CAAC,OAAO;wCACtB,IAAI,EAAE,KAAK,CAAC,IAAI;wCAChB,KAAK,EAAE,KAAK,CAAC,KAAK;wCAClB,MAAM,EAAE,KAAK,CAAC,MAAM;qCACrB,CAAC;oCACF,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,OAAO,CAC9B,KAAK,EACL,KAAK,CAAC,GAAG,EACT,KAAK,IAAI,EAAE;wCACT,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;oCAClD,CAAC,CACF,CAAC;oCACF,OAAO,QAA8C,CAAC;gCACxD,CAAC;6BACF;yBACF,CAAC,CAAC,CAAC;wBAEN,GAAG,GAAG,MAAM,sBAAsB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;oBAC5D,CAAC;oBAED,mBAAmB;oBACnB,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;oBAE/C,kCAAkC;oBAClC,MAAM,UAAU,GAAG,iBAAiB,CAClC,QAAQ,EACR,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,aAAa,CACpB,CAAC;oBAEF,aAAa,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;gBACjC,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,IAAY;YACvB,MAAM,MAAM,GAAW,YAAY,CAAC,GAAG,CAAC,CAAC;YAEzC,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAClC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;YAClD,CAAC,CAAC,CAAC;YAEH,OAAO;gBACL,KAAK,CAAC,KAAK;oBACT,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;wBAC1C,MAAM,CAAC,KAAK,CAAC,CAAC,GAAW,EAAE,EAAE;4BAC3B,IAAI,GAAG;gCAAE,MAAM,CAAC,GAAG,CAAC,CAAC;;gCAChB,OAAO,EAAE,CAAC;wBACjB,CAAC,CAAC,CAAC;oBACL,CAAC,CAAC,CAAC;gBACL,CAAC;gBACD,OAAO,EAAE,MAAM;aACsB,CAAC;QAC1C,CAAC;QAED,gBAAgB;QAChB,aAAa;QAEb,eAAe;YACb,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,4BAA4B;AAC5B,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,uBAAuB,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@typokit/server-express",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "version": "0.1.4",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "express": "^5.1.0",
+    "@typokit/types": "0.1.4",
+    "@typokit/core": "0.1.4"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KyleBastien/typokit",
+    "directory": "packages/server-express"
+  },
+  "scripts": {
+    "test": "rstest run --passWithNoTests"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,297 @@
+// @typokit/server-express — Integration tests
+import { describe, it, expect } from "@rstest/core";
+import { expressServer } from "./index.js";
+import type {
+  CompiledRouteTable,
+  HandlerMap,
+  MiddlewareChain,
+  ValidatorMap,
+  TypoKitRequest,
+  TypoKitResponse,
+  RequestContext,
+  ServerHandle,
+} from "@typokit/types";
+import type { Server } from "node:http";
+
+// ─── Test Helpers ────────────────────────────────────────────
+
+function makeRouteTable(
+  routes: {
+    method: string;
+    path: string;
+    ref: string;
+    validators?: { params?: string; query?: string; body?: string };
+  }[],
+): CompiledRouteTable {
+  const root: CompiledRouteTable = {
+    segment: "",
+    children: {},
+  };
+
+  for (const route of routes) {
+    const segments = route.path.split("/").filter(Boolean);
+    let current: CompiledRouteTable = root;
+
+    for (const seg of segments) {
+      if (seg.startsWith(":")) {
+        if (!current.paramChild) {
+          current.paramChild = {
+            segment: seg.slice(1),
+            paramName: seg.slice(1),
+            children: {},
+          };
+        }
+        current = current.paramChild;
+      } else {
+        if (!current.children![seg]) {
+          current.children![seg] = { segment: seg, children: {} };
+        }
+        current = current.children![seg];
+      }
+    }
+
+    if (!current.handlers) {
+      current.handlers = {};
+    }
+    (current.handlers as Record<string, unknown>)[route.method] = {
+      ref: route.ref,
+      validators: route.validators,
+      middleware: [],
+    };
+  }
+
+  return root;
+}
+
+function makeMiddlewareChain(): MiddlewareChain {
+  return { entries: [] };
+}
+
+async function fetchJson(port: number, path: string, options?: RequestInit) {
+  const res = await fetch(`http://127.0.0.1:${port}${path}`, options);
+  const text = await res.text();
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+  return {
+    status: res.status,
+    body,
+    headers: Object.fromEntries(res.headers.entries()),
+  };
+}
+
+// ─── Tests ───────────────────────────────────────────────────
+
+describe("expressServer", () => {
+  it("creates an adapter with correct name", () => {
+    const adapter = expressServer();
+    expect(adapter.name).toBe("express");
+  });
+
+  it("getNativeServer returns Express app", () => {
+    const adapter = expressServer();
+    const app = adapter.getNativeServer!();
+    expect(app).toBeDefined();
+    expect(typeof (app as Record<string, unknown>).use).toBe("function");
+  });
+
+  it("normalizeRequest converts Express request shape", () => {
+    const adapter = expressServer();
+    const mockReq = {
+      method: "GET",
+      path: "/test",
+      headers: { "content-type": "application/json" },
+      body: undefined,
+      query: { page: "1" },
+      params: { id: "42" },
+    };
+    const normalized = adapter.normalizeRequest(mockReq);
+    expect(normalized.method).toBe("GET");
+    expect(normalized.path).toBe("/test");
+    expect(normalized.params.id).toBe("42");
+  });
+});
+
+describe("expressServer integration", () => {
+  let handle: ServerHandle & { _server?: Server };
+  let port: number;
+
+  it("starts server, handles GET, and shuts down", async () => {
+    const routeTable = makeRouteTable([
+      { method: "GET", path: "/health", ref: "getHealth" },
+    ]);
+
+    const handlerMap: HandlerMap = {
+      getHealth: async (
+        _req: TypoKitRequest,
+        _ctx: RequestContext,
+      ): Promise<TypoKitResponse> => ({
+        status: 200,
+        headers: {},
+        body: { status: "ok" },
+      }),
+    };
+
+    const adapter = expressServer();
+    adapter.registerRoutes(routeTable, handlerMap, makeMiddlewareChain());
+    handle = (await adapter.listen(0)) as ServerHandle & { _server?: Server };
+
+    const addr = handle._server!.address();
+    port = typeof addr === "object" && addr !== null ? addr.port : 0;
+
+    const res = await fetchJson(port, "/health");
+    expect(res.status).toBe(200);
+    expect((res.body as Record<string, unknown>).status).toBe("ok");
+
+    await handle.close();
+  });
+
+  it("handles POST with JSON body", async () => {
+    const routeTable = makeRouteTable([
+      { method: "POST", path: "/items", ref: "createItem" },
+    ]);
+
+    const handlerMap: HandlerMap = {
+      createItem: async (
+        req: TypoKitRequest,
+        _ctx: RequestContext,
+      ): Promise<TypoKitResponse> => ({
+        status: 201,
+        headers: {},
+        body: {
+          created: true,
+          name: (req.body as Record<string, unknown>)?.name,
+        },
+      }),
+    };
+
+    const adapter = expressServer();
+    adapter.registerRoutes(routeTable, handlerMap, makeMiddlewareChain());
+    handle = (await adapter.listen(0)) as ServerHandle & { _server?: Server };
+
+    const addr = handle._server!.address();
+    port = typeof addr === "object" && addr !== null ? addr.port : 0;
+
+    const res = await fetchJson(port, "/items", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "test-item" }),
+    });
+    expect(res.status).toBe(201);
+    expect((res.body as Record<string, unknown>).name).toBe("test-item");
+
+    await handle.close();
+  });
+
+  it("handles parameterized routes", async () => {
+    const routeTable = makeRouteTable([
+      { method: "GET", path: "/items/:id", ref: "getItem" },
+    ]);
+
+    const handlerMap: HandlerMap = {
+      getItem: async (
+        req: TypoKitRequest,
+        _ctx: RequestContext,
+      ): Promise<TypoKitResponse> => ({
+        status: 200,
+        headers: {},
+        body: { id: req.params.id },
+      }),
+    };
+
+    const adapter = expressServer();
+    adapter.registerRoutes(routeTable, handlerMap, makeMiddlewareChain());
+    handle = (await adapter.listen(0)) as ServerHandle & { _server?: Server };
+
+    const addr = handle._server!.address();
+    port = typeof addr === "object" && addr !== null ? addr.port : 0;
+
+    const res = await fetchJson(port, "/items/abc123");
+    expect(res.status).toBe(200);
+    expect((res.body as Record<string, unknown>).id).toBe("abc123");
+
+    await handle.close();
+  });
+
+  it("runs validation and returns 400 on failure", async () => {
+    const routeTable = makeRouteTable([
+      {
+        method: "POST",
+        path: "/validated",
+        ref: "validatedHandler",
+        validators: { body: "validateBody" },
+      },
+    ]);
+
+    const handlerMap: HandlerMap = {
+      validatedHandler: async (
+        _req: TypoKitRequest,
+        _ctx: RequestContext,
+      ): Promise<TypoKitResponse> => ({
+        status: 200,
+        headers: {},
+        body: { ok: true },
+      }),
+    };
+
+    const validatorMap: ValidatorMap = {
+      validateBody: (data: unknown) => {
+        const body = data as Record<string, unknown>;
+        if (!body || !body.name) {
+          return {
+            success: false,
+            errors: [{ path: "name", expected: "string", actual: "undefined" }],
+          };
+        }
+        return { success: true };
+      },
+    };
+
+    const adapter = expressServer();
+    adapter.registerRoutes(
+      routeTable,
+      handlerMap,
+      makeMiddlewareChain(),
+      validatorMap,
+    );
+    handle = (await adapter.listen(0)) as ServerHandle & { _server?: Server };
+
+    const addr = handle._server!.address();
+    port = typeof addr === "object" && addr !== null ? addr.port : 0;
+
+    // Send invalid body
+    const res = await fetchJson(port, "/validated", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+    const body = res.body as { error: { code: string } };
+    expect(body.error.code).toBe("VALIDATION_ERROR");
+
+    await handle.close();
+  });
+
+  it("returns 500 for missing handler", async () => {
+    const routeTable = makeRouteTable([
+      { method: "GET", path: "/missing", ref: "nonExistentHandler" },
+    ]);
+
+    const handlerMap: HandlerMap = {};
+
+    const adapter = expressServer();
+    adapter.registerRoutes(routeTable, handlerMap, makeMiddlewareChain());
+    handle = (await adapter.listen(0)) as ServerHandle & { _server?: Server };
+
+    const addr = handle._server!.address();
+    port = typeof addr === "object" && addr !== null ? addr.port : 0;
+
+    const res = await fetchJson(port, "/missing");
+    expect(res.status).toBe(500);
+
+    await handle.close();
+  });
+});

package/src/index.ts

@@ -0,0 +1,439 @@
+// @typokit/server-express — Express Server Adapter
+//
+// Translates TypoKit's compiled route table into Express-native route
+// registrations. Provides a migration path for teams with existing
+// Express applications.
+
+import express from "express";
+import type { Express, Request, Response, Application } from "express";
+import { createServer } from "node:http";
+import type { Server } from "node:http";
+import type {
+  CompiledRoute,
+  CompiledRouteTable,
+  ErrorResponse,
+  HandlerMap,
+  HttpMethod,
+  MiddlewareChain,
+  SerializerMap,
+  ServerHandle,
+  TypoKitRequest,
+  TypoKitResponse,
+  ValidatorMap,
+  ValidationFieldError,
+} from "@typokit/types";
+import type { ServerAdapter, MiddlewareEntry } from "@typokit/core";
+import { createRequestContext, executeMiddlewareChain } from "@typokit/core";
+
+// ─── Route Traversal ─────────────────────────────────────────
+
+interface RouteEntry {
+  method: HttpMethod;
+  path: string;
+  handlerRef: string;
+  validators?: { params?: string; query?: string; body?: string };
+  serializer?: string;
+  middleware: string[];
+}
+
+/**
+ * Recursively walk the compiled radix tree and collect all registered routes
+ * as flat entries with their full paths reconstructed.
+ */
+function collectRoutes(
+  node: CompiledRoute,
+  prefix: string,
+  entries: RouteEntry[],
+): void {
+  if (node.handlers) {
+    for (const [method, handler] of Object.entries(node.handlers)) {
+      if (handler) {
+        entries.push({
+          method: method as HttpMethod,
+          path: prefix || "/",
+          handlerRef: handler.ref,
+          validators: handler.validators,
+          serializer: handler.serializer,
+          middleware: handler.middleware,
+        });
+      }
+    }
+  }
+
+  // Static children
+  if (node.children) {
+    for (const [segment, child] of Object.entries(node.children)) {
+      collectRoutes(child, `${prefix}/${segment}`, entries);
+    }
+  }
+
+  // Param child (:id) — Express uses :param syntax same as TypoKit
+  if (node.paramChild) {
+    const paramNode = node.paramChild;
+    collectRoutes(paramNode, `${prefix}/:${paramNode.paramName}`, entries);
+  }
+
+  // Wildcard child (*path)
+  if (node.wildcardChild) {
+    const wildcardNode = node.wildcardChild;
+    collectRoutes(wildcardNode, `${prefix}/*`, entries);
+  }
+}
+
+// ─── Request Validation Pipeline ─────────────────────────────
+
+function validationErrorResponse(
+  message: string,
+  fields: ValidationFieldError[],
+): TypoKitResponse {
+  const body: ErrorResponse = {
+    error: {
+      code: "VALIDATION_ERROR",
+      message,
+      details: { fields },
+    },
+  };
+  return {
+    status: 400,
+    headers: { "content-type": "application/json" },
+    body,
+  };
+}
+
+function runValidators(
+  routeHandler: {
+    validators?: { params?: string; query?: string; body?: string };
+  },
+  validatorMap: ValidatorMap | null,
+  params: Record<string, string>,
+  query: Record<string, string | string[] | undefined>,
+  body: unknown,
+): TypoKitResponse | undefined {
+  if (!validatorMap || !routeHandler.validators) {
+    return undefined;
+  }
+
+  const allErrors: ValidationFieldError[] = [];
+
+  if (routeHandler.validators.params) {
+    const validator = validatorMap[routeHandler.validators.params];
+    if (validator) {
+      const result = validator(params);
+      if (!result.success && result.errors) {
+        for (const e of result.errors) {
+          allErrors.push({
+            path: `params.${e.path}`,
+            expected: e.expected,
+            actual: e.actual,
+          });
+        }
+      }
+    }
+  }
+
+  if (routeHandler.validators.query) {
+    const validator = validatorMap[routeHandler.validators.query];
+    if (validator) {
+      const result = validator(query);
+      if (!result.success && result.errors) {
+        for (const e of result.errors) {
+          allErrors.push({
+            path: `query.${e.path}`,
+            expected: e.expected,
+            actual: e.actual,
+          });
+        }
+      }
+    }
+  }
+
+  if (routeHandler.validators.body) {
+    const validator = validatorMap[routeHandler.validators.body];
+    if (validator) {
+      const result = validator(body);
+      if (!result.success && result.errors) {
+        for (const e of result.errors) {
+          allErrors.push({
+            path: `body.${e.path}`,
+            expected: e.expected,
+            actual: e.actual,
+          });
+        }
+      }
+    }
+  }
+
+  if (allErrors.length > 0) {
+    return validationErrorResponse("Request validation failed", allErrors);
+  }
+
+  return undefined;
+}
+
+// ─── Response Serialization Pipeline ──────────────────────────
+
+function serializeResponse(
+  response: TypoKitResponse,
+  serializerRef: string | undefined,
+  serializerMap: SerializerMap | null,
+): TypoKitResponse {
+  if (
+    response.body === null ||
+    response.body === undefined ||
+    typeof response.body === "string"
+  ) {
+    return response;
+  }
+
+  const headers = { ...response.headers };
+  if (!headers["content-type"]) {
+    headers["content-type"] = "application/json";
+  }
+
+  if (serializerRef && serializerMap) {
+    const serializer = serializerMap[serializerRef];
+    if (serializer) {
+      return {
+        ...response,
+        headers,
+        body: serializer(response.body),
+      };
+    }
+  }
+
+  return {
+    ...response,
+    headers,
+    body: JSON.stringify(response.body),
+  };
+}
+
+// ─── Express Server Adapter ──────────────────────────────────
+
+export interface ExpressServerOptions {
+  /** Pass an existing Express app instance instead of creating a new one */
+  app?: Express;
+}
+
+interface ExpressServerState {
+  routeTable: CompiledRouteTable | null;
+  handlerMap: HandlerMap | null;
+  middlewareChain: MiddlewareChain | null;
+  validatorMap: ValidatorMap | null;
+  serializerMap: SerializerMap | null;
+}
+
+/**
+ * Create an Express server adapter for TypoKit.
+ *
+ * Provides a migration path for teams with existing Express applications.
+ *
+ * ```ts
+ * import { expressServer } from "@typokit/server-express";
+ * const adapter = expressServer();
+ * adapter.registerRoutes(routeTable, handlerMap, middlewareChain, validatorMap);
+ * const handle = await adapter.listen(3000);
+ * ```
+ */
+export function expressServer(options?: ExpressServerOptions): ServerAdapter {
+  const app: Express = options?.app ?? express();
+
+  // Enable JSON body parsing
+  app.use(express.json());
+
+  const state: ExpressServerState = {
+    routeTable: null,
+    handlerMap: null,
+    middlewareChain: null,
+    validatorMap: null,
+    serializerMap: null,
+  };
+
+  /** Convert Express request to TypoKitRequest */
+  function normalizeRequest(raw: unknown): TypoKitRequest {
+    const req = raw as Request;
+    const headers: Record<string, string | string[] | undefined> = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+      headers[key] = value;
+    }
+
+    const query: Record<string, string | string[] | undefined> = {};
+    for (const [key, value] of Object.entries(req.query)) {
+      if (typeof value === "string") {
+        query[key] = value;
+      } else if (Array.isArray(value)) {
+        query[key] = value as string[];
+      }
+    }
+
+    return {
+      method: req.method.toUpperCase() as HttpMethod,
+      path: req.path,
+      headers,
+      body: req.body as unknown,
+      query,
+      params: (req.params as Record<string, string>) ?? {},
+    };
+  }
+
+  /** Write TypoKitResponse to Express response */
+  function writeResponse(raw: unknown, response: TypoKitResponse): void {
+    const res = raw as Response;
+
+    // Set headers
+    for (const [key, value] of Object.entries(response.headers)) {
+      if (value !== undefined) {
+        res.set(key, value);
+      }
+    }
+
+    res.status(response.status);
+
+    if (response.body === null || response.body === undefined) {
+      res.end("");
+    } else {
+      res.send(response.body);
+    }
+  }
+
+  const adapter: ServerAdapter = {
+    name: "express",
+
+    registerRoutes(
+      routeTable: CompiledRouteTable,
+      handlerMap: HandlerMap,
+      middlewareChain: MiddlewareChain,
+      validatorMap?: ValidatorMap,
+      serializerMap?: SerializerMap,
+    ): void {
+      state.routeTable = routeTable;
+      state.handlerMap = handlerMap;
+      state.middlewareChain = middlewareChain;
+      state.validatorMap = validatorMap ?? null;
+      state.serializerMap = serializerMap ?? null;
+
+      // Collect all routes from the compiled radix tree
+      const routes: RouteEntry[] = [];
+      collectRoutes(routeTable, "", routes);
+
+      // Register each route as an Express-native route
+      for (const route of routes) {
+        const method = route.method.toLowerCase() as keyof Pick<
+          Application,
+          "get" | "post" | "put" | "delete" | "patch" | "options" | "head"
+        >;
+
+        app[method](route.path, async (req: Request, res: Response) => {
+          const typoReq = normalizeRequest(req);
+
+          // Run request validation pipeline
+          const validationError = runValidators(
+            { validators: route.validators },
+            state.validatorMap,
+            typoReq.params,
+            typoReq.query,
+            typoReq.body,
+          );
+          if (validationError) {
+            writeResponse(res, validationError);
+            return;
+          }
+
+          const handlerFn = state.handlerMap![route.handlerRef];
+          if (!handlerFn) {
+            const errorResp: TypoKitResponse = {
+              status: 500,
+              headers: { "content-type": "application/json" },
+              body: JSON.stringify({
+                error: "Internal Server Error",
+                message: `Handler not found: ${route.handlerRef}`,
+              }),
+            };
+            writeResponse(res, errorResp);
+            return;
+          }
+
+          // Create request context and execute middleware chain
+          let ctx = createRequestContext();
+
+          if (
+            state.middlewareChain &&
+            state.middlewareChain.entries.length > 0
+          ) {
+            const entries: MiddlewareEntry[] =
+              state.middlewareChain.entries.map((e) => ({
+                name: e.name,
+                middleware: {
+                  handler: async (input) => {
+                    const mwReq: TypoKitRequest = {
+                      method: typoReq.method,
+                      path: typoReq.path,
+                      headers: input.headers,
+                      body: input.body,
+                      query: input.query,
+                      params: input.params,
+                    };
+                    const response = await e.handler(
+                      mwReq,
+                      input.ctx,
+                      async () => {
+                        return { status: 200, headers: {}, body: null };
+                      },
+                    );
+                    return response as unknown as Record<string, unknown>;
+                  },
+                },
+              }));
+
+            ctx = await executeMiddlewareChain(typoReq, ctx, entries);
+          }
+
+          // Call the handler
+          const response = await handlerFn(typoReq, ctx);
+
+          // Response serialization pipeline
+          const serialized = serializeResponse(
+            response,
+            route.serializer,
+            state.serializerMap,
+          );
+
+          writeResponse(res, serialized);
+        });
+      }
+    },
+
+    async listen(port: number): Promise<ServerHandle> {
+      const server: Server = createServer(app);
+
+      await new Promise<void>((resolve) => {
+        server.listen(port, "0.0.0.0", () => resolve());
+      });
+
+      return {
+        async close(): Promise<void> {
+          await new Promise<void>((resolve, reject) => {
+            server.close((err?: Error) => {
+              if (err) reject(err);
+              else resolve();
+            });
+          });
+        },
+        _server: server,
+      } as ServerHandle & { _server: Server };
+    },
+
+    normalizeRequest,
+    writeResponse,
+
+    getNativeServer(): unknown {
+      return app;
+    },
+  };
+
+  return adapter;
+}
+
+// Re-export for convenience
+export { serializeResponse, runValidators, validationErrorResponse };
+export { type ServerAdapter } from "@typokit/core";