@peerbit/react 0.0.20 → 0.0.22

package/src/useQuery.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useRef } from "react";
+import { useState, useEffect, useRef, useReducer } from "react";
 import {
     ClosedError,
     Documents,
@@ -8,26 +8,19 @@ import {
 } from "@peerbit/document";
 import * as indexerTypes from "@peerbit/indexer-interface";
 import { AbortError } from "@peerbit/time";
+import { NoPeersError } from "@peerbit/shared-log";
+import { v4 as uuid } from "uuid";
 
+/* ────────────── helper types ────────────── */
 type QueryLike = {
     query?: indexerTypes.Query[] | indexerTypes.QueryLike;
     sort?: indexerTypes.Sort[] | indexerTypes.Sort | indexerTypes.SortLike;
 };
-type QueryOptions = { query: QueryLike; id: string };
+type QueryOptions = { query: QueryLike; id?: string };
 
-const logWithId = (
-    options: { debug?: boolean | { id: string } } | undefined,
-    ...args: any[]
-) => {
-    if (!options?.debug) return;
-
-    if (typeof options.debug === "boolean") {
-        console.log(...args);
-    } else if (typeof options.debug.id === "string") {
-        console.log(options.debug.id, ...args);
-    }
-};
+type WaitForReplicatorsOption = { warmup?: number; eager?: boolean };
 
+/* ────────────── main hook ────────────── */
 export const useQuery = <
     T extends Record<string, any>,
     I extends Record<string, any>,
@@ -37,167 +30,179 @@ export const useQuery = <
     db?: Documents<T, I>,
     options?: {
         resolve?: R;
-        waitForReplicators?: boolean | { timeout?: number };
-        transform?: (result: WithContext<RT>) => Promise<WithContext<RT>>;
+        transform?: (r: RT) => Promise<RT>;
         debounce?: number;
         debug?: boolean | { id: string };
         reverse?: boolean;
-        batchSize?: number; // You can set a default batch size here
+        batchSize?: number;
+        prefetch?: boolean;
         onChange?: {
             merge?:
                 | boolean
                 | ((
-                      change: DocumentsChange<T>
+                      c: DocumentsChange<T>
                   ) =>
                       | DocumentsChange<T>
                       | Promise<DocumentsChange<T>>
-                      | undefined); // if true, the iterator will be updated with new documents
-            update?: (
-                prev: WithContext<RT>[],
-                change: DocumentsChange<T>
-            ) => WithContext<RT>[];
+                      | undefined);
+            update?: (prev: RT[], change: DocumentsChange<T>) => RT[];
         };
-        local?: boolean; // if true, (default is true) the iterator will only return local documents
-        remote?:
-            | boolean
-            | {
-                  eager?: boolean;
-              };
+        local?: boolean;
+        remote?: boolean | WaitForReplicatorsOption;
     } & QueryOptions
 ) => {
-    const [all, setAll] = useState<WithContext<RT>[]>([]);
-    const allRef = useRef<WithContext<RT>[]>([]);
+    /* ── «Item» is the concrete element type flowing through the hook ── */
+    type Item = RT;
+
+    /* ────────────── state & refs ────────────── */
+    const [all, setAll] = useState<Item[]>([]);
+    const allRef = useRef<Item[]>([]);
     const [isLoading, setIsLoading] = useState(false);
-    const loadingMoreRef = useRef(false);
+    const loadingMoreRef = useRef<boolean>(false);
     const iteratorRef = useRef<{
         id?: string;
-        iterator: ResultsIterator<WithContext<RT>>;
+        iterator: ResultsIterator<Item>;
+        itemsConsumed: number;
     } | null>(null);
     const emptyResultsRef = useRef(false);
     const closeControllerRef = useRef<AbortController | null>(null);
+    const waitedOnceRef = useRef(false);
+    const resetResultsOnReset = useRef(true);
 
-    const updateAll = (
-        combined: WithContext<RT>[],
-        fromChange?: DocumentsChange<any> | null
-    ) => {
-        logWithId(
-            options,
-            "Loading more items, new combined length",
-            combined.length,
-            "from change",
-            fromChange
-        );
+    const [id, setId] = useState<string | undefined>(undefined);
+    const [resetCounter, invokeReset] = useReducer((n) => n + 1, 0);
 
-        allRef.current = combined;
+    const reverseRef = useRef(options?.reverse);
+    useEffect(() => {
+        reverseRef.current = options?.reverse;
+    }, [options?.reverse]);
+
+    /* ────────────── util ────────────── */
+    const log = (...a: any[]) => {
+        if (!options?.debug) return;
+        if (typeof options.debug === "boolean") console.log(...a);
+        else console.log(options.debug.id, ...a);
+    };
 
+    const updateAll = (combined: Item[]) => {
+        allRef.current = combined;
         setAll(combined);
     };
 
     const reset = (
         fromRef: {
             id?: string;
-            iterator: ResultsIterator<WithContext<RT>>;
+            iterator: ResultsIterator<Item>;
         } | null
     ) => {
-        if (iteratorRef.current != null && iteratorRef.current !== fromRef) {
+        const toClose = iteratorRef.current;
+        if (toClose && fromRef && toClose !== fromRef) {
             return;
         }
+
+        iteratorRef.current = null;
+
         closeControllerRef.current?.abort();
         closeControllerRef.current = new AbortController();
-
         emptyResultsRef.current = false;
-        logWithId(options, "reset", {
-            id: iteratorRef.current?.id,
-            size: allRef.current.length,
-        });
 
-        !iteratorRef.current?.iterator.done() &&
-            iteratorRef.current?.iterator?.close();
-        iteratorRef.current = null;
-        setAll([]);
+        toClose?.iterator.close();
+
+        if (resetResultsOnReset.current) {
+            allRef.current = [];
+            setAll([]);
+        }
+
         setIsLoading(false);
         loadingMoreRef.current = false;
-        allRef.current = [];
+        log(options, "Iterator reset", toClose?.id, fromRef?.id);
+        setId(undefined);
     };
 
-    // Initialize the iterator only once or when query changes
     useEffect(() => {
-        if (!db || db.closed || options?.query === null) {
+        resetResultsOnReset.current = true;
+        waitedOnceRef.current = false;
+    }, [db, options?.id ?? options?.query, options?.resolve, options?.reverse]);
+
+    /* ────────────── effect: (re)create iterator ────────────── */
+    useEffect(() => {
+        if (!db || db.closed || options?.query == null) {
             reset(null);
             return;
         }
 
         const initIterator = () => {
-            // Don't make this async, it will cause issues with the iterator refs
-            try {
-                // Initialize the iterator and load initial batch.
-
-                const ref = {
-                    id: options?.id,
-                    iterator: db.index.iterate(options?.query ?? {}, {
-                        local: options?.local ?? true,
-                        remote: options?.remote ?? true,
-                        resolve: options?.resolve as any,
-                    }) as any as ResultsIterator<WithContext<RT>>,
-                };
-                iteratorRef.current = ref;
-
-                logWithId(options, "Initializing iterator", {
-                    id: options?.id,
-                    options: options,
-                });
-
-                loadMore(); // initial load
-                return ref;
-            } catch (error) {
-                console.error("Error initializing iterator", error);
-                return null;
+            let id = options?.id ?? uuid();
+            const ref = {
+                id,
+                iterator: db.index.iterate(options.query ?? {}, {
+                    local: options?.local ?? true,
+                    remote:
+                        options.remote == null || options.remote === false
+                            ? false
+                            : typeof options.remote === "object"
+                            ? options.remote
+                            : true,
+                    resolve: options?.resolve,
+                }) as ResultsIterator<Item>,
+                itemsConsumed: 0,
+            };
+            iteratorRef.current = ref;
+            if (options?.prefetch) {
+                loadMore();
             }
+            setId(id);
+
+            log("Iterator initialised", ref.id);
+            return ref;
         };
 
-        // Reset state when the db or query changes.
         reset(iteratorRef.current);
-
         const newIteratorRef = initIterator();
 
+        /* live-merge listener (optional) */
         let handleChange:
-            | undefined
-            | ((e: CustomEvent<DocumentsChange<T>>) => void | Promise<void>) =
-            undefined;
-        if (options?.onChange && options?.onChange?.merge !== false) {
-            let mergeFunction =
+            | ((e: CustomEvent<DocumentsChange<T>>) => void | Promise<void>)
+            | undefined;
+
+        if (options?.onChange && options.onChange.merge !== false) {
+            const mergeFn =
                 typeof options.onChange.merge === "function"
                     ? options.onChange.merge
-                    : (change: DocumentsChange<T>) => change;
+                    : (c: DocumentsChange<T>) => c;
+
             handleChange = async (e: CustomEvent<DocumentsChange<T>>) => {
-                // while we are iterating, we might get new documents.. so this method inserts them where they should be
-                let filteredChange = await mergeFunction(e.detail);
+                log(
+                    options,
+                    "Merge change",
+                    e.detail,
+                    "iterator",
+                    newIteratorRef.id
+                );
+                const filtered = await mergeFn(e.detail);
                 if (
-                    !filteredChange ||
-                    (filteredChange.added.length === 0 &&
-                        filteredChange.removed.length === 0)
-                ) {
+                    !filtered ||
+                    (filtered.added.length === 0 &&
+                        filtered.removed.length === 0)
+                )
                     return;
-                }
-                let merged: WithContext<RT>[] = [];
+
+                let merged: Item[];
                 if (options.onChange?.update) {
                     merged = [
-                        ...options.onChange.update(
-                            allRef.current,
-                            filteredChange
-                        ),
+                        ...options.onChange?.update(allRef.current, filtered),
                     ];
                 } else {
                     merged = await db.index.updateResults(
-                        allRef.current,
-                        filteredChange,
-                        options?.query || {},
-                        options?.resolve ?? true
+                        allRef.current as WithContext<RT>[],
+                        filtered,
+                        options.query || {},
+                        options.resolve ?? true
                     );
-                    logWithId(options, "After update", allRef.current, merged);
+
+                    log(options, "After update", allRef.current, merged);
                     const expectedDiff =
-                        filteredChange.added.length -
-                        filteredChange.removed.length;
+                        filtered.added.length - filtered.removed.length;
 
                     if (
                         merged === allRef.current ||
@@ -205,23 +210,14 @@ export const useQuery = <
                             merged.length === allRef.current.length)
                     ) {
                         // no change
-                        logWithId(options, "no change after merge");
+                        log(options, "no change after merge");
                         return;
                     }
                 }
 
-                logWithId(options, "handleChange", {
-                    added: e.detail.added.length,
-                    removed: e.detail.removed.length,
-                    merged: merged.length,
-                    allRef: allRef.current.length,
-                });
-
-                updateAll(
-                    options?.reverse ? merged.reverse() : merged,
-                    e.detail
-                );
+                updateAll(options?.reverse ? merged.reverse() : merged);
             };
+
             db.events.addEventListener("change", handleChange);
         }
 
@@ -232,137 +228,162 @@ export const useQuery = <
         };
     }, [
         db?.closed ? undefined : db?.address,
-        options?.id != null ? options?.id : options?.query,
+        options?.id ?? options?.query,
         options?.resolve,
+        options?.reverse,
+        resetCounter,
     ]);
 
-    // Define the loadMore function
+    /* ────────────── loadMore (once-wait aware) ────────────── */
     const batchSize = options?.batchSize ?? 10;
+
+    const shouldWait = (): boolean => {
+        if (waitedOnceRef.current) {
+            return false;
+        }
+        if (options?.remote === false) return false;
+        if (options?.remote === true) return true;
+        if (options?.remote == null) return true;
+        if (typeof options?.remote === "object") {
+            return true;
+        }
+        return true;
+    };
+
+    const reloadAfterTime = (): number | undefined => {
+        if (typeof options?.remote === "object" && options.remote.eager) {
+            return options.remote.warmup ?? db?.log.timeUntilRoleMaturity;
+        }
+        return undefined;
+    };
+
+    const markWaited = () => {
+        waitedOnceRef.current = true;
+    };
+
     const loadMore = async () => {
+        const iterator = iteratorRef.current;
         if (
-            !iteratorRef.current ||
+            !iterator ||
             emptyResultsRef.current ||
-            iteratorRef.current.iterator.done() ||
+            iterator.iterator.done() ||
             loadingMoreRef.current
         ) {
-            logWithId(options, "loadMore: already loading or no more items", {
-                isLoading,
-                emptyResultsRef: emptyResultsRef.current,
-                iteratorRef: !iteratorRef.current,
-            });
-            return;
+            return false;
         }
-        const iterator = iteratorRef.current;
 
         setIsLoading(true);
         loadingMoreRef.current = true;
+
         try {
-            // Fetch next batchSize number of items:
-            logWithId(
-                options,
-                "wait for replicators for iterator " + iterator.id
-            );
-            if (options?.waitForReplicators !== false) {
-                let timeout = 5e3;
-                if (typeof options?.waitForReplicators === "object") {
-                    timeout = options.waitForReplicators.timeout ?? 1e4;
-                }
-                await db?.log
+            /* ── optional replicate-wait ── */
+            if (shouldWait()) {
+                log(options, "Wait for replicators", iterator.id);
+
+                let isEager =
+                    typeof options?.remote === "object" && options.remote.eager;
+                const waitTimeout =
+                    typeof options?.remote === "object" &&
+                    typeof options?.remote.warmup === "number"
+                        ? options?.remote.warmup
+                        : 5_000;
+
+                let shouldResetAfterMaturity =
+                    isEager && !waitedOnceRef.current;
+                let promise = db?.log
                     .waitForReplicators({
-                        timeout,
+                        timeout: waitTimeout,
                         signal: closeControllerRef.current?.signal,
                     })
                     .catch((e) => {
-                        if (e instanceof AbortError) {
-                            // Ignore abort error
+                        if (
+                            e instanceof AbortError ||
+                            e instanceof NoPeersError
+                        )
                             return;
-                        }
                         console.warn("Remote replicators not ready", e);
+                    })
+                    .finally(() => {
+                        markWaited();
+                        if (shouldResetAfterMaturity) {
+                            resetResultsOnReset.current = false; // don't reset results， because we expect to get same or more results
+                            invokeReset();
+                        }
                     });
+                if (!shouldResetAfterMaturity) {
+                    await promise;
+                }
+            } else {
+                log(options, "Skip wait for replicators", iterator.id);
             }
 
-            logWithId(
-                options,
-                "loadMore: loading more items for iterator " +
-                    iteratorRef.current?.id,
-                "should resolve?: " + options?.resolve,
-                "query local?: " + options?.local,
-                "query remote?: " + options?.remote,
-                "isReplicating: " + (await db?.log.isReplicating())
-            );
-
-            let newItems: WithContext<RT>[] = await iterator.iterator.next(
-                batchSize
-            );
-
+            /* ── fetch next batch ── */
+            log(options, "Retrieve next batch", iterator.id);
+            let newItems = await iterator.iterator.next(batchSize);
             if (options?.transform) {
-                newItems = await Promise.all(
-                    newItems.map((item) => options.transform!(item))
-                );
+                log(options, "Transform start", iterator.id);
+
+                newItems = await Promise.all(newItems.map(options.transform));
+                log(options, "Transform end", iterator.id);
             }
 
+            /* iterator might have been reset while we were async… */
+
             if (iteratorRef.current !== iterator) {
-                // If the iterator has changed, we should not update the state
-                // This can happen if the iterator was closed and a new one was created
-                logWithId(options, "Iterator ref changed, not updating state", {
-                    refBefore: iterator.id,
-                    currentRef: iteratorRef.current?.id,
-                    ignoredItems: newItems.length,
-                });
-                return;
+                log(options, "Iterator reset while loading more");
+                return false;
             }
 
-            logWithId(
-                options,
-                "loadMore: loaded more items for iterator " +
-                    iteratorRef.current?.id,
-                "new items length",
-                newItems.length,
-                "all items length",
-                allRef.current.length
-            );
+            iterator.itemsConsumed += newItems.length;
 
             emptyResultsRef.current = newItems.length === 0;
 
-            if (newItems.length > 0) {
-                let prev = allRef.current;
-                let prevHash = new Set(prev.map((x) => x.__context.head));
-                let newItemsNoHash = newItems.filter(
-                    (x) => !prevHash.has(x.__context.head)
+            if (newItems.length) {
+                log(
+                    "Loaded more items for iterator",
+                    iterator.id,
+                    "current id",
+                    iteratorRef.current?.id,
+                    "new items",
+                    newItems.length,
+                    "previous results",
+                    allRef.current.length,
+                    "batchSize",
+                    batchSize,
+                    "items consumed",
+                    iterator.itemsConsumed
                 );
-                if (newItemsNoHash.length === 0) {
-                    logWithId(
-                        options,
-                        "no new items after dedup, not updating state. Prev length",
-                        prev.length
-                    );
-                    return;
-                }
-                const combined = options?.reverse
-                    ? [...newItemsNoHash.reverse(), ...prev]
-                    : [...prev, ...newItemsNoHash];
-                updateAll(combined, null);
-            } else {
-                logWithId(
-                    options,
-                    "no new items, not updating state for iterator " +
-                        iteratorRef.current?.id +
-                        " existing results length",
-                    allRef.current.length
+                const prev = allRef.current;
+                const dedup = new Set(
+                    prev.map((x) => (x as any).__context.head)
                 );
-            }
-        } catch (error) {
-            if (error instanceof ClosedError) {
-                // Handle closed database gracefully
-                logWithId(options, "Database closed error");
+                const unique = newItems.filter(
+                    (x) => !dedup.has((x as any).__context.head)
+                );
+                if (!unique.length) return;
+
+                const combined = reverseRef.current
+                    ? [...unique.reverse(), ...prev]
+                    : [...prev, ...unique];
+                updateAll(combined);
             } else {
-                throw error;
+                log(options, "No new items", iterator.id);
             }
+            return !iterator.iterator.done();
+        } catch (e) {
+            if (!(e instanceof ClosedError)) throw e;
         } finally {
             setIsLoading(false);
             loadingMoreRef.current = false;
         }
     };
 
-    return { items: all, loadMore, isLoading, empty: emptyResultsRef.current };
+    /* ────────────── public API ────────────── */
+    return {
+        items: all,
+        loadMore,
+        isLoading,
+        empty: () => emptyResultsRef.current,
+        id: id,
+    };
 };