@raf-query/core 0.11.0 → 0.12.0

package/dist/entry.d.mts

@@ -1,159 +1,78 @@
-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>;
 }
+export declare function abortError(): DOMException;
 /**
- * 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.
+ * 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 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 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'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;
 }
-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.
+ * 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 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;
-/**
- * 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.
- */
-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;
-/**
- * Adopt a request started elsewhere (the server's, during hydration). Its
- * data counts as fetched when the sender got it, not when it arrived.
- */
-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