@nkzw/fate 1.0.3 → 1.2.0

package/lib/index.mjs

@@ -1,6 +1,7 @@
-import { t as isRecord } from "./record-AeZJC9fd.mjs";
-import { a as errorCodeFromStatus, c as cloneArgs, d as hashArgs, f as paginationArgKeys, i as FateRequestError, l as combineArgsPayload, m as scopeArgsPayload, n as liveEntityTopic, p as resolvedArgsFromPlan, r as liveGlobalConnectionTopic, s as applyArgsPayloadToPlan, t as liveConnectionTopic, u as filterConnectionArgs } from "./liveTopics-DzNtJaBD.mjs";
-import { t as getListEntries } from "./list-C_mi6GnE.mjs";
+import { t as isRecord } from "./record-B07VwXd-.mjs";
+import { a as errorCodeFromStatus, c as cloneArgs, d as hashArgs, f as paginationArgKeys, i as FateRequestError, l as combineArgsPayload, m as scopeArgsPayload, n as liveEntityTopic, p as resolvedArgsFromPlan, r as liveGlobalConnectionTopic, s as applyArgsPayloadToPlan, t as liveConnectionTopic, u as filterConnectionArgs } from "./liveTopics-JIDh3t3P.mjs";
+import { t as getListEntries } from "./list-_6fXYLtJ.mjs";
+import { n as graphqlMutation, t as createGraphQLTransport } from "./graphqlTransport-IFgmY-Qq.mjs";
 //#region src/cache.ts
 var ViewDataCache = class {
 	constructor() {
@@ -8,6 +9,11 @@ var ViewDataCache = class {
 		this.rootDependencies = /* @__PURE__ */ new Map();
 		this.dependencyIndex = /* @__PURE__ */ new Map();
 	}
+	clear() {
+		this.cache.clear();
+		this.rootDependencies.clear();
+		this.dependencyIndex.clear();
+	}
 	get(entityId, view, ref) {
 		return this.cache.get(entityId)?.get(view)?.get(ref) ?? null;
 	}
@@ -63,6 +69,288 @@ var ViewDataCache = class {
 	}
 };
 //#endregion
+//#region src/types.ts
+/** Internal marker added to objects that represent a view payload. */
+const ViewKind = Symbol("__fate__view");
+/** Symbol used to attach the set of view tags that were spread into a ref or masked record. */
+const ViewsTag = Symbol("__fate__views");
+/** Symbol used to brand a value as a node reference inside the cache. */
+const NodeRefTag = Symbol("__fate__node-ref");
+/** Symbol attached to connection results so pagination helpers can find their metadata. */
+const ConnectionTag = Symbol("__fate__connection");
+/** Symbol used to mark a selection as deferred. */
+const DeferTag = Symbol("__fate__defer");
+/** Symbol attached to deferred values returned from masked views. */
+const DeferredTag = Symbol("__fate__deferred");
+const viewTag = "__fate-view__";
+/** Generates a stable view tag for a view definition. */
+function getViewTag(id) {
+	return `${viewTag}${id}`;
+}
+/** Determines whether a property key is a fate view tag. */
+function isViewTag(key) {
+	return key.startsWith(viewTag);
+}
+/** Indicates whether a request item represents an explicit node ID. */
+function isNodeItem(item) {
+	return "id" in item;
+}
+/** Indicates whether a request item represents explicit node IDs. */
+function isNodesItem(item) {
+	return "ids" in item;
+}
+/** Indicates whether a request item represents a root query. */
+function isQueryItem(item) {
+	return "view" in item && !("id" in item) && !("ids" in item);
+}
+/** Brand used on root definitions to mark their identity in the d.ts output. */
+const RootKind = "__fate__root";
+/** Brand used on mutation definitions to mark their identity in the d.ts output. */
+const MutationKind = "__fate__mutation";
+//#endregion
+//#region src/defer.ts
+function defer(selection) {
+	return Object.freeze({ [DeferTag]: selection });
+}
+const isDeferredSelection = (value) => typeof value === "object" && value !== null && DeferTag in value;
+const getDeferredSelection = (selection) => selection[DeferTag];
+const createDeferred = (metadata) => Object.freeze({ [DeferredTag]: metadata });
+const isDeferred = (value) => typeof value === "object" && value !== null && DeferredTag in value;
+const getDeferredMetadata = (deferred) => deferred[DeferredTag];
+//#endregion
+//#region src/node-ref.ts
+function createNodeRef(id) {
+	const ref = {};
+	Object.defineProperty(ref, NodeRefTag, {
+		configurable: false,
+		enumerable: false,
+		value: id,
+		writable: false
+	});
+	return Object.freeze(ref);
+}
+function isNodeRef(value) {
+	return !value || typeof value !== "object" ? false : NodeRefTag in value;
+}
+function getNodeRefId(ref) {
+	return ref[NodeRefTag];
+}
+//#endregion
+//#region src/hydration.ts
+const maxDepth = 64;
+const defaultHydrationLimits = {
+	maxCollectionLength: 1e5,
+	maxNodes: 25e4,
+	maxStringLength: 1e6
+};
+const resolveHydrationLimits = (limits) => {
+	const result = {
+		...defaultHydrationLimits,
+		...limits
+	};
+	for (const [key, value] of Object.entries(result)) if (!Number.isInteger(value) || value < 1) throw new Error(`fate: Hydration limit '${key}' must be a positive integer.`);
+	return result;
+};
+const error = (path, message) => /* @__PURE__ */ new Error(`fate: Cannot serialize hydration value at '${path}': ${message}`);
+const isPlainObject = (value) => {
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+const isDenseArray = (value) => {
+	for (let index = 0; index < value.length; index += 1) if (!Object.hasOwn(value, index)) return false;
+	return true;
+};
+const isDate$1 = (value) => Object.prototype.toString.call(value) === "[object Date]" && typeof value.getTime === "function" && typeof value.toISOString === "function";
+const encodeHydrationValue = (value, limits) => {
+	const resolvedLimits = resolveHydrationLimits(limits);
+	const seen = /* @__PURE__ */ new Set();
+	let nodes = 0;
+	const encode = (entry, path, depth) => {
+		nodes += 1;
+		if (nodes > resolvedLimits.maxNodes) throw error(path, `Maximum node count of ${String(resolvedLimits.maxNodes)} exceeded.`);
+		if (depth > maxDepth) throw error(path, `Maximum depth of ${String(maxDepth)} exceeded.`);
+		if (entry === null) return ["null"];
+		const type = typeof entry;
+		if (typeof entry === "string" || typeof entry === "boolean") {
+			if (typeof entry === "string" && entry.length > resolvedLimits.maxStringLength) throw error(path, `Maximum string length of ${String(resolvedLimits.maxStringLength)} exceeded.`);
+			return [typeof entry, entry];
+		}
+		if (type === "number") {
+			if (Number.isNaN(entry)) return ["number", "NaN"];
+			if (entry === Infinity) return ["number", "Infinity"];
+			if (entry === -Infinity) return ["number", "-Infinity"];
+			if (Object.is(entry, -0)) return ["number", "-0"];
+			return ["number", entry];
+		}
+		if (type === "undefined") return ["undefined"];
+		if (type === "bigint") {
+			const bigint = String(entry);
+			if (bigint.length > resolvedLimits.maxStringLength) throw error(path, `Maximum string length of ${String(resolvedLimits.maxStringLength)} exceeded.`);
+			return ["bigint", bigint];
+		}
+		if (type === "function" || type === "symbol") throw error(path, `Received unsupported '${type}' value.`);
+		if (!entry || typeof entry !== "object") throw error(path, `Received unsupported '${type}' value.`);
+		if (isNodeRef(entry)) {
+			const id = getNodeRefId(entry);
+			if (id.length > resolvedLimits.maxStringLength) throw error(path, `Maximum string length of ${String(resolvedLimits.maxStringLength)} exceeded.`);
+			return ["ref", id];
+		}
+		if (isDate$1(entry)) {
+			if (Number.isNaN(entry.getTime())) throw error(path, `Received an invalid Date.`);
+			return ["date", entry.toISOString()];
+		}
+		if (seen.has(entry)) throw error(path, `Circular references are not supported.`);
+		seen.add(entry);
+		try {
+			if (Array.isArray(entry)) {
+				if (!isDenseArray(entry)) throw error(path, `Sparse arrays are not supported.`);
+				if (entry.length > resolvedLimits.maxCollectionLength) throw error(path, `Maximum collection length of ${String(resolvedLimits.maxCollectionLength)} exceeded.`);
+				return ["array", entry.map((item, index) => encode(item, `${path}[${String(index)}]`, depth + 1))];
+			}
+			if (!isPlainObject(entry)) throw error(path, `Received unsupported '${entry.constructor?.name ?? "object"}' value.`);
+			if (Object.getOwnPropertySymbols(entry).length > 0) throw error(path, `Received an unsupported symbol-keyed property.`);
+			const entries = Object.entries(entry);
+			if (entries.length > resolvedLimits.maxCollectionLength) throw error(path, `Maximum collection length of ${String(resolvedLimits.maxCollectionLength)} exceeded.`);
+			return ["object", entries.map(([key, item]) => {
+				if (key.length > resolvedLimits.maxStringLength) throw error(path, `Maximum string length of ${String(resolvedLimits.maxStringLength)} exceeded.`);
+				return [key, encode(item, `${path}.${key}`, depth + 1)];
+			})];
+		} finally {
+			seen.delete(entry);
+		}
+	};
+	return encode(value, "data", 0);
+};
+const invalidPayload = (path) => /* @__PURE__ */ new Error(`fate: Invalid hydration payload at '${path}'.`);
+const tagLengths = {
+	array: 2,
+	bigint: 2,
+	boolean: 2,
+	date: 2,
+	null: 1,
+	number: 2,
+	object: 2,
+	ref: 2,
+	string: 2,
+	undefined: 1
+};
+const decodeHydrationValue = (value, limits) => {
+	const resolvedLimits = resolveHydrationLimits(limits);
+	let nodes = 0;
+	const decode = (entry, path, depth) => {
+		nodes += 1;
+		if (nodes > resolvedLimits.maxNodes || depth > maxDepth || !Array.isArray(entry) || typeof entry[0] !== "string") throw invalidPayload(path);
+		const [tag, payload] = entry;
+		if (entry.length !== tagLengths[tag]) throw invalidPayload(path);
+		switch (tag) {
+			case "null": return null;
+			case "undefined": return;
+			case "string":
+				if (typeof payload !== "string" || payload.length > resolvedLimits.maxStringLength) throw invalidPayload(path);
+				return payload;
+			case "boolean":
+				if (typeof payload !== "boolean") throw invalidPayload(path);
+				return payload;
+			case "number":
+				if (typeof payload === "number") {
+					if (!Number.isFinite(payload) || Object.is(payload, -0)) throw invalidPayload(path);
+					return payload;
+				}
+				if (payload === "NaN") return NaN;
+				if (payload === "Infinity") return Infinity;
+				if (payload === "-Infinity") return -Infinity;
+				if (payload === "-0") return -0;
+				throw invalidPayload(path);
+			case "bigint":
+				if (typeof payload !== "string" || payload.length > resolvedLimits.maxStringLength) throw invalidPayload(path);
+				try {
+					const bigint = BigInt(payload);
+					if (String(bigint) !== payload) throw invalidPayload(path);
+					return bigint;
+				} catch {
+					throw invalidPayload(path);
+				}
+			case "date": {
+				if (typeof payload !== "string" || payload.length > resolvedLimits.maxStringLength) throw invalidPayload(path);
+				const date = new Date(payload);
+				if (Number.isNaN(date.getTime()) || date.toISOString() !== payload) throw invalidPayload(path);
+				return date;
+			}
+			case "ref":
+				if (typeof payload !== "string" || payload.length > resolvedLimits.maxStringLength) throw invalidPayload(path);
+				return createNodeRef(payload);
+			case "array":
+				if (!Array.isArray(payload) || !isDenseArray(payload) || payload.length > resolvedLimits.maxCollectionLength) throw invalidPayload(path);
+				return payload.map((item, index) => decode(item, `${path}[${String(index)}]`, depth + 1));
+			case "object": {
+				if (!Array.isArray(payload) || payload.length > resolvedLimits.maxCollectionLength) throw invalidPayload(path);
+				const result = Object.create(null);
+				for (const item of payload) {
+					if (!Array.isArray(item) || item.length !== 2 || typeof item[0] !== "string" || item[0].length > resolvedLimits.maxStringLength) throw invalidPayload(path);
+					if (item[0] in result) throw invalidPayload(path);
+					result[item[0]] = decode(item[1], `${path}.${item[0]}`, depth + 1);
+				}
+				return result;
+			}
+			default: throw invalidPayload(path);
+		}
+	};
+	return decode(value, "data", 0);
+};
+const isRecord$1 = (value) => {
+	if (!value || typeof value !== "object" || Array.isArray(value) || isNodeRef(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+const isStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
+const hasDuplicates = (values) => new Set(values).size !== values.length;
+const isUniqueStringArray = (value) => isStringArray(value) && !hasDuplicates(value);
+const hasOnlyKeys = (value, keys) => Object.keys(value).every((key) => keys.has(key));
+const listKeys = new Set([
+	"backwardPageLimit",
+	"cursors",
+	"forwardPageLimit",
+	"ids",
+	"liveAfterIds",
+	"liveBeforeIds",
+	"pagination",
+	"pendingAfterIds",
+	"pendingBeforeIds"
+]);
+const paginationKeys = new Set([
+	"hasNext",
+	"hasPrevious",
+	"nextCursor",
+	"previousCursor"
+]);
+const clientStateKeys = new Set([
+	"rootLists",
+	"rootRequests",
+	"store"
+]);
+const storeStateKeys = new Set([
+	"coverage",
+	"lists",
+	"records"
+]);
+const isEntry = (value) => Array.isArray(value) && value.length === 2 && typeof value[0] === "string";
+const isOptionalLimit = (value) => value === void 0 || typeof value === "number" && Number.isInteger(value) && value >= 0;
+const isPagination = (value) => value === void 0 || isRecord$1(value) && hasOnlyKeys(value, paginationKeys) && typeof value.hasNext === "boolean" && typeof value.hasPrevious === "boolean" && (value.nextCursor === void 0 || typeof value.nextCursor === "string") && (value.previousCursor === void 0 || typeof value.previousCursor === "string");
+const isList = (value) => {
+	if (!isRecord$1(value) || !hasOnlyKeys(value, listKeys) || !isStringArray(value.ids) || hasDuplicates(value.ids) || value.cursors !== void 0 && (!Array.isArray(value.cursors) || value.cursors.length !== value.ids.length)) return false;
+	return (value.cursors === void 0 || Array.isArray(value.cursors) && value.cursors.every((entry) => entry === void 0 || typeof entry === "string")) && (value.liveAfterIds === void 0 || isUniqueStringArray(value.liveAfterIds)) && (value.liveBeforeIds === void 0 || isUniqueStringArray(value.liveBeforeIds)) && isOptionalLimit(value.backwardPageLimit) && isOptionalLimit(value.forwardPageLimit) && isPagination(value.pagination) && (value.pendingAfterIds === void 0 || isUniqueStringArray(value.pendingAfterIds)) && (value.pendingBeforeIds === void 0 || isUniqueStringArray(value.pendingBeforeIds));
+};
+const isFieldPath = (value) => value.length > 0 && value.split(".").every((segment) => segment.length > 0);
+const isFieldPathArray = (value) => isUniqueStringArray(value) && value.every(isFieldPath);
+const hasDuplicateEntries = (entries) => hasDuplicates(entries.map((entry) => entry[0]));
+const decodeClientHydrationState = (value, limits) => {
+	const decoded = decodeHydrationValue(value, limits);
+	if (!isRecord$1(decoded) || !hasOnlyKeys(decoded, clientStateKeys) || !Array.isArray(decoded.rootLists) || !Array.isArray(decoded.rootRequests) || !isRecord$1(decoded.store) || !hasOnlyKeys(decoded.store, storeStateKeys) || !Array.isArray(decoded.store.coverage) || !Array.isArray(decoded.store.lists) || !Array.isArray(decoded.store.records)) throw invalidPayload("data");
+	if (decoded.rootLists.some((entry) => !isEntry(entry) || !isStringArray(entry[1])) || decoded.rootRequests.some((entry) => !isEntry(entry) || entry[1] !== null && typeof entry[1] !== "string") || decoded.store.coverage.some((entry) => !isEntry(entry) || !isFieldPathArray(entry[1])) || decoded.store.lists.some((entry) => !isEntry(entry) || !isList(entry[1])) || decoded.store.records.some((entry) => !isEntry(entry) || !isRecord$1(entry[1]))) throw invalidPayload("data");
+	if (hasDuplicateEntries(decoded.rootLists) || hasDuplicateEntries(decoded.rootRequests) || hasDuplicateEntries(decoded.store.coverage) || hasDuplicateEntries(decoded.store.lists) || hasDuplicateEntries(decoded.store.records) || decoded.rootLists.some(([, keys]) => hasDuplicates(keys))) throw invalidPayload("data");
+	return decoded;
+};
+//#endregion
 //#region src/mask.ts
 function emptyMask() {
 	return {
@@ -111,6 +399,18 @@ function fromPaths(paths) {
 	for (const path of paths) addPath(mask, path);
 	return mask;
 }
+function toPaths(mask) {
+	const paths = [];
+	const visit = (current, prefix) => {
+		if (current.all) {
+			if (prefix) paths.push(prefix);
+			return;
+		}
+		for (const [key, child] of current.children) visit(child, prefix ? `${prefix}.${key}` : key);
+	};
+	visit(mask, null);
+	return paths;
+}
 function isCovered(mask, path) {
 	if (mask.all) return true;
 	const parts = path.split(".");
@@ -138,7 +438,7 @@ function intersects(a, b) {
 	return false;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@trpc+server@11.17.0_typescript@5.9.3/node_modules/@trpc/server/dist/getErrorShape-BPSzUA7W.mjs
+//#region ../../node_modules/.pnpm/@trpc+server@11.17.0_typescript@6.0.3/node_modules/@trpc/server/dist/getErrorShape-BPSzUA7W.mjs
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -264,41 +564,6 @@ __toESM(__commonJS({ "../../node_modules/.pnpm/@oxc-project+runtime@0.72.2/node_
 	module.exports = _objectSpread2, module.exports.__esModule = true, module.exports["default"] = module.exports;
 } })(), 1);
 //#endregion
-//#region src/types.ts
-/** Internal marker added to objects that represent a view payload. */
-const ViewKind = Symbol("__fate__view");
-/** Symbol used to attach the set of view tags that were spread into a ref or masked record. */
-const ViewsTag = Symbol("__fate__views");
-/** Symbol used to brand a value as a node reference inside the cache. */
-const NodeRefTag = Symbol("__fate__node-ref");
-/** Symbol attached to connection results so pagination helpers can find their metadata. */
-const ConnectionTag = Symbol("__fate__connection");
-const viewTag = "__fate-view__";
-/** Generates a stable view tag for a view definition. */
-function getViewTag(id) {
-	return `${viewTag}${id}`;
-}
-/** Determines whether a property key is a fate view tag. */
-function isViewTag(key) {
-	return key.startsWith(viewTag);
-}
-/** Indicates whether a request item represents an explicit node ID. */
-function isNodeItem(item) {
-	return "id" in item;
-}
-/** Indicates whether a request item represents explicit node IDs. */
-function isNodesItem(item) {
-	return "ids" in item;
-}
-/** Indicates whether a request item represents a root query. */
-function isQueryItem(item) {
-	return "view" in item && !("id" in item) && !("ids" in item);
-}
-/** Brand used on root definitions to mark their identity in the d.ts output. */
-const RootKind = "__fate__root";
-/** Brand used on mutation definitions to mark their identity in the d.ts output. */
-const MutationKind = "__fate__mutation";
-//#endregion
 //#region src/view.ts
 /**
 * Collects all view payloads that apply to the given ref.
@@ -455,6 +720,7 @@ const getSelectionPlan = (viewComposition, ref) => {
 				if (value) paths.add(path);
 				continue;
 			}
+			if (isDeferredSelection(value)) continue;
 			if (isViewTag(key)) {
 				if (!ref || ref[ViewsTag] && ref[ViewsTag].has(key)) walk(value.select, prefix);
 				continue;
@@ -492,6 +758,9 @@ const getSelectionPlan = (viewComposition, ref) => {
 		paths
 	};
 };
+const getDeferredSelectionPlan = (field, selection) => {
+	return getSelectionPlan({ [field]: selection }, null);
+};
 //#endregion
 //#region src/mutation.ts
 /**
@@ -593,7 +862,7 @@ function wrapMutation(client, identifier) {
 				client.clearOptimisticUpdate(optimisticToken);
 			}
 		};
-		const mutationPromise = performMutation();
+		const mutationPromise = client.trackPendingRequest(performMutation);
 		if (optimisticEntityId) client.registerPendingOptimisticMutation(optimisticEntityId, mutationPromise);
 		return mutationPromise;
 	};
@@ -621,24 +890,6 @@ const categorizeHTTPErrorStatus = (statusCode) => {
 	}
 };
 //#endregion
-//#region src/node-ref.ts
-function createNodeRef(id) {
-	const ref = {};
-	Object.defineProperty(ref, NodeRefTag, {
-		configurable: false,
-		enumerable: false,
-		value: id,
-		writable: false
-	});
-	return Object.freeze(ref);
-}
-function isNodeRef(value) {
-	return !value || typeof value !== "object" ? false : NodeRefTag in value;
-}
-function getNodeRefId(ref) {
-	return ref[NodeRefTag];
-}
-//#endregion
 //#region src/operation-lifetime.ts
 var OperationLifetime = class {
 	constructor(releaseBufferSize) {
@@ -726,6 +977,45 @@ const cloneValue = (value) => {
 	}
 	return value;
 };
+const isPlainRecord = (value) => {
+	if (value == null || typeof value !== "object" || Array.isArray(value) || isNodeRef(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+const isDate = (value) => value != null && typeof value === "object" && Object.prototype.toString.call(value) === "[object Date]" && typeof value.getTime === "function";
+const mergePreservingExisting = (incoming, existing) => {
+	if (!isPlainRecord(incoming) || !isPlainRecord(existing)) return existing;
+	const result = Object.create(null);
+	for (const [key, value] of Object.entries(incoming)) Object.defineProperty(result, key, {
+		configurable: true,
+		enumerable: true,
+		value,
+		writable: true
+	});
+	for (const [key, value] of Object.entries(existing)) Object.defineProperty(result, key, {
+		configurable: true,
+		enumerable: true,
+		value: Object.hasOwn(result, key) ? mergePreservingExisting(result[key], value) : value,
+		writable: true
+	});
+	return result;
+};
+const areHydrationValuesEqual = (left, right) => {
+	if (Object.is(left, right)) return true;
+	if (isNodeRef(left) || isNodeRef(right)) return isNodeRef(left) && isNodeRef(right) && getNodeRefId(left) === getNodeRefId(right);
+	if (isDate(left) || isDate(right)) return isDate(left) && isDate(right) && left.getTime() === right.getTime();
+	if (Array.isArray(left) || Array.isArray(right)) return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((value, index) => areHydrationValuesEqual(value, right[index]));
+	if (!isPlainRecord(left) || !isPlainRecord(right)) return false;
+	const leftKeys = Object.keys(left);
+	const rightKeys = Object.keys(right);
+	return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && areHydrationValuesEqual(left[key], right[key]));
+};
+const areMasksEqual = (left, right) => {
+	if (!left || !right) return left === right;
+	const leftPaths = toPaths(left).sort();
+	const rightPaths = toPaths(right).sort();
+	return leftPaths.length === rightPaths.length && leftPaths.every((path, index) => path === rightPaths[index]);
+};
 const emptyFunction = () => {};
 var Store = class {
 	constructor() {
@@ -739,6 +1029,58 @@ var Store = class {
 		this.subscriptions = /* @__PURE__ */ new Map();
 		this.listSubscriptions = /* @__PURE__ */ new Map();
 	}
+	dehydrate() {
+		return {
+			coverage: [...this.coverage].map(([id, mask]) => [id, toPaths(mask)]),
+			lists: [...this.lists],
+			records: [...this.records]
+		};
+	}
+	hydrate(state, mode, options = {}) {
+		const previousCoverage = this.coverage;
+		const previousLists = this.lists;
+		const previousRecords = this.records;
+		const coverage = mode === "replace" ? /* @__PURE__ */ new Map() : new Map([...previousCoverage].map(([id, mask]) => [id, cloneMask(mask)]));
+		const lists = mode === "replace" ? /* @__PURE__ */ new Map() : new Map(previousLists);
+		const records = mode === "replace" ? /* @__PURE__ */ new Map() : new Map(previousRecords);
+		for (const [id, incoming] of state.records) {
+			const previous = records.get(id);
+			const next = previous && mode === "preserve-existing" ? mergePreservingExisting(incoming, previous) : incoming;
+			records.set(id, previous && areHydrationValuesEqual(previous, next) ? previous : next);
+		}
+		for (const [id, paths] of state.coverage) {
+			const incoming = fromPaths(paths);
+			const previous = coverage.get(id);
+			if (previous && mode === "preserve-existing") union(previous, incoming);
+			else coverage.set(id, incoming);
+		}
+		for (const [key, list] of state.lists) {
+			const previous = lists.get(key);
+			if (mode === "replace" || !previous) lists.set(key, previous && areHydrationValuesEqual(previous, list) ? previous : list);
+		}
+		this.coverage = coverage;
+		this.lists = lists;
+		this.records = records;
+		this.rebuildIndexes();
+		const changedRecordIds = /* @__PURE__ */ new Set();
+		for (const id of new Set([...previousRecords.keys(), ...records.keys()])) if (!areHydrationValuesEqual(previousRecords.get(id), records.get(id)) || !areMasksEqual(previousCoverage.get(id), coverage.get(id))) changedRecordIds.add(id);
+		const changedListKeys = /* @__PURE__ */ new Set();
+		for (const key of new Set([...previousLists.keys(), ...lists.keys()])) if (!areHydrationValuesEqual(previousLists.get(key), lists.get(key))) changedListKeys.add(key);
+		const notify = () => {
+			for (const id of changedRecordIds) this.notify(id);
+			for (const key of changedListKeys) this.notifyListSubscribers(key);
+		};
+		if (!options.deferNotifications) notify();
+		return notify;
+	}
+	rebuildIndexes() {
+		this.listKeysByOwnerField.clear();
+		this.listKeysByReferencedEntity.clear();
+		this.recordReferenceFields.clear();
+		this.recordReferencesByTarget.clear();
+		for (const [id, record] of this.records) this.addRecordReferenceIndexes(id, record);
+		for (const [key, list] of this.lists) this.addListIndexes(key, list);
+	}
 	read(id) {
 		return this.records.get(id);
 	}
@@ -1337,6 +1679,14 @@ const getId = (record) => {
 };
 const emptySet = /* @__PURE__ */ new Set();
 const emptyDispose = () => void 0;
+const compareStrings = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const getDefaultHydrationScope = (roots, types) => JSON.stringify({
+	roots: Object.entries(roots ?? {}).map(([name, root]) => [name, root.type]).sort(([left], [right]) => compareStrings(left, right)),
+	types: types.map(({ fields, type }) => ({
+		fields: Object.entries(fields ?? {}).map(([field, descriptor]) => [field, descriptor]).sort(([left], [right]) => compareStrings(left, right)),
+		type
+	})).sort((left, right) => compareStrings(left.type, right.type))
+});
 const dropCanonicalListIds = (listIds, ids) => {
 	if (!listIds || listIds.length === 0) return;
 	const canonicalIds = new Set(ids);
@@ -1464,6 +1814,7 @@ var FateClient = class {
 		this.parentLists = /* @__PURE__ */ new Map();
 		this.rootLists = /* @__PURE__ */ new Map();
 		this.pending = /* @__PURE__ */ new Map();
+		this.pendingDeferred = /* @__PURE__ */ new Map();
 		this.pendingOptimisticMutations = /* @__PURE__ */ new Map();
 		this.optimisticMasks = /* @__PURE__ */ new Map();
 		this.optimisticByEntity = /* @__PURE__ */ new Map();
@@ -1477,6 +1828,7 @@ var FateClient = class {
 		this.stalledRequests = /* @__PURE__ */ new Set();
 		this.gcPending = false;
 		this.gcScheduled = false;
+		this.pendingNetworkRequests = 0;
 		this.store = new Store();
 		this.viewDataCache = new ViewDataCache();
 		this.liveConnectionInvalidationToken = 0;
@@ -1485,6 +1837,10 @@ var FateClient = class {
 		this.mutations = Object.create(null);
 		this.onLiveError = options.onLiveError;
 		this.operationLifetime = new OperationLifetime(options.gcReleaseBufferSize ?? 10);
+		this.hydrationLimits = resolveHydrationLimits(options.hydrationLimits);
+		const hydrationScope = options.hydrationScope ?? getDefaultHydrationScope(options.roots, options.types);
+		if (typeof hydrationScope !== "string" || hydrationScope.length === 0) throw new Error(`fate: Hydration scope must be a non-empty string.`);
+		this.hydrationScope = hydrationScope;
 		this.roots = options.roots;
 		this.transport = options.transport;
 		this.types = new Map(options.types.map((entity) => [entity.type, {
@@ -1529,6 +1885,56 @@ var FateClient = class {
 			}
 		}
 	}
+	/**
+	* Exports the durable normalized cache as an opaque JSON-safe value for SSR
+	* transfer or persistence. Runtime requests, subscriptions, retainers, and
+	* optimistic state are intentionally excluded.
+	*/
+	dehydrate() {
+		if (this.hasActiveOptimisticUpdates()) throw new Error(`fate: Cannot dehydrate while optimistic updates are active.`);
+		if (this.hasPendingRequests()) throw new Error(`fate: Cannot dehydrate while requests are pending.`);
+		return {
+			data: encodeHydrationValue({
+				rootLists: [...this.rootLists].map(([type, keys]) => [type, [...keys]]),
+				rootRequests: [...this.rootRequests],
+				store: this.store.dehydrate()
+			}, this.hydrationLimits),
+			scope: this.hydrationScope,
+			version: 1
+		};
+	}
+	/**
+	* Restores a durable normalized cache snapshot without restoring runtime
+	* request handles, retainers, subscriptions, or optimistic update state.
+	* Hydrate before rendering SSR content. Replaying the same snapshot is safe.
+	*/
+	hydrate(state, options = {}) {
+		if (!state || typeof state !== "object" || state.version !== 1) throw new Error(`fate: Unsupported hydration state version.`);
+		if (state.scope !== this.hydrationScope) throw new Error(`fate: Hydration state scope does not match this client.`);
+		if (this.hasActiveOptimisticUpdates()) throw new Error(`fate: Cannot hydrate while optimistic updates are active.`);
+		if (this.hasPendingRequests()) throw new Error(`fate: Cannot hydrate while requests are pending.`);
+		const mode = options.merge ?? "preserve-existing";
+		if (mode !== "preserve-existing" && mode !== "replace") throw new Error(`fate: Unsupported hydration merge mode.`);
+		const decoded = decodeClientHydrationState(state.data, this.hydrationLimits);
+		const notify = this.store.hydrate(decoded.store, mode, { deferNotifications: true });
+		if (mode === "replace") {
+			this.rootLists.clear();
+			this.rootRequests.clear();
+			this.stableRefs.clear();
+		}
+		for (const [type, incomingKeys] of decoded.rootLists) {
+			let keys = this.rootLists.get(type);
+			if (!keys) {
+				keys = /* @__PURE__ */ new Set();
+				this.rootLists.set(type, keys);
+			}
+			for (const key of incomingKeys) keys.add(key);
+		}
+		for (const [key, entityId] of decoded.rootRequests) if (mode === "replace" || !this.rootRequests.has(key)) this.rootRequests.set(key, entityId);
+		this.stalledRequests.clear();
+		this.viewDataCache.clear();
+		notify();
+	}
 	registerRootList(type, key) {
 		let lists = this.rootLists.get(type);
 		if (!lists) {
@@ -1597,7 +2003,7 @@ var FateClient = class {
 			...baseRecord,
 			args: argsPayload
 		} : argsPayload ? { args: argsPayload } : input;
-		return await this.transport.mutate(key, requestInput, select);
+		return await this.trackPendingRequest(() => this.transport.mutate(key, requestInput, select));
 	}
 	write(type, data, select, snapshots, plan, pathPrefix = null, blockedMask, insert, listSnapshots) {
 		return this.writeEntity(type, data, select, snapshots, plan, pathPrefix, blockedMask, insert, listSnapshots);
@@ -1690,19 +2096,81 @@ var FateClient = class {
 			if (this.stalledRequests.has(key)) return resolveSnapshot();
 			const pendingPromise = this.pending.get(key) || null;
 			if (pendingPromise) return pendingPromise;
-			const promise = this.fetchByIdAndNormalize(type, [id], missing, plan).finally(() => this.pending.delete(key)).then(() => {
-				if (this.store.missingForSelection(entityId, selectedPaths).size > 0) {
-					this.stalledRequests.add(key);
-					return resolveSnapshot();
+			const promise = this.trackPendingRequest(async () => {
+				await this.fetchByIdAndNormalize(type, [id], missing, plan);
+				try {
+					if (this.store.missingForSelection(entityId, selectedPaths).size > 0) {
+						this.stalledRequests.add(key);
+						return resolveSnapshot();
+					}
+					this.stalledRequests.delete(key);
+					return this.readView(view, ref);
+				} finally {
+					this.pending.delete(key);
 				}
-				this.stalledRequests.delete(key);
-				return this.readView(view, ref);
 			});
 			this.pending.set(key, promise);
 			return promise;
 		}
 		return resolveSnapshot();
 	}
+	readDeferred(deferred) {
+		const metadata = getDeferredMetadata(deferred);
+		const resolvedOwner = this.optimisticEntityResolutions.get(metadata.owner) ?? metadata.owner;
+		const parsedOwner = parseEntityId(resolvedOwner);
+		const ownerRecord = this.store.read(resolvedOwner);
+		const rawOwnerId = ownerRecord && (typeof ownerRecord.id === "string" || typeof ownerRecord.id === "number") ? ownerRecord.id : parsedOwner.id;
+		const ownerType = parsedOwner.type || metadata.type;
+		const plan = getDeferredSelectionPlan(metadata.field, metadata.selection);
+		const selectedPaths = plan.paths;
+		const missing = this.store.missingForSelection(resolvedOwner, selectedPaths);
+		const hasMissingList = () => this.hasMissingDeferredList(resolvedOwner, ownerType, metadata.field, plan);
+		const listMissing = hasMissingList();
+		const fetchPaths = listMissing ? selectedPaths : missing;
+		const resolveSnapshot = () => {
+			const snapshot = this.readViewSelection({ [metadata.field]: metadata.selection }, this.stableRefWithViewNames(ownerType, rawOwnerId, /* @__PURE__ */ new Set()), resolvedOwner, plan);
+			const resolved = {
+				coverage: snapshot.coverage,
+				data: snapshot.data[metadata.field]
+			};
+			return {
+				status: "fulfilled",
+				then: (onfulfilled, onrejected) => Promise.resolve(resolved).then(onfulfilled, onrejected),
+				value: resolved
+			};
+		};
+		if (missing.size === 0 && !listMissing) {
+			this.clearStalledRequestsForEntity(resolvedOwner);
+			return resolveSnapshot();
+		}
+		const key = this.deferredPendingKey(resolvedOwner, fetchPaths, plan, this.deferredSelectionSignature(metadata.selection));
+		if (this.stalledRequests.has(key)) return resolveSnapshot();
+		const pendingOptimistic = this.getPendingOptimisticMutations(resolvedOwner);
+		if (pendingOptimistic) {
+			const pending = this.pendingDeferred.get(key);
+			if (pending) return pending;
+			const promise = Promise.all(pendingOptimistic).then(() => this.readDeferred(deferred)).finally(() => this.pendingDeferred.delete(key));
+			this.pendingDeferred.set(key, promise);
+			return promise;
+		}
+		const pendingPromise = this.pendingDeferred.get(key) || null;
+		if (pendingPromise) return pendingPromise;
+		const promise = this.trackPendingRequest(async () => {
+			try {
+				await this.fetchByIdAndNormalize(ownerType, [rawOwnerId], fetchPaths, plan);
+				if (this.store.missingForSelection(resolvedOwner, selectedPaths).size > 0 || hasMissingList()) {
+					this.stalledRequests.add(key);
+					return resolveSnapshot().value;
+				}
+				this.stalledRequests.delete(key);
+				return this.readDeferred(deferred).value;
+			} finally {
+				this.pendingDeferred.delete(key);
+			}
+		});
+		this.pendingDeferred.set(key, promise);
+		return promise;
+	}
 	assertLiveViewSupport() {
 		if (!this.transport.subscribeById) throw new Error(`fate: transport does not support live views. Please provide a 'subscribeById' implementation in your transport.`);
 	}
@@ -2134,6 +2602,9 @@ var FateClient = class {
 		return filtered;
 	}
 	async loadConnection(view, connection, args, options = {}) {
+		return await this.trackPendingRequest(() => this.loadConnectionInternal(view, connection, args, options));
+	}
+	async loadConnectionInternal(view, connection, args, options = {}) {
 		const direction = options.direction ?? "forward";
 		if (connection.root) {
 			if (!this.transport.fetchList) throw new Error(`fate: transport does not support list fetching. Please add support for 'fetchList' in your transport.`);
@@ -2379,6 +2850,17 @@ var FateClient = class {
 	hasActiveOptimisticUpdates() {
 		return this.optimisticMasks.size > 0 || this.optimisticByEntity.size > 0 || this.pendingOptimisticMutations.size > 0;
 	}
+	hasPendingRequests() {
+		return this.pendingNetworkRequests > 0;
+	}
+	async trackPendingRequest(request) {
+		this.pendingNetworkRequests += 1;
+		try {
+			return await request();
+		} finally {
+			this.pendingNetworkRequests -= 1;
+		}
+	}
 	runPendingGarbageCollection() {
 		if (this.gcPending && !this.hasActiveOptimisticUpdates()) this.gc();
 	}
@@ -2531,35 +3013,41 @@ var FateClient = class {
 	}
 	async fetchByIdAndNormalize(type, ids, select, plan, prefix = null) {
 		const resolvedArgs = resolvedArgsFromPlan(plan);
-		const records = await this.transport.fetchById(type, ids, select, resolvedArgs);
-		for (const record of records) this.writeEntity(type, record, select, void 0, plan, prefix);
+		await this.trackPendingRequest(async () => {
+			const records = await this.transport.fetchById(type, ids, select, resolvedArgs);
+			for (const record of records) this.writeEntity(type, record, select, void 0, plan, prefix);
+		});
 	}
 	async fetchQueryAndNormalize(item) {
 		if (!this.transport.fetchQuery) throw new Error(`fate: transport does not support queries. Please add support for 'fetchQuery' in your transport for '${item.name}'.`);
-		const record = await this.transport.fetchQuery(item.name, item.plan.paths, item.argsPayload);
-		if (!record || typeof record !== "object") {
-			this.rootRequests.set(item.queryKey, null);
-			return;
-		}
-		const entityId = this.writeEntity(item.type, record, item.plan.paths, void 0, item.plan);
-		this.rootRequests.set(item.queryKey, entityId);
+		await this.trackPendingRequest(async () => {
+			const record = await this.transport.fetchQuery(item.name, item.plan.paths, item.argsPayload);
+			if (!record || typeof record !== "object") {
+				this.rootRequests.set(item.queryKey, null);
+				return;
+			}
+			const entityId = this.writeEntity(item.type, record, item.plan.paths, void 0, item.plan);
+			this.rootRequests.set(item.queryKey, entityId);
+		});
 	}
 	async fetchListAndNormalize(item) {
 		if (!this.transport.fetchList) throw new Error(`fate: 'transport.fetchList' is not configured but request includes a list for key '${item.name}'.`);
-		const { items, pagination } = await this.transport.fetchList(item.name, item.plan.paths, item.argsPayload);
-		const ids = [];
-		const cursors = [];
-		for (const entry of items) {
-			const id = this.writeEntity(item.type, entry.node, item.plan.paths, void 0, item.plan);
-			ids.push(id);
-			cursors.push(entry.cursor);
-		}
-		if (!filterConnectionArgs(item.argsPayload)) this.registerRootList(item.type, item.listKey);
-		const previous = this.store.getListState(item.listKey);
-		this.store.setList(item.listKey, this.mergeListState(previous, ids, cursors, pagination, {
-			...getPaginationMergeInfo(item.argsPayload),
-			replace: true
-		}));
+		await this.trackPendingRequest(async () => {
+			const { items, pagination } = await this.transport.fetchList(item.name, item.plan.paths, item.argsPayload);
+			const ids = [];
+			const cursors = [];
+			for (const entry of items) {
+				const id = this.writeEntity(item.type, entry.node, item.plan.paths, void 0, item.plan);
+				ids.push(id);
+				cursors.push(entry.cursor);
+			}
+			if (!filterConnectionArgs(item.argsPayload)) this.registerRootList(item.type, item.listKey);
+			const previous = this.store.getListState(item.listKey);
+			this.store.setList(item.listKey, this.mergeListState(previous, ids, cursors, pagination, {
+				...getPaginationMergeInfo(item.argsPayload),
+				replace: true
+			}));
+		});
 	}
 	writeEntity(type, record, select, snapshots, plan, pathPrefix = null, blockedMask, insert, listSnapshots) {
 		const config = this.types.get(type);
@@ -2726,8 +3214,20 @@ var FateClient = class {
 					target[ViewsTag].add(key);
 					continue;
 				}
-				coverageById.set(parentId, (coverageById.get(parentId) ?? /* @__PURE__ */ new Set()).add(key));
 				const fieldPath = prefix ? `${prefix}.${key}` : key;
+				if (isDeferredSelection(selectionKind)) {
+					const { id, type } = parseEntityId(parentId);
+					coverageById.set(parentId, (coverageById.get(parentId) ?? /* @__PURE__ */ new Set()).add(key));
+					target[key] = createDeferred({
+						field: key,
+						id,
+						owner: parentId,
+						selection: getDeferredSelection(selectionKind),
+						type
+					});
+					continue;
+				}
+				coverageById.set(parentId, (coverageById.get(parentId) ?? /* @__PURE__ */ new Set()).add(key));
 				const selectionType = typeof selectionKind;
 				if (selectionType === "boolean" && selectionKind) target[key] = record[key];
 				else if (selectionKind && selectionType === "object") {
@@ -2846,7 +3346,9 @@ var FateClient = class {
 			}
 		};
 		const data = { __typename: parseEntityId(entityId).type };
-		for (const viewPayload of getViewPayloads(viewComposition, ref)) walk(viewPayload.select, record, data, entityId, pathPrefix);
+		const payloads = getViewPayloads(viewComposition, ref);
+		if (payloads.length === 0 && isRecord(viewComposition)) walk(viewComposition, record, data, entityId, pathPrefix);
+		else for (const viewPayload of payloads) walk(viewPayload.select, record, data, entityId, pathPrefix);
 		return {
 			coverage: [...coverageById.entries()],
 			data
@@ -2862,6 +3364,32 @@ var FateClient = class {
 	pendingKey(entityId, missingFields) {
 		return `${this.pendingPrefix(entityId)}${[...missingFields].sort().join("|")}`;
 	}
+	deferredPendingKey(entityId, fields, plan, selectionSignature) {
+		const args = [...plan.args.entries()].map(([path, entry]) => `${path}:${entry.hash}`).sort().join("|");
+		return `${this.pendingKey(entityId, new Set(fields))}|${args}|${selectionSignature}`;
+	}
+	deferredSelectionSignature(selection) {
+		const seen = /* @__PURE__ */ new Set();
+		const serialize = (value) => {
+			if (value === null || typeof value !== "object") return `${typeof value}:${String(value)}`;
+			if (seen.has(value)) return "[Circular]";
+			seen.add(value);
+			if (Array.isArray(value)) return `[${value.map((item) => serialize(item)).join(",")}]`;
+			return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => isViewTag(key) ? `view:${key}` : `${key}:${serialize(entry)}`).join(",")}}`;
+		};
+		return serialize(selection);
+	}
+	hasMissingDeferredList(owner, type, field, plan) {
+		const descriptor = this.types.get(type)?.fields?.[field];
+		if (!descriptor || descriptor === "scalar" || !("listOf" in descriptor)) return false;
+		const fieldArgs = plan.args.get(field);
+		const listState = this.store.getListState(getListKey(owner, field, fieldArgs?.hash));
+		if (!listState) return true;
+		const args = fieldArgs?.value;
+		const paginationArgs = getPaginationArgsInfo(args);
+		if (paginationArgs.hasCursorArg) return true;
+		return !hasConnectionPageCoverage(listState, args, paginationArgs.direction);
+	}
 	liveSubscriptionKey(entityId, plan) {
 		return `${entityId}|${[...plan.paths].sort().join("|")}|${[...plan.args.entries()].map(([path, entry]) => `${path}:${entry.hash}`).sort().join("|")}`;
 	}
@@ -3396,4 +3924,4 @@ function clientRoot(type) {
 	});
 }
 //#endregion
-export { ConnectionTag, FateClient, clientRoot, createClient, createHTTPTransport, createTRPCTransport, getListEntries, getSelectionPlan, isRecord, isViewTag, liveConnectionTopic, liveEntityTopic, liveGlobalConnectionTopic, mutation, toEntityId, view };
+export { ConnectionTag, DeferTag, DeferredTag, FateClient, clientRoot, createClient, createGraphQLTransport, createHTTPTransport, createTRPCTransport, defer, getDeferredMetadata, getListEntries, getSelectionPlan, graphqlMutation, isDeferred, isRecord, isViewTag, liveConnectionTopic, liveEntityTopic, liveGlobalConnectionTopic, mutation, toEntityId, view };