inviton-backduck 1.0.0

package/dist/data-contracts.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Options for setting HTTP cookies
+ */
+export interface CookieOptions {
+    /** Maximum age of the cookie in milliseconds */
+    maxAge?: number;
+    /** Whether the cookie should be signed using a secret key */
+    signed?: boolean;
+    /** Expiration date of the cookie */
+    expires?: Date;
+    /** Whether the cookie is accessible only via HTTP (not JavaScript) */
+    httpOnly?: boolean;
+    /** URL path for which the cookie is valid */
+    path?: string;
+    /** Domain for which the cookie is valid */
+    domain?: string;
+    /** Whether the cookie should only be transmitted over HTTPS */
+    secure?: boolean;
+    /** Controls cross-site request behavior for the cookie */
+    sameSite?: boolean | 'lax' | 'strict' | 'none';
+}
+/**
+ * Runtime-agnostic HTTP headers interface
+ */
+export interface WebHeaders {
+    /**
+     * Get a header value by name
+     * @param name - Header name (case-insensitive)
+     * @returns Header value or null if not found
+     */
+    get: (name: string) => string | null | undefined;
+}
+/**
+ * Runtime-agnostic HTTP request interface
+ * Compatible with both Express Request and Bun Request
+ */
+export interface WebRequest {
+    /** HTTP method (GET, POST, PUT, PATCH, DELETE) */
+    method: string;
+    /** Full request URL including query string */
+    url: string;
+    /** Request path without query string */
+    path: string;
+    /** Parsed query string parameters */
+    query: Record<string, any>;
+    /** URL path parameters (e.g., /users/:id) */
+    params: Record<string, string>;
+    /** Parsed request body (requires body parser middleware) */
+    body: any;
+    /** HTTP request headers */
+    headers: WebHeaders;
+    /** Client IP address */
+    ip: string;
+    /** Parsed cookies (requires cookie-parser middleware in Express) */
+    cookies?: Record<string, string>;
+    /** Signed cookies (requires cookie-parser middleware in Express) */
+    signedCookies?: Record<string, string>;
+}
+/**
+ * Runtime-agnostic HTTP response interface
+ * Compatible with both Express Response and Bun Response
+ */
+export interface WebResponse {
+    /** Current HTTP status code */
+    statusCode: number;
+    /**
+     * Set HTTP status code
+     * @param code - HTTP status code (200, 404, 500, etc.)
+     * @returns The response object for chaining
+     */
+    status: (code: number) => WebResponse;
+    /**
+     * Send JSON response
+     * @param data - Data to serialize as JSON
+     */
+    json: (data: any) => void;
+    /**
+     * Send text response
+     * @param data - Text content to send
+     */
+    send: (data: string) => void;
+    /**
+     * Send binary data (Buffer or ArrayBuffer)
+     * @param data - Binary data to send
+     */
+    sendBuffer: (data: Buffer | ArrayBuffer | Uint8Array) => void;
+    /**
+     * Set response header
+     * @param name - Header name
+     * @param value - Header value
+     * @returns The response object for chaining
+     */
+    setHeader: (name: string, value: string) => WebResponse;
+    /**
+     * Redirect to another URL
+     * @param url - Target URL for redirection
+     */
+    redirect: (url: string) => void;
+    /** Whether response headers have been sent */
+    headersSent: boolean;
+    /**
+     * Set a cookie
+     * @param name - Cookie name
+     * @param value - Cookie value
+     * @param options - Cookie options (maxAge, httpOnly, etc.)
+     * @returns The response object for chaining
+     */
+    cookie?: (name: string, value: string, options?: CookieOptions) => WebResponse;
+    /**
+     * Clear a cookie
+     * @param name - Cookie name to clear
+     * @param options - Cookie options (must match original options)
+     * @returns The response object for chaining
+     */
+    clearCookie?: (name: string, options?: CookieOptions) => WebResponse;
+}
+/**
+ * Route handler function that processes HTTP requests
+ * @param req - HTTP request object
+ * @param res - HTTP response object
+ * @param next - Optional function to pass control to next handler
+ */
+export type RouteHandler = (req: WebRequest, res: WebResponse, next?: () => void) => void | Promise<void>;
+/**
+ * Middleware function that processes requests before route handlers
+ * Middleware can modify request/response or pass control to next handler
+ * @param req - HTTP request object
+ * @param res - HTTP response object
+ * @param next - Function to pass control to next middleware/handler
+ */
+export type MiddlewareDefinition = (req: WebRequest, res: WebResponse, next: () => void | Promise<void>) => void | Promise<void>;
+//# sourceMappingURL=data-contracts.d.ts.map

package/dist/data-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-contracts.d.ts","sourceRoot":"","sources":["../src/data-contracts.ts"],"names":[],"mappings":"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"}

package/dist/data-contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data-contracts.js.map

package/dist/data-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-contracts.js","sourceRoot":"","sources":["../src/data-contracts.ts"],"names":[],"mappings":""}

package/dist/decorators.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Controller decorators for route configuration
+ */
+import type { MiddlewareDefinition, WebRequest } from './data-contracts';
+/**
+ * Get or create middlewares array on controller
+ * Used internally by the Middleware decorator
+ * @param target - Controller class or prototype
+ * @returns Array of middleware functions
+ */
+export declare const ControllerGetMiddlewares: (target: any) => MiddlewareDefinition[];
+/**
+ * Decorator to set the route path for a controller
+ * @param route - Base route path (e.g., '/users', '/products')
+ * @returns Decorator function
+ * @example
+ * ```typescript
+ * @Route('/products')
+ * class ProductController extends ControllerBase {
+ *   // Routes will be registered under /products
+ * }
+ * ```
+ */
+export declare const Route: (route: string) => (target: any) => void;
+/**
+ * Decorator to set the request body size limit for a controller
+ * Only applies to Express runtime (Bun handles large payloads natively)
+ * @param size - Size limit (e.g., '10mb', '50mb')
+ * @returns Decorator function
+ * @example
+ * ```typescript
+ * @Route('/files')
+ * @RequestSize('50mb')
+ * class FileUploadController extends ControllerBase {
+ *   // Allows up to 50MB file uploads
+ * }
+ * ```
+ */
+export declare const RequestSize: (size: string) => (target: any) => void;
+/**
+ * Decorator to add middlewares to a controller
+ * Middlewares run before all route handlers in the controller
+ * @param middlewares - Array of middleware functions
+ * @returns Decorator function
+ * @example
+ * ```typescript
+ * @Route('/admin')
+ * @Middleware([authMiddleware, loggingMiddleware])
+ * class AdminController extends ControllerBase {
+ *   // All routes require auth and logging
+ * }
+ * ```
+ */
+export declare const Middleware: (middlewares: MiddlewareDefinition[]) => (target: any) => void;
+/**
+ * Decorator to set a custom request args parser for a controller method
+ * By default, GET methods use query string parsing and POST/PUT/PATCH use body parsing
+ * Use this decorator to customize how request arguments are extracted
+ * @param parser - Function that extracts arguments from the request
+ * @returns Decorator function
+ * @example
+ * ```typescript
+ * class UserController extends ControllerBase {
+ *   @ParseRequestArgs((req) => ({
+ *     id: parseInt(req.params.id),
+ *     includeDeleted: req.query.includeDeleted === 'true'
+ *   }))
+ *   async get(args: { id: number, includeDeleted: boolean }) {
+ *     // Custom parsed args
+ *   }
+ * }
+ * ```
+ */
+export declare const ParseRequestArgs: <T>(parser: (req: WebRequest) => T) => (target: any, methodName?: string) => void;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,UAAU,EAAe,MAAM,kBAAkB,CAAC;AAEtF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,QAAQ,GAAG,KAAG,oBAAoB,EAgB1E,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,MAAM,QAAQ,GAAG,SAQnD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,MAAM,QAAQ,GAAG,SAQxD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,GAAI,aAAa,oBAAoB,EAAE,MAAM,QAAQ,GAAG,SAK9E,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAAE,QAAQ,CAAC,GAAG,EAAE,UAAU,KAAK,CAAC,MAAM,QAAQ,GAAG,EAAE,aAAa,MAAM,SAQvG,CAAC"}

package/dist/decorators.js

@@ -0,0 +1,101 @@
+/**
+ * Controller decorators for route configuration
+ */
+/**
+ * Get or create middlewares array on controller
+ * Used internally by the Middleware decorator
+ * @param target - Controller class or prototype
+ * @returns Array of middleware functions
+ */
+export const ControllerGetMiddlewares = (target) => {
+    let middlewares = target.$middlewares;
+    if (middlewares == null) {
+        const arr = [];
+        Object.defineProperty(target, '$middlewares', {
+            get: () => arr,
+        });
+        middlewares = target.$middlewares;
+    }
+    return middlewares;
+};
+/**
+ * Decorator to set the route path for a controller
+ * @param route - Base route path (e.g., '/users', '/products')
+ * @returns Decorator function
+ * @example
+ * ```typescript
+ * @Route('/products')
+ * class ProductController extends ControllerBase {
+ *   // Routes will be registered under /products
+ * }
+ * ```
+ */
+export const Route = (route) => (target) => {
+    Object.defineProperty(target, '$route', {
+        get: () => route,
+    });
+};
+/**
+ * Decorator to set the request body size limit for a controller
+ * Only applies to Express runtime (Bun handles large payloads natively)
+ * @param size - Size limit (e.g., '10mb', '50mb')
+ * @returns Decorator function
+ * @example
+ * ```typescript
+ * @Route('/files')
+ * @RequestSize('50mb')
+ * class FileUploadController extends ControllerBase {
+ *   // Allows up to 50MB file uploads
+ * }
+ * ```
+ */
+export const RequestSize = (size) => (target) => {
+    Object.defineProperty(target, '$requestSize', {
+        get: () => size,
+    });
+};
+/**
+ * Decorator to add middlewares to a controller
+ * Middlewares run before all route handlers in the controller
+ * @param middlewares - Array of middleware functions
+ * @returns Decorator function
+ * @example
+ * ```typescript
+ * @Route('/admin')
+ * @Middleware([authMiddleware, loggingMiddleware])
+ * class AdminController extends ControllerBase {
+ *   // All routes require auth and logging
+ * }
+ * ```
+ */
+export const Middleware = (middlewares) => (target) => {
+    const arr = ControllerGetMiddlewares(target);
+    for (const mw of middlewares) {
+        arr.push(mw);
+    }
+};
+/**
+ * Decorator to set a custom request args parser for a controller method
+ * By default, GET methods use query string parsing and POST/PUT/PATCH use body parsing
+ * Use this decorator to customize how request arguments are extracted
+ * @param parser - Function that extracts arguments from the request
+ * @returns Decorator function
+ * @example
+ * ```typescript
+ * class UserController extends ControllerBase {
+ *   @ParseRequestArgs((req) => ({
+ *     id: parseInt(req.params.id),
+ *     includeDeleted: req.query.includeDeleted === 'true'
+ *   }))
+ *   async get(args: { id: number, includeDeleted: boolean }) {
+ *     // Custom parsed args
+ *   }
+ * }
+ * ```
+ */
+export const ParseRequestArgs = (parser) => (target, methodName) => {
+    Object.defineProperty(target, methodName && methodName.length > 0 ? `$parse-${methodName}` : '$parse-', {
+        get: () => (req, _) => parser(req),
+    });
+};
+//# sourceMappingURL=decorators.js.map

package/dist/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,MAAW,EAA0B,EAAE;IAC/E,IAAI,WAAW,GAAG,MAAM,CAAC,YAAY,CAAC;IACtC,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;QACzB,MAAM,GAAG,GAA2B,EAAE,CAAC;QACvC,MAAM,CAAC,cAAc,CACpB,MAAM,EACN,cAAc,EACd;YACC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG;SACd,CACD,CAAC;QAEF,WAAW,GAAG,MAAM,CAAC,YAAY,CAAC;IACnC,CAAC;IAED,OAAO,WAAW,CAAC;AACpB,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,MAAW,EAAE,EAAE;IACvD,MAAM,CAAC,cAAc,CACpB,MAAM,EACN,QAAQ,EACR;QACC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK;KAChB,CACD,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,MAAW,EAAE,EAAE;IAC5D,MAAM,CAAC,cAAc,CACpB,MAAM,EACN,cAAc,EACd;QACC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI;KACf,CACD,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,WAAmC,EAAE,EAAE,CAAC,CAAC,MAAW,EAAE,EAAE;IAClF,MAAM,GAAG,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAC7C,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACd,CAAC;AACF,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAI,MAA8B,EAAE,EAAE,CAAC,CAAC,MAAW,EAAE,UAAmB,EAAE,EAAE;IAC3G,MAAM,CAAC,cAAc,CACpB,MAAM,EACN,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,EACxE;QACC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,GAAe,EAAE,CAAc,EAAK,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC;KAC9D,CACD,CAAC;AACH,CAAC,CAAC"}

package/dist/express/expressFrontendRouter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Express Frontend Router - Express-specific SPA routing
+ */
+import type { Router as ExpressRouter } from 'express';
+type StringOrRegex = string | RegExp;
+export interface ExpressFrontendConfig {
+    /** Route patterns to match */
+    routes: StringOrRegex[];
+    /** Pre-loaded HTML content */
+    indexHtml: string | null;
+}
+/**
+ * Build Express frontend router for SPA routing
+ */
+export declare const buildExpressFrontendRouter: (config: ExpressFrontendConfig) => Promise<ExpressRouter>;
+export {};
+//# sourceMappingURL=expressFrontendRouter.d.ts.map

package/dist/express/expressFrontendRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressFrontendRouter.d.ts","sourceRoot":"","sources":["../../src/express/expressFrontendRouter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAA0D,MAAM,IAAI,aAAa,EAAgB,MAAM,SAAS,CAAC;AAE7H,KAAK,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAErC,MAAM,WAAW,qBAAqB;IACrC,8BAA8B;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAU,QAAQ,qBAAqB,KAAG,OAAO,CAAC,aAAa,CA+BrG,CAAC"}

package/dist/express/expressFrontendRouter.js

@@ -0,0 +1,33 @@
+/**
+ * Express Frontend Router - Express-specific SPA routing
+ */
+/**
+ * Build Express frontend router for SPA routing
+ */
+export const buildExpressFrontendRouter = async (config) => {
+    const { default: express } = await import('express');
+    const router = express.Router();
+    const { indexHtml, routes } = config;
+    const handler = (_req, res, _next) => {
+        res.setHeader('Content-Type', 'text/html');
+        res.send(indexHtml);
+    };
+    // Convert routes to Express-compatible format
+    // Using *splat for Express 5+ compatibility with path-to-regexp v8
+    const expressRoutes = [];
+    for (const route of routes) {
+        if (typeof route === 'string') {
+            expressRoutes.push(route);
+            // Add wildcard version for SPA routing
+            if (!route.endsWith('/*splat')) {
+                expressRoutes.push(`${route}/*splat`);
+            }
+        }
+        else {
+            expressRoutes.push(route);
+        }
+    }
+    router.use(expressRoutes, handler);
+    return router;
+};
+//# sourceMappingURL=expressFrontendRouter.js.map

package/dist/express/expressFrontendRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressFrontendRouter.js","sourceRoot":"","sources":["../../src/express/expressFrontendRouter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAaH;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,EAAE,MAA6B,EAA0B,EAAE;IACzG,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IACrD,MAAM,MAAM,GAAkB,OAAO,CAAC,MAAM,EAAE,CAAC;IAC/C,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAErC,MAAM,OAAO,GAAG,CACf,IAAoB,EACpB,GAAoB,EACpB,KAAmB,EAClB,EAAE;QACH,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;QAC3C,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACrB,CAAC,CAAC;IAEF,8CAA8C;IAC9C,mEAAmE;IACnE,MAAM,aAAa,GAAwB,EAAE,CAAC;IAC9C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/B,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,uCAAuC;YACvC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAChC,aAAa,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC;YACvC,CAAC;QACF,CAAC;aAAM,CAAC;YACP,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;IACF,CAAC;IAED,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC;AACf,CAAC,CAAC"}

package/dist/express/expressRouter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Express Router - Express-specific routing implementation
+ */
+import type { Router as ExpressRouter } from 'express';
+import type { MiddlewareDefinition, RouteHandler } from '../data-contracts';
+import type { HttpMethod } from '../router';
+interface RouteDefinition {
+    method: HttpMethod;
+    path: string;
+    /** Optional regex for pattern matching */
+    regex?: RegExp;
+    handlers: (RouteHandler | MiddlewareDefinition)[];
+    /** Optional request size limit for body parsing */
+    requestSize?: string;
+}
+interface SubRouterMount {
+    path: string;
+    buildExpress: () => Promise<ExpressRouter>;
+}
+/**
+ * Build Express router from route definitions
+ */
+export declare const buildExpressRouter: (routes: RouteDefinition[], subRouters: SubRouterMount[]) => Promise<ExpressRouter>;
+export {};
+//# sourceMappingURL=expressRouter.d.ts.map

package/dist/express/expressRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressRouter.d.ts","sourceRoot":"","sources":["../../src/express/expressRouter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAiD,MAAM,IAAI,aAAa,EAAgB,MAAM,SAAS,CAAC;AACpH,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAA2B,MAAM,mBAAmB,CAAC;AACrG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAM5C,UAAU,eAAe;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,CAAC,YAAY,GAAG,oBAAoB,CAAC,EAAE,CAAC;IAClD,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,cAAc;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3C;AA0ID;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAU,QAAQ,eAAe,EAAE,EAAE,YAAY,cAAc,EAAE,KAAG,OAAO,CAAC,aAAa,CAoCvH,CAAC"}

package/dist/express/expressRouter.js

@@ -0,0 +1,150 @@
+/**
+ * Express Router - Express-specific routing implementation
+ */
+/** Symbol keys for storing universal request/response on Express objects */
+const UNI_REQ_KEY = Symbol('uniReq');
+const UNI_RES_KEY = Symbol('uniRes');
+/**
+ * Convert Express request to WebRequest
+ */
+const expressToUniversalReq = (req) => ({
+    method: req.method,
+    url: req.url,
+    path: req.path,
+    query: req.query,
+    params: req.params,
+    body: req.body,
+    headers: { get: (name) => req.get(name) },
+    ip: req.ip || req.socket?.remoteAddress || '',
+    cookies: req.cookies,
+    signedCookies: req.signedCookies,
+});
+/**
+ * Convert Express response to WebResponse
+ */
+const expressToUniversalRes = (res) => {
+    const uniRes = {
+        statusCode: 200,
+        status(code) {
+            this.statusCode = code;
+            res.status(code);
+            return this;
+        },
+        json: (data) => {
+            res.json(data);
+        },
+        send: (data) => {
+            res.send(data);
+        },
+        sendBuffer: (data) => {
+            res.send(data);
+        },
+        setHeader: (name, value) => {
+            res.setHeader(name, value);
+            return uniRes;
+        },
+        redirect: (url) => {
+            res.redirect(url);
+        },
+        get headersSent() {
+            return res.headersSent;
+        },
+        cookie: (name, value, options) => {
+            res.cookie(name, value, options);
+            return uniRes;
+        },
+        clearCookie: (name, options) => {
+            res.clearCookie(name, options);
+            return uniRes;
+        },
+    };
+    return uniRes;
+};
+/**
+ * Get or create universal request/response from Express objects.
+ * Conversion happens only once per request lifecycle.
+ */
+const getOrCreateUniversal = (req, res) => {
+    if (!req[UNI_REQ_KEY]) {
+        req[UNI_REQ_KEY] = expressToUniversalReq(req);
+        res[UNI_RES_KEY] = expressToUniversalRes(res);
+    }
+    return {
+        uniReq: req[UNI_REQ_KEY],
+        uniRes: res[UNI_RES_KEY],
+    };
+};
+/**
+ * Convert universal handler to Express handler
+ */
+const toExpressHandler = (handler) => async (req, res, next) => {
+    const { uniReq, uniRes } = getOrCreateUniversal(req, res);
+    try {
+        await handler(uniReq, uniRes, next);
+    }
+    catch (err) {
+        next(err);
+    }
+};
+/**
+ * Convert wildcard paths to Express 5+ compatible format
+ * Express 5 with path-to-regexp v8 requires named parameters for wildcards
+ * Converts /* to /*splat
+ */
+const toExpressPath = (path) => path.replace(/\/\*$/g, '/*splat').replace(/\/\*\//g, '/*splat/');
+/**
+ * Check if method requires body parsing
+ */
+const isBodyMethod = (method) => method === 'post' || method === 'put' || method === 'patch';
+/**
+ * Get body parser middlewares for a route
+ */
+const getBodyParserMiddlewares = (express, requestSize) => {
+    if (requestSize) {
+        return [
+            express.urlencoded({ extended: true, limit: requestSize }),
+            express.json({ limit: requestSize }),
+        ];
+    }
+    return [
+        express.urlencoded({ extended: true }),
+        express.json(),
+    ];
+};
+/**
+ * Build Express router from route definitions
+ */
+export const buildExpressRouter = async (routes, subRouters) => {
+    const { default: express } = await import('express');
+    const router = express.Router();
+    // Mount sub-routers
+    for (const { path, buildExpress } of subRouters) {
+        router.use(path, await buildExpress());
+    }
+    // Register routes
+    for (const route of routes) {
+        const method = route.method.toLowerCase();
+        const expressHandlers = route.handlers.map(h => toExpressHandler(h));
+        // Add body parser middlewares for POST/PUT/PATCH methods
+        const allHandlers = isBodyMethod(method)
+            ? [
+                ...getBodyParserMiddlewares(express, route.requestSize),
+                ...expressHandlers,
+            ]
+            : expressHandlers;
+        // For regex routes (path starts with __regex__), use the regex pattern
+        // For regular routes, convert to Express 5+ compatible path
+        if (route.path.startsWith('__regex__')) {
+            if (route.regex) {
+                router[method](route.regex, ...allHandlers);
+            }
+            // Skip if regex is missing (shouldn't happen, but defensive)
+        }
+        else {
+            const expressPath = toExpressPath(route.path);
+            router[method](expressPath, ...allHandlers);
+        }
+    }
+    return router;
+};
+//# sourceMappingURL=expressRouter.js.map

package/dist/express/expressRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressRouter.js","sourceRoot":"","sources":["../../src/express/expressRouter.ts"],"names":[],"mappings":"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"}

package/dist/express/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Express runtime utilities - barrel export
+ */
+export { buildExpressFrontendRouter, type ExpressFrontendConfig } from './expressFrontendRouter';
+export { buildExpressRouter } from './expressRouter';
+//# sourceMappingURL=index.d.ts.map

package/dist/express/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/express/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,0BAA0B,EAAE,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/express/index.js

@@ -0,0 +1,6 @@
+/**
+ * Express runtime utilities - barrel export
+ */
+export { buildExpressFrontendRouter } from './expressFrontendRouter';
+export { buildExpressRouter } from './expressRouter';
+//# sourceMappingURL=index.js.map

package/dist/express/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/express/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,0BAA0B,EAA8B,MAAM,yBAAyB,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @server-runtime - Runtime-agnostic utilities for building web servers
+ *
+ * This package provides a unified API for building web servers that can run on
+ * both Node.js (with Express) and Bun natively. Write your server code once,
+ * and it will automatically adapt to the runtime environment.
+ *
+ * Key Features:
+ * - Universal Router: Define routes once, run anywhere
+ * - Controller-based routing with automatic REST mapping
+ * - Runtime detection and automatic adaptation
+ * - Type-safe request/response handling
+ * - Middleware support with chaining
+ * - Static file serving with compression
+ *
+ * @example
+ * ```typescript
+ * import { createRouter, createServer, Route, ControllerBase } from '@server-runtime';
+ *
+ * // Define a controller
+ * @Route('/products')
+ * class ProductController extends ControllerBase {
+ *   async getAll() { return products; }
+ *   async get(args: { id: number }) { return product; }
+ *   async post(args: CreateProductArgs) { return created; }
+ * }
+ *
+ * // Create router and register controllers
+ * const router = createRouter();
+ * router.registerController(ProductController);
+ *
+ * // Create and start server
+ * const server = createServer({
+ *   port: 3000,
+ *   apiRouters: { '/api': router }
+ * });
+ * await server.start();
+ * ```
+ */
+export * from './apidoc';
+export type { CookieOptions, MiddlewareDefinition as Middleware, RouteHandler, WebHeaders as UniversalHeaders, WebRequest, WebResponse, } from './data-contracts';
+export { ControllerGetMiddlewares, Middleware as MiddlewareDecorator, ParseRequestArgs, RequestSize, Route, } from './decorators';
+export { ControllerBase, createRouter, type HttpMethod, type IController, WebRouter as UniversalRouter, WebRouter, } from './router';
+export { IS_BUN, RUNTIME } from './runtime-detect';
+export { type BuildableRouter, createServer, type ServerInstance, type StaticFileConfig, UniversalServer, type UniversalServerOptions, } from './server';
+export { RuntimeUtils } from './utils';
+//# 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,cAAc,UAAU,CAAC;AAGzB,YAAY,EACX,aAAa,EACb,oBAAoB,IAAI,UAAU,EAClC,YAAY,EACZ,UAAU,IAAI,gBAAgB,EAC9B,UAAU,EACV,WAAW,GACX,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACN,wBAAwB,EACxB,UAAU,IAAI,mBAAmB,EACjC,gBAAgB,EAChB,WAAW,EACX,KAAK,GACL,MAAM,cAAc,CAAC;AAGtB,OAAO,EACN,cAAc,EACd,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,SAAS,IAAI,eAAe,EAC5B,SAAS,GACT,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EACN,KAAK,eAAe,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,eAAe,EACf,KAAK,sBAAsB,GAC3B,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}