@bounded-sh/client 0.0.3 → 0.0.4

package/dist/hooks/useQuery.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Reactive realtime query hook — the ergonomic counterpart to the imperative
+ * `subscribe(path, { onData })`.
+ *
+ * `useQuery` subscribes for you and returns an **auto-updating value**, so you
+ * never write an `onData` callback (and never trip the classic trap of treating
+ * the *first* callback as the final state). `data` always holds the **full,
+ * current, read-rule-filtered** result the server last delivered — an array for
+ * a collection path, the document (or `null`) for a single-document path — and
+ * re-renders whenever ANY writer changes the matching set.
+ *
+ * ```tsx
+ * const { data: rows, loading, error } = useQuery<Presence[]>(
+ *   `rooms/${roomId}/presence`,
+ *   { filter: { online: true } },
+ * );
+ * if (loading) return <Spinner/>;
+ * return <>{rows!.map(p => <Peer key={p._id} p={p}/>)}</>;   // shows EVERYONE, always
+ * ```
+ *
+ * Mirrors Convex's `useQuery`: there is no callback to get wrong, so a doc
+ * another client writes a moment later simply appears in `data` on the next
+ * render — there is no "missed cross-writer update".
+ *
+ * Pass `path = null`/`undefined` to skip subscribing (e.g. until an id is ready);
+ * `data` stays `undefined` and `loading` flips to `false`.
+ */
+export interface UseQueryOptions {
+    /** MongoDB-style filter, same shape as `get()`/`subscribe()`. */
+    filter?: Record<string, any>;
+    /** Server-side sort, e.g. `{ createdAt: -1 }`. */
+    sort?: Record<string, number>;
+    /** Natural-language filter (AI), evaluated server-side. */
+    prompt?: string;
+    /** Also walk nested sub-collections at the path. */
+    includeSubPaths?: boolean;
+    /** Expand relationship links on each delivered doc. */
+    shape?: Record<string, any>;
+    /** Cap how many docs the live feed tracks. */
+    limit?: number;
+    /** Pagination cursor. */
+    cursor?: string;
+    /** Explicit app id override (else the configured one). */
+    appId?: string;
+}
+export interface UseQueryResult<T> {
+    /**
+     * The full current value the server delivered: an array of documents for a
+     * collection path, the document (or `null`) for a single-document path, and
+     * `undefined` before the first delivery (or when `path` is nullish).
+     */
+    data: T | undefined;
+    /** `true` until the first delivery arrives. */
+    loading: boolean;
+    /** The last subscription error, or `null`. */
+    error: Error | null;
+}
+export declare function useQuery<T = any>(path: string | null | undefined, options?: UseQueryOptions): UseQueryResult<T>;