Skip to content

Latest commit

 

History

History
 
 

effect-query

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 

README.md

@magnitudedev/effect-query

Effect-native query and mutation state built on Effect Atom. Definitions retain their exact input, data, expected-error, and service-requirement types.

Relationship to TanStack Query

This package intentionally preserves TanStack Query's established query and mutation concepts so that cache behavior and API responsibilities remain familiar. It expresses those concepts with Effect and Effect Atom rather than React hooks, Promises, or an untyped error channel. The goal is semantic parity, not a line-for-line port: exact Effect error and requirement types, atom identity, and Effect services remain native to this package.

TanStack Query concept effect-query equivalent Effect-native difference
Query options (queryKey, queryFn) Query.make(name, { key, effect }) The fetch operation is an Effect; its error and service requirements remain typed.
useQuery Observe the query atom with the relevant Effect Atom integration The query itself is a framework-independent atom.
fetchQuery QueryClient.fetch Returns fresh retained data, joins active work, or fetches missing/stale data; preserves the exact error type.
ensureQueryData QueryClient.ensure Returns retained data immediately and revalidates stale data.
prefetchQuery QueryClient.prefetch Failure remains in query state and is not returned in the Effect error channel.
invalidateQueries QueryClient.invalidate Accepts typed definition/key filters and optionally refetches.
refetchQueries QueryClient.refetch Heterogeneous failures are collected in QueryBatchError.
cancelQueries QueryClient.cancel Cancellation is represented by Effect interruption.
removeQueries QueryClient.remove Removes matching query entries from the atom-backed cache.
getQueryState QueryClient.getState Returns Option<Query.State<...>> in an Effect.
setQueryData QueryClient.setData The updater receives Option<Data>.
Query cache retention (gcTime) Query gcTime Retains the complete canonical entry—data, status, invalidation, and in-flight coordination—after its last observer unmounts.
Mutation options (mutationFn, scope) Mutation.make({ effect, scope }) The command and optional synchronization operation are typed Effects.
mutate / mutateAsync Write the mutation atom / Mutation.execute Atom writes support reactive use; execute composes directly in Effect workflows.
Mutation key Exact mutation-definition identity The definition is the typed identity, avoiding a parallel string-key contract.
MutationState Mutation.State<M> Preserves the exact mutation input, output, and error types.
useMutationState Mutation.state({ filters, select }) An Effect requiring the contextual QueryClient that yields a derived Atom of matching mutation states.
useIsMutating Mutation.isMutating(filters) An Effect requiring the contextual QueryClient that yields an Atom<number>.
Mutation cache retention (gcTime) Mutation gcTime Each invocation's Mutation.State remains selectable until collection.
experimental_streamedQuery Query.fromStream(name, { key, stream, reduce }) The first element resolves the query; later elements are reduced into the data; refetch reopens the stream.
— (tRPC useSubscription) Subscription.make(name, { key, stream, reconnect }) A keyed, shared, reconnecting stream with status/latest; consumers drain Subscription.events(atom).

Queries

Definitions are static domain values. Create them once, independently of any connection or Atom runtime. A Client materializes those definitions for one application connection and owns the shared query cache and mutation history:

import * as AtomRegistry from "@effect-atom/atom/Registry"
import * as AtomResult from "@effect-atom/atom/Result"
import * as Data from "effect/Data"
import * as Effect from "effect/Effect"
import * as Layer from "effect/Layer"
import * as Option from "effect/Option"
import { Client, Query, QueryClient } from "@magnitudedev/effect-query"

class UserNotFound extends Data.TaggedError("UserNotFound")<{
  readonly id: string
}> {}

const userQuery = Query.make("User", {
  key: ({ id }: { readonly id: string }) => Data.tuple(id),
  effect: ({ id }) => id === "missing"
    ? Effect.fail(new UserNotFound({ id }))
    : Effect.succeed({ id, name: "Ada" }),
  staleTime: "30 seconds",
  gcTime: "5 minutes"
})

const client = Client.make(Layer.empty)
const registry = AtomRegistry.make()
const user = client.query(userQuery, { id: "1" })
const unmount = registry.mount(user)
const state = registry.get(user)
const current = AtomResult.value(state.result)
unmount()

Equivalent keys return the same query atom and share cached data and in-flight work. Structured keys must be Effect Data or another value implementing Effect Equal; plain objects and arrays are rejected because they have reference identity.

Like TanStack Query, observer lifetime and cache lifetime are distinct. Unmounting the final observer does not reset a query: its complete canonical entry remains available until gcTime expires. Remounting during that interval synchronously reads retained state. Concurrent fetches join the active fetch, while repeated invalidations during an active replacement fetch coalesce instead of starting parallel requests.

The keyed family returns that canonical query atom directly. Consumers and the registry therefore hold the same object that the family weakly indexes; it must not index a temporary wrapper around the atom, because collecting that wrapper would split one query key into multiple entries.

QueryClient also provides exact operations for cache control:

const cacheProgram = Effect.gen(function*() {
  yield* QueryClient.ensure(userQuery, { id: "1" }) // retained value, revalidate if stale
  yield* QueryClient.prefetch(userQuery, { id: "1" }) // failure stays in query state
  yield* QueryClient.invalidate(userQuery.match())
  yield* QueryClient.invalidate(userQuery.match({ id: "1" }), { refetch: false })
  yield* QueryClient.cancel({ stale: true })
  yield* QueryClient.setData(userQuery, { id: "1" }, (current) => Option.match(current, {
    onNone: () => ({ id: "1", name: "Grace" }),
    onSome: (value) => ({ ...value, name: "Grace" })
  }))
  yield* QueryClient.remove(userQuery.match({ id: "1" }))
})

fetch and ensure preserve the query's exact error type. Broad filtered refetch instead returns QueryBatchError, because matches may have unrelated error types.

SDK-backed definitions

RPC contracts are independent of Effect Query. Define cache and mutation policy around ordinary Effect SDK operations; derive payload keys from their existing schemas.

import { Effect, Layer } from "effect"
import { Group, Query, Mutation, Operation, Client } from "@magnitudedev/effect-query"
import { MagnitudeClient, Sessions as SessionRpcs } from "@magnitudedev/sdk"

const GetSession = Query.make(SessionRpcs.getSession._tag, {
  key: Operation.payloadKey(SessionRpcs.getSession.payloadSchema),
  effect: (input: Parameters<MagnitudeClient["sessions"]["getSession"]>[0]) =>
    Effect.flatMap(MagnitudeClient, sdk => sdk.sessions.getSession(input)),
  staleTime: "30 seconds",
})
const Sessions = Group.make({ GetSession })
const Application = Group.make({ Sessions })
const effectQuery = Client.make(Application, Layer.succeed(MagnitudeClient, existingSdk))
const session = effectQuery.Sessions.GetSession({ sessionId: "session-1" })

Every materialized group member is its canonical atom. Query members return QueryAtoms, mutation members are MutationAtoms, and subscription members return SubscriptionAtoms. Payload, success, and error types are inferred from the supplied Effect or Stream, not redeclared wire schemas. Client.make checks that all operation requirements are provided. Query.fromStream folds an ordinary SDK stream. The library has no RPC declaration, server, transport, or adapter surface.

HTTP API-backed definitions

The same pattern applies to AtomHttpApi.Tag. Its generated client is an Effect service; the query definition supplies only domain identity and cache policy:

import * as AtomHttpApi from "@effect-atom/atom/AtomHttpApi"
import * as FetchHttpClient from "@effect/platform/FetchHttpClient"
import { IcnApi } from "./icn-api.js"

class IcnHttpClient {}

const IcnHttp = AtomHttpApi.Tag<IcnHttpClient>()("IcnHttpClient", {
  api: IcnApi,
  httpClient: FetchHttpClient.layer,
  baseUrl: "http://127.0.0.1:8080"
})

const hardwareQuery = Query.make("Hardware", {
  key: () => Data.tuple("hardware"),
  effect: () => Effect.flatMap(IcnHttp, (client) =>
    client.system.getHardware({})),
  staleTime: "10 seconds"
})

const modelDownloadQuery = Query.make("ModelDownload", {
  key: ({ attemptId }: { readonly attemptId: string }) => Data.tuple(attemptId),
  effect: ({ attemptId }) => Effect.flatMap(IcnHttp, (client) =>
    client.models.getModelDownload({ path: { attempt_id: attemptId } }))
})

const icnQuery = Client.make(IcnHttp.layer)
const hardwareAtom = icnQuery.query(hardwareQuery, undefined)

Endpoint success, declared API errors, HTTP client failures, and Schema parse failures remain in the query's inferred error channel. A generated HttpApiClient service can be used identically; the essential input to Query.make is its typed Effect, not a transport-specific adapter.

Subscriptions

A Subscription is a keyed, shared, reconnecting event stream with the same identity discipline as a query: one open stream per key while observed, closed gcTime after the last observer leaves. Its atom carries status (idle | connecting | active | reconnecting | failed | completed), latest, failure, and attempt; Subscription.events(atom) exposes the events as a Stream and keeps the subscription mounted while consumed. Writing Atom.Reset reopens it, Atom.Interrupt closes it, and QueryClient.reconnect(filter) reopens matching subscriptions.

Relating a subscription to a query is ordinary code — there is no binding layer:

const changes = Subscription.make("Changes", {
  key: (_: void) => "changes",
  stream: () => changeStream,
  reconnect: Schedule.exponential("100 millis")
})

// poke → refetch
yield* Subscription.events(client.subscription(changes, undefined)).pipe(
  Stream.runForEach((change) => queryClient.invalidate({ name: change.query })),
  Effect.forkScoped
)

// data over time: a query whose source is a stream
const totals = Query.fromStream("Totals", {
  key: (_: void) => "totals",
  stream: () => totalsStream,
  reduce: (previous, event) => Option.getOrElse(previous, () => 0) + event
})

Remote atom pattern

A remote atom is ordinary composition, not another cache primitive:

snapshot RPC → Query atom ← invalidate ← watch Stream

The watch is a Subscription member of the boundary, drained once per connection as scoped Effect infrastructure installed through Client.make's additional Layer. Notifications carry identity and announce that authoritative state may have changed, while the query remains the only owner of snapshot data:

import * as Stream from "effect/Stream"

const synchronizeModels = (client: Client.Materialized<typeof Application, AcnClientRequirements, never>) =>
  Subscription.events(client.Models.WatchModelChanges({})).pipe(
    Stream.runForEach((change) =>
      QueryClient.invalidate(Models.GetModel.match({ modelId: change.modelId }))
    )
  )

const effectQuery = Client.make(
  Application,
  Layer.succeed(MagnitudeClient, existingSdk),
  (client) => Layer.scopedDiscard(Effect.forkScoped(synchronizeModels(client)))
)

Mutation synchronization uses the same cache primitives and is declared on the mutation itself. Fetch the exact query when the command must remain pending until the authoritative snapshot has been read:

const RenameModel = Mutation.make("RenameModel", {
  payload: { modelId: Schema.String, name: Schema.String },
  success: Schema.Struct({}),
  synchronize: (_receipt, payload) => QueryClient.invalidate(
    GetModel.match({ modelId: payload.modelId })
  ).pipe(
    Effect.zipRight(QueryClient.fetch(GetModel, { modelId: payload.modelId })),
    Effect.asVoid
  )
})

The resulting “remote atom” is therefore a Query plus an optional scoped notification Stream. RPC and HTTP transports supply Effects and Streams but do not need query-specific adapters. If an API requires a stronger consistency guarantee than “refetch the authoritative snapshot,” that guarantee belongs in the operation's implementation rather than in the generic cache.

Observation and selection

Query atoms are ordinary Effect atoms:

const unsubscribe = registry.subscribe(user, (state) => {
  console.log(state.fetchStatus, state.result)
})

const nameAtom = Query.select(user, (value) => value.name)
const optionalUser = Query.when(Option.fromNullable(user))

select returns a derived read-only atom and does not create another cache entry. Cache operations continue to target the source query atom.

React

React observes the same query and mutation atoms through @effect-atom/atom-react; no query-specific hooks or provider are needed:

import {
  RegistryProvider,
  Result,
  useAtomSet,
  useAtomValue
} from "@effect-atom/atom-react"
import { createRoot } from "react-dom/client"

function Session({ sessionId }: { readonly sessionId: string }) {
  const state = useAtomValue(effectQuery.Sessions.GetSession({ sessionId }))
  const remove = useAtomSet(effectQuery.Sessions.DeleteSession, { mode: "promise" })

  if (Result.isInitial(state.result)) return <p>Loading…</p>
  if (Result.isFailure(state.result)) return <p>Unable to load session.</p>

  return (
    <section aria-busy={state.result.waiting}>
      <h1>{state.result.value.title}</h1>
      <button onClick={() => void remove({ sessionId })}>Delete</button>
    </section>
  )
}

createRoot(document.getElementById("root")!).render(
  <RegistryProvider defaultIdleTTL={5_000}>
    <Session sessionId="session-1" />
  </RegistryProvider>
)

RegistryProvider owns the registry used by observation, remote-client runtimes, and the connection-scoped Effect Query client, so reads, commands, and synchronization operate on the same cache.

Mutations

Mutation command and synchronization Effects retain separate error and requirement types. The connection-scoped client supplies both application services and the query client used during synchronization:

import { Mutation } from "@magnitudedev/effect-query"

const renameUser = Mutation.make("RenameUser", {
  effect: ({ id, name }: { readonly id: string; readonly name: string }) =>
    Effect.succeed({ id, name }),
  synchronize: (_output, input) =>
    QueryClient.invalidate(userQuery.match({ id: input.id })),
  scope: ({ id }) => Mutation.MutationScope(`user:${id}`)
})

const renameUserAtom = client.mutation(renameUser)
const renameProgram = Mutation.execute(renameUserAtom, { id: "1", name: "Grace" }).pipe(
  Effect.provideService(AtomRegistry.AtomRegistry, registry)
)

Invocations with the same scope are serialized. A synchronization failure is reported as MutationSynchronizationError<Output, SynchronizationError>, retaining both the accepted command output and the exact visibility error. Reactive aggregate state is available through QueryClient.isFetching, QueryClient.isMutating, and QueryClient.mutationState.

The equivalents of TanStack Query's useMutationState and useIsMutating preserve the mutation's input, output, and error types and support exact semantic scope selection. Like the hooks, they read the contextual client's history: each is an Effect requiring QueryClient that yields the derived atom.

const userScope = Mutation.MutationScope("user:1")
const selectors = Effect.gen(function*() {
  const mutationStatesAtom = yield* Mutation.state({
    filters: { mutation: renameUser, scope: userScope },
  })
  const namesAtom = yield* Mutation.state({
    filters: { mutation: renameUser, status: "success" },
    select: ({ input }) => input.name,
  })
  const isMutatingAtom = yield* Mutation.isMutating({ mutation: renameUser, scope: userScope })
  return { mutationStatesAtom, namesAtom, isMutatingAtom }
})

Derive the latest invocation state with mutationStates.at(-1) and a pending boolean with isMutating > 0; these are consumer views rather than cache APIs. Resource lifecycle continues to come from its query. A history entry is retained while the mutation atom that produced it is observed and for gcTime after its last observer leaves, as with query entries.

Optimistic presentation from mutation state

For updates whose immediate presentation can be derived from the submitted input, keep the query cache authoritative and project the latest pending mutation over it. This is the Effect Query equivalent of TanStack Query v5's simplified optimistic-update pattern: the mutation input is provisional intent, while the query result is confirmed state.

const userScope = Mutation.MutationScope("user:1")
// Inside the domain service's Effect, where QueryClient is in context:
const pendingNamesAtom = yield* Mutation.state({
  filters: {
    mutation: renameUser,
    scope: userScope,
    status: "pending"
  },
  select: ({ input }) => input.name
})

function UserName() {
  const user = useAtomValue(client.query(userQuery, { id: "1" }))
  const pendingNames = useAtomValue(pendingNamesAtom)

  if (!Result.isSuccess(user.result)) return <p>Loading…</p>

  const presentedName = pendingNames.at(-1) ?? user.result.value.name
  return <p>{presentedName}</p>
}

The presentation changes as soon as the mutation invocation enters the cache. If the command fails, that invocation stops matching the pending filter and the presentation falls back to the authoritative query value. If the command succeeds, synchronize makes the accepted value visible through the query before the mutation stops being pending, so the presentation does not flicker back to stale data.

This pattern requires no QueryClient.setData, snapshot, or rollback. Use a cache update instead only when consumers must observe a speculative query result and the mutation can correctly derive that complete result. Mutation state describes the submitted command; resource lifecycle and confirmed state continue to come from queries.