@raf-query/core 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -1,10 +1,48 @@
 # Changelog
 
+## [0.13.0](https://github.com/KATT/raf-query/compare/0.12.0...0.13.0) (2026-11-10)
+
+### ⚠ BREAKING CHANGES
+
+* **core:** paging lives in core; useInfiniteQuery reads core's PageControls ([#246](https://github.com/KATT/raf-query/issues/246))
+
+### Features
+
+* **core:** paging lives in core; useInfiniteQuery reads core's PageControls ([#246](https://github.com/KATT/raf-query/issues/246)) ([f6b4ed2](https://github.com/KATT/raf-query/commit/f6b4ed210340b4b25bf3316ef08a9c8ceb9ed112))
+* **core:** pass the client making the request to queryFn ([#241](https://github.com/KATT/raf-query/issues/241)) ([8c85746](https://github.com/KATT/raf-query/commit/8c85746c230bc3d8a426b32a130a260fa7e8ca62))
+* **core:** replay cached entries to a new client subscriber ([#243](https://github.com/KATT/raf-query/issues/243)) ([1455eed](https://github.com/KATT/raf-query/commit/1455eed2612fe69f0f10bfec08cfd552ef90c786))
+* **core:** ssr: false for queries only a browser can run ([#240](https://github.com/KATT/raf-query/issues/240)) ([077de62](https://github.com/KATT/raf-query/commit/077de6223a92b8bd8d35f7df043d1efe147ca403))
+
+### Bug Fixes
+
+* **core:** infer factories built inline by a generic maker in setData ([#244](https://github.com/KATT/raf-query/issues/244)) ([da87c07](https://github.com/KATT/raf-query/commit/da87c07a3463a919c154ac3ac5fba3d546b3231e))
+* **core:** keep data written while a request ran ([#239](https://github.com/KATT/raf-query/issues/239)) ([4cb7cc0](https://github.com/KATT/raf-query/commit/4cb7cc0605a2d4637591eb365153c5e955eb41a8))
+* **core:** start features once for providers that share a client ([#242](https://github.com/KATT/raf-query/issues/242)) ([d5968fb](https://github.com/KATT/raf-query/commit/d5968fb140429a1b2e7fb94662c266a52e877cc0))
+
+### Documentation
+
+* every example is the blog's posts, comments and authors ([#236](https://github.com/KATT/raf-query/issues/236)) ([2551e97](https://github.com/KATT/raf-query/commit/2551e9710aa7b149be333a1675dae31d9d1f5efd)), references [#230](https://github.com/KATT/raf-query/issues/230)
+
+### Miscellaneous Chores
+
+* **lint:** require a docs link on every public export ([#237](https://github.com/KATT/raf-query/issues/237)) ([b5c8133](https://github.com/KATT/raf-query/commit/b5c8133c129e0412e82cd2f24da6a2516b4a2012))
+* unblock CI: [@see](https://github.com/see) links and the RSC test's build ([#245](https://github.com/KATT/raf-query/issues/245)) ([84927e4](https://github.com/KATT/raf-query/commit/84927e4a900f7608e1e17b022e28afadbe00e4ae)), references [#243](https://github.com/KATT/raf-query/issues/243) [#246](https://github.com/KATT/raf-query/issues/246) [#240](https://github.com/KATT/raf-query/issues/240) [#238](https://github.com/KATT/raf-query/issues/238)
+
+## [0.12.0](https://github.com/KATT/raf-query/compare/0.11.1...0.12.0) (2026-11-08)
+
+### ⚠ BREAKING CHANGES
+
+- greenfield rewrite on a promise kernel, with load() handles and opt-in behaviors ([#230](https://github.com/KATT/raf-query/issues/230))
+
+### Features
+
+- greenfield rewrite on a promise kernel, with load() handles and opt-in behaviors ([#230](https://github.com/KATT/raf-query/issues/230)) ([e2a6f85](https://github.com/KATT/raf-query/commit/e2a6f85297992dc8a5cdd3f871a54452393ae978))
+
 ## [0.11.1](https://github.com/KATT/raf-query/compare/0.11.0...0.11.1) (2026-10-17)
 
 ### Features
 
-* **core:** take throwOnError from the query's options (2/2) ([#214](https://github.com/KATT/raf-query/issues/214)) ([ef1f0fd](https://github.com/KATT/raf-query/commit/ef1f0fd8eda2a73f4c4c268e8a3a5cf91a0ba0d8)), references [#448](https://github.com/KATT/raf-query/issues/448)
+- **core:** take throwOnError from the query's options (2/2) ([#214](https://github.com/KATT/raf-query/issues/214)) ([ef1f0fd](https://github.com/KATT/raf-query/commit/ef1f0fd8eda2a73f4c4c268e8a3a5cf91a0ba0d8)), references [#448](https://github.com/KATT/raf-query/issues/448)
 
 ## [0.11.0](https://github.com/KATT/raf-query/compare/0.10.4...0.11.0) (2026-10-16)
 

package/README.md

@@ -1,47 +1,57 @@
 # @raf-query/core
 
-The framework-agnostic cache behind [raf-query](https://raf-query.katt.dev), written in and for [Effect](https://effect.website): every verb is an Effect with typed errors and services, and entries can be watched as Streams. It also holds `QueryClient`, the same cache with Promise methods, which the framework bindings re-export.
+The framework-agnostic query client behind [raf-query](https://raf-query.katt.dev): a small cache that dedupes requests, keeps entries fresh, and hands out serializable handles. Retries, timeouts, refetch on focus or reconnect, polling and hydration are opt-in links, features and exports, so a client bundles only what it turns on.
 
-**[Documentation](https://raf-query.katt.dev/docs/effect)** · [API reference](https://raf-query.katt.dev/docs/api-reference#raf-querycore) · [GitHub](https://github.com/KATT/raf-query)
+**[Documentation](https://raf-query.katt.dev)** · [API reference](https://raf-query.katt.dev/docs/api-reference#raf-querycore) · [GitHub](https://github.com/KATT/raf-query)
 
 > [!NOTE]
 > raf-query is early. The API can still change between minor releases, and you use it at your own risk.
 
-React apps install [`@raf-query/react`](https://www.npmjs.com/package/@raf-query/react) instead: it re-exports this package, so you never import core directly. Install core on its own for Effect programs and for bindings to other frameworks.
+React apps install [`@raf-query/react`](https://www.npmjs.com/package/@raf-query/react) instead: it re-exports this package, so you never import core directly. Install core on its own for scripts, tests and bindings to other frameworks.
 
 ## Install
 
 ```bash
-npm install @raf-query/core effect
+npm install @raf-query/core
 ```
 
 ## Usage
 
 ```ts
-import { QueryCache, queryOptions } from "@raf-query/core";
-import { Effect, Schedule, Stream } from "effect";
+import {
+	createQueryClient,
+	group,
+	invalidateOne,
+	load,
+	queryOptions,
+	retry,
+	revalidate,
+} from "@raf-query/core";
+
+const issues = group("issues");
 
 export function issueQuery(input: { id: number }) {
 	return queryOptions({
-		queryKey: ["issue", input.id],
-		queryFn: () => IssueRepo.get(input.id), // Effect<Issue, IssueNotFound>
-		retry: Schedule.exponential("200 millis").pipe(Schedule.upTo({ times: 3 })),
+		queryKey: issues("byId", input.id),
+		queryFn: () => getIssue(input.id),
 	});
 }
 
-const program = Effect.gen(function* () {
-	const cache = yield* QueryCache.QueryCache;
-	yield* cache.fetch(issueQuery, { id: 1 }); // fails with IssueNotFound
-	yield* cache.watch(issueQuery, { id: 1 }).pipe(
-		Stream.map((state) => state.data?.title),
-		Stream.runForEach((title) => Effect.log(title)),
-	);
+const queryClient = createQueryClient({ links: [retry()], staleTime: 5000 });
+
+const [, data] = await load(queryClient, {
+	issue: revalidate(issueQuery, { id: 1 }),
 });
+console.log(data.issue.title);
 
-Effect.runFork(program.pipe(Effect.provide(QueryCache.layer())));
+await invalidateOne(queryClient, issueQuery, { id: 1 });
 ```
 
-[Effect](https://raf-query.katt.dev/docs/effect) and [services](https://raf-query.katt.dev/docs/effect-services) in the docs cover the rest.
+## Entry points
+
+| Import            | Use                                                                                                                          |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `@raf-query/core` | `createQueryClient`, query factories, `load`, the verbs, the built-in links and features, `group`, `dehydrate` and `hydrate` |
 
 ## License
 

package/dist/client.d.mts

@@ -1,130 +1,174 @@
-import { DataOf, InputArgs, InputOf, LoadOptions, PagedQueryFactory, QueryFactory, QueryHandle, QueryHandleWithData } from "./options.mjs";
-import { Query, query_d_exports } from "./query.mjs";
-import { DehydrateOptions, DehydratedState, HydrateOptions } from "./hydration.mjs";
-import { Config, Event, Filter, QueryCache, Target, Updater, cache_d_exports } from "./cache.mjs";
-import { Effect, Layer } from "effect";
+import { QueryKey } from "./keys/keys.mjs";
+import { AnyPart, AnyRoot, Decl, Declares, MetaOf, MetaOfDecl, RootTypes } from "./root.mjs";
+import { Stamp } from "./keys/targets.mjs";
+import { QueryOptions } from "./options.mjs";
+import { Listeners, SubscribeOptions } from "./subscribe.mjs";
+import { Entry } from "./entry.mjs";
 //#region src/client.d.ts
-export interface QueryClientConfig<TServices = never> extends Config {
-  /**
-   * Services for queries whose `queryFn` returns an Effect. Built with the
-   * client, so it must build synchronously; `dispose()` runs its
-   * finalizers.
-   */
-  readonly layer?: Layer.Layer<TServices>;
-  /** Called with every failed request, including failed prefetches. */
-  onError?(error: unknown, query: Query): void;
-  /**
-   * When `false`, `useQuery` for an Effect `queryFn` (a typed `ErrorOf`)
-   * returns a `Result` in the first tuple slot instead of a promise that
-   * rejects. Defaults to `false` when `layer` is set, `true` otherwise.
-   * A query's own `throwOnError` (in `queryOptions`) and a read's win over
-   * it; types only see those two. Promise `queryFn`s always throw, whatever
-   * the flags say: reads tell them apart by what the `queryFn` returned
-   * ({@link Query.returnsEffectUnsafe}).
-   */
-  readonly throwOnError?: boolean;
+type LinkFunction = (op: Operation, next: (op: Operation) => Promise<unknown>) => Promise<unknown>;
+type FeatureFunction = (client: QueryClient, signal: AbortSignal) => void;
+/** Any link, whatever `meta` it reads. */
+export type AnyLink = LinkFunction & AnyPart;
+/** Any feature, whatever `meta` it reads. */
+export type AnyFeature = FeatureFunction & AnyPart;
+/**
+ * Time and timers, injectable so tests control them without patching globals.
+ *
+ * @see https://raf-query.katt.dev/docs/testing#time
+ */
+export interface Clock {
+  clearTimeout(handle: unknown): void;
+  now(): number;
+  setTimeout(callback: () => void, ms: number): unknown;
 }
+export declare const systemClock: Clock;
 /**
- * The query cache, with Promise methods. Create one per request on the
- * server and one per browser tab. `effect` is the same cache's Effect API.
- * Its verbs take factories whose `queryFn` needs at most `TServices`, the
- * services of `config.layer`.
+ * One request, as links see it. `TMeta` is what the link declares.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#links-and-features
  */
-export declare class QueryClient<TServices = never> {
-  #private;
-  /** The Effect-native cache behind this client. */
-  readonly effect: QueryCache;
+export interface Operation<TMeta extends object = object> {
+  readonly client: QueryClient;
+  /** The entry's data when the request started (paged queries extend it). */
+  readonly data: unknown;
+  /** For paged queries: which page to add. */
+  readonly direction: "next" | "previous" | undefined;
+  readonly hasData: boolean;
+  readonly hash: string;
+  readonly input: unknown;
+  /** The query's `meta`, `{}` when it has none. */
+  readonly meta: TMeta;
+  readonly options: QueryOptions;
+  /** For paged queries: how many pages a first load fetches. */
+  readonly pages: number | undefined;
+  readonly queryKey: QueryKey;
+  readonly signal: AbortSignal;
+}
+/**
+ * Wraps every request, like a tRPC link. Call `next(op)` to run the rest of
+ * the chain; the last link is the query's own `queryFn`. `TDecl` is the
+ * `meta` it reads: see {@link link}.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#links-and-features
+ */
+export type Link<TDecl extends Decl = Decl> = LinkFunction & Declares<TDecl>;
+/**
+ * A cache-wide behavior, started when a provider mounts the client and
+ * stopped by `signal`. `TDecl` is the `meta` it reads: see {@link feature}.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#links-and-features
+ */
+export type Feature<TDecl extends Decl = Decl> = FeatureFunction & Declares<TDecl>;
+/**
+ * A link that declares the `meta` fields it reads. A root's queries take
+ * those fields only when the root has the link.
+ *
+ * ```ts
+ * const traced = link<{ meta: { traceId?: string } }>((op, next) =>
+ *   withTrace(op.meta.traceId, () => next(op)),
+ * );
+ * ```
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#links-and-features
+ */
+export declare function link<TDecl extends Decl = Decl>(run: (op: Operation<MetaOfDecl<TDecl> & object>, next: (op: Operation) => Promise<unknown>) => Promise<unknown>): Link<TDecl>;
+/**
+ * A feature that declares the `meta` fields it reads. Without `setup`, it
+ * only declares them: a root's own fields, such as an `owner` its targets
+ * match on.
+ *
+ * ```ts
+ * const ownership = feature<{ meta: { owner?: "posts-team" | "users-team" } }>();
+ * ```
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#links-and-features
+ */
+export declare function feature<TDecl extends Decl = Decl>(setup?: FeatureFunction): Feature<TDecl>;
+export type ClientEvent = {
+  readonly entry: Entry;
+  readonly type: "added" | "removed" | "updated";
+} | {
+  readonly entry: Entry;
+  readonly type: "readers";
+};
+/**
+ * What `createQueryClient` takes: links, features and the cache-wide defaults.
+ *
+ * @see https://raf-query.katt.dev/docs/important-defaults#changing-the-defaults
+ */
+export interface QueryClientConfig {
+  readonly clock?: Clock;
+  /** Behaviors started while a provider has the client mounted. */
+  readonly features?: ReadonlyArray<AnyFeature>;
+  /** Default `gcTime`: 5 minutes. Server clients never gc. */
+  readonly gcTime?: number;
+  /** Default: no `window`. Server clients never gc and never revalidate cached data. */
+  readonly isServer?: boolean;
+  /** Wrap every request, outermost first. */
+  readonly links?: ReadonlyArray<AnyLink>;
+  /** Default `staleTime`: `0`. */
+  readonly staleTime?: number;
+  /** Default `structuralSharing`: `true`. */
+  readonly structuralSharing?: boolean;
+}
+/**
+ * A query cache. `TTypes` is its root's types, which factories built with
+ * `bindQueryOptions<typeof makeQueryClient>()` are checked against. The bare
+ * `QueryClient` type takes a client of any root.
+ *
+ * @see https://raf-query.katt.dev/docs/api-reference#the-client
+ */
+export interface QueryClient<TTypes extends RootTypes = AnyRoot> {
+  /** Entries changed since the last notification. */
+  readonly "~changed": Set<Entry>;
+  readonly "~entries": Map<string, Entry>;
+  readonly "~events": Listeners<ClientEvent>;
+  /** Orders requests and invalidations. */
+  "~seq": number;
+  /** Invalidations not yet older than every entry's data. */
+  "~stamps": Array<Stamp>;
+  /** Phantom: the root's types, invariant. `undefined` at runtime. */
+  readonly "~types"?: {
+    readonly root: (types: TTypes) => TTypes;
+  };
+  readonly clock: Clock;
+  readonly config: QueryClientConfig;
   readonly isServer: boolean;
   /**
-   * Default for Effect `useQuery` reads. See
-   * {@link QueryClientConfig.throwOnError}.
-   */
-  readonly throwOnError: boolean;
-  constructor(config?: QueryClientConfig<TServices>);
-  /**
-   * The cache entry for a factory call, created if missing. Doesn't fetch.
-   * For bindings; apps use the verbs.
-   */
-  getQuery<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Query<TFactory>;
-  /**
-   * Start a query without waiting and return its handle. Fresh data is
-   * reused; stale data refetches in the background (in the browser only).
-   * Errors surface where the data is read, never here.
-   */
-  prefetch<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): QueryHandle<TFactory>;
-  /**
-   * {@link fetch} without waiting on stale data: start a query and wait for
-   * it on a cache miss. Stale cached data resolves immediately and
-   * revalidates in the browser. Rejects if that request fails.
-   */
-  ensure<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<QueryHandleWithData<TFactory>>;
-  /** {@link ensure}, loading `options.pages` pages of a paged query. */
-  ensure<TFactory extends PagedQueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Promise<QueryHandleWithData<TFactory>>;
-  /**
-   * Start a query and resolve to a handle holding its data. Waits on a cache
-   * miss and on stale data (on the server, only invalidated data), so the
-   * data is fresh. Rejects if that request fails.
-   */
-  fetch<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<QueryHandleWithData<TFactory>>;
-  /** {@link fetch}, loading `options.pages` pages of a paged query. */
-  fetch<TFactory extends PagedQueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Promise<QueryHandleWithData<TFactory>>;
-  /**
-   * Mark queries stale and refetch the ones being read. Resolves once those
-   * refetches settle, so an action stays pending until fresh data is on
-   * screen. Takes a factory and its input, or a {@link QueryCache.Filter}.
-   */
-  invalidate<TFactory extends QueryFactory<TServices>>(...target: Target<TFactory>): Promise<void>;
-  /**
-   * Drop queries' data and errors, as if they were never fetched. Read ones
-   * suspend and refetch; resolves once those refetches settle.
+   * Cache events: entries added, updated, removed, or gaining and losing
+   * readers. With `replay: true`, the listener first gets an `added` event
+   * for every entry the cache already holds, so a feature that keeps
+   * entries in sync starts from what's there.
    */
-  reset<TFactory extends QueryFactory<TServices>>(...target: Target<TFactory>): Promise<void>;
-  /**
-   * Remove queries from the cache and abort their requests. Readers keep the
-   * removed entry until they render again.
-   */
-  remove<TFactory extends QueryFactory<TServices>>(...target: Target<TFactory>): void;
-  /** Write data for a factory call. Readers re-render without suspending. */
-  setData<TFactory extends QueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, updater: Updater<DataOf<TFactory>>): void;
-  /**
-   * Cached data for a factory call, or `undefined` if there is none. Data can
-   * itself be `undefined`; `Query.getUnsafe(getQuery(...)).hasData` tells
-   * them apart.
-   */
-  getData<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): DataOf<TFactory> | undefined;
-  /** Every entry, for devtools and integrations. */
-  getAll(): ReadonlyArray<Query>;
-  /**
-   * How many entries have a request in flight: all of them, or those
-   * matching `filter`. For global loading indicators.
-   */
-  isFetching(filter?: Filter): number;
-  /** Listen to entries being added, updated, and removed. */
-  subscribe(listener: (event: Event) => void): () => void;
-  /** Drop every entry and abort in-flight requests. */
-  clear(): void;
-  /**
-   * Start refetching read, stale queries on window focus and reconnect.
-   * Returns the matching unmount. Providers call this; mounts are counted.
-   */
-  mount(): () => void;
-  /**
-   * Run an Effect with the cache (`QueryCache`) and the services of
-   * `config.layer`, as `Effect.runPromise` does: it rejects with the
-   * Effect's failure, or its defect. For an app's loaders and actions.
-   */
-  runPromise<A, E>(effect: Effect.Effect<A, E, QueryCache | TServices>): Promise<A>;
-  /**
-   * Close the client: interrupt every request and timer, and release the
-   * layer's services. Resolves once the layer's finalizers have run.
-   */
-  dispose(): Promise<void>;
+  subscribe(listener: (event: ClientEvent) => void, options?: SubscribeOptions & {
+    readonly replay?: boolean;
+  }): () => void;
 }
-/** Snapshot the cache for transfer to another client (server → browser). */
-export declare function dehydrate(client: QueryClient, options?: DehydrateOptions): DehydratedState;
 /**
- * Write dehydrated entries into a client. Existing entries only take newer
- * data; pending entries resume the sender's request.
+ * Create a query client. Behaviors are opt-in: pass `links` and `features`,
+ * or spread `recommended()`. The client's `meta` type is what they declare.
+ *
+ * ```ts
+ * const ownership = feature<{ meta: { owner?: "posts-team" | "users-team" } }>();
+ * export const makeQueryClient = () =>
+ *   createQueryClient({ links: [retry()], features: [ownership], staleTime: 30_000 });
+ * ```
+ *
+ * Make one per request on the server (in a loader or a request-scoped
+ * cache), never at module level.
+ *
+ * @see https://raf-query.katt.dev/docs/important-defaults
+ */
+export declare function createQueryClient<const TLinks extends ReadonlyArray<AnyLink> = [], const TFeatures extends ReadonlyArray<AnyFeature> = []>(config?: QueryClientConfig & {
+  readonly features?: TFeatures;
+  readonly links?: TLinks;
+}): QueryClient<{
+  readonly meta: MetaOf<[...TLinks, ...TFeatures]>;
+}>;
+/**
+ * Start the client's features. Providers call it while mounted; the
+ * returned function stops them. Mounts are counted, so features start once
+ * however many providers share the client, and stop with the last.
  */
-export declare function hydrate(client: QueryClient, state: DehydratedState, options?: HydrateOptions): void;
+export declare function mount(client: QueryClient): () => void;
 //#endregion