@mearie/core 0.1.2 → 0.2.0

package/dist/{index.js → index.mjs}

@@ -1,4 +1,4 @@
-import { C as share, S as mergeMap, _ as fromArray, a as finalize, b as fromPromise, c as takeUntil, i as fromValue, n as fromSubscription, o as initialize, r as makeSubject, s as switchMap, t as make, u as map, v as tap, w as pipe, x as filter, y as merge } from "./stream-DiNE6b2z.js";
+import { C as mergeMap, S as filter, a as finalize, b as merge, c as share, d as map, i as fromValue, l as takeUntil, m as collect, n as fromSubscription, o as initialize, r as makeSubject, s as switchMap, t as make, u as take, v as fromArray, w as pipe, x as fromPromise, y as tap } from "./make-C7I1YIXm.mjs";
 
 //#region src/errors.ts
 /**
@@ -74,30 +74,14 @@ const isAggregatedError = (error) => {
 	return error instanceof AggregatedError;
 };
 
-//#endregion
-//#region src/exchanges/compose.ts
-const composeExchange = (options) => {
-	const { exchanges } = options;
-	return ({ forward, client }) => {
-		return exchanges.reduceRight((forward$1, exchange) => {
-			return (ops$) => {
-				return pipe(ops$, share(), exchange({
-					forward: forward$1,
-					client
-				}), share());
-			};
-		}, forward);
-	};
-};
-
 //#endregion
 //#region src/exchanges/http.ts
-const executeFetch = async ({ url, fetchOptions, operation, signal }) => {
+const executeFetch = async ({ url, fetchFn, fetchOptions, operation, signal }) => {
 	const { artifact, variables } = operation;
 	let response;
 	try {
 		await Promise.resolve();
-		response = await fetch(url, {
+		response = await fetchFn(url, {
 			method: "POST",
 			mode: fetchOptions.mode,
 			credentials: fetchOptions.credentials,
@@ -152,9 +136,10 @@ const executeFetch = async ({ url, fetchOptions, operation, signal }) => {
 	};
 };
 const httpExchange = (options) => {
-	const { url, headers, mode, credentials } = options;
-	return ({ forward }) => {
-		return (ops$) => {
+	const { url, headers, mode, credentials, fetch: fetchFn = globalThis.fetch } = options;
+	return ({ forward }) => ({
+		name: "http",
+		io: (ops$) => {
 			const inflight = /* @__PURE__ */ new Map();
 			return merge(pipe(ops$, filter((op) => op.variant === "request" && (op.artifact.kind === "query" || op.artifact.kind === "mutation")), mergeMap((op) => {
 				inflight.get(op.key)?.abort();
@@ -162,6 +147,7 @@ const httpExchange = (options) => {
 				inflight.set(op.key, controller);
 				return fromPromise(executeFetch({
 					url,
+					fetchFn,
 					fetchOptions: {
 						mode,
 						credentials,
@@ -179,8 +165,8 @@ const httpExchange = (options) => {
 					inflight.delete(op.key);
 				}
 			}), forward));
-		};
-	};
+		}
+	});
 };
 
 //#endregion
@@ -247,7 +233,7 @@ const stringify = (value) => {
 * @param value - Value to check.
 * @returns True if the value is nullish.
 */
-const isNullish = (value) => {
+const isNullish$1 = (value) => {
 	return value === void 0 || value === null;
 };
 
@@ -272,8 +258,9 @@ const makeDedupKey = (op) => {
 * @returns An exchange that deduplicates in-flight operations.
 */
 const dedupExchange = () => {
-	return ({ forward }) => {
-		return (ops$) => {
+	return ({ forward }) => ({
+		name: "dedup",
+		io: (ops$) => {
 			const operations = /* @__PURE__ */ new Map();
 			return pipe(merge(pipe(ops$, filter((op) => op.variant === "request" && (op.artifact.kind === "mutation" || op.artifact.kind === "fragment"))), pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind !== "mutation" && op.artifact.kind !== "fragment"), filter((op) => {
 				const dedupKey = makeDedupKey(op);
@@ -301,8 +288,8 @@ const dedupExchange = () => {
 					}
 				})));
 			}));
-		};
-	};
+		}
+	});
 };
 
 //#endregion
@@ -361,6 +348,15 @@ const makeFieldKey = (selection, variables) => {
 	return `${selection.name}@${args}`;
 };
 /**
+* Generates a unique key for tracking memoized denormalized results for structural sharing.
+* @internal
+* @param kind - The operation kind ('query', 'fragment', 'fragments').
+* @param name - The artifact name.
+* @param id - Serialized identifier (variables, entity key, etc.).
+* @returns A unique memo key.
+*/
+const makeMemoKey = (kind, name, id) => `${kind}:${name}:${id}`;
+/**
 * Gets a unique key for tracking a field dependency.
 * @internal
 * @param storageKey Storage key (entity or root query key).
@@ -389,46 +385,166 @@ const isFragmentRef = (value) => {
 	return typeof value === "object" && value !== null && FragmentRefKey in value;
 };
 /**
+* Type guard to check if a value is an array of fragment references.
+* @internal
+* @param value - Value to check.
+* @returns True if the value is a FragmentRef array.
+*/
+const isFragmentRefArray = (value) => {
+	return Array.isArray(value) && value.length > 0 && isFragmentRef(value[0]);
+};
+/**
 * Type guard to check if a value is nullish.
 * @internal
 * @param value - Value to check.
 * @returns True if the value is nullish.
 */
-const isNullish$1 = (value) => {
+const isNullish = (value) => {
 	return value === void 0 || value === null;
 };
+/**
+* Deep equality check for normalized cache values.
+* Handles scalars, arrays, and plain objects (entity links, value objects).
+* @internal
+*/
+const isEqual = (a, b) => {
+	if (a === b) return true;
+	if (typeof a !== typeof b || a === null || b === null) return false;
+	if (Array.isArray(a)) {
+		if (!Array.isArray(b) || a.length !== b.length) return false;
+		for (const [i, item] of a.entries()) if (!isEqual(item, b[i])) return false;
+		return true;
+	}
+	if (typeof a === "object") {
+		const aObj = a;
+		const bObj = b;
+		const aKeys = Object.keys(aObj);
+		if (aKeys.length !== Object.keys(bObj).length) return false;
+		for (const key of aKeys) if (!isEqual(aObj[key], bObj[key])) return false;
+		return true;
+	}
+	return false;
+};
+/**
+* Recursively replaces a new value tree with the previous one wherever structurally equal,
+* preserving referential identity for unchanged subtrees.
+*
+* Returns `prev` (same reference) when the entire subtree is structurally equal.
+* @internal
+*/
+const replaceEqualDeep = (prev, next) => {
+	if (prev === next) return prev;
+	if (typeof prev !== typeof next || prev === null || next === null || typeof prev !== "object") return next;
+	if (Array.isArray(prev)) {
+		if (!Array.isArray(next)) return next;
+		let allSame = prev.length === next.length;
+		const result = [];
+		for (const [i, item] of next.entries()) {
+			const shared = i < prev.length ? replaceEqualDeep(prev[i], item) : item;
+			result.push(shared);
+			if (shared !== prev[i]) allSame = false;
+		}
+		return allSame ? prev : result;
+	}
+	if (Array.isArray(next)) return next;
+	const prevObj = prev;
+	const nextObj = next;
+	const nextKeys = Object.keys(nextObj);
+	const prevKeys = Object.keys(prevObj);
+	let allSame = nextKeys.length === prevKeys.length;
+	const result = {};
+	for (const key of nextKeys) if (key in prevObj) {
+		result[key] = replaceEqualDeep(prevObj[key], nextObj[key]);
+		if (result[key] !== prevObj[key]) allSame = false;
+	} else {
+		result[key] = nextObj[key];
+		allSame = false;
+	}
+	return allSame ? prev : result;
+};
+/**
+* Deeply merges two values. Objects are recursively merged, arrays are element-wise merged,
+* entity links and primitives use last-write-wins.
+* @internal
+*/
+const mergeFieldValue = (existing, incoming) => {
+	if (isNullish(existing) || isNullish(incoming)) return incoming;
+	if (typeof existing !== "object" || typeof incoming !== "object") return incoming;
+	if (isEntityLink(existing) || isEntityLink(incoming)) return incoming;
+	if (Array.isArray(existing) && Array.isArray(incoming)) return incoming.map((item, i) => i < existing.length ? mergeFieldValue(existing[i], item) : item);
+	if (Array.isArray(existing) || Array.isArray(incoming)) return incoming;
+	mergeFields(existing, incoming);
+	return existing;
+};
+/**
+* Deeply merges source fields into target. Objects are recursively merged,
+* arrays are element-wise merged, entity links and primitives use last-write-wins.
+* @internal
+*/
+const mergeFields = (target, source) => {
+	if (isNullish(source) || typeof source !== "object" || Array.isArray(source)) return;
+	for (const key of Object.keys(source)) target[key] = mergeFieldValue(target[key], source[key]);
+};
+/**
+* Creates a FieldKey from a raw field name and optional arguments.
+* @internal
+* @param field - The field name.
+* @param args - Optional argument values.
+* @returns A FieldKey in "field@args" format.
+*/
+const makeFieldKeyFromArgs = (field, args) => {
+	return `${field}@${args && Object.keys(args).length > 0 ? stringify(args) : "{}"}`;
+};
+/**
+* Converts an EntityId to an EntityKey.
+* @internal
+* @param typename - The GraphQL typename of the entity.
+* @param id - The entity identifier (string, number, or composite key record).
+* @param keyFields - Optional ordered list of key field names for composite keys.
+* @returns An EntityKey.
+*/
+const resolveEntityKey = (typename, id, keyFields) => {
+	if (typeof id === "string" || typeof id === "number") return makeEntityKey(typename, [id]);
+	return makeEntityKey(typename, keyFields ? keyFields.map((f) => id[f]) : Object.values(id));
+};
 
 //#endregion
 //#region src/cache/normalize.ts
+const SKIP = Symbol();
 const normalize = (schemaMeta, selections, storage, data, variables, accessor) => {
-	const normalizeField = (storageKey, selections$1, value) => {
-		if (isNullish$1(value)) return value;
-		if (Array.isArray(value)) return value.map((item) => normalizeField(storageKey, selections$1, item));
-		const data$1 = value;
-		const typename = data$1.__typename;
+	const normalizeField = (storageKey, selections, value) => {
+		if (isNullish(value)) return value;
+		if (Array.isArray(value)) return value.map((item) => normalizeField(storageKey, selections, item));
+		const data = value;
+		const typename = data.__typename;
 		const entityMeta = schemaMeta.entities[typename];
-		if (entityMeta) storageKey = makeEntityKey(typename, entityMeta.keyFields.map((field) => data$1[field]));
-		const fields$1 = {};
-		for (const selection of selections$1) if (selection.kind === "Field") {
+		if (entityMeta) {
+			const keys = entityMeta.keyFields.map((field) => data[field]);
+			if (!keys.every((k) => k !== void 0 && k !== null)) return SKIP;
+			storageKey = makeEntityKey(typename, keys);
+		}
+		const fields = {};
+		for (const selection of selections) if (selection.kind === "Field") {
 			const fieldKey = makeFieldKey(selection, variables);
-			const fieldValue = data$1[selection.alias ?? selection.name];
-			if (storageKey !== null) {
-				const oldValue = storage[storageKey]?.[fieldKey];
-				if (!selection.selections || isNullish$1(oldValue) || isNullish$1(fieldValue)) accessor?.(storageKey, fieldKey, oldValue, fieldValue);
-			}
-			fields$1[fieldKey] = selection.selections ? normalizeField(null, selection.selections, fieldValue) : fieldValue;
+			const fieldValue = data[selection.alias ?? selection.name];
+			const oldValue = storageKey === null ? void 0 : storage[storageKey]?.[fieldKey];
+			if (storageKey !== null && (!selection.selections || isNullish(oldValue) || isNullish(fieldValue))) accessor?.(storageKey, fieldKey, oldValue, fieldValue);
+			const normalized = selection.selections ? normalizeField(null, selection.selections, fieldValue) : fieldValue;
+			if (normalized === SKIP) continue;
+			fields[fieldKey] = normalized;
+			if (storageKey !== null && selection.selections && !isNullish(oldValue) && !isNullish(fieldValue) && !isEntityLink(fields[fieldKey]) && !isEqual(oldValue, fields[fieldKey])) accessor?.(storageKey, fieldKey, oldValue, fields[fieldKey]);
 		} else if (selection.kind === "FragmentSpread" || selection.kind === "InlineFragment" && selection.on === typename) {
 			const inner = normalizeField(storageKey, selection.selections, value);
-			if (!isEntityLink(inner)) Object.assign(fields$1, inner);
+			if (inner !== SKIP && !isEntityLink(inner)) mergeFields(fields, inner);
 		}
 		if (entityMeta && storageKey !== null) {
 			storage[storageKey] = {
 				...storage[storageKey],
-				...fields$1
+				...fields
 			};
 			return { [EntityLinkKey]: storageKey };
 		}
-		return fields$1;
+		return fields;
 	};
 	const fields = normalizeField(RootFieldKey, selections, data);
 	storage[RootFieldKey] = {
@@ -446,10 +562,10 @@ const typenameFieldKey = makeFieldKey({
 }, {});
 const denormalize = (selections, storage, value, variables, accessor) => {
 	let partial = false;
-	const denormalizeField = (storageKey, selections$1, value$1) => {
-		if (isNullish$1(value$1)) return value$1;
-		if (Array.isArray(value$1)) return value$1.map((item) => denormalizeField(storageKey, selections$1, item));
-		const data = value$1;
+	const denormalizeField = (storageKey, selections, value) => {
+		if (isNullish(value)) return value;
+		if (Array.isArray(value)) return value.map((item) => denormalizeField(storageKey, selections, item));
+		const data = value;
 		if (isEntityLink(data)) {
 			const entityKey = data[EntityLinkKey];
 			const entity = storage[entityKey];
@@ -458,10 +574,10 @@ const denormalize = (selections, storage, value, variables, accessor) => {
 				partial = true;
 				return null;
 			}
-			return denormalizeField(entityKey, selections$1, entity);
+			return denormalizeField(entityKey, selections, entity);
 		}
 		const fields = {};
-		for (const selection of selections$1) if (selection.kind === "Field") {
+		for (const selection of selections) if (selection.kind === "Field") {
 			const fieldKey = makeFieldKey(selection, variables);
 			const fieldValue = data[fieldKey];
 			if (storageKey !== null) accessor?.(storageKey, fieldKey);
@@ -469,10 +585,13 @@ const denormalize = (selections, storage, value, variables, accessor) => {
 				partial = true;
 				continue;
 			}
-			fields[selection.alias ?? selection.name] = selection.selections ? denormalizeField(null, selection.selections, fieldValue) : fieldValue;
+			const name = selection.alias ?? selection.name;
+			const value = selection.selections ? denormalizeField(null, selection.selections, fieldValue) : fieldValue;
+			if (name in fields) mergeFields(fields, { [name]: value });
+			else fields[name] = value;
 		} else if (selection.kind === "FragmentSpread") if (storageKey !== null && storageKey !== RootFieldKey) fields[FragmentRefKey] = storageKey;
-		else Object.assign(fields, denormalizeField(storageKey, selection.selections, value$1));
-		else if (selection.kind === "InlineFragment" && selection.on === data[typenameFieldKey]) Object.assign(fields, denormalizeField(storageKey, selection.selections, value$1));
+		else mergeFields(fields, denormalizeField(storageKey, selection.selections, value));
+		else if (selection.kind === "InlineFragment" && selection.on === data[typenameFieldKey]) mergeFields(fields, denormalizeField(storageKey, selection.selections, value));
 		return fields;
 	};
 	return {
@@ -491,6 +610,7 @@ var Cache = class {
 	#schemaMeta;
 	#storage = { [RootFieldKey]: {} };
 	#subscriptions = /* @__PURE__ */ new Map();
+	#memo = /* @__PURE__ */ new Map();
 	constructor(schemaMetadata) {
 		this.#schemaMeta = schemaMetadata;
 	}
@@ -517,13 +637,19 @@ var Cache = class {
 	}
 	/**
 	* Reads a query result from the cache, denormalizing entities if available.
+	* Uses structural sharing to preserve referential identity for unchanged subtrees.
 	* @param artifact - GraphQL document artifact.
 	* @param variables - Query variables.
 	* @returns Denormalized query result or null if not found.
 	*/
 	readQuery(artifact, variables) {
 		const { data, partial } = denormalize(artifact.selections, this.#storage, this.#storage[RootFieldKey], variables);
-		return partial ? null : data;
+		if (partial) return null;
+		const key = makeMemoKey("query", artifact.name, stringify(variables));
+		const prev = this.#memo.get(key);
+		const result = prev === void 0 ? data : replaceEqualDeep(prev, data);
+		this.#memo.set(key, result);
+		return result;
 	}
 	/**
 	* Subscribes to cache invalidations for a specific query.
@@ -542,8 +668,7 @@ var Cache = class {
 	}
 	/**
 	* Reads a fragment from the cache for a specific entity.
-	* Returns null for invalid or missing fragment references, making it safe for
-	* defensive reads. For subscriptions, use subscribeFragment which throws errors.
+	* Uses structural sharing to preserve referential identity for unchanged subtrees.
 	* @param artifact - GraphQL fragment artifact.
 	* @param fragmentRef - Fragment reference containing entity key.
 	* @returns Denormalized fragment data or null if not found or invalid.
@@ -552,7 +677,12 @@ var Cache = class {
 		const entityKey = fragmentRef[FragmentRefKey];
 		if (!this.#storage[entityKey]) return null;
 		const { data, partial } = denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {});
-		return partial ? null : data;
+		if (partial) return null;
+		const key = makeMemoKey("fragment", artifact.name, entityKey);
+		const prev = this.#memo.get(key);
+		const result = prev === void 0 ? data : replaceEqualDeep(prev, data);
+		this.#memo.set(key, result);
+		return result;
 	}
 	subscribeFragment(artifact, fragmentRef, listener) {
 		const entityKey = fragmentRef[FragmentRefKey];
@@ -563,6 +693,80 @@ var Cache = class {
 		});
 		return this.#subscribe(dependencies, listener);
 	}
+	readFragments(artifact, fragmentRefs) {
+		const results = [];
+		for (const ref of fragmentRefs) {
+			const data = this.readFragment(artifact, ref);
+			if (data === null) return null;
+			results.push(data);
+		}
+		const entityKeys = fragmentRefs.map((ref) => ref[FragmentRefKey]);
+		const key = makeMemoKey("fragments", artifact.name, entityKeys.join(","));
+		const prev = this.#memo.get(key);
+		const result = prev === void 0 ? results : replaceEqualDeep(prev, results);
+		this.#memo.set(key, result);
+		return result;
+	}
+	subscribeFragments(artifact, fragmentRefs, listener) {
+		const dependencies = /* @__PURE__ */ new Set();
+		for (const ref of fragmentRefs) {
+			const entityKey = ref[FragmentRefKey];
+			denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {}, (storageKey, fieldKey) => {
+				dependencies.add(makeDependencyKey(storageKey, fieldKey));
+			});
+		}
+		return this.#subscribe(dependencies, listener);
+	}
+	/**
+	* Invalidates one or more cache entries and notifies affected subscribers.
+	* @param targets - Cache entries to invalidate.
+	*/
+	invalidate(...targets) {
+		const subscriptions = /* @__PURE__ */ new Set();
+		for (const target of targets) if (target.__typename === "Query") if ("field" in target) {
+			const fieldKey = makeFieldKeyFromArgs(target.field, target.args);
+			delete this.#storage[RootFieldKey]?.[fieldKey];
+			this.#collectSubscriptions(RootFieldKey, fieldKey, subscriptions);
+		} else {
+			this.#storage[RootFieldKey] = {};
+			this.#collectSubscriptions(RootFieldKey, void 0, subscriptions);
+		}
+		else if ("id" in target) {
+			const entityKey = resolveEntityKey(target.__typename, target.id, this.#schemaMeta.entities[target.__typename]?.keyFields);
+			if ("field" in target) {
+				const fieldKey = makeFieldKeyFromArgs(target.field, target.args);
+				delete this.#storage[entityKey]?.[fieldKey];
+				this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
+			} else {
+				delete this.#storage[entityKey];
+				this.#collectSubscriptions(entityKey, void 0, subscriptions);
+			}
+		} else {
+			const prefix = `${target.__typename}:`;
+			for (const key of Object.keys(this.#storage)) if (key.startsWith(prefix)) {
+				const entityKey = key;
+				if ("field" in target) {
+					const fieldKey = makeFieldKeyFromArgs(target.field, target.args);
+					delete this.#storage[entityKey]?.[fieldKey];
+					this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
+				} else {
+					delete this.#storage[entityKey];
+					this.#collectSubscriptions(entityKey, void 0, subscriptions);
+				}
+			}
+		}
+		for (const subscription of subscriptions) subscription.listener();
+	}
+	#collectSubscriptions(storageKey, fieldKey, out) {
+		if (fieldKey === void 0) {
+			const prefix = `${storageKey}.`;
+			for (const [depKey, ss] of this.#subscriptions) if (depKey.startsWith(prefix)) for (const s of ss) out.add(s);
+		} else {
+			const depKey = makeDependencyKey(storageKey, fieldKey);
+			const ss = this.#subscriptions.get(depKey);
+			if (ss) for (const s of ss) out.add(s);
+		}
+	}
 	#subscribe(dependencies, listener) {
 		const subscription = { listener };
 		for (const dependency of dependencies) {
@@ -579,62 +783,134 @@ var Cache = class {
 		};
 	}
 	/**
+	* Extracts a serializable snapshot of the cache storage and structural sharing state.
+	*/
+	extract() {
+		return {
+			storage: structuredClone(this.#storage),
+			memo: Object.fromEntries(this.#memo)
+		};
+	}
+	/**
+	* Hydrates the cache with a previously extracted snapshot.
+	*/
+	hydrate(snapshot) {
+		const { storage, memo } = snapshot;
+		for (const [key, fields] of Object.entries(storage)) this.#storage[key] = {
+			...this.#storage[key],
+			...fields
+		};
+		for (const [key, value] of Object.entries(memo)) this.#memo.set(key, value);
+	}
+	/**
 	* Clears all cache data.
 	*/
 	clear() {
 		this.#storage = { [RootFieldKey]: {} };
 		this.#subscriptions.clear();
+		this.#memo.clear();
 	}
 };
 
+//#endregion
+//#region src/stream/sources/empty.ts
+/**
+* Creates a source that completes immediately without emitting any values.
+* @returns An empty source.
+*/
+const empty = () => {
+	return (sink) => {
+		sink.complete();
+		return { unsubscribe() {} };
+	};
+};
+
 //#endregion
 //#region src/exchanges/cache.ts
 const cacheExchange = (options = {}) => {
 	const { fetchPolicy = "cache-first" } = options;
 	return ({ forward, client }) => {
 		const cache = new Cache(client.schema);
-		return (ops$) => {
-			const fragment$ = pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind === "fragment"), mergeMap((op) => {
-				const fragmentRef = op.metadata?.fragmentRef;
-				if (!fragmentRef) return fromValue({
-					operation: op,
-					errors: [new ExchangeError("Fragment operation missing fragmentRef in metadata. This usually happens when the wrong fragment reference was passed.", { exchangeName: "cache" })]
-				});
-				if (!isFragmentRef(fragmentRef)) return fromValue({
-					operation: op,
-					data: fragmentRef,
-					errors: []
-				});
-				const trigger = makeSubject();
-				const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key), tap(() => trigger.complete()));
-				return pipe(merge(fromValue(void 0), trigger.source), switchMap(() => fromSubscription(() => cache.readFragment(op.artifact, fragmentRef), () => cache.subscribeFragment(op.artifact, fragmentRef, async () => {
-					await Promise.resolve();
-					trigger.next();
-				}))), takeUntil(teardown$), map((data) => ({
-					operation: op,
-					data,
-					errors: []
-				})));
-			}));
-			const nonCache$ = pipe(ops$, filter((op) => op.variant === "request" && (op.artifact.kind === "mutation" || op.artifact.kind === "subscription" || op.artifact.kind === "query" && fetchPolicy === "network-only")));
-			const query$ = pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind === "query" && fetchPolicy !== "network-only"), share());
-			return merge(fragment$, pipe(query$, mergeMap((op) => {
-				const trigger = makeSubject();
-				const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key), tap(() => trigger.complete()));
-				return pipe(merge(fromValue(void 0), trigger.source), switchMap(() => fromSubscription(() => cache.readQuery(op.artifact, op.variables), () => cache.subscribeQuery(op.artifact, op.variables, async () => {
-					await Promise.resolve();
-					trigger.next();
-				}))), takeUntil(teardown$), map((data) => ({
-					operation: op,
-					data,
-					errors: []
-				})));
-			}), filter((result) => fetchPolicy === "cache-only" || fetchPolicy === "cache-and-network" && result.data !== null || fetchPolicy === "cache-first" && result.data !== null)), pipe(merge(nonCache$, pipe(query$, filter((op) => {
-				const cached = cache.readQuery(op.artifact, op.variables);
-				return fetchPolicy === "cache-and-network" || cached === null;
-			})), pipe(ops$, filter((op) => op.variant === "teardown"))), forward, tap((result) => {
-				if (result.operation.variant === "request" && result.data) cache.writeQuery(result.operation.artifact, result.operation.variables, result.data);
-			}), filter((result) => result.operation.variant !== "request" || result.operation.artifact.kind !== "query" || fetchPolicy === "network-only")));
+		return {
+			name: "cache",
+			extension: {
+				extract: () => cache.extract(),
+				hydrate: (snapshot) => cache.hydrate(snapshot),
+				invalidate: (...targets) => cache.invalidate(...targets),
+				clear: () => cache.clear()
+			},
+			io: (ops$) => {
+				const fragment$ = pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind === "fragment"), mergeMap((op) => {
+					const fragmentRef = op.metadata?.fragmentRef;
+					if (!fragmentRef) return fromValue({
+						operation: op,
+						errors: [new ExchangeError("Fragment operation missing fragmentRef in metadata. This usually happens when the wrong fragment reference was passed.", { exchangeName: "cache" })]
+					});
+					if (isFragmentRefArray(fragmentRef)) {
+						const trigger = makeSubject();
+						const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key), tap(() => trigger.complete()));
+						return pipe(merge(fromValue(void 0), trigger.source), switchMap(() => fromSubscription(() => cache.readFragments(op.artifact, fragmentRef), () => cache.subscribeFragments(op.artifact, fragmentRef, async () => {
+							await Promise.resolve();
+							trigger.next();
+						}))), takeUntil(teardown$), map((data) => ({
+							operation: op,
+							data,
+							errors: []
+						})));
+					}
+					if (!isFragmentRef(fragmentRef)) return fromValue({
+						operation: op,
+						data: fragmentRef,
+						errors: []
+					});
+					const trigger = makeSubject();
+					const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key), tap(() => trigger.complete()));
+					return pipe(merge(fromValue(void 0), trigger.source), switchMap(() => fromSubscription(() => cache.readFragment(op.artifact, fragmentRef), () => cache.subscribeFragment(op.artifact, fragmentRef, async () => {
+						await Promise.resolve();
+						trigger.next();
+					}))), takeUntil(teardown$), map((data) => ({
+						operation: op,
+						data,
+						errors: []
+					})));
+				}));
+				const nonCache$ = pipe(ops$, filter((op) => op.variant === "request" && (op.artifact.kind === "mutation" || op.artifact.kind === "subscription" || op.artifact.kind === "query" && fetchPolicy === "network-only")));
+				const query$ = pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind === "query" && fetchPolicy !== "network-only"), share());
+				const refetch$ = makeSubject();
+				return merge(fragment$, pipe(query$, mergeMap((op) => {
+					const trigger = makeSubject();
+					let hasData = false;
+					const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key), tap(() => trigger.complete()));
+					return pipe(merge(fromValue(void 0), trigger.source), switchMap(() => fromSubscription(() => cache.readQuery(op.artifact, op.variables), () => cache.subscribeQuery(op.artifact, op.variables, async () => {
+						await Promise.resolve();
+						trigger.next();
+					}))), takeUntil(teardown$), mergeMap((data) => {
+						if (data !== null) {
+							hasData = true;
+							return fromValue({
+								operation: op,
+								data,
+								errors: []
+							});
+						}
+						if (hasData) {
+							refetch$.next(op);
+							return empty();
+						}
+						if (fetchPolicy === "cache-only") return fromValue({
+							operation: op,
+							data: null,
+							errors: []
+						});
+						return empty();
+					}));
+				}), filter(() => fetchPolicy === "cache-only" || fetchPolicy === "cache-and-network" || fetchPolicy === "cache-first")), pipe(merge(nonCache$, pipe(query$, filter((op) => {
+					const cached = cache.readQuery(op.artifact, op.variables);
+					return fetchPolicy === "cache-and-network" || cached === null;
+				})), pipe(ops$, filter((op) => op.variant === "teardown")), refetch$.source), forward, tap((result) => {
+					if (result.operation.variant === "request" && result.data) cache.writeQuery(result.operation.artifact, result.operation.variables, result.data);
+				}), filter((result) => result.operation.variant !== "request" || result.operation.artifact.kind !== "query" || fetchPolicy === "network-only" || !!(result.errors && result.errors.length > 0))));
+			}
 		};
 	};
 };
@@ -644,16 +920,17 @@ const cacheExchange = (options = {}) => {
 const defaultShouldRetry = (error) => isExchangeError(error, "http") && error.extensions?.statusCode !== void 0 && error.extensions.statusCode >= 500;
 const retryExchange = (options = {}) => {
 	const { maxAttempts = 3, backoff = (attempt) => Math.min(1e3 * 2 ** attempt, 3e4), shouldRetry = defaultShouldRetry } = options;
-	return ({ forward }) => {
-		return (ops$) => {
+	return ({ forward }) => ({
+		name: "retry",
+		io: (ops$) => {
 			const { source: retries$, next } = makeSubject();
 			const tornDown = /* @__PURE__ */ new Set();
 			const teardown$ = pipe(ops$, filter((op) => op.variant === "teardown"), tap((op) => {
 				tornDown.add(op.key);
 			}));
 			return pipe(merge(pipe(ops$, filter((op) => op.variant === "request")), pipe(retries$, filter((op) => !tornDown.has(op.key)), mergeMap((op) => {
-				const teardown$$1 = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key));
-				return pipe(fromValue(op), delay(op.metadata.retry.delay), takeUntil(teardown$$1));
+				const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key));
+				return pipe(fromValue(op), delay(op.metadata.retry.delay), takeUntil(teardown$));
 			})), teardown$), forward, filter((result) => {
 				if (!result.errors || result.errors.length === 0) return true;
 				if (result.operation.variant === "request" && result.operation.artifact.kind === "mutation") return true;
@@ -673,15 +950,16 @@ const retryExchange = (options = {}) => {
 				});
 				return false;
 			}));
-		};
-	};
+		}
+	});
 };
 
 //#endregion
 //#region src/exchanges/fragment.ts
 const fragmentExchange = () => {
-	return ({ forward }) => {
-		return (ops$) => {
+	return ({ forward }) => ({
+		name: "fragment",
+		io: (ops$) => {
 			return merge(pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind === "fragment"), map((op) => {
 				const fragmentRef = op.metadata.fragmentRef;
 				if (!fragmentRef) return {
@@ -693,12 +971,103 @@ const fragmentExchange = () => {
 					data: fragmentRef
 				};
 			})), pipe(ops$, filter((op) => op.variant === "teardown" || op.artifact.kind !== "fragment"), forward));
-		};
-	};
+		}
+	});
+};
+
+//#endregion
+//#region src/required.ts
+const CASCADE_NULL = Symbol("CASCADE_NULL");
+var RequiredFieldError = class extends Error {
+	fieldPath;
+	fieldName;
+	constructor(fieldPath, fieldName) {
+		super(`Required field '${fieldPath.join(".")}.${fieldName}' is null`);
+		this.name = "RequiredFieldError";
+		this.fieldPath = fieldPath;
+		this.fieldName = fieldName;
+	}
+};
+const getRequiredAction = (directives) => {
+	if (!directives) return null;
+	const requiredDirective = directives.find((d) => d.name === "required");
+	if (!requiredDirective) return null;
+	if (requiredDirective.args?.action === "CASCADE") return "CASCADE";
+	return "THROW";
+};
+const validateRequiredInner = (selections, data, fieldPath, validatedMap) => {
+	if (data === null || data === void 0) return data;
+	if (typeof data !== "object") return data;
+	if (Array.isArray(data)) return data.map((item, index) => {
+		const result = validateRequiredInner(selections, item, [...fieldPath, `[${index}]`], validatedMap);
+		return result === CASCADE_NULL ? null : result;
+	});
+	const obj = data;
+	validatedMap ??= /* @__PURE__ */ new WeakMap();
+	let validated = validatedMap.get(obj);
+	if (!validated) {
+		validated = /* @__PURE__ */ new Set();
+		validatedMap.set(obj, validated);
+	}
+	for (const selection of selections) if (selection.kind === "Field") {
+		const fieldName = selection.alias ?? selection.name;
+		if (!(fieldName in obj)) continue;
+		const fieldValue = obj[fieldName];
+		const action = getRequiredAction(selection.directives);
+		if (selection.selections) {
+			if (action && fieldValue === null) {
+				if (action === "THROW") throw new RequiredFieldError(fieldPath, fieldName);
+				else if (action === "CASCADE") return CASCADE_NULL;
+			}
+			if (fieldValue !== null && fieldValue !== void 0) {
+				if (validateRequiredInner(selection.selections, fieldValue, [...fieldPath, fieldName], validatedMap) === CASCADE_NULL) if (selection.nullable && !getRequiredAction(selection.directives)) obj[fieldName] = null;
+				else return CASCADE_NULL;
+			}
+		} else {
+			if (validated.has(fieldName)) continue;
+			validated.add(fieldName);
+			if (action && fieldValue === null) {
+				if (action === "THROW") throw new RequiredFieldError(fieldPath, fieldName);
+				else if (action === "CASCADE") return CASCADE_NULL;
+			}
+		}
+	} else if (selection.kind === "FragmentSpread" || selection.kind === "InlineFragment") {
+		if (validateRequiredInner(selection.selections, data, fieldPath, validatedMap) === CASCADE_NULL) return CASCADE_NULL;
+	}
+	return data;
+};
+const validateRequired = (selections, data, fieldPath = []) => {
+	const result = validateRequiredInner(selections, data, fieldPath);
+	return result === CASCADE_NULL ? null : result;
+};
+
+//#endregion
+//#region src/exchanges/required.ts
+const requiredExchange = () => {
+	return ({ forward }) => ({
+		name: "required",
+		io: (ops$) => {
+			return pipe(ops$, forward, map((result) => {
+				if (result.operation.variant !== "request" || !result.data) return result;
+				try {
+					return {
+						...result,
+						data: validateRequired(result.operation.artifact.selections, result.data)
+					};
+				} catch (error) {
+					return {
+						...result,
+						errors: [new ExchangeError(error instanceof Error ? error.message : String(error), { exchangeName: "required" })]
+					};
+				}
+			}));
+		}
+	});
 };
 
 //#endregion
 //#region src/exchanges/subscription.ts
+const shouldHandle = (op) => op.variant === "request" && (op.artifact.kind === "subscription" || op.metadata.subscription?.transport === true);
 /**
 * Creates an exchange for handling GraphQL subscriptions using a subscription client.
 *
@@ -728,9 +1097,10 @@ const fragmentExchange = () => {
 */
 const subscriptionExchange = (options) => {
 	const { client } = options;
-	return ({ forward }) => {
-		return (ops$) => {
-			return merge(pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind === "subscription"), mergeMap((op) => {
+	return ({ forward }) => ({
+		name: "subscription",
+		io: (ops$) => {
+			return merge(pipe(ops$, filter(shouldHandle), mergeMap((op) => {
 				const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key));
 				return pipe(make((observer) => {
 					let unsubscribe;
@@ -772,41 +1142,73 @@ const subscriptionExchange = (options) => {
 						unsubscribe?.();
 					};
 				}), takeUntil(teardown$));
-			})), pipe(ops$, filter((op) => op.variant === "teardown" || op.artifact.kind !== "subscription"), forward));
-		};
+			})), pipe(ops$, filter((op) => !shouldHandle(op)), forward));
+		}
+	});
+};
+
+//#endregion
+//#region src/compose.ts
+/** @internal */
+const composeExchanges = (options, input) => {
+	const { exchanges } = options;
+	const { client } = input;
+	const extensions = /* @__PURE__ */ new Map();
+	return {
+		io: exchanges.reduceRight((forward, exchange) => {
+			const result = exchange({
+				forward,
+				client
+			});
+			if ("extension" in result) extensions.set(result.name, result.extension);
+			return (ops$) => {
+				return pipe(ops$, share(), result.io, share());
+			};
+		}, input.forward),
+		extensions
 	};
 };
 
 //#endregion
 //#region src/scalars.ts
 const parse = (selections, scalars, value) => {
-	const parseValue = (selection, value$1) => {
-		if (isNullish(value$1)) return value$1;
-		if (selection.array && Array.isArray(value$1)) return value$1.map((item) => parseValue({
+	const parseValue = (selection, value, parsedMap) => {
+		if (isNullish$1(value)) return value;
+		if (selection.array && Array.isArray(value)) return value.map((item) => parseValue({
 			...selection,
 			array: false
-		}, item));
-		if (selection.selections) return parseField(selection.selections, value$1);
+		}, item, parsedMap));
+		if (selection.selections) return parseField(selection.selections, value, parsedMap);
 		const transformer = scalars[selection.type];
-		if (transformer) return transformer.parse(value$1);
-		return value$1;
+		if (transformer) return transformer.parse(value);
+		return value;
 	};
-	const parseField = (selections$1, value$1) => {
-		if (isNullish(value$1)) return value$1;
-		const data = value$1;
-		const fields = {};
-		for (const selection of selections$1) if (selection.kind === "Field") {
+	const parseField = (selections, value, parsedMap) => {
+		if (isNullish$1(value)) return value;
+		const data = value;
+		parsedMap ??= /* @__PURE__ */ new WeakMap();
+		let parsed = parsedMap.get(data);
+		if (!parsed) {
+			parsed = /* @__PURE__ */ new Set();
+			parsedMap.set(data, parsed);
+		}
+		for (const selection of selections) if (selection.kind === "Field") {
 			const fieldName = selection.alias ?? selection.name;
-			const fieldValue = data[fieldName];
-			fields[fieldName] = parseValue(selection, fieldValue);
-		} else if (selection.kind === "FragmentSpread" || selection.kind === "InlineFragment" && selection.on === data.__typename) Object.assign(fields, parseField(selection.selections, value$1));
-		return fields;
+			if (!(fieldName in data)) continue;
+			if (selection.selections) data[fieldName] = parseValue(selection, data[fieldName], parsedMap);
+			else {
+				if (parsed.has(fieldName)) continue;
+				parsed.add(fieldName);
+				data[fieldName] = parseValue(selection, data[fieldName], parsedMap);
+			}
+		} else if (selection.kind === "FragmentSpread" || selection.kind === "InlineFragment" && selection.on === data.__typename) parseField(selection.selections, value, parsedMap);
+		return data;
 	};
 	return parseField(selections, value);
 };
 const serialize = (schemaMeta, variableDefs, scalars, variables) => {
 	const serializeValue = (variableDef, value) => {
-		if (isNullish(value)) return value;
+		if (isNullish$1(value)) return value;
 		if (variableDef.array && Array.isArray(value)) return value.map((item) => serializeValue({
 			...variableDef,
 			array: false
@@ -817,11 +1219,11 @@ const serialize = (schemaMeta, variableDefs, scalars, variables) => {
 		if (transformer) return transformer.serialize(value);
 		return value;
 	};
-	const serializeField = (variableDefs$1, value) => {
-		if (isNullish(value)) return value;
+	const serializeField = (variableDefs, value) => {
+		if (isNullish$1(value)) return value;
 		const data = value;
 		const fields = {};
-		for (const variableDef of variableDefs$1) {
+		for (const variableDef of variableDefs) {
 			const variableValue = data[variableDef.name];
 			fields[variableDef.name] = serializeValue(variableDef, variableValue);
 		}
@@ -833,8 +1235,9 @@ const serialize = (schemaMeta, variableDefs, scalars, variables) => {
 //#endregion
 //#region src/exchanges/scalar.ts
 const scalarExchange = () => {
-	return ({ forward, client }) => {
-		return (ops$) => {
+	return ({ forward, client }) => ({
+		name: "scalar",
+		io: (ops$) => {
 			return pipe(ops$, map((op) => {
 				if (op.variant !== "request" || !op.artifact.variableDefs || !client.scalars) return op;
 				return {
@@ -848,21 +1251,22 @@ const scalarExchange = () => {
 					data: parse(result.operation.artifact.selections, client.scalars, result.data)
 				};
 			}));
-		};
-	};
+		}
+	});
 };
 
 //#endregion
 //#region src/exchanges/terminal.ts
 const terminalExchange = () => {
-	return () => {
-		return (ops$) => {
+	return () => ({
+		name: "terminal",
+		io: (ops$) => {
 			return pipe(ops$, filter((op) => op.variant !== "teardown"), mergeMap((op) => fromValue({
 				operation: op,
 				errors: [new ExchangeError("No terminal exchange found in exchange chain. Did you forget to add httpExchange to your exchanges array?", { exchangeName: "terminal" })]
 			})));
-		};
-	};
+		}
+	});
 };
 
 //#endregion
@@ -882,22 +1286,25 @@ const never = () => {
 var Client = class {
 	#schema;
 	#scalars;
+	#extensions;
 	operations$;
 	results$;
 	constructor(config) {
 		this.#schema = config.schema;
 		this.#scalars = config.scalars;
-		const exchange = composeExchange({ exchanges: [
+		const { io, extensions } = composeExchanges({ exchanges: [
+			requiredExchange(),
 			scalarExchange(),
 			...config.exchanges,
 			fragmentExchange(),
 			terminalExchange()
-		] });
-		this.operations$ = makeSubject();
-		this.results$ = exchange({
+		] }, {
 			forward: never,
 			client: this
-		})(this.operations$.source);
+		});
+		this.#extensions = extensions;
+		this.operations$ = makeSubject();
+		this.results$ = io(this.operations$.source);
 	}
 	get schema() {
 		return this.#schema;
@@ -908,11 +1315,11 @@ var Client = class {
 	createOperationKey() {
 		return Math.random().toString(36).slice(2) + Date.now().toString(36);
 	}
-	createOperation(artifact, variables) {
+	createOperation(artifact, variables, metadata) {
 		return {
 			variant: "request",
 			key: this.createOperationKey(),
-			metadata: {},
+			metadata: { ...metadata },
 			artifact,
 			variables: variables ?? {}
 		};
@@ -925,27 +1332,50 @@ var Client = class {
 		})), share());
 	}
 	executeQuery(artifact, ...[variables, options]) {
-		const operation = this.createOperation(artifact, variables);
+		const operation = this.createOperation(artifact, variables, options?.metadata);
 		return this.executeOperation(operation);
 	}
 	executeMutation(artifact, ...[variables, options]) {
-		const operation = this.createOperation(artifact, variables);
+		const operation = this.createOperation(artifact, variables, options?.metadata);
 		return this.executeOperation(operation);
 	}
 	executeSubscription(artifact, ...[variables, options]) {
-		const operation = this.createOperation(artifact, variables);
+		const operation = this.createOperation(artifact, variables, options?.metadata);
 		return this.executeOperation(operation);
 	}
 	executeFragment(artifact, fragmentRef, options) {
 		const operation = {
 			variant: "request",
 			key: this.createOperationKey(),
-			metadata: { fragmentRef },
+			metadata: {
+				...options?.metadata,
+				fragmentRef
+			},
 			artifact,
 			variables: {}
 		};
 		return this.executeOperation(operation);
 	}
+	async query(artifact, ...[variables, options]) {
+		const operation = this.createOperation(artifact, variables, options?.metadata);
+		const result = await pipe(this.executeOperation(operation), take(1), collect);
+		if (result.errors && result.errors.length > 0) throw new AggregatedError(result.errors);
+		return result.data;
+	}
+	async mutation(artifact, ...[variables, options]) {
+		const operation = this.createOperation(artifact, variables, options?.metadata);
+		const result = await pipe(this.executeOperation(operation), take(1), collect);
+		if (result.errors && result.errors.length > 0) throw new AggregatedError(result.errors);
+		return result.data;
+	}
+	extension(name) {
+		const ext = this.#extensions.get(name);
+		if (!ext) throw new Error(`Exchange extension '${name}' is not registered. Check your exchange configuration.`);
+		return ext;
+	}
+	maybeExtension(name) {
+		return this.#extensions.get(name);
+	}
 	dispose() {
 		this.operations$.complete();
 	}
@@ -955,4 +1385,4 @@ const createClient = (config) => {
 };
 
 //#endregion
-export { AggregatedError, Client, ExchangeError, GraphQLError, cacheExchange, composeExchange, createClient, dedupExchange, fragmentExchange, httpExchange, isAggregatedError, isExchangeError, isGraphQLError, retryExchange, stringify, subscriptionExchange };
+export { AggregatedError, Client, ExchangeError, GraphQLError, RequiredFieldError, cacheExchange, createClient, dedupExchange, fragmentExchange, httpExchange, isAggregatedError, isExchangeError, isGraphQLError, requiredExchange, retryExchange, stringify, subscriptionExchange };