@lytjs/ssr 6.0.0 → 6.4.0

package/dist/index.d.cts

@@ -49,6 +49,16 @@ interface StreamRenderOptions {
     onShellReady?: () => void;
     /** 错误回调 */
     onError?: (error: Error) => void;
+    /** 流式渲染超时时间（毫秒），默认 30000 */
+    timeout?: number;
+    /** 当渲染超时时的回退 HTML 内容 */
+    fallbackHtml?: string;
+    /** 流控制：每秒最大字节数，用于防止突发流量 */
+    maxBytesPerSecond?: number;
+    /** 是否启用错误恢复模式，默认 true */
+    errorRecovery?: boolean;
+    /** 单个组件渲染超时（毫秒），默认 5000 */
+    componentTimeout?: number;
 }
 /** 异步数据预取上下文 */
 interface DataPrefetchContext {
@@ -90,6 +100,8 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
  * - 支持 Suspense 边界（先发送 shell，再发送异步内容）
  * - 使用 TextEncoder 编码为 Uint8Array
  * - 可配置分块大小和回调
+ * - 超时控制和错误恢复
+ * - 流速率控制
  *
  * @param vnode - 要渲染的 VNode
  * @param options - 流式渲染配置选项
@@ -101,6 +113,7 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
  *   chunkSize: 2048,
  *   onShellReady: () => console.log('Shell 已发送'),
  *   onError: (err) => console.error(err),
+ *   timeout: 30000,
  * });
  *
  * for await (const chunk of stream) {
@@ -182,6 +195,15 @@ interface SSGOptions {
     globalScripts?: string[];
     /** 全局额外样式 */
     globalStyles?: string[];
+    /** ISR 配置（增量静态再生成） */
+    isr?: {
+        /** 重新验证间隔（秒），0 表示按需重新验证 */
+        revalidate?: number;
+        /** 是否启用增量静态再生成 */
+        enabled?: boolean;
+        /** 预渲染 fallback 页面 */
+        fallback?: 'blocking' | boolean;
+    };
 }
 /**
  * 将生成的 HTML 写入文件系统
@@ -263,6 +285,224 @@ declare function generateRouteManifest(pages: SSGPage[], baseUrl?: string): Arra
  * @returns 错误信息数组，空数组表示全部合法
  */
 declare function validatePages(pages: SSGPage[]): string[];
+/**
+ * 创建 ISR 中间件
+ *
+ * @description
+ * 创建用于 Express/Fastify 等框架的 ISR 中间件，
+ * 支持增量静态再生成和背景重新验证。
+ *
+ * @param options - ISR 选项
+ * @returns 中间件函数
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createISRMiddleware, generateStaticPages } from '@lytjs/ssr';
+ *
+ * const app = express();
+ *
+ * // 预生成的页面
+ * const pages = [
+ *   { path: '/', component: homeComponent },
+ * ];
+ *
+ * const staticPages = generateStaticPages(pages);
+ *
+ * app.use(createISRMiddleware({
+ *   staticPages,
+ *   revalidate: 60, // 60秒后重新验证
+ *   async regenerate(path) {
+ *     const page = pages.find(p => p.path === path);
+ *     if (page) {
+ *       return generateStaticPages([page]).get('/index.html')!;
+ *     }
+ *     throw new Error('Page not found');
+ *   }
+ * }));
+ * ```
+ */
+declare function createISRMiddleware(options: {
+    /** 预生成的静态页面 */
+    staticPages: Map<string, string>;
+    /** 重新验证间隔（秒） */
+    revalidate?: number;
+    /** 是否启用 ISR */
+    enabled?: boolean;
+    /** 重新生成页面的函数 */
+    regenerate?: (path: string) => Promise<string>;
+}): (req: any, res: any, next: any) => Promise<any>;
+/**
+ * 触发按需重新验证
+ *
+ * @description
+ * 手动触发特定路径的重新验证，适合于内容更新后调用。
+ *
+ * @param path - 要重新验证的路径
+ * @param regenerate - 重新生成页面的函数
+ * @returns Promise<string> 新生成的 HTML
+ *
+ * @example
+ * ```typescript
+ * // 当博客文章更新时
+ * await revalidateOnDemand(
+ *   '/blog/my-post',
+ *   async () => generatePostHTML('my-post')
+ * );
+ * ```
+ */
+declare function revalidateOnDemand(path: string, regenerate: () => Promise<string>): Promise<string>;
+/**
+ * 获取 ISR 缓存统计信息
+ *
+ * @description
+ * 获取当前 ISR 缓存的统计信息，用于监控和调试。
+ *
+ * @returns 缓存统计信息
+ */
+declare function getISRCacheStats(): {
+    total: number;
+    paths: string[];
+};
+/**
+ * 清除 ISR 缓存
+ *
+ * @description
+ * 清除指定路径或所有过期的缓存。
+ *
+ * @param path - 可选，要清除的特定路径
+ * @param maxAge - 可选，清除超过指定秒数的缓存
+ */
+declare function clearISRCache(path?: string, maxAge?: number): void;
+
+/**
+ * @lytjs/ssr - 服务端组件完善
+ *
+ * 提供服务端组件生命周期管理、数据预取优化、状态序列化等功能
+ */
+
+/** 服务端组件生命周期钩子类型 */
+type ServerLifecycleHook = (context: ServerComponentContext) => Promise<void> | void;
+/** 服务端组件上下文 */
+interface ServerComponentContext {
+    /** 组件唯一 ID */
+    componentId: string;
+    /** 路由信息 */
+    route?: {
+        path: string;
+        params: Record<string, string>;
+        query: Record<string, string>;
+    };
+    /** 请求上下文 */
+    request?: {
+        headers: Record<string, string | undefined>;
+        cookies: Record<string, string>;
+    };
+}
+/** 服务端组件注册信息 */
+interface ServerComponentRegistration {
+    /** 组件名称 */
+    name: string;
+    /** 组件渲染函数 */
+    render: () => VNode;
+    /** 服务端初始化钩子 */
+    onServerInit?: ServerLifecycleHook;
+    /** 数据预取钩子 */
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+    /** 服务端清理钩子 */
+    onServerCleanup?: ServerLifecycleHook;
+}
+/** 服务端组件状态管理器 */
+declare class ServerComponentStateManager {
+    /** 注册的组件 */
+    private registrations;
+    /** 正在执行的预取请求 */
+    private pendingPrefetches;
+    /** 组件初始化状态 */
+    private initializationStates;
+    /**
+     * 注册服务端组件
+     */
+    register(name: string, registration: ServerComponentRegistration): void;
+    /**
+     * 取消注册服务端组件
+     */
+    unregister(name: string): void;
+    /**
+     * 获取已注册的组件
+     */
+    getRegistration(name: string): ServerComponentRegistration | undefined;
+    /**
+     * 初始化服务端组件
+     */
+    initializeComponent(name: string, context: ServerComponentContext): Promise<void>;
+    /**
+     * 清理服务端组件
+     */
+    cleanupComponent(name: string, context: ServerComponentContext): Promise<void>;
+    /**
+     * 预取组件数据（带缓存）
+     */
+    prefetchComponentData(name: string, context: DataPrefetchContext, cacheKey?: string): Promise<PrefetchResult>;
+    /**
+     * 清除所有缓存
+     */
+    clearAll(): void;
+}
+/** 全局状态管理器实例 */
+declare const stateManager: ServerComponentStateManager;
+/**
+ * 注册服务端组件
+ */
+declare function registerServerComponent(name: string, registration: ServerComponentRegistration): void;
+/**
+ * 取消注册服务端组件
+ */
+declare function unregisterServerComponent(name: string): void;
+/**
+ * 从 VNode 树中收集需要预取数据的组件
+ */
+declare function collectPrefetchComponents(vnode: VNode | VNode[] | string | number | null | undefined): string[];
+/**
+ * 并发预取多个组件的数据
+ */
+declare function prefetchAllComponents(components: string[], context: DataPrefetchContext): Promise<Record<string, PrefetchResult>>;
+/**
+ * 安全的状态序列化
+ * 处理循环引用、日期、正则表达式等特殊类型
+ */
+declare function safeSerializeState(state: unknown): string;
+/**
+ * 安全的状态反序列化
+ * 恢复特殊类型
+ */
+declare function safeDeserializeState(serialized: string): unknown;
+/**
+ * 创建组件脱水状态
+ */
+interface ComponentDehydratedState {
+    /** 组件名称 */
+    componentName: string;
+    /** 组件 Props */
+    props: Record<string, unknown>;
+    /** 预取的数据 */
+    data?: Record<string, unknown>;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 构建完整的脱水状态
+ */
+declare function buildDehydratedState(prefetchResults: Record<string, PrefetchResult>): Record<string, ComponentDehydratedState>;
+/**
+ * 服务端组件管理器装饰器
+ */
+declare function ServerComponent(options: {
+    name: string;
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+    onInit?: ServerLifecycleHook;
+    onCleanup?: ServerLifecycleHook;
+}): (target: any) => void;
 
 /**
  * @lytjs/ssr - 组件级水合提示
@@ -369,4 +609,4 @@ declare function serializeHydrationState(state: unknown): string;
  */
 declare function createDehydratedState(vnode: VNode, initialState?: Record<string, unknown>): string;
 
-export { type DataPrefetchContext, type EnhancedStreamRenderOptions, type HydrationHints, type HydrationState, type HydrationStrategy, type PrefetchResult, type PrefetchableComponent, type SSGOptions, type SSGPage, type StreamRenderOptions, VirtualList, createDehydratedState, createHydrationMarkers, _default as default, generateRouteManifest, generateStaticPages, getHydrationStrategy, renderToHtml, renderToStream, renderToStreamAsync, renderToStreamEnhanced, renderToString, resetComponentIdCounter, serializeHydrationState, validatePages, writeStaticFiles };
+export { type ComponentDehydratedState, type DataPrefetchContext, type EnhancedStreamRenderOptions, type HydrationHints, type HydrationState, type HydrationStrategy, type PrefetchResult, type PrefetchableComponent, type SSGOptions, type SSGPage, ServerComponent, type ServerComponentContext, type ServerComponentRegistration, type ServerLifecycleHook, type StreamRenderOptions, VirtualList, buildDehydratedState, clearISRCache, collectPrefetchComponents, createDehydratedState, createHydrationMarkers, createISRMiddleware, _default as default, generateRouteManifest, generateStaticPages, getHydrationStrategy, getISRCacheStats, prefetchAllComponents, registerServerComponent, renderToHtml, renderToStream, renderToStreamAsync, renderToStreamEnhanced, renderToString, resetComponentIdCounter, revalidateOnDemand, safeDeserializeState, safeSerializeState, serializeHydrationState, stateManager, unregisterServerComponent, validatePages, writeStaticFiles };

package/dist/index.d.ts

@@ -49,6 +49,16 @@ interface StreamRenderOptions {
     onShellReady?: () => void;
     /** 错误回调 */
     onError?: (error: Error) => void;
+    /** 流式渲染超时时间（毫秒），默认 30000 */
+    timeout?: number;
+    /** 当渲染超时时的回退 HTML 内容 */
+    fallbackHtml?: string;
+    /** 流控制：每秒最大字节数，用于防止突发流量 */
+    maxBytesPerSecond?: number;
+    /** 是否启用错误恢复模式，默认 true */
+    errorRecovery?: boolean;
+    /** 单个组件渲染超时（毫秒），默认 5000 */
+    componentTimeout?: number;
 }
 /** 异步数据预取上下文 */
 interface DataPrefetchContext {
@@ -90,6 +100,8 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
  * - 支持 Suspense 边界（先发送 shell，再发送异步内容）
  * - 使用 TextEncoder 编码为 Uint8Array
  * - 可配置分块大小和回调
+ * - 超时控制和错误恢复
+ * - 流速率控制
  *
  * @param vnode - 要渲染的 VNode
  * @param options - 流式渲染配置选项
@@ -101,6 +113,7 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
  *   chunkSize: 2048,
  *   onShellReady: () => console.log('Shell 已发送'),
  *   onError: (err) => console.error(err),
+ *   timeout: 30000,
  * });
  *
  * for await (const chunk of stream) {
@@ -182,6 +195,15 @@ interface SSGOptions {
     globalScripts?: string[];
     /** 全局额外样式 */
     globalStyles?: string[];
+    /** ISR 配置（增量静态再生成） */
+    isr?: {
+        /** 重新验证间隔（秒），0 表示按需重新验证 */
+        revalidate?: number;
+        /** 是否启用增量静态再生成 */
+        enabled?: boolean;
+        /** 预渲染 fallback 页面 */
+        fallback?: 'blocking' | boolean;
+    };
 }
 /**
  * 将生成的 HTML 写入文件系统
@@ -263,6 +285,224 @@ declare function generateRouteManifest(pages: SSGPage[], baseUrl?: string): Arra
  * @returns 错误信息数组，空数组表示全部合法
  */
 declare function validatePages(pages: SSGPage[]): string[];
+/**
+ * 创建 ISR 中间件
+ *
+ * @description
+ * 创建用于 Express/Fastify 等框架的 ISR 中间件，
+ * 支持增量静态再生成和背景重新验证。
+ *
+ * @param options - ISR 选项
+ * @returns 中间件函数
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createISRMiddleware, generateStaticPages } from '@lytjs/ssr';
+ *
+ * const app = express();
+ *
+ * // 预生成的页面
+ * const pages = [
+ *   { path: '/', component: homeComponent },
+ * ];
+ *
+ * const staticPages = generateStaticPages(pages);
+ *
+ * app.use(createISRMiddleware({
+ *   staticPages,
+ *   revalidate: 60, // 60秒后重新验证
+ *   async regenerate(path) {
+ *     const page = pages.find(p => p.path === path);
+ *     if (page) {
+ *       return generateStaticPages([page]).get('/index.html')!;
+ *     }
+ *     throw new Error('Page not found');
+ *   }
+ * }));
+ * ```
+ */
+declare function createISRMiddleware(options: {
+    /** 预生成的静态页面 */
+    staticPages: Map<string, string>;
+    /** 重新验证间隔（秒） */
+    revalidate?: number;
+    /** 是否启用 ISR */
+    enabled?: boolean;
+    /** 重新生成页面的函数 */
+    regenerate?: (path: string) => Promise<string>;
+}): (req: any, res: any, next: any) => Promise<any>;
+/**
+ * 触发按需重新验证
+ *
+ * @description
+ * 手动触发特定路径的重新验证，适合于内容更新后调用。
+ *
+ * @param path - 要重新验证的路径
+ * @param regenerate - 重新生成页面的函数
+ * @returns Promise<string> 新生成的 HTML
+ *
+ * @example
+ * ```typescript
+ * // 当博客文章更新时
+ * await revalidateOnDemand(
+ *   '/blog/my-post',
+ *   async () => generatePostHTML('my-post')
+ * );
+ * ```
+ */
+declare function revalidateOnDemand(path: string, regenerate: () => Promise<string>): Promise<string>;
+/**
+ * 获取 ISR 缓存统计信息
+ *
+ * @description
+ * 获取当前 ISR 缓存的统计信息，用于监控和调试。
+ *
+ * @returns 缓存统计信息
+ */
+declare function getISRCacheStats(): {
+    total: number;
+    paths: string[];
+};
+/**
+ * 清除 ISR 缓存
+ *
+ * @description
+ * 清除指定路径或所有过期的缓存。
+ *
+ * @param path - 可选，要清除的特定路径
+ * @param maxAge - 可选，清除超过指定秒数的缓存
+ */
+declare function clearISRCache(path?: string, maxAge?: number): void;
+
+/**
+ * @lytjs/ssr - 服务端组件完善
+ *
+ * 提供服务端组件生命周期管理、数据预取优化、状态序列化等功能
+ */
+
+/** 服务端组件生命周期钩子类型 */
+type ServerLifecycleHook = (context: ServerComponentContext) => Promise<void> | void;
+/** 服务端组件上下文 */
+interface ServerComponentContext {
+    /** 组件唯一 ID */
+    componentId: string;
+    /** 路由信息 */
+    route?: {
+        path: string;
+        params: Record<string, string>;
+        query: Record<string, string>;
+    };
+    /** 请求上下文 */
+    request?: {
+        headers: Record<string, string | undefined>;
+        cookies: Record<string, string>;
+    };
+}
+/** 服务端组件注册信息 */
+interface ServerComponentRegistration {
+    /** 组件名称 */
+    name: string;
+    /** 组件渲染函数 */
+    render: () => VNode;
+    /** 服务端初始化钩子 */
+    onServerInit?: ServerLifecycleHook;
+    /** 数据预取钩子 */
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+    /** 服务端清理钩子 */
+    onServerCleanup?: ServerLifecycleHook;
+}
+/** 服务端组件状态管理器 */
+declare class ServerComponentStateManager {
+    /** 注册的组件 */
+    private registrations;
+    /** 正在执行的预取请求 */
+    private pendingPrefetches;
+    /** 组件初始化状态 */
+    private initializationStates;
+    /**
+     * 注册服务端组件
+     */
+    register(name: string, registration: ServerComponentRegistration): void;
+    /**
+     * 取消注册服务端组件
+     */
+    unregister(name: string): void;
+    /**
+     * 获取已注册的组件
+     */
+    getRegistration(name: string): ServerComponentRegistration | undefined;
+    /**
+     * 初始化服务端组件
+     */
+    initializeComponent(name: string, context: ServerComponentContext): Promise<void>;
+    /**
+     * 清理服务端组件
+     */
+    cleanupComponent(name: string, context: ServerComponentContext): Promise<void>;
+    /**
+     * 预取组件数据（带缓存）
+     */
+    prefetchComponentData(name: string, context: DataPrefetchContext, cacheKey?: string): Promise<PrefetchResult>;
+    /**
+     * 清除所有缓存
+     */
+    clearAll(): void;
+}
+/** 全局状态管理器实例 */
+declare const stateManager: ServerComponentStateManager;
+/**
+ * 注册服务端组件
+ */
+declare function registerServerComponent(name: string, registration: ServerComponentRegistration): void;
+/**
+ * 取消注册服务端组件
+ */
+declare function unregisterServerComponent(name: string): void;
+/**
+ * 从 VNode 树中收集需要预取数据的组件
+ */
+declare function collectPrefetchComponents(vnode: VNode | VNode[] | string | number | null | undefined): string[];
+/**
+ * 并发预取多个组件的数据
+ */
+declare function prefetchAllComponents(components: string[], context: DataPrefetchContext): Promise<Record<string, PrefetchResult>>;
+/**
+ * 安全的状态序列化
+ * 处理循环引用、日期、正则表达式等特殊类型
+ */
+declare function safeSerializeState(state: unknown): string;
+/**
+ * 安全的状态反序列化
+ * 恢复特殊类型
+ */
+declare function safeDeserializeState(serialized: string): unknown;
+/**
+ * 创建组件脱水状态
+ */
+interface ComponentDehydratedState {
+    /** 组件名称 */
+    componentName: string;
+    /** 组件 Props */
+    props: Record<string, unknown>;
+    /** 预取的数据 */
+    data?: Record<string, unknown>;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 构建完整的脱水状态
+ */
+declare function buildDehydratedState(prefetchResults: Record<string, PrefetchResult>): Record<string, ComponentDehydratedState>;
+/**
+ * 服务端组件管理器装饰器
+ */
+declare function ServerComponent(options: {
+    name: string;
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+    onInit?: ServerLifecycleHook;
+    onCleanup?: ServerLifecycleHook;
+}): (target: any) => void;
 
 /**
  * @lytjs/ssr - 组件级水合提示
@@ -369,4 +609,4 @@ declare function serializeHydrationState(state: unknown): string;
  */
 declare function createDehydratedState(vnode: VNode, initialState?: Record<string, unknown>): string;
 
-export { type DataPrefetchContext, type EnhancedStreamRenderOptions, type HydrationHints, type HydrationState, type HydrationStrategy, type PrefetchResult, type PrefetchableComponent, type SSGOptions, type SSGPage, type StreamRenderOptions, VirtualList, createDehydratedState, createHydrationMarkers, _default as default, generateRouteManifest, generateStaticPages, getHydrationStrategy, renderToHtml, renderToStream, renderToStreamAsync, renderToStreamEnhanced, renderToString, resetComponentIdCounter, serializeHydrationState, validatePages, writeStaticFiles };
+export { type ComponentDehydratedState, type DataPrefetchContext, type EnhancedStreamRenderOptions, type HydrationHints, type HydrationState, type HydrationStrategy, type PrefetchResult, type PrefetchableComponent, type SSGOptions, type SSGPage, ServerComponent, type ServerComponentContext, type ServerComponentRegistration, type ServerLifecycleHook, type StreamRenderOptions, VirtualList, buildDehydratedState, clearISRCache, collectPrefetchComponents, createDehydratedState, createHydrationMarkers, createISRMiddleware, _default as default, generateRouteManifest, generateStaticPages, getHydrationStrategy, getISRCacheStats, prefetchAllComponents, registerServerComponent, renderToHtml, renderToStream, renderToStreamAsync, renderToStreamEnhanced, renderToString, resetComponentIdCounter, revalidateOnDemand, safeDeserializeState, safeSerializeState, serializeHydrationState, stateManager, unregisterServerComponent, validatePages, writeStaticFiles };