inviton-backduck 1.0.0

package/dist/server.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Universal Server - Runtime-agnostic server configuration
+ * Define server once, run on Express or Bun
+ */
+import type { Router as ExpressRouter } from 'express';
+import type { BunRouter } from './bun';
+import type { WebRouter } from './router';
+/**
+ * Type representing one or more URL paths
+ * Used for static file serving where multiple paths can point to the same directory
+ */
+type PathOrPaths = string | string[];
+export interface StaticFileConfig {
+    /** URL path(s) to serve files from */
+    urlPath: PathOrPaths;
+    /** File system path to serve files from */
+    fsPath: string;
+    /** Enable compression (Bun only) */
+    compress?: boolean;
+    /** Cache-Control header value (e.g., 'public, max-age=31536000') */
+    cacheControl?: string;
+}
+/**
+ * Interface for routers that can build for both Express and Bun
+ * Used for SSR, frontend routers, and other non-API routes
+ */
+export interface BuildableRouter {
+    buildExpress: () => Promise<ExpressRouter>;
+    buildBun: (basePath?: string) => Promise<BunRouter>;
+}
+export interface UniversalServerOptions {
+    /** Server port */
+    port: number;
+    /** Server hostname */
+    hostname?: string;
+    /** API routes with base paths (use Bun native routes when possible) */
+    apiRouters: Record<string, WebRouter>;
+    /** Static file configurations */
+    staticFiles?: StaticFileConfig[];
+    /**
+     * Additional routers for fallback handling (SSR, frontend SPAs, etc.)
+     * These are processed in order in the fetch fallback handler.
+     * Use for routes that need regex matching or conditional handling.
+     */
+    routers?: BuildableRouter[];
+    /** CORS origins for development */
+    corsOrigins?: string[];
+    /** Middleware to apply to specific paths (Express only) */
+    pathMiddlewares?: Array<{
+        path: string;
+        middleware: any;
+    }>;
+    /** Called when server starts */
+    onStart?: (runtime: string) => void;
+    /** Called on server error */
+    onError?: (error: Error) => void;
+}
+export interface ServerInstance {
+    /** Stop the server */
+    stop: () => void | Promise<void>;
+    /** Runtime name */
+    runtime: string;
+}
+/**
+ * Universal Server - builds and runs server for current runtime
+ */
+export declare class UniversalServer {
+    private options;
+    private instance;
+    constructor(options: UniversalServerOptions);
+    /**
+     * Start the server for current runtime
+     * Automatically detects runtime (Bun or Node.js/Express) and starts appropriate server
+     * @returns Promise that resolves to ServerInstance with stop() method
+     */
+    start(): Promise<ServerInstance>;
+    /**
+     * Stop the server
+     * Gracefully shuts down the running server instance
+     */
+    stop(): Promise<void>;
+    /**
+     * Start Express server
+     */
+    private startExpress;
+    /**
+     * Start Bun server
+     */
+    private startBun;
+    /**
+     * Get current runtime name
+     * @returns 'bun' or 'node'
+     */
+    static get runtime(): string;
+    /**
+     * Check if running on Bun
+     * @returns True if running on Bun runtime, false if Node.js
+     */
+    static get isBun(): boolean;
+}
+/**
+ * Create a new UniversalServer instance
+ * Factory function for creating runtime-agnostic servers
+ * @param options - Server configuration options
+ * @returns New UniversalServer instance
+ * @example
+ * ```typescript
+ * const server = createServer({
+ *   port: 3000,
+ *   apiRouters: {
+ *     '/api': apiRouter,
+ *     '/admin': adminRouter
+ *   },
+ *   staticFiles: [{
+ *     urlPath: '/static',
+ *     fsPath: './public'
+ *   }],
+ *   onStart: (runtime) => console.log(`Server started on ${runtime}`)
+ * });
+ *
+ * await server.start();
+ * ```
+ */
+export declare const createServer: (options: UniversalServerOptions) => UniversalServer;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAW,MAAM,IAAI,aAAa,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C;;;GAGG;AACH,KAAK,WAAW,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAErC,MAAM,WAAW,gBAAgB;IAChC,sCAAsC;IACtC,OAAO,EAAE,WAAW,CAAC;IACrB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,YAAY,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,QAAQ,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,sBAAsB;IACtC,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACtC,iCAAiC;IACjC,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAC3D,gCAAgC;IAChC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC9B,sBAAsB;IACtB,IAAI,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,QAAQ,CAA+B;gBAEnC,OAAO,EAAE,sBAAsB;IAI3C;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;IAQtC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B;;OAEG;YACW,YAAY;IAoG1B;;OAEG;YACW,QAAQ;IA0BtB;;;OAGG;IACH,MAAM,KAAK,OAAO,IAAI,MAAM,CAE3B;IAED;;;OAGG;IACH,MAAM,KAAK,KAAK,IAAI,OAAO,CAE1B;CACD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,sBAAsB,KAAG,eAA+C,CAAC"}

package/dist/server.js

@@ -0,0 +1,181 @@
+/**
+ * Universal Server - Runtime-agnostic server configuration
+ * Define server once, run on Express or Bun
+ */
+import { IS_BUN, RUNTIME } from './runtime-detect';
+/**
+ * Universal Server - builds and runs server for current runtime
+ */
+export class UniversalServer {
+    options;
+    instance = null;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Start the server for current runtime
+     * Automatically detects runtime (Bun or Node.js/Express) and starts appropriate server
+     * @returns Promise that resolves to ServerInstance with stop() method
+     */
+    async start() {
+        if (IS_BUN) {
+            return this.startBun();
+        }
+        return this.startExpress();
+    }
+    /**
+     * Stop the server
+     * Gracefully shuts down the running server instance
+     */
+    async stop() {
+        if (this.instance) {
+            await this.instance.stop();
+            this.instance = null;
+        }
+    }
+    /**
+     * Start Express server
+     */
+    async startExpress() {
+        const [{ default: express }, { default: cookieParser }, { default: cors },] = await Promise.all([
+            import('express'),
+            import('cookie-parser'),
+            import('cors'),
+        ]);
+        const app = express();
+        app.disable('x-powered-by');
+        // CORS
+        if (this.options.corsOrigins && this.options.corsOrigins.length > 0) {
+            app.use(cors({
+                origin: this.options.corsOrigins,
+                credentials: true,
+                methods: [
+                    'GET',
+                    'POST',
+                    'PUT',
+                    'DELETE',
+                ],
+                allowedHeaders: [
+                    'Content-Type',
+                    'Authorization',
+                    'X-Requested-With',
+                    'Accept',
+                    'Cache-Control',
+                ],
+            }));
+        }
+        // Cookie parser
+        app.use(cookieParser());
+        // Path-specific middlewares
+        if (this.options.pathMiddlewares) {
+            for (const { path, middleware } of this.options.pathMiddlewares) {
+                app.use(path, middleware);
+            }
+        }
+        // Fallback routers (SSR, frontend SPAs, etc.) - order matters
+        for (const router of this.options.routers || []) {
+            app.use(await router.buildExpress());
+        }
+        // Static files (assets)
+        // Using *splat for Express 5+ compatibility with path-to-regexp v8
+        for (const staticConfig of this.options.staticFiles || []) {
+            const paths = Array.isArray(staticConfig.urlPath)
+                ? staticConfig.urlPath.flatMap(p => [
+                    p,
+                    `${p}/*splat`,
+                ])
+                : [
+                    staticConfig.urlPath,
+                    `${staticConfig.urlPath}/*splat`,
+                ];
+            const staticOptions = {};
+            // Set cache control if specified
+            if (staticConfig.cacheControl) {
+                staticOptions.setHeaders = (res) => {
+                    res.setHeader('Cache-Control', staticConfig.cacheControl);
+                };
+            }
+            app.use(paths, express.static(staticConfig.fsPath, staticOptions));
+        }
+        // API routes
+        for (const [basePath, router,] of Object.entries(this.options.apiRouters)) {
+            app.use(basePath, await router.buildExpress());
+        }
+        // Start listening
+        const server = app.listen(this.options.port);
+        this.instance = {
+            runtime: 'Express',
+            stop: () => new Promise((resolve, reject) => {
+                server.close(err => (err ? reject(err) : resolve()));
+            }),
+        };
+        if (this.options.onStart) {
+            this.options.onStart('Express');
+        }
+        return this.instance;
+    }
+    /**
+     * Start Bun server
+     */
+    async startBun() {
+        const { BunServer } = await import('./bun');
+        const bunServer = await BunServer.create({
+            port: this.options.port,
+            hostname: this.options.hostname,
+            apiRoutes: this.options.apiRouters,
+            staticFiles: this.options.staticFiles?.map(s => ({
+                urlPath: s.urlPath,
+                fsPath: s.fsPath,
+                compress: s.compress,
+            })),
+            fallbackRouters: this.options.routers,
+            corsOrigins: this.options.corsOrigins,
+            onStart: () => this.options.onStart?.('Bun'),
+            onError: this.options.onError,
+        });
+        this.instance = {
+            runtime: 'Bun',
+            stop: () => bunServer.stop(),
+        };
+        return this.instance;
+    }
+    /**
+     * Get current runtime name
+     * @returns 'bun' or 'node'
+     */
+    static get runtime() {
+        return RUNTIME;
+    }
+    /**
+     * Check if running on Bun
+     * @returns True if running on Bun runtime, false if Node.js
+     */
+    static get isBun() {
+        return IS_BUN;
+    }
+}
+/**
+ * Create a new UniversalServer instance
+ * Factory function for creating runtime-agnostic servers
+ * @param options - Server configuration options
+ * @returns New UniversalServer instance
+ * @example
+ * ```typescript
+ * const server = createServer({
+ *   port: 3000,
+ *   apiRouters: {
+ *     '/api': apiRouter,
+ *     '/admin': adminRouter
+ *   },
+ *   staticFiles: [{
+ *     urlPath: '/static',
+ *     fsPath: './public'
+ *   }],
+ *   onStart: (runtime) => console.log(`Server started on ${runtime}`)
+ * });
+ *
+ * await server.start();
+ * ```
+ */
+export const createServer = (options) => new UniversalServer(options);
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/utils.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Runtime utilities for request parsing and handling
+ */
+import type { WebRequest, WebResponse } from './data-contracts';
+/**
+ * Runtime utilities for working with WebRequest/WebResponse
+ */
+export declare class RuntimeUtils {
+    /**
+     * Parse a query parameter as a number
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Parsed number or null if invalid
+     */
+    static parseQueryNumber(req: WebRequest, key: string): number | null;
+    /**
+     * Parse a comma-separated query parameter as an array of numbers
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Array of numbers or null if invalid/empty
+     */
+    static parseQueryNumberArray(req: WebRequest, key: string): number[] | null;
+    /**
+     * Parse a comma-separated query parameter as an array of strings
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Array of strings or null if invalid/empty
+     */
+    static parseQueryStringArray(req: WebRequest, key: string): string[] | null;
+    /**
+     * Parse a query parameter as a boolean
+     * Accepts '1' or 'true' as truthy values
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns True if parameter is '1' or 'true', false otherwise
+     */
+    static parseQueryBoolean(req: WebRequest, key: string): boolean;
+    /**
+     * Parse a query parameter as a string
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Query parameter value as string
+     */
+    static parseQueryString(req: WebRequest, key: string): string;
+    /**
+     * Parse a query parameter as JSON
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Parsed JSON object or null if empty/invalid
+     */
+    static parseQueryJSON(req: WebRequest, key: string): any;
+    /**
+     * Parse a query parameter as an ISO date string
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns ISO date string or null if empty
+     */
+    static parseQueryDate(req: WebRequest, key: string): string | null;
+    /**
+     * Parse a query parameter as an array
+     * Handles both single values and array values
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Array of values (empty array if parameter is missing)
+     */
+    static parseQueryArray(req: WebRequest, key: string): any[];
+    /**
+     * Debug utility to dump request details to console
+     * @param req - HTTP request object
+     * @param res - Optional HTTP response object
+     * @param writeResponse - Whether to send a 200 OK response
+     * @param isError - Whether this is an error request dump
+     */
+    static dumpRequest(req: WebRequest, res?: WebResponse, writeResponse?: boolean, isError?: boolean): void;
+    /**
+     * Get the client IP address from request
+     * Checks x-forwarded-for header first (for proxy/load balancer support)
+     * @param req - HTTP request object
+     * @returns Client IP address
+     */
+    static getIpAddress(req: WebRequest): string;
+}
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEhE;;GAEG;AACH,qBAAa,YAAY;IACxB;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAapE;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAY3E;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAY3E;;;;;;OAMG;IACH,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAO/D;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAI7D;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,GAAG;IASxD;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKlE;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE;IAS3D;;;;;;OAMG;IACH,MAAM,CAAC,WAAW,CACjB,GAAG,EAAE,UAAU,EACf,GAAG,CAAC,EAAE,WAAW,EACjB,aAAa,CAAC,EAAE,OAAO,EACvB,OAAO,CAAC,EAAE,OAAO,GACf,IAAI;IAmBP;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM;CAG5C"}

package/dist/utils.js

@@ -0,0 +1,157 @@
+/**
+ * Runtime utilities for request parsing and handling
+ */
+/**
+ * Runtime utilities for working with WebRequest/WebResponse
+ */
+export class RuntimeUtils {
+    /**
+     * Parse a query parameter as a number
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Parsed number or null if invalid
+     */
+    static parseQueryNumber(req, key) {
+        try {
+            const retVal = Number(req.query[key]);
+            if (isNaN(retVal)) {
+                return null;
+            }
+            return retVal;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Parse a comma-separated query parameter as an array of numbers
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Array of numbers or null if invalid/empty
+     */
+    static parseQueryNumberArray(req, key) {
+        try {
+            if (!(req.query[key]?.length > 0)) {
+                return null;
+            }
+            return req.query[key].split(',').map(p => Number(p));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Parse a comma-separated query parameter as an array of strings
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Array of strings or null if invalid/empty
+     */
+    static parseQueryStringArray(req, key) {
+        try {
+            if (!(req.query[key]?.length > 0)) {
+                return null;
+            }
+            return req.query[key].split(',');
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Parse a query parameter as a boolean
+     * Accepts '1' or 'true' as truthy values
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns True if parameter is '1' or 'true', false otherwise
+     */
+    static parseQueryBoolean(req, key) {
+        return [
+            '1',
+            'true',
+        ].includes(req.query[key]);
+    }
+    /**
+     * Parse a query parameter as a string
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Query parameter value as string
+     */
+    static parseQueryString(req, key) {
+        return req.query[key];
+    }
+    /**
+     * Parse a query parameter as JSON
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Parsed JSON object or null if empty/invalid
+     */
+    static parseQueryJSON(req, key) {
+        const val = req.query[key];
+        if (val == null || val.length == 0) {
+            return null;
+        }
+        else {
+            return JSON.parse(val);
+        }
+    }
+    /**
+     * Parse a query parameter as an ISO date string
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns ISO date string or null if empty
+     */
+    static parseQueryDate(req, key) {
+        const val = req.query[key];
+        return val && val.length > 0 ? val : null;
+    }
+    /**
+     * Parse a query parameter as an array
+     * Handles both single values and array values
+     * @param req - HTTP request object
+     * @param key - Query parameter name
+     * @returns Array of values (empty array if parameter is missing)
+     */
+    static parseQueryArray(req, key) {
+        const val = req.query[key];
+        if (val == null || val.length == 0) {
+            return [];
+        }
+        else {
+            return Array.isArray(val) ? val : [val];
+        }
+    }
+    /**
+     * Debug utility to dump request details to console
+     * @param req - HTTP request object
+     * @param res - Optional HTTP response object
+     * @param writeResponse - Whether to send a 200 OK response
+     * @param isError - Whether this is an error request dump
+     */
+    static dumpRequest(req, res, writeResponse, isError) {
+        if (isError) {
+            console.log('\n *** ERROR Request dump *** \n');
+        }
+        else {
+            console.log('\n *** Request dump *** \n');
+        }
+        console.log(`URL: ${req.url}`);
+        console.log(`Method: ${req.method}`);
+        console.log(`Headers: ${JSON.stringify(req.headers)}`);
+        console.log(`Params: ${JSON.stringify(req.params)}`);
+        console.log(`Query: ${JSON.stringify(req.query)}`);
+        console.log(`Body: ${JSON.stringify(req.body)}`);
+        if (res && writeResponse) {
+            res.status(200).json({});
+        }
+    }
+    /**
+     * Get the client IP address from request
+     * Checks x-forwarded-for header first (for proxy/load balancer support)
+     * @param req - HTTP request object
+     * @returns Client IP address
+     */
+    static getIpAddress(req) {
+        return req.headers.get('x-forwarded-for') || req.ip || '';
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,MAAM,OAAO,YAAY;IACxB;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAe,EAAE,GAAW;QACnD,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YACtC,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;gBACnB,OAAO,IAAI,CAAC;YACb,CAAC;YAED,OAAO,MAAM,CAAC;QACf,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,GAAe,EAAE,GAAW;QACxD,IAAI,CAAC;YACJ,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;gBACnC,OAAO,IAAI,CAAC;YACb,CAAC;YAED,OAAQ,GAAG,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAClE,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,GAAe,EAAE,GAAW;QACxD,IAAI,CAAC;YACJ,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;gBACnC,OAAO,IAAI,CAAC;YACb,CAAC;YAED,OAAQ,GAAG,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,iBAAiB,CAAC,GAAe,EAAE,GAAW;QACpD,OAAO;YACN,GAAG;YACH,MAAM;SACN,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAe,EAAE,GAAW;QACnD,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,GAAe,EAAE,GAAW;QACjD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC;QACb,CAAC;aAAM,CAAC;YACP,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACF,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,GAAe,EAAE,GAAW;QACjD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3C,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,GAAe,EAAE,GAAW;QAClD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACpC,OAAO,EAAE,CAAC;QACX,CAAC;aAAM,CAAC;YACP,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACzC,CAAC;IACF,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,WAAW,CACjB,GAAe,EACf,GAAiB,EACjB,aAAuB,EACvB,OAAiB;QAEjB,IAAI,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACP,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACvD,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEjD,IAAI,GAAG,IAAI,aAAa,EAAE,CAAC;YAC1B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;IACF,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,GAAe;QAClC,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;IAC3D,CAAC;CACD"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "inviton-backduck",
+  "version": "1.0.0",
+  "description": "Runtime-agnostic utilities for building web servers with Express and Bun support",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "prepublishOnly": "npm run build",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "express",
+    "bun",
+    "runtime",
+    "router",
+    "server",
+    "api",
+    "documentation",
+    "openapi",
+    "swagger"
+  ],
+  "author": "Inviton",
+  "license": "MIT",
+  "peerDependencies": {
+    "express": "^5.x",
+    "bun-types": "*"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "bun-types": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.5",
+    "mime-types": "^2.1.35",
+    "openapi-types": "^12.1.3",
+    "ts-morph": "^26.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.5",
+    "@types/cookie-parser": "^1.4.7",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/mime-types": "^2.1.4",
+    "@types/node": "^22.10.5",
+    "bun-types": "^1.1.38",
+    "typescript": "^5.7.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}