ai-props 2.3.0 → 2.4.0

package/dist/rpc.js

@@ -0,0 +1,359 @@
+/**
+ * RPC Export - Cloudflare Workers RPC utilities for AI Props
+ *
+ * This module provides RPC-specific functionality for consuming the AI Props
+ * service via Cloudflare Workers Service Bindings. It exports the service
+ * classes, types, and utilities for building RPC clients.
+ *
+ * ## RPC Pattern Overview
+ *
+ * Cloudflare Workers RPC allows direct method invocation between workers
+ * using Service Bindings. The AI Props service exposes methods through:
+ *
+ * 1. **WorkerEntrypoint** (`PropsService`) - The main entry point that workers
+ *    bind to. Provides `getService()` to get an RPC-callable service instance.
+ *
+ * 2. **RpcTarget** (`PropsServiceCore`) - The actual service implementation
+ *    with all callable methods. Returned by `getService()`.
+ *
+ * ## Usage Patterns
+ *
+ * ### Basic Service Binding
+ * ```typescript
+ * // wrangler.jsonc
+ * {
+ *   "services": [
+ *     { "binding": "AI_PROPS", "service": "ai-props" }
+ *   ]
+ * }
+ *
+ * // worker.ts
+ * import type { PropsService } from 'ai-props/rpc'
+ *
+ * interface Env {
+ *   AI_PROPS: Service<PropsService>
+ * }
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const service = env.AI_PROPS.getService()
+ *     const result = await service.generate({
+ *       schema: { title: 'Page title' }
+ *     })
+ *     return Response.json(result)
+ *   }
+ * }
+ * ```
+ *
+ * ### With Typed Client Factory
+ * ```typescript
+ * import { createPropsClient, type PropsClientOptions } from 'ai-props/rpc'
+ *
+ * const client = createPropsClient({
+ *   service: env.AI_PROPS,
+ *   timeout: 30000,
+ *   retry: { attempts: 3, backoff: 'exponential' }
+ * })
+ *
+ * const result = await client.generate({
+ *   schema: { title: 'Page title' }
+ * })
+ * ```
+ *
+ * ### Error Handling
+ * ```typescript
+ * import { PropsRPCError, isPropsRPCError } from 'ai-props/rpc'
+ *
+ * try {
+ *   const result = await service.generate(options)
+ * } catch (error) {
+ *   if (isPropsRPCError(error)) {
+ *     console.error(`RPC Error: ${error.code} - ${error.message}`)
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Re-export service classes from worker
+export { PropsService, PropsServiceCore, PropsWorker } from './worker.js';
+// ==================== RPC Error Types ====================
+/**
+ * Error codes for RPC operations
+ */
+export var PropsRPCErrorCode;
+(function (PropsRPCErrorCode) {
+    /** Method not found on service */
+    PropsRPCErrorCode["METHOD_NOT_FOUND"] = "METHOD_NOT_FOUND";
+    /** Invalid arguments passed to method */
+    PropsRPCErrorCode["INVALID_ARGUMENTS"] = "INVALID_ARGUMENTS";
+    /** Service connection failed */
+    PropsRPCErrorCode["CONNECTION_FAILED"] = "CONNECTION_FAILED";
+    /** Request timed out */
+    PropsRPCErrorCode["TIMEOUT"] = "TIMEOUT";
+    /** Service returned an error */
+    PropsRPCErrorCode["SERVICE_ERROR"] = "SERVICE_ERROR";
+    /** Network error during RPC call */
+    PropsRPCErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    /** Unknown error */
+    PropsRPCErrorCode["UNKNOWN"] = "UNKNOWN";
+})(PropsRPCErrorCode || (PropsRPCErrorCode = {}));
+/**
+ * Structured error for RPC failures
+ *
+ * Provides detailed error information for debugging RPC issues.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await service.generate(options)
+ * } catch (error) {
+ *   if (error instanceof PropsRPCError) {
+ *     console.error(`[${error.code}] ${error.message}`)
+ *     if (error.cause) console.error('Caused by:', error.cause)
+ *   }
+ * }
+ * ```
+ */
+export class PropsRPCError extends Error {
+    /** Error code for programmatic handling */
+    code;
+    /** Original error that caused this RPC error */
+    originalCause;
+    /** Method that was being called */
+    method;
+    /** Timestamp when error occurred */
+    timestamp;
+    constructor(message, code = PropsRPCErrorCode.UNKNOWN, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.name = 'PropsRPCError';
+        this.code = code;
+        this.originalCause = options?.cause;
+        this.method = options?.method;
+        this.timestamp = Date.now();
+    }
+    /**
+     * Convert to JSON for logging/serialization
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            method: this.method,
+            timestamp: this.timestamp,
+            cause: this.originalCause?.message,
+        };
+    }
+}
+/**
+ * Type guard to check if an error is a PropsRPCError
+ */
+export function isPropsRPCError(error) {
+    return error instanceof PropsRPCError;
+}
+/**
+ * Default retry configuration
+ */
+export const DEFAULT_RETRY_CONFIG = {
+    attempts: 3,
+    backoff: 'exponential',
+    initialDelay: 1000,
+    maxDelay: 30000,
+    multiplier: 2,
+    retryOn: [
+        PropsRPCErrorCode.CONNECTION_FAILED,
+        PropsRPCErrorCode.TIMEOUT,
+        PropsRPCErrorCode.NETWORK_ERROR,
+    ],
+};
+/**
+ * Calculate delay for retry attempt based on backoff strategy
+ */
+export function calculateRetryDelay(attempt, config) {
+    let delay;
+    switch (config.backoff) {
+        case 'fixed':
+            delay = config.initialDelay;
+            break;
+        case 'linear':
+            delay = config.initialDelay * attempt;
+            break;
+        case 'exponential':
+        default:
+            delay = config.initialDelay * Math.pow(config.multiplier, attempt - 1);
+            break;
+    }
+    return Math.min(delay, config.maxDelay);
+}
+/**
+ * Sleep for a specified number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Execute a function with retry logic
+ *
+ * Wraps an async function with configurable retry behavior including
+ * exponential backoff, maximum attempts, and error code filtering.
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => service.generate(options),
+ *   { attempts: 3, backoff: 'exponential' }
+ * )
+ * ```
+ */
+export async function withRetry(fn, config) {
+    const fullConfig = {
+        ...DEFAULT_RETRY_CONFIG,
+        ...config,
+    };
+    let lastError;
+    let attempt = 0;
+    while (attempt < fullConfig.attempts) {
+        attempt++;
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if we should retry this error
+            const shouldRetry = attempt < fullConfig.attempts &&
+                (isPropsRPCError(error) ? fullConfig.retryOn.includes(error.code) : true);
+            if (!shouldRetry) {
+                throw error;
+            }
+            // Calculate and wait for delay
+            const delay = calculateRetryDelay(attempt, fullConfig);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Create a typed Props RPC client with optional retry and monitoring
+ *
+ * Wraps the service binding with timeout handling, retry logic, and
+ * lifecycle hooks for monitoring.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const client = createPropsClient({ service: env.AI_PROPS })
+ * const result = await client.generate({ schema: { title: 'Page title' } })
+ *
+ * // With retry and monitoring
+ * const client = createPropsClient({
+ *   service: env.AI_PROPS,
+ *   timeout: 30000,
+ *   retry: { attempts: 3, backoff: 'exponential' },
+ *   onRequest: (method, args) => console.log(`Calling ${method}`),
+ *   onResponse: (method, result, duration) =>
+ *     console.log(`${method} completed in ${duration}ms`),
+ *   onError: (method, error) => console.error(`${method} failed:`, error)
+ * })
+ * ```
+ */
+export function createPropsClient(options) {
+    const { service, timeout = 30000, retry, onRequest, onResponse, onError } = options;
+    // Get the underlying service instance
+    const serviceInstance = service.getService();
+    /**
+     * Wrap a method with timeout, retry, and hooks
+     */
+    function wrapMethod(methodName, method) {
+        return async (...args) => {
+            const startTime = Date.now();
+            // Call onRequest hook
+            onRequest?.(methodName, args);
+            const executeCall = async () => {
+                // Create timeout promise
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => {
+                        reject(new PropsRPCError(`Request timed out after ${timeout}ms`, PropsRPCErrorCode.TIMEOUT, {
+                            method: methodName,
+                        }));
+                    }, timeout);
+                });
+                // Race between call and timeout
+                try {
+                    return await Promise.race([method.apply(serviceInstance, args), timeoutPromise]);
+                }
+                catch (error) {
+                    // Convert to PropsRPCError if not already
+                    if (!isPropsRPCError(error)) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        const errorCause = error instanceof Error ? error : undefined;
+                        throw new PropsRPCError(message, PropsRPCErrorCode.SERVICE_ERROR, errorCause ? { cause: errorCause, method: methodName } : { method: methodName });
+                    }
+                    throw error;
+                }
+            };
+            try {
+                // Execute with optional retry
+                const result = retry ? await withRetry(executeCall, retry) : await executeCall();
+                // Call onResponse hook
+                const duration = Date.now() - startTime;
+                onResponse?.(methodName, result, duration);
+                return result;
+            }
+            catch (error) {
+                // Call onError hook
+                onError?.(methodName, error instanceof Error ? error : new Error(String(error)));
+                throw error;
+            }
+        };
+    }
+    /**
+     * Wrap a synchronous method (just adds hooks, no timeout/retry)
+     */
+    function wrapSyncMethod(methodName, method) {
+        return (...args) => {
+            const startTime = Date.now();
+            onRequest?.(methodName, args);
+            try {
+                const result = method.apply(serviceInstance, args);
+                const duration = Date.now() - startTime;
+                onResponse?.(methodName, result, duration);
+                return result;
+            }
+            catch (error) {
+                onError?.(methodName, error instanceof Error ? error : new Error(String(error)));
+                throw error;
+            }
+        };
+    }
+    // Create wrapped client with type assertions to preserve generics
+    const client = {
+        // Async methods with timeout/retry
+        generate: wrapMethod('generate', serviceInstance.generate.bind(serviceInstance)),
+        prefetch: wrapMethod('prefetch', serviceInstance.prefetch.bind(serviceInstance)),
+        generateMany: wrapMethod('generateMany', serviceInstance.generateMany.bind(serviceInstance)),
+        mergeWithGenerated: wrapMethod('mergeWithGenerated', serviceInstance.mergeWithGenerated.bind(serviceInstance)),
+        // Sync methods (just hooks)
+        getSync: wrapSyncMethod('getSync', serviceInstance.getSync.bind(serviceInstance)),
+        configure: wrapSyncMethod('configure', serviceInstance.configure.bind(serviceInstance)),
+        getConfig: wrapSyncMethod('getConfig', serviceInstance.getConfig.bind(serviceInstance)),
+        resetConfig: wrapSyncMethod('resetConfig', serviceInstance.resetConfig.bind(serviceInstance)),
+        getCached: wrapSyncMethod('getCached', serviceInstance.getCached.bind(serviceInstance)),
+        setCached: wrapSyncMethod('setCached', serviceInstance.setCached.bind(serviceInstance)),
+        deleteCached: wrapSyncMethod('deleteCached', serviceInstance.deleteCached.bind(serviceInstance)),
+        clearCache: wrapSyncMethod('clearCache', serviceInstance.clearCache.bind(serviceInstance)),
+        getCacheSize: wrapSyncMethod('getCacheSize', serviceInstance.getCacheSize.bind(serviceInstance)),
+        createCacheKey: wrapSyncMethod('createCacheKey', serviceInstance.createCacheKey.bind(serviceInstance)),
+        configureCache: wrapSyncMethod('configureCache', serviceInstance.configureCache.bind(serviceInstance)),
+        validate: wrapSyncMethod('validate', serviceInstance.validate.bind(serviceInstance)),
+        hasRequired: wrapSyncMethod('hasRequired', serviceInstance.hasRequired.bind(serviceInstance)),
+        getMissing: wrapSyncMethod('getMissing', serviceInstance.getMissing.bind(serviceInstance)),
+        isComplete: wrapSyncMethod('isComplete', serviceInstance.isComplete.bind(serviceInstance)),
+        sanitize: wrapSyncMethod('sanitize', serviceInstance.sanitize.bind(serviceInstance)),
+        mergeDefaults: wrapSyncMethod('mergeDefaults', serviceInstance.mergeDefaults.bind(serviceInstance)),
+        // Utility method
+        getUnderlyingService: () => serviceInstance,
+    };
+    return client;
+}
+//# sourceMappingURL=rpc.js.map

package/dist/rpc.js.map

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

package/dist/streaming.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Optimized streaming utilities for AI-powered props rendering
+ *
+ * This module provides high-performance streaming capabilities with:
+ * - Adaptive chunk sizing for network efficiency
+ * - Backpressure handling to prevent memory overflow
+ * - Progress callbacks for streaming status
+ * - Memory-efficient streaming for large components
+ *
+ * @packageDocumentation
+ */
+import { renderToReadableStream as baseRenderToReadableStream, streamJSXResponse as baseStreamJSXResponse, createStreamingRenderer as baseCreateStreamingRenderer, type StreamingOptions, type StreamingRendererOptions } from './hono-jsx.js';
+import { type StreamMDXOptions } from './mdx.js';
+/** Default chunk size for optimal network performance (16KB) */
+export declare const DEFAULT_CHUNK_SIZE: number;
+/** Minimum chunk size to avoid excessive overhead (1KB) */
+export declare const MIN_CHUNK_SIZE = 1024;
+/** Maximum chunk size for memory efficiency (64KB) */
+export declare const MAX_CHUNK_SIZE: number;
+/** High water mark for backpressure (64KB) */
+export declare const DEFAULT_HIGH_WATER_MARK: number;
+/**
+ * Progress information during streaming
+ */
+export interface StreamingProgress {
+    /** Total bytes processed so far */
+    bytesProcessed: number;
+    /** Total bytes expected (if known) */
+    totalBytes?: number;
+    /** Number of chunks sent */
+    chunksProcessed: number;
+    /** Percentage complete (0-100, if total is known) */
+    percentComplete?: number;
+    /** Current streaming phase */
+    phase: 'starting' | 'streaming' | 'hydration' | 'complete' | 'error';
+    /** Time elapsed in milliseconds */
+    elapsedMs: number;
+}
+/**
+ * Progress callback function type
+ */
+export type StreamingProgressCallback = (progress: StreamingProgress) => void;
+/**
+ * Enhanced streaming options with optimization controls
+ */
+export interface OptimizedStreamingOptions extends StreamingOptions {
+    /** Chunk size in bytes (default: 16KB) */
+    chunkSize?: number;
+    /** High water mark for backpressure (default: 64KB) */
+    highWaterMark?: number;
+    /** Progress callback for streaming updates */
+    onProgress?: StreamingProgressCallback;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Enable compression hints for response */
+    compressionHint?: boolean;
+    /** Flush chunks immediately without buffering */
+    flushImmediate?: boolean;
+}
+/**
+ * Enhanced streaming renderer options
+ */
+export interface OptimizedStreamingRendererOptions extends StreamingRendererOptions {
+    /** Chunk size in bytes */
+    chunkSize?: number;
+    /** High water mark for backpressure */
+    highWaterMark?: number;
+    /** Progress callback */
+    onProgress?: StreamingProgressCallback;
+}
+/**
+ * Streaming statistics for monitoring
+ */
+export interface StreamingStats {
+    /** Total bytes streamed */
+    totalBytes: number;
+    /** Number of chunks sent */
+    totalChunks: number;
+    /** Average chunk size */
+    averageChunkSize: number;
+    /** Time to first byte in ms */
+    timeToFirstByte: number;
+    /** Total streaming duration in ms */
+    totalDuration: number;
+    /** Whether backpressure was encountered */
+    encounteredBackpressure: boolean;
+}
+/**
+ * Calculate optimal chunk size based on content size
+ *
+ * @param contentLength - Total content length in bytes
+ * @returns Optimal chunk size
+ */
+export declare function calculateOptimalChunkSize(contentLength: number): number;
+/**
+ * Render a component to a ReadableStream with optimizations
+ *
+ * Features:
+ * - Adaptive chunk sizing based on content
+ * - Backpressure handling to prevent memory overflow
+ * - Progress callbacks for monitoring
+ * - Memory-efficient streaming for large content
+ *
+ * @param component - Component function to render
+ * @param props - Props to pass to component
+ * @param options - Optimized streaming options
+ * @returns ReadableStream of rendered HTML
+ *
+ * @example
+ * ```ts
+ * const stream = await renderToReadableStream(
+ *   MyComponent,
+ *   { title: 'Hello' },
+ *   {
+ *     chunkSize: 8192,
+ *     onProgress: (progress) => console.log(`${progress.percentComplete}% complete`),
+ *   }
+ * )
+ * ```
+ */
+export declare function renderToReadableStream<P>(component: (props: P) => string | Promise<string>, props: P, options?: OptimizedStreamingOptions): Promise<ReadableStream<Uint8Array>>;
+/**
+ * Create a streaming Response with optimizations
+ *
+ * @param component - Component function to render
+ * @param props - Props to pass to component
+ * @param options - Optimized streaming options
+ * @returns Response with streaming body
+ *
+ * @example
+ * ```ts
+ * // In a Hono/Worker handler
+ * export default {
+ *   fetch(request, env) {
+ *     return streamJSXResponse(
+ *       PageComponent,
+ *       { data: pageData },
+ *       {
+ *         streaming: true,
+ *         compressionHint: true,
+ *       }
+ *     )
+ *   }
+ * }
+ * ```
+ */
+export declare function streamJSXResponse<P>(component: (props: P) => string | Promise<string>, props: P, options?: OptimizedStreamingOptions): Promise<Response>;
+/**
+ * Create a reusable streaming renderer with configuration
+ *
+ * @param options - Renderer options with optimization controls
+ * @returns Streaming renderer instance with stats
+ *
+ * @example
+ * ```ts
+ * const renderer = createStreamingRenderer({
+ *   doctype: '<!DOCTYPE html>',
+ *   includeHydration: true,
+ *   chunkSize: 8192,
+ *   onProgress: (p) => console.log(p.phase),
+ * })
+ *
+ * const stream = await renderer.render(MyComponent, props)
+ * const stats = renderer.getStats()
+ * ```
+ */
+export declare function createStreamingRenderer(options: OptimizedStreamingRendererOptions): {
+    render: <P>(component: (props: P) => string | Promise<string>, props: P) => Promise<ReadableStream<Uint8Array>>;
+    getStats: () => StreamingStats | null;
+    resetStats: () => void;
+};
+/**
+ * Stream MDX content with AI-generated props and optimizations
+ *
+ * @param mdx - MDX content string
+ * @param props - Props for each component
+ * @param options - Stream options with optimizations
+ * @returns ReadableStream of rendered content
+ *
+ * @example
+ * ```ts
+ * const stream = await streamMDXWithProps(
+ *   '<Hero title="Welcome" />',
+ *   { Hero: { title: 'Welcome', subtitle: 'To the site' } },
+ *   {
+ *     chunkSize: 8192,
+ *     onProgress: (p) => console.log(`${p.chunksProcessed} chunks sent`),
+ *   }
+ * )
+ * ```
+ */
+export declare function streamMDXWithProps(mdx: string, props: Record<string, Record<string, unknown>>, options?: StreamMDXOptions & {
+    chunkSize?: number;
+    highWaterMark?: number;
+    onProgress?: StreamingProgressCallback;
+}): Promise<ReadableStream<Uint8Array>>;
+export { createHydrationContext, serializeHydrationData, collectHydrationData, HydrationProvider, useHydration, type HydrationContext, type HydrationData, type HydrationNode, type StreamingOptions, type StreamingRendererOptions, } from './hono-jsx.js';
+export { baseRenderToReadableStream as renderToReadableStreamBasic, baseStreamJSXResponse as streamJSXResponseBasic, baseCreateStreamingRenderer as createStreamingRendererBasic, };
+//# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

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