# effector-refetch

> Friendly, effect-first query layer for effector — createQuery/createMutation built on real effects, with caching, retries, concurrency, pagination, validation, React/Vue/Solid bindings, SSR via fork/allSettled, devtools and an offline/auth barrier.

Full documentation as plain text: [llms-full.txt](https://olovyannikov.github.io/effector-refetch/llms-full.txt). Repo: https://github.com/Olovyannikov/effector-refetch

## Guide

- [Core concepts](https://olovyannikov.github.io/effector-refetch/guide/concepts.html): A query wraps your **real effector `Effect`**. It is not a black box with an internal executor — your effect is a first-class unit: visible in devtools, composable with `attach`, and fork-friendly for
- [Local development](https://olovyannikov.github.io/effector-refetch/guide/contributing.html): Want to hack on **effector-refetch** itself (not just use it)? Here's how to get the repo running.
- [Getting started](https://olovyannikov.github.io/effector-refetch/guide/getting-started.html): This page gets you from zero to a working query in a couple of minutes. For the _why_, read the [Introduction](/guide/introduction) first.
- [Introduction](https://olovyannikov.github.io/effector-refetch/guide/introduction.html): Almost every app does the same dance around data: kick off a request, track whether it's loading, catch the error, show the result. Then reality piles on — the user double-clicks, a second request rac
- [LLMs & AI agents](https://olovyannikov.github.io/effector-refetch/guide/llms.html): effector-refetch ships machine-readable docs and an installable agent skill, so AI coding agents write idiomatic, fork-correct code with the library.
- [Migration](https://olovyannikov.github.io/effector-refetch/guide/migration.html): A codemod handles the mechanical parts — rewriting imports and folding the standalone operators into the inline `createQuery` config:
- [vs. farfetched](https://olovyannikov.github.io/effector-refetch/guide/vs-farfetched.html): [farfetched](https://ff.effector.dev) is the most complete data-fetching tool for effector and the obvious reference point. It's mature, well-designed, and **open-source / not archived**. This page is

## API

- [Framework bindings](https://olovyannikov.github.io/effector-refetch/api/bindings.html): A query implements effector's `@@unitShape` protocol, so you can pass it straight to `useUnit` from **effector-react**, **effector-vue** or **effector-solid** — no wrapper needed.
- [Devtools](https://olovyannikov.github.io/effector-refetch/api/devtools.html): A floating devtools panel — like TanStack Query's — that lists your queries with live status, params, data, error and a per-query event log. Available for **React** (`effector-refetch/devtools`), **Vu
- [HTTP & validation](https://olovyannikov.github.io/effector-refetch/api/http.html): Wrap any HTTP client into a typed, abort-aware effector effect with normalized errors:
- [Introspection](https://olovyannikov.github.io/effector-refetch/api/introspection.html): Pass `name` to label the units in the effector inspector — **the public surface and every internal seam**, so the whole pipeline is readable, not just the entry points:
- [Mutations & invalidation](https://olovyannikov.github.io/effector-refetch/api/mutations.html): A mutation is a write-flavored query: the same effect-first engine (status, retry, concurrency, lifecycle) without cache/refresh/stale, plus a `mutate` alias. Concurrency defaults to `TAKE_EVERY` so i
- [Operators](https://olovyannikov.github.io/effector-refetch/api/operators.html): Every inline `createQuery` option is sugar over a **standalone operator** — `import` them and apply to any query/mutation (even one built elsewhere). They're composable and tree-shakeable.
- [Pagination](https://olovyannikov.github.io/effector-refetch/api/pagination.html): Cursor/offset pagination that accumulates pages. `start` loads the first page (resetting), `fetchNext` appends the next — driven by `getNextPageParam`.
- [Queries](https://olovyannikov.github.io/effector-refetch/api/queries.html): - **`effect`** — your `Effect<Params, Result, Error>`. `handler: async params => …` is sugar. - **`concurrency`** — how overlapping runs behave: - `TAKE_LATEST` (default) — new run supersedes & aborts
- [API reference](https://olovyannikov.github.io/effector-refetch/api/reference.html): > Auto-generated from the public type entry points — always in sync with the build. > For prose and examples, see the [API](/api/queries) and [Recipes](/recipes/ssr-and-testing) sections.

## Recipes

- [Auth & barrier (pause the environment)](https://olovyannikov.github.io/effector-refetch/recipes/auth-barrier.html): Sometimes you need to **pause every request**, do something, then resume — the classic case being a `401`: pause, refresh the token, replay the queued requests.
- [Auto-refetch & polling](https://olovyannikov.github.io/effector-refetch/recipes/auto-refetch.html): Refetch on a timer while the query is started and enabled:
- [Circuit breaker](https://olovyannikov.github.io/effector-refetch/recipes/circuit-breaker.html): A [barrier](/recipes/auth-barrier) is a mutex you can `lock` and `unlock`; gated queries wait while it's locked. That's all you need for a **circuit breaker**: after N consecutive failures, trip the b
- [Shared defaults (query factory)](https://olovyannikov.github.io/effector-refetch/recipes/defaults.html): effector-refetch has no global `QueryClient`. Instead, bake shared policy into a factory with `createQueryFactory` — per-call options always override the defaults.
- [Dependent queries](https://olovyannikov.github.io/effector-refetch/recipes/dependent-queries.html): When one request needs the result of another (fetch a character, then its origin location), [`connectQuery`](/api/queries) wires them: when the **source** succeeds it computes the **target**'s params 
- [Error handling](https://olovyannikov.github.io/effector-refetch/recipes/error-handling.html): Errors are first-class: a failed effect drives `$error`, flips `$status` to `'fail'`, and emits `finished.fail` — all scope-safe. This recipe covers reading errors, normalizing them, deciding what to 
- [File uploads (FormData)](https://olovyannikov.github.io/effector-refetch/recipes/file-uploads.html): A file upload is just a `POST` with a `FormData` body — so it needs no special support. Build the `FormData` inside a [`createRequestFx`](/api/http) effect and hand it to `createMutation`.
- [GraphQL](https://olovyannikov.github.io/effector-refetch/recipes/graphql.html): GraphQL is just a `POST` with `{ query, variables }`, so it needs no special support — wrap one document in a [`createRequestFx`](/api/http) effect and hand it to `createQuery` / `createMutation`. A t
- [Groups & cache access](https://olovyannikov.github.io/effector-refetch/recipes/groups-and-cache.html): A [factory](/recipes/defaults) registers every query it creates, so you can refetch them together — the effector-flavored equivalent of `queryClient.invalidateQueries`:
- [effector inspector & logging](https://olovyannikov.github.io/effector-refetch/recipes/inspector.html): Beyond the [visual devtools](/api/devtools), effector-refetch plays well with the broader effector tooling — the inspector and any logger.
- [Normalized list updates](https://olovyannikov.github.io/effector-refetch/recipes/list-updates.html): When a mutation changes one item in a list query, you usually don't need a full refetch — patch the item in place with [`update`](/api/mutations#update) (or `optimisticUpdate`).
- [Optimistic updates](https://olovyannikov.github.io/effector-refetch/recipes/optimistic.html): Show a change instantly, roll back on failure, reconcile with the server on success — then optionally `invalidate` to confirm against server truth (the TanStack pattern).
- [Router & loaders](https://olovyannikov.github.io/effector-refetch/recipes/router.html): With a data router (React Router 6.4+, TanStack Router, …) you can fetch in the route **loader**, so a page renders with its data already present — no in-component loading flash. effector-refetch fits
- [Selecting slices](https://olovyannikov.github.io/effector-refetch/recipes/select.html): Sometimes a component needs only a **slice** of a query's data and should re-render only when that slice changes (TanStack calls this `select`). There's nothing to add — a query's `$data` is a plain e
- [Shared request factory](https://olovyannikov.github.io/effector-refetch/recipes/shared-factory.html): Bake `baseURL` + headers/auth into a factory once, then declare endpoints in one line each — the FSD `shared/api` pattern.
- [SSR & testing](https://olovyannikov.github.io/effector-refetch/recipes/ssr-and-testing.html): Because a query is plain effector under the hood, `fork()` + `allSettled()` work as usual — no special test utilities.
- [Streaming (SSE & WebSocket)](https://olovyannikov.github.io/effector-refetch/recipes/streaming.html): A query owns the **snapshot**; a stream keeps a live **view store** fresh. Load the initial data with a query, then fold stream events into a plain store seeded from the query's public `finished.done`

## Overview

- [index.md](https://olovyannikov.github.io/effector-refetch/): ::: code-group