@effector-tanstack-query/core 0.4.0 → 1.0.0-rc.1

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', {

package/src/createQuery.ts

@@ -124,6 +124,7 @@ export function createQuery<
     prefetch,
     mounted: base.mounted,
     unmounted: base.unmounted,
+    finished: base.finished,
   }
 
   // Internal: used by useSuspenseQuery to construct a transient observer

package/src/index.ts

@@ -4,6 +4,17 @@ export { createQueries } from './createQueries'
 export { createMutation } from './createMutation'
 export { createInvalidate } from './createInvalidate'
 export type { CreateInvalidateOptions } from './createInvalidate'
+export {
+  createCancel,
+  createRemove,
+  createReset,
+} from './createCacheAction'
+export type {
+  CacheActionOptions,
+  CreateCancelOptions,
+  CreateRemoveOptions,
+  CreateResetOptions,
+} from './createCacheAction'
 export { $queryClient, setQueryClient } from './queryClient'
 export { prefetchQueries } from './prefetchQueries'
 export type {

package/src/types.ts

@@ -160,6 +160,30 @@ export 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>
+  }
 }
 
 export interface CreateInfiniteQueryOptions<
@@ -231,6 +255,11 @@ export interface InfiniteQueryResult<
   >
   /** See {@link QueryResult.$queryClient}. */
   $queryClient: Store<QueryClient | null>
+  /** See {@link QueryResult.finished}. */
+  finished: {
+    success: Event<TData>
+    failure: Event<TError>
+  }
 }
 
 export type CreateMutationOptions<