@raf-query/core 0.11.1 → 0.13.0

package/dist/client.mjs

@@ -1,176 +1,104 @@
-import { QueryCache, layer } from "./cache.mjs";
-import { Context, Effect, Exit, Layer, Option, Predicate, Scope } from "effect";
+import { listeners } from "./subscribe.mjs";
 //#region src/client.ts
+const systemClock = {
+	clearTimeout: (handle) => {
+		clearTimeout(handle);
+	},
+	now: () => Date.now(),
+	setTimeout: (callback, ms) => setTimeout(callback, ms)
+};
 /**
-* A verb's Effect, run by a client. Its requirement is the factory's
-* `ServicesOf`, which the client's verbs only accept when its `layer`
-* provides them.
+* 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
 */
-function provided(effect) {
-	return effect;
+function link(run) {
+	return run;
 }
+const noop = () => {};
 /**
-* Run a verb that waits on a request. A cancelled request rejects with an
-* `AbortError`, as an aborted `fetch` does, not with the Effect API's
-* `Query.CancelledError`.
+* 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
 */
-function runLoad(effect) {
-	return Effect.runPromise(effect).catch((error) => {
-		throw Predicate.isTagged(error, "CancelledError") ? new DOMException("The query was cancelled", "AbortError") : error;
-	});
-}
-/** `ensure` / `fetch` arguments, forwarded to the cache's same verb. */
-function loadArgs(input, options) {
-	return [input, options];
+function feature(setup = noop) {
+	return setup;
 }
 /**
-* 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`.
+* 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
 */
-var QueryClient = class {
-	/** The Effect-native cache behind this client. */
-	effect;
-	isServer;
-	/**
-	* Default for Effect `useQuery` reads. See
-	* {@link QueryClientConfig.throwOnError}.
-	*/
-	throwOnError;
-	/**
-	* The cache and the layer's services. Typed `never` so clients of any
-	* `TServices` stay assignable to each other; `runPromise` restores it.
-	*/
-	#context;
-	/**
-	* Owns the cache's fibers, mounts and the layer's services; lives until
-	* `dispose()`.
-	*/
-	#scope = Scope.makeUnsafe();
-	constructor(config = {}) {
-		const cache = layer(config);
-		const services = Effect.runSync(Layer.buildWithScope(config.layer ? Layer.provideMerge(cache, config.layer) : cache, this.#scope));
-		this.#context = services;
-		this.effect = Context.get(services, QueryCache);
-		this.isServer = this.effect.isServer;
-		this.throwOnError = config.throwOnError ?? config.layer === void 0;
-		const onError = config.onError;
-		if (onError) this.effect.subscribeUnsafe((event) => {
-			if (event.type === "failed") onError(event.error, event.query);
-		});
-	}
-	/**
-	* The cache entry for a factory call, created if missing. Doesn't fetch.
-	* For bindings; apps use the verbs.
-	*/
-	getQuery(factory, ...args) {
-		return this.effect.getQueryUnsafe(factory, ...args);
-	}
-	/**
-	* 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(factory, ...args) {
-		return Effect.runSync(provided(this.effect.prefetch(factory, ...args)));
-	}
-	ensure(factory, input, options) {
-		return runLoad(provided(this.effect.ensure(factory, ...loadArgs(input, options))));
-	}
-	fetch(factory, input, options) {
-		return runLoad(provided(this.effect.fetch(factory, ...loadArgs(input, options))));
-	}
-	/**
-	* 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(...target) {
-		return Effect.runPromise(this.effect.invalidate(...target));
-	}
-	/**
-	* Drop queries' data and errors, as if they were never fetched. Read ones
-	* suspend and refetch; resolves once those refetches settle.
-	*/
-	reset(...target) {
-		return Effect.runPromise(this.effect.reset(...target));
-	}
-	/**
-	* Remove queries from the cache and abort their requests. Readers keep the
-	* removed entry until they render again.
-	*/
-	remove(...target) {
-		Effect.runSync(this.effect.remove(...target));
-	}
-	/** Write data for a factory call. Readers re-render without suspending. */
-	setData(factory, input, updater) {
-		Effect.runSync(this.effect.setData(factory, input, updater));
-	}
-	/**
-	* 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(factory, ...args) {
-		return Option.getOrUndefined(Effect.runSync(this.effect.getData(factory, ...args)));
-	}
-	/** Every entry, for devtools and integrations. */
-	getAll() {
-		return Effect.runSync(this.effect.all);
-	}
-	/**
-	* How many entries have a request in flight: all of them, or those
-	* matching `filter`. For global loading indicators.
-	*/
-	isFetching(filter) {
-		return this.effect.isFetchingUnsafe(filter);
-	}
-	/** Listen to entries being added, updated, and removed. */
-	subscribe(listener) {
-		return this.effect.subscribeUnsafe(listener);
-	}
-	/** Drop every entry and abort in-flight requests. */
-	clear() {
-		Effect.runSync(this.effect.clear);
-	}
-	/**
-	* Start refetching read, stale queries on window focus and reconnect.
-	* Returns the matching unmount. Providers call this; mounts are counted.
-	*/
-	mount() {
-		const scope = Scope.forkUnsafe(this.#scope);
-		Effect.runSync(this.effect.mount.pipe(Scope.provide(scope)));
-		return () => {
-			Effect.runSync(Scope.close(scope, Exit.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(effect) {
-		return Effect.runPromiseWith(this.#context)(effect);
-	}
-	/**
-	* Close the client: interrupt every request and timer, and release the
-	* layer's services. Resolves once the layer's finalizers have run.
-	*/
-	dispose() {
-		return Effect.runPromise(Scope.close(this.#scope, Exit.void));
-	}
-};
-/** Snapshot the cache for transfer to another client (server → browser). */
-function dehydrate(client, options) {
-	return Effect.runSync(client.effect.dehydrate(options));
+function createQueryClient(config = {}) {
+	const events = listeners();
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		"~changed": /* @__PURE__ */ new Set(),
+		"~entries": entries,
+		"~events": events,
+		"~seq": 0,
+		"~stamps": [],
+		clock: config.clock ?? systemClock,
+		config,
+		isServer: config.isServer ?? !("window" in globalThis),
+		subscribe: (listener, options) => {
+			const unsubscribe = events.subscribe(listener, options);
+			if (options?.replay && !options.signal?.aborted) for (const entry of entries.values()) listener({
+				entry,
+				type: "added"
+			});
+			return unsubscribe;
+		}
+	};
 }
+const mounted = /* @__PURE__ */ new WeakMap();
 /**
-* Write dehydrated entries into a client. Existing entries only take newer
-* data; pending entries resume the sender's request.
+* 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.
 */
-function hydrate(client, state, options) {
-	Effect.runSync(client.effect.hydrate(state, options));
+function mount(client) {
+	let current = mounted.get(client);
+	if (!current) {
+		current = {
+			controller: new AbortController(),
+			count: 0
+		};
+		mounted.set(client, current);
+		for (const start of client.config.features ?? []) start(client, current.controller.signal);
+	}
+	const shared = current;
+	shared.count += 1;
+	return () => {
+		shared.count -= 1;
+		if (shared.count === 0) {
+			mounted.delete(client);
+			shared.controller.abort();
+		}
+	};
 }
 //#endregion
-export { QueryClient, dehydrate, hydrate };
+export { createQueryClient, feature, link, mount, systemClock };

package/dist/entry.d.mts

@@ -1,159 +1,85 @@
-import { QueryKey } from "./key.mjs";
-import { AnyQueryOptions, QueryBehavior, QueryFactory, QueryHandle, QueryMeta } from "./options.mjs";
-import { Platform, PlatformEvent } from "./platform.mjs";
+import { AnyFactory, QueryKey } from "./keys/keys.mjs";
+import { QueryOptions } from "./options.mjs";
+import { Listeners, SubscribeOptions } from "./subscribe.mjs";
 import { Pending, Thenable } from "./thenable.mjs";
-import { FetchRequest, Query, State, SubscribeOptions } from "./query.mjs";
-import { Event } from "./cache.mjs";
-import { Cause, Clock, Context, Deferred, Effect, Scope, Stream } from "effect";
-declare namespace entry_d_exports {
-  export { CacheState, CancelledError, DisabledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isDisabled, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
+import { QueryClient } from "./client.mjs";
+//#region src/entry.d.ts
+/** An entry's state. A new object on every change, so it works as a snapshot. */
+export interface EntryState {
+  readonly data: unknown;
+  /** The last request's error, while it's the latest outcome. */
+  readonly error: unknown;
+  readonly fetchingDirection: "next" | "previous" | undefined;
+  readonly hasData: boolean;
+  readonly isFetching: boolean;
+  readonly status: "error" | "pending" | "success";
+  /** When the data was written (ms since epoch); `0` without data. */
+  readonly updatedAt: number;
 }
-export declare const TypeId = "~@raf-query/core/Query";
-declare const CancelledError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
-  readonly _tag: "CancelledError";
-} & Readonly<A>;
-/**
- * The failure of a request that was interrupted rather than settled: its
- * entry was removed or cleared, or an Effect `queryFn` was interrupted.
- */
-export declare class CancelledError extends CancelledError_base {
-  readonly message = "The query was cancelled";
+/** How a request ended, for whoever waited on it. */
+export type Outcome = {
+  readonly error: unknown;
+  readonly ok: false;
+} | {
+  readonly ok: true;
+};
+interface Run {
+  readonly controller: AbortController;
+  readonly done: PromiseWithResolvers<Outcome>;
+  /** Resolve `done` at the first chunk of a stream, not its end. */
+  settled: boolean;
+  readonly startedAt: number;
 }
-declare const DisabledError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
-  readonly _tag: "DisabledError";
-} & Readonly<A>;
-/**
- * Why a query with `enabled: false` has no data: `ensure` / `fetch` die
- * with it, and on a server its promise rejects with it.
- */
-export declare class DisabledError extends DisabledError_base<{
+export interface Entry {
+  readonly client: QueryClient;
+  factory: AnyFactory | undefined;
+  gcTimer: unknown;
   readonly hash: string;
-}> {
-  get message(): string;
+  input: unknown;
+  readonly key: QueryKey;
+  options: QueryOptions | undefined;
+  pendingThenable: Pending<unknown> | undefined;
+  readonly readers: Listeners<EntryState>;
+  /** `~seq` when the request behind the data started; invalidations after it make it stale. */
+  requestedAt: number;
+  run: Run | undefined;
+  state: EntryState;
+  thenable: Thenable<unknown>;
 }
 /**
- * The state a cache shares with its entries. Entries are created
- * synchronously (a render reads one), so they fork their fibers with the
- * services and into the scope the cache was made with.
+ * Make the `AbortError` (a `DOMException`) that a `load` waiting on a removed query rejects with.
+ *
+ * @see https://raf-query.katt.dev/docs/query-cancellation#when-requests-are-aborted
  */
-export interface CacheState {
-  readonly clock: Clock.Clock;
-  readonly defaults: QueryBehavior;
-  readonly entries: Map<string, Entry>;
-  readonly isServer: boolean;
-  readonly listeners: Set<(event: Event) => void>;
-  readonly platform: Platform;
-  readonly scope: Scope.Scope;
-  readonly services: Context.Context<never>;
-}
-/** The background work of an entry, one fiber per kind. */
-type Task = "errorShown" | "gc" | "request" | "stale";
-interface Tasks {
-  cancel(task: Task): void;
-  fork(task: Task, effect: Effect.Effect<void>, options?: {
-    readonly onlyIfMissing?: boolean;
-  }): void;
-}
-interface Commands {
-  readonly fetchNextPage: Effect.Effect<void>;
-  readonly fetchPreviousPage: Effect.Effect<void>;
-  readonly refetch: Effect.Effect<void>;
-}
-/** A cache entry: a {@link Query} and the state behind it. */
-export interface Entry extends Query {
-  readonly cache: CacheState;
-  /** One Effect per command, so readers can compare them by identity. */
-  readonly commands: Commands;
-  /** A failed first load was shown; the next read retries it. */
-  errorShown: boolean;
-  /** `failureCount` before the request in flight, restored if it's cancelled. */
-  failureCountBefore: number;
-  handle: QueryHandle;
-  /** `meta` sent with dehydrated state, for an entry no factory call has reached. */
-  hydratedMeta: QueryMeta | undefined;
-  /** Awaited by every caller of the request in flight; outlives restarts. */
-  inFlight: Deferred.Deferred<unknown, unknown> | undefined;
-  readonly listeners: Map<() => void, SubscribeOptions>;
-  options: AnyQueryOptions | undefined;
-  /** The first load's promise, until it settles. */
-  pending: Pending<unknown> | undefined;
-  /** The last reader left during the request in flight: it retries no more. */
-  retriesStopped: boolean;
-  /**
-   * The last `queryFn` call returned an Effect (`true`) or a promise or
-   * plain value (`false`), here or on the cache it was hydrated from.
-   * `undefined` until one has run.
-   */
-  returnsEffect: boolean | undefined;
-  /** Open while the entry is cached; owns its fibers. */
-  readonly scope: Scope.Closeable;
-  /**
-   * What its requests run with: the cache's services, under those of the
-   * latest verb that called for this entry ({@link provide}).
-   */
-  services: Context.Context<never>;
-  /**
-   * The request in flight read its `signal`, or returned an Effect, so
-   * interrupting it cancels its work (TanStack's `abortSignalConsumed`).
-   */
-  signalRead: boolean;
-  state: State<unknown>;
-  readonly tasks: Tasks;
-}
-export declare function isQuery(value: unknown): value is Query;
-export declare function entryOf<TFactory extends QueryFactory>(query: Query<TFactory>): Entry;
-export declare function emit(cache: CacheState, event: Event): void;
-export declare function make(cache: CacheState, key: QueryKey, hash: string): Entry;
-/** Readers are subscribed; `invalidate` and focus refetch only what is read. */
-export declare function isObserved(entry: Entry): boolean;
-/** The entry's latest factory call returned `enabled: false`: it doesn't run. */
-export declare function isDisabled(entry: Entry): boolean;
-/** Until a factory call attaches options, `meta` comes from hydration. */
-export declare function metaOf(entry: Entry): QueryMeta | undefined;
-export declare function isStaleUnsafe(entry: Entry): boolean;
-export declare function hasNextPageUnsafe(entry: Entry): boolean;
-export declare function hasPreviousPageUnsafe(entry: Entry): boolean;
-export declare function subscribeUnsafe(entry: Entry, listener: () => void, options?: SubscribeOptions): () => void;
-export declare function changes(entry: Entry): Stream.Stream<State<unknown>>;
-/**
- * Run this entry's requests with the services of `caller`, a verb's fiber
- * context, over the cache's: every request from now on, including ones a
- * render, a refetch or `invalidate` starts.
- */
-export declare function provide(entry: Entry, caller: Context.Context<never>): void;
-/** Attach the options and input of the latest factory call. */
-export declare function setOptions(entry: Entry, options: AnyQueryOptions, input: unknown): void;
+export declare function abortError(): DOMException;
 /**
- * The promise a render should unwrap. Starts the first request if nothing
- * has, and retries a failed first load once its error has been shown.
+ * The entry for a factory's input, created if missing, with the factory's
+ * current options. Every read goes through here, which links an entry that
+ * was only hydrated to its factory.
  */
-export declare function readUnsafe(entry: Entry): Thenable<unknown>;
-/** Start a request unless one is in flight, without waiting for it. */
-export declare function start(entry: Entry): void;
-/**
- * Whether cached data that was asked for again should be refetched. A server
- * cache renders once, so a refetch there could only duplicate a request whose
- * result is never shown; it refetches only what `invalidate` marked.
- */
-export declare function needsRefetch(entry: Entry): boolean;
-/** Background refetch of cached data that was asked for again. */
-export declare function revalidate(entry: Entry): void;
-export declare function fetch(entry: Entry, request?: FetchRequest): Effect.Effect<unknown, unknown>;
-export declare function invalidate(entry: Entry): Effect.Effect<void>;
-export declare function reset(entry: Entry): Effect.Effect<void>;
-/** Write data directly, as if a request had returned it. */
-export declare function setData(entry: Entry, data: unknown, updatedAt?: number): void;
+export declare function entryOf(client: QueryClient, factory: AnyFactory, input: unknown): Entry;
+/** Whether an invalidation newer than the entry's data covers it. */
+export declare function isInvalidated(entry: Entry): boolean;
+/** Whether the entry is a browser-only query (`ssr: false`) on a server client: nothing starts it there. */
+export declare function isBrowserOnly(entry: Entry): boolean;
+/** Whether the entry's data should be refetched before it's trusted. */
+export declare function isStale(entry: Entry): boolean;
+export interface FetchRequest {
+  readonly direction?: "next" | "previous";
+  readonly pages?: number;
+  /** Abort a request in flight and start over (an invalidation). */
+  readonly restart?: boolean;
+}
 /**
- * Adopt a request started elsewhere (the server's, during hydration). Its
- * data counts as fetched when the sender got it, not when it arrived.
+ * Run the entry's request, or join the one in flight. Resolves with how it
+ * ended, never rejects: a removed entry's request ends with an `AbortError`.
+ * Whoever waited on a restarted request gets the new one's outcome.
  */
-export declare function resume(entry: Entry, promise: PromiseLike<{
-  readonly data?: unknown;
-  readonly updatedAt: number;
-}>): void;
-/** Refetch a read, stale entry whose readers want it on this event. */
-export declare function onPlatformEvent(entry: Entry, event: PlatformEvent): void;
-/** Take `entry` out of its cache: interrupt its fibers and fail its awaiters. */
+export declare function fetchEntry(entry: Entry, request?: FetchRequest): Promise<Outcome>;
+/** Subscribe to an entry's state. Subscribers are its readers: an entry with none can be gc'd. */
+export declare function subscribeEntry(entry: Entry, listener: (state: EntryState) => void, options?: SubscribeOptions): () => void;
+/** Drop the entry, aborting its request. Waiters get an `AbortError`. */
 export declare function remove(entry: Entry): void;
-//#endregion
-export { entry_d_exports };
+/** Drop data and errors. Read entries (or ones loading) refetch; resolves when they settle. */
+export declare function reset(entry: Entry): Promise<Outcome>;
+//#endregion