@firtoz/collection-sync 4.0.0 → 6.0.0

package/dist/chunk-O3KBDCEI.js

@@ -0,0 +1,615 @@
+import { DEFAULT_PAGE_LIMIT, DEFAULT_SEEK_COOLDOWN_MS } from './chunk-M5MJHS6A.js';
+import { defaultPartialSyncVersionMs, assertSyncUtils, getPartialSyncRowByMapId, tryIdsForIndexWindow, computeFingerprintForIndexWindow } from './chunk-4BEXLBCH.js';
+import { CacheManager } from './chunk-5V6BSQAB.js';
+import { connectPartialSync } from './chunk-XC4QNFSQ.js';
+import { PartialSyncClientBridge } from './chunk-P3JOTUAB.js';
+import { partialSyncRowKey } from './chunk-UJ24XW52.js';
+import { useState, useRef, useCallback, useMemo, useLayoutEffect, useSyncExternalStore, useEffect } from 'react';
+
+function usePartialSyncWindow({
+  collection,
+  sort,
+  getSortValue,
+  wsUrl,
+  wsTransport = "json",
+  serializeJson = JSON.stringify,
+  deserializeJson = JSON.parse,
+  getVersionMs = defaultPartialSyncVersionMs,
+  getSortPositions,
+  pageLimit = DEFAULT_PAGE_LIMIT,
+  seekCooldownMs = DEFAULT_SEEK_COOLDOWN_MS,
+  partialWindowResetKey,
+  mutationBridge,
+  mergeTransportSend,
+  collectionId,
+  cacheDisplayMode = "immediate"
+}) {
+  const [windowStartIndex, setWindowStartIndex] = useState(0);
+  const [totalCount, setTotalCount] = useState(0);
+  const [nextCursor, setNextCursor] = useState(null);
+  const [hasMore, setHasMore] = useState(true);
+  const [rangeRequestInFlight, setRangeRequestInFlight] = useState(false);
+  const [pendingServerRange, setPendingServerRange] = useState(null);
+  const [bridgeState, setBridgeState] = useState({
+    status: "offline"
+  });
+  const [viewportInfo, setViewportInfo] = useState({
+    firstVisibleIndex: 0,
+    lastVisibleIndex: 0
+  });
+  const viewportInfoRef = useRef(viewportInfo);
+  viewportInfoRef.current = viewportInfo;
+  const [lastSeekMeta, setLastSeekMeta] = useState(null);
+  const [collectionVersion, setCollectionVersion] = useState(0);
+  const [indexMapVersion, setIndexMapVersion] = useState(0);
+  const globalIndexMapRef = useRef(/* @__PURE__ */ new Map());
+  const denseRowsRef = useRef([]);
+  const windowStartRef = useRef(windowStartIndex);
+  windowStartRef.current = windowStartIndex;
+  const sortRef = useRef(sort);
+  sortRef.current = sort;
+  const totalCountRef = useRef(totalCount);
+  totalCountRef.current = totalCount;
+  const fetchGenRef = useRef(0);
+  const seekCooldownUntilRef = useRef(0);
+  const seekToViewportRef = useRef(() => {
+  });
+  const invalidateSeekTimerRef = useRef(
+    null
+  );
+  const getSortValueRef = useRef(getSortValue);
+  getSortValueRef.current = getSortValue;
+  const getSortPositionsRef = useRef(getSortPositions);
+  getSortPositionsRef.current = getSortPositions;
+  const getVersionMsRef = useRef(getVersionMs);
+  getVersionMsRef.current = getVersionMs;
+  const serializeJsonRef = useRef(serializeJson);
+  serializeJsonRef.current = serializeJson;
+  const deserializeJsonRef = useRef(deserializeJson);
+  deserializeJsonRef.current = deserializeJson;
+  const bumpIndexMap = useCallback(() => {
+    setIndexMapVersion((v) => v + 1);
+  }, []);
+  const syncUtils = useMemo(
+    () => assertSyncUtils(collection.utils),
+    [collection]
+  );
+  const syncUtilsRef = useRef(syncUtils);
+  syncUtilsRef.current = syncUtils;
+  const collectionRef = useRef(collection);
+  collectionRef.current = collection;
+  const cacheManager = useMemo(
+    () => new CacheManager({
+      getStorageEstimate: async () => {
+        if (typeof navigator === "undefined" || !navigator.storage?.estimate) {
+          const usageBytes2 = 0;
+          const quotaBytes2 = 50 * 1024 * 1024;
+          return {
+            usageBytes: usageBytes2,
+            quotaBytes: quotaBytes2,
+            utilizationRatio: usageBytes2 / quotaBytes2
+          };
+        }
+        const estimate = await navigator.storage.estimate();
+        const usageBytes = estimate.usage ?? 0;
+        const quotaBytes = estimate.quota ?? 1;
+        return {
+          usageBytes,
+          quotaBytes,
+          utilizationRatio: usageBytes / quotaBytes
+        };
+      },
+      deleteRows: async (keys) => {
+        const keySet = /* @__PURE__ */ new Set();
+        for (const k of keys) {
+          keySet.add(k);
+          keySet.add(String(k));
+        }
+        for (const [idx, id] of globalIndexMapRef.current) {
+          if (keySet.has(id) || keySet.has(String(id)) || typeof id === "string" && /^-?\d+$/.test(id) && keySet.has(Number(id))) {
+            globalIndexMapRef.current.delete(idx);
+          }
+        }
+        bumpIndexMap();
+        await syncUtilsRef.current.receiveSync(
+          keys.map((key) => ({ type: "delete", key }))
+        );
+      }
+    }),
+    [bumpIndexMap]
+  );
+  const cacheManagerRef = useRef(cacheManager);
+  cacheManagerRef.current = cacheManager;
+  const partialClientId = mutationBridge?.clientId;
+  const bridge = useMemo(
+    () => new PartialSyncClientBridge({
+      ...partialClientId !== void 0 ? { clientId: partialClientId } : {},
+      ...collectionId !== void 0 ? { collectionId } : {},
+      collection: {
+        get: (key) => getPartialSyncRowByMapId(collectionRef.current, key),
+        utils: {
+          receiveSync: (messages) => syncUtilsRef.current.receiveSync(messages)
+        }
+      },
+      send: () => {
+      },
+      onStateChange: (state) => setBridgeState(state),
+      beforeApplyRows: async (incomingRows) => {
+        const sortNow = sortRef.current;
+        const rowsNow = denseRowsRef.current;
+        const sortPos = getSortPositionsRef.current;
+        const gsv = getSortValueRef.current;
+        const cm = cacheManagerRef.current;
+        cm.recordFetchedRows(
+          incomingRows,
+          (row) => sortPos !== void 0 ? sortPos(row) : {
+            [sortNow.column]: gsv(row, sortNow.column)
+          }
+        );
+        const firstRow = rowsNow[0] ?? incomingRows[0];
+        const lastRow = rowsNow[rowsNow.length - 1] ?? incomingRows[incomingRows.length - 1];
+        const result = await cm.evictIfNeeded({
+          sortColumn: sortNow.column,
+          sortDirection: sortNow.direction,
+          fromValue: firstRow !== void 0 ? gsv(firstRow, sortNow.column) : "",
+          toValue: lastRow !== void 0 ? gsv(lastRow, sortNow.column) : ""
+        });
+        setBridgeState((previous) => {
+          if (previous.status === "partial" || previous.status === "realtime") {
+            return {
+              ...previous,
+              cacheUtilization: result.estimate.utilizationRatio
+            };
+          }
+          return previous;
+        });
+      },
+      onViewTransition: (e) => {
+        if (e.type === "exitView" && e.change.type === "update") {
+          const key = partialSyncRowKey(e.change.value.id);
+          let removed = false;
+          for (const [idx, mappedId] of [
+            ...globalIndexMapRef.current.entries()
+          ]) {
+            if (mappedId === key) {
+              globalIndexMapRef.current.delete(idx);
+              removed = true;
+            }
+          }
+          if (removed) {
+            bumpIndexMap();
+          }
+        }
+      },
+      onRangePatchApplied: ({
+        change,
+        viewTransition
+      }) => {
+        if (change.type !== "update" || viewTransition !== void 0) {
+          return;
+        }
+        if (change.previousValue === void 0) return;
+        const col = sortRef.current.column;
+        const gsv = getSortValueRef.current;
+        if (gsv(change.previousValue, col) === gsv(change.value, col)) {
+          return;
+        }
+        const rowKey = partialSyncRowKey(change.value.id);
+        const inDense = denseRowsRef.current.some(
+          (r) => partialSyncRowKey(r.id) === rowKey
+        );
+        if (!inDense) return;
+        if (invalidateSeekTimerRef.current !== null) {
+          clearTimeout(invalidateSeekTimerRef.current);
+        }
+        invalidateSeekTimerRef.current = setTimeout(() => {
+          invalidateSeekTimerRef.current = null;
+          seekToViewportRef.current(
+            viewportInfoRef.current.firstVisibleIndex,
+            {
+              force: true
+            }
+          );
+        }, 80);
+      }
+    }),
+    [partialClientId, collectionId, bumpIndexMap]
+  );
+  const mutationBridgeRef = useRef(mutationBridge);
+  mutationBridgeRef.current = mutationBridge;
+  const mergeTransportSendRef = useRef(mergeTransportSend);
+  mergeTransportSendRef.current = mergeTransportSend;
+  useLayoutEffect(() => {
+    const disconnect = connectPartialSync(bridge, {
+      url: wsUrl,
+      transport: wsTransport,
+      setTransportSend: (send) => {
+        bridge.setSend((message) => send(message));
+        mergeTransportSendRef.current?.(send);
+      },
+      serializeJson: (value) => serializeJsonRef.current(value),
+      deserializeJson: (raw) => deserializeJsonRef.current(raw),
+      mutationBridge: mutationBridgeRef.current
+    });
+    return () => {
+      disconnect();
+    };
+  }, [bridge, wsTransport, wsUrl]);
+  const confirmedKeysRevision = useSyncExternalStore(
+    (onStoreChange) => bridge.subscribeConfirmedKeysRevision(onStoreChange),
+    () => bridge.serverConfirmedKeysRevision,
+    () => 0
+  );
+  const indexRows = useMemo(() => {
+    const start = windowStartIndex;
+    const out = [];
+    for (let i = 0; ; i += 1) {
+      const id = globalIndexMapRef.current.get(start + i);
+      if (id === void 0) break;
+      const row = getPartialSyncRowByMapId(collection, id);
+      if (row === void 0) continue;
+      out.push(row);
+    }
+    if (cacheDisplayMode === "confirmed") {
+      return out.filter(
+        (row) => bridge.serverConfirmedKeys.has(partialSyncRowKey(row.id))
+      );
+    }
+    return out;
+  }, [
+    bridge,
+    cacheDisplayMode,
+    collection,
+    collectionVersion,
+    confirmedKeysRevision,
+    indexMapVersion,
+    windowStartIndex
+  ]);
+  const rows = indexRows;
+  useLayoutEffect(() => {
+    denseRowsRef.current = rows;
+  }, [rows]);
+  const getRowSlot = useCallback(
+    (globalIndex) => {
+      const id = globalIndexMapRef.current.get(globalIndex);
+      const row = id !== void 0 ? getPartialSyncRowByMapId(collection, id) : void 0;
+      if (row !== void 0) {
+        const ws = windowStartIndex;
+        const denseEnd = ws + rows.length;
+        const inDense = globalIndex >= ws && globalIndex < denseEnd;
+        return {
+          row,
+          slot: inDense ? "ready" : "ready_global"
+        };
+      }
+      if (id !== void 0) {
+        return { row: void 0, slot: "stale_map" };
+      }
+      if (rangeRequestInFlight && pendingServerRange !== null && globalIndex >= pendingServerRange.start && globalIndex < pendingServerRange.endExclusive) {
+        return { row: void 0, slot: "server" };
+      }
+      return { row: void 0, slot: "none" };
+    },
+    [
+      collection,
+      collectionVersion,
+      indexMapVersion,
+      windowStartIndex,
+      rows.length,
+      rangeRequestInFlight,
+      pendingServerRange
+    ]
+  );
+  const recordIdsAtOffset = useCallback(
+    (offset, fetchedRows) => {
+      for (let i = 0; i < fetchedRows.length; i += 1) {
+        globalIndexMapRef.current.set(
+          offset + i,
+          partialSyncRowKey(fetchedRows[i].id)
+        );
+      }
+      bumpIndexMap();
+    },
+    [bumpIndexMap]
+  );
+  const fetchNext = useCallback(async () => {
+    if (rangeRequestInFlight || !hasMore) return;
+    const gen = fetchGenRef.current;
+    const fetchStart = windowStartRef.current + denseRowsRef.current.length;
+    setPendingServerRange({
+      start: fetchStart,
+      endExclusive: fetchStart + pageLimit
+    });
+    setRangeRequestInFlight(true);
+    try {
+      const result = await bridge.requestRangeQuery({
+        kind: "index",
+        mode: "cursor",
+        sort: sortRef.current,
+        limit: pageLimit,
+        afterCursor: nextCursor
+      });
+      if (gen !== fetchGenRef.current) return;
+      if (result.invalidateWindow && result.rows.length === 0) {
+        const again = await bridge.requestRangeQuery({
+          kind: "index",
+          mode: "cursor",
+          sort: sortRef.current,
+          limit: pageLimit,
+          afterCursor: nextCursor
+        });
+        if (gen !== fetchGenRef.current) return;
+        recordIdsAtOffset(
+          windowStartRef.current + denseRowsRef.current.length,
+          again.rows
+        );
+        setTotalCount(again.totalCount);
+        setNextCursor(again.lastCursor);
+        setHasMore(again.rows.length === pageLimit);
+        return;
+      }
+      if (result.upToDate) {
+        setTotalCount(result.totalCount);
+        return;
+      }
+      recordIdsAtOffset(
+        windowStartRef.current + denseRowsRef.current.length,
+        result.rows
+      );
+      setTotalCount(result.totalCount);
+      setNextCursor(result.lastCursor);
+      setHasMore(result.rows.length === pageLimit);
+    } catch (error) {
+      if (error !== null && typeof error === "object" && "name" in error && error.name === "AbortError") {
+        return;
+      }
+      throw error;
+    } finally {
+      if (gen === fetchGenRef.current) {
+        setPendingServerRange(null);
+        setRangeRequestInFlight(false);
+      }
+    }
+  }, [
+    bridge,
+    hasMore,
+    rangeRequestInFlight,
+    nextCursor,
+    pageLimit,
+    recordIdsAtOffset
+  ]);
+  const seekToViewport = useCallback(
+    (firstVisibleIndex, options) => {
+      const offset = Math.max(0, firstVisibleIndex);
+      const loadedEndExclusive = windowStartRef.current + denseRowsRef.current.length;
+      const lastForDense = options?.scrollSettled === true && typeof options.lastVisibleIndex === "number" ? options.lastVisibleIndex : firstVisibleIndex;
+      const inDenseWindow = denseRowsRef.current.length > 0 && firstVisibleIndex >= windowStartRef.current && lastForDense < loadedEndExclusive;
+      if (options?.scrollSettled === true && inDenseWindow && !options?.force) {
+        return;
+      }
+      const now = Date.now();
+      if (!options?.force && now < seekCooldownUntilRef.current) {
+        return;
+      }
+      if (!options?.scrollSettled) {
+        const ws = windowStartRef.current;
+        const f = firstVisibleIndex;
+        const firstInsideDense = denseRowsRef.current.length > 0 && f >= ws && f < loadedEndExclusive;
+        if (firstInsideDense && !options?.force) return;
+      }
+      seekCooldownUntilRef.current = now + seekCooldownMs;
+      setLastSeekMeta({
+        offset,
+        reason: options?.scrollSettled === true ? "scrollSettled" : "scroll"
+      });
+      fetchGenRef.current += 1;
+      const gen = fetchGenRef.current;
+      bridge.abortRangeRequests();
+      const want = Math.min(
+        pageLimit,
+        Math.max(0, totalCountRef.current - offset)
+      );
+      if (totalCountRef.current > 0 && want === 0) {
+        setWindowStartIndex(offset);
+        windowStartRef.current = offset;
+        setNextCursor(null);
+        setHasMore(false);
+        setPendingServerRange(null);
+        setRangeRequestInFlight(false);
+        return;
+      }
+      const ids = tryIdsForIndexWindow(
+        globalIndexMapRef.current,
+        offset,
+        want,
+        totalCountRef.current
+      );
+      if (ids !== null) {
+        setWindowStartIndex(offset);
+        const lastId = ids[ids.length - 1];
+        const gsv = getSortValueRef.current;
+        const lastRow = lastId !== void 0 ? getPartialSyncRowByMapId(collection, lastId) : void 0;
+        setNextCursor(
+          lastRow !== void 0 ? gsv(lastRow, sortRef.current.column) : null
+        );
+        setHasMore(offset + ids.length < totalCountRef.current);
+        setPendingServerRange(null);
+        bumpIndexMap();
+        windowStartRef.current = offset;
+        return;
+      }
+      let fingerprint;
+      if (totalCountRef.current > 0 && want > 0) {
+        const fp = computeFingerprintForIndexWindow(
+          collection,
+          globalIndexMapRef.current,
+          offset,
+          want,
+          (row) => getVersionMsRef.current(row)
+        );
+        if (fp !== void 0) {
+          fingerprint = fp;
+        }
+      }
+      setWindowStartIndex(offset);
+      windowStartRef.current = offset;
+      setNextCursor(null);
+      setHasMore(true);
+      setPendingServerRange({ start: offset, endExclusive: offset + want });
+      setRangeRequestInFlight(true);
+      void (async () => {
+        try {
+          let result = await bridge.requestRangeQuery(
+            {
+              kind: "index",
+              mode: "offset",
+              sort: sortRef.current,
+              limit: pageLimit,
+              offset
+            },
+            fingerprint
+          );
+          if (gen !== fetchGenRef.current) return;
+          if (result.upToDate) {
+            setTotalCount(result.totalCount);
+            setHasMore(offset + pageLimit < result.totalCount);
+            const gsv = getSortValueRef.current;
+            const lastId = globalIndexMapRef.current.get(offset + want - 1) ?? globalIndexMapRef.current.get(offset + pageLimit - 1);
+            const lastRow = lastId !== void 0 ? getPartialSyncRowByMapId(collection, lastId) : void 0;
+            setNextCursor(
+              lastRow !== void 0 ? gsv(lastRow, sortRef.current.column) : null
+            );
+            return;
+          }
+          if (result.invalidateWindow && result.rows.length === 0) {
+            result = await bridge.requestRangeQuery({
+              kind: "index",
+              mode: "offset",
+              sort: sortRef.current,
+              limit: pageLimit,
+              offset
+            });
+            if (gen !== fetchGenRef.current) return;
+          }
+          recordIdsAtOffset(offset, result.rows);
+          setTotalCount(result.totalCount);
+          setNextCursor(result.lastCursor);
+          setHasMore(result.rows.length === pageLimit);
+        } catch (error) {
+          if (error !== null && typeof error === "object" && "name" in error && error.name === "AbortError") {
+            return;
+          }
+          throw error;
+        } finally {
+          if (gen === fetchGenRef.current) {
+            setPendingServerRange(null);
+            setRangeRequestInFlight(false);
+          }
+        }
+      })();
+    },
+    [
+      bridge,
+      bumpIndexMap,
+      collection,
+      pageLimit,
+      recordIdsAtOffset,
+      seekCooldownMs
+    ]
+  );
+  seekToViewportRef.current = seekToViewport;
+  useEffect(() => {
+    return () => {
+      if (invalidateSeekTimerRef.current !== null) {
+        clearTimeout(invalidateSeekTimerRef.current);
+      }
+    };
+  }, []);
+  useEffect(() => {
+    const sub = collection.subscribeChanges(() => {
+      let removedStaleMapEntry = false;
+      if (globalIndexMapRef.current.size > 0) {
+        for (const [idx, id] of globalIndexMapRef.current) {
+          if (getPartialSyncRowByMapId(collection, id) === void 0) {
+            globalIndexMapRef.current.delete(idx);
+            removedStaleMapEntry = true;
+          }
+        }
+      }
+      if (removedStaleMapEntry) {
+        bumpIndexMap();
+      }
+      setCollectionVersion((v) => v + 1);
+      const sortNow = sortRef.current;
+      const sortPos = getSortPositionsRef.current;
+      const gsv = getSortValueRef.current;
+      cacheManagerRef.current.resyncSortPositionsForTrackedRows(
+        (key) => getPartialSyncRowByMapId(collection, key),
+        (row) => sortPos !== void 0 ? sortPos(row) : {
+          [sortNow.column]: gsv(row, sortNow.column)
+        }
+      );
+    });
+    return () => {
+      sub.unsubscribe();
+    };
+  }, [bumpIndexMap, collection]);
+  const seekAfterScrollSettled = useCallback(
+    (firstVisibleIndex, lastVisibleIndex) => {
+      seekToViewport(firstVisibleIndex, {
+        scrollSettled: true,
+        lastVisibleIndex
+      });
+    },
+    [seekToViewport]
+  );
+  useEffect(() => {
+    fetchGenRef.current += 1;
+    bridge.abortRangeRequests();
+    bridge.clearTrackedRowIds();
+    setWindowStartIndex(0);
+    setTotalCount(0);
+    setNextCursor(null);
+    setHasMore(true);
+    setLastSeekMeta(null);
+    setRangeRequestInFlight(false);
+    setPendingServerRange(null);
+    globalIndexMapRef.current.clear();
+    bumpIndexMap();
+    void syncUtilsRef.current.truncate();
+    cacheManager.clear();
+  }, [
+    bridge,
+    bumpIndexMap,
+    cacheManager,
+    sort.column,
+    sort.direction,
+    partialWindowResetKey ?? ""
+  ]);
+  useEffect(() => {
+    if (rows.length === 0 && !rangeRequestInFlight && hasMore) {
+      void fetchNext();
+    }
+  }, [fetchNext, hasMore, rangeRequestInFlight, rows.length]);
+  return {
+    bridge,
+    cacheManager,
+    rows,
+    windowStartIndex,
+    totalCount,
+    rangeRequestInFlight,
+    hasMore,
+    fetchNext,
+    seekToViewport,
+    seekAfterScrollSettled,
+    bridgeState,
+    viewportInfo,
+    setViewportInfo,
+    lastSeekMeta,
+    getRowSlot
+  };
+}
+
+export { usePartialSyncWindow };
+//# sourceMappingURL=chunk-O3KBDCEI.js.map
+//# sourceMappingURL=chunk-O3KBDCEI.js.map