@ubean/pages 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -29,15 +29,31 @@ interface PageRenderContext {
    *  preventing `availableLocales` hydration mismatches. */
   availableLocales?: LocaleMetaInfo[];
 }
-type PageRenderFn = (pageObj: PageObject, shellHtml: string, assetTags: PageAssetTags, renderContext?: PageRenderContext) => string | Promise<string>;
+/**
+ * 渲染结果。
+ *
+ * - `string`:仅 HTML(向后兼容,无 SSR state)
+ * - `{ html, state? }`:HTML + 可选的 SSR state(由 `defineApp.serializeState` 产生,
+ *   会被序列化到 `__UBEAN_STATE__` script 标签中,客户端通过 `getInitialState()` 读取)
+ *
+ * `state` 用于支持 Pinia / vue-query 等需要跨 SSR 边界传递状态的库。
+ */
+type PageRenderResult = string | {
+  html: string;
+  state?: Record<string, unknown>;
+};
+type PageRenderFn = (pageObj: PageObject, shellHtml: string, assetTags: PageAssetTags, renderContext?: PageRenderContext) => PageRenderResult | Promise<PageRenderResult>;
 interface PageRenderer {
   render: PageRenderFn;
   preambleScript?: string;
 }
 declare const PAGE_DATA_ID = "__UBEAN_PAGE_DATA__";
 declare const LOCALE_DATA_ID = "__UBEAN_LOCALE__";
+declare const STATE_DATA_ID = "__UBEAN_STATE__";
 declare const PAGE_REQUEST_HEADER = "x-ubeanpages";
 declare const SSR_CONTENT_MARKER = "<!--UBEAN_SSR_CONTENT-->";
+/** Shell 中 state script 的占位符,render 后由 `insertStateContent` 替换为实际 JSON */
+declare const STATE_MARKER = "<!--UBEAN_STATE-->";
 declare function isPagesRequest(c: {
   req: {
     header: (k: string) => string | undefined;
@@ -48,6 +64,16 @@ declare function serializePageData(pageObj: PageObject): string;
 declare function pageJsonResponse(pageObj: PageObject, headers?: Record<string, string>): Response;
 declare function buildPageShell(pageObj: PageObject, assetTags: PageAssetTags, preambleScript?: string, appId?: string, renderContext?: PageRenderContext): string;
 declare function insertSsrContent(shell: string, appHtml: string): string;
+/**
+ * 将序列化后的 state JSON 注入 shell 中的 `__UBEAN_STATE__` script 标签。
+ *
+ * 在 `renderPage` 中于 `renderer.render()` 之后调用:renderer 返回 `{ html, state }`
+ * 时,把 `state` 用 `safeJsonStringify` 转义后替换 `STATE_MARKER` 占位符。
+ *
+ * 若 `stateJson` 为空字符串或 `null`,将占位符替换为空字符串(产出空 script 体,
+ * 客户端 `getInitialState()` 会返回 `null`)。
+ */
+declare function insertStateContent(shell: string, stateJson: string | null): string;
 declare function buildClientOnlyShell(pageObj: PageObject, assetTags: PageAssetTags, preambleScript?: string, appId?: string, renderContext?: PageRenderContext): string;
 declare function renderPage(pageObj: PageObject, assetTags: PageAssetTags, renderer: PageRenderer | null, appId?: string, renderContext?: PageRenderContext): Promise<string>;
 //#endregion
@@ -110,4 +136,4 @@ interface StreamHelper {
 declare function createStreamResponse(init?: ResponseInit, onStart?: (stream: StreamHelper) => void | Promise<void>): Response;
 declare function createSseStream(onStart?: (stream: StreamHelper) => void | Promise<void>): Response;
 //#endregion
-export { type DataCacheEntry, type DataKey, type DataResult, type DependencyDeclaration, type InternalFetchOptions, LOCALE_DATA_ID, type LocaleMetaInfo, PAGE_DATA_ID, PAGE_REQUEST_HEADER, type PageAssetTags, type PageHead, type PageHeadMeta, type PageObject, type PageRenderContext, type PageRenderFn, type PageRenderer, SSR_CONTENT_MARKER, type StreamHelper, type UseDataOptions, buildClientOnlyShell, buildPageShell, clearDataCache, createInternalFetch, createSseStream, createStreamResponse, declareDependencies, defineDataKey, getInvalidatedKeysForAction, hasData, insertSsrContent, invalidateAll, invalidateData, isPagesRequest, pageJsonResponse, renderPage, safeJsonStringify, serializePageData, useData, withDependencies };
+export { type DataCacheEntry, type DataKey, type DataResult, type DependencyDeclaration, type InternalFetchOptions, LOCALE_DATA_ID, type LocaleMetaInfo, PAGE_DATA_ID, PAGE_REQUEST_HEADER, type PageAssetTags, type PageHead, type PageHeadMeta, type PageObject, type PageRenderContext, type PageRenderFn, type PageRenderResult, type PageRenderer, SSR_CONTENT_MARKER, STATE_DATA_ID, STATE_MARKER, type StreamHelper, type UseDataOptions, buildClientOnlyShell, buildPageShell, clearDataCache, createInternalFetch, createSseStream, createStreamResponse, declareDependencies, defineDataKey, getInvalidatedKeysForAction, hasData, insertSsrContent, insertStateContent, invalidateAll, invalidateData, isPagesRequest, pageJsonResponse, renderPage, safeJsonStringify, serializePageData, useData, withDependencies };

package/dist/index.js

@@ -1,8 +1,11 @@
 //#region src/protocol.ts
 const PAGE_DATA_ID = "__UBEAN_PAGE_DATA__";
 const LOCALE_DATA_ID = "__UBEAN_LOCALE__";
+const STATE_DATA_ID = "__UBEAN_STATE__";
 const PAGE_REQUEST_HEADER = "x-ubeanpages";
 const SSR_CONTENT_MARKER = "<!--UBEAN_SSR_CONTENT-->";
+/** Shell 中 state script 的占位符,render 后由 `insertStateContent` 替换为实际 JSON */
+const STATE_MARKER = "<!--UBEAN_STATE-->";
 function isPagesRequest(c) {
 	return c.req.header(PAGE_REQUEST_HEADER) === "true";
 }
@@ -83,6 +86,7 @@ function buildPageShell(pageObj, assetTags, preambleScript = "", appId = "app",
 <body${finalBodyAttrs ? ` ${finalBodyAttrs}` : ""}>
   ${localeScript}
   <script id="${PAGE_DATA_ID}" type="application/json">${pageData}<\/script>
+  <script id="${STATE_DATA_ID}" type="application/json">${STATE_MARKER}<\/script>
   <div id="${appId}">${SSR_CONTENT_MARKER}</div>
   ${preambleScript}
   ${bodyTags}
@@ -92,6 +96,18 @@ function buildPageShell(pageObj, assetTags, preambleScript = "", appId = "app",
 function insertSsrContent(shell, appHtml) {
 	return shell.replace(SSR_CONTENT_MARKER, appHtml);
 }
+/**
+* 将序列化后的 state JSON 注入 shell 中的 `__UBEAN_STATE__` script 标签。
+*
+* 在 `renderPage` 中于 `renderer.render()` 之后调用:renderer 返回 `{ html, state }`
+* 时,把 `state` 用 `safeJsonStringify` 转义后替换 `STATE_MARKER` 占位符。
+*
+* 若 `stateJson` 为空字符串或 `null`,将占位符替换为空字符串(产出空 script 体,
+* 客户端 `getInitialState()` 会返回 `null`)。
+*/
+function insertStateContent(shell, stateJson) {
+	return shell.replace(STATE_MARKER, stateJson ?? "");
+}
 function buildClientOnlyShell(pageObj, assetTags, preambleScript = "", appId = "app", renderContext) {
 	const pageData = serializePageData(pageObj);
 	const css = assetTags.css ?? "";
@@ -123,6 +139,7 @@ function buildClientOnlyShell(pageObj, assetTags, preambleScript = "", appId = "
 <body${finalBodyAttrs ? ` ${finalBodyAttrs}` : ""}>
   ${localeScript}
   <script id="${PAGE_DATA_ID}" type="application/json">${pageData}<\/script>
+  <script id="${STATE_DATA_ID}" type="application/json"><\/script>
   <div id="${appId}" data-ubean-ssr="false"></div>
   ${bodyTags}
 </body>
@@ -131,9 +148,17 @@ function buildClientOnlyShell(pageObj, assetTags, preambleScript = "", appId = "
 async function renderPage(pageObj, assetTags, renderer, appId = "app", renderContext) {
 	if (!renderer) return buildClientOnlyShell(pageObj, assetTags, "", appId, renderContext);
 	const shell = buildPageShell(pageObj, assetTags, renderer.preambleScript ?? "", appId, renderContext);
-	const appHtml = await renderer.render(pageObj, shell, assetTags, renderContext);
-	if (typeof appHtml === "string" && !shell.includes(appHtml) && !appHtml.includes("<html")) return insertSsrContent(shell, appHtml);
-	return appHtml;
+	const result = await renderer.render(pageObj, shell, assetTags, renderContext);
+	if (typeof result === "string") {
+		if (!shell.includes(result) && !result.includes("<html")) return insertSsrContent(shell, result);
+		return result;
+	}
+	const { html, state } = result;
+	let finalHtml = html;
+	if (!shell.includes(html) && !html.includes("<html")) finalHtml = insertSsrContent(shell, html);
+	if (state && Object.keys(state).length > 0) finalHtml = insertStateContent(finalHtml, safeJsonStringify(state));
+	else finalHtml = insertStateContent(finalHtml, "");
+	return finalHtml;
 }
 //#endregion
 //#region src/data.ts
@@ -372,4 +397,4 @@ function createSseStream(onStart) {
 	} });
 }
 //#endregion
-export { LOCALE_DATA_ID, PAGE_DATA_ID, PAGE_REQUEST_HEADER, SSR_CONTENT_MARKER, buildClientOnlyShell, buildPageShell, clearDataCache, createInternalFetch, createSseStream, createStreamResponse, declareDependencies, defineDataKey, getInvalidatedKeysForAction, hasData, insertSsrContent, invalidateAll, invalidateData, isPagesRequest, pageJsonResponse, renderPage, safeJsonStringify, serializePageData, useData, withDependencies };
+export { LOCALE_DATA_ID, PAGE_DATA_ID, PAGE_REQUEST_HEADER, SSR_CONTENT_MARKER, STATE_DATA_ID, STATE_MARKER, buildClientOnlyShell, buildPageShell, clearDataCache, createInternalFetch, createSseStream, createStreamResponse, declareDependencies, defineDataKey, getInvalidatedKeysForAction, hasData, insertSsrContent, insertStateContent, invalidateAll, invalidateData, isPagesRequest, pageJsonResponse, renderPage, safeJsonStringify, serializePageData, useData, withDependencies };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/pages",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Page data protocol and isomorphic data layer for ubean (PageObject, useData, invalidateData)",
   "files": [
     "dist"
@@ -16,11 +16,11 @@
     }
   },
   "dependencies": {
-    "@ubean/types": "0.1.6"
+    "@ubean/types": "0.1.8"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
-    "typescript": "6.0.3",
+    "@types/node": "^26.1.2",
+    "typescript": "7.0.2",
     "vite-plus": "0.2.6"
   },
   "scripts": {