@flight-framework/core 0.0.3 → 0.2.0

package/dist/streaming/conditional.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @flight-framework/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 '@flight-framework/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-XOIYNY4I.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

@@ -61,6 +61,14 @@ interface SuspenseBoundaryConfig {
     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.

package/dist/streaming/index.js

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

package/dist/streaming/observability.d.ts

@@ -0,0 +1,201 @@
+import { SuspenseBoundaryConfig, StreamingRenderOptions } from './index.js';
+
+/**
+ * @flight-framework/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 '@flight-framework/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-6BDCTUQY.js';
+import '../chunk-RSVA2EYO.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';
+
+/**
+ * @flight-framework/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 '@flight-framework/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-WOEIJWGJ.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"}