@remit/web-client 0.0.25 → 0.0.27

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: [] };
+};

package/src/lib/escalation-label.test.ts

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+	describeSearchScope,
+	escalatedStatusLabel,
+	escalationActionLabel,
+} from "./escalation-label.js";
+
+describe("describeSearchScope", () => {
+	test("free text query wins and is quoted", () => {
+		assert.equal(describeSearchScope({ query: "npm" }), 'matching "npm"');
+	});
+
+	test("falls back to a from: filter when there's no free text", () => {
+		assert.equal(
+			describeSearchScope({ from: "billing@example.com" }),
+			'from "billing@example.com"',
+		);
+	});
+
+	test("free text wins over a from: filter when both are set", () => {
+		assert.equal(
+			describeSearchScope({ query: "npm", from: "noreply@npmjs.com" }),
+			'matching "npm"',
+		);
+	});
+
+	test("neither present falls back to a generic scope rather than throwing", () => {
+		assert.equal(describeSearchScope({}), "matching your search");
+	});
+});
+
+describe("escalationActionLabel", () => {
+	test("names the scope, never a bare Select all", () => {
+		assert.equal(
+			escalationActionLabel({ query: "npm" }),
+			'Select all matching "npm"',
+		);
+	});
+});
+
+describe("escalatedStatusLabel", () => {
+	test("thousands-separates the total and names the scope", () => {
+		assert.equal(
+			escalatedStatusLabel({ query: "npm" }, 3412),
+			'All 3,412 matching "npm" selected',
+		);
+	});
+});

package/src/lib/escalation-label.ts

@@ -0,0 +1,32 @@
+import { formatNumber } from "./format";
+
+/** The subset of the search predicate that names the scope in escalation copy. */
+export interface EscalationScopeQuery {
+	query?: string;
+	from?: string;
+}
+
+/**
+ * Names what an escalated selection covers, for the notice text and the
+ * confirm dialog — never a bare "Select all" (issue #92 requirement 4). Free
+ * text wins when present since it's what the user actually typed; `from:`
+ * alone still names a scope. Neither present is unreachable in practice (the
+ * escalation control only ever renders for an active search), but the
+ * fallback keeps the label honest instead of throwing.
+ */
+export const describeSearchScope = (query: EscalationScopeQuery): string => {
+	if (query.query) return `matching "${query.query}"`;
+	if (query.from) return `from "${query.from}"`;
+	return "matching your search";
+};
+
+/** "Select all matching "npm"" — the escalation notice's action label. */
+export const escalationActionLabel = (query: EscalationScopeQuery): string =>
+	`Select all ${describeSearchScope(query)}`;
+
+/** "All 3,412 matching "npm" selected" — the bar's status label once escalated. */
+export const escalatedStatusLabel = (
+	query: EscalationScopeQuery,
+	total: number,
+): string =>
+	`All ${formatNumber(total)} ${describeSearchScope(query)} selected`;

package/src/lib/format.test.ts

@@ -112,4 +112,11 @@ describe("formatDeleteToTrashTitle", () => {
 			"Move 0 messages to Trash?",
 		);
 	});
+
+	test("thousands-separates an escalated-selection-scale count", () => {
+		assert.strictEqual(
+			formatDeleteToTrashTitle(3412),
+			"Move 3,412 messages to Trash?",
+		);
+	});
 });

package/src/lib/format.ts

@@ -193,6 +193,10 @@ export const formatList = (
 /**
  * Confirmation title for the move-to-Trash delete flow. Reflects that delete
  * moves messages to Trash (not a permanent delete) and pluralizes on count.
+ * Thousands-separated: at escalated-selection scale this is exactly the digit
+ * count someone checks against what they meant to select.
  */
 export const formatDeleteToTrashTitle = (count: number): string =>
-	count === 1 ? "Move 1 message to Trash?" : `Move ${count} messages to Trash?`;
+	count === 1
+		? "Move 1 message to Trash?"
+		: `Move ${formatNumber(count)} messages to Trash?`;