@lytjs/ssr 6.0.0

package/dist/index.d.ts

@@ -0,0 +1,372 @@
+import { VNode } from '@lytjs/vdom';
+import * as _lytjs_component from '@lytjs/component';
+
+/**
+ * @lytjs/ssr - 服务端渲染
+ *
+ * 将 VNode 渲染为 HTML 字符串
+ */
+
+/**
+ * 渲染 VNode 为 HTML 字符串
+ */
+declare function renderToString(vnode: VNode | VNode[] | string | number | null | undefined): string;
+/**
+ * 渲染完整的 HTML 页面
+ */
+declare function renderToHtml(vnode: VNode | VNode[], options?: {
+    title?: string;
+    lang?: string;
+    head?: string;
+    bodyAttrs?: Record<string, string>;
+}): string;
+declare const _default: {
+    renderToString: typeof renderToString;
+    renderToHtml: typeof renderToHtml;
+};
+
+/**
+ * @lytjs/ssr - 虚拟列表组件
+ *
+ * 高性能大数据列表渲染
+ */
+/**
+ * 虚拟列表组件
+ */
+declare const VirtualList: _lytjs_component.ComponentOptions<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>>;
+
+/**
+ * @lytjs/ssr - 流式服务端渲染
+ *
+ * 将 VNode 渲染为 ReadableStream，支持分块发送和 Suspense 边界
+ */
+
+/** 流式渲染配置选项 */
+interface StreamRenderOptions {
+    /** 每个分块的最大字节数，默认 4096 */
+    chunkSize?: number;
+    /** Shell 就绪回调（Suspense 边界之前的初始内容已发送） */
+    onShellReady?: () => void;
+    /** 错误回调 */
+    onError?: (error: Error) => void;
+}
+/** 异步数据预取上下文 */
+interface DataPrefetchContext {
+    /** 路由路径 */
+    path?: string;
+    /** 路由参数 */
+    params?: Record<string, string>;
+    /** 查询参数 */
+    query?: Record<string, string>;
+}
+/** 异步数据预取结果 */
+interface PrefetchResult {
+    /** 预取的数据 */
+    data: Record<string, any>;
+    /** 数据过期时间（毫秒） */
+    ttl?: number;
+}
+/** 支持数据预取的组件接口 */
+interface PrefetchableComponent {
+    /** 预取数据方法 */
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+}
+/** 流式渲染增强选项 */
+interface EnhancedStreamRenderOptions extends StreamRenderOptions {
+    /** 数据预取上下文 */
+    prefetchContext?: DataPrefetchContext;
+    /** 数据预取完成回调 */
+    onDataPrefetched?: (data: Record<string, any>) => void;
+    /** 是否启用渐进式水合 */
+    progressiveHydration?: boolean;
+}
+/**
+ * 将 VNode 渲染为 ReadableStream（流式服务端渲染）
+ *
+ * @description
+ * 将 VNode 树渲染为 HTML 并通过 ReadableStream 分块发送。
+ * 支持以下特性：
+ * - 按组件边界拆分 HTML 分块
+ * - 支持 Suspense 边界（先发送 shell，再发送异步内容）
+ * - 使用 TextEncoder 编码为 Uint8Array
+ * - 可配置分块大小和回调
+ *
+ * @param vnode - 要渲染的 VNode
+ * @param options - 流式渲染配置选项
+ * @returns ReadableStream<Uint8Array>
+ *
+ * @example
+ * ```typescript
+ * const stream = renderToStream(vnode, {
+ *   chunkSize: 2048,
+ *   onShellReady: () => console.log('Shell 已发送'),
+ *   onError: (err) => console.error(err),
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   response.write(chunk);
+ * }
+ * ```
+ */
+declare function renderToStream(vnode: VNode, options?: StreamRenderOptions): ReadableStream<Uint8Array>;
+/**
+ * 将 VNode 渲染为异步 ReadableStream（支持异步组件和数据预取）
+ *
+ * @description
+ * 与 renderToStream 类似，但支持异步组件和数据预取。
+ * 遇到返回 Promise 的组件时先发送占位内容，等 Promise 解析后再发送实际内容。
+ *
+ * @param vnode - 要渲染的 VNode
+ * @param options - 流式渲染配置选项
+ * @returns ReadableStream<Uint8Array>
+ */
+declare function renderToStreamAsync(vnode: VNode, options?: EnhancedStreamRenderOptions): ReadableStream<Uint8Array>;
+/**
+ * 增强型流式渲染（包含数据预取和渐进式水合）
+ *
+ * @description
+ * 完整的流式渲染解决方案，包含数据预取、渐进式水合等高级特性。
+ *
+ * @param vnode - 要渲染的 VNode
+ * @param options - 增强型流式渲染配置
+ * @returns Promise<{ stream: ReadableStream<Uint8Array>; dehydratedState: Record<string, any> }>
+ */
+declare function renderToStreamEnhanced(vnode: VNode, options?: EnhancedStreamRenderOptions): Promise<{
+    stream: ReadableStream<Uint8Array>;
+    dehydratedState: Record<string, any>;
+}>;
+
+/**
+ * @lytjs/ssr - 静态站点生成（SSG）
+ *
+ * 预渲染页面配置为静态 HTML 文件
+ */
+
+/** SSG 页面配置 */
+interface SSGPage {
+    /** 页面路径，如 '/' 或 '/about' */
+    path: string;
+    /** 页面组件 VNode */
+    component: VNode;
+    /** 可选布局组件 */
+    layout?: VNode;
+    /** 页面头部信息 */
+    head?: {
+        /** 页面标题 */
+        title?: string;
+        /** 元信息键值对 */
+        meta?: Record<string, string>;
+    };
+    /** 额外的脚本标签 */
+    scripts?: string[];
+    /** 额外的样式标签 */
+    styles?: string[];
+}
+/** SSG 生成选项 */
+interface SSGOptions {
+    /** 站点基础 URL，默认 '/' */
+    baseUrl?: string;
+    /** 输出目录，默认 'dist' */
+    outDir?: string;
+    /** 默认页面标题 */
+    defaultTitle?: string;
+    /** 默认语言 */
+    lang?: string;
+    /** 是否生成 sitemap */
+    generateSitemap?: boolean;
+    /** 站点名称（用于 sitemap） */
+    siteName?: string;
+    /** 是否使用哈希路由 */
+    hashMode?: boolean;
+    /** 全局额外脚本 */
+    globalScripts?: string[];
+    /** 全局额外样式 */
+    globalStyles?: string[];
+}
+/**
+ * 将生成的 HTML 写入文件系统
+ *
+ * @description
+ * 将 generateStaticPages 生成的结果写入到指定的输出目录。
+ * 会自动创建所需的目录结构。
+ *
+ * @param pages - 页面配置数组
+ * @param options - SSG 选项
+ * @returns Promise<void>
+ *
+ * @example
+ * ```typescript
+ * await writeStaticFiles(pages, { outDir: 'build' });
+ * ```
+ */
+declare function writeStaticFiles(pages: SSGPage[], options?: SSGOptions): Promise<void>;
+/**
+ * 预渲染页面配置数组为静态 HTML
+ *
+ * @description
+ * 接受页面配置数组，为每个页面生成完整的 HTML 内容。
+ * 返回一个 Map，键为文件路径，值为 HTML 内容。
+ *
+ * @param pages - 页面配置数组
+ * @param options - SSG 生成选项
+ * @returns Map<string, string> 文件路径 -> HTML 内容
+ *
+ * @example
+ * ```typescript
+ * const pages: SSGPage[] = [
+ *   {
+ *     path: '/',
+ *     component: h('div', {}, 'Home'),
+ *     head: { title: '首页', meta: { description: '欢迎' } },
+ *   },
+ *   {
+ *     path: '/about',
+ *     component: h('div', {}, 'About'),
+ *   },
+ * ];
+ *
+ * const results = generateStaticPages(pages, {
+ *   baseUrl: 'https://example.com',
+ *   defaultTitle: 'My Site',
+ * });
+ *
+ * for (const [filePath, html] of results) {
+ *   console.log(filePath, html);
+ * }
+ * ```
+ */
+declare function generateStaticPages(pages: SSGPage[], options?: SSGOptions): Map<string, string>;
+/**
+ * 生成页面路由清单
+ *
+ * @description
+ * 根据页面配置生成一个 JSON 格式的路由清单，
+ * 可用于客户端路由注册或构建分析。
+ *
+ * @param pages - 页面配置数组
+ * @param baseUrl - 站点基础 URL
+ * @returns 路由信息数组
+ */
+declare function generateRouteManifest(pages: SSGPage[], baseUrl?: string): Array<{
+    path: string;
+    filePath: string;
+    title?: string;
+}>;
+/**
+ * 验证页面配置数组的合法性
+ *
+ * @description
+ * 检查每个页面配置是否包含必要的字段（path 和 component），
+ * 以及路径是否合法。返回错误信息数组。
+ *
+ * @param pages - 页面配置数组
+ * @returns 错误信息数组，空数组表示全部合法
+ */
+declare function validatePages(pages: SSGPage[]): string[];
+
+/**
+ * @lytjs/ssr - 组件级水合提示
+ *
+ * 提供水合标记、策略检测和状态序列化等辅助函数，
+ * 用于 SSR 输出中嵌入客户端水合所需的信息
+ */
+
+/** 水合策略类型 */
+type HydrationStrategy = 'lazy' | 'eager' | 'idle';
+/** 水合提示信息 */
+interface HydrationHints {
+    /** 组件唯一标识 */
+    componentId: string;
+    /** 水合策略 */
+    strategy: HydrationStrategy;
+    /** 组件 props 快照 */
+    props: Record<string, unknown>;
+}
+/** 水合状态数据结构 */
+interface HydrationState {
+    /** 组件水合提示列表 */
+    hints: HydrationHints[];
+    /** 全局初始状态 */
+    initialState?: Record<string, unknown>;
+}
+/**
+ * 重置组件 ID 计数器（仅用于测试）
+ */
+declare function resetComponentIdCounter(): void;
+/**
+ * 为 VNode 树添加水合标记
+ *
+ * @description
+ * 递归遍历 VNode 树，为每个元素节点添加 data-hydrate 属性，
+ * 用于客户端水合时识别对应的 SSR 输出节点。
+ * 同时根据 props 中的 hydrateStrategy 设置 data-hydrate-strategy 属性。
+ *
+ * @param vnode - 原始 VNode
+ * @returns 添加了水合标记的新 VNode（浅拷贝）
+ *
+ * @example
+ * ```typescript
+ * const marked = createHydrationMarkers(vnode);
+ * // marked 的每个元素节点都带有 data-hydrate="lyt-hydrate-1" 等属性
+ * ```
+ */
+declare function createHydrationMarkers(vnode: VNode): VNode;
+/**
+ * 获取组件的水合策略
+ *
+ * @description
+ * 从 VNode 的 props 中读取 hydrateStrategy 字段，
+ * 返回对应的水合策略。如果未设置，默认返回 'eager'。
+ *
+ * @param vnode - 目标 VNode
+ * @returns 水合策略（lazy / eager / idle）
+ *
+ * @example
+ * ```typescript
+ * const strategy = getHydrationStrategy(vnode);
+ * // 'eager' | 'lazy' | 'idle'
+ * ```
+ */
+declare function getHydrationStrategy(vnode: VNode): HydrationStrategy;
+/**
+ * 序列化客户端水合所需的初始状态
+ *
+ * @description
+ * 将任意状态对象序列化为可安全嵌入 HTML 的 JSON 字符串。
+ * 处理特殊值（undefined、函数、Symbol 等）以确保 JSON 安全。
+ *
+ * @param state - 要序列化的状态对象
+ * @returns JSON 字符串
+ *
+ * @example
+ * ```typescript
+ * const serialized = serializeHydrationState({
+ *   user: { name: 'Alice', age: 30 },
+ *   items: [1, 2, 3],
+ * });
+ * // '{"user":{"name":"Alice","age":30},"items":[1,2,3]}'
+ * ```
+ */
+declare function serializeHydrationState(state: unknown): string;
+/**
+ * 创建脱水状态（SSR 时序列化到 HTML 中的状态）
+ *
+ * @description
+ * 从 VNode 树中提取水合所需的信息，生成一段可嵌入 HTML 的 script 标签内容。
+ * 客户端加载时读取此状态进行水合。
+ *
+ * @param vnode - VNode 节点
+ * @param initialState - 可选的全局初始状态
+ * @returns 可嵌入 HTML 的 script 标签字符串
+ *
+ * @example
+ * ```typescript
+ * const script = createDehydratedState(vnode, {
+ *   user: { name: 'Alice' },
+ * });
+ * // <script id="__LYT_DEHYDRATED_STATE__" type="application/json">...</script>
+ * ```
+ */
+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 };