@mearie/core 0.4.0 → 0.5.1

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.
@@ -504,38 +518,47 @@ const makeFieldKeyFromArgs = (field, args) => {
 
 //#endregion
 //#region src/cache/normalize.ts
-const SKIP = Symbol();
+const resolveTypename = (selections, data) => {
+	for (const s of selections) if (s.kind === "Field" && s.name === "__typename") return data[s.alias ?? "__typename"];
+	return data.__typename;
+};
 const normalize = (schemaMeta, selections, storage, data, variables, accessor) => {
+	const resolveEntityKey = (typename, data) => {
+		if (!typename) return null;
+		const entityMeta = schemaMeta.entities[typename];
+		if (!entityMeta) return null;
+		const keys = entityMeta.keyFields.map((field) => data[field]);
+		if (keys.every((k) => k !== void 0 && k !== null)) return makeEntityKey(typename, keys);
+		return null;
+	};
 	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) {
-			const keys = entityMeta.keyFields.map((field) => data[field]);
-			if (!keys.every((k) => k !== void 0 && k !== null)) return SKIP;
-			storageKey = makeEntityKey(typename, keys);
-		}
+		const typename = resolveTypename(selections, data);
+		const entityKey = resolveEntityKey(typename, data);
+		if (entityKey) storageKey = entityKey;
 		const fields = {};
 		for (const selection of selections) if (selection.kind === "Field") {
 			const fieldKey = makeFieldKey(selection, variables);
 			const fieldValue = data[selection.alias ?? selection.name];
+			if (storageKey !== null && selection.selections && typeof fieldValue === "object" && fieldValue !== null && !Array.isArray(fieldValue)) {
+				const fieldTypename = resolveTypename(selection.selections, fieldValue);
+				if (fieldTypename && schemaMeta.entities[fieldTypename] && !resolveEntityKey(fieldTypename, fieldValue) && isEntityLink(storage[storageKey]?.[fieldKey])) continue;
+			}
 			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];
+		if (entityKey) {
+			const existing = storage[entityKey];
 			if (existing) mergeFields(existing, fields);
-			else storage[storageKey] = fields;
-			return { [EntityLinkKey]: storageKey };
+			else storage[entityKey] = fields;
+			return { [EntityLinkKey]: entityKey };
 		}
 		return fields;
 	};
@@ -584,6 +607,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));
@@ -607,9 +641,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.
@@ -642,7 +741,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 {
@@ -667,7 +767,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);
 		});
@@ -682,19 +783,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);
@@ -705,8 +809,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);
 		});
@@ -736,9 +842,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));
 			});
 		}
@@ -819,6 +927,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 {
@@ -836,6 +945,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.
@@ -845,6 +955,9 @@ var Cache = class {
 		this.#subscriptions.clear();
 		this.#memo.clear();
 		this.#stale.clear();
+		this.#optimisticKeys = [];
+		this.#optimisticLayers.clear();
+		this.#storageView = null;
 	}
 };
 
@@ -877,10 +990,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();
@@ -912,7 +1025,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) => {
@@ -955,9 +1070,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" })]
+					});
+				})));
 			}
 		};
 	};
@@ -1009,10 +1133,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,
@@ -1398,7 +1522,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,14 +93,14 @@ 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.
@@ -115,9 +115,9 @@ declare class Client<TMeta extends SchemaMeta$1 = SchemaMeta$1> {
 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>;
@@ -248,6 +248,11 @@ declare module '@mearie/core' {
   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?: {
       stale: boolean;
@@ -278,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;

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,14 +93,14 @@ 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.
@@ -115,9 +115,9 @@ declare class Client<TMeta extends SchemaMeta$1 = SchemaMeta$1> {
 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>;
@@ -248,6 +248,11 @@ declare module '@mearie/core' {
   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?: {
       stale: boolean;
@@ -278,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;

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.
@@ -503,38 +517,47 @@ const makeFieldKeyFromArgs = (field, args) => {
 
 //#endregion
 //#region src/cache/normalize.ts
-const SKIP = Symbol();
+const resolveTypename = (selections, data) => {
+	for (const s of selections) if (s.kind === "Field" && s.name === "__typename") return data[s.alias ?? "__typename"];
+	return data.__typename;
+};
 const normalize = (schemaMeta, selections, storage, data, variables, accessor) => {
+	const resolveEntityKey = (typename, data) => {
+		if (!typename) return null;
+		const entityMeta = schemaMeta.entities[typename];
+		if (!entityMeta) return null;
+		const keys = entityMeta.keyFields.map((field) => data[field]);
+		if (keys.every((k) => k !== void 0 && k !== null)) return makeEntityKey(typename, keys);
+		return null;
+	};
 	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) {
-			const keys = entityMeta.keyFields.map((field) => data[field]);
-			if (!keys.every((k) => k !== void 0 && k !== null)) return SKIP;
-			storageKey = makeEntityKey(typename, keys);
-		}
+		const typename = resolveTypename(selections, data);
+		const entityKey = resolveEntityKey(typename, data);
+		if (entityKey) storageKey = entityKey;
 		const fields = {};
 		for (const selection of selections) if (selection.kind === "Field") {
 			const fieldKey = makeFieldKey(selection, variables);
 			const fieldValue = data[selection.alias ?? selection.name];
+			if (storageKey !== null && selection.selections && typeof fieldValue === "object" && fieldValue !== null && !Array.isArray(fieldValue)) {
+				const fieldTypename = resolveTypename(selection.selections, fieldValue);
+				if (fieldTypename && schemaMeta.entities[fieldTypename] && !resolveEntityKey(fieldTypename, fieldValue) && isEntityLink(storage[storageKey]?.[fieldKey])) continue;
+			}
 			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];
+		if (entityKey) {
+			const existing = storage[entityKey];
 			if (existing) mergeFields(existing, fields);
-			else storage[storageKey] = fields;
-			return { [EntityLinkKey]: storageKey };
+			else storage[entityKey] = fields;
+			return { [EntityLinkKey]: entityKey };
 		}
 		return fields;
 	};
@@ -583,6 +606,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));
@@ -606,9 +640,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.
@@ -641,7 +740,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 {
@@ -666,7 +766,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);
 		});
@@ -681,19 +782,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);
@@ -704,8 +808,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);
 		});
@@ -735,9 +841,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));
 			});
 		}
@@ -818,6 +926,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 {
@@ -835,6 +944,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.
@@ -844,6 +954,9 @@ var Cache = class {
 		this.#subscriptions.clear();
 		this.#memo.clear();
 		this.#stale.clear();
+		this.#optimisticKeys = [];
+		this.#optimisticLayers.clear();
+		this.#storageView = null;
 	}
 };
 
@@ -876,10 +989,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();
@@ -911,7 +1024,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) => {
@@ -954,9 +1069,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" })]
+					});
+				})));
 			}
 		};
 	};
@@ -1008,10 +1132,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,
@@ -1397,7 +1521,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.4.0",
+  "version": "0.5.1",
   "description": "Type-safe, zero-overhead GraphQL client",
   "keywords": [
     "graphql",
@@ -62,7 +62,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mearie/shared": "0.3.0"
+    "@mearie/shared": "0.4.0"
   },
   "devDependencies": {
     "tsdown": "^0.20.3",