@fitzzero/quickdraw-core 3.9.1 → 4.0.0

package/dist/client/index.js

@@ -140,7 +140,8 @@ function QuickdrawProvider({
   authToken,
   autoConnect = !!authToken,
   withCredentials = true,
-  socketPath
+  socketPath,
+  reconnectBehavior = "invalidate-queries"
 }) {
   const [defaultQueryClient] = React.useState(() => createQueryClient());
   const actualQueryClient = queryClient ?? defaultQueryClient;
@@ -148,12 +149,38 @@ function QuickdrawProvider({
   const [isConnected, setIsConnected] = React.useState(false);
   const [userId, setUserId] = React.useState(null);
   const [serviceAccess, setServiceAccess] = React.useState({});
+  const [isRateLimited, setIsRateLimited] = React.useState(false);
   const subscriptionRegistryRef = React.useRef(createSubscriptionRegistry());
   const prevAuthTokenRef = React.useRef(authToken);
   const socketRef = React.useRef(null);
   const subscriptionBatcherRef = React.useRef(
     createSubscriptionBatcher(socketRef)
   );
+  const hasEverConnectedRef = React.useRef(false);
+  const reconnectBehaviorRef = React.useRef(reconnectBehavior);
+  reconnectBehaviorRef.current = reconnectBehavior;
+  const queryClientRef = React.useRef(actualQueryClient);
+  queryClientRef.current = actualQueryClient;
+  const rateLimitUntilRef = React.useRef(0);
+  const rateLimitTimerRef = React.useRef(null);
+  const reportRateLimited = React.useCallback((retryAfterMs) => {
+    const backoffMs = Math.min(Math.max(retryAfterMs ?? 5e3, 250), 5 * 60 * 1e3);
+    const until = Date.now() + backoffMs;
+    if (until <= rateLimitUntilRef.current) return;
+    rateLimitUntilRef.current = until;
+    setIsRateLimited(true);
+    if (rateLimitTimerRef.current) clearTimeout(rateLimitTimerRef.current);
+    rateLimitTimerRef.current = setTimeout(() => {
+      rateLimitTimerRef.current = null;
+      rateLimitUntilRef.current = 0;
+      setIsRateLimited(false);
+    }, backoffMs);
+  }, []);
+  React.useEffect(() => {
+    return () => {
+      if (rateLimitTimerRef.current) clearTimeout(rateLimitTimerRef.current);
+    };
+  }, []);
   const connect = React.useCallback(
     (token) => {
       if (socketRef.current) return;
@@ -169,6 +196,10 @@ function QuickdrawProvider({
       });
       newSocket.on("connect", () => {
         setIsConnected(true);
+        if (hasEverConnectedRef.current && reconnectBehaviorRef.current === "invalidate-queries") {
+          void queryClientRef.current.invalidateQueries();
+        }
+        hasEverConnectedRef.current = true;
       });
       newSocket.on("disconnect", () => {
         setIsConnected(false);
@@ -178,16 +209,21 @@ function QuickdrawProvider({
         "auth:info",
         (info) => {
           setUserId(info.userId);
-          setServiceAccess(info.serviceAccess);
+          setServiceAccess(info.serviceAccess ?? {});
         }
       );
+      newSocket.on("error", (payload) => {
+        if (payload && payload.code === "RATE_LIMITED") {
+          reportRateLimited(payload.retryAfter);
+        }
+      });
       newSocket.on("connect_error", (error) => {
         console.error("Socket connection error:", error.message);
       });
       socketRef.current = newSocket;
       setSocket(newSocket);
     },
-    [serverUrl, withCredentials, socketPath]
+    [serverUrl, withCredentials, socketPath, reportRateLimited]
   );
   const disconnect = React.useCallback(() => {
     if (socketRef.current) {
@@ -233,9 +269,20 @@ function QuickdrawProvider({
       connect,
       disconnect,
       subscriptionRegistry: subscriptionRegistryRef.current,
-      subscriptionBatcher: subscriptionBatcherRef.current
+      subscriptionBatcher: subscriptionBatcherRef.current,
+      isRateLimited,
+      reportRateLimited
     }),
-    [socket, isConnected, userId, serviceAccess, connect, disconnect]
+    [
+      socket,
+      isConnected,
+      userId,
+      serviceAccess,
+      connect,
+      disconnect,
+      isRateLimited,
+      reportRateLimited
+    ]
   );
   return /* @__PURE__ */ jsx(QueryClientProvider, { client: actualQueryClient, children: /* @__PURE__ */ jsx(QuickdrawSocketContext.Provider, { value: contextValue, children }) });
 }
@@ -357,8 +404,20 @@ function useServiceMethod(serviceName, methodName, options) {
     [execute, loading, error, data, socket, isConnected]
   );
 }
+
+// src/client/serviceError.ts
+var ServiceCallError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "ServiceCallError";
+    this.code = code;
+  }
+};
+
+// src/client/useServiceQuery.ts
 function useServiceQuery(serviceName, methodName, payload, options) {
-  const { socket, isConnected } = useQuickdrawSocket();
+  const { socket, isConnected, isRateLimited, reportRateLimited } = useQuickdrawSocket();
   const queryClient = useQueryClient();
   const [error, setError] = React.useState(null);
   const optionsRef = React.useRef(options);
@@ -377,7 +436,9 @@ function useServiceQuery(serviceName, methodName, payload, options) {
     timeout = 1e4,
     retry = 1,
     retryDelay,
-    invalidateOn
+    invalidateOn,
+    refetchInterval,
+    refetchIntervalInBackground
   } = options ?? {};
   const queryKey = React.useMemo(
     () => [serviceName, methodName, JSON.stringify(payload)],
@@ -397,11 +458,14 @@ function useServiceQuery(serviceName, methodName, payload, options) {
         if (response.success) {
           resolve(response.data);
         } else {
-          reject(new Error(response.error));
+          if (response.code === 429) {
+            reportRateLimited();
+          }
+          reject(new ServiceCallError(response.error, response.code));
         }
       });
     });
-  }, [socket, isConnected, serviceName, methodName, payload, timeout]);
+  }, [socket, isConnected, serviceName, methodName, payload, timeout, reportRateLimited]);
   React.useEffect(() => {
     if (skipCache && enabled) {
       queryClient.invalidateQueries({ queryKey });
@@ -438,13 +502,17 @@ function useServiceQuery(serviceName, methodName, payload, options) {
   const query = useQuery({
     queryKey,
     queryFn,
-    enabled: enabled && !!socket && isConnected,
+    // Reads pause while the server reports us rate-limited; they resume
+    // (and refetch as needed) when the backoff window elapses.
+    enabled: enabled && !!socket && isConnected && !isRateLimited,
     staleTime,
     gcTime,
     refetchOnMount,
     refetchOnWindowFocus,
     retry,
-    retryDelay
+    retryDelay,
+    refetchInterval,
+    refetchIntervalInBackground
   });
   React.useEffect(() => {
     if (query.isSuccess && query.data !== void 0) {
@@ -633,6 +701,406 @@ function useSubscription(serviceName, entryId, options = {}) {
     unsubscribe
   };
 }
+
+// src/shared/types.ts
+function channelEventName(serviceName, channelName) {
+  return `channel:${serviceName}:${channelName}`;
+}
+function collectionRoom(serviceName, collection, scopeId) {
+  return `${serviceName}:collection:${collection}:${scopeId}`;
+}
+
+// src/client/collectionCache.ts
+function createEmptyEntry() {
+  return {
+    byId: {},
+    order: [],
+    revById: {},
+    nextCursor: null,
+    totalCount: null,
+    snapshotRev: 0
+  };
+}
+function applySnapshot(prev, snapshot) {
+  const base = prev ?? createEmptyEntry();
+  const pageIds = new Set(snapshot.items.map((item) => item.id));
+  const memberIds = snapshot.ids ? new Set(snapshot.ids) : null;
+  const byId = {};
+  const revById = {};
+  for (const id of base.order) {
+    const item = base.byId[id];
+    if (!item) continue;
+    const rev = base.revById[id] ?? 0;
+    const liveWins = rev > snapshot.rev;
+    const pruned = memberIds !== null && !memberIds.has(id) && !pageIds.has(id) && !liveWins;
+    if (pruned) continue;
+    byId[id] = item;
+    revById[id] = rev;
+  }
+  for (const item of snapshot.items) {
+    const cachedRev = revById[item.id];
+    if (cachedRev !== void 0 && cachedRev > snapshot.rev) continue;
+    const tombstoneRev = base.revById[item.id];
+    if (base.byId[item.id] === void 0 && tombstoneRev !== void 0 && tombstoneRev > snapshot.rev) {
+      continue;
+    }
+    byId[item.id] = item;
+    revById[item.id] = snapshot.rev;
+  }
+  for (const [id, rev] of Object.entries(base.revById)) {
+    if (byId[id] === void 0 && rev > snapshot.rev) {
+      revById[id] = rev;
+    }
+  }
+  const order = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of snapshot.items) {
+    if (byId[item.id] !== void 0 && !seen.has(item.id)) {
+      order.push(item.id);
+      seen.add(item.id);
+    }
+  }
+  for (const id of base.order) {
+    if (byId[id] !== void 0 && !seen.has(id)) {
+      order.push(id);
+      seen.add(id);
+    }
+  }
+  return {
+    byId,
+    order,
+    revById,
+    nextCursor: snapshot.nextCursor,
+    totalCount: snapshot.totalCount,
+    snapshotRev: snapshot.rev
+  };
+}
+function applyPage(prev, page) {
+  const base = prev ?? createEmptyEntry();
+  const byId = { ...base.byId };
+  const revById = { ...base.revById };
+  const order = [...base.order];
+  const known = new Set(order);
+  for (const item of page.items) {
+    const cachedRev = revById[item.id];
+    if (cachedRev !== void 0 && cachedRev > page.rev) {
+      continue;
+    }
+    byId[item.id] = item;
+    revById[item.id] = page.rev;
+    if (!known.has(item.id)) {
+      order.push(item.id);
+      known.add(item.id);
+    }
+  }
+  return {
+    byId,
+    order,
+    revById,
+    nextCursor: page.nextCursor,
+    totalCount: page.totalCount,
+    snapshotRev: base.snapshotRev
+  };
+}
+function applyDelta(prev, delta, options) {
+  const base = prev ?? createEmptyEntry();
+  if (delta.type === "reset") {
+    return { entry: base, resetRequested: true };
+  }
+  if (delta.type === "removed") {
+    const cachedRev2 = base.revById[delta.id];
+    if (cachedRev2 !== void 0 && delta.rev < cachedRev2) {
+      return { entry: base, resetRequested: false };
+    }
+    const existed = base.byId[delta.id] !== void 0;
+    const byId = { ...base.byId };
+    delete byId[delta.id];
+    return {
+      entry: {
+        ...base,
+        byId,
+        order: existed ? base.order.filter((id) => id !== delta.id) : base.order,
+        // Tombstone: keep the removal rev so a stale `added` can't resurrect
+        revById: { ...base.revById, [delta.id]: delta.rev },
+        totalCount: existed && base.totalCount !== null ? Math.max(0, base.totalCount - 1) : base.totalCount
+      },
+      resetRequested: false
+    };
+  }
+  const { item, rev } = delta;
+  const cachedRev = base.revById[item.id];
+  if (cachedRev !== void 0 && rev < cachedRev) {
+    return { entry: base, resetRequested: false };
+  }
+  const isNew = base.byId[item.id] === void 0;
+  const insertPosition = options?.insertPosition ?? "end";
+  return {
+    entry: {
+      ...base,
+      byId: { ...base.byId, [item.id]: item },
+      order: isNew ? insertPosition === "start" ? [item.id, ...base.order] : [...base.order, item.id] : base.order,
+      revById: { ...base.revById, [item.id]: rev },
+      totalCount: isNew && base.totalCount !== null ? base.totalCount + 1 : base.totalCount
+    },
+    resetRequested: false
+  };
+}
+function applyDeltas(prev, deltas, options) {
+  let entry = prev ?? createEmptyEntry();
+  let resetRequested = false;
+  for (const delta of deltas) {
+    const result = applyDelta(entry, delta, options);
+    entry = result.entry;
+    resetRequested = resetRequested || result.resetRequested;
+  }
+  return { entry, resetRequested };
+}
+
+// src/client/useCollection.ts
+var RESET_DEBOUNCE_MS = 100;
+var REQUEST_TIMEOUT_MS = 1e4;
+var EMPTY_STATE = { entry: null, error: null };
+function useCollection(serviceName, collection, scopeId, options) {
+  const { socket, isConnected, subscriptionRegistry } = useQuickdrawSocket();
+  const queryClient = useQueryClient();
+  const [isLoadingMore, setIsLoadingMore] = React.useState(false);
+  const {
+    enabled = true,
+    limit,
+    compare,
+    insertPosition = "end",
+    onDelta,
+    onError
+  } = options ?? {};
+  const onDeltaRef = React.useRef(onDelta);
+  const onErrorRef = React.useRef(onError);
+  const insertPositionRef = React.useRef(insertPosition);
+  React.useEffect(() => {
+    onDeltaRef.current = onDelta;
+    onErrorRef.current = onError;
+    insertPositionRef.current = insertPosition;
+  }, [onDelta, onError, insertPosition]);
+  const subscriptionKey = scopeId ? collectionRoom(serviceName, collection, scopeId) : null;
+  const queryKey = React.useMemo(
+    () => [serviceName, "collection", collection, scopeId],
+    [serviceName, collection, scopeId]
+  );
+  const query = useQuery({
+    queryKey,
+    queryFn: () => queryClient.getQueryData(queryKey) ?? EMPTY_STATE,
+    initialData: () => EMPTY_STATE,
+    staleTime: Infinity,
+    refetchOnMount: false,
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: false
+  });
+  const regEntryRef = React.useRef(null);
+  React.useEffect(() => {
+    if (!socket || !isConnected || !enabled || !subscriptionKey || !scopeId) {
+      return;
+    }
+    const { isNew, entry: regEntry } = subscriptionRegistry.acquire(subscriptionKey);
+    regEntryRef.current = regEntry;
+    if (!isNew) {
+      return () => {
+        regEntryRef.current = null;
+        subscriptionRegistry.release(subscriptionKey);
+      };
+    }
+    const eventName = subscriptionKey;
+    let disposed = false;
+    let snapshotInFlight = false;
+    let buffered = [];
+    let inFlightSnapshot = null;
+    let inFlightLoadMore = null;
+    let resetTimer = null;
+    const readState = () => queryClient.getQueryData(queryKey) ?? EMPTY_STATE;
+    const writeState = (state2) => {
+      queryClient.setQueryData(queryKey, state2);
+    };
+    const emitSubscribe = (cursor) => new Promise((resolve) => {
+      let settled = false;
+      const timeoutId = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          resolve({ success: false, error: "Request timeout" });
+        }
+      }, REQUEST_TIMEOUT_MS);
+      socket.emit(
+        `${serviceName}:collection:subscribe`,
+        {
+          collection,
+          scopeId,
+          ...cursor === null ? {} : { cursor },
+          ...limit === void 0 ? {} : { limit }
+        },
+        (response) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeoutId);
+          resolve(response);
+        }
+      );
+    });
+    const scheduleReset = () => {
+      if (resetTimer || disposed) return;
+      resetTimer = setTimeout(() => {
+        resetTimer = null;
+        void requestSnapshot();
+      }, RESET_DEBOUNCE_MS);
+    };
+    const requestSnapshot = () => {
+      if (inFlightSnapshot) return inFlightSnapshot;
+      snapshotInFlight = true;
+      buffered = [];
+      inFlightSnapshot = emitSubscribe(null).then((response) => {
+        snapshotInFlight = false;
+        inFlightSnapshot = null;
+        const raced = buffered;
+        buffered = [];
+        if (disposed) return;
+        if (response.success) {
+          const prev = readState();
+          const fresh = applySnapshot(prev.entry, response.data);
+          const { entry: entry2, resetRequested } = applyDeltas(fresh, raced, {
+            insertPosition: insertPositionRef.current
+          });
+          writeState({ entry: entry2, error: null });
+          if (resetRequested) scheduleReset();
+        } else {
+          const prev = readState();
+          writeState({ entry: prev.entry, error: response.error });
+        }
+      });
+      return inFlightSnapshot;
+    };
+    const loadMore2 = () => {
+      if (inFlightLoadMore) return inFlightLoadMore;
+      const cursor = readState().entry?.nextCursor ?? null;
+      if (cursor === null) return Promise.resolve();
+      inFlightLoadMore = emitSubscribe(cursor).then((response) => {
+        inFlightLoadMore = null;
+        if (disposed) return;
+        const prev = readState();
+        if (response.success) {
+          writeState({ entry: applyPage(prev.entry, response.data), error: prev.error });
+        } else {
+          writeState({ entry: prev.entry, error: response.error });
+        }
+      });
+      return inFlightLoadMore;
+    };
+    const handleDelta = (delta) => {
+      if (delta.type === "reset") {
+        scheduleReset();
+        return;
+      }
+      if (snapshotInFlight) {
+        buffered.push(delta);
+        return;
+      }
+      const prev = readState();
+      const { entry: entry2 } = applyDelta(prev.entry, delta, {
+        insertPosition: insertPositionRef.current
+      });
+      if (entry2 !== prev.entry) {
+        writeState({ entry: entry2, error: prev.error });
+      }
+    };
+    const controller = { requestSnapshot, loadMore: loadMore2 };
+    regEntry.controller = controller;
+    socket.on(eventName, handleDelta);
+    void requestSnapshot();
+    subscriptionRegistry.setCleanup(subscriptionKey, () => {
+      disposed = true;
+      if (resetTimer) clearTimeout(resetTimer);
+      socket.off(eventName, handleDelta);
+      socket.emit(`${serviceName}:collection:unsubscribe`, { collection, scopeId });
+      regEntry.controller = void 0;
+    });
+    return () => {
+      regEntryRef.current = null;
+      subscriptionRegistry.release(subscriptionKey);
+    };
+  }, [
+    socket,
+    isConnected,
+    enabled,
+    subscriptionKey,
+    scopeId,
+    serviceName,
+    collection,
+    limit,
+    queryClient,
+    queryKey,
+    subscriptionRegistry
+  ]);
+  const wantsDelta = !!onDelta;
+  React.useEffect(() => {
+    if (!socket || !isConnected || !enabled || !subscriptionKey || !wantsDelta) {
+      return;
+    }
+    const listener = (delta) => {
+      onDeltaRef.current?.(delta);
+    };
+    socket.on(subscriptionKey, listener);
+    return () => {
+      socket.off(subscriptionKey, listener);
+    };
+  }, [socket, isConnected, enabled, subscriptionKey, wantsDelta]);
+  const state = query.data ?? EMPTY_STATE;
+  const entry = state.entry;
+  React.useEffect(() => {
+    if (state.error) {
+      onErrorRef.current?.(state.error);
+    }
+  }, [state.error]);
+  const getController = () => regEntryRef.current?.controller ?? null;
+  const getControllerRef = React.useRef(getController);
+  getControllerRef.current = getController;
+  const refresh = React.useCallback(async () => {
+    await getControllerRef.current()?.requestSnapshot();
+  }, []);
+  const loadMore = React.useCallback(async () => {
+    const controller = getControllerRef.current();
+    if (!controller) return;
+    setIsLoadingMore(true);
+    try {
+      await controller.loadMore();
+    } finally {
+      setIsLoadingMore(false);
+    }
+  }, []);
+  const items = React.useMemo(() => {
+    if (!entry) return [];
+    const list = entry.order.map((id) => entry.byId[id]).filter((item) => item !== void 0);
+    if (compare) list.sort(compare);
+    return list;
+  }, [entry, compare]);
+  const byId = React.useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    if (entry) {
+      for (const id of entry.order) {
+        const item = entry.byId[id];
+        if (item !== void 0) map.set(id, item);
+      }
+    }
+    return map;
+  }, [entry]);
+  const active = enabled && !!scopeId;
+  return {
+    items,
+    byId,
+    totalCount: entry?.totalCount ?? null,
+    isLoading: active && !entry && !state.error,
+    isError: state.error !== null,
+    error: state.error,
+    hasMore: (entry?.nextCursor ?? null) !== null,
+    isLoadingMore,
+    loadMore,
+    refresh
+  };
+}
 function useRoomEvents(handlers, options) {
   const { socket, isConnected } = useQuickdrawSocket();
   const { enabled = true } = options ?? {};
@@ -640,7 +1108,7 @@ function useRoomEvents(handlers, options) {
   React.useEffect(() => {
     handlersRef.current = handlers;
   }, [handlers]);
-  const eventNames = Object.keys(handlers);
+  const eventNames = Object.keys(handlers).filter((name) => handlers[name] != null);
   const eventNamesKey = eventNames.join("\0");
   const stableEventNames = React.useMemo(
     () => eventNames,
@@ -666,13 +1134,6 @@ function useRoomEvents(handlers, options) {
     };
   }, [socket, isConnected, enabled, stableEventNames]);
 }
-
-// src/shared/types.ts
-function channelEventName(serviceName, channelName) {
-  return `channel:${serviceName}:${channelName}`;
-}
-
-// src/client/useChannelSend.ts
 function useChannelSend(serviceName, channelName) {
   const { socket, isConnected } = useQuickdrawSocket();
   const eventName = channelEventName(serviceName, channelName);
@@ -835,6 +1296,8 @@ function SocketTextField(props) {
     onSuccess,
     onError,
     disabled,
+    type = "text",
+    onBlur: consumerOnBlur,
     ...inputProps
   } = props;
   const defaultFormat = React.useCallback((v) => String(v ?? ""), []);
@@ -856,14 +1319,21 @@ function SocketTextField(props) {
     },
     [onLocalChange]
   );
+  const handleBlur = React.useCallback(
+    (event) => {
+      onBlur();
+      consumerOnBlur?.(event);
+    },
+    [onBlur, consumerOnBlur]
+  );
   return /* @__PURE__ */ jsx(
     "input",
     {
       ...inputProps,
-      type: "text",
+      type,
       value: String(value),
       onChange: handleChange,
-      onBlur,
+      onBlur: handleBlur,
       disabled: Boolean(disabled) || inFlight
     }
   );
@@ -1215,6 +1685,6 @@ function routeRequiresAuth(pathname, navigation, userMenuItems) {
   return false;
 }
 
-export { QuickdrawProvider, SocketCheckbox, SocketSelect, SocketSlider, SocketSwitch, SocketTextField, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useChannelSend, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
+export { QuickdrawProvider, ServiceCallError, SocketCheckbox, SocketSelect, SocketSlider, SocketSwitch, SocketTextField, applyDelta, applyDeltas, applyPage, applySnapshot, buildBreadcrumbs, clearAuthToken, createEmptyEntry, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useChannelSend, useCollection, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map