@lytjs/ssr 6.0.0 → 6.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -30,9 +30,6 @@ declare const _default: {
30
30
  *
31
31
  * 高性能大数据列表渲染
32
32
  */
33
- /**
34
- * 虚拟列表组件
35
- */
36
33
  declare const VirtualList: _lytjs_component.ComponentOptions<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>>;
37
34
 
38
35
  /**
@@ -49,6 +46,16 @@ interface StreamRenderOptions {
49
46
  onShellReady?: () => void;
50
47
  /** 错误回调 */
51
48
  onError?: (error: Error) => void;
49
+ /** 流式渲染超时时间(毫秒),默认 30000 */
50
+ timeout?: number;
51
+ /** 当渲染超时时的回退 HTML 内容 */
52
+ fallbackHtml?: string;
53
+ /** 流控制:每秒最大字节数,用于防止突发流量 */
54
+ maxBytesPerSecond?: number;
55
+ /** 是否启用错误恢复模式,默认 true */
56
+ errorRecovery?: boolean;
57
+ /** 单个组件渲染超时(毫秒),默认 5000 */
58
+ componentTimeout?: number;
52
59
  }
53
60
  /** 异步数据预取上下文 */
54
61
  interface DataPrefetchContext {
@@ -62,7 +69,7 @@ interface DataPrefetchContext {
62
69
  /** 异步数据预取结果 */
63
70
  interface PrefetchResult {
64
71
  /** 预取的数据 */
65
- data: Record<string, any>;
72
+ data: Record<string, unknown>;
66
73
  /** 数据过期时间(毫秒) */
67
74
  ttl?: number;
68
75
  }
@@ -76,7 +83,7 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
76
83
  /** 数据预取上下文 */
77
84
  prefetchContext?: DataPrefetchContext;
78
85
  /** 数据预取完成回调 */
79
- onDataPrefetched?: (data: Record<string, any>) => void;
86
+ onDataPrefetched?: (data: Record<string, unknown>) => void;
80
87
  /** 是否启用渐进式水合 */
81
88
  progressiveHydration?: boolean;
82
89
  }
@@ -90,6 +97,8 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
90
97
  * - 支持 Suspense 边界(先发送 shell,再发送异步内容)
91
98
  * - 使用 TextEncoder 编码为 Uint8Array
92
99
  * - 可配置分块大小和回调
100
+ * - 超时控制和错误恢复
101
+ * - 流速率控制
93
102
  *
94
103
  * @param vnode - 要渲染的 VNode
95
104
  * @param options - 流式渲染配置选项
@@ -101,6 +110,7 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
101
110
  * chunkSize: 2048,
102
111
  * onShellReady: () => console.log('Shell 已发送'),
103
112
  * onError: (err) => console.error(err),
113
+ * timeout: 30000,
104
114
  * });
105
115
  *
106
116
  * for await (const chunk of stream) {
@@ -133,7 +143,7 @@ declare function renderToStreamAsync(vnode: VNode, options?: EnhancedStreamRende
133
143
  */
134
144
  declare function renderToStreamEnhanced(vnode: VNode, options?: EnhancedStreamRenderOptions): Promise<{
135
145
  stream: ReadableStream<Uint8Array>;
136
- dehydratedState: Record<string, any>;
146
+ dehydratedState: Record<string, unknown>;
137
147
  }>;
138
148
 
139
149
  /**
@@ -182,6 +192,15 @@ interface SSGOptions {
182
192
  globalScripts?: string[];
183
193
  /** 全局额外样式 */
184
194
  globalStyles?: string[];
195
+ /** ISR 配置(增量静态再生成) */
196
+ isr?: {
197
+ /** 重新验证间隔(秒),0 表示按需重新验证 */
198
+ revalidate?: number;
199
+ /** 是否启用增量静态再生成 */
200
+ enabled?: boolean;
201
+ /** 预渲染 fallback 页面 */
202
+ fallback?: 'blocking' | boolean;
203
+ };
185
204
  }
186
205
  /**
187
206
  * 将生成的 HTML 写入文件系统
@@ -263,6 +282,227 @@ declare function generateRouteManifest(pages: SSGPage[], baseUrl?: string): Arra
263
282
  * @returns 错误信息数组,空数组表示全部合法
264
283
  */
265
284
  declare function validatePages(pages: SSGPage[]): string[];
285
+ /**
286
+ * 创建 ISR 中间件
287
+ *
288
+ * @description
289
+ * 创建用于 Express/Fastify 等框架的 ISR 中间件,
290
+ * 支持增量静态再生成和背景重新验证。
291
+ *
292
+ * @param options - ISR 选项
293
+ * @returns 中间件函数
294
+ *
295
+ * @example
296
+ * ```typescript
297
+ * import express from 'express';
298
+ * import { createISRMiddleware, generateStaticPages } from '@lytjs/ssr';
299
+ *
300
+ * const app = express();
301
+ *
302
+ * // 预生成的页面
303
+ * const pages = [
304
+ * { path: '/', component: homeComponent },
305
+ * ];
306
+ *
307
+ * const staticPages = generateStaticPages(pages);
308
+ *
309
+ * app.use(createISRMiddleware({
310
+ * staticPages,
311
+ * revalidate: 60, // 60秒后重新验证
312
+ * async regenerate(path) {
313
+ * const page = pages.find(p => p.path === path);
314
+ * if (page) {
315
+ * return generateStaticPages([page]).get('/index.html')!;
316
+ * }
317
+ * throw new Error('Page not found');
318
+ * }
319
+ * }));
320
+ * ```
321
+ */
322
+ declare function createISRMiddleware(options: {
323
+ /** 预生成的静态页面 */
324
+ staticPages: Map<string, string>;
325
+ /** 重新验证间隔(秒) */
326
+ revalidate?: number;
327
+ /** 是否启用 ISR */
328
+ enabled?: boolean;
329
+ /** 重新生成页面的函数 */
330
+ regenerate?: (path: string) => Promise<string>;
331
+ }): (req: any, res: any, next: any) => Promise<any>;
332
+ /**
333
+ * 触发按需重新验证
334
+ *
335
+ * @description
336
+ * 手动触发特定路径的重新验证,适合于内容更新后调用。
337
+ *
338
+ * @param path - 要重新验证的路径
339
+ * @param regenerate - 重新生成页面的函数
340
+ * @returns Promise<string> 新生成的 HTML
341
+ *
342
+ * @example
343
+ * ```typescript
344
+ * // 当博客文章更新时
345
+ * await revalidateOnDemand(
346
+ * '/blog/my-post',
347
+ * async () => generatePostHTML('my-post')
348
+ * );
349
+ * ```
350
+ */
351
+ declare function revalidateOnDemand(path: string, regenerate: () => Promise<string>): Promise<string>;
352
+ /**
353
+ * 获取 ISR 缓存统计信息
354
+ *
355
+ * @description
356
+ * 获取当前 ISR 缓存的统计信息,用于监控和调试。
357
+ *
358
+ * @returns 缓存统计信息
359
+ */
360
+ declare function getISRCacheStats(): {
361
+ total: number;
362
+ paths: string[];
363
+ };
364
+ /**
365
+ * 清除 ISR 缓存
366
+ *
367
+ * @description
368
+ * 清除指定路径或所有过期的缓存。
369
+ *
370
+ * @param path - 可选,要清除的特定路径
371
+ * @param maxAge - 可选,清除超过指定秒数的缓存
372
+ */
373
+ declare function clearISRCache(path?: string, maxAge?: number): void;
374
+
375
+ /**
376
+ * @lytjs/ssr - 服务端组件完善
377
+ *
378
+ * 提供服务端组件生命周期管理、数据预取优化、状态序列化等功能
379
+ */
380
+
381
+ /** 服务端组件生命周期钩子类型 */
382
+ type ServerLifecycleHook = (context: ServerComponentContext) => Promise<void> | void;
383
+ /** 服务端组件上下文 */
384
+ interface ServerComponentContext {
385
+ /** 组件唯一 ID */
386
+ componentId: string;
387
+ /** 路由信息 */
388
+ route?: {
389
+ path: string;
390
+ params: Record<string, string>;
391
+ query: Record<string, string>;
392
+ };
393
+ /** 请求上下文 */
394
+ request?: {
395
+ headers: Record<string, string | undefined>;
396
+ cookies: Record<string, string>;
397
+ };
398
+ }
399
+ /** 服务端组件注册信息 */
400
+ interface ServerComponentRegistration {
401
+ /** 组件名称 */
402
+ name: string;
403
+ /** 组件渲染函数 */
404
+ render: () => VNode;
405
+ /** 服务端初始化钩子 */
406
+ onServerInit?: ServerLifecycleHook;
407
+ /** 数据预取钩子 */
408
+ prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
409
+ /** 服务端清理钩子 */
410
+ onServerCleanup?: ServerLifecycleHook;
411
+ }
412
+ /** 服务端组件状态管理器 */
413
+ declare class ServerComponentStateManager {
414
+ /** 注册的组件 */
415
+ private registrations;
416
+ /** 正在执行的预取请求 */
417
+ private pendingPrefetches;
418
+ /** 组件初始化状态 */
419
+ private initializationStates;
420
+ /**
421
+ * 注册服务端组件
422
+ */
423
+ register(name: string, registration: ServerComponentRegistration): void;
424
+ /**
425
+ * 取消注册服务端组件
426
+ */
427
+ unregister(name: string): void;
428
+ /**
429
+ * 获取已注册的组件
430
+ */
431
+ getRegistration(name: string): ServerComponentRegistration | undefined;
432
+ /**
433
+ * 初始化服务端组件
434
+ */
435
+ initializeComponent(name: string, context: ServerComponentContext): Promise<void>;
436
+ /**
437
+ * 清理服务端组件
438
+ */
439
+ cleanupComponent(name: string, context: ServerComponentContext): Promise<void>;
440
+ /**
441
+ * 预取组件数据(带缓存)
442
+ */
443
+ prefetchComponentData(name: string, context: DataPrefetchContext, cacheKey?: string): Promise<PrefetchResult>;
444
+ /**
445
+ * 清除所有缓存
446
+ */
447
+ clearAll(): void;
448
+ }
449
+ /** 全局状态管理器实例 */
450
+ declare const stateManager: ServerComponentStateManager;
451
+ /**
452
+ * 注册服务端组件
453
+ */
454
+ declare function registerServerComponent(name: string, registration: ServerComponentRegistration): void;
455
+ /**
456
+ * 取消注册服务端组件
457
+ */
458
+ declare function unregisterServerComponent(name: string): void;
459
+ /**
460
+ * 从 VNode 树中收集需要预取数据的组件
461
+ */
462
+ declare function collectPrefetchComponents(vnode: VNode | VNode[] | string | number | null | undefined): string[];
463
+ /**
464
+ * 并发预取多个组件的数据
465
+ */
466
+ declare function prefetchAllComponents(components: string[], context: DataPrefetchContext): Promise<Record<string, PrefetchResult>>;
467
+ /**
468
+ * 安全的状态序列化
469
+ * 处理循环引用、日期、正则表达式等特殊类型
470
+ */
471
+ declare function safeSerializeState(state: unknown): string;
472
+ /**
473
+ * 安全的状态反序列化
474
+ * 恢复特殊类型
475
+ */
476
+ declare function safeDeserializeState(serialized: string): unknown;
477
+ /**
478
+ * 创建组件脱水状态
479
+ */
480
+ interface ComponentDehydratedState {
481
+ /** 组件名称 */
482
+ componentName: string;
483
+ /** 组件 Props */
484
+ props: Record<string, unknown>;
485
+ /** 预取的数据 */
486
+ data?: Record<string, unknown>;
487
+ /** 错误信息 */
488
+ error?: string;
489
+ }
490
+ /**
491
+ * 构建完整的脱水状态
492
+ */
493
+ declare function buildDehydratedState(prefetchResults: Record<string, PrefetchResult>): Record<string, ComponentDehydratedState>;
494
+ /**
495
+ * 服务端组件管理器装饰器
496
+ */
497
+ declare function ServerComponent(options: {
498
+ name: string;
499
+ prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
500
+ onInit?: ServerLifecycleHook;
501
+ onCleanup?: ServerLifecycleHook;
502
+ }): (target: {
503
+ name?: string;
504
+ render?: () => VNode;
505
+ }) => void;
266
506
 
267
507
  /**
268
508
  * @lytjs/ssr - 组件级水合提示
@@ -369,4 +609,4 @@ declare function serializeHydrationState(state: unknown): string;
369
609
  */
370
610
  declare function createDehydratedState(vnode: VNode, initialState?: Record<string, unknown>): string;
371
611
 
372
- 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 };
612
+ 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 CHANGED
@@ -30,9 +30,6 @@ declare const _default: {
30
30
  *
31
31
  * 高性能大数据列表渲染
32
32
  */
33
- /**
34
- * 虚拟列表组件
35
- */
36
33
  declare const VirtualList: _lytjs_component.ComponentOptions<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>>;
37
34
 
38
35
  /**
@@ -49,6 +46,16 @@ interface StreamRenderOptions {
49
46
  onShellReady?: () => void;
50
47
  /** 错误回调 */
51
48
  onError?: (error: Error) => void;
49
+ /** 流式渲染超时时间(毫秒),默认 30000 */
50
+ timeout?: number;
51
+ /** 当渲染超时时的回退 HTML 内容 */
52
+ fallbackHtml?: string;
53
+ /** 流控制:每秒最大字节数,用于防止突发流量 */
54
+ maxBytesPerSecond?: number;
55
+ /** 是否启用错误恢复模式,默认 true */
56
+ errorRecovery?: boolean;
57
+ /** 单个组件渲染超时(毫秒),默认 5000 */
58
+ componentTimeout?: number;
52
59
  }
53
60
  /** 异步数据预取上下文 */
54
61
  interface DataPrefetchContext {
@@ -62,7 +69,7 @@ interface DataPrefetchContext {
62
69
  /** 异步数据预取结果 */
63
70
  interface PrefetchResult {
64
71
  /** 预取的数据 */
65
- data: Record<string, any>;
72
+ data: Record<string, unknown>;
66
73
  /** 数据过期时间(毫秒) */
67
74
  ttl?: number;
68
75
  }
@@ -76,7 +83,7 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
76
83
  /** 数据预取上下文 */
77
84
  prefetchContext?: DataPrefetchContext;
78
85
  /** 数据预取完成回调 */
79
- onDataPrefetched?: (data: Record<string, any>) => void;
86
+ onDataPrefetched?: (data: Record<string, unknown>) => void;
80
87
  /** 是否启用渐进式水合 */
81
88
  progressiveHydration?: boolean;
82
89
  }
@@ -90,6 +97,8 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
90
97
  * - 支持 Suspense 边界(先发送 shell,再发送异步内容)
91
98
  * - 使用 TextEncoder 编码为 Uint8Array
92
99
  * - 可配置分块大小和回调
100
+ * - 超时控制和错误恢复
101
+ * - 流速率控制
93
102
  *
94
103
  * @param vnode - 要渲染的 VNode
95
104
  * @param options - 流式渲染配置选项
@@ -101,6 +110,7 @@ interface EnhancedStreamRenderOptions extends StreamRenderOptions {
101
110
  * chunkSize: 2048,
102
111
  * onShellReady: () => console.log('Shell 已发送'),
103
112
  * onError: (err) => console.error(err),
113
+ * timeout: 30000,
104
114
  * });
105
115
  *
106
116
  * for await (const chunk of stream) {
@@ -133,7 +143,7 @@ declare function renderToStreamAsync(vnode: VNode, options?: EnhancedStreamRende
133
143
  */
134
144
  declare function renderToStreamEnhanced(vnode: VNode, options?: EnhancedStreamRenderOptions): Promise<{
135
145
  stream: ReadableStream<Uint8Array>;
136
- dehydratedState: Record<string, any>;
146
+ dehydratedState: Record<string, unknown>;
137
147
  }>;
138
148
 
139
149
  /**
@@ -182,6 +192,15 @@ interface SSGOptions {
182
192
  globalScripts?: string[];
183
193
  /** 全局额外样式 */
184
194
  globalStyles?: string[];
195
+ /** ISR 配置(增量静态再生成) */
196
+ isr?: {
197
+ /** 重新验证间隔(秒),0 表示按需重新验证 */
198
+ revalidate?: number;
199
+ /** 是否启用增量静态再生成 */
200
+ enabled?: boolean;
201
+ /** 预渲染 fallback 页面 */
202
+ fallback?: 'blocking' | boolean;
203
+ };
185
204
  }
186
205
  /**
187
206
  * 将生成的 HTML 写入文件系统
@@ -263,6 +282,227 @@ declare function generateRouteManifest(pages: SSGPage[], baseUrl?: string): Arra
263
282
  * @returns 错误信息数组,空数组表示全部合法
264
283
  */
265
284
  declare function validatePages(pages: SSGPage[]): string[];
285
+ /**
286
+ * 创建 ISR 中间件
287
+ *
288
+ * @description
289
+ * 创建用于 Express/Fastify 等框架的 ISR 中间件,
290
+ * 支持增量静态再生成和背景重新验证。
291
+ *
292
+ * @param options - ISR 选项
293
+ * @returns 中间件函数
294
+ *
295
+ * @example
296
+ * ```typescript
297
+ * import express from 'express';
298
+ * import { createISRMiddleware, generateStaticPages } from '@lytjs/ssr';
299
+ *
300
+ * const app = express();
301
+ *
302
+ * // 预生成的页面
303
+ * const pages = [
304
+ * { path: '/', component: homeComponent },
305
+ * ];
306
+ *
307
+ * const staticPages = generateStaticPages(pages);
308
+ *
309
+ * app.use(createISRMiddleware({
310
+ * staticPages,
311
+ * revalidate: 60, // 60秒后重新验证
312
+ * async regenerate(path) {
313
+ * const page = pages.find(p => p.path === path);
314
+ * if (page) {
315
+ * return generateStaticPages([page]).get('/index.html')!;
316
+ * }
317
+ * throw new Error('Page not found');
318
+ * }
319
+ * }));
320
+ * ```
321
+ */
322
+ declare function createISRMiddleware(options: {
323
+ /** 预生成的静态页面 */
324
+ staticPages: Map<string, string>;
325
+ /** 重新验证间隔(秒) */
326
+ revalidate?: number;
327
+ /** 是否启用 ISR */
328
+ enabled?: boolean;
329
+ /** 重新生成页面的函数 */
330
+ regenerate?: (path: string) => Promise<string>;
331
+ }): (req: any, res: any, next: any) => Promise<any>;
332
+ /**
333
+ * 触发按需重新验证
334
+ *
335
+ * @description
336
+ * 手动触发特定路径的重新验证,适合于内容更新后调用。
337
+ *
338
+ * @param path - 要重新验证的路径
339
+ * @param regenerate - 重新生成页面的函数
340
+ * @returns Promise<string> 新生成的 HTML
341
+ *
342
+ * @example
343
+ * ```typescript
344
+ * // 当博客文章更新时
345
+ * await revalidateOnDemand(
346
+ * '/blog/my-post',
347
+ * async () => generatePostHTML('my-post')
348
+ * );
349
+ * ```
350
+ */
351
+ declare function revalidateOnDemand(path: string, regenerate: () => Promise<string>): Promise<string>;
352
+ /**
353
+ * 获取 ISR 缓存统计信息
354
+ *
355
+ * @description
356
+ * 获取当前 ISR 缓存的统计信息,用于监控和调试。
357
+ *
358
+ * @returns 缓存统计信息
359
+ */
360
+ declare function getISRCacheStats(): {
361
+ total: number;
362
+ paths: string[];
363
+ };
364
+ /**
365
+ * 清除 ISR 缓存
366
+ *
367
+ * @description
368
+ * 清除指定路径或所有过期的缓存。
369
+ *
370
+ * @param path - 可选,要清除的特定路径
371
+ * @param maxAge - 可选,清除超过指定秒数的缓存
372
+ */
373
+ declare function clearISRCache(path?: string, maxAge?: number): void;
374
+
375
+ /**
376
+ * @lytjs/ssr - 服务端组件完善
377
+ *
378
+ * 提供服务端组件生命周期管理、数据预取优化、状态序列化等功能
379
+ */
380
+
381
+ /** 服务端组件生命周期钩子类型 */
382
+ type ServerLifecycleHook = (context: ServerComponentContext) => Promise<void> | void;
383
+ /** 服务端组件上下文 */
384
+ interface ServerComponentContext {
385
+ /** 组件唯一 ID */
386
+ componentId: string;
387
+ /** 路由信息 */
388
+ route?: {
389
+ path: string;
390
+ params: Record<string, string>;
391
+ query: Record<string, string>;
392
+ };
393
+ /** 请求上下文 */
394
+ request?: {
395
+ headers: Record<string, string | undefined>;
396
+ cookies: Record<string, string>;
397
+ };
398
+ }
399
+ /** 服务端组件注册信息 */
400
+ interface ServerComponentRegistration {
401
+ /** 组件名称 */
402
+ name: string;
403
+ /** 组件渲染函数 */
404
+ render: () => VNode;
405
+ /** 服务端初始化钩子 */
406
+ onServerInit?: ServerLifecycleHook;
407
+ /** 数据预取钩子 */
408
+ prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
409
+ /** 服务端清理钩子 */
410
+ onServerCleanup?: ServerLifecycleHook;
411
+ }
412
+ /** 服务端组件状态管理器 */
413
+ declare class ServerComponentStateManager {
414
+ /** 注册的组件 */
415
+ private registrations;
416
+ /** 正在执行的预取请求 */
417
+ private pendingPrefetches;
418
+ /** 组件初始化状态 */
419
+ private initializationStates;
420
+ /**
421
+ * 注册服务端组件
422
+ */
423
+ register(name: string, registration: ServerComponentRegistration): void;
424
+ /**
425
+ * 取消注册服务端组件
426
+ */
427
+ unregister(name: string): void;
428
+ /**
429
+ * 获取已注册的组件
430
+ */
431
+ getRegistration(name: string): ServerComponentRegistration | undefined;
432
+ /**
433
+ * 初始化服务端组件
434
+ */
435
+ initializeComponent(name: string, context: ServerComponentContext): Promise<void>;
436
+ /**
437
+ * 清理服务端组件
438
+ */
439
+ cleanupComponent(name: string, context: ServerComponentContext): Promise<void>;
440
+ /**
441
+ * 预取组件数据(带缓存)
442
+ */
443
+ prefetchComponentData(name: string, context: DataPrefetchContext, cacheKey?: string): Promise<PrefetchResult>;
444
+ /**
445
+ * 清除所有缓存
446
+ */
447
+ clearAll(): void;
448
+ }
449
+ /** 全局状态管理器实例 */
450
+ declare const stateManager: ServerComponentStateManager;
451
+ /**
452
+ * 注册服务端组件
453
+ */
454
+ declare function registerServerComponent(name: string, registration: ServerComponentRegistration): void;
455
+ /**
456
+ * 取消注册服务端组件
457
+ */
458
+ declare function unregisterServerComponent(name: string): void;
459
+ /**
460
+ * 从 VNode 树中收集需要预取数据的组件
461
+ */
462
+ declare function collectPrefetchComponents(vnode: VNode | VNode[] | string | number | null | undefined): string[];
463
+ /**
464
+ * 并发预取多个组件的数据
465
+ */
466
+ declare function prefetchAllComponents(components: string[], context: DataPrefetchContext): Promise<Record<string, PrefetchResult>>;
467
+ /**
468
+ * 安全的状态序列化
469
+ * 处理循环引用、日期、正则表达式等特殊类型
470
+ */
471
+ declare function safeSerializeState(state: unknown): string;
472
+ /**
473
+ * 安全的状态反序列化
474
+ * 恢复特殊类型
475
+ */
476
+ declare function safeDeserializeState(serialized: string): unknown;
477
+ /**
478
+ * 创建组件脱水状态
479
+ */
480
+ interface ComponentDehydratedState {
481
+ /** 组件名称 */
482
+ componentName: string;
483
+ /** 组件 Props */
484
+ props: Record<string, unknown>;
485
+ /** 预取的数据 */
486
+ data?: Record<string, unknown>;
487
+ /** 错误信息 */
488
+ error?: string;
489
+ }
490
+ /**
491
+ * 构建完整的脱水状态
492
+ */
493
+ declare function buildDehydratedState(prefetchResults: Record<string, PrefetchResult>): Record<string, ComponentDehydratedState>;
494
+ /**
495
+ * 服务端组件管理器装饰器
496
+ */
497
+ declare function ServerComponent(options: {
498
+ name: string;
499
+ prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
500
+ onInit?: ServerLifecycleHook;
501
+ onCleanup?: ServerLifecycleHook;
502
+ }): (target: {
503
+ name?: string;
504
+ render?: () => VNode;
505
+ }) => void;
266
506
 
267
507
  /**
268
508
  * @lytjs/ssr - 组件级水合提示
@@ -369,4 +609,4 @@ declare function serializeHydrationState(state: unknown): string;
369
609
  */
370
610
  declare function createDehydratedState(vnode: VNode, initialState?: Record<string, unknown>): string;
371
611
 
372
- 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 };
612
+ 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 };