xfeed 0.1.0

package/src/experiments/use-bookmark-mutation.ts

@@ -0,0 +1,342 @@
+/**
+ * useBookmarkMutation - TanStack Query mutation hook for bookmark operations
+ *
+ * Features:
+ * - Optimistic updates for immediate UI feedback
+ * - Automatic cache rollback on error
+ * - Supports both adding and removing bookmarks
+ * - Updates all relevant bookmark caches (all bookmarks + folder-specific)
+ */
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+
+import type { XClient } from "@/api/client";
+import type { TweetData } from "@/api/types";
+
+import { queryKeys } from "./query-client";
+
+interface BookmarksPage {
+  tweets: TweetData[];
+  nextCursor?: string;
+}
+
+interface BookmarksCacheData {
+  pages: BookmarksPage[];
+  pageParams: (string | undefined)[];
+}
+
+interface UseBookmarkMutationOptions {
+  client: XClient;
+  /** Callback when mutation succeeds */
+  onSuccess?: (message: string) => void;
+  /** Callback when mutation fails */
+  onError?: (error: string) => void;
+}
+
+interface MutationContext {
+  previousAllBookmarks?: BookmarksCacheData;
+  previousFolderBookmarks?: Map<string, BookmarksCacheData>;
+}
+
+/** Duration for "just acted" visual feedback in ms */
+const JUST_ACTED_DURATION = 600;
+
+export function useBookmarkMutation({
+  client,
+  onSuccess,
+  onError,
+}: UseBookmarkMutationOptions) {
+  const queryClient = useQueryClient();
+
+  // Track pending state per tweet
+  const [pendingTweets, setPendingTweets] = useState<Set<string>>(new Set());
+
+  // Track "just bookmarked" state per tweet
+  const [justBookmarkedTweets, setJustBookmarkedTweets] = useState<Set<string>>(
+    new Set()
+  );
+
+  // Timeouts for clearing justBookmarked state
+  const justBookmarkedTimeouts = useRef<
+    Map<string, ReturnType<typeof setTimeout>>
+  >(new Map());
+
+  // Add bookmark mutation
+  const addMutation = useMutation({
+    mutationFn: async (tweet: TweetData) => {
+      const result = await client.createBookmark(tweet.id);
+      if (!result.success) {
+        throw new Error(result.error);
+      }
+      return { tweet, success: true };
+    },
+    onMutate: async (tweet) => {
+      // Mark as pending
+      setPendingTweets((prev) => new Set(prev).add(tweet.id));
+
+      // Cancel any outgoing refetches
+      await queryClient.cancelQueries({
+        queryKey: queryKeys.bookmarks.all,
+      });
+
+      // Snapshot the previous values
+      const previousAllBookmarks = queryClient.getQueryData<BookmarksCacheData>(
+        queryKeys.bookmarks.list(undefined)
+      );
+
+      // Optimistically add to "all bookmarks" cache
+      if (previousAllBookmarks) {
+        queryClient.setQueryData<BookmarksCacheData>(
+          queryKeys.bookmarks.list(undefined),
+          (old) => {
+            if (!old?.pages?.length) return old;
+
+            // Add tweet to the beginning of the first page
+            const firstPage = old.pages[0];
+            if (!firstPage) return old;
+
+            // Check if already exists
+            const exists = old.pages.some((page) =>
+              page.tweets.some((t) => t.id === tweet.id)
+            );
+            if (exists) return old;
+
+            return {
+              ...old,
+              pages: [
+                {
+                  ...firstPage,
+                  tweets: [tweet, ...firstPage.tweets],
+                },
+                ...old.pages.slice(1),
+              ],
+            };
+          }
+        );
+      }
+
+      return { previousAllBookmarks } as MutationContext;
+    },
+    onError: (error, tweet, context) => {
+      // Remove from pending
+      setPendingTweets((prev) => {
+        const next = new Set(prev);
+        next.delete(tweet.id);
+        return next;
+      });
+
+      // Rollback cache
+      if (context?.previousAllBookmarks) {
+        queryClient.setQueryData(
+          queryKeys.bookmarks.list(undefined),
+          context.previousAllBookmarks
+        );
+      }
+
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+
+      // Handle "already bookmarked" gracefully
+      if (errorMessage.toLowerCase().includes("already bookmarked")) {
+        onSuccess?.("Already bookmarked");
+        return;
+      }
+
+      onError?.(errorMessage);
+    },
+    onSuccess: (_, tweet) => {
+      // Remove from pending
+      setPendingTweets((prev) => {
+        const next = new Set(prev);
+        next.delete(tweet.id);
+        return next;
+      });
+
+      // Set justBookmarked for visual feedback
+      const existingTimeout = justBookmarkedTimeouts.current.get(tweet.id);
+      if (existingTimeout) clearTimeout(existingTimeout);
+
+      setJustBookmarkedTweets((prev) => new Set(prev).add(tweet.id));
+
+      const timeout = setTimeout(() => {
+        setJustBookmarkedTweets((prev) => {
+          const next = new Set(prev);
+          next.delete(tweet.id);
+          return next;
+        });
+        justBookmarkedTimeouts.current.delete(tweet.id);
+      }, JUST_ACTED_DURATION);
+      justBookmarkedTimeouts.current.set(tweet.id, timeout);
+
+      onSuccess?.("Bookmarked");
+    },
+  });
+
+  // Remove bookmark mutation
+  const removeMutation = useMutation({
+    mutationFn: async ({
+      tweetId,
+      folderId,
+    }: {
+      tweetId: string;
+      tweet?: TweetData;
+      folderId?: string;
+    }) => {
+      const result = await client.deleteBookmark(tweetId);
+      if (!result.success) {
+        throw new Error(result.error);
+      }
+      return { tweetId, folderId, success: true };
+    },
+    onMutate: async ({ tweetId, folderId }) => {
+      // Mark as pending
+      setPendingTweets((prev) => new Set(prev).add(tweetId));
+
+      // Cancel any outgoing refetches
+      await queryClient.cancelQueries({
+        queryKey: queryKeys.bookmarks.all,
+      });
+
+      // Snapshot and update "all bookmarks" cache
+      const previousAllBookmarks = queryClient.getQueryData<BookmarksCacheData>(
+        queryKeys.bookmarks.list(undefined)
+      );
+
+      if (previousAllBookmarks) {
+        queryClient.setQueryData<BookmarksCacheData>(
+          queryKeys.bookmarks.list(undefined),
+          (old) => {
+            if (!old) return old;
+            return {
+              ...old,
+              pages: old.pages.map((page) => ({
+                ...page,
+                tweets: page.tweets.filter((t) => t.id !== tweetId),
+              })),
+            };
+          }
+        );
+      }
+
+      // Snapshot and update folder-specific cache if provided
+      const previousFolderBookmarks = new Map<string, BookmarksCacheData>();
+      if (folderId) {
+        const folderData = queryClient.getQueryData<BookmarksCacheData>(
+          queryKeys.bookmarks.list(folderId)
+        );
+        if (folderData) {
+          previousFolderBookmarks.set(folderId, folderData);
+          queryClient.setQueryData<BookmarksCacheData>(
+            queryKeys.bookmarks.list(folderId),
+            (old) => {
+              if (!old) return old;
+              return {
+                ...old,
+                pages: old.pages.map((page) => ({
+                  ...page,
+                  tweets: page.tweets.filter((t) => t.id !== tweetId),
+                })),
+              };
+            }
+          );
+        }
+      }
+
+      return {
+        previousAllBookmarks,
+        previousFolderBookmarks,
+      } as MutationContext;
+    },
+    onError: (error, { tweetId }, context) => {
+      // Remove from pending
+      setPendingTweets((prev) => {
+        const next = new Set(prev);
+        next.delete(tweetId);
+        return next;
+      });
+
+      // Rollback caches
+      if (context?.previousAllBookmarks) {
+        queryClient.setQueryData(
+          queryKeys.bookmarks.list(undefined),
+          context.previousAllBookmarks
+        );
+      }
+      if (context?.previousFolderBookmarks) {
+        for (const [fId, data] of context.previousFolderBookmarks) {
+          queryClient.setQueryData(queryKeys.bookmarks.list(fId), data);
+        }
+      }
+
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+
+      // Handle "not found" gracefully (already removed)
+      if (errorMessage.toLowerCase().includes("not found")) {
+        onSuccess?.("Already removed");
+        return;
+      }
+
+      onError?.(errorMessage);
+    },
+    onSuccess: (_, { tweetId }) => {
+      // Remove from pending
+      setPendingTweets((prev) => {
+        const next = new Set(prev);
+        next.delete(tweetId);
+        return next;
+      });
+
+      onSuccess?.("Removed bookmark");
+    },
+  });
+
+  // Public API
+  const addBookmark = useCallback(
+    (tweet: TweetData) => {
+      if (pendingTweets.has(tweet.id)) return;
+      addMutation.mutate(tweet);
+    },
+    [addMutation, pendingTweets]
+  );
+
+  const removeBookmark = useCallback(
+    (tweetId: string, folderId?: string, tweet?: TweetData) => {
+      if (pendingTweets.has(tweetId)) return;
+      removeMutation.mutate({ tweetId, folderId, tweet });
+    },
+    [removeMutation, pendingTweets]
+  );
+
+  const toggleBookmark = useCallback(
+    (tweet: TweetData, isCurrentlyBookmarked: boolean, folderId?: string) => {
+      if (isCurrentlyBookmarked) {
+        removeBookmark(tweet.id, folderId, tweet);
+      } else {
+        addBookmark(tweet);
+      }
+    },
+    [addBookmark, removeBookmark]
+  );
+
+  const isPending = useCallback(
+    (tweetId: string) => pendingTweets.has(tweetId),
+    [pendingTweets]
+  );
+
+  const isJustBookmarked = useCallback(
+    (tweetId: string) => justBookmarkedTweets.has(tweetId),
+    [justBookmarkedTweets]
+  );
+
+  return {
+    addBookmark,
+    removeBookmark,
+    toggleBookmark,
+    isPending,
+    isJustBookmarked,
+    isAddPending: addMutation.isPending,
+    isRemovePending: removeMutation.isPending,
+  };
+}

package/src/experiments/use-bookmarks-query.ts

@@ -0,0 +1,166 @@
+/**
+ * useBookmarksQuery - TanStack Query hook for bookmarks fetching
+ *
+ * Features:
+ * - Infinite query for cursor-based pagination
+ * - Folder filtering with separate cache keys per folder
+ * - Deduplication across pages
+ * - Cache mutation for bookmark removal
+ */
+
+import { useInfiniteQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useMemo } from "react";
+
+import type { XClient } from "@/api/client";
+import type { ApiError, TweetData } from "@/api/types";
+
+import { queryKeys } from "./query-client";
+
+interface BookmarksPage {
+  tweets: TweetData[];
+  nextCursor?: string;
+}
+
+interface UseBookmarksQueryOptions {
+  client: XClient;
+  /** Optional folder ID to filter bookmarks by a specific folder */
+  folderId?: string | null;
+}
+
+interface UseBookmarksQueryResult {
+  /** List of bookmarked posts */
+  posts: TweetData[];
+  /** Whether initial data is loading */
+  isLoading: boolean;
+  /** Whether more data is being loaded (pagination) */
+  isFetchingNextPage: boolean;
+  /** Whether there are more posts to load */
+  hasNextPage: boolean;
+  /** Error if fetch failed */
+  error: ApiError | null;
+  /** Fetch next page of results */
+  fetchNextPage: () => void;
+  /** Manually refresh bookmarks */
+  refresh: () => void;
+  /** Whether refresh is in progress */
+  isRefetching: boolean;
+  /** Remove a post from the cache (used when unbookmarked) */
+  removePost: (tweetId: string) => void;
+}
+
+/**
+ * Fetch bookmarks page from X API
+ */
+async function fetchBookmarksPage(
+  client: XClient,
+  folderId: string | undefined | null,
+  cursor?: string
+): Promise<BookmarksPage> {
+  const result = folderId
+    ? await client.getBookmarkFolderTimelineV2(folderId, 30, cursor)
+    : await client.getBookmarksV2(30, cursor);
+
+  if (!result.success) {
+    throw result.error;
+  }
+
+  return {
+    tweets: result.tweets,
+    nextCursor: result.nextCursor,
+  };
+}
+
+/**
+ * Deduplicate tweets across all pages
+ */
+function deduplicateTweets(pages: BookmarksPage[]): TweetData[] {
+  const seen = new Set<string>();
+  const result: TweetData[] = [];
+
+  for (const page of pages) {
+    for (const tweet of page.tweets) {
+      if (!seen.has(tweet.id)) {
+        seen.add(tweet.id);
+        result.push(tweet);
+      }
+    }
+  }
+
+  return result;
+}
+
+export function useBookmarksQuery({
+  client,
+  folderId,
+}: UseBookmarksQueryOptions): UseBookmarksQueryResult {
+  const queryClient = useQueryClient();
+
+  // Normalize folderId: treat null and undefined the same
+  const normalizedFolderId = folderId ?? undefined;
+
+  // Main infinite query for bookmarks
+  const {
+    data,
+    isLoading,
+    isFetchingNextPage,
+    hasNextPage,
+    error,
+    fetchNextPage,
+    refetch,
+    isRefetching,
+  } = useInfiniteQuery({
+    queryKey: queryKeys.bookmarks.list(normalizedFolderId),
+    queryFn: async ({ pageParam }) => {
+      return fetchBookmarksPage(client, normalizedFolderId, pageParam);
+    },
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+    initialPageParam: undefined as string | undefined,
+    staleTime: 0,
+  });
+
+  // Flatten and deduplicate tweets from all pages
+  const posts = useMemo(() => {
+    if (!data?.pages) return [];
+    return deduplicateTweets(data.pages);
+  }, [data?.pages]);
+
+  // Manual refresh
+  const refresh = useCallback(() => {
+    refetch();
+  }, [refetch]);
+
+  // Remove a post from the cache (called when user unbookmarks)
+  const removePost = useCallback(
+    (tweetId: string) => {
+      const queryKey = queryKeys.bookmarks.list(normalizedFolderId);
+
+      queryClient.setQueryData<{
+        pages: BookmarksPage[];
+        pageParams: (string | undefined)[];
+      }>(queryKey, (oldData) => {
+        if (!oldData) return oldData;
+
+        return {
+          ...oldData,
+          pages: oldData.pages.map((page) => ({
+            ...page,
+            tweets: page.tweets.filter((tweet) => tweet.id !== tweetId),
+          })),
+        };
+      });
+    },
+    [queryClient, normalizedFolderId]
+  );
+
+  return {
+    posts,
+    isLoading,
+    isFetchingNextPage,
+    hasNextPage: hasNextPage ?? false,
+    error: error as ApiError | null,
+    fetchNextPage,
+    refresh,
+    isRefetching,
+    removePost,
+  };
+}