@ubean/pages 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import { PageHead, PageHead as PageHead$1, PageHead as PageHeadMeta } from "@ubean/types";
+//#region src/protocol.d.ts
+interface PageObject<Props = Record<string, unknown>> {
+  component: string;
+  props: Props;
+  params: Record<string, string>;
+  url: string;
+  layout?: string | false;
+  errors?: Record<string, string> | null;
+  head?: PageHead$1;
+}
+interface PageAssetTags {
+  css?: string;
+  preloads?: string;
+  body?: string;
+}
+interface LocaleMetaInfo {
+  code: string;
+  name?: string;
+  dir: 'ltr' | 'rtl';
+  isDefault?: boolean;
+}
+interface PageRenderContext {
+  locale?: string;
+  localeDir?: 'ltr' | 'rtl';
+  messages?: Record<string, unknown>;
+  /** All registered locales (metadata only, no messages) — sent to the
+   *  client so it can register every available locale during hydration,
+   *  preventing `availableLocales` hydration mismatches. */
+  availableLocales?: LocaleMetaInfo[];
+}
+type PageRenderFn = (pageObj: PageObject, shellHtml: string, assetTags: PageAssetTags, renderContext?: PageRenderContext) => string | Promise<string>;
+interface PageRenderer {
+  render: PageRenderFn;
+  preambleScript?: string;
+}
+declare const PAGE_DATA_ID = "__UBEAN_PAGE_DATA__";
+declare const LOCALE_DATA_ID = "__UBEAN_LOCALE__";
+declare const PAGE_REQUEST_HEADER = "x-ubeanpages";
+declare const SSR_CONTENT_MARKER = "<!--UBEAN_SSR_CONTENT-->";
+declare function isPagesRequest(c: {
+  req: {
+    header: (k: string) => string | undefined;
+  };
+}): boolean;
+declare function safeJsonStringify(value: unknown): string;
+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;
+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
+//#region src/data.d.ts
+type DataKey = string | symbol;
+interface DataCacheEntry<T = unknown> {
+  key: DataKey;
+  data: T;
+  timestamp: number;
+  ttl?: number;
+  tags?: string[];
+}
+type DataFetcher<T> = () => T | Promise<T>;
+declare function defineDataKey(key: string): symbol;
+interface UseDataOptions<T> {
+  key?: DataKey;
+  tags?: string[];
+  ttl?: number;
+  staleWhileRevalidate?: boolean;
+  fetcher: DataFetcher<T>;
+}
+interface DataResult<T> {
+  data: T | undefined;
+  error: Error | null;
+  loading: boolean;
+  timestamp: number | undefined;
+  invalidate: () => void;
+}
+declare function useData<T>(options: UseDataOptions<T>, context?: object): Promise<DataResult<T>>;
+declare function invalidateData(keyOrTag: DataKey | string, context?: object): number;
+declare function invalidateAll(context?: object): void;
+declare function clearDataCache(context?: object): void;
+declare function hasData(key: DataKey, context?: object): boolean;
+interface DependencyDeclaration {
+  keys: DataKey[];
+  tags?: string[];
+}
+declare function declareDependencies(deps: DependencyDeclaration): DependencyDeclaration;
+declare function withDependencies<T>(fn: () => T | Promise<T>, _deps: DependencyDeclaration): () => Promise<T>;
+declare function getInvalidatedKeysForAction(actionName: string, invalidationMap: Record<string, Array<DataKey | string>>, context?: object): number;
+interface InternalFetchOptions {
+  baseURL?: string;
+  headers?: Record<string, string>;
+  credentials?: 'include' | 'omit' | 'same-origin';
+  forwardHeaders?: string[];
+}
+declare function createInternalFetch(c: {
+  req: {
+    raw?: Request;
+    header?: (name: string) => string | undefined;
+    url?: string;
+  };
+}, options?: InternalFetchOptions): typeof fetch;
+interface StreamHelper {
+  enqueue: (chunk: unknown) => void;
+  close: () => void;
+  error: (err: Error) => void;
+  response: Response;
+}
+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 };

package/dist/index.js

@@ -0,0 +1,375 @@
+//#region src/protocol.ts
+const PAGE_DATA_ID = "__UBEAN_PAGE_DATA__";
+const LOCALE_DATA_ID = "__UBEAN_LOCALE__";
+const PAGE_REQUEST_HEADER = "x-ubeanpages";
+const SSR_CONTENT_MARKER = "<!--UBEAN_SSR_CONTENT-->";
+function isPagesRequest(c) {
+	return c.req.header(PAGE_REQUEST_HEADER) === "true";
+}
+function safeJsonStringify(value) {
+	return (JSON.stringify(value) ?? "null").replaceAll("<", "\\u003c").replaceAll(">", "\\u003e").replaceAll("&", "\\u0026").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+}
+function serializePageData(pageObj) {
+	return safeJsonStringify(pageObj);
+}
+function pageJsonResponse(pageObj, headers = {}) {
+	const safeJson = safeJsonStringify(pageObj);
+	return new Response(safeJson, { headers: {
+		"Content-Type": "application/json",
+		"X-UbeanPages": "true",
+		Vary: "X-UbeanPages",
+		...headers
+	} });
+}
+function escapeAttr(str) {
+	return str.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;");
+}
+function renderHeadTags(head) {
+	if (!head) return {
+		headTags: "",
+		htmlAttrsStr: "",
+		bodyAttrsStr: ""
+	};
+	const tags = [];
+	if (head.title) tags.push(`<title>${escapeAttr(head.title)}</title>`);
+	if (head.meta) for (const meta of head.meta) {
+		const attrs = Object.entries(meta).map(([k, v]) => `${k}="${escapeAttr(String(v))}"`).join(" ");
+		tags.push(`<meta ${attrs}>`);
+	}
+	if (head.link) for (const link of head.link) {
+		const attrs = Object.entries(link).map(([k, v]) => `${k}="${escapeAttr(String(v))}"`).join(" ");
+		tags.push(`<link ${attrs}>`);
+	}
+	if (head.script) for (const script of head.script) {
+		const attrs = Object.entries(script).map(([k, v]) => `${k}="${escapeAttr(String(v))}"`).join(" ");
+		tags.push(`<script ${attrs}><\/script>`);
+	}
+	const htmlAttrsStr = head.htmlAttrs ? Object.entries(head.htmlAttrs).map(([k, v]) => `${k}="${escapeAttr(String(v))}"`).join(" ") : "";
+	const bodyAttrsStr = head.bodyAttrs ? Object.entries(head.bodyAttrs).map(([k, v]) => `${k}="${escapeAttr(String(v))}"`).join(" ") : "";
+	return {
+		headTags: tags.join("\n    "),
+		htmlAttrsStr,
+		bodyAttrsStr
+	};
+}
+function buildPageShell(pageObj, assetTags, preambleScript = "", appId = "app", renderContext) {
+	const pageData = serializePageData(pageObj);
+	const css = assetTags.css ?? "";
+	const preloads = assetTags.preloads ?? "";
+	const bodyTags = assetTags.body ?? "";
+	const locale = renderContext?.locale;
+	const localeDir = renderContext?.localeDir || "ltr";
+	const messages = renderContext?.messages;
+	const availableLocales = renderContext?.availableLocales;
+	const localeScript = locale ? `<script id="${LOCALE_DATA_ID}" type="application/json">${safeJsonStringify({
+		locale,
+		dir: localeDir,
+		...messages ? { messages } : {},
+		...availableLocales?.length ? { availableLocales } : {}
+	})}<\/script>` : "";
+	const { headTags, htmlAttrsStr, bodyAttrsStr } = renderHeadTags(pageObj.head);
+	const localeHtmlAttrs = {};
+	if (locale) {
+		localeHtmlAttrs.lang = locale;
+		localeHtmlAttrs.dir = localeDir;
+	}
+	const finalHtmlAttrs = [Object.entries(localeHtmlAttrs).map(([k, v]) => `${k}="${escapeAttr(String(v))}"`).join(" "), htmlAttrsStr].filter(Boolean).join(" ");
+	const finalBodyAttrs = bodyAttrsStr;
+	return `<!doctype html>
+<html${finalHtmlAttrs ? ` ${finalHtmlAttrs}` : ""}>
+<head>
+    ${headTags ? `${headTags}\n    ` : ""}${css}${preloads}
+</head>
+<body${finalBodyAttrs ? ` ${finalBodyAttrs}` : ""}>
+  ${localeScript}
+  <script id="${PAGE_DATA_ID}" type="application/json">${pageData}<\/script>
+  <div id="${appId}">${SSR_CONTENT_MARKER}</div>
+  ${preambleScript}
+  ${bodyTags}
+</body>
+</html>`;
+}
+function insertSsrContent(shell, appHtml) {
+	return shell.replace(SSR_CONTENT_MARKER, appHtml);
+}
+function buildClientOnlyShell(pageObj, assetTags, preambleScript = "", appId = "app", renderContext) {
+	const pageData = serializePageData(pageObj);
+	const css = assetTags.css ?? "";
+	const preloads = assetTags.preloads ?? "";
+	const bodyTags = assetTags.body ?? "";
+	const locale = renderContext?.locale;
+	const localeDir = renderContext?.localeDir || "ltr";
+	const messages = renderContext?.messages;
+	const availableLocales = renderContext?.availableLocales;
+	const localeScript = locale ? `<script id="${LOCALE_DATA_ID}" type="application/json">${safeJsonStringify({
+		locale,
+		dir: localeDir,
+		...messages ? { messages } : {},
+		...availableLocales?.length ? { availableLocales } : {}
+	})}<\/script>` : "";
+	const { headTags, htmlAttrsStr: pageHtmlAttrsStr, bodyAttrsStr } = renderHeadTags(pageObj.head);
+	const htmlAttrs = {};
+	if (locale) {
+		htmlAttrs.lang = locale;
+		htmlAttrs.dir = localeDir;
+	}
+	const finalHtmlAttrs = [Object.entries(htmlAttrs).map(([k, v]) => `${k}="${escapeAttr(String(v))}"`).join(" "), pageHtmlAttrsStr].filter(Boolean).join(" ");
+	const finalBodyAttrs = bodyAttrsStr;
+	return `<!doctype html>
+<html${finalHtmlAttrs ? ` ${finalHtmlAttrs}` : ""}>
+<head>
+    ${headTags ? `${headTags}\n    ` : ""}${preambleScript}${css}${preloads}
+</head>
+<body${finalBodyAttrs ? ` ${finalBodyAttrs}` : ""}>
+  ${localeScript}
+  <script id="${PAGE_DATA_ID}" type="application/json">${pageData}<\/script>
+  <div id="${appId}" data-ubean-ssr="false"></div>
+  ${bodyTags}
+</body>
+</html>`;
+}
+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;
+}
+//#endregion
+//#region src/data.ts
+function createRegistry() {
+	return {
+		entries: /* @__PURE__ */ new Map(),
+		tagIndex: /* @__PURE__ */ new Map()
+	};
+}
+const globalRegistry = createRegistry();
+const contextRegistry = /* @__PURE__ */ new WeakMap();
+function getRegistry(context) {
+	if (context) {
+		let reg = contextRegistry.get(context);
+		if (!reg) {
+			reg = createRegistry();
+			contextRegistry.set(context, reg);
+		}
+		return reg;
+	}
+	return globalRegistry;
+}
+function defineDataKey(key) {
+	return Symbol.for(`ubean:data:${key}`);
+}
+async function useData(options, context) {
+	const registry = getRegistry(context);
+	const key = options.key || Symbol();
+	const invalidate = () => {
+		invalidateData(key, context);
+	};
+	try {
+		const cached = registry.entries.get(key);
+		if (cached) {
+			if (!(cached.ttl !== void 0 && Date.now() - cached.timestamp > cached.ttl)) return {
+				data: cached.data,
+				error: null,
+				loading: false,
+				timestamp: cached.timestamp,
+				invalidate
+			};
+		}
+		const data = await options.fetcher();
+		const entry = {
+			key,
+			data,
+			timestamp: Date.now(),
+			ttl: options.ttl,
+			tags: options.tags
+		};
+		registry.entries.set(key, entry);
+		if (options.tags) for (const tag of options.tags) {
+			let tagSet = registry.tagIndex.get(tag);
+			if (!tagSet) {
+				tagSet = /* @__PURE__ */ new Set();
+				registry.tagIndex.set(tag, tagSet);
+			}
+			tagSet.add(key);
+		}
+		return {
+			data,
+			error: null,
+			loading: false,
+			timestamp: entry.timestamp,
+			invalidate
+		};
+	} catch (err) {
+		return {
+			data: void 0,
+			error: err instanceof Error ? err : new Error(String(err)),
+			loading: false,
+			timestamp: void 0,
+			invalidate
+		};
+	}
+}
+function invalidateData(keyOrTag, context) {
+	const registry = getRegistry(context);
+	let count = 0;
+	if (typeof keyOrTag === "string") {
+		const tagSet = registry.tagIndex.get(keyOrTag);
+		if (tagSet) {
+			for (const key of tagSet) {
+				const entry = registry.entries.get(key);
+				if (entry) {
+					if (entry.tags) for (const t of entry.tags) {
+						const tSet = registry.tagIndex.get(t);
+						if (tSet) tSet.delete(key);
+					}
+					registry.entries.delete(key);
+					count++;
+				}
+			}
+			registry.tagIndex.delete(keyOrTag);
+		}
+	} else {
+		const entry = registry.entries.get(keyOrTag);
+		if (entry) {
+			if (entry.tags) for (const t of entry.tags) {
+				const tSet = registry.tagIndex.get(t);
+				if (tSet) tSet.delete(keyOrTag);
+			}
+			registry.entries.delete(keyOrTag);
+			count = 1;
+		}
+	}
+	return count;
+}
+function invalidateAll(context) {
+	const registry = getRegistry(context);
+	registry.entries.clear();
+	registry.tagIndex.clear();
+}
+function clearDataCache(context) {
+	invalidateAll(context);
+}
+function hasData(key, context) {
+	return getRegistry(context).entries.has(key);
+}
+function declareDependencies(deps) {
+	return deps;
+}
+function withDependencies(fn, _deps) {
+	return async () => {
+		return fn();
+	};
+}
+function getInvalidatedKeysForAction(actionName, invalidationMap, context) {
+	const toInvalidate = invalidationMap[actionName];
+	if (!toInvalidate) return 0;
+	let count = 0;
+	for (const key of toInvalidate) count += invalidateData(key, context);
+	return count;
+}
+const FORWARD_HEADER_DEFAULTS = [
+	"cookie",
+	"authorization",
+	"x-request-id",
+	"x-forwarded-for",
+	"x-forwarded-proto",
+	"x-forwarded-host",
+	"accept-language",
+	"user-agent",
+	"referer"
+];
+function createInternalFetch(c, options = {}) {
+	const forwardHeaders = options.forwardHeaders || FORWARD_HEADER_DEFAULTS;
+	const incomingHeaders = new Headers();
+	for (const headerName of forwardHeaders) {
+		const value = c.req.header?.(headerName);
+		if (value) incomingHeaders.set(headerName, value);
+	}
+	if (options.headers) for (const [k, v] of Object.entries(options.headers)) incomingHeaders.set(k, v);
+	const baseURL = options.baseURL || "";
+	return async function internalFetch(input, init) {
+		let url;
+		if (typeof input === "string") url = input.startsWith("http") ? input : `${baseURL}${input.startsWith("/") ? "" : "/"}${input}`;
+		else if (input instanceof URL) url = input.toString();
+		else url = input.url;
+		const mergedInit = {
+			...init,
+			headers: mergeHeaders(incomingHeaders, init?.headers)
+		};
+		return fetch(url, mergedInit);
+	};
+}
+function mergeHeaders(base, extra) {
+	const result = new Headers(base);
+	if (!extra) return result;
+	if (extra instanceof Headers) extra.forEach((value, key) => result.set(key, value));
+	else if (Array.isArray(extra)) for (const [key, value] of extra) result.set(key, value);
+	else for (const [key, value] of Object.entries(extra)) if (value !== void 0) result.set(key, String(value));
+	return result;
+}
+function createStreamResponse(init, onStart) {
+	const encoder = new TextEncoder();
+	const stream = new ReadableStream({ async start(controller) {
+		const helper = {
+			enqueue(chunk) {
+				const data = typeof chunk === "string" ? chunk : JSON.stringify(chunk);
+				controller.enqueue(encoder.encode(data));
+			},
+			close() {
+				controller.close();
+			},
+			error(err) {
+				controller.error(err);
+			},
+			response: null
+		};
+		try {
+			await onStart?.(helper);
+		} catch (err) {
+			controller.error(err);
+		}
+	} });
+	return new Response(stream, {
+		...init,
+		headers: {
+			"Content-Type": init?.headers ? init.headers["Content-Type"] || "text/event-stream" : "text/event-stream",
+			"Cache-Control": "no-cache",
+			Connection: "keep-alive",
+			...init?.headers
+		}
+	});
+}
+function createSseStream(onStart) {
+	const encoder = new TextEncoder();
+	const stream = new ReadableStream({ async start(controller) {
+		const helper = {
+			enqueue(chunk) {
+				let text;
+				if (typeof chunk === "string") text = `data: ${chunk}\n\n`;
+				else text = `data: ${JSON.stringify(chunk)}\n\n`;
+				controller.enqueue(encoder.encode(text));
+			},
+			close() {
+				controller.close();
+			},
+			error(err) {
+				controller.error(err);
+			},
+			response: null
+		};
+		controller.enqueue(encoder.encode(": connected\n\n"));
+		try {
+			await onStart?.(helper);
+		} catch (err) {
+			controller.error(err);
+		}
+	} });
+	return new Response(stream, { headers: {
+		"Content-Type": "text/event-stream",
+		"Cache-Control": "no-cache",
+		Connection: "keep-alive"
+	} });
+}
+//#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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/pages",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Page data protocol and isomorphic data layer for ubean (PageObject, useData, invalidateData)",
   "files": [
     "dist"
@@ -16,7 +16,7 @@
     }
   },
   "dependencies": {
-    "@ubean/types": "0.1.1"
+    "@ubean/types": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",