@remit/data-ports 0.0.66 → 0.0.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.66",
+  "version": "0.0.68",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/folder-role.test.ts

@@ -9,6 +9,7 @@ import {
 import {
 	composeFolderRoleAppointmentLabelName,
 	composeFolderRoleAppointmentName,
+	isReservedFolderName,
 	meetsTrashAssurance,
 	parseFolderRoleAppointmentLabelName,
 	parseFolderRoleAppointmentName,
@@ -180,9 +181,9 @@ describe("resolveConfirmedMailboxForRole", () => {
 
 describe("resolveRoleForAccount", () => {
 	it("resolves an appointment naming a mailbox whose last sync failed", () => {
-		// `failed` has three writers (imap-worker mailbox-management: create :166
-		// rolls nothing back, rename :275 restores oldPath, delete :384 leaves the
-		// folder) and in two the folder is really at the path the row names.
+		// `failed` means the folder exists at `fullPath` and the last rename or
+		// delete intent did not land (folder-rename-and-delete.md D7), so the row
+		// names a path the server really holds.
 		const failed: RoleMailboxCandidate & { syncStatus: string } = {
 			...mailbox("mb-trash", "INBOX/Prullenbak"),
 			syncStatus: MailboxSyncStatus.failed,
@@ -382,3 +383,40 @@ describe("the appointment name and its label sibling", () => {
 		});
 	});
 });
+
+describe("isReservedFolderName", () => {
+	/**
+	 * The sweep's own predicate. A folder whose leaf name is a role's
+	 * conventional name but which lacks the server's flag is read as a duplicate
+	 * and its row is deleted — under D8, with the folder's mail — as soon as
+	 * another folder holds the flag. A rename to one of these settles `synced`
+	 * and is then reaped, which is why the API refuses it (D5).
+	 */
+	for (const name of [
+		"archive",
+		"Archive",
+		"ARCHIVES",
+		"trash",
+		"Deleted Items",
+		"drafts",
+		"Sent Mail",
+		"junk",
+		"Spam",
+		"All Mail",
+	]) {
+		it(`reserves "${name}"`, () => {
+			assert.equal(isReservedFolderName(name), true);
+		});
+	}
+
+	/**
+	 * #843 dropped a bare "Deleted" and "Bin" from the Trash hints precisely
+	 * because they are ordinary folder names a user keeps mail in. Reserving
+	 * them here would refuse a rename nothing would ever have reaped.
+	 */
+	for (const name of ["Deleted", "Bin", "Receipts", "Work", "Inbox 2024"]) {
+		it(`leaves "${name}" alone`, () => {
+			assert.equal(isReservedFolderName(name), false);
+		});
+	}
+});

package/src/folder-role.ts

@@ -134,6 +134,41 @@ export const ROLE_NAME_HINTS: Partial<
 	[CanonicalMailboxRole.All]: ["all mail", "all"],
 };
 
+/**
+ * The role a folder's own leaf name is most conventionally for. A name that
+ * several roles list goes to the role that ranks it highest, so `All Mail` is
+ * an All folder rather than a lookalike of Archive.
+ *
+ * `name` is the leaf segment, lower case.
+ */
+export const roleForFolderName = (
+	name: string,
+): CanonicalMailboxRoleValue | undefined => {
+	let best: { role: CanonicalMailboxRoleValue; rank: number } | undefined;
+	for (const role of CANONICAL_ROLES) {
+		const rank = ROLE_NAME_HINTS[role]?.indexOf(name) ?? -1;
+		if (rank < 0) continue;
+		if (!best || rank < best.rank) best = { role, rank };
+	}
+	return best?.role;
+};
+
+/**
+ * Whether the mailbox sweep would read a folder with this leaf name as a
+ * duplicate of a role's canonical folder — and so delete its row, and under D8
+ * the mail in it, as soon as another folder carries the role's SPECIAL-USE
+ * flag. It is the sweep's own predicate, so a rename refused on it and a folder
+ * reaped by it can never disagree (docs/architecture/folder-rename-and-delete.md
+ * D5).
+ *
+ * A role with no flag to be a duplicate of is not reserved: nothing reaps a
+ * folder for it.
+ */
+export const isReservedFolderName = (name: string): boolean => {
+	const role = roleForFolderName(name.toLowerCase());
+	return role !== undefined && ROLE_SPECIAL_USE[role] !== undefined;
+};
+
 /**
  * The pane where a user appoints a folder to a role, named as it is labelled.
  * Every refusal that asks for an appointment points here, in one wording — the

package/src/index.ts

@@ -117,6 +117,10 @@ export type {
 	MailboxLockItem,
 	MailboxSpecialUseItem,
 	MailboxSpecialUseValue,
+	MailboxStatePredicate,
+	MailboxSubtreeTransitionIntent,
+	MailboxTransitionIntent,
+	MailboxTransitionWrite,
 	MessageData,
 	MessageDescription,
 	MessageFlagItem,

package/src/interfaces/mailbox.ts

@@ -1,6 +1,8 @@
 import type {
 	CreateMailboxInput,
 	MailboxItem,
+	MailboxSubtreeTransitionIntent,
+	MailboxTransitionIntent,
 	ResultList,
 	UpdateMailboxInput,
 } from "../types.js";
@@ -28,8 +30,67 @@ export interface IMailboxRepository {
 		input: UpdateMailboxInput,
 		remove?: string[],
 	): Promise<MailboxItem>;
+	/**
+	 * Move one folder's mutation state from the state the caller read to the
+	 * state it decided on, as one conditional write
+	 * (docs/architecture/folder-rename-and-delete.md D3). The only writer of
+	 * `syncStatus` and `pendingPath` — so a folder state written without a
+	 * predicate is a type error rather than a convention.
+	 *
+	 * The predicate names one of the six states, not one of the four enum
+	 * values: `wherePendingPath` as a string requires equality, `null` requires
+	 * the column to be NULL, and omitting it predicates on `syncStatus` alone.
+	 * A create settle that leaves it out matches a row a rename has claimed and
+	 * strands it `synced` with a target on it, which is the seventh combination
+	 * the invariant forbids.
+	 *
+	 * Resolves with the written row when the predicate matched, and with `null`
+	 * when it did not — the row is absent, or somebody else won. The loser
+	 * re-reads and re-decides; it never blind-retries and never writes anyway.
+	 */
+	transition(
+		accountId: string,
+		mailboxId: string,
+		intent: MailboxTransitionIntent,
+	): Promise<MailboxItem | null>;
+	/**
+	 * Record one intent across a folder and every descendant, all-or-nothing, in
+	 * one transaction (D6). Each row's UPDATE carries the from-state predicate
+	 * and the affected-row count is compared to the resolved subtree, so a
+	 * concurrent single-row transition rolls the whole thing back rather than
+	 * being missed by a prior read.
+	 *
+	 * Resolves with every written row, or with `null` when any row in the
+	 * subtree was not in an accepted from-state — in which case nothing was
+	 * written. The named folder comes first and its descendants follow, but a
+	 * caller wanting one row should find it by `mailboxId` rather than lean on
+	 * that. This serves the intent only: a settle is per-row (D15).
+	 */
+	transitionSubtree(
+		accountId: string,
+		mailboxId: string,
+		intent: MailboxSubtreeTransitionIntent,
+	): Promise<MailboxItem[] | null>;
 	delete(accountId: string, mailboxId: string): Promise<void>;
 	deleteMany(accountId: string, mailboxIds: string[]): Promise<void>;
+	/**
+	 * Remove a folder along with the mail it holds (D8): the messages through
+	 * `deleteMessageSubtree`, so the nine per-message child tables go and one
+	 * `message.removed` outbox row per message clears the search index; then the
+	 * mailbox's own child rows; then, last, the mailbox row itself.
+	 *
+	 * "Its own child rows" includes a `message_placement_move` marker naming this
+	 * folder as a move's *destination*, not only as its source. The folder it
+	 * points at is gone, so the move it records can never land, and leaving the
+	 * marker behind holds a message elsewhere in the account unsettled forever.
+	 *
+	 * Ordered, batched and resumable rather than one transaction — the caller
+	 * keeps the row `deleting` until this returns, so a redelivery re-enters and
+	 * continues. `filter` rows bound to this mailbox are never touched: D16
+	 * refuses the delete while any binding stands, so there is nothing to unbind
+	 * and deleting a user's filters is not a folder delete's decision.
+	 */
+	deleteMailboxWithMail(accountId: string, mailboxId: string): Promise<void>;
 	listByAccount(
 		accountId: string,
 		options?: { limit?: number; continuationToken?: string },
@@ -48,12 +109,6 @@ export interface IMailboxRepository {
 	): Promise<MailboxItem[]>;
 	findBySyncStatus(
 		accountId: string,
-		syncStatus: NonNullable<MailboxItem["syncStatus"]>,
+		syncStatus: MailboxItem["syncStatus"],
 	): Promise<MailboxItem[]>;
-	renameChildPaths(
-		accountId: string,
-		oldPath: string,
-		newPath: string,
-		delimiter?: string,
-	): Promise<void>;
 }

package/src/mailbox-name.ts

@@ -24,6 +24,31 @@ export const mailboxLeafName = (mailbox: MailboxPath): string => {
 	return parts[parts.length - 1] || mailbox.fullPath;
 };
 
+/**
+ * Where a path under a renamed folder lands, or `undefined` when the rename did
+ * not move it. IMAP RENAME moves the whole subtree in one command, so a path
+ * inside the renamed branch moves exactly as far as its prefix does, and a path
+ * merely starting with the same characters (`Workshop` beside `Work`) does not
+ * move at all.
+ *
+ * Sliced rather than replaced. `String.prototype.replace` with a string pattern
+ * expands `$&`, `` $` ``, `$'` and `$$` in the replacement, so a rename to a
+ * folder whose name contains one of those wrote a different path locally from
+ * the one the RENAME carried to the server — the row and the server diverge and
+ * the next sweep inserts a second row for the real path.
+ */
+export const rebaseMailboxPath = (
+	recorded: string,
+	oldPath: string,
+	newPath: string,
+	delimiter: string,
+): string | undefined => {
+	if (recorded === oldPath) return newPath;
+	if (delimiter.length === 0) return undefined;
+	if (!recorded.startsWith(`${oldPath}${delimiter}`)) return undefined;
+	return `${newPath}${recorded.slice(oldPath.length)}`;
+};
+
 const rank = (
 	mailbox: MailboxNameCandidate,
 	names: readonly string[],

package/src/mailbox-state-doors.test.ts

@@ -0,0 +1,104 @@
+/**
+ * The doors onto a folder's mutation state, proved by the compiler.
+ *
+ * `docs/architecture/folder-rename-and-delete.md` D3 says every transition of a
+ * folder's state is a conditional write. A rule like that is worth exactly as
+ * much as the thing enforcing it, and a convention enforces nothing: every
+ * writer in the tree before this reached for the general-purpose `update()`,
+ * because nothing stopped them.
+ *
+ * So `syncStatus` and `pendingPath` are gone from `UpdateMailboxInput`, and
+ * `pendingPath` from `CreateMailboxInput` too — a create records no rename
+ * target (T1). What is left is `transition` and `transitionSubtree`, both of
+ * which take a predicate. Every `@ts-expect-error` below is a door that is
+ * shut: put the field back and these stop erroring, which fails the build.
+ *
+ * `@ts-expect-error` is the assertion here, so this file is checked rather than
+ * run. The one runtime case exists to keep the suite honest about having loaded
+ * it.
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type {
+	CreateMailboxInput,
+	MailboxStatePredicate,
+	MailboxSubtreeTransitionIntent,
+	MailboxTransitionIntent,
+	UpdateMailboxInput,
+} from "./types.js";
+
+// --- The general-purpose writer refuses both state fields -------------------
+
+// @ts-expect-error `syncStatus` is mutation state: write it through a transition
+const syncStatus: UpdateMailboxInput = { syncStatus: "pending" };
+
+// @ts-expect-error `pendingPath` is mutation state
+const pendingPath: UpdateMailboxInput = { pendingPath: "Archive/2025" };
+
+// The insert records a state — the intent recorders say which — but never a
+// rename target, because a create has none.
+const created: CreateMailboxInput = {
+	accountId: "acct-1",
+	namespacePrefix: "",
+	hierarchyDelimiter: "/",
+	fullPath: "Archive",
+	uidValidity: 1,
+	uidNext: 1,
+	highestModseq: "0",
+	messageCount: 0,
+	unseenCount: 0,
+	deletedCount: 0,
+	totalSize: 0,
+	lastSyncUid: 0,
+	highWaterMarkUid: 0,
+	lastMessageSyncAt: 0,
+	syncStatus: "pending",
+};
+
+// @ts-expect-error a create records no rename target (T1)
+const createdWithTarget: CreateMailboxInput = { ...created, pendingPath: "X" };
+
+// Everything else about a folder still goes through `update()`, unchanged.
+const ordinary: UpdateMailboxInput = {
+	fullPath: "Archive/2025",
+	messageCount: 12,
+	cursorState: "cursor_invalid",
+};
+
+// --- The transitions are the doors, and they take a predicate ---------------
+
+const transition: MailboxTransitionIntent = {
+	from: ["pending"],
+	wherePendingPath: null,
+	to: "synced",
+	set: { fullPath: "INBOX/Archive", pendingPath: null },
+};
+
+const subtree: MailboxSubtreeTransitionIntent = {
+	from: ["synced", "failed"],
+	to: "pending",
+	rowSet: (row) => ({ pendingPath: row.fullPath }),
+};
+
+// The predicate names states, never a free-form column: a caller cannot smuggle
+// an unrelated field into the WHERE clause and call it a lock.
+const notAState: MailboxStatePredicate = {
+	from: ["synced"],
+	// @ts-expect-error `fullPath` is not part of a folder's mutation state
+	fullPath: "INBOX",
+};
+
+test("the folder-state doors are the two transitions", () => {
+	assert.equal(transition.to, "synced");
+	assert.equal(
+		subtree.rowSet({ fullPath: "Work" } as never).pendingPath,
+		"Work",
+	);
+	assert.equal(ordinary.messageCount, 12);
+	assert.deepEqual(
+		[syncStatus, pendingPath, createdWithTarget, notAState].length,
+		4,
+		"each field taken off an input, and the predicate's own shape, is pinned above",
+	);
+});

package/src/types.ts

@@ -360,6 +360,11 @@ export type BodyPartContentUpsertInput = {
 	content: string;
 };
 
+/**
+ * A mailbox row as an insert states it. `pendingPath` is absent: a create
+ * records no rename target (folder-rename-and-delete.md T1), and the transition
+ * is the only writer of it.
+ */
 export type CreateMailboxInput = Omit<
 	MailboxItem,
 	| "mailboxId"
@@ -368,14 +373,70 @@ export type CreateMailboxInput = Omit<
 	| "namespaceType"
 	| "parentMailboxId"
 	| "cursorState"
+	| "syncStatus"
+	| "pendingPath"
 > & {
 	namespaceType?: MailboxItem["namespaceType"];
 	parentMailboxId?: MailboxItem["parentMailboxId"];
 	/** Total per RFC 032 (defaults to `normal`) — optional at the input boundary, callers rarely set it explicitly. */
 	cursorState?: MailboxItem["cursorState"];
+	/** Total per D1 (defaults to `synced`) — the insert paths that record an intent say so; the sweep's discovery insert does not have to. */
+	syncStatus?: MailboxItem["syncStatus"];
 };
 
-export type UpdateMailboxInput = Partial<Omit<CreateMailboxInput, "accountId">>;
+/**
+ * Everything about a mailbox that is not its mutation state.
+ *
+ * `syncStatus` and `pendingPath` are omitted rather than merely discouraged
+ * (docs/architecture/folder-rename-and-delete.md D3): where they are gone from
+ * the only general-purpose writer, a folder state written without a predicate
+ * is a type error rather than a convention someone has to remember. The two
+ * doors are `transition` and `transitionSubtree`, and they are the whole set.
+ */
+export type UpdateMailboxInput = Partial<
+	Omit<CreateMailboxInput, "accountId" | "syncStatus">
+>;
+
+/**
+ * The state a mailbox transition expects to find, as the six states this design
+ * defines rather than as the four enum values
+ * (docs/architecture/folder-rename-and-delete.md D3). `from` becomes an
+ * `IN (…)` term; `wherePendingPath` becomes an equality or an `IS NULL` term,
+ * and is omitted only by a caller that genuinely does not care which of the two
+ * states sharing a `syncStatus` it is looking at.
+ */
+export type MailboxStatePredicate = {
+	from: readonly MailboxItem["syncStatus"][];
+	wherePendingPath?: string | null;
+};
+
+/**
+ * What a winning mailbox transition writes. `pendingPath` takes `null` to
+ * clear, and is only honoured at all when the state being written is one that
+ * may carry a rename target — a transition to `synced` or `deleting` drops it
+ * whatever the caller passes, which is what makes the invariant hold by
+ * construction rather than by convention.
+ */
+export type MailboxTransitionWrite = {
+	fullPath?: string;
+	pendingPath?: string | null;
+};
+
+export type MailboxTransitionIntent = MailboxStatePredicate & {
+	to: MailboxItem["syncStatus"];
+	set?: MailboxTransitionWrite;
+};
+
+/**
+ * A subtree intent recorded all-or-nothing (D6). It carries no
+ * `wherePendingPath`: its accepted from-states are `synced` and the two failed
+ * variants, and both failed variants are legal starting points.
+ */
+export type MailboxSubtreeTransitionIntent = {
+	from: readonly MailboxItem["syncStatus"][];
+	to: MailboxItem["syncStatus"];
+	rowSet: (row: MailboxItem) => MailboxTransitionWrite;
+};
 
 export type CreateMessageInput = Omit<
 	MessageItem,