@effector-tanstack-query/core 0.3.0 → 0.5.0

package/dist/types.d.cts

@@ -118,6 +118,30 @@ interface QueryResult<TData, TError = Error> {
      * `$queryClient` and honors `fork({ values: [[$queryClient, qc]] })`.
      */
     $queryClient: Store<QueryClient | null>;
+    /**
+     * Lifecycle events for `sample`-driven reactions to fetch completion.
+     *
+     * - `success` fires with the (post-`select`) data on every newly-finished
+     *   successful fetch — fresh fetch, refetch, reactive key change, or a
+     *   cross-scope `setQueryData`.
+     * - `failure` fires with the error on every failed fetch.
+     *
+     * Neither fires for the baseline state observed on `mounted()` (e.g.
+     * SSR-hydrated cache data) — the events track *new* fetches, not the
+     * initial observation. Each fork scope tracks its own baseline.
+     *
+     * @example
+     * sample({ clock: userQuery.finished.success, target: loadSettings })
+     * sample({
+     *   clock: userQuery.finished.failure,
+     *   fn: (err) => `Failed: ${err.message}`,
+     *   target: showToast,
+     * })
+     */
+    finished: {
+        success: Event<TData>;
+        failure: Event<TError>;
+    };
 }
 interface CreateInfiniteQueryOptions<TQueryFnData = unknown, TError = Error, TPageParam = unknown, TData = InfiniteData<TQueryFnData, TPageParam>, TQueryKey extends EffectorQueryKey = EffectorQueryKey> extends Omit<InfiniteQueryObserverOptions<TQueryFnData, TError, TData, ResolvedQueryKey<TQueryKey>, TPageParam>, 'queryKey' | 'enabled' | 'refetchInterval'> {
     queryKey: TQueryKey;
@@ -158,6 +182,11 @@ interface InfiniteQueryResult<TData, TError = Error, TPageParam = unknown> {
     $observer: Store<InfiniteQueryObserver<any, TError, TData, QueryKey, TPageParam> | null>;
     /** See {@link QueryResult.$queryClient}. */
     $queryClient: Store<QueryClient | null>;
+    /** See {@link QueryResult.finished}. */
+    finished: {
+        success: Event<TData>;
+        failure: Event<TError>;
+    };
 }
 type CreateMutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> = MutationObserverOptions<TData, TError, TVariables, TOnMutateResult> & {
     /** See {@link CreateQueryOptions.name}. */
@@ -229,5 +258,115 @@ interface MutationResult<TData = unknown, TError = Error, TVariables = void> {
         }>;
     };
 }
+/**
+ * Per-item snapshot inside a `createQueries` family. Parallel to the
+ * factory's `source` array — one entry per item, in source order.
+ */
+interface QueryItemState<TItem, TData, TError = Error> {
+    /** The source item this entry was derived from. */
+    source: TItem;
+    data: TData | undefined;
+    error: TError | null;
+    status: QueryStatus;
+    isPending: boolean;
+    isFetching: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    isPlaceholderData: boolean;
+    fetchStatus: FetchStatus;
+}
+/**
+ * Per-item query options produced by `createQueries({ query })`. A pure
+ * function of one source item — no effector stores, no closures over
+ * mutable state. Reactivity comes from the source store; whenever it
+ * updates, this callback re-runs to compute fresh options.
+ *
+ * `enabled` is a plain boolean (not a `Store`) for the same reason —
+ * it's derived from the item, so reactivity is already covered.
+ */
+interface CreateQueriesItemOptions<TQueryFnData, TError, TData, TQueryKey extends ReadonlyArray<unknown>> extends Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, 'queryKey' | 'enabled'> {
+    queryKey: TQueryKey;
+    enabled?: boolean;
+}
+interface CreateQueriesOptions<TItem, TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends ReadonlyArray<unknown> = ReadonlyArray<unknown>> {
+    /**
+     * Stable name used to derive the SID of the result `$items` store so
+     * `serialize(scope)` round-trips it for SSR. Without a name, the
+     * QueryClient cache still hydrates via `dehydrate`/`hydrate`, but the
+     * `$items` snapshot is silently dropped from `serialize(scope)`.
+     */
+    name?: string;
+    /**
+     * Reactive list of items. Each item becomes one parallel query in the
+     * family. Adding / removing items updates the family (spawn / dispose
+     * observer). Order is preserved in `$items`.
+     *
+     * Duplicates in `source` deduplicate observers (same `queryKey` hash)
+     * but produce separate `$items` entries — one per occurrence.
+     */
+    source: Store<ReadonlyArray<TItem>>;
+    /**
+     * Per-item options builder. MUST be pure — same item in, same options
+     * out. Reactivity is driven by the source store; this callback fires
+     * synchronously when source updates.
+     */
+    query: (item: TItem) => CreateQueriesItemOptions<TQueryFnData, TError, TData, TQueryKey>;
+    /** Shared QueryObserver defaults applied on top of `query(item)`. */
+    staleTime?: number;
+    gcTime?: number;
+    retry?: QueryObserverOptions<TQueryFnData, TError, TData>['retry'];
+    retryDelay?: QueryObserverOptions<TQueryFnData, TError, TData>['retryDelay'];
+    refetchOnMount?: QueryObserverOptions<TQueryFnData, TError, TData>['refetchOnMount'];
+    refetchOnReconnect?: QueryObserverOptions<TQueryFnData, TError, TData>['refetchOnReconnect'];
+    refetchOnWindowFocus?: QueryObserverOptions<TQueryFnData, TError, TData>['refetchOnWindowFocus'];
+    networkMode?: QueryObserverOptions<TQueryFnData, TError, TData>['networkMode'];
+}
+/**
+ * Result of `createQueries(...)`. A reactive "family" of parallel
+ * queries indexed by a source store. Composes naturally with
+ * `useUnit($items)` for non-Suspense usage and with
+ * `useQueries(family)` / `useSuspenseQueries(family)` for React-style
+ * consumption.
+ */
+interface QueriesResult<TItem, TData = unknown, TError = Error> {
+    /** Per-item snapshots, parallel to `source`. */
+    $items: Store<ReadonlyArray<QueryItemState<TItem, TData, TError>>>;
+    /** Just the `data` field of `$items` — shortcut for common UIs. */
+    $data: Store<ReadonlyArray<TData | undefined>>;
+    /** `true` while **any** query in the family is pending. */
+    $isPending: Store<boolean>;
+    /** `true` only when **every** query in the family has succeeded. */
+    $isSuccess: Store<boolean>;
+    /** `true` if **any** query in the family is currently fetching. */
+    $isFetching: Store<boolean>;
+    /** `true` if **any** query in the family errored. */
+    $isError: Store<boolean>;
+    /**
+     * Triggers a parallel `fetchQuery` for every current source item.
+     * SSR-friendly — `await allSettled(family.prefetch, { scope })`
+     * returns after every queryFn has resolved (or failed).
+     */
+    prefetch: EventCallable<void>;
+    /**
+     * Increment the per-scope refcount and ensure every observer is
+     * subscribed to the QueryClient. Call from `useEffect` (or its
+     * effector equivalent). The matching `unmounted()` decrements; when
+     * the count hits zero, observers unsubscribe.
+     */
+    mounted: EventCallable<void>;
+    unmounted: EventCallable<void>;
+    /** Invalidates every query in the family — re-fetches in background. */
+    refresh: EventCallable<void>;
+    /** Invalidates one specific item's query. */
+    refreshOne: EventCallable<TItem>;
+    /** See {@link QueryResult.$queryClient}. */
+    $queryClient: Store<QueryClient | null>;
+    /**
+     * Discriminator that lets `useQueries` / `useSuspenseQueries` and
+     * other helpers distinguish a family from a tuple of factories at
+     * runtime. Not part of the public API.
+     */
+    readonly __family: true;
+}
 
-export type { CreateInfiniteQueryOptions, CreateMutationOptions, CreateQueryOptions, EffectorQueryKey, InfiniteQueryResult, MutationResult, MutationStatus, QueryResult, ResolveQueryKeyElement, ResolvedQueryKey, StoreOrValue };
+export type { CreateInfiniteQueryOptions, CreateMutationOptions, CreateQueriesItemOptions, CreateQueriesOptions, CreateQueryOptions, EffectorQueryKey, InfiniteQueryResult, MutationResult, MutationStatus, QueriesResult, QueryItemState, QueryResult, ResolveQueryKeyElement, ResolvedQueryKey, StoreOrValue };

package/dist/types.d.ts

@@ -118,6 +118,30 @@ interface QueryResult<TData, TError = Error> {
      * `$queryClient` and honors `fork({ values: [[$queryClient, qc]] })`.
      */
     $queryClient: Store<QueryClient | null>;
+    /**
+     * Lifecycle events for `sample`-driven reactions to fetch completion.
+     *
+     * - `success` fires with the (post-`select`) data on every newly-finished
+     *   successful fetch — fresh fetch, refetch, reactive key change, or a
+     *   cross-scope `setQueryData`.
+     * - `failure` fires with the error on every failed fetch.
+     *
+     * Neither fires for the baseline state observed on `mounted()` (e.g.
+     * SSR-hydrated cache data) — the events track *new* fetches, not the
+     * initial observation. Each fork scope tracks its own baseline.
+     *
+     * @example
+     * sample({ clock: userQuery.finished.success, target: loadSettings })
+     * sample({
+     *   clock: userQuery.finished.failure,
+     *   fn: (err) => `Failed: ${err.message}`,
+     *   target: showToast,
+     * })
+     */
+    finished: {
+        success: Event<TData>;
+        failure: Event<TError>;
+    };
 }
 interface CreateInfiniteQueryOptions<TQueryFnData = unknown, TError = Error, TPageParam = unknown, TData = InfiniteData<TQueryFnData, TPageParam>, TQueryKey extends EffectorQueryKey = EffectorQueryKey> extends Omit<InfiniteQueryObserverOptions<TQueryFnData, TError, TData, ResolvedQueryKey<TQueryKey>, TPageParam>, 'queryKey' | 'enabled' | 'refetchInterval'> {
     queryKey: TQueryKey;
@@ -158,6 +182,11 @@ interface InfiniteQueryResult<TData, TError = Error, TPageParam = unknown> {
     $observer: Store<InfiniteQueryObserver<any, TError, TData, QueryKey, TPageParam> | null>;
     /** See {@link QueryResult.$queryClient}. */
     $queryClient: Store<QueryClient | null>;
+    /** See {@link QueryResult.finished}. */
+    finished: {
+        success: Event<TData>;
+        failure: Event<TError>;
+    };
 }
 type CreateMutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> = MutationObserverOptions<TData, TError, TVariables, TOnMutateResult> & {
     /** See {@link CreateQueryOptions.name}. */
@@ -229,5 +258,115 @@ interface MutationResult<TData = unknown, TError = Error, TVariables = void> {
         }>;
     };
 }
+/**
+ * Per-item snapshot inside a `createQueries` family. Parallel to the
+ * factory's `source` array — one entry per item, in source order.
+ */
+interface QueryItemState<TItem, TData, TError = Error> {
+    /** The source item this entry was derived from. */
+    source: TItem;
+    data: TData | undefined;
+    error: TError | null;
+    status: QueryStatus;
+    isPending: boolean;
+    isFetching: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    isPlaceholderData: boolean;
+    fetchStatus: FetchStatus;
+}
+/**
+ * Per-item query options produced by `createQueries({ query })`. A pure
+ * function of one source item — no effector stores, no closures over
+ * mutable state. Reactivity comes from the source store; whenever it
+ * updates, this callback re-runs to compute fresh options.
+ *
+ * `enabled` is a plain boolean (not a `Store`) for the same reason —
+ * it's derived from the item, so reactivity is already covered.
+ */
+interface CreateQueriesItemOptions<TQueryFnData, TError, TData, TQueryKey extends ReadonlyArray<unknown>> extends Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, 'queryKey' | 'enabled'> {
+    queryKey: TQueryKey;
+    enabled?: boolean;
+}
+interface CreateQueriesOptions<TItem, TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends ReadonlyArray<unknown> = ReadonlyArray<unknown>> {
+    /**
+     * Stable name used to derive the SID of the result `$items` store so
+     * `serialize(scope)` round-trips it for SSR. Without a name, the
+     * QueryClient cache still hydrates via `dehydrate`/`hydrate`, but the
+     * `$items` snapshot is silently dropped from `serialize(scope)`.
+     */
+    name?: string;
+    /**
+     * Reactive list of items. Each item becomes one parallel query in the
+     * family. Adding / removing items updates the family (spawn / dispose
+     * observer). Order is preserved in `$items`.
+     *
+     * Duplicates in `source` deduplicate observers (same `queryKey` hash)
+     * but produce separate `$items` entries — one per occurrence.
+     */
+    source: Store<ReadonlyArray<TItem>>;
+    /**
+     * Per-item options builder. MUST be pure — same item in, same options
+     * out. Reactivity is driven by the source store; this callback fires
+     * synchronously when source updates.
+     */
+    query: (item: TItem) => CreateQueriesItemOptions<TQueryFnData, TError, TData, TQueryKey>;
+    /** Shared QueryObserver defaults applied on top of `query(item)`. */
+    staleTime?: number;
+    gcTime?: number;
+    retry?: QueryObserverOptions<TQueryFnData, TError, TData>['retry'];
+    retryDelay?: QueryObserverOptions<TQueryFnData, TError, TData>['retryDelay'];
+    refetchOnMount?: QueryObserverOptions<TQueryFnData, TError, TData>['refetchOnMount'];
+    refetchOnReconnect?: QueryObserverOptions<TQueryFnData, TError, TData>['refetchOnReconnect'];
+    refetchOnWindowFocus?: QueryObserverOptions<TQueryFnData, TError, TData>['refetchOnWindowFocus'];
+    networkMode?: QueryObserverOptions<TQueryFnData, TError, TData>['networkMode'];
+}
+/**
+ * Result of `createQueries(...)`. A reactive "family" of parallel
+ * queries indexed by a source store. Composes naturally with
+ * `useUnit($items)` for non-Suspense usage and with
+ * `useQueries(family)` / `useSuspenseQueries(family)` for React-style
+ * consumption.
+ */
+interface QueriesResult<TItem, TData = unknown, TError = Error> {
+    /** Per-item snapshots, parallel to `source`. */
+    $items: Store<ReadonlyArray<QueryItemState<TItem, TData, TError>>>;
+    /** Just the `data` field of `$items` — shortcut for common UIs. */
+    $data: Store<ReadonlyArray<TData | undefined>>;
+    /** `true` while **any** query in the family is pending. */
+    $isPending: Store<boolean>;
+    /** `true` only when **every** query in the family has succeeded. */
+    $isSuccess: Store<boolean>;
+    /** `true` if **any** query in the family is currently fetching. */
+    $isFetching: Store<boolean>;
+    /** `true` if **any** query in the family errored. */
+    $isError: Store<boolean>;
+    /**
+     * Triggers a parallel `fetchQuery` for every current source item.
+     * SSR-friendly — `await allSettled(family.prefetch, { scope })`
+     * returns after every queryFn has resolved (or failed).
+     */
+    prefetch: EventCallable<void>;
+    /**
+     * Increment the per-scope refcount and ensure every observer is
+     * subscribed to the QueryClient. Call from `useEffect` (or its
+     * effector equivalent). The matching `unmounted()` decrements; when
+     * the count hits zero, observers unsubscribe.
+     */
+    mounted: EventCallable<void>;
+    unmounted: EventCallable<void>;
+    /** Invalidates every query in the family — re-fetches in background. */
+    refresh: EventCallable<void>;
+    /** Invalidates one specific item's query. */
+    refreshOne: EventCallable<TItem>;
+    /** See {@link QueryResult.$queryClient}. */
+    $queryClient: Store<QueryClient | null>;
+    /**
+     * Discriminator that lets `useQueries` / `useSuspenseQueries` and
+     * other helpers distinguish a family from a tuple of factories at
+     * runtime. Not part of the public API.
+     */
+    readonly __family: true;
+}
 
-export type { CreateInfiniteQueryOptions, CreateMutationOptions, CreateQueryOptions, EffectorQueryKey, InfiniteQueryResult, MutationResult, MutationStatus, QueryResult, ResolveQueryKeyElement, ResolvedQueryKey, StoreOrValue };
+export type { CreateInfiniteQueryOptions, CreateMutationOptions, CreateQueriesItemOptions, CreateQueriesOptions, CreateQueryOptions, EffectorQueryKey, InfiniteQueryResult, MutationResult, MutationStatus, QueriesResult, QueryItemState, QueryResult, ResolveQueryKeyElement, ResolvedQueryKey, StoreOrValue };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@effector-tanstack-query/core",
-  "version": "0.3.0",
-  "description": "Effector bindings for TanStack Query — core factories (createQuery, createMutation, createInfiniteQuery)",
+  "version": "0.5.0",
+  "description": "Effector bindings for TanStack Query — core factories (createQuery, createMutation, createInfiniteQuery, createQueries) plus invalidate / cancel / remove / reset cache actions",
   "license": "MIT",
   "author": "Ilya Agarkov <ilya.al.ag@gmail.com>",
   "repository": {
@@ -43,10 +43,11 @@
     "!src/__tests__"
   ],
   "sideEffects": false,
-  "dependencies": {
+  "devDependencies": {
     "@tanstack/query-core": "^5.100.10"
   },
   "peerDependencies": {
+    "@tanstack/query-core": "^5.0.0",
     "effector": ">=23.0.0"
   },
   "scripts": {

package/src/createBaseQuery.ts

@@ -6,7 +6,7 @@ import {
   sample,
   scopeBind,
 } from 'effector'
-import type { EventCallable, Store } from 'effector'
+import type { Event, EventCallable, Store } from 'effector'
 import type {
   FetchStatus,
   QueryClient,
@@ -40,6 +40,17 @@ export interface BaseObserverResult<TData, TError> {
   isFetching: boolean
   fetchStatus: FetchStatus
   isPlaceholderData: boolean
+  /**
+   * Timestamp (ms) of the last successful data resolution. Monotonically
+   * increases per successful fetch — used to detect newly-finished fetches
+   * for the `finished.success` lifecycle event.
+   */
+  dataUpdatedAt: number
+  /**
+   * Timestamp (ms) of the last error. Increments per failed fetch — used to
+   * detect newly-finished failures for the `finished.failure` lifecycle event.
+   */
+  errorUpdatedAt: number
 }
 
 export interface BaseQueryStores<TData, TError, TObserver> {
@@ -71,6 +82,17 @@ export interface BaseQueryStores<TData, TError, TObserver> {
   refresh: EventCallable<void>
   mounted: EventCallable<void>
   unmounted: EventCallable<void>
+  /**
+   * Lifecycle events for `sample`-driven reactions to fetch completion.
+   * `success` fires with the (post-`select`) data on every newly-finished
+   * successful fetch; `failure` fires with the error on every failed fetch.
+   * Neither fires for the baseline state observed on mount (e.g. hydrated
+   * cache) — they track *new* fetches, not initial observability.
+   */
+  finished: {
+    success: Event<TData>
+    failure: Event<TError>
+  }
 }
 
 export interface BaseQueryOptions {
@@ -186,6 +208,11 @@ export function createBaseQuery<
   const fetchStatusUpdated = createEvent<FetchStatus>()
   const isPlaceholderDataUpdated = createEvent<boolean>()
 
+  // Lifecycle events. Created once at factory time; dispatched per-scope via
+  // scopeBind inside the mount effect so `allSettled` / fork isolation work.
+  const finishedSuccess = createEvent<TData>()
+  const finishedFailure = createEvent<TError>()
+
   const $data = createStore<TData | undefined>(undefined, {
     skipVoid: false,
     ...sidConfig(name, '$data'),
@@ -268,8 +295,19 @@ export function createBaseQuery<
       const dispatchIsPlaceholderData = scopeBind(isPlaceholderDataUpdated, {
         safe: true,
       })
+      const dispatchFinishedSuccess = scopeBind(finishedSuccess, { safe: true })
+      const dispatchFinishedFailure = scopeBind(finishedFailure, { safe: true })
       const dispatchExtras = extras?.bindDispatcher()
 
+      // Per-mount, per-scope baseline for lifecycle events. The first
+      // notification (the immediate getCurrentResult() emit below, or the
+      // observer's first callback) establishes the baseline without firing —
+      // so hydrated cache data on mount doesn't dispatch `finished.success`.
+      // Subsequent increments of dataUpdatedAt / errorUpdatedAt are genuine
+      // new fetches and do fire.
+      let lastDataUpdatedAt = -1
+      let lastErrorUpdatedAt = -1
+
       observerSubscriptions.get(observer)?.()
       observer.setOptions({
         ...observer.options,
@@ -289,6 +327,30 @@ export function createBaseQuery<
         dispatchFetchStatus(result.fetchStatus)
         dispatchIsPlaceholderData(result.isPlaceholderData)
         dispatchExtras?.(result)
+
+        if (lastDataUpdatedAt === -1) {
+          // Baseline — record current timestamps without emitting.
+          lastDataUpdatedAt = result.dataUpdatedAt
+          lastErrorUpdatedAt = result.errorUpdatedAt
+        } else {
+          // A newly-resolved successful fetch. Guard against placeholderData,
+          // which carries status 'success' but never advances dataUpdatedAt.
+          if (
+            result.dataUpdatedAt > lastDataUpdatedAt &&
+            result.status === 'success' &&
+            !result.isPlaceholderData
+          ) {
+            lastDataUpdatedAt = result.dataUpdatedAt
+            dispatchFinishedSuccess(result.data as TData)
+          }
+          if (
+            result.errorUpdatedAt > lastErrorUpdatedAt &&
+            result.status === 'error'
+          ) {
+            lastErrorUpdatedAt = result.errorUpdatedAt
+            dispatchFinishedFailure(result.error as TError)
+          }
+        }
       }
 
       const unsubscribe = observer.subscribe(dispatch)
@@ -423,6 +485,10 @@ export function createBaseQuery<
     refresh,
     mounted,
     unmounted,
+    finished: {
+      success: finishedSuccess,
+      failure: finishedFailure,
+    },
     ...(extras?.stores ?? ({} as TExtraStores)),
   }
 }

package/src/createCacheAction.ts

@@ -0,0 +1,172 @@
+import { attach, createEvent, createStore, sample } from 'effector'
+import type { EventCallable, Store } from 'effector'
+import type { QueryClient, QueryFilters, QueryKey } from '@tanstack/query-core'
+import { $queryClient } from './queryClient'
+import { resolveKey } from './resolve'
+import type { EffectorQueryKey } from './types'
+
+/**
+ * Options shared by `createCancel` / `createRemove` / `createReset`.
+ *
+ * Structurally a `QueryFilters` (from `@tanstack/query-core`) with the
+ * `queryKey` field widened to the reactive `EffectorQueryKey` shape — drop a
+ * `Store` anywhere in the array and the action resolves it on every call.
+ *
+ * `queryKey` is **optional**: omit it to target *all* queries, mirroring
+ * `queryClient.cancelQueries()` / `removeQueries()` / `resetQueries()` with no
+ * filters.
+ */
+export interface CacheActionOptions extends Omit<QueryFilters, 'queryKey'> {
+  /**
+   * Key (or key prefix) to act on. Supports the same reactive shape as
+   * `createQuery.queryKey`. Omit to match every query in the cache.
+   */
+  queryKey?: EffectorQueryKey
+}
+
+/** Distinct named aliases so each factory documents its own option type. */
+export type CreateCancelOptions = CacheActionOptions
+export type CreateRemoveOptions = CacheActionOptions
+export type CreateResetOptions = CacheActionOptions
+
+/**
+ * The QueryClient method a given action drives. Receives the resolved filters
+ * (with `queryKey` already merged in when present). May be sync (`removeQueries`
+ * returns `void`) or async (`cancelQueries` / `resetQueries` return a Promise).
+ */
+type CacheActionRunner = (qc: QueryClient, filters: QueryFilters) => unknown
+
+/**
+ * Shared builder. Returns a `void` event that, when fired, runs `action`
+ * against the resolved `QueryClient` with the resolved filters. Mirrors
+ * `createInvalidate`'s locking + reactive-key + per-scope semantics exactly.
+ */
+function buildCacheAction(
+  action: CacheActionRunner,
+  explicitClient: QueryClient | null,
+  options: CacheActionOptions,
+): EventCallable<void> {
+  const { queryKey, ...restFilters } = options
+
+  // Same locking semantics as the other factories: explicit client freezes the
+  // store, default flows through global $queryClient (and respects
+  // fork({ values: [[$queryClient, qc]] }) for per-scope isolation).
+  const $effectiveClient: Store<QueryClient | null> = explicitClient
+    ? createStore(explicitClient as QueryClient | null, {
+        serialize: 'ignore',
+      })
+    : $queryClient
+
+  // No queryKey → a store of `undefined`, so the effect omits the field and the
+  // action matches all queries.
+  const $resolvedKey: Store<QueryKey | undefined> = queryKey
+    ? resolveKey(queryKey)
+    : createStore<QueryKey | undefined>(undefined, { skipVoid: false })
+
+  const run = createEvent<void>()
+
+  const runFx = attach({
+    source: { qc: $effectiveClient, key: $resolvedKey },
+    effect: ({ qc, key }) => {
+      if (!qc) return
+      const filters: QueryFilters = { ...restFilters }
+      if (key !== undefined) filters.queryKey = key
+      return action(qc, filters)
+    },
+  })
+
+  sample({ clock: run, target: runFx })
+
+  return run
+}
+
+function parseArgs(
+  arg1: QueryClient | CacheActionOptions,
+  arg2?: CacheActionOptions,
+): [QueryClient | null, CacheActionOptions] {
+  if (arg2 !== undefined) return [arg1 as QueryClient, arg2]
+  return [null, arg1 as CacheActionOptions]
+}
+
+/**
+ * Builds a `sample`-friendly event that **cancels** in-flight queries on the
+ * resolved `QueryClient` (without removing cached data). Wraps
+ * `queryClient.cancelQueries` — async, so `await allSettled(cancel, { scope })`
+ * waits for cancellation to settle.
+ *
+ * @example Cancel a user's queries on logout
+ * const cancelUserQueries = createCancel({ queryKey: ['user', $userId] })
+ * sample({ clock: logoutClicked, target: cancelUserQueries })
+ *
+ * @example Explicit client (same back-compat overload as createInvalidate)
+ * const cancelAll = createCancel(queryClient, {})
+ */
+export function createCancel(options: CacheActionOptions): EventCallable<void>
+export function createCancel(
+  queryClient: QueryClient,
+  options: CacheActionOptions,
+): EventCallable<void>
+export function createCancel(
+  arg1: QueryClient | CacheActionOptions,
+  arg2?: CacheActionOptions,
+): EventCallable<void> {
+  const [explicitClient, options] = parseArgs(arg1, arg2)
+  return buildCacheAction(
+    (qc, filters) => qc.cancelQueries(filters),
+    explicitClient,
+    options,
+  )
+}
+
+/**
+ * Builds a `sample`-friendly event that **removes** matching entries from the
+ * cache entirely. Wraps `queryClient.removeQueries` — synchronous (no Promise).
+ * The next mount of a removed query starts from a pending state.
+ *
+ * @example Drop stale cache on navigation
+ * const removeStale = createRemove({ queryKey: ['stale-cache'] })
+ * sample({ clock: navigated, target: removeStale })
+ */
+export function createRemove(options: CacheActionOptions): EventCallable<void>
+export function createRemove(
+  queryClient: QueryClient,
+  options: CacheActionOptions,
+): EventCallable<void>
+export function createRemove(
+  arg1: QueryClient | CacheActionOptions,
+  arg2?: CacheActionOptions,
+): EventCallable<void> {
+  const [explicitClient, options] = parseArgs(arg1, arg2)
+  return buildCacheAction(
+    (qc, filters) => qc.removeQueries(filters),
+    explicitClient,
+    options,
+  )
+}
+
+/**
+ * Builds a `sample`-friendly event that **resets** matching queries back to
+ * their initial state and refetches any active observers. Wraps
+ * `queryClient.resetQueries` — async, so `await allSettled(reset, { scope })`
+ * waits for the refetch to settle.
+ *
+ * @example Reset search results when the filters are cleared
+ * const resetSearch = createReset({ queryKey: ['search'] })
+ * sample({ clock: filtersCleared, target: resetSearch })
+ */
+export function createReset(options: CacheActionOptions): EventCallable<void>
+export function createReset(
+  queryClient: QueryClient,
+  options: CacheActionOptions,
+): EventCallable<void>
+export function createReset(
+  arg1: QueryClient | CacheActionOptions,
+  arg2?: CacheActionOptions,
+): EventCallable<void> {
+  const [explicitClient, options] = parseArgs(arg1, arg2)
+  return buildCacheAction(
+    (qc, filters) => qc.resetQueries(filters),
+    explicitClient,
+    options,
+  )
+}

package/src/createInfiniteQuery.ts

@@ -272,6 +272,7 @@ export function createInfiniteQuery<
     prefetch,
     mounted: base.mounted,
     unmounted: base.unmounted,
+    finished: base.finished,
   }
 
   Object.defineProperty(result, '__createObserver', {