@mearie/core 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -318,6 +318,12 @@ const RootFieldKey = "__root";
 * @internal
 */
 const FragmentRefKey = "__fragmentRef";
+/**
+* Special key used to carry merged variable context (fragment args + operation variables)
+* on fragment references. Used by readFragment to resolve variable-dependent field keys.
+* @internal
+*/
+const FragmentVarsKey = "__fragmentVars";
 
 //#endregion
 //#region src/cache/utils.ts
@@ -391,6 +397,14 @@ const isFragmentRef = (value) => {
 	return typeof value === "object" && value !== null && FragmentRefKey in value;
 };
 /**
+* Extracts the merged variable context for a specific fragment from a fragment reference.
+* Returns the merged variables (fragment args + operation variables) if present, or an empty object.
+* @internal
+*/
+const getFragmentVars = (fragmentRef, fragmentName) => {
+	return fragmentRef[FragmentVarsKey]?.[fragmentName] ?? {};
+};
+/**
 * Type guard to check if a value is an array of fragment references.
 * @internal
 * @param value - Value to check.
@@ -501,33 +515,20 @@ const mergeFields = (target, source) => {
 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, 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];
+		let entityMeta = schemaMeta.entities[typename];
 		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);
+			if (keys.every((k) => k !== void 0 && k !== null)) storageKey = makeEntityKey(typename, keys);
+			else entityMeta = void 0;
 		}
 		const fields = {};
 		for (const selection of selections) if (selection.kind === "Field") {
@@ -535,13 +536,11 @@ const normalize = (schemaMeta, selections, storage, data, variables, accessor) =
 			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;
+			fields[fieldKey] = selection.selections ? normalizeField(null, selection.selections, fieldValue) : fieldValue;
 			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 (inner !== SKIP && !isEntityLink(inner)) mergeFields(fields, inner);
+			if (!isEntityLink(inner)) mergeFields(fields, inner);
 		}
 		if (entityMeta && storageKey !== null) {
 			const existing = storage[storageKey];
@@ -596,6 +595,17 @@ const denormalize = (selections, storage, value, variables, accessor) => {
 			else fields[name] = value;
 		} else if (selection.kind === "FragmentSpread") if (storageKey !== null && storageKey !== RootFieldKey) {
 			fields[FragmentRefKey] = storageKey;
+			if (selection.args) {
+				const resolvedArgs = resolveArguments(selection.args, variables);
+				const mergedVars = {
+					...variables,
+					...resolvedArgs
+				};
+				fields[FragmentVarsKey] = {
+					...fields[FragmentVarsKey],
+					[selection.name]: mergedVars
+				};
+			}
 			if (accessor) denormalize(selection.selections, storage, { [EntityLinkKey]: storageKey }, variables, accessor);
 		} else mergeFields(fields, denormalizeField(storageKey, selection.selections, value));
 		else if (selection.kind === "InlineFragment" && selection.on === data[typenameFieldKey]) mergeFields(fields, denormalizeField(storageKey, selection.selections, value));
@@ -619,9 +629,74 @@ var Cache = class {
 	#subscriptions = /* @__PURE__ */ new Map();
 	#memo = /* @__PURE__ */ new Map();
 	#stale = /* @__PURE__ */ new Set();
+	#optimisticKeys = [];
+	#optimisticLayers = /* @__PURE__ */ new Map();
+	#storageView = null;
 	constructor(schemaMetadata) {
 		this.#schemaMeta = schemaMetadata;
 	}
+	#getStorageView() {
+		if (this.#optimisticKeys.length === 0) return this.#storage;
+		if (this.#storageView) return this.#storageView;
+		const merged = { ...this.#storage };
+		for (const storageKey of Object.keys(this.#storage)) merged[storageKey] = { ...this.#storage[storageKey] };
+		for (const key of this.#optimisticKeys) {
+			const layer = this.#optimisticLayers.get(key);
+			if (!layer) continue;
+			for (const storageKey of Object.keys(layer.storage)) merged[storageKey] = merged[storageKey] ? {
+				...merged[storageKey],
+				...layer.storage[storageKey]
+			} : { ...layer.storage[storageKey] };
+		}
+		this.#storageView = merged;
+		return merged;
+	}
+	/**
+	* Writes an optimistic response to a separate cache layer.
+	* The optimistic data is immediately visible in reads but does not affect the base storage.
+	* @internal
+	* @param key - Unique key identifying this optimistic mutation (typically the operation key).
+	* @param artifact - GraphQL document artifact.
+	* @param variables - Operation variables.
+	* @param data - The optimistic response data.
+	*/
+	writeOptimistic(key, artifact, variables, data) {
+		const layerStorage = { [RootFieldKey]: {} };
+		const dependencies = /* @__PURE__ */ new Set();
+		normalize(this.#schemaMeta, artifact.selections, layerStorage, data, variables, (storageKey, fieldKey) => {
+			dependencies.add(makeDependencyKey(storageKey, fieldKey));
+		});
+		this.#optimisticKeys.push(key);
+		this.#optimisticLayers.set(key, {
+			storage: layerStorage,
+			dependencies
+		});
+		this.#storageView = null;
+		const subscriptions = /* @__PURE__ */ new Set();
+		for (const depKey of dependencies) {
+			const ss = this.#subscriptions.get(depKey);
+			if (ss) for (const s of ss) subscriptions.add(s);
+		}
+		for (const subscription of subscriptions) subscription.listener();
+	}
+	/**
+	* Removes an optimistic layer and notifies affected subscribers.
+	* @internal
+	* @param key - The key of the optimistic layer to remove.
+	*/
+	removeOptimistic(key) {
+		const layer = this.#optimisticLayers.get(key);
+		if (!layer) return;
+		this.#optimisticLayers.delete(key);
+		this.#optimisticKeys = this.#optimisticKeys.filter((k) => k !== key);
+		this.#storageView = null;
+		const subscriptions = /* @__PURE__ */ new Set();
+		for (const depKey of layer.dependencies) {
+			const ss = this.#subscriptions.get(depKey);
+			if (ss) for (const s of ss) subscriptions.add(s);
+		}
+		for (const subscription of subscriptions) subscription.listener();
+	}
 	/**
 	* Writes a query result to the cache, normalizing entities.
 	* @param artifact - GraphQL document artifact.
@@ -654,7 +729,8 @@ var Cache = class {
 	*/
 	readQuery(artifact, variables) {
 		let stale = false;
-		const { data, partial } = denormalize(artifact.selections, this.#storage, this.#storage[RootFieldKey], variables, (storageKey, fieldKey) => {
+		const storage = this.#getStorageView();
+		const { data, partial } = denormalize(artifact.selections, storage, storage[RootFieldKey], variables, (storageKey, fieldKey) => {
 			if (this.#stale.has(storageKey) || this.#stale.has(makeDependencyKey(storageKey, fieldKey))) stale = true;
 		});
 		if (partial) return {
@@ -679,7 +755,8 @@ var Cache = class {
 	*/
 	subscribeQuery(artifact, variables, listener) {
 		const dependencies = /* @__PURE__ */ new Set();
-		denormalize(artifact.selections, this.#storage, this.#storage[RootFieldKey], variables, (storageKey, fieldKey) => {
+		const storageView = this.#getStorageView();
+		denormalize(artifact.selections, storageView, storageView[RootFieldKey], variables, (storageKey, fieldKey) => {
 			const dependencyKey = makeDependencyKey(storageKey, fieldKey);
 			dependencies.add(dependencyKey);
 		});
@@ -694,19 +771,22 @@ var Cache = class {
 	*/
 	readFragment(artifact, fragmentRef) {
 		const entityKey = fragmentRef[FragmentRefKey];
-		if (!this.#storage[entityKey]) return {
+		const fragmentVars = getFragmentVars(fragmentRef, artifact.name);
+		const storageView = this.#getStorageView();
+		if (!storageView[entityKey]) return {
 			data: null,
 			stale: false
 		};
 		let stale = false;
-		const { data, partial } = denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {}, (storageKey, fieldKey) => {
+		const { data, partial } = denormalize(artifact.selections, storageView, { [EntityLinkKey]: entityKey }, fragmentVars, (storageKey, fieldKey) => {
 			if (this.#stale.has(storageKey) || this.#stale.has(makeDependencyKey(storageKey, fieldKey))) stale = true;
 		});
 		if (partial) return {
 			data: null,
 			stale: false
 		};
-		const key = makeMemoKey("fragment", artifact.name, entityKey);
+		const argsId = Object.keys(fragmentVars).length > 0 ? entityKey + stringify(fragmentVars) : entityKey;
+		const key = makeMemoKey("fragment", artifact.name, argsId);
 		const prev = this.#memo.get(key);
 		const result = prev === void 0 ? data : replaceEqualDeep(prev, data);
 		this.#memo.set(key, result);
@@ -717,8 +797,10 @@ var Cache = class {
 	}
 	subscribeFragment(artifact, fragmentRef, listener) {
 		const entityKey = fragmentRef[FragmentRefKey];
+		const fragmentVars = getFragmentVars(fragmentRef, artifact.name);
 		const dependencies = /* @__PURE__ */ new Set();
-		denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {}, (storageKey, fieldKey) => {
+		const storageView = this.#getStorageView();
+		denormalize(artifact.selections, storageView, { [EntityLinkKey]: entityKey }, fragmentVars, (storageKey, fieldKey) => {
 			const dependencyKey = makeDependencyKey(storageKey, fieldKey);
 			dependencies.add(dependencyKey);
 		});
@@ -748,9 +830,11 @@ var Cache = class {
 	}
 	subscribeFragments(artifact, fragmentRefs, listener) {
 		const dependencies = /* @__PURE__ */ new Set();
+		const storageView = this.#getStorageView();
 		for (const ref of fragmentRefs) {
 			const entityKey = ref[FragmentRefKey];
-			denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {}, (storageKey, fieldKey) => {
+			const fragmentVars = getFragmentVars(ref, artifact.name);
+			denormalize(artifact.selections, storageView, { [EntityLinkKey]: entityKey }, fragmentVars, (storageKey, fieldKey) => {
 				dependencies.add(makeDependencyKey(storageKey, fieldKey));
 			});
 		}
@@ -762,8 +846,8 @@ var Cache = class {
 	*/
 	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);
+		for (const target of targets) if (target.__typename === "Query") if ("$field" in target) {
+			const fieldKey = makeFieldKeyFromArgs(target.$field, target.$args);
 			const depKey = makeDependencyKey(RootFieldKey, fieldKey);
 			this.#stale.add(depKey);
 			this.#collectSubscriptions(RootFieldKey, fieldKey, subscriptions);
@@ -771,32 +855,39 @@ var Cache = class {
 			this.#stale.add(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);
-				this.#stale.add(makeDependencyKey(entityKey, fieldKey));
-				this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
-			} else {
-				this.#stale.add(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);
+		else {
+			const keyFields = this.#schemaMeta.entities[target.__typename]?.keyFields;
+			if (keyFields && this.#hasKeyFields(target, keyFields)) {
+				const keyValues = keyFields.map((f) => target[f]);
+				const entityKey = makeEntityKey(target.__typename, keyValues);
+				if ("$field" in target) {
+					const fieldKey = makeFieldKeyFromArgs(target.$field, target.$args);
 					this.#stale.add(makeDependencyKey(entityKey, fieldKey));
 					this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
 				} else {
 					this.#stale.add(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);
+						this.#stale.add(makeDependencyKey(entityKey, fieldKey));
+						this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
+					} else {
+						this.#stale.add(entityKey);
+						this.#collectSubscriptions(entityKey, void 0, subscriptions);
+					}
+				}
 			}
 		}
 		for (const subscription of subscriptions) subscription.listener();
 	}
+	#hasKeyFields(target, keyFields) {
+		return keyFields.every((f) => f in target);
+	}
 	#collectSubscriptions(storageKey, fieldKey, out) {
 		if (fieldKey === void 0) {
 			const prefix = `${storageKey}.`;
@@ -824,6 +915,7 @@ var Cache = class {
 	}
 	/**
 	* Extracts a serializable snapshot of the cache storage and structural sharing state.
+	* Optimistic layers are excluded because they represent transient in-flight state.
 	*/
 	extract() {
 		return {
@@ -841,6 +933,7 @@ var Cache = class {
 			...fields
 		};
 		for (const [key, value] of Object.entries(memo)) this.#memo.set(key, value);
+		this.#storageView = null;
 	}
 	/**
 	* Clears all cache data.
@@ -850,6 +943,9 @@ var Cache = class {
 		this.#subscriptions.clear();
 		this.#memo.clear();
 		this.#stale.clear();
+		this.#optimisticKeys = [];
+		this.#optimisticLayers.clear();
+		this.#storageView = null;
 	}
 };
 
@@ -882,10 +978,10 @@ const cacheExchange = (options = {}) => {
 			},
 			io: (ops$) => {
 				const fragment$ = require_make.pipe(ops$, require_make.filter((op) => op.variant === "request" && op.artifact.kind === "fragment"), require_make.mergeMap((op) => {
-					const fragmentRef = op.metadata?.fragmentRef;
+					const fragmentRef = op.metadata?.fragment?.ref;
 					if (!fragmentRef) return require_make.fromValue({
 						operation: op,
-						errors: [new ExchangeError("Fragment operation missing fragmentRef in metadata. This usually happens when the wrong fragment reference was passed.", { exchangeName: "cache" })]
+						errors: [new ExchangeError("Fragment operation missing fragment.ref in metadata. This usually happens when the wrong fragment reference was passed.", { exchangeName: "cache" })]
 					});
 					if (isFragmentRefArray(fragmentRef)) {
 						const trigger = require_make.makeSubject();
@@ -917,7 +1013,9 @@ const cacheExchange = (options = {}) => {
 						errors: []
 					})));
 				}));
-				const nonCache$ = require_make.pipe(ops$, require_make.filter((op) => op.variant === "request" && (op.artifact.kind === "mutation" || op.artifact.kind === "subscription" || op.artifact.kind === "query" && fetchPolicy === "network-only")));
+				const nonCache$ = require_make.pipe(ops$, require_make.filter((op) => op.variant === "request" && (op.artifact.kind === "mutation" || op.artifact.kind === "subscription" || op.artifact.kind === "query" && fetchPolicy === "network-only")), require_make.tap((op) => {
+					if (op.artifact.kind === "mutation" && op.metadata?.cache?.optimisticResponse) cache.writeOptimistic(op.key, op.artifact, op.variables, op.metadata.cache.optimisticResponse);
+				}));
 				const query$ = require_make.pipe(ops$, require_make.filter((op) => op.variant === "request" && op.artifact.kind === "query" && fetchPolicy !== "network-only"), require_make.share());
 				const refetch$ = require_make.makeSubject();
 				return require_make.merge(fragment$, require_make.pipe(query$, require_make.mergeMap((op) => {
@@ -960,9 +1058,18 @@ const cacheExchange = (options = {}) => {
 				}), require_make.filter(() => fetchPolicy === "cache-only" || fetchPolicy === "cache-and-network" || fetchPolicy === "cache-first")), require_make.pipe(require_make.merge(nonCache$, require_make.pipe(query$, require_make.filter((op) => {
 					const { data } = cache.readQuery(op.artifact, op.variables);
 					return fetchPolicy === "cache-and-network" || data === null;
-				})), require_make.pipe(ops$, require_make.filter((op) => op.variant === "teardown")), refetch$.source), forward, require_make.tap((result) => {
+				})), require_make.pipe(ops$, require_make.filter((op) => op.variant === "teardown")), refetch$.source), forward, require_make.mergeMap((result) => {
+					if (result.operation.variant === "request" && result.operation.artifact.kind === "mutation" && result.operation.metadata?.cache?.optimisticResponse) cache.removeOptimistic(result.operation.key);
 					if (result.operation.variant === "request" && result.data) cache.writeQuery(result.operation.artifact, result.operation.variables, result.data);
-				}), require_make.filter((result) => result.operation.variant !== "request" || result.operation.artifact.kind !== "query" || fetchPolicy === "network-only" || !!(result.errors && result.errors.length > 0))));
+					if (result.operation.variant !== "request" || result.operation.artifact.kind !== "query" || fetchPolicy === "network-only" || !!(result.errors && result.errors.length > 0)) return require_make.fromValue(result);
+					const { data } = cache.readQuery(result.operation.artifact, result.operation.variables);
+					if (data !== null) return empty();
+					return require_make.fromValue({
+						operation: result.operation,
+						data: void 0,
+						errors: [new ExchangeError("Cache failed to denormalize the network response. This is likely a bug in the cache normalizer.", { exchangeName: "cache" })]
+					});
+				})));
 			}
 		};
 	};
@@ -1014,10 +1121,10 @@ const fragmentExchange = () => {
 		name: "fragment",
 		io: (ops$) => {
 			return require_make.merge(require_make.pipe(ops$, require_make.filter((op) => op.variant === "request" && op.artifact.kind === "fragment"), require_make.map((op) => {
-				const fragmentRef = op.metadata.fragmentRef;
+				const fragmentRef = op.metadata.fragment?.ref;
 				if (!fragmentRef) return {
 					operation: op,
-					errors: [new ExchangeError("Fragment operation missing fragmentRef in metadata. This usually happens when the wrong fragment reference was passed.", { exchangeName: "fragment" })]
+					errors: [new ExchangeError("Fragment operation missing fragment.ref in metadata. This usually happens when the wrong fragment reference was passed.", { exchangeName: "fragment" })]
 				};
 				return {
 					operation: op,
@@ -1403,7 +1510,7 @@ var Client = class {
 			key: this.createOperationKey(),
 			metadata: {
 				...options?.metadata,
-				fragmentRef
+				fragment: { ref: fragmentRef }
 			},
 			artifact,
 			variables: {}

package/dist/index.d.cts

@@ -68,8 +68,8 @@ type QueryOptions<T extends Artifact$1<'query'> = Artifact$1<'query'>> = {
   initialData?: DataOf$1<T>;
   metadata?: OperationMetadata;
 };
-type MutationOptions = {
-  metadata?: OperationMetadata;
+type MutationOptions<T extends Artifact$1<'mutation'> = Artifact$1<'mutation'>> = {
+  metadata?: OperationMetadata<T>;
 };
 type SubscriptionOptions = {
   metadata?: OperationMetadata;
@@ -93,31 +93,31 @@ declare class Client<TMeta extends SchemaMeta$1 = SchemaMeta$1> {
   get schema(): TMeta;
   get scalars(): ScalarsConfig<TMeta> | undefined;
   private createOperationKey;
-  createOperation(artifact: Artifact$1, variables?: unknown, metadata?: OperationMetadata): Operation;
+  createOperation(artifact: Artifact$1, variables?: unknown, metadata?: Record<string, unknown>): Operation;
   executeOperation(operation: Operation): Source<OperationResult>;
   executeQuery<T extends Artifact$1<'query'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, QueryOptions<T>?] : [VariablesOf$1<T>, QueryOptions<T>?]): Source<OperationResult>;
-  executeMutation<T extends Artifact$1<'mutation'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, MutationOptions?] : [VariablesOf$1<T>, MutationOptions?]): Source<OperationResult>;
+  executeMutation<T extends Artifact$1<'mutation'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, MutationOptions<T>?] : [VariablesOf$1<T>, MutationOptions<T>?]): Source<OperationResult>;
   executeSubscription<T extends Artifact$1<'subscription'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, SubscriptionOptions?] : [VariablesOf$1<T>, SubscriptionOptions?]): Source<OperationResult>;
   executeFragment<T extends Artifact$1<'fragment'>>(artifact: T, fragmentRef: FragmentRefs$1<T['name']> | FragmentRefs$1<T['name']>[], options?: FragmentOptions): Source<OperationResult>;
   query<T extends Artifact$1<'query'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, QueryOptions<T>?] : [VariablesOf$1<T>, QueryOptions<T>?]): Promise<DataOf$1<T>>;
-  mutation<T extends Artifact$1<'mutation'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, MutationOptions?] : [VariablesOf$1<T>, MutationOptions?]): Promise<DataOf$1<T>>;
+  mutation<T extends Artifact$1<'mutation'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, MutationOptions<T>?] : [VariablesOf$1<T>, MutationOptions<T>?]): Promise<DataOf$1<T>>;
   /**
    * Returns the extension registered by a named exchange.
    * @param name - The exchange name.
    * @returns The extension object provided by the exchange.
    */
-  extension<TName extends keyof ExchangeExtensionMap>(name: TName): ExchangeExtensionMap[TName];
+  extension<TName extends keyof ExchangeExtensionMap<TMeta>>(name: TName): ExchangeExtensionMap<TMeta>[TName];
   extension(name: string): unknown;
-  maybeExtension<TName extends keyof ExchangeExtensionMap>(name: TName): ExchangeExtensionMap[TName] | undefined;
+  maybeExtension<TName extends keyof ExchangeExtensionMap<TMeta>>(name: TName): ExchangeExtensionMap<TMeta>[TName] | undefined;
   maybeExtension(name: string): unknown;
   dispose(): void;
 }
 declare const createClient: <T extends SchemaMeta$1>(config: ClientOptions<T>) => Client<T>;
 //#endregion
 //#region src/exchange.d.ts
-interface OperationMetadataMap {}
+interface OperationMetadataMap<T extends Artifact$1 = Artifact$1> {}
 interface OperationResultMetadataMap {}
-type OperationMetadata = { [K in keyof OperationMetadataMap]?: OperationMetadataMap[K] } & Record<string, unknown>;
+type OperationMetadata<T extends Artifact$1 = Artifact$1> = { [K in keyof OperationMetadataMap<T>]?: OperationMetadataMap<T>[K] } & Record<string, unknown>;
 type BaseOperation = {
   key: string;
   metadata: OperationMetadataMap & Record<string, unknown>;
@@ -143,14 +143,14 @@ type ExchangeInput<TMeta extends SchemaMeta$1 = SchemaMeta$1> = {
   client: Client<TMeta>;
 };
 type ExchangeIO = (operations: Source<Operation>) => Source<OperationResult>;
-interface ExchangeExtensionMap {}
-type ExchangeResult<TName extends keyof ExchangeExtensionMap | (string & {}) = string> = {
+interface ExchangeExtensionMap<TMeta extends SchemaMeta$1 = SchemaMeta$1> {}
+type ExchangeResult<TName extends keyof ExchangeExtensionMap | (string & {}) = string, TMeta extends SchemaMeta$1 = SchemaMeta$1> = {
   name: TName;
   io: ExchangeIO;
-} & (TName extends keyof ExchangeExtensionMap ? {
-  extension: ExchangeExtensionMap[TName];
+} & (TName extends keyof ExchangeExtensionMap<TMeta> ? {
+  extension: ExchangeExtensionMap<TMeta>[TName];
 } : {});
-type Exchange<TName extends keyof ExchangeExtensionMap | (string & {}) = string> = <TMeta extends SchemaMeta$1 = SchemaMeta$1>(input: ExchangeInput<TMeta>) => ExchangeResult<TName>;
+type Exchange<TName extends keyof ExchangeExtensionMap | (string & {}) = string> = <TMeta extends SchemaMeta$1 = SchemaMeta$1>(input: ExchangeInput<TMeta>) => ExchangeResult<TName, TMeta>;
 //#endregion
 //#region src/exchanges/http.d.ts
 declare module '@mearie/core' {
@@ -195,34 +195,38 @@ declare module '@mearie/core' {
 declare const dedupExchange: () => Exchange;
 //#endregion
 //#region src/cache/types.d.ts
-/**
- * Identifier for a single entity, supporting simple or composite keys.
- */
-type EntityId = string | number | Record<string, string | number>;
-/**
- * Target specification for cache invalidation operations.
- */
-type InvalidateTarget = {
-  __typename: string;
-  id: EntityId;
-} | {
-  __typename: string;
-  id: EntityId;
-  field: string;
-  args?: Record<string, unknown>;
-} | {
+type EntityTypes<TMeta extends SchemaMeta$1> = NonNullable<TMeta[' $entityTypes']>;
+type QueryFields<TMeta extends SchemaMeta$1> = NonNullable<TMeta[' $queryFields']>;
+type KeyFieldsOf<E> = E extends {
+  keyFields: infer KF;
+} ? KF : Record<string, unknown>;
+type FieldsOf<E> = E extends {
+  fields: infer F extends string;
+} ? F : string;
+type EntityInvalidateTarget<Entities> = { [K in keyof Entities & string]: {
+  __typename: K;
+} | ({
+  __typename: K;
+} & KeyFieldsOf<Entities[K]>) | {
+  __typename: K;
+  $field: FieldsOf<Entities[K]>;
+  $args?: Record<string, unknown>;
+} | ({
+  __typename: K;
+  $field: FieldsOf<Entities[K]>;
+  $args?: Record<string, unknown>;
+} & KeyFieldsOf<Entities[K]>) }[keyof Entities & string];
+type QueryInvalidateTarget<QF extends string> = {
   __typename: 'Query';
 } | {
   __typename: 'Query';
-  field: string;
-  args?: Record<string, unknown>;
-} | {
-  __typename: string;
-} | {
-  __typename: string;
-  field: string;
-  args?: Record<string, unknown>;
+  $field: QF;
+  $args?: Record<string, unknown>;
 };
+/**
+ * Target specification for cache invalidation operations.
+ */
+type InvalidateTarget<TMeta extends SchemaMeta$1 = SchemaMeta$1> = EntityInvalidateTarget<EntityTypes<TMeta>> | QueryInvalidateTarget<QueryFields<TMeta>>;
 /**
  * Opaque type representing a serializable cache snapshot.
  */
@@ -232,17 +236,22 @@ type CacheSnapshot = {
 /**
  * Operations available for programmatic cache manipulation.
  */
-type CacheOperations = {
+type CacheOperations<TMeta extends SchemaMeta$1 = SchemaMeta$1> = {
   extract(): CacheSnapshot;
   hydrate(data: CacheSnapshot): void;
-  invalidate(...targets: InvalidateTarget[]): void;
+  invalidate(...targets: InvalidateTarget<TMeta>[]): void;
   clear(): void;
 };
 //#endregion
 //#region src/exchanges/cache.d.ts
 declare module '@mearie/core' {
-  interface ExchangeExtensionMap {
-    cache: CacheOperations;
+  interface ExchangeExtensionMap<TMeta extends SchemaMeta$1> {
+    cache: CacheOperations<TMeta>;
+  }
+  interface OperationMetadataMap<T extends Artifact$1> {
+    cache?: {
+      optimisticResponse?: T extends Artifact$1<'mutation'> ? DataOf$1<T> : never;
+    };
   }
   interface OperationResultMetadataMap {
     cache?: {
@@ -274,7 +283,9 @@ declare const retryExchange: (options?: RetryOptions) => Exchange;
 //#region src/exchanges/fragment.d.ts
 declare module '@mearie/core' {
   interface OperationMetadataMap {
-    fragmentRef?: unknown;
+    fragment?: {
+      ref?: unknown;
+    };
   }
 }
 declare const fragmentExchange: () => Exchange;
@@ -351,4 +362,4 @@ declare class RequiredFieldError extends Error {
  */
 declare const stringify: (value: unknown) => string;
 //#endregion
-export { AggregatedError, type Artifact, type ArtifactKind, type CacheOptions, type CacheSnapshot, Client, type ClientOptions, type DataOf, type Exchange, ExchangeError, type ExchangeErrorExtensionsMap, type ExchangeExtensionMap, type ExchangeIO, type ExchangeResult, type FragmentOptions, type FragmentRefs, GraphQLError, type HttpOptions, type MutationOptions, type Operation, type OperationError, type OperationMetadata, type OperationMetadataMap, type OperationResult, type OperationResultMetadataMap, type QueryOptions, type RequiredAction, RequiredFieldError, type RetryOptions, type SchemaMeta, type SubscriptionClient, type SubscriptionExchangeOptions, type SubscriptionOptions, type VariablesOf, cacheExchange, createClient, dedupExchange, fragmentExchange, httpExchange, isAggregatedError, isExchangeError, isGraphQLError, requiredExchange, retryExchange, stringify, subscriptionExchange };
+export { AggregatedError, type Artifact, type ArtifactKind, type CacheOperations, type CacheOptions, type CacheSnapshot, Client, type ClientOptions, type DataOf, type Exchange, ExchangeError, type ExchangeErrorExtensionsMap, type ExchangeExtensionMap, type ExchangeIO, type ExchangeResult, type FragmentOptions, type FragmentRefs, GraphQLError, type HttpOptions, type InvalidateTarget, type MutationOptions, type Operation, type OperationError, type OperationMetadata, type OperationMetadataMap, type OperationResult, type OperationResultMetadataMap, type QueryOptions, type RequiredAction, RequiredFieldError, type RetryOptions, type SchemaMeta, type SubscriptionClient, type SubscriptionExchangeOptions, type SubscriptionOptions, type VariablesOf, cacheExchange, createClient, dedupExchange, fragmentExchange, httpExchange, isAggregatedError, isExchangeError, isGraphQLError, requiredExchange, retryExchange, stringify, subscriptionExchange };

package/dist/index.d.mts

@@ -68,8 +68,8 @@ type QueryOptions<T extends Artifact$1<'query'> = Artifact$1<'query'>> = {
   initialData?: DataOf$1<T>;
   metadata?: OperationMetadata;
 };
-type MutationOptions = {
-  metadata?: OperationMetadata;
+type MutationOptions<T extends Artifact$1<'mutation'> = Artifact$1<'mutation'>> = {
+  metadata?: OperationMetadata<T>;
 };
 type SubscriptionOptions = {
   metadata?: OperationMetadata;
@@ -93,31 +93,31 @@ declare class Client<TMeta extends SchemaMeta$1 = SchemaMeta$1> {
   get schema(): TMeta;
   get scalars(): ScalarsConfig<TMeta> | undefined;
   private createOperationKey;
-  createOperation(artifact: Artifact$1, variables?: unknown, metadata?: OperationMetadata): Operation;
+  createOperation(artifact: Artifact$1, variables?: unknown, metadata?: Record<string, unknown>): Operation;
   executeOperation(operation: Operation): Source<OperationResult>;
   executeQuery<T extends Artifact$1<'query'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, QueryOptions<T>?] : [VariablesOf$1<T>, QueryOptions<T>?]): Source<OperationResult>;
-  executeMutation<T extends Artifact$1<'mutation'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, MutationOptions?] : [VariablesOf$1<T>, MutationOptions?]): Source<OperationResult>;
+  executeMutation<T extends Artifact$1<'mutation'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, MutationOptions<T>?] : [VariablesOf$1<T>, MutationOptions<T>?]): Source<OperationResult>;
   executeSubscription<T extends Artifact$1<'subscription'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, SubscriptionOptions?] : [VariablesOf$1<T>, SubscriptionOptions?]): Source<OperationResult>;
   executeFragment<T extends Artifact$1<'fragment'>>(artifact: T, fragmentRef: FragmentRefs$1<T['name']> | FragmentRefs$1<T['name']>[], options?: FragmentOptions): Source<OperationResult>;
   query<T extends Artifact$1<'query'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, QueryOptions<T>?] : [VariablesOf$1<T>, QueryOptions<T>?]): Promise<DataOf$1<T>>;
-  mutation<T extends Artifact$1<'mutation'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, MutationOptions?] : [VariablesOf$1<T>, MutationOptions?]): Promise<DataOf$1<T>>;
+  mutation<T extends Artifact$1<'mutation'>>(artifact: T, ...[variables, options]: VariablesOf$1<T> extends undefined ? [undefined?, MutationOptions<T>?] : [VariablesOf$1<T>, MutationOptions<T>?]): Promise<DataOf$1<T>>;
   /**
    * Returns the extension registered by a named exchange.
    * @param name - The exchange name.
    * @returns The extension object provided by the exchange.
    */
-  extension<TName extends keyof ExchangeExtensionMap>(name: TName): ExchangeExtensionMap[TName];
+  extension<TName extends keyof ExchangeExtensionMap<TMeta>>(name: TName): ExchangeExtensionMap<TMeta>[TName];
   extension(name: string): unknown;
-  maybeExtension<TName extends keyof ExchangeExtensionMap>(name: TName): ExchangeExtensionMap[TName] | undefined;
+  maybeExtension<TName extends keyof ExchangeExtensionMap<TMeta>>(name: TName): ExchangeExtensionMap<TMeta>[TName] | undefined;
   maybeExtension(name: string): unknown;
   dispose(): void;
 }
 declare const createClient: <T extends SchemaMeta$1>(config: ClientOptions<T>) => Client<T>;
 //#endregion
 //#region src/exchange.d.ts
-interface OperationMetadataMap {}
+interface OperationMetadataMap<T extends Artifact$1 = Artifact$1> {}
 interface OperationResultMetadataMap {}
-type OperationMetadata = { [K in keyof OperationMetadataMap]?: OperationMetadataMap[K] } & Record<string, unknown>;
+type OperationMetadata<T extends Artifact$1 = Artifact$1> = { [K in keyof OperationMetadataMap<T>]?: OperationMetadataMap<T>[K] } & Record<string, unknown>;
 type BaseOperation = {
   key: string;
   metadata: OperationMetadataMap & Record<string, unknown>;
@@ -143,14 +143,14 @@ type ExchangeInput<TMeta extends SchemaMeta$1 = SchemaMeta$1> = {
   client: Client<TMeta>;
 };
 type ExchangeIO = (operations: Source<Operation>) => Source<OperationResult>;
-interface ExchangeExtensionMap {}
-type ExchangeResult<TName extends keyof ExchangeExtensionMap | (string & {}) = string> = {
+interface ExchangeExtensionMap<TMeta extends SchemaMeta$1 = SchemaMeta$1> {}
+type ExchangeResult<TName extends keyof ExchangeExtensionMap | (string & {}) = string, TMeta extends SchemaMeta$1 = SchemaMeta$1> = {
   name: TName;
   io: ExchangeIO;
-} & (TName extends keyof ExchangeExtensionMap ? {
-  extension: ExchangeExtensionMap[TName];
+} & (TName extends keyof ExchangeExtensionMap<TMeta> ? {
+  extension: ExchangeExtensionMap<TMeta>[TName];
 } : {});
-type Exchange<TName extends keyof ExchangeExtensionMap | (string & {}) = string> = <TMeta extends SchemaMeta$1 = SchemaMeta$1>(input: ExchangeInput<TMeta>) => ExchangeResult<TName>;
+type Exchange<TName extends keyof ExchangeExtensionMap | (string & {}) = string> = <TMeta extends SchemaMeta$1 = SchemaMeta$1>(input: ExchangeInput<TMeta>) => ExchangeResult<TName, TMeta>;
 //#endregion
 //#region src/exchanges/http.d.ts
 declare module '@mearie/core' {
@@ -195,34 +195,38 @@ declare module '@mearie/core' {
 declare const dedupExchange: () => Exchange;
 //#endregion
 //#region src/cache/types.d.ts
-/**
- * Identifier for a single entity, supporting simple or composite keys.
- */
-type EntityId = string | number | Record<string, string | number>;
-/**
- * Target specification for cache invalidation operations.
- */
-type InvalidateTarget = {
-  __typename: string;
-  id: EntityId;
-} | {
-  __typename: string;
-  id: EntityId;
-  field: string;
-  args?: Record<string, unknown>;
-} | {
+type EntityTypes<TMeta extends SchemaMeta$1> = NonNullable<TMeta[' $entityTypes']>;
+type QueryFields<TMeta extends SchemaMeta$1> = NonNullable<TMeta[' $queryFields']>;
+type KeyFieldsOf<E> = E extends {
+  keyFields: infer KF;
+} ? KF : Record<string, unknown>;
+type FieldsOf<E> = E extends {
+  fields: infer F extends string;
+} ? F : string;
+type EntityInvalidateTarget<Entities> = { [K in keyof Entities & string]: {
+  __typename: K;
+} | ({
+  __typename: K;
+} & KeyFieldsOf<Entities[K]>) | {
+  __typename: K;
+  $field: FieldsOf<Entities[K]>;
+  $args?: Record<string, unknown>;
+} | ({
+  __typename: K;
+  $field: FieldsOf<Entities[K]>;
+  $args?: Record<string, unknown>;
+} & KeyFieldsOf<Entities[K]>) }[keyof Entities & string];
+type QueryInvalidateTarget<QF extends string> = {
   __typename: 'Query';
 } | {
   __typename: 'Query';
-  field: string;
-  args?: Record<string, unknown>;
-} | {
-  __typename: string;
-} | {
-  __typename: string;
-  field: string;
-  args?: Record<string, unknown>;
+  $field: QF;
+  $args?: Record<string, unknown>;
 };
+/**
+ * Target specification for cache invalidation operations.
+ */
+type InvalidateTarget<TMeta extends SchemaMeta$1 = SchemaMeta$1> = EntityInvalidateTarget<EntityTypes<TMeta>> | QueryInvalidateTarget<QueryFields<TMeta>>;
 /**
  * Opaque type representing a serializable cache snapshot.
  */
@@ -232,17 +236,22 @@ type CacheSnapshot = {
 /**
  * Operations available for programmatic cache manipulation.
  */
-type CacheOperations = {
+type CacheOperations<TMeta extends SchemaMeta$1 = SchemaMeta$1> = {
   extract(): CacheSnapshot;
   hydrate(data: CacheSnapshot): void;
-  invalidate(...targets: InvalidateTarget[]): void;
+  invalidate(...targets: InvalidateTarget<TMeta>[]): void;
   clear(): void;
 };
 //#endregion
 //#region src/exchanges/cache.d.ts
 declare module '@mearie/core' {
-  interface ExchangeExtensionMap {
-    cache: CacheOperations;
+  interface ExchangeExtensionMap<TMeta extends SchemaMeta$1> {
+    cache: CacheOperations<TMeta>;
+  }
+  interface OperationMetadataMap<T extends Artifact$1> {
+    cache?: {
+      optimisticResponse?: T extends Artifact$1<'mutation'> ? DataOf$1<T> : never;
+    };
   }
   interface OperationResultMetadataMap {
     cache?: {
@@ -274,7 +283,9 @@ declare const retryExchange: (options?: RetryOptions) => Exchange;
 //#region src/exchanges/fragment.d.ts
 declare module '@mearie/core' {
   interface OperationMetadataMap {
-    fragmentRef?: unknown;
+    fragment?: {
+      ref?: unknown;
+    };
   }
 }
 declare const fragmentExchange: () => Exchange;
@@ -351,4 +362,4 @@ declare class RequiredFieldError extends Error {
  */
 declare const stringify: (value: unknown) => string;
 //#endregion
-export { AggregatedError, type Artifact, type ArtifactKind, type CacheOptions, type CacheSnapshot, Client, type ClientOptions, type DataOf, type Exchange, ExchangeError, type ExchangeErrorExtensionsMap, type ExchangeExtensionMap, type ExchangeIO, type ExchangeResult, type FragmentOptions, type FragmentRefs, GraphQLError, type HttpOptions, type MutationOptions, type Operation, type OperationError, type OperationMetadata, type OperationMetadataMap, type OperationResult, type OperationResultMetadataMap, type QueryOptions, type RequiredAction, RequiredFieldError, type RetryOptions, type SchemaMeta, type SubscriptionClient, type SubscriptionExchangeOptions, type SubscriptionOptions, type VariablesOf, cacheExchange, createClient, dedupExchange, fragmentExchange, httpExchange, isAggregatedError, isExchangeError, isGraphQLError, requiredExchange, retryExchange, stringify, subscriptionExchange };
+export { AggregatedError, type Artifact, type ArtifactKind, type CacheOperations, type CacheOptions, type CacheSnapshot, Client, type ClientOptions, type DataOf, type Exchange, ExchangeError, type ExchangeErrorExtensionsMap, type ExchangeExtensionMap, type ExchangeIO, type ExchangeResult, type FragmentOptions, type FragmentRefs, GraphQLError, type HttpOptions, type InvalidateTarget, type MutationOptions, type Operation, type OperationError, type OperationMetadata, type OperationMetadataMap, type OperationResult, type OperationResultMetadataMap, type QueryOptions, type RequiredAction, RequiredFieldError, type RetryOptions, type SchemaMeta, type SubscriptionClient, type SubscriptionExchangeOptions, type SubscriptionOptions, type VariablesOf, cacheExchange, createClient, dedupExchange, fragmentExchange, httpExchange, isAggregatedError, isExchangeError, isGraphQLError, requiredExchange, retryExchange, stringify, subscriptionExchange };

package/dist/index.mjs

@@ -317,6 +317,12 @@ const RootFieldKey = "__root";
 * @internal
 */
 const FragmentRefKey = "__fragmentRef";
+/**
+* Special key used to carry merged variable context (fragment args + operation variables)
+* on fragment references. Used by readFragment to resolve variable-dependent field keys.
+* @internal
+*/
+const FragmentVarsKey = "__fragmentVars";
 
 //#endregion
 //#region src/cache/utils.ts
@@ -390,6 +396,14 @@ const isFragmentRef = (value) => {
 	return typeof value === "object" && value !== null && FragmentRefKey in value;
 };
 /**
+* Extracts the merged variable context for a specific fragment from a fragment reference.
+* Returns the merged variables (fragment args + operation variables) if present, or an empty object.
+* @internal
+*/
+const getFragmentVars = (fragmentRef, fragmentName) => {
+	return fragmentRef[FragmentVarsKey]?.[fragmentName] ?? {};
+};
+/**
 * Type guard to check if a value is an array of fragment references.
 * @internal
 * @param value - Value to check.
@@ -500,33 +514,20 @@ const mergeFields = (target, source) => {
 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, 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];
+		let entityMeta = schemaMeta.entities[typename];
 		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);
+			if (keys.every((k) => k !== void 0 && k !== null)) storageKey = makeEntityKey(typename, keys);
+			else entityMeta = void 0;
 		}
 		const fields = {};
 		for (const selection of selections) if (selection.kind === "Field") {
@@ -534,13 +535,11 @@ const normalize = (schemaMeta, selections, storage, data, variables, accessor) =
 			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;
+			fields[fieldKey] = selection.selections ? normalizeField(null, selection.selections, fieldValue) : fieldValue;
 			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 (inner !== SKIP && !isEntityLink(inner)) mergeFields(fields, inner);
+			if (!isEntityLink(inner)) mergeFields(fields, inner);
 		}
 		if (entityMeta && storageKey !== null) {
 			const existing = storage[storageKey];
@@ -595,6 +594,17 @@ const denormalize = (selections, storage, value, variables, accessor) => {
 			else fields[name] = value;
 		} else if (selection.kind === "FragmentSpread") if (storageKey !== null && storageKey !== RootFieldKey) {
 			fields[FragmentRefKey] = storageKey;
+			if (selection.args) {
+				const resolvedArgs = resolveArguments(selection.args, variables);
+				const mergedVars = {
+					...variables,
+					...resolvedArgs
+				};
+				fields[FragmentVarsKey] = {
+					...fields[FragmentVarsKey],
+					[selection.name]: mergedVars
+				};
+			}
 			if (accessor) denormalize(selection.selections, storage, { [EntityLinkKey]: storageKey }, variables, accessor);
 		} else mergeFields(fields, denormalizeField(storageKey, selection.selections, value));
 		else if (selection.kind === "InlineFragment" && selection.on === data[typenameFieldKey]) mergeFields(fields, denormalizeField(storageKey, selection.selections, value));
@@ -618,9 +628,74 @@ var Cache = class {
 	#subscriptions = /* @__PURE__ */ new Map();
 	#memo = /* @__PURE__ */ new Map();
 	#stale = /* @__PURE__ */ new Set();
+	#optimisticKeys = [];
+	#optimisticLayers = /* @__PURE__ */ new Map();
+	#storageView = null;
 	constructor(schemaMetadata) {
 		this.#schemaMeta = schemaMetadata;
 	}
+	#getStorageView() {
+		if (this.#optimisticKeys.length === 0) return this.#storage;
+		if (this.#storageView) return this.#storageView;
+		const merged = { ...this.#storage };
+		for (const storageKey of Object.keys(this.#storage)) merged[storageKey] = { ...this.#storage[storageKey] };
+		for (const key of this.#optimisticKeys) {
+			const layer = this.#optimisticLayers.get(key);
+			if (!layer) continue;
+			for (const storageKey of Object.keys(layer.storage)) merged[storageKey] = merged[storageKey] ? {
+				...merged[storageKey],
+				...layer.storage[storageKey]
+			} : { ...layer.storage[storageKey] };
+		}
+		this.#storageView = merged;
+		return merged;
+	}
+	/**
+	* Writes an optimistic response to a separate cache layer.
+	* The optimistic data is immediately visible in reads but does not affect the base storage.
+	* @internal
+	* @param key - Unique key identifying this optimistic mutation (typically the operation key).
+	* @param artifact - GraphQL document artifact.
+	* @param variables - Operation variables.
+	* @param data - The optimistic response data.
+	*/
+	writeOptimistic(key, artifact, variables, data) {
+		const layerStorage = { [RootFieldKey]: {} };
+		const dependencies = /* @__PURE__ */ new Set();
+		normalize(this.#schemaMeta, artifact.selections, layerStorage, data, variables, (storageKey, fieldKey) => {
+			dependencies.add(makeDependencyKey(storageKey, fieldKey));
+		});
+		this.#optimisticKeys.push(key);
+		this.#optimisticLayers.set(key, {
+			storage: layerStorage,
+			dependencies
+		});
+		this.#storageView = null;
+		const subscriptions = /* @__PURE__ */ new Set();
+		for (const depKey of dependencies) {
+			const ss = this.#subscriptions.get(depKey);
+			if (ss) for (const s of ss) subscriptions.add(s);
+		}
+		for (const subscription of subscriptions) subscription.listener();
+	}
+	/**
+	* Removes an optimistic layer and notifies affected subscribers.
+	* @internal
+	* @param key - The key of the optimistic layer to remove.
+	*/
+	removeOptimistic(key) {
+		const layer = this.#optimisticLayers.get(key);
+		if (!layer) return;
+		this.#optimisticLayers.delete(key);
+		this.#optimisticKeys = this.#optimisticKeys.filter((k) => k !== key);
+		this.#storageView = null;
+		const subscriptions = /* @__PURE__ */ new Set();
+		for (const depKey of layer.dependencies) {
+			const ss = this.#subscriptions.get(depKey);
+			if (ss) for (const s of ss) subscriptions.add(s);
+		}
+		for (const subscription of subscriptions) subscription.listener();
+	}
 	/**
 	* Writes a query result to the cache, normalizing entities.
 	* @param artifact - GraphQL document artifact.
@@ -653,7 +728,8 @@ var Cache = class {
 	*/
 	readQuery(artifact, variables) {
 		let stale = false;
-		const { data, partial } = denormalize(artifact.selections, this.#storage, this.#storage[RootFieldKey], variables, (storageKey, fieldKey) => {
+		const storage = this.#getStorageView();
+		const { data, partial } = denormalize(artifact.selections, storage, storage[RootFieldKey], variables, (storageKey, fieldKey) => {
 			if (this.#stale.has(storageKey) || this.#stale.has(makeDependencyKey(storageKey, fieldKey))) stale = true;
 		});
 		if (partial) return {
@@ -678,7 +754,8 @@ var Cache = class {
 	*/
 	subscribeQuery(artifact, variables, listener) {
 		const dependencies = /* @__PURE__ */ new Set();
-		denormalize(artifact.selections, this.#storage, this.#storage[RootFieldKey], variables, (storageKey, fieldKey) => {
+		const storageView = this.#getStorageView();
+		denormalize(artifact.selections, storageView, storageView[RootFieldKey], variables, (storageKey, fieldKey) => {
 			const dependencyKey = makeDependencyKey(storageKey, fieldKey);
 			dependencies.add(dependencyKey);
 		});
@@ -693,19 +770,22 @@ var Cache = class {
 	*/
 	readFragment(artifact, fragmentRef) {
 		const entityKey = fragmentRef[FragmentRefKey];
-		if (!this.#storage[entityKey]) return {
+		const fragmentVars = getFragmentVars(fragmentRef, artifact.name);
+		const storageView = this.#getStorageView();
+		if (!storageView[entityKey]) return {
 			data: null,
 			stale: false
 		};
 		let stale = false;
-		const { data, partial } = denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {}, (storageKey, fieldKey) => {
+		const { data, partial } = denormalize(artifact.selections, storageView, { [EntityLinkKey]: entityKey }, fragmentVars, (storageKey, fieldKey) => {
 			if (this.#stale.has(storageKey) || this.#stale.has(makeDependencyKey(storageKey, fieldKey))) stale = true;
 		});
 		if (partial) return {
 			data: null,
 			stale: false
 		};
-		const key = makeMemoKey("fragment", artifact.name, entityKey);
+		const argsId = Object.keys(fragmentVars).length > 0 ? entityKey + stringify(fragmentVars) : entityKey;
+		const key = makeMemoKey("fragment", artifact.name, argsId);
 		const prev = this.#memo.get(key);
 		const result = prev === void 0 ? data : replaceEqualDeep(prev, data);
 		this.#memo.set(key, result);
@@ -716,8 +796,10 @@ var Cache = class {
 	}
 	subscribeFragment(artifact, fragmentRef, listener) {
 		const entityKey = fragmentRef[FragmentRefKey];
+		const fragmentVars = getFragmentVars(fragmentRef, artifact.name);
 		const dependencies = /* @__PURE__ */ new Set();
-		denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {}, (storageKey, fieldKey) => {
+		const storageView = this.#getStorageView();
+		denormalize(artifact.selections, storageView, { [EntityLinkKey]: entityKey }, fragmentVars, (storageKey, fieldKey) => {
 			const dependencyKey = makeDependencyKey(storageKey, fieldKey);
 			dependencies.add(dependencyKey);
 		});
@@ -747,9 +829,11 @@ var Cache = class {
 	}
 	subscribeFragments(artifact, fragmentRefs, listener) {
 		const dependencies = /* @__PURE__ */ new Set();
+		const storageView = this.#getStorageView();
 		for (const ref of fragmentRefs) {
 			const entityKey = ref[FragmentRefKey];
-			denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {}, (storageKey, fieldKey) => {
+			const fragmentVars = getFragmentVars(ref, artifact.name);
+			denormalize(artifact.selections, storageView, { [EntityLinkKey]: entityKey }, fragmentVars, (storageKey, fieldKey) => {
 				dependencies.add(makeDependencyKey(storageKey, fieldKey));
 			});
 		}
@@ -761,8 +845,8 @@ var Cache = class {
 	*/
 	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);
+		for (const target of targets) if (target.__typename === "Query") if ("$field" in target) {
+			const fieldKey = makeFieldKeyFromArgs(target.$field, target.$args);
 			const depKey = makeDependencyKey(RootFieldKey, fieldKey);
 			this.#stale.add(depKey);
 			this.#collectSubscriptions(RootFieldKey, fieldKey, subscriptions);
@@ -770,32 +854,39 @@ var Cache = class {
 			this.#stale.add(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);
-				this.#stale.add(makeDependencyKey(entityKey, fieldKey));
-				this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
-			} else {
-				this.#stale.add(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);
+		else {
+			const keyFields = this.#schemaMeta.entities[target.__typename]?.keyFields;
+			if (keyFields && this.#hasKeyFields(target, keyFields)) {
+				const keyValues = keyFields.map((f) => target[f]);
+				const entityKey = makeEntityKey(target.__typename, keyValues);
+				if ("$field" in target) {
+					const fieldKey = makeFieldKeyFromArgs(target.$field, target.$args);
 					this.#stale.add(makeDependencyKey(entityKey, fieldKey));
 					this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
 				} else {
 					this.#stale.add(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);
+						this.#stale.add(makeDependencyKey(entityKey, fieldKey));
+						this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
+					} else {
+						this.#stale.add(entityKey);
+						this.#collectSubscriptions(entityKey, void 0, subscriptions);
+					}
+				}
 			}
 		}
 		for (const subscription of subscriptions) subscription.listener();
 	}
+	#hasKeyFields(target, keyFields) {
+		return keyFields.every((f) => f in target);
+	}
 	#collectSubscriptions(storageKey, fieldKey, out) {
 		if (fieldKey === void 0) {
 			const prefix = `${storageKey}.`;
@@ -823,6 +914,7 @@ var Cache = class {
 	}
 	/**
 	* Extracts a serializable snapshot of the cache storage and structural sharing state.
+	* Optimistic layers are excluded because they represent transient in-flight state.
 	*/
 	extract() {
 		return {
@@ -840,6 +932,7 @@ var Cache = class {
 			...fields
 		};
 		for (const [key, value] of Object.entries(memo)) this.#memo.set(key, value);
+		this.#storageView = null;
 	}
 	/**
 	* Clears all cache data.
@@ -849,6 +942,9 @@ var Cache = class {
 		this.#subscriptions.clear();
 		this.#memo.clear();
 		this.#stale.clear();
+		this.#optimisticKeys = [];
+		this.#optimisticLayers.clear();
+		this.#storageView = null;
 	}
 };
 
@@ -881,10 +977,10 @@ const cacheExchange = (options = {}) => {
 			},
 			io: (ops$) => {
 				const fragment$ = pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind === "fragment"), mergeMap((op) => {
-					const fragmentRef = op.metadata?.fragmentRef;
+					const fragmentRef = op.metadata?.fragment?.ref;
 					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" })]
+						errors: [new ExchangeError("Fragment operation missing fragment.ref in metadata. This usually happens when the wrong fragment reference was passed.", { exchangeName: "cache" })]
 					});
 					if (isFragmentRefArray(fragmentRef)) {
 						const trigger = makeSubject();
@@ -916,7 +1012,9 @@ const cacheExchange = (options = {}) => {
 						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 nonCache$ = pipe(ops$, filter((op) => op.variant === "request" && (op.artifact.kind === "mutation" || op.artifact.kind === "subscription" || op.artifact.kind === "query" && fetchPolicy === "network-only")), tap((op) => {
+					if (op.artifact.kind === "mutation" && op.metadata?.cache?.optimisticResponse) cache.writeOptimistic(op.key, op.artifact, op.variables, op.metadata.cache.optimisticResponse);
+				}));
 				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) => {
@@ -959,9 +1057,18 @@ const cacheExchange = (options = {}) => {
 				}), filter(() => fetchPolicy === "cache-only" || fetchPolicy === "cache-and-network" || fetchPolicy === "cache-first")), pipe(merge(nonCache$, pipe(query$, filter((op) => {
 					const { data } = cache.readQuery(op.artifact, op.variables);
 					return fetchPolicy === "cache-and-network" || data === null;
-				})), pipe(ops$, filter((op) => op.variant === "teardown")), refetch$.source), forward, tap((result) => {
+				})), pipe(ops$, filter((op) => op.variant === "teardown")), refetch$.source), forward, mergeMap((result) => {
+					if (result.operation.variant === "request" && result.operation.artifact.kind === "mutation" && result.operation.metadata?.cache?.optimisticResponse) cache.removeOptimistic(result.operation.key);
 					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))));
+					if (result.operation.variant !== "request" || result.operation.artifact.kind !== "query" || fetchPolicy === "network-only" || !!(result.errors && result.errors.length > 0)) return fromValue(result);
+					const { data } = cache.readQuery(result.operation.artifact, result.operation.variables);
+					if (data !== null) return empty();
+					return fromValue({
+						operation: result.operation,
+						data: void 0,
+						errors: [new ExchangeError("Cache failed to denormalize the network response. This is likely a bug in the cache normalizer.", { exchangeName: "cache" })]
+					});
+				})));
 			}
 		};
 	};
@@ -1013,10 +1120,10 @@ const fragmentExchange = () => {
 		name: "fragment",
 		io: (ops$) => {
 			return merge(pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind === "fragment"), map((op) => {
-				const fragmentRef = op.metadata.fragmentRef;
+				const fragmentRef = op.metadata.fragment?.ref;
 				if (!fragmentRef) return {
 					operation: op,
-					errors: [new ExchangeError("Fragment operation missing fragmentRef in metadata. This usually happens when the wrong fragment reference was passed.", { exchangeName: "fragment" })]
+					errors: [new ExchangeError("Fragment operation missing fragment.ref in metadata. This usually happens when the wrong fragment reference was passed.", { exchangeName: "fragment" })]
 				};
 				return {
 					operation: op,
@@ -1402,7 +1509,7 @@ var Client = class {
 			key: this.createOperationKey(),
 			metadata: {
 				...options?.metadata,
-				fragmentRef
+				fragment: { ref: fragmentRef }
 			},
 			artifact,
 			variables: {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearie/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Type-safe, zero-overhead GraphQL client",
   "keywords": [
     "graphql",
@@ -62,7 +62,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mearie/shared": "0.2.2"
+    "@mearie/shared": "0.4.0"
   },
   "devDependencies": {
     "tsdown": "^0.20.3",