@remit/web-client 0.0.25 → 0.0.26

package/src/hooks/useEscalatedDelete.ts

@@ -0,0 +1,244 @@
+import {
+	mailboxOperationsListMailboxesQueryKey,
+	threadOperationsListThreadsQueryKey,
+	threadOperationsSearchThreadsQueryKey,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import {
+	messageBulkOperationsDeleteMessages,
+	threadOperationsSearchThreads,
+} from "@remit/api-http-client/sdk.gen.ts";
+import type { ThreadOperationsSearchThreadsData } from "@remit/api-http-client/types.gen.ts";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
+import { buildMutationErrorBanner } from "@/components/ui/error-banners";
+import {
+	type BulkDeleteProgress,
+	countMatches,
+	type DeleteRunOutcome,
+	type FetchIdsPage,
+	runChunkedDelete,
+	runPredicateDelete,
+} from "@/lib/bulk-delete";
+
+/** The predicate a search-scoped delete re-issues on every page — the same
+ *  filters the visible list is searching with, minus pagination/count knobs. */
+export type EscalationSearchQuery = Pick<
+	NonNullable<ThreadOperationsSearchThreadsData["query"]>,
+	"order" | "query" | "subject" | "from" | "unread" | "starred" | "attachments"
+>;
+
+/** Page size for both the counting and the execution loop. Set to the write
+ *  side's own 100-id cap so an execution page IS a delete chunk — no
+ *  in-memory accumulation step between reading ids and sending them. Counting
+ *  doesn't have that constraint but reuses the same page size rather than
+ *  adding a second one to reason about. */
+const PAGE_SIZE = 100;
+
+export type EscalationPhase =
+	| { kind: "idle" }
+	| { kind: "counting"; countSoFar: number }
+	| { kind: "escalated"; total: number };
+
+interface UseEscalatedDeleteOptions {
+	mailboxId: string;
+	/** Owning account, forwarded to the unseen-count invalidation on completion. */
+	accountId?: string;
+	/** Disables escalation entirely (e.g. not searching, or desktop — this is a
+	 *  mobile-only affordance). Resets any in-flight phase back to idle. */
+	enabled: boolean;
+	/** Identifies the active predicate; escalation resets to idle whenever this
+	 *  changes (a different search is a different question). */
+	predicateKey: string;
+	searchQuery: EscalationSearchQuery;
+}
+
+export interface UseEscalatedDeleteResult {
+	phase: EscalationPhase;
+	/** Begin paging the predicate's full match set to find its total. */
+	escalate: () => void;
+	/** Stop whatever's running — counting or a delete — at the next page
+	 *  boundary. A no-op when nothing is running. */
+	stop: () => void;
+	/** Drop an escalated selection back to bounded without confirming anything. */
+	clear: () => void;
+	/** True while a chunked delete (bounded->100 ids, or the escalated
+	 *  predicate) is running. */
+	isDeleting: boolean;
+	deleteProgress: BulkDeleteProgress | undefined;
+	/**
+	 * Runs a chunked delete. Pass `ids` for a materialized (bounded) selection;
+	 * omit it to delete the escalated predicate (`phase` must be "escalated").
+	 * Resolves once the run ends for any reason — cancelled, errored, or
+	 * complete — with a `done`/`failedIds` outcome the caller feeds to
+	 * `resolveSelectionAfterDelete` to decide what selection looks like next.
+	 * Infrastructure failures are reported through the app's existing
+	 * escalation seam (`pushError`, which itself escalates a 5xx/exception to
+	 * the fatal overlay) — not swallowed here.
+	 */
+	runDelete: (ids?: string[]) => Promise<DeleteRunOutcome>;
+}
+
+export const useEscalatedDelete = ({
+	mailboxId,
+	accountId,
+	enabled,
+	predicateKey,
+	searchQuery,
+}: UseEscalatedDeleteOptions): UseEscalatedDeleteResult => {
+	const [phase, setPhase] = useState<EscalationPhase>({ kind: "idle" });
+	const [isDeleting, setIsDeleting] = useState(false);
+	const [deleteProgress, setDeleteProgress] = useState<
+		BulkDeleteProgress | undefined
+	>(undefined);
+	const cancelRef = useRef(false);
+	const queryClient = useQueryClient();
+	const { pushError } = useErrorBanners();
+
+	// A different search (or leaving search/desktop) makes any in-flight
+	// escalation meaningless — it would otherwise keep counting or offering to
+	// delete a predicate the visible list no longer reflects.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: enabled/predicateKey are trigger-only — the reset itself is unconditional, not a value read from either.
+	useEffect(() => {
+		cancelRef.current = true;
+		setPhase({ kind: "idle" });
+	}, [enabled, predicateKey]);
+
+	const searchQueryRef = useRef(searchQuery);
+	searchQueryRef.current = searchQuery;
+
+	const fetchIdsPage = useCallback<FetchIdsPage>(
+		async (continuationToken) => {
+			const { data } = await threadOperationsSearchThreads({
+				path: { mailboxId },
+				query: {
+					...searchQueryRef.current,
+					continuationToken,
+					limit: PAGE_SIZE,
+				},
+				throwOnError: true,
+			});
+			return {
+				ids: (data.items ?? []).map((item) => item.messageId),
+				continuationToken: data.continuationToken,
+			};
+		},
+		[mailboxId],
+	);
+
+	const deleteBatch = useCallback(async (ids: string[]) => {
+		const { data } = await messageBulkOperationsDeleteMessages({
+			body: { messageIds: ids },
+			throwOnError: true,
+		});
+		return data;
+	}, []);
+
+	const invalidateAfterDelete = useCallback(() => {
+		queryClient.invalidateQueries({
+			queryKey: threadOperationsListThreadsQueryKey({ path: { mailboxId } }),
+		});
+		queryClient.invalidateQueries({
+			queryKey: threadOperationsSearchThreadsQueryKey({ path: { mailboxId } }),
+		});
+		if (accountId) {
+			queryClient.invalidateQueries({
+				queryKey: mailboxOperationsListMailboxesQueryKey({
+					path: { accountId },
+				}),
+			});
+		}
+	}, [queryClient, mailboxId, accountId]);
+
+	const escalate = useCallback(() => {
+		cancelRef.current = false;
+		setPhase({ kind: "counting", countSoFar: 0 });
+		countMatches(
+			fetchIdsPage,
+			(countSoFar) => setPhase({ kind: "counting", countSoFar }),
+			() => cancelRef.current,
+		).then((result) => {
+			if (result.error) {
+				pushError(
+					buildMutationErrorBanner(
+						"Couldn't count matching messages",
+						"The count didn't finish.",
+						result.error,
+					),
+				);
+				setPhase({ kind: "idle" });
+				return;
+			}
+			if (result.cancelled) {
+				setPhase({ kind: "idle" });
+				return;
+			}
+			setPhase({ kind: "escalated", total: result.total });
+		});
+	}, [fetchIdsPage, pushError]);
+
+	const stop = useCallback(() => {
+		cancelRef.current = true;
+	}, []);
+
+	const clear = useCallback(() => {
+		cancelRef.current = true;
+		setPhase({ kind: "idle" });
+	}, []);
+
+	const runDelete = useCallback(
+		async (ids?: string[]): Promise<DeleteRunOutcome> => {
+			cancelRef.current = false;
+			setIsDeleting(true);
+			const onProgress = (progress: BulkDeleteProgress) =>
+				setDeleteProgress(progress);
+
+			const outcome =
+				ids !== undefined
+					? await runChunkedDelete(
+							ids,
+							deleteBatch,
+							onProgress,
+							() => cancelRef.current,
+						)
+					: await runPredicateDelete(
+							fetchIdsPage,
+							phase.kind === "escalated" ? phase.total : 0,
+							deleteBatch,
+							onProgress,
+							() => cancelRef.current,
+						);
+
+			setIsDeleting(false);
+			setDeleteProgress(undefined);
+			setPhase({ kind: "idle" });
+
+			if (outcome.error) {
+				pushError(
+					buildMutationErrorBanner(
+						outcome.done > 0
+							? `Stopped after ${outcome.done} — some messages weren't deleted`
+							: "Couldn't delete these messages",
+						"The delete didn't finish.",
+						outcome.error,
+					),
+				);
+			}
+			if (outcome.done > 0) {
+				invalidateAfterDelete();
+			}
+			return outcome;
+		},
+		[deleteBatch, fetchIdsPage, phase, pushError, invalidateAfterDelete],
+	);
+
+	return {
+		phase,
+		escalate,
+		stop,
+		clear,
+		isDeleting,
+		deleteProgress,
+		runDelete,
+	};
+};

package/src/lib/bulk-delete.test.ts

@@ -0,0 +1,456 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+	BULK_DELETE_CHUNK_SIZE,
+	chunkIds,
+	countMatches,
+	type DeleteBatchResult,
+	type FetchIdsPageResult,
+	resolveSelectionAfterDelete,
+	runChunkedDelete,
+	runPredicateDelete,
+} from "./bulk-delete.js";
+
+const ids = (count: number, prefix = "m"): string[] =>
+	Array.from({ length: count }, (_, i) => `${prefix}${i}`);
+
+describe("chunkIds", () => {
+	test("empty input yields no chunks", () => {
+		assert.deepEqual(chunkIds([]), []);
+	});
+
+	test("exactly one chunk's worth stays a single chunk", () => {
+		const got = chunkIds(ids(BULK_DELETE_CHUNK_SIZE));
+		assert.equal(got.length, 1);
+		assert.equal(got[0].length, BULK_DELETE_CHUNK_SIZE);
+	});
+
+	test("one over the boundary spills a second chunk of one", () => {
+		const got = chunkIds(ids(BULK_DELETE_CHUNK_SIZE + 1));
+		assert.equal(got.length, 2);
+		assert.equal(got[0].length, BULK_DELETE_CHUNK_SIZE);
+		assert.equal(got[1].length, 1);
+	});
+
+	test("preserves order across chunk boundaries", () => {
+		const input = ids(BULK_DELETE_CHUNK_SIZE + 5);
+		const got = chunkIds(input).flat();
+		assert.deepEqual(got, input);
+	});
+
+	test("a custom size chunks accordingly", () => {
+		assert.deepEqual(chunkIds(["a", "b", "c", "d", "e"], 2), [
+			["a", "b"],
+			["c", "d"],
+			["e"],
+		]);
+	});
+});
+
+describe("runChunkedDelete", () => {
+	const neverCancelled = () => false;
+	const noopProgress = () => undefined;
+
+	test("zero ids does nothing and reports done=0", async () => {
+		const calls: string[][] = [];
+		const outcome = await runChunkedDelete(
+			[],
+			async (chunk) => {
+				calls.push(chunk);
+				return { successCount: chunk.length, failureCount: 0 };
+			},
+			noopProgress,
+			neverCancelled,
+		);
+		assert.deepEqual(outcome, {
+			done: 0,
+			failedIds: [],
+			cancelled: false,
+		});
+		assert.equal(calls.length, 0);
+	});
+
+	test("sequences one call per 100-id chunk, in order", async () => {
+		const input = ids(BULK_DELETE_CHUNK_SIZE + 1);
+		const calls: string[][] = [];
+		const outcome = await runChunkedDelete(
+			input,
+			async (chunk) => {
+				calls.push(chunk);
+				return { successCount: chunk.length, failureCount: 0 };
+			},
+			noopProgress,
+			neverCancelled,
+		);
+		assert.equal(calls.length, 2);
+		assert.equal(calls[0].length, BULK_DELETE_CHUNK_SIZE);
+		assert.equal(calls[1].length, 1);
+		assert.equal(outcome.done, input.length);
+		assert.deepEqual(outcome.failedIds, []);
+	});
+
+	test("the count deleted matches exactly what the batches reported succeeded", async () => {
+		const input = ids(5);
+		const outcome = await runChunkedDelete(
+			input,
+			async (chunk) => ({
+				successCount: chunk.length - 2,
+				failureCount: 2,
+				failedIds: chunk.slice(0, 2),
+			}),
+			noopProgress,
+			neverCancelled,
+		);
+		assert.equal(outcome.done, 3);
+		assert.deepEqual(outcome.failedIds, input.slice(0, 2));
+	});
+
+	test("partial failure: failed ids are reported, not rolled into done", async () => {
+		const input = ids(3);
+		const outcome = await runChunkedDelete(
+			input,
+			async (chunk) => ({
+				successCount: 2,
+				failureCount: 1,
+				failedIds: [chunk[1]],
+			}),
+			noopProgress,
+			neverCancelled,
+		);
+		assert.equal(outcome.done, 2);
+		assert.deepEqual(outcome.failedIds, [input[1]]);
+	});
+
+	test("cancelling mid-run folds every unreached chunk into failedIds", async () => {
+		const input = ids(BULK_DELETE_CHUNK_SIZE * 3);
+		let calls = 0;
+		let cancelled = false;
+		const outcome = await runChunkedDelete(
+			input,
+			async (chunk) => {
+				calls++;
+				if (calls === 1) cancelled = true; // cancel after the first chunk lands
+				return { successCount: chunk.length, failureCount: 0 };
+			},
+			() => undefined,
+			() => cancelled,
+		);
+		assert.equal(outcome.cancelled, true);
+		assert.equal(calls, 1);
+		assert.equal(outcome.done, BULK_DELETE_CHUNK_SIZE);
+		// The two chunks never attempted come back as not-yet-deleted.
+		assert.equal(outcome.failedIds.length, BULK_DELETE_CHUNK_SIZE * 2);
+	});
+
+	test("an infra failure mid-run stops the run and reports the error", async () => {
+		const input = ids(BULK_DELETE_CHUNK_SIZE * 2);
+		const boom = new Error("network blip");
+		const outcome = await runChunkedDelete(
+			input,
+			async () => {
+				throw boom;
+			},
+			noopProgress,
+			neverCancelled,
+		);
+		assert.equal(outcome.error, boom);
+		assert.equal(outcome.done, 0);
+		assert.equal(outcome.failedIds.length, input.length);
+	});
+
+	test("reports progress after each chunk", async () => {
+		const input = ids(BULK_DELETE_CHUNK_SIZE + 1);
+		const progressCalls: { done: number; total: number }[] = [];
+		await runChunkedDelete(
+			input,
+			async (chunk) => ({ successCount: chunk.length, failureCount: 0 }),
+			(p) => progressCalls.push(p),
+			neverCancelled,
+		);
+		assert.deepEqual(progressCalls, [
+			{ done: BULK_DELETE_CHUNK_SIZE, total: input.length },
+			{ done: input.length, total: input.length },
+		]);
+	});
+});
+
+describe("runPredicateDelete", () => {
+	const neverCancelled = () => false;
+	const noopProgress = () => undefined;
+
+	/** Builds a paged fixture: `pages[i]` is what the i-th call returns. */
+	const pagedFetcher = (pages: FetchIdsPageResult[]) => {
+		let call = 0;
+		return async (): Promise<FetchIdsPageResult> => {
+			const page = pages[call];
+			call++;
+			return page;
+		};
+	};
+
+	test("zero matches deletes nothing", async () => {
+		const fetch = pagedFetcher([{ ids: [] }]);
+		const outcome = await runPredicateDelete(
+			fetch,
+			0,
+			async (chunk) => ({ successCount: chunk.length, failureCount: 0 }),
+			noopProgress,
+			neverCancelled,
+		);
+		assert.deepEqual(outcome, { done: 0, failedIds: [], cancelled: false });
+	});
+
+	test("exactly 100 matches — a page size's worth — resolves in a single page with no continuation", async () => {
+		const fetch = pagedFetcher([{ ids: ids(BULK_DELETE_CHUNK_SIZE) }]);
+		const deleteCalls: string[][] = [];
+		const outcome = await runPredicateDelete(
+			fetch,
+			BULK_DELETE_CHUNK_SIZE,
+			async (chunk) => {
+				deleteCalls.push(chunk);
+				return { successCount: chunk.length, failureCount: 0 };
+			},
+			noopProgress,
+			neverCancelled,
+		);
+		assert.equal(deleteCalls.length, 1);
+		assert.equal(outcome.done, BULK_DELETE_CHUNK_SIZE);
+	});
+
+	test("pages until the continuation token is exhausted, one delete call per page", async () => {
+		const fetch = pagedFetcher([
+			{ ids: ids(100, "a"), continuationToken: "t1" },
+			{ ids: ids(50, "b") },
+		]);
+		const deleteCalls: string[][] = [];
+		const outcome = await runPredicateDelete(
+			fetch,
+			150,
+			async (chunk) => {
+				deleteCalls.push(chunk);
+				return { successCount: chunk.length, failureCount: 0 };
+			},
+			noopProgress,
+			neverCancelled,
+		);
+		assert.equal(deleteCalls.length, 2);
+		assert.equal(outcome.done, 150);
+	});
+
+	test("a list refresh mid-run that adds and removes rows just changes what later pages contain — the predicate resolves fresh, never a stale materialized set", async () => {
+		// Page 1 sees the original matches. Page 2 (fetched only after page 1's
+		// batch has already been deleted) reflects new mail having arrived and
+		// one previously-seen id having been filed elsewhere mid-run.
+		const fetch = pagedFetcher([
+			{ ids: ["a", "b"], continuationToken: "t1" },
+			{ ids: ["new-c", "d"] }, // "b" is gone (filed away), "new-c" just arrived
+		]);
+		const deleteCalls: string[][] = [];
+		const outcome = await runPredicateDelete(
+			fetch,
+			4,
+			async (chunk) => {
+				deleteCalls.push(chunk);
+				return { successCount: chunk.length, failureCount: 0 };
+			},
+			noopProgress,
+			neverCancelled,
+		);
+		assert.deepEqual(deleteCalls, [
+			["a", "b"],
+			["new-c", "d"],
+		]);
+		assert.equal(outcome.done, 4);
+	});
+
+	test("partial failure across pages accumulates failedIds without rolling into done", async () => {
+		const fetch = pagedFetcher([
+			{ ids: ["a", "b"], continuationToken: "t1" },
+			{ ids: ["c"] },
+		]);
+		const outcome = await runPredicateDelete(
+			fetch,
+			3,
+			async (chunk): Promise<DeleteBatchResult> => {
+				if (chunk.includes("b")) {
+					return { successCount: 1, failureCount: 1, failedIds: ["b"] };
+				}
+				return { successCount: chunk.length, failureCount: 0 };
+			},
+			noopProgress,
+			neverCancelled,
+		);
+		assert.equal(outcome.done, 2);
+		assert.deepEqual(outcome.failedIds, ["b"]);
+	});
+
+	test("cancelling mid-delete stops paging without inventing failedIds for unfetched pages", async () => {
+		let fetchCalls = 0;
+		let cancelled = false;
+		const fetch = async (): Promise<FetchIdsPageResult> => {
+			fetchCalls++;
+			return { ids: ["a", "b"], continuationToken: "more" };
+		};
+		const outcome = await runPredicateDelete(
+			fetch,
+			1000,
+			async (chunk) => {
+				cancelled = true; // cancel takes effect on the next loop iteration
+				return { successCount: chunk.length, failureCount: 0 };
+			},
+			() => undefined,
+			() => cancelled,
+		);
+		assert.equal(outcome.cancelled, true);
+		assert.equal(fetchCalls, 1);
+		assert.equal(outcome.done, 2);
+		assert.deepEqual(outcome.failedIds, []);
+	});
+
+	test("an infra failure while fetching a page stops the run and reports the error", async () => {
+		const boom = new Error("timed out");
+		const fetch = async (): Promise<FetchIdsPageResult> => {
+			throw boom;
+		};
+		const outcome = await runPredicateDelete(
+			fetch,
+			100,
+			async (chunk) => ({ successCount: chunk.length, failureCount: 0 }),
+			noopProgress,
+			neverCancelled,
+		);
+		assert.equal(outcome.error, boom);
+		assert.equal(outcome.done, 0);
+	});
+
+	test("an infra failure from the delete call itself stops the run and reports the error", async () => {
+		const boom = new Error("500");
+		const fetch = pagedFetcher([{ ids: ["a"] }]);
+		const outcome = await runPredicateDelete(
+			fetch,
+			1,
+			async () => {
+				throw boom;
+			},
+			noopProgress,
+			neverCancelled,
+		);
+		assert.equal(outcome.error, boom);
+	});
+});
+
+describe("countMatches", () => {
+	const neverCancelled = () => false;
+
+	test("counts across every page until the token is exhausted", async () => {
+		let call = 0;
+		const pages: FetchIdsPageResult[] = [
+			{ ids: ids(500, "a"), continuationToken: "t1" },
+			{ ids: ids(500, "b"), continuationToken: "t2" },
+			{ ids: ids(412, "c") },
+		];
+		const fetch = async () => pages[call++];
+		const outcome = await countMatches(fetch, () => undefined, neverCancelled);
+		assert.deepEqual(outcome, { total: 1412, cancelled: false });
+	});
+
+	test("reports a running total after each page", async () => {
+		let call = 0;
+		const pages: FetchIdsPageResult[] = [
+			{ ids: ids(500), continuationToken: "t1" },
+			{ ids: ids(300) },
+		];
+		const fetch = async () => pages[call++];
+		const progressCalls: number[] = [];
+		await countMatches(fetch, (n) => progressCalls.push(n), neverCancelled);
+		assert.deepEqual(progressCalls, [500, 800]);
+	});
+
+	test("cancelling mid-count stops paging and reports what it had so far", async () => {
+		let call = 0;
+		let cancelled = false;
+		const fetch = async (): Promise<FetchIdsPageResult> => {
+			call++;
+			return { ids: ids(500), continuationToken: "more" };
+		};
+		const outcome = await countMatches(
+			fetch,
+			() => {
+				cancelled = true;
+			},
+			() => cancelled,
+		);
+		assert.equal(outcome.cancelled, true);
+		assert.equal(call, 1);
+		assert.equal(outcome.total, 500);
+	});
+
+	test("an infra failure while paging stops the count and reports the error", async () => {
+		const boom = new Error("network blip");
+		const fetch = async (): Promise<FetchIdsPageResult> => {
+			throw boom;
+		};
+		const outcome = await countMatches(fetch, () => undefined, neverCancelled);
+		assert.equal(outcome.error, boom);
+		assert.equal(outcome.total, 0);
+	});
+});
+
+describe("resolveSelectionAfterDelete", () => {
+	test("a clean run with nothing failed exits selection mode", () => {
+		assert.deepEqual(
+			resolveSelectionAfterDelete({
+				done: 3412,
+				failedIds: [],
+				cancelled: false,
+			}),
+			{ exit: true, retryIds: [] },
+		);
+	});
+
+	test("explicit failures stay selected for a precise retry, even alongside a clean stop", () => {
+		assert.deepEqual(
+			resolveSelectionAfterDelete({
+				done: 3072,
+				failedIds: ["a", "b"],
+				cancelled: false,
+			}),
+			{ exit: false, retryIds: ["a", "b"] },
+		);
+	});
+
+	test("a clean cancel with nothing yet confirmed failed leaves nothing to retry, but does not exit", () => {
+		assert.deepEqual(
+			resolveSelectionAfterDelete({
+				done: 100,
+				failedIds: [],
+				cancelled: true,
+			}),
+			{ exit: false, retryIds: [] },
+		);
+	});
+
+	test("an infra failure with no explicit per-item failures still keeps selection mode open", () => {
+		assert.deepEqual(
+			resolveSelectionAfterDelete({
+				done: 0,
+				failedIds: [],
+				cancelled: false,
+				error: new Error("network blip"),
+			}),
+			{ exit: false, retryIds: [] },
+		);
+	});
+
+	test("failedIds wins over cancelled/error when both are present", () => {
+		assert.deepEqual(
+			resolveSelectionAfterDelete({
+				done: 10,
+				failedIds: ["x"],
+				cancelled: true,
+				error: new Error("boom"),
+			}),
+			{ exit: false, retryIds: ["x"] },
+		);
+	});
+});