@mearie/core 0.2.4 → 0.4.0

package/dist/index.cjs

@@ -501,18 +501,6 @@ 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
@@ -594,8 +582,10 @@ const denormalize = (selections, storage, value, variables, accessor) => {
 			const value = selection.selections ? denormalizeField(null, selection.selections, fieldValue) : fieldValue;
 			if (name in fields) mergeFields(fields, { [name]: value });
 			else fields[name] = value;
-		} else if (selection.kind === "FragmentSpread") if (storageKey !== null && storageKey !== RootFieldKey) fields[FragmentRefKey] = storageKey;
-		else mergeFields(fields, denormalizeField(storageKey, selection.selections, value));
+		} else if (selection.kind === "FragmentSpread") if (storageKey !== null && storageKey !== RootFieldKey) {
+			fields[FragmentRefKey] = storageKey;
+			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));
 		return fields;
 	};
@@ -616,6 +606,7 @@ var Cache = class {
 	#storage = { [RootFieldKey]: {} };
 	#subscriptions = /* @__PURE__ */ new Map();
 	#memo = /* @__PURE__ */ new Map();
+	#stale = /* @__PURE__ */ new Set();
 	constructor(schemaMetadata) {
 		this.#schemaMeta = schemaMetadata;
 	}
@@ -628,17 +619,19 @@ var Cache = class {
 	writeQuery(artifact, variables, data) {
 		const dependencies = /* @__PURE__ */ new Set();
 		const subscriptions = /* @__PURE__ */ new Set();
+		const entityStaleCleared = /* @__PURE__ */ new Set();
 		normalize(this.#schemaMeta, artifact.selections, this.#storage, data, variables, (storageKey, fieldKey, oldValue, newValue) => {
-			if (oldValue !== newValue) {
-				const dependencyKey = makeDependencyKey(storageKey, fieldKey);
-				dependencies.add(dependencyKey);
-			}
+			const depKey = makeDependencyKey(storageKey, fieldKey);
+			if (this.#stale.delete(depKey)) dependencies.add(depKey);
+			if (!entityStaleCleared.has(storageKey) && this.#stale.delete(storageKey)) entityStaleCleared.add(storageKey);
+			if (oldValue !== newValue) dependencies.add(depKey);
 		});
+		for (const entityKey of entityStaleCleared) this.#collectSubscriptions(entityKey, void 0, subscriptions);
 		for (const dependency of dependencies) {
 			const ss = this.#subscriptions.get(dependency);
 			if (ss) for (const s of ss) subscriptions.add(s);
 		}
-		for (const subscription of subscriptions) subscription.listener("write");
+		for (const subscription of subscriptions) subscription.listener();
 	}
 	/**
 	* Reads a query result from the cache, denormalizing entities if available.
@@ -648,13 +641,22 @@ var Cache = class {
 	* @returns Denormalized query result or null if not found.
 	*/
 	readQuery(artifact, variables) {
-		const { data, partial } = denormalize(artifact.selections, this.#storage, this.#storage[RootFieldKey], variables);
-		if (partial) return null;
+		let stale = false;
+		const { data, partial } = denormalize(artifact.selections, this.#storage, this.#storage[RootFieldKey], variables, (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("query", artifact.name, stringify(variables));
 		const prev = this.#memo.get(key);
 		const result = prev === void 0 ? data : replaceEqualDeep(prev, data);
 		this.#memo.set(key, result);
-		return result;
+		return {
+			data: result,
+			stale
+		};
 	}
 	/**
 	* Subscribes to cache invalidations for a specific query.
@@ -680,14 +682,26 @@ var Cache = class {
 	*/
 	readFragment(artifact, fragmentRef) {
 		const entityKey = fragmentRef[FragmentRefKey];
-		if (!this.#storage[entityKey]) return null;
-		const { data, partial } = denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {});
-		if (partial) return null;
+		if (!this.#storage[entityKey]) return {
+			data: null,
+			stale: false
+		};
+		let stale = false;
+		const { data, partial } = denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {}, (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 prev = this.#memo.get(key);
 		const result = prev === void 0 ? data : replaceEqualDeep(prev, data);
 		this.#memo.set(key, result);
-		return result;
+		return {
+			data: result,
+			stale
+		};
 	}
 	subscribeFragment(artifact, fragmentRef, listener) {
 		const entityKey = fragmentRef[FragmentRefKey];
@@ -700,17 +714,25 @@ var Cache = class {
 	}
 	readFragments(artifact, fragmentRefs) {
 		const results = [];
+		let stale = false;
 		for (const ref of fragmentRefs) {
-			const data = this.readFragment(artifact, ref);
-			if (data === null) return null;
-			results.push(data);
+			const result = this.readFragment(artifact, ref);
+			if (result.data === null) return {
+				data: null,
+				stale: false
+			};
+			if (result.stale) stale = true;
+			results.push(result.data);
 		}
 		const entityKeys = fragmentRefs.map((ref) => ref[FragmentRefKey]);
 		const key = makeMemoKey("fragments", artifact.name, entityKeys.join(","));
 		const prev = this.#memo.get(key);
 		const result = prev === void 0 ? results : replaceEqualDeep(prev, results);
 		this.#memo.set(key, result);
-		return result;
+		return {
+			data: result,
+			stale
+		};
 	}
 	subscribeFragments(artifact, fragmentRefs, listener) {
 		const dependencies = /* @__PURE__ */ new Set();
@@ -728,50 +750,47 @@ 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);
-			delete this.#storage[RootFieldKey]?.[fieldKey];
+		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);
 		} else {
-			this.#storage[RootFieldKey] = {};
+			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);
-				delete this.#storage[entityKey]?.[fieldKey];
-				this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
-			} else {
-				delete this.#storage[entityKey];
-				this.#collectSubscriptions(entityKey, void 0, subscriptions);
-			}
-			this.#collectLinkedEntitySubscriptions((linkedEntityKey) => linkedEntityKey === entityKey, subscriptions);
-		} else {
-			const prefix = `${target.__typename}:`;
-			for (const key of Object.keys(this.#storage)) if (key.startsWith(prefix)) {
-				const entityKey = key;
-				if ("field" in target) {
-					const fieldKey = makeFieldKeyFromArgs(target.field, target.args);
-					delete this.#storage[entityKey]?.[fieldKey];
+		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 {
-					delete this.#storage[entityKey];
+					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);
+					}
+				}
 			}
-			this.#collectLinkedEntitySubscriptions((linkedEntityKey) => linkedEntityKey.startsWith(prefix), subscriptions);
 		}
-		for (const subscription of subscriptions) subscription.listener("invalidate");
-	}
-	#collectLinkedEntitySubscriptions(matcher, out) {
-		for (const [storageKey, fields] of Object.entries(this.#storage)) for (const [fieldKey, value] of Object.entries(fields)) if (this.#containsEntityLink(value, matcher)) this.#collectSubscriptions(storageKey, fieldKey, out);
+		for (const subscription of subscriptions) subscription.listener();
 	}
-	#containsEntityLink(value, matcher) {
-		if (isEntityLink(value)) return matcher(value[EntityLinkKey]);
-		if (Array.isArray(value)) return value.some((item) => this.#containsEntityLink(item, matcher));
-		if (value && typeof value === "object") return Object.values(value).some((item) => this.#containsEntityLink(item, matcher));
-		return false;
+	#hasKeyFields(target, keyFields) {
+		return keyFields.every((f) => f in target);
 	}
 	#collectSubscriptions(storageKey, fieldKey, out) {
 		if (fieldKey === void 0) {
@@ -825,6 +844,7 @@ var Cache = class {
 		this.#storage = { [RootFieldKey]: {} };
 		this.#subscriptions.clear();
 		this.#memo.clear();
+		this.#stale.clear();
 	}
 };
 
@@ -864,27 +884,16 @@ const cacheExchange = (options = {}) => {
 					});
 					if (isFragmentRefArray(fragmentRef)) {
 						const trigger = require_make.makeSubject();
-						let hasData = false;
 						const teardown$ = require_make.pipe(ops$, require_make.filter((operation) => operation.variant === "teardown" && operation.key === op.key), require_make.tap(() => trigger.complete()));
 						return require_make.pipe(require_make.merge(require_make.fromValue(void 0), trigger.source), require_make.switchMap(() => require_make.fromSubscription(() => cache.readFragments(op.artifact, fragmentRef), () => cache.subscribeFragments(op.artifact, fragmentRef, async () => {
 							await Promise.resolve();
 							trigger.next();
-						}))), require_make.takeUntil(teardown$), require_make.mergeMap((data) => {
-							if (data !== null) {
-								hasData = true;
-								return require_make.fromValue({
-									operation: op,
-									data,
-									errors: []
-								});
-							}
-							if (hasData) return empty();
-							return require_make.fromValue({
-								operation: op,
-								data,
-								errors: []
-							});
-						}));
+						}))), require_make.takeUntil(teardown$), require_make.map(({ data, stale }) => ({
+							operation: op,
+							data,
+							...stale && { metadata: { cache: { stale: true } } },
+							errors: []
+						})));
 					}
 					if (!isFragmentRef(fragmentRef)) return require_make.fromValue({
 						operation: op,
@@ -892,27 +901,16 @@ const cacheExchange = (options = {}) => {
 						errors: []
 					});
 					const trigger = require_make.makeSubject();
-					let hasData = false;
 					const teardown$ = require_make.pipe(ops$, require_make.filter((operation) => operation.variant === "teardown" && operation.key === op.key), require_make.tap(() => trigger.complete()));
 					return require_make.pipe(require_make.merge(require_make.fromValue(void 0), trigger.source), require_make.switchMap(() => require_make.fromSubscription(() => cache.readFragment(op.artifact, fragmentRef), () => cache.subscribeFragment(op.artifact, fragmentRef, async () => {
 						await Promise.resolve();
 						trigger.next();
-					}))), require_make.takeUntil(teardown$), require_make.mergeMap((data) => {
-						if (data !== null) {
-							hasData = true;
-							return require_make.fromValue({
-								operation: op,
-								data,
-								errors: []
-							});
-						}
-						if (hasData) return empty();
-						return require_make.fromValue({
-							operation: op,
-							data,
-							errors: []
-						});
-					}));
+					}))), require_make.takeUntil(teardown$), require_make.map(({ data, stale }) => ({
+						operation: op,
+						data,
+						...stale && { metadata: { cache: { stale: true } } },
+						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 query$ = require_make.pipe(ops$, require_make.filter((op) => op.variant === "request" && op.artifact.kind === "query" && fetchPolicy !== "network-only"), require_make.share());
@@ -920,30 +918,31 @@ const cacheExchange = (options = {}) => {
 				return require_make.merge(fragment$, require_make.pipe(query$, require_make.mergeMap((op) => {
 					const trigger = require_make.makeSubject();
 					let hasData = false;
-					let invalidated = false;
 					const teardown$ = require_make.pipe(ops$, require_make.filter((operation) => operation.variant === "teardown" && operation.key === op.key), require_make.tap(() => trigger.complete()));
-					return require_make.pipe(require_make.merge(require_make.fromValue(void 0), trigger.source), require_make.switchMap(() => require_make.fromSubscription(() => cache.readQuery(op.artifact, op.variables), () => cache.subscribeQuery(op.artifact, op.variables, async (event) => {
-						if (event === "invalidate") invalidated = true;
+					return require_make.pipe(require_make.merge(require_make.fromValue(void 0), trigger.source), require_make.switchMap(() => require_make.fromSubscription(() => cache.readQuery(op.artifact, op.variables), () => cache.subscribeQuery(op.artifact, op.variables, async () => {
 						await Promise.resolve();
 						trigger.next();
-					}))), require_make.takeUntil(teardown$), require_make.mergeMap((data) => {
-						if (data !== null) {
-							if (invalidated && hasData && fetchPolicy !== "cache-only") {
-								invalidated = false;
-								refetch$.next(op);
-								return empty();
-							}
+					}))), require_make.takeUntil(teardown$), require_make.mergeMap(({ data, stale }) => {
+						if (data !== null && !stale) {
+							hasData = true;
+							return require_make.fromValue({
+								operation: op,
+								data,
+								errors: []
+							});
+						}
+						if (data !== null && stale) {
 							hasData = true;
-							invalidated = false;
+							refetch$.next(op);
 							return require_make.fromValue({
 								operation: op,
 								data,
+								metadata: { cache: { stale: true } },
 								errors: []
 							});
 						}
 						if (hasData) {
-							if (fetchPolicy !== "cache-only") refetch$.next(op);
-							invalidated = false;
+							refetch$.next(op);
 							return empty();
 						}
 						if (fetchPolicy === "cache-only") return require_make.fromValue({
@@ -954,8 +953,8 @@ const cacheExchange = (options = {}) => {
 						return empty();
 					}));
 				}), 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 cached = cache.readQuery(op.artifact, op.variables);
-					return fetchPolicy === "cache-and-network" || cached === null;
+					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) => {
 					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))));

package/dist/index.d.cts

@@ -106,9 +106,9 @@ declare class Client<TMeta extends SchemaMeta$1 = SchemaMeta$1> {
    * @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;
 }
@@ -116,6 +116,7 @@ declare const createClient: <T extends SchemaMeta$1>(config: ClientOptions<T>) =
 //#endregion
 //#region src/exchange.d.ts
 interface OperationMetadataMap {}
+interface OperationResultMetadataMap {}
 type OperationMetadata = { [K in keyof OperationMetadataMap]?: OperationMetadataMap[K] } & Record<string, unknown>;
 type BaseOperation = {
   key: string;
@@ -135,21 +136,21 @@ type OperationResult = {
   data?: unknown;
   errors?: readonly OperationError[];
   extensions?: Record<string, unknown>;
-  stale?: boolean;
+  metadata?: OperationResultMetadataMap & Record<string, unknown>;
 };
 type ExchangeInput<TMeta extends SchemaMeta$1 = SchemaMeta$1> = {
   forward: ExchangeIO;
   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' {
@@ -194,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.
  */
@@ -231,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 OperationResultMetadataMap {
+    cache?: {
+      stale: boolean;
+    };
   }
 }
 type CacheOptions = {
@@ -345,4 +355,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 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

@@ -106,9 +106,9 @@ declare class Client<TMeta extends SchemaMeta$1 = SchemaMeta$1> {
    * @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;
 }
@@ -116,6 +116,7 @@ declare const createClient: <T extends SchemaMeta$1>(config: ClientOptions<T>) =
 //#endregion
 //#region src/exchange.d.ts
 interface OperationMetadataMap {}
+interface OperationResultMetadataMap {}
 type OperationMetadata = { [K in keyof OperationMetadataMap]?: OperationMetadataMap[K] } & Record<string, unknown>;
 type BaseOperation = {
   key: string;
@@ -135,21 +136,21 @@ type OperationResult = {
   data?: unknown;
   errors?: readonly OperationError[];
   extensions?: Record<string, unknown>;
-  stale?: boolean;
+  metadata?: OperationResultMetadataMap & Record<string, unknown>;
 };
 type ExchangeInput<TMeta extends SchemaMeta$1 = SchemaMeta$1> = {
   forward: ExchangeIO;
   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' {
@@ -194,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.
  */
@@ -231,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 OperationResultMetadataMap {
+    cache?: {
+      stale: boolean;
+    };
   }
 }
 type CacheOptions = {
@@ -345,4 +355,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 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

@@ -500,18 +500,6 @@ 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
@@ -593,8 +581,10 @@ const denormalize = (selections, storage, value, variables, accessor) => {
 			const value = selection.selections ? denormalizeField(null, selection.selections, fieldValue) : fieldValue;
 			if (name in fields) mergeFields(fields, { [name]: value });
 			else fields[name] = value;
-		} else if (selection.kind === "FragmentSpread") if (storageKey !== null && storageKey !== RootFieldKey) fields[FragmentRefKey] = storageKey;
-		else mergeFields(fields, denormalizeField(storageKey, selection.selections, value));
+		} else if (selection.kind === "FragmentSpread") if (storageKey !== null && storageKey !== RootFieldKey) {
+			fields[FragmentRefKey] = storageKey;
+			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));
 		return fields;
 	};
@@ -615,6 +605,7 @@ var Cache = class {
 	#storage = { [RootFieldKey]: {} };
 	#subscriptions = /* @__PURE__ */ new Map();
 	#memo = /* @__PURE__ */ new Map();
+	#stale = /* @__PURE__ */ new Set();
 	constructor(schemaMetadata) {
 		this.#schemaMeta = schemaMetadata;
 	}
@@ -627,17 +618,19 @@ var Cache = class {
 	writeQuery(artifact, variables, data) {
 		const dependencies = /* @__PURE__ */ new Set();
 		const subscriptions = /* @__PURE__ */ new Set();
+		const entityStaleCleared = /* @__PURE__ */ new Set();
 		normalize(this.#schemaMeta, artifact.selections, this.#storage, data, variables, (storageKey, fieldKey, oldValue, newValue) => {
-			if (oldValue !== newValue) {
-				const dependencyKey = makeDependencyKey(storageKey, fieldKey);
-				dependencies.add(dependencyKey);
-			}
+			const depKey = makeDependencyKey(storageKey, fieldKey);
+			if (this.#stale.delete(depKey)) dependencies.add(depKey);
+			if (!entityStaleCleared.has(storageKey) && this.#stale.delete(storageKey)) entityStaleCleared.add(storageKey);
+			if (oldValue !== newValue) dependencies.add(depKey);
 		});
+		for (const entityKey of entityStaleCleared) this.#collectSubscriptions(entityKey, void 0, subscriptions);
 		for (const dependency of dependencies) {
 			const ss = this.#subscriptions.get(dependency);
 			if (ss) for (const s of ss) subscriptions.add(s);
 		}
-		for (const subscription of subscriptions) subscription.listener("write");
+		for (const subscription of subscriptions) subscription.listener();
 	}
 	/**
 	* Reads a query result from the cache, denormalizing entities if available.
@@ -647,13 +640,22 @@ var Cache = class {
 	* @returns Denormalized query result or null if not found.
 	*/
 	readQuery(artifact, variables) {
-		const { data, partial } = denormalize(artifact.selections, this.#storage, this.#storage[RootFieldKey], variables);
-		if (partial) return null;
+		let stale = false;
+		const { data, partial } = denormalize(artifact.selections, this.#storage, this.#storage[RootFieldKey], variables, (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("query", artifact.name, stringify(variables));
 		const prev = this.#memo.get(key);
 		const result = prev === void 0 ? data : replaceEqualDeep(prev, data);
 		this.#memo.set(key, result);
-		return result;
+		return {
+			data: result,
+			stale
+		};
 	}
 	/**
 	* Subscribes to cache invalidations for a specific query.
@@ -679,14 +681,26 @@ var Cache = class {
 	*/
 	readFragment(artifact, fragmentRef) {
 		const entityKey = fragmentRef[FragmentRefKey];
-		if (!this.#storage[entityKey]) return null;
-		const { data, partial } = denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {});
-		if (partial) return null;
+		if (!this.#storage[entityKey]) return {
+			data: null,
+			stale: false
+		};
+		let stale = false;
+		const { data, partial } = denormalize(artifact.selections, this.#storage, { [EntityLinkKey]: entityKey }, {}, (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 prev = this.#memo.get(key);
 		const result = prev === void 0 ? data : replaceEqualDeep(prev, data);
 		this.#memo.set(key, result);
-		return result;
+		return {
+			data: result,
+			stale
+		};
 	}
 	subscribeFragment(artifact, fragmentRef, listener) {
 		const entityKey = fragmentRef[FragmentRefKey];
@@ -699,17 +713,25 @@ var Cache = class {
 	}
 	readFragments(artifact, fragmentRefs) {
 		const results = [];
+		let stale = false;
 		for (const ref of fragmentRefs) {
-			const data = this.readFragment(artifact, ref);
-			if (data === null) return null;
-			results.push(data);
+			const result = this.readFragment(artifact, ref);
+			if (result.data === null) return {
+				data: null,
+				stale: false
+			};
+			if (result.stale) stale = true;
+			results.push(result.data);
 		}
 		const entityKeys = fragmentRefs.map((ref) => ref[FragmentRefKey]);
 		const key = makeMemoKey("fragments", artifact.name, entityKeys.join(","));
 		const prev = this.#memo.get(key);
 		const result = prev === void 0 ? results : replaceEqualDeep(prev, results);
 		this.#memo.set(key, result);
-		return result;
+		return {
+			data: result,
+			stale
+		};
 	}
 	subscribeFragments(artifact, fragmentRefs, listener) {
 		const dependencies = /* @__PURE__ */ new Set();
@@ -727,50 +749,47 @@ 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);
-			delete this.#storage[RootFieldKey]?.[fieldKey];
+		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);
 		} else {
-			this.#storage[RootFieldKey] = {};
+			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);
-				delete this.#storage[entityKey]?.[fieldKey];
-				this.#collectSubscriptions(entityKey, fieldKey, subscriptions);
-			} else {
-				delete this.#storage[entityKey];
-				this.#collectSubscriptions(entityKey, void 0, subscriptions);
-			}
-			this.#collectLinkedEntitySubscriptions((linkedEntityKey) => linkedEntityKey === entityKey, subscriptions);
-		} else {
-			const prefix = `${target.__typename}:`;
-			for (const key of Object.keys(this.#storage)) if (key.startsWith(prefix)) {
-				const entityKey = key;
-				if ("field" in target) {
-					const fieldKey = makeFieldKeyFromArgs(target.field, target.args);
-					delete this.#storage[entityKey]?.[fieldKey];
+		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 {
-					delete this.#storage[entityKey];
+					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);
+					}
+				}
 			}
-			this.#collectLinkedEntitySubscriptions((linkedEntityKey) => linkedEntityKey.startsWith(prefix), subscriptions);
 		}
-		for (const subscription of subscriptions) subscription.listener("invalidate");
-	}
-	#collectLinkedEntitySubscriptions(matcher, out) {
-		for (const [storageKey, fields] of Object.entries(this.#storage)) for (const [fieldKey, value] of Object.entries(fields)) if (this.#containsEntityLink(value, matcher)) this.#collectSubscriptions(storageKey, fieldKey, out);
+		for (const subscription of subscriptions) subscription.listener();
 	}
-	#containsEntityLink(value, matcher) {
-		if (isEntityLink(value)) return matcher(value[EntityLinkKey]);
-		if (Array.isArray(value)) return value.some((item) => this.#containsEntityLink(item, matcher));
-		if (value && typeof value === "object") return Object.values(value).some((item) => this.#containsEntityLink(item, matcher));
-		return false;
+	#hasKeyFields(target, keyFields) {
+		return keyFields.every((f) => f in target);
 	}
 	#collectSubscriptions(storageKey, fieldKey, out) {
 		if (fieldKey === void 0) {
@@ -824,6 +843,7 @@ var Cache = class {
 		this.#storage = { [RootFieldKey]: {} };
 		this.#subscriptions.clear();
 		this.#memo.clear();
+		this.#stale.clear();
 	}
 };
 
@@ -863,27 +883,16 @@ const cacheExchange = (options = {}) => {
 					});
 					if (isFragmentRefArray(fragmentRef)) {
 						const trigger = makeSubject();
-						let hasData = false;
 						const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key), tap(() => trigger.complete()));
 						return pipe(merge(fromValue(void 0), trigger.source), switchMap(() => fromSubscription(() => cache.readFragments(op.artifact, fragmentRef), () => cache.subscribeFragments(op.artifact, fragmentRef, async () => {
 							await Promise.resolve();
 							trigger.next();
-						}))), takeUntil(teardown$), mergeMap((data) => {
-							if (data !== null) {
-								hasData = true;
-								return fromValue({
-									operation: op,
-									data,
-									errors: []
-								});
-							}
-							if (hasData) return empty();
-							return fromValue({
-								operation: op,
-								data,
-								errors: []
-							});
-						}));
+						}))), takeUntil(teardown$), map(({ data, stale }) => ({
+							operation: op,
+							data,
+							...stale && { metadata: { cache: { stale: true } } },
+							errors: []
+						})));
 					}
 					if (!isFragmentRef(fragmentRef)) return fromValue({
 						operation: op,
@@ -891,27 +900,16 @@ const cacheExchange = (options = {}) => {
 						errors: []
 					});
 					const trigger = makeSubject();
-					let hasData = false;
 					const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key), tap(() => trigger.complete()));
 					return pipe(merge(fromValue(void 0), trigger.source), switchMap(() => fromSubscription(() => cache.readFragment(op.artifact, fragmentRef), () => cache.subscribeFragment(op.artifact, fragmentRef, async () => {
 						await Promise.resolve();
 						trigger.next();
-					}))), takeUntil(teardown$), mergeMap((data) => {
-						if (data !== null) {
-							hasData = true;
-							return fromValue({
-								operation: op,
-								data,
-								errors: []
-							});
-						}
-						if (hasData) return empty();
-						return fromValue({
-							operation: op,
-							data,
-							errors: []
-						});
-					}));
+					}))), takeUntil(teardown$), map(({ data, stale }) => ({
+						operation: op,
+						data,
+						...stale && { metadata: { cache: { stale: true } } },
+						errors: []
+					})));
 				}));
 				const nonCache$ = pipe(ops$, filter((op) => op.variant === "request" && (op.artifact.kind === "mutation" || op.artifact.kind === "subscription" || op.artifact.kind === "query" && fetchPolicy === "network-only")));
 				const query$ = pipe(ops$, filter((op) => op.variant === "request" && op.artifact.kind === "query" && fetchPolicy !== "network-only"), share());
@@ -919,30 +917,31 @@ const cacheExchange = (options = {}) => {
 				return merge(fragment$, pipe(query$, mergeMap((op) => {
 					const trigger = makeSubject();
 					let hasData = false;
-					let invalidated = false;
 					const teardown$ = pipe(ops$, filter((operation) => operation.variant === "teardown" && operation.key === op.key), tap(() => trigger.complete()));
-					return pipe(merge(fromValue(void 0), trigger.source), switchMap(() => fromSubscription(() => cache.readQuery(op.artifact, op.variables), () => cache.subscribeQuery(op.artifact, op.variables, async (event) => {
-						if (event === "invalidate") invalidated = true;
+					return pipe(merge(fromValue(void 0), trigger.source), switchMap(() => fromSubscription(() => cache.readQuery(op.artifact, op.variables), () => cache.subscribeQuery(op.artifact, op.variables, async () => {
 						await Promise.resolve();
 						trigger.next();
-					}))), takeUntil(teardown$), mergeMap((data) => {
-						if (data !== null) {
-							if (invalidated && hasData && fetchPolicy !== "cache-only") {
-								invalidated = false;
-								refetch$.next(op);
-								return empty();
-							}
+					}))), takeUntil(teardown$), mergeMap(({ data, stale }) => {
+						if (data !== null && !stale) {
+							hasData = true;
+							return fromValue({
+								operation: op,
+								data,
+								errors: []
+							});
+						}
+						if (data !== null && stale) {
 							hasData = true;
-							invalidated = false;
+							refetch$.next(op);
 							return fromValue({
 								operation: op,
 								data,
+								metadata: { cache: { stale: true } },
 								errors: []
 							});
 						}
 						if (hasData) {
-							if (fetchPolicy !== "cache-only") refetch$.next(op);
-							invalidated = false;
+							refetch$.next(op);
 							return empty();
 						}
 						if (fetchPolicy === "cache-only") return fromValue({
@@ -953,8 +952,8 @@ const cacheExchange = (options = {}) => {
 						return empty();
 					}));
 				}), filter(() => fetchPolicy === "cache-only" || fetchPolicy === "cache-and-network" || fetchPolicy === "cache-first")), pipe(merge(nonCache$, pipe(query$, filter((op) => {
-					const cached = cache.readQuery(op.artifact, op.variables);
-					return fetchPolicy === "cache-and-network" || cached === null;
+					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) => {
 					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))));

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "@mearie/core",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "Type-safe, zero-overhead GraphQL client",
   "keywords": [
     "graphql",
     "graphql-client",
     "typescript",
+    "type-safe",
     "codegen",
-    "cache"
+    "cache",
+    "normalized-cache",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "vite"
   ],
-  "homepage": "https://github.com/devunt/mearie#readme",
+  "homepage": "https://mearie.dev/",
   "bugs": {
     "url": "https://github.com/devunt/mearie/issues"
   },
@@ -55,7 +62,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mearie/shared": "0.2.1"
+    "@mearie/shared": "0.3.0"
   },
   "devDependencies": {
     "tsdown": "^0.20.3",