@flight-framework/core 0.0.1

package/dist/server/index.d.ts

@@ -0,0 +1,135 @@
+import { Router } from '../router/index.js';
+import { Middleware, MiddlewareChain } from '../middleware/index.js';
+import { FlightUserConfig, FlightConfig } from '../config/index.js';
+import { FlightAdapter } from '../adapters/index.js';
+import '../render/index.js';
+
+/**
+ * Flight Server - Main server factory
+ *
+ * Creates a Flight server instance that handles routing, middleware, and rendering.
+ * This is the primary entry point for Flight applications.
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@flight/core';
+ *
+ * const server = createServer();
+ *
+ * server.get('/api/health', () => Response.json({ status: 'ok' }));
+ *
+ * // Just works! Auto-detects Node.js, Bun, or Deno
+ * server.listen(3000);
+ * ```
+ */
+
+/** Route handler function signature */
+type RouteHandler = (context: RouteHandlerContext) => Promise<Response> | Response;
+/** Context passed to route handlers */
+interface RouteHandlerContext {
+    /** The incoming request */
+    request: Request;
+    /** URL parameters from routing */
+    params: Record<string, string | string[]>;
+    /** Query parameters */
+    query: URLSearchParams;
+    /** Parsed URL */
+    url: URL;
+    /** Local data from middleware */
+    locals: Record<string, unknown>;
+    /** Database instance (if configured) */
+    db?: unknown;
+    /** Auth instance (if configured) */
+    auth?: unknown;
+    /** Email instance (if configured) */
+    email?: unknown;
+}
+/** Server options */
+interface ServerOptions {
+    /** Server configuration */
+    config?: FlightUserConfig;
+    /** Deployment adapter */
+    adapter?: FlightAdapter;
+    /** Database instance */
+    db?: unknown;
+    /** Auth instance */
+    auth?: unknown;
+    /** Email instance */
+    email?: unknown;
+}
+/** Route definition for the server */
+interface ServerRoute {
+    /** HTTP method (GET, POST, etc.) */
+    method: string | string[];
+    /** Route path pattern */
+    path: string;
+    /** Route handler */
+    handler: RouteHandler;
+}
+/** Listen options */
+interface ListenOptions {
+    /** Port to listen on (default: 3000) */
+    port?: number;
+    /** Hostname to bind to (default: 'localhost') */
+    hostname?: string;
+    /** Callback when server starts */
+    onListen?: (info: {
+        port: number;
+        hostname: string;
+    }) => void;
+}
+/** Flight Server instance */
+interface FlightServer {
+    /** Add a route */
+    route(method: string | string[], path: string, handler: RouteHandler): FlightServer;
+    /** Convenience methods for common HTTP methods */
+    get(path: string, handler: RouteHandler): FlightServer;
+    post(path: string, handler: RouteHandler): FlightServer;
+    put(path: string, handler: RouteHandler): FlightServer;
+    delete(path: string, handler: RouteHandler): FlightServer;
+    patch(path: string, handler: RouteHandler): FlightServer;
+    /** Add middleware */
+    use(middleware: Middleware): FlightServer;
+    use(path: string, middleware: Middleware): FlightServer;
+    /** Handle incoming request (Web standard Request/Response) */
+    handle(request: Request): Promise<Response>;
+    /**
+     * Start the HTTP server
+     * Auto-detects runtime: Node.js, Bun, or Deno
+     */
+    listen(port?: number | ListenOptions): Promise<void>;
+    /** Fetch handler for Bun.serve() and Deno.serve() */
+    fetch(request: Request): Promise<Response>;
+    /** Get the resolved configuration */
+    readonly config: FlightConfig;
+    /** Get the router instance */
+    readonly router: Router<RouteHandler>;
+    /** Get the middleware chain */
+    readonly middleware: MiddlewareChain;
+}
+type Runtime = 'node' | 'bun' | 'deno' | 'unknown';
+/**
+ * Create a new Flight server instance
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@flight/core';
+ *
+ * const server = createServer();
+ *
+ * server.get('/api/users', async ({ db }) => {
+ *   const users = await db.query('SELECT * FROM users');
+ *   return Response.json(users);
+ * });
+ *
+ * // Works on Node.js, Bun, and Deno!
+ * server.listen(3000);
+ * ```
+ */
+declare function createServer(options?: ServerOptions): FlightServer;
+/** Type guard to check if an object is a FlightServer */
+declare function isFlightServer(obj: unknown): obj is FlightServer;
+/** Get current runtime */
+declare function getRuntime(): Runtime;
+
+export { type FlightServer, type ListenOptions, type RouteHandler, type RouteHandlerContext, type ServerOptions, type ServerRoute, createServer, getRuntime, isFlightServer };

package/dist/server/index.js

@@ -0,0 +1,6 @@
+export { createServer, getRuntime, isFlightServer } from '../chunk-Y22KEW2F.js';
+import '../chunk-GCQZ4FHI.js';
+import '../chunk-KWFX6WHG.js';
+import '../chunk-WAGCTWGY.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/streaming/index.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @flight/core - Streaming SSR
+ *
+ * Full streaming server-side rendering implementation following React 18+/19 patterns.
+ * Supports both Node.js (renderToPipeableStream) and Edge (renderToReadableStream) environments.
+ *
+ * Best Practices 2025/2026:
+ * - Progressive HTML streaming with Suspense boundaries
+ * - Shell-first rendering for fast TTFB
+ * - Nested Suspense for granular loading states
+ * - Error boundaries for graceful degradation
+ * - Web Streams API for Edge runtime compatibility
+ */
+/**
+ * Streaming render options following React's conventions
+ */
+interface StreamingRenderOptions {
+    /** Bootstrap scripts to load on client */
+    bootstrapScripts?: string[];
+    /** Bootstrap ES modules */
+    bootstrapModules?: string[];
+    /** Inline script content */
+    bootstrapScriptContent?: string;
+    /** Prefix for React IDs (useId) */
+    identifierPrefix?: string;
+    /** Nonce for CSP */
+    nonce?: string;
+    /** Callback when shell is ready (main content before Suspense) */
+    onShellReady?: () => void;
+    /** Callback when shell errors */
+    onShellError?: (error: Error) => void;
+    /** Callback when all content is ready */
+    onAllReady?: () => void;
+    /** Callback for any error */
+    onError?: (error: Error) => void;
+    /** Timeout before aborting stream */
+    timeoutMs?: number;
+    /** Progressive hydration enabled */
+    progressiveHydration?: boolean;
+}
+/**
+ * Streaming render result
+ */
+interface StreamingRenderResult {
+    /** The readable stream to pipe to response */
+    stream: ReadableStream<Uint8Array>;
+    /** Abort the stream */
+    abort: () => void;
+    /** Promise that resolves when shell is ready */
+    shellReady: Promise<void>;
+    /** Promise that resolves when all content is ready */
+    allReady: Promise<void>;
+}
+/**
+ * Suspense boundary configuration
+ */
+interface SuspenseBoundaryConfig {
+    /** Unique ID for this boundary */
+    id: string;
+    /** Fallback HTML to show while loading */
+    fallback: string;
+    /** Content resolver promise */
+    contentPromise: Promise<string>;
+}
+/**
+ * Create a streaming SSR response using Web Streams API.
+ * Compatible with Edge Runtime (Cloudflare, Vercel Edge, Deno).
+ *
+ * @example
+ * ```typescript
+ * const result = await createStreamingSSR({
+ *   shell: '<html><body><div id="root">',
+ *   shellEnd: '</div></body></html>',
+ *   suspenseBoundaries: [
+ *     {
+ *       id: 'posts',
+ *       fallback: '<div>Loading posts...</div>',
+ *       contentPromise: fetchAndRenderPosts(),
+ *     }
+ *   ],
+ *   bootstrapScripts: ['/client.js'],
+ * });
+ *
+ * return new Response(result.stream, {
+ *   headers: { 'Content-Type': 'text/html' },
+ * });
+ * ```
+ */
+declare function createStreamingSSR(config: {
+    /** Initial HTML shell (before suspense content) */
+    shell: string;
+    /** Closing HTML shell */
+    shellEnd: string;
+    /** Suspense boundaries with async content */
+    suspenseBoundaries?: SuspenseBoundaryConfig[];
+    /** Streaming options */
+    options?: StreamingRenderOptions;
+}): Promise<StreamingRenderResult>;
+/**
+ * Create a streaming HTML Response object
+ */
+declare function createStreamingResponse(stream: ReadableStream<Uint8Array>, options?: {
+    status?: number;
+    headers?: Record<string, string>;
+}): Response;
+/**
+ * Higher-level API: Render page with Suspense boundaries
+ *
+ * @example
+ * ```typescript
+ * return renderWithStreaming({
+ *   layout: ({ children }) => `
+ *     <html>
+ *       <head><title>My App</title></head>
+ *       <body><div id="root">${children}</div></body>
+ *     </html>
+ *   `,
+ *   page: async () => '<h1>Welcome</h1>',
+ *   suspense: {
+ *     posts: {
+ *       fallback: '<div class="skeleton">Loading...</div>',
+ *       content: fetchPosts().then(renderPosts),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function renderWithStreaming(config: {
+    /** Layout wrapper */
+    layout: (props: {
+        children: string;
+    }) => string;
+    /** Main page content (sync part) */
+    page: () => string | Promise<string>;
+    /** Suspense boundaries keyed by ID */
+    suspense?: Record<string, {
+        fallback: string;
+        content: Promise<string>;
+    }>;
+    /** Bootstrap scripts */
+    bootstrapScripts?: string[];
+    /** Timeout in ms */
+    timeoutMs?: number;
+}): Promise<Response>;
+/**
+ * Create a lazy component that streams its content
+ */
+declare function createLazyContent<T>(fetcher: () => Promise<T>, renderer: (data: T) => string, fallback: string): {
+    fallback: string;
+    content: Promise<string>;
+};
+/**
+ * Parallel streaming: resolve multiple boundaries simultaneously
+ */
+declare function streamParallel(boundaries: Array<{
+    id: string;
+    fallback: string;
+    content: () => Promise<string>;
+}>): Promise<SuspenseBoundaryConfig[]>;
+/**
+ * Sequential streaming: resolve boundaries in order
+ */
+declare function streamSequential(boundaries: Array<{
+    id: string;
+    fallback: string;
+    content: () => Promise<string>;
+}>): Promise<SuspenseBoundaryConfig[]>;
+
+export { type StreamingRenderOptions, type StreamingRenderResult, type SuspenseBoundaryConfig, createLazyContent, createStreamingResponse, createStreamingSSR, renderWithStreaming, streamParallel, streamSequential };

package/dist/streaming/index.js

@@ -0,0 +1,3 @@
+export { createLazyContent, createStreamingResponse, createStreamingSSR, renderWithStreaming, streamParallel, streamSequential } from '../chunk-QEFGUHYD.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/streaming/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@flight-framework/core",
+  "version": "0.0.1",
+  "description": "Core primitives for Flight Framework - routing, rendering, caching",
+  "keywords": [
+    "flight",
+    "framework",
+    "core",
+    "ssr",
+    "routing"
+  ],
+  "license": "MIT",
+  "author": "Flight Contributors",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./router": {
+      "types": "./dist/router/index.d.ts",
+      "import": "./dist/router/index.js"
+    },
+    "./render": {
+      "types": "./dist/render/index.d.ts",
+      "import": "./dist/render/index.js"
+    },
+    "./cache": {
+      "types": "./dist/cache/index.d.ts",
+      "import": "./dist/cache/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./file-router": {
+      "types": "./dist/file-router/index.d.ts",
+      "import": "./dist/file-router/index.js"
+    },
+    "./actions": {
+      "types": "./dist/actions/index.d.ts",
+      "import": "./dist/actions/index.js"
+    },
+    "./handlers": {
+      "types": "./dist/handlers/index.d.ts",
+      "import": "./dist/handlers/index.js"
+    },
+    "./streaming": {
+      "types": "./dist/streaming/index.d.ts",
+      "import": "./dist/streaming/index.js"
+    },
+    "./rsc": {
+      "types": "./dist/rsc/index.d.ts",
+      "import": "./dist/rsc/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "radix3": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^6.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "vite": "^6.0.0 || ^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "clean": "rimraf dist"
+  }
+}