@flightdev/core 0.6.7

package/dist/streaming/conditional.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @flightdev/core - Conditional Streaming
+ *
+ * Smart streaming decisions based on request context.
+ * Bots get full HTML, users get streaming - YOU control the logic.
+ *
+ * Best Practices 2026:
+ * - SEO-friendly: Crawlers receive complete HTML
+ * - Performance: Users get progressive streaming
+ * - Flexibility: Custom conditions for any use case
+ *
+ * @example
+ * ```typescript
+ * import { streamIf } from '@flightdev/core/streaming';
+ *
+ * const response = await streamIf({
+ *     request,
+ *     condition: (req) => !isBot(req), // YOUR logic
+ *     stream: () => createStreamingSSR({ ... }),
+ *     static: () => renderToString(<App />),
+ * });
+ * ```
+ */
+/**
+ * Condition function to determine if streaming should be used
+ */
+type StreamingCondition = (request: Request) => boolean | Promise<boolean>;
+/**
+ * Built-in condition types
+ */
+type BuiltInCondition = 'always-stream' | 'never-stream' | 'no-bots' | 'fast-network' | 'modern-browser';
+/**
+ * Configuration for conditional streaming
+ */
+interface StreamIfConfig<T = Response> {
+    /** The incoming request */
+    request: Request;
+    /** Condition to check (function or built-in) */
+    condition: StreamingCondition | BuiltInCondition;
+    /** Factory for streaming response */
+    stream: () => Promise<T> | T;
+    /** Factory for static response */
+    static: () => Promise<T> | T;
+    /** Optional: Custom bot patterns */
+    botPatterns?: RegExp[];
+    /** Optional: Force streaming via query param (for testing) */
+    forceStreamParam?: string;
+    /** Optional: Force static via query param (for testing) */
+    forceStaticParam?: string;
+}
+/**
+ * Result of condition evaluation
+ */
+interface StreamingDecision {
+    /** Whether streaming was used */
+    streaming: boolean;
+    /** Reason for the decision */
+    reason: string;
+    /** The response */
+    response: Response;
+}
+/**
+ * Default bot patterns for detection
+ */
+declare const DEFAULT_BOT_PATTERNS: RegExp[];
+/**
+ * Check if a request is from a bot/crawler
+ */
+declare function isBot(request: Request, customPatterns?: RegExp[]): boolean;
+/**
+ * Check if request explicitly asks for no streaming
+ */
+declare function prefersNoStream(request: Request): boolean;
+/**
+ * Check if a connection is likely slow (based on headers)
+ */
+declare function isSlowConnection(request: Request): boolean;
+/**
+ * Check if browser supports streaming well
+ */
+declare function supportsStreaming(request: Request): boolean;
+/**
+ * Conditionally use streaming or static rendering based on request context
+ */
+declare function streamIf<T = Response>(config: StreamIfConfig<T>): Promise<{
+    result: T;
+    streaming: boolean;
+    reason: string;
+}>;
+/**
+ * Create a middleware-style conditional streamer
+ */
+declare function createConditionalStreamer<T = Response>(defaultCondition: StreamingCondition | BuiltInCondition, options?: {
+    botPatterns?: RegExp[];
+    forceStreamParam?: string;
+    forceStaticParam?: string;
+}): (config: {
+    request: Request;
+    stream: () => Promise<T> | T;
+    static: () => Promise<T> | T;
+    condition?: StreamingCondition | BuiltInCondition;
+}) => Promise<{
+    result: T;
+    streaming: boolean;
+    reason: string;
+}>;
+/**
+ * Add streaming decision headers to response (for debugging)
+ */
+declare function addStreamingHeaders(response: Response, decision: {
+    streaming: boolean;
+    reason: string;
+}): Response;
+/**
+ * Create a streaming-aware Response with appropriate headers
+ */
+declare function createStreamingResponse(stream: ReadableStream<Uint8Array>, options?: {
+    status?: number;
+    headers?: Record<string, string>;
+    isStreaming?: boolean;
+}): Response;
+/**
+ * Create a static HTML Response
+ */
+declare function createStaticResponse(html: string, options?: {
+    status?: number;
+    headers?: Record<string, string>;
+}): Response;
+
+export { type BuiltInCondition, DEFAULT_BOT_PATTERNS, type StreamIfConfig, type StreamingCondition, type StreamingDecision, addStreamingHeaders, createConditionalStreamer, createStaticResponse, createStreamingResponse, isBot, isSlowConnection, prefersNoStream, streamIf, supportsStreaming };

package/dist/streaming/conditional.js

@@ -0,0 +1,3 @@
+export { DEFAULT_BOT_PATTERNS, addStreamingHeaders, createConditionalStreamer, createStaticResponse, createStreamingResponse, isBot, isSlowConnection, prefersNoStream, streamIf, supportsStreaming } from '../chunk-UVH5XJRP.js';
+//# sourceMappingURL=conditional.js.map
+//# sourceMappingURL=conditional.js.map

package/dist/streaming/conditional.js.map

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

package/dist/streaming/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @flightdev/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>;
+    /**
+     * IDs of boundaries that must resolve before this one.
+     * Enables dependency-aware streaming for complex data relationships.
+     * @example ['user'] - Wait for 'user' boundary before starting
+     */
+    dependsOn?: string[];
+    /** Custom metadata for observability */
+    meta?: Record<string, unknown>;
+}
+/**
+ * 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-C37YQQI7.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/dist/streaming/observability.d.ts

@@ -0,0 +1,201 @@
+import { SuspenseBoundaryConfig, StreamingRenderOptions } from './index.js';
+
+/**
+ * @flightdev/core - Streaming Observability
+ *
+ * Zero-telemetry metrics and instrumentation for streaming SSR.
+ * All data stays on YOUR infrastructure - never sent anywhere.
+ *
+ * Best Practices 2026:
+ * - Comprehensive timing metrics for each boundary
+ * - Hook-based observability for custom integrations
+ * - Performance insights without vendor lock-in
+ *
+ * @example
+ * ```typescript
+ * import { createInstrumentedStream } from '@flightdev/core/streaming';
+ *
+ * const { stream, metrics } = await createInstrumentedStream({
+ *     shell: '<html>...',
+ *     boundaries: [...],
+ *     onMetrics: (m) => myAnalytics.track(m), // YOUR system
+ * });
+ * ```
+ */
+
+/**
+ * Timing information for a single boundary
+ */
+interface BoundaryTiming {
+    /** Boundary identifier */
+    id: string;
+    /** When the boundary started resolving (ms since stream start) */
+    startTime: number;
+    /** When the boundary finished resolving */
+    endTime: number;
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Whether it resolved successfully */
+    success: boolean;
+    /** Size of content in bytes (if successful) */
+    contentSize?: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Overall streaming metrics
+ */
+interface StreamingMetrics {
+    /** Unique ID for this stream session */
+    streamId: string;
+    /** When streaming started */
+    startTime: number;
+    /** Time to shell ready (TTFB improvement) */
+    shellTime: number;
+    /** Time until all boundaries resolved */
+    totalStreamTime: number;
+    /** Individual boundary timings */
+    boundaries: BoundaryTiming[];
+    /** Number of boundaries that resolved successfully */
+    successCount: number;
+    /** Number of boundaries that failed */
+    errorCount: number;
+    /** Total bytes streamed */
+    totalBytes: number;
+    /** Strategy used (if priority streaming) */
+    strategy?: string;
+    /** Custom metadata you can add */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Observability hooks for streaming events
+ */
+interface StreamingObserver {
+    /** Called when streaming starts */
+    onStreamStart?: (streamId: string) => void;
+    /** Called when shell is sent */
+    onShellReady?: (timing: {
+        streamId: string;
+        duration: number;
+    }) => void;
+    /** Called when a boundary starts resolving */
+    onBoundaryStart?: (info: {
+        streamId: string;
+        boundaryId: string;
+        startTime: number;
+    }) => void;
+    /** Called when a boundary finishes */
+    onBoundaryEnd?: (timing: BoundaryTiming & {
+        streamId: string;
+    }) => void;
+    /** Called when streaming completes */
+    onStreamEnd?: (metrics: StreamingMetrics) => void;
+    /** Called on any error */
+    onError?: (error: {
+        streamId: string;
+        boundaryId?: string;
+        error: Error;
+    }) => void;
+}
+/**
+ * Configuration for instrumented streaming
+ */
+interface InstrumentedStreamConfig {
+    /** Initial HTML shell */
+    shell: string;
+    /** Closing HTML */
+    shellEnd: string;
+    /** Suspense boundaries */
+    suspenseBoundaries: SuspenseBoundaryConfig[];
+    /** Streaming options */
+    options?: StreamingRenderOptions;
+    /** Observer hooks */
+    observer?: StreamingObserver;
+    /** Callback when all metrics are ready */
+    onMetrics?: (metrics: StreamingMetrics) => void;
+    /** Custom metadata to include in metrics */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Result of instrumented streaming
+ */
+interface InstrumentedStreamResult {
+    /** The readable stream */
+    stream: ReadableStream<Uint8Array>;
+    /** Abort the stream */
+    abort: () => void;
+    /** Shell ready promise */
+    shellReady: Promise<void>;
+    /** All content ready promise */
+    allReady: Promise<void>;
+    /** Final metrics (resolves when stream completes) */
+    metrics: Promise<StreamingMetrics>;
+    /** Stream ID for correlation */
+    streamId: string;
+}
+/**
+ * Create an instrumented streaming SSR response with full observability
+ */
+declare function createInstrumentedStream(config: InstrumentedStreamConfig): Promise<InstrumentedStreamResult>;
+/**
+ * Aggregate metrics from multiple streams for analysis
+ */
+declare class MetricsAggregator {
+    private metrics;
+    private maxSamples;
+    constructor(maxSamples?: number);
+    /**
+     * Add metrics from a stream
+     */
+    add(metrics: StreamingMetrics): void;
+    /**
+     * Get average shell time
+     */
+    getAverageShellTime(): number;
+    /**
+     * Get average total stream time
+     */
+    getAverageTotalTime(): number;
+    /**
+     * Get slowest boundaries (by average duration)
+     */
+    getSlowestBoundaries(limit?: number): {
+        id: string;
+        avgDuration: number;
+        errorRate: number;
+    }[];
+    /**
+     * Get overall error rate
+     */
+    getErrorRate(): number;
+    /**
+     * Get percentiles for shell time
+     */
+    getShellTimePercentiles(): {
+        p50: number;
+        p90: number;
+        p99: number;
+    };
+    /**
+     * Export all metrics for external analysis
+     */
+    export(): StreamingMetrics[];
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+}
+/**
+ * Create a streaming observer from a simple logger function
+ */
+declare function createLoggerObserver(log: (message: string, data?: Record<string, unknown>) => void): StreamingObserver;
+/**
+ * Create observer that sends metrics to a custom endpoint (YOUR infrastructure)
+ */
+declare function createHttpObserver(endpoint: string, options?: {
+    headers?: Record<string, string>;
+    batchSize?: number;
+    flushInterval?: number;
+}): StreamingObserver;
+
+export { type BoundaryTiming, type InstrumentedStreamConfig, type InstrumentedStreamResult, MetricsAggregator, type StreamingMetrics, type StreamingObserver, createHttpObserver, createInstrumentedStream, createLoggerObserver };

package/dist/streaming/observability.js

@@ -0,0 +1,4 @@
+export { MetricsAggregator, createHttpObserver, createInstrumentedStream, createLoggerObserver } from '../chunk-WZIJKCL3.js';
+import '../chunk-C37YQQI7.js';
+//# sourceMappingURL=observability.js.map
+//# sourceMappingURL=observability.js.map

package/dist/streaming/observability.js.map

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

package/dist/streaming/priority.d.ts

@@ -0,0 +1,103 @@
+import { StreamingRenderOptions, StreamingRenderResult } from './index.js';
+
+/**
+ * @flightdev/core - Priority-Based Streaming SSR
+ *
+ * Out-of-order streaming with priority control, deadlines, and dependencies.
+ * Gives developers full control over streaming order and timing.
+ *
+ * Best Practices 2026:
+ * - Priority-based content delivery for optimal UX
+ * - Deadline-aware streaming to prevent slow boundaries from blocking
+ * - Dependency graphs for complex data relationships
+ * - Strategy-based streaming modes for different use cases
+ *
+ * @example
+ * ```typescript
+ * import { streamWithPriority } from '@flightdev/core/streaming';
+ *
+ * const result = await streamWithPriority({
+ *     shell: '<html>...',
+ *     shellEnd: '</html>',
+ *     boundaries: [
+ *         { id: 'hero', priority: 1, content: fetchHero() },
+ *         { id: 'nav', priority: 2, content: fetchNav() },
+ *         { id: 'comments', priority: 10, content: fetchComments() },
+ *     ],
+ *     strategy: 'priority-first',
+ * });
+ * ```
+ */
+
+/**
+ * Boundary with priority and advanced options
+ */
+interface PriorityBoundary {
+    /** Unique identifier for this boundary */
+    id: string;
+    /** Fallback HTML while loading */
+    fallback: string;
+    /** Content promise or factory function */
+    content: Promise<string> | (() => Promise<string>);
+    /** Priority level (lower number = higher priority, rendered first) */
+    priority: number;
+    /** Maximum time to wait before skipping (ms). Boundary shows fallback if exceeded. */
+    deadline?: number;
+    /** IDs of boundaries that must resolve before this one starts */
+    dependsOn?: string[];
+    /** Optional metadata for observability */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Streaming strategy - how to order content delivery
+ */
+type StreamingStrategy = 'priority-first' | 'first-ready' | 'dependency-aware' | 'round-robin' | 'deadline-strict';
+/**
+ * Result of a priority boundary resolution
+ */
+interface BoundaryResolution {
+    id: string;
+    content: string | null;
+    duration: number;
+    status: 'resolved' | 'timeout' | 'error' | 'skipped';
+    error?: Error;
+}
+/**
+ * Priority streaming configuration
+ */
+interface PriorityStreamConfig {
+    /** Initial HTML shell */
+    shell: string;
+    /** Closing HTML */
+    shellEnd: string;
+    /** Boundaries with priorities */
+    boundaries: PriorityBoundary[];
+    /** Streaming strategy */
+    strategy: StreamingStrategy;
+    /** Base streaming options */
+    options?: StreamingRenderOptions;
+    /** Callback when a boundary resolves */
+    onBoundaryResolved?: (resolution: BoundaryResolution) => void;
+    /** Global timeout for all boundaries */
+    globalTimeout?: number;
+}
+/**
+ * Priority streaming result with additional metrics
+ */
+interface PriorityStreamResult extends StreamingRenderResult {
+    /** Resolution details for each boundary */
+    resolutions: Promise<BoundaryResolution[]>;
+}
+/**
+ * Create a priority-ordered streaming SSR response
+ */
+declare function streamWithPriority(config: PriorityStreamConfig): Promise<PriorityStreamResult>;
+/**
+ * Validate that boundaries don't have circular dependencies
+ */
+declare function validateDependencies(boundaries: PriorityBoundary[]): {
+    valid: boolean;
+    cycles?: string[][];
+};
+
+export { type BoundaryResolution, type PriorityBoundary, type PriorityStreamConfig, type PriorityStreamResult, type StreamingStrategy, streamWithPriority, validateDependencies };

package/dist/streaming/priority.js

@@ -0,0 +1,3 @@
+export { streamWithPriority, validateDependencies } from '../chunk-OEJMIE2Q.js';
+//# sourceMappingURL=priority.js.map
+//# sourceMappingURL=priority.js.map

package/dist/streaming/priority.js.map

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

package/dist/utils/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @flightdev/core - Environment Utilities
+ *
+ * Environment detection utilities that work across Node.js, browsers, and edge runtimes.
+ * No hardcoded values - detects environment dynamically.
+ */
+/**
+ * Check if running in production environment.
+ *
+ * Detection order:
+ * 1. Node.js process.env.NODE_ENV
+ * 2. Vite/modern bundlers import.meta.env.MODE or import.meta.env.PROD
+ * 3. Default: false (not production)
+ */
+declare function isProduction(): boolean;
+/**
+ * Check if running in development environment.
+ *
+ * Detection order:
+ * 1. Node.js process.env.NODE_ENV
+ * 2. Vite/modern bundlers import.meta.env.MODE or import.meta.env.DEV
+ * 3. Default: true (assume development if unknown)
+ */
+declare function isDevelopment(): boolean;
+/**
+ * Check if running in test environment.
+ */
+declare function isTest(): boolean;
+/**
+ * Check if running on the server (not browser).
+ */
+declare function isServer(): boolean;
+/**
+ * Check if running in the browser.
+ */
+declare function isBrowser(): boolean;
+/**
+ * Get the current environment name.
+ */
+declare function getEnvironment(): 'production' | 'development' | 'test' | 'unknown';
+
+export { getEnvironment, isBrowser, isDevelopment, isProduction, isServer, isTest };

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+import '../chunk-PL37KFRJ.js';
+export { getEnvironment, isBrowser, isDevelopment, isProduction, isServer, isTest } from '../chunk-LWVETFJV.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map