@remit/web-client 0.0.24 → 0.0.26

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"] },
+		);
+	});
+});

package/src/lib/bulk-delete.ts

@@ -0,0 +1,251 @@
+/**
+ * Chunked bulk-delete orchestration (issue #92).
+ *
+ * The bulk endpoint caps a call at 100 ids (`BulkMessageInput.messageIds`,
+ * `@maxItems(100)`); a delete over a search result can run to thousands. These
+ * helpers sequence the calls and tally what actually happened rather than what
+ * was requested, so a caller can always ask "what's still not deleted" instead
+ * of trusting the request it sent.
+ *
+ * Pure, framework-agnostic, and independently testable — no React, no fetch.
+ * `useEscalatedDelete.ts` supplies the real `DeleteBatch`/`FetchIdsPage`
+ * implementations (the generated SDK client) and owns the React state.
+ */
+
+export const BULK_DELETE_CHUNK_SIZE = 100;
+
+/**
+ * Resolves a promise to a discriminated result instead of throwing, so a
+ * caller can branch on infrastructure failure as a value — the app's
+ * try/catch rule requires a rethrow, and there is nothing to rethrow to here;
+ * the caller's job on failure is to stop the run and report what happened,
+ * not to keep propagating the same rejection past the point it's already
+ * been handled.
+ */
+const attempt = async <T>(
+	promise: Promise<T>,
+): Promise<{ ok: true; value: T } | { ok: false; error: unknown }> =>
+	promise.then(
+		(value) => ({ ok: true as const, value }),
+		(error) => ({ ok: false as const, error }),
+	);
+
+/** Split `ids` into chunks of at most `size`. Empty input yields no chunks. */
+export const chunkIds = (
+	ids: readonly string[],
+	size = BULK_DELETE_CHUNK_SIZE,
+): string[][] => {
+	if (ids.length === 0) return [];
+	const chunks: string[][] = [];
+	for (let i = 0; i < ids.length; i += size) {
+		chunks.push(ids.slice(i, i + size));
+	}
+	return chunks;
+};
+
+export interface DeleteBatchResult {
+	successCount: number;
+	failureCount: number;
+	failedIds?: string[];
+}
+
+/** Sends one bulk-delete call for the given ids (≤100). */
+export type DeleteBatch = (ids: string[]) => Promise<DeleteBatchResult>;
+
+export interface BulkDeleteProgress {
+	/** Ids confirmed deleted so far. */
+	done: number;
+	/** The total the run was started against (may be an estimate for the
+	 *  predicate case — see `runPredicateDelete`). */
+	total: number;
+}
+
+export interface BulkDeleteOutcome {
+	/** Ids confirmed deleted (server-reported success, not merely "sent"). */
+	done: number;
+	/**
+	 * Ids not confirmed deleted: explicit per-batch failures. Does NOT include
+	 * ids from chunks the run never reached (cancelled or stopped by an
+	 * error) — see the per-function doc for how each source handles that.
+	 */
+	failedIds: string[];
+	cancelled: boolean;
+	/** Set when a batch call threw — an infrastructure failure, not a
+	 *  per-item failure. The run stops at the point it was raised. */
+	error?: unknown;
+}
+
+/**
+ * Bounded case: the full id list is known upfront (a materialized selection,
+ * or a "select all loaded" that grew past 100 rows). Chunked synchronously, so
+ * on cancellation or a thrown error every chunk not yet attempted — including
+ * the one in flight when an error was thrown — is folded into `failedIds`. The
+ * caller always gets back exactly the ids still not confirmed deleted, ready
+ * to retry as-is (deleting an already-trashed message is a safe no-op).
+ */
+export const runChunkedDelete = async (
+	ids: readonly string[],
+	deleteBatch: DeleteBatch,
+	onProgress: (progress: BulkDeleteProgress) => void,
+	isCancelled: () => boolean,
+): Promise<BulkDeleteOutcome> => {
+	const chunks = chunkIds(ids);
+	const total = ids.length;
+	let done = 0;
+	const failedIds: string[] = [];
+
+	for (let i = 0; i < chunks.length; i++) {
+		if (isCancelled()) {
+			failedIds.push(...chunks.slice(i).flat());
+			return { done, failedIds, cancelled: true };
+		}
+		const chunk = chunks[i];
+		const attempted = await attempt(deleteBatch(chunk));
+		if (!attempted.ok) {
+			failedIds.push(...chunks.slice(i).flat());
+			onProgress({ done, total });
+			return { done, failedIds, cancelled: false, error: attempted.error };
+		}
+		const failedInChunk = new Set(attempted.value.failedIds ?? []);
+		done += chunk.length - failedInChunk.size;
+		failedIds.push(...chunk.filter((id) => failedInChunk.has(id)));
+		onProgress({ done, total });
+	}
+
+	return { done, failedIds, cancelled: false };
+};
+
+export interface FetchIdsPageResult {
+	ids: string[];
+	continuationToken?: string;
+}
+
+/** Fetches one page of matching message ids for the active predicate. */
+export type FetchIdsPage = (
+	continuationToken: string | undefined,
+) => Promise<FetchIdsPageResult>;
+
+/**
+ * Escalated case: the selection is a predicate (D2), not a materialized list.
+ * Each page is fetched immediately before the chunk it feeds is deleted — a
+ * page IS a chunk, sized to the same 100-id cap the write side enforces — so
+ * ids are never held in memory beyond the batch in flight.
+ *
+ * Cancelling or a thrown error simply stops paging: nothing is added to
+ * `failedIds` for the unreached remainder, because those ids were never
+ * fetched — there is nothing to hand back. A predicate resolves fresh on
+ * every run (D2), so resuming is re-invoking this same function with the same
+ * predicate: already-deleted matches drop out of the search on their own and
+ * are not re-sent.
+ */
+export const runPredicateDelete = async (
+	fetchIdsPage: FetchIdsPage,
+	total: number,
+	deleteBatch: DeleteBatch,
+	onProgress: (progress: BulkDeleteProgress) => void,
+	isCancelled: () => boolean,
+): Promise<BulkDeleteOutcome> => {
+	let done = 0;
+	const failedIds: string[] = [];
+	let token: string | undefined;
+
+	do {
+		if (isCancelled()) {
+			return { done, failedIds, cancelled: true };
+		}
+
+		const fetched = await attempt(fetchIdsPage(token));
+		if (!fetched.ok) {
+			return { done, failedIds, cancelled: false, error: fetched.error };
+		}
+		const page = fetched.value;
+
+		if (page.ids.length > 0) {
+			const attempted = await attempt(deleteBatch(page.ids));
+			if (!attempted.ok) {
+				return { done, failedIds, cancelled: false, error: attempted.error };
+			}
+			const failedInPage = new Set(attempted.value.failedIds ?? []);
+			done += page.ids.length - failedInPage.size;
+			failedIds.push(...page.ids.filter((id) => failedInPage.has(id)));
+			onProgress({ done, total });
+		}
+
+		token = page.continuationToken;
+	} while (token);
+
+	return { done, failedIds, cancelled: false };
+};
+
+export interface CountMatchesResult {
+	total: number;
+	cancelled: boolean;
+	error?: unknown;
+}
+
+/**
+ * Pages the full predicate result set to find its exact total — the only way,
+ * short of a server-side total (out of scope, see issue #92), since search has
+ * no total-count field beyond a small capped-window estimate. Reports a
+ * running count via `onProgress` so a long count reads as progressing rather
+ * than hung, and checks `isCancelled` between pages so Stop takes effect
+ * within one page's latency.
+ */
+export const countMatches = async (
+	fetchIdsPage: FetchIdsPage,
+	onProgress: (countSoFar: number) => void,
+	isCancelled: () => boolean,
+): Promise<CountMatchesResult> => {
+	let total = 0;
+	let token: string | undefined;
+
+	do {
+		if (isCancelled()) {
+			return { total, cancelled: true };
+		}
+		const fetched = await attempt(fetchIdsPage(token));
+		if (!fetched.ok) {
+			return { total, cancelled: false, error: fetched.error };
+		}
+		const page = fetched.value;
+		total += page.ids.length;
+		onProgress(total);
+		token = page.continuationToken;
+	} while (token);
+
+	return { total, cancelled: false };
+};
+
+export interface DeleteRunOutcome {
+	done: number;
+	failedIds: string[];
+	cancelled: boolean;
+	error?: unknown;
+}
+
+export interface SelectionAfterDelete {
+	/** Everything targeted was confirmed deleted — selection mode should exit. */
+	exit: boolean;
+	/** The bounded selection to leave in place, empty when exiting. */
+	retryIds: string[];
+}
+
+/**
+ * What a caller does with selection once a run ends, for any reason. Every id
+ * not confirmed deleted — an explicit failure, or a chunk the run never
+ * reached because it was stopped or errored — belongs in `retryIds`: it is
+ * exactly what Retry should resend, and it is what stays selected so the
+ * count on screen never claims more was deleted than actually was (#92
+ * requirement 8).
+ */
+export const resolveSelectionAfterDelete = (
+	outcome: DeleteRunOutcome,
+): SelectionAfterDelete => {
+	if (outcome.failedIds.length > 0) {
+		return { exit: false, retryIds: outcome.failedIds };
+	}
+	if (outcome.cancelled || outcome.error) {
+		return { exit: false, retryIds: [] };
+	}
+	return { exit: true, retryIds: [] };
+};