@raf-query/core 0.0.19 → 0.1.0

package/dist/query.d.mts

@@ -1,9 +1,31 @@
 import { QueryKey } from "./key.mjs";
-import { AnyQueryOptions, QueryFactory, QueryHandle } from "./options.mjs";
+import { AnyQueryOptions, DataOf, ErrorOf, QueryFactory, QueryHandle, ServicesOf } from "./options.mjs";
 import { Thenable } from "./thenable.mjs";
-//#region src/query.d.ts
+import { CancelledError as CancelledError$1, TypeId as TypeId$1, entry_d_exports } from "./entry.mjs";
+import { Direction } from "./infinite.mjs";
+import { Effect, Pipeable, Stream } from "effect";
+declare namespace query_d_exports {
+  export { CancelledError, FetchRequest, Of, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, subscribeUnsafe };
+}
+export declare const TypeId: typeof TypeId$1;
+export type TypeId = typeof TypeId;
+export interface Query<TData = unknown, TFactory extends QueryFactory = QueryFactory, TError = unknown> extends Pipeable.Pipeable {
+  /** The serializable handle for this entry's factory call. */
+  readonly handle: QueryHandle<TFactory>;
+  /** Stable string form of `key`. */
+  readonly hash: string;
+  readonly key: QueryKey;
+  /** Options from the latest factory call; `undefined` for an entry only hydrated so far. */
+  readonly options: AnyQueryOptions | undefined;
+  readonly [TypeId]: {
+    readonly _A: (_: never) => TData;
+    readonly _E: (_: never) => TError;
+  };
+}
+/** The entry of a factory call, typed by the factory. */
+export type Of<TFactory extends QueryFactory> = Query<DataOf<TFactory>, TFactory, ErrorOf<TFactory>>;
 /** A snapshot of one cache entry. Replaced, never mutated, on every change. */
-export interface QueryState<TData> {
+export interface State<TData> {
   /** Last successful data, kept through background errors. */
   readonly data: TData | undefined;
   /** Error of the last failed request, or `null`. */
@@ -11,7 +33,7 @@ export interface QueryState<TData> {
   /** Failed attempts of the current request, retries included. */
   readonly failureCount: number;
   /** Set while a paged query loads a page at one end of the list. */
-  readonly fetchDirection: "backward" | "forward" | undefined;
+  readonly fetchDirection: Direction | undefined;
   readonly hasData: boolean;
   /** A request is in flight. */
   readonly isFetching: boolean;
@@ -28,60 +50,66 @@ export interface QueryState<TData> {
   /** When `data` was fetched (ms since epoch); `0` without data. */
   readonly updatedAt: number;
 }
-/** Per-reader preferences, registered with {@link Query.subscribe}. */
+/** Per-reader preferences, registered with {@link subscribeUnsafe}. */
 export interface SubscribeOptions {
   readonly refetchOnReconnect?: boolean;
   readonly refetchOnWindowFocus?: boolean;
 }
 export interface FetchRequest {
   /** Load one more page at this end of a paged query. */
-  readonly direction?: "backward" | "forward";
+  readonly direction?: Direction;
   /** Pages to load when a paged query has none yet. */
   readonly pages?: number;
-  /** Abort an in-flight request and start over (used by `invalidate`). */
+  /** Interrupt an in-flight request and start over (used by `invalidate`). */
   readonly restart?: boolean;
 }
+export declare const CancelledError: typeof CancelledError$1;
+export type CancelledError = CancelledError$1;
+export declare const isQuery: (value: unknown) => value is Query;
 /**
- * A cache entry, as seen by bindings. Obtain one with
- * `QueryClient.getQuery(factory, input)`.
+ * Start a request, or join the one in flight. Fails with the request's
+ * error, or a {@link CancelledError} if the entry leaves the cache first.
+ * The entry's requests run with this fiber's services from now on, as after
+ * a `QueryCache` verb.
  */
-export interface Query<TData = unknown, TFactory extends QueryFactory = QueryFactory> {
-  /** Start a request, or join the one in flight. */
-  fetch(request?: FetchRequest): Promise<TData>;
-  fetchNextPage(): Promise<void>;
-  fetchPreviousPage(): Promise<void>;
-  getState(): QueryState<TData>;
-  /** The serializable handle for this entry's factory call. */
-  readonly handle: QueryHandle<TFactory>;
-  /** Stable string form of `key`. */
-  readonly hash: string;
-  hasNextPage(): boolean;
-  hasPreviousPage(): boolean;
-  invalidate(): Promise<void>;
-  /** Staleness as of now; `getState().isStale` is only kept current while read. */
-  isStaleNow(): boolean;
-  readonly key: QueryKey;
-  /** Readers currently subscribed. */
-  readonly observerCount: number;
-  /** Options from the latest factory call; `undefined` for an entry only hydrated so far. */
-  readonly options: AnyQueryOptions | undefined;
-  /**
-   * 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.
-   */
-  read(): Promise<TData>;
-  /** Refetch now; resolves when the request settles. */
-  refetch(): Promise<void>;
-  /**
-   * Drop data and errors, back to the state of a new entry. Readers suspend
-   * and refetch; resolves when that refetch settles.
-   */
-  reset(): Promise<void>;
-  /** Listen for state changes. Subscribed entries count as read. */
-  subscribe(listener: () => void, options?: SubscribeOptions): () => void;
-}
-/** Thrown into a request's awaiters when the cache is cleared mid-request. */
-export declare class CancelledError extends Error {
-  constructor();
-}
-//#endregion
+export declare const fetch: {
+  (request?: FetchRequest): <TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>) => Effect.Effect<TData, TError | CancelledError, ServicesOf<TFactory>>;
+  <TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>, request?: FetchRequest): Effect.Effect<TData, TError | CancelledError, ServicesOf<TFactory>>;
+};
+/** Refetch now; succeeds when the request settles, whatever its outcome. */
+export declare function refetch<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Effect.Effect<void>;
+/** Load the page after the last one; succeeds once it settles. */
+export declare function fetchNextPage<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Effect.Effect<void>;
+/** Load the page before the first one; succeeds once it settles. */
+export declare function fetchPreviousPage<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Effect.Effect<void>;
+/** Mark stale, and refetch if read; succeeds once that refetch settles. */
+export declare function invalidate<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Effect.Effect<void>;
+/**
+ * Drop data and errors, back to the state of a new entry. Readers suspend
+ * and refetch; succeeds when that refetch settles.
+ */
+export declare function reset<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Effect.Effect<void>;
+/** The entry's current state. */
+export declare function get<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Effect.Effect<State<TData>>;
+/** {@link get}, synchronously. */
+export declare function getUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): State<TData>;
+/**
+ * The entry's current state, then every change. Counts as a reader while
+ * the stream runs, so invalidation and focus refetch it.
+ */
+export declare function changes<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Stream.Stream<State<TData>>;
+/**
+ * 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<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Thenable<TData>;
+/** Listen for state changes. Subscribed entries count as read. */
+export declare function subscribeUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>, listener: () => void, options?: SubscribeOptions): () => void;
+/** Staleness as of now; `state.isStale` is only kept current while read. */
+export declare function isStaleUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): boolean;
+export declare function hasNextPageUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): boolean;
+export declare function hasPreviousPageUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): boolean;
+/** Readers currently subscribed. */
+export declare function observerCountUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): number;
+//#endregion
+export { query_d_exports };