@remit/drizzle-service 0.0.1

package/src/repos/i4-message-flag-push.test.ts

@@ -0,0 +1,189 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { createTestDb, randomId, type TestDb } from "../test-db.js";
+import { MessageFlagPushRepo } from "./i4-message-flag-push.js";
+
+describe("MessageFlagPushRepo (Postgres counterpart to MessageFlagPushService)", () => {
+	let db: TestDb;
+	let close: () => Promise<void>;
+	let repo: MessageFlagPushRepo;
+
+	const seedInput = (
+		overrides: Partial<{
+			messageId: string;
+			flagName: string;
+			accountId: string;
+			accountConfigId: string;
+			mailboxId: string;
+			operation: "add" | "remove";
+		}> = {},
+	) => ({
+		messageId: randomId(),
+		flagName: "\\Seen",
+		accountId: randomId(),
+		accountConfigId: randomId(),
+		mailboxId: randomId(),
+		operation: "add" as const,
+		...overrides,
+	});
+
+	before(async () => {
+		({ db, close } = await createTestDb());
+		repo = new MessageFlagPushRepo(db as never);
+	});
+
+	after(async () => {
+		await close();
+	});
+
+	test("find returns null when no marker exists — the normal steady state", async () => {
+		const found = await repo.find(randomId(), "\\Seen");
+		assert.equal(found, null);
+	});
+
+	test("put then find round-trips the marker, using the composite (messageId, flagName) key, defaulting state to pending", async () => {
+		const input = seedInput();
+		await repo.put(input);
+
+		const found = await repo.find(input.messageId, input.flagName);
+		assert.ok(found);
+		assert.equal(found?.messageId, input.messageId);
+		assert.equal(found?.flagName, input.flagName);
+		assert.equal(found?.mailboxId, input.mailboxId);
+		assert.equal(found?.operation, "add");
+		assert.equal(found?.state, "pending");
+	});
+
+	test("a pending Seen marker and a pending Flagged marker on the SAME message coexist independently", async () => {
+		const messageId = randomId();
+		await repo.put(
+			seedInput({ messageId, flagName: "\\Seen", operation: "add" }),
+		);
+		await repo.put(
+			seedInput({ messageId, flagName: "\\Flagged", operation: "remove" }),
+		);
+
+		const seenMarker = await repo.find(messageId, "\\Seen");
+		const starMarker = await repo.find(messageId, "\\Flagged");
+
+		assert.equal(seenMarker?.operation, "add");
+		assert.equal(starMarker?.operation, "remove");
+
+		await repo.put(
+			seedInput({ messageId, flagName: "\\Seen", operation: "remove" }),
+		);
+		const starMarkerAfter = await repo.find(messageId, "\\Flagged");
+		assert.equal(
+			starMarkerAfter?.operation,
+			"remove",
+			"the star marker must survive a later flip of the read-state field",
+		);
+	});
+
+	test("updateState advances the state engine without touching other fields", async () => {
+		const input = seedInput();
+		await repo.put(input);
+
+		const queued = await repo.updateState(
+			input.messageId,
+			input.flagName,
+			"queued",
+		);
+		assert.equal(queued.state, "queued");
+		assert.equal(queued.operation, input.operation);
+
+		const processing = await repo.updateState(
+			input.messageId,
+			input.flagName,
+			"processing",
+		);
+		assert.equal(processing.state, "processing");
+
+		const found = await repo.find(input.messageId, input.flagName);
+		assert.equal(found?.state, "processing");
+	});
+
+	test("updateState throws on a marker that does not exist", async () => {
+		await assert.rejects(() =>
+			repo.updateState(randomId(), "\\Seen", "queued"),
+		);
+	});
+
+	test("put resets state back to pending — a fresh flip always starts a new lifecycle", async () => {
+		const input = seedInput();
+		await repo.put(input);
+		await repo.updateState(input.messageId, input.flagName, "processing");
+
+		await repo.put(
+			seedInput({ messageId: input.messageId, flagName: input.flagName }),
+		);
+
+		const found = await repo.find(input.messageId, input.flagName);
+		assert.equal(found?.state, "pending");
+	});
+
+	test("put is idempotent — a later flip of the SAME field replaces the marker", async () => {
+		const messageId = randomId();
+		const flagName = "\\Seen";
+
+		await repo.put(seedInput({ messageId, flagName, operation: "add" }));
+		await repo.put(seedInput({ messageId, flagName, operation: "remove" }));
+
+		const found = await repo.find(messageId, flagName);
+		assert.equal(found?.operation, "remove");
+	});
+
+	test("delete clears the marker (confirmed push / external delete)", async () => {
+		const input = seedInput();
+		await repo.put(input);
+		await repo.delete(input.messageId, input.flagName);
+
+		const found = await repo.find(input.messageId, input.flagName);
+		assert.equal(found, null);
+	});
+
+	test("delete on an absent marker is a no-op, never throws", async () => {
+		await assert.doesNotReject(() => repo.delete(randomId(), "\\Seen"));
+	});
+
+	test("listByAccountId returns every pending marker for the account, none for another", async () => {
+		const accountId = randomId();
+		const otherAccountId = randomId();
+
+		const first = seedInput({ accountId });
+		const second = seedInput({ accountId, flagName: "\\Flagged" });
+		const foreign = seedInput({ accountId: otherAccountId });
+
+		await repo.put(first);
+		await repo.put(second);
+		await repo.put(foreign);
+
+		const markers = await repo.listByAccountId(accountId);
+		const messageIds = markers.map((m) => m.messageId).sort();
+
+		assert.deepEqual(messageIds, [first.messageId, second.messageId].sort());
+	});
+
+	test("listByAccountId returns an empty list for an account with no pending pushes", async () => {
+		const markers = await repo.listByAccountId(randomId());
+		assert.deepEqual(markers, []);
+	});
+
+	test("listByMailboxId returns every pending marker for the mailbox, none for another", async () => {
+		const mailboxId = randomId();
+		const otherMailboxId = randomId();
+
+		const first = seedInput({ mailboxId });
+		const second = seedInput({ mailboxId, flagName: "\\Flagged" });
+		const foreign = seedInput({ mailboxId: otherMailboxId });
+
+		await repo.put(first);
+		await repo.put(second);
+		await repo.put(foreign);
+
+		const markers = await repo.listByMailboxId(mailboxId);
+		const messageIds = markers.map((m) => m.messageId).sort();
+
+		assert.deepEqual(messageIds, [first.messageId, second.messageId].sort());
+	});
+});

package/src/repos/i4-message-flag-push.ts

@@ -0,0 +1,173 @@
+import { and, eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { messageFlagPushTable } from "../schema/i4-message-flag-push.js";
+
+type DB = NodePgDatabase<Record<string, unknown>>;
+
+export type FlagPushOperation = "add" | "remove";
+export type MessageFlagPushState =
+	| "pending"
+	| "queued"
+	| "processing"
+	| "processed";
+
+export interface MessageFlagPushItem {
+	messageId: string;
+	flagName: string;
+	accountId: string;
+	accountConfigId: string;
+	mailboxId: string;
+	operation: FlagPushOperation;
+	state: MessageFlagPushState;
+	createdAt: number;
+	updatedAt: number;
+}
+
+export type PutMessageFlagPushInput = Omit<
+	MessageFlagPushItem,
+	"state" | "createdAt" | "updatedAt"
+>;
+
+const DEFAULT_STATE: MessageFlagPushState = "pending";
+
+function rowToItem(
+	row: typeof messageFlagPushTable.$inferSelect,
+): MessageFlagPushItem {
+	return {
+		messageId: row.messageId,
+		flagName: row.flagName,
+		accountId: row.accountId,
+		accountConfigId: row.accountConfigId,
+		mailboxId: row.mailboxId,
+		operation: row.operation,
+		state: row.state,
+		createdAt: row.createdAt,
+		updatedAt: row.updatedAt,
+	};
+}
+
+/**
+ * Postgres counterpart to `MessageFlagPushService` (remit-electrodb-service).
+ * Same public shape (`put`/`find`/`updateState`/`delete`/`listByAccountId`/
+ * `listByMailboxId`) so both backends satisfy the same structural contract
+ * for read-time unseenCount prediction (issue #1273, epic #1281 invariant 4)
+ * and the account-worker cascade delete.
+ *
+ * Keyed by (`messageId`, `flagName`) — a message can carry an independent
+ * pending read-state marker and pending star marker at once (epic FAQ: "a
+ * flag flip replaces a pending flag flip", scoped per field).
+ */
+export class MessageFlagPushRepo {
+	constructor(private db: DB) {}
+
+	put = async (
+		input: PutMessageFlagPushInput,
+	): Promise<MessageFlagPushItem> => {
+		const now = Date.now();
+		// A fresh put ALWAYS resets state to `pending` (the field's default) —
+		// a new flip decision starts a new lifecycle regardless of whatever
+		// state the row it replaces was in.
+		const [row] = await this.db
+			.insert(messageFlagPushTable)
+			.values({
+				...input,
+				state: DEFAULT_STATE,
+				createdAt: now,
+				updatedAt: now,
+			})
+			.onConflictDoUpdate({
+				target: [messageFlagPushTable.messageId, messageFlagPushTable.flagName],
+				set: {
+					accountId: input.accountId,
+					accountConfigId: input.accountConfigId,
+					mailboxId: input.mailboxId,
+					operation: input.operation,
+					state: DEFAULT_STATE,
+					updatedAt: now,
+				},
+			})
+			.returning();
+		if (!row) {
+			throw new Error(
+				`Failed to upsert MessageFlagPush: ${input.messageId}/${input.flagName}`,
+			);
+		}
+		return rowToItem(row);
+	};
+
+	find = async (
+		messageId: string,
+		flagName: string,
+	): Promise<MessageFlagPushItem | null> => {
+		const [row] = await this.db
+			.select()
+			.from(messageFlagPushTable)
+			.where(
+				and(
+					eq(messageFlagPushTable.messageId, messageId),
+					eq(messageFlagPushTable.flagName, flagName),
+				),
+			);
+		return row ? rowToItem(row) : null;
+	};
+
+	/**
+	 * Advance the marker's state engine. Never touches any other field — a
+	 * state transition is not a new decision, so `operation`/`mailboxId` must
+	 * not change here (a genuinely new decision goes through `put`, which
+	 * fully replaces the row).
+	 */
+	updateState = async (
+		messageId: string,
+		flagName: string,
+		state: MessageFlagPushState,
+	): Promise<MessageFlagPushItem> => {
+		const [row] = await this.db
+			.update(messageFlagPushTable)
+			.set({ state, updatedAt: Date.now() })
+			.where(
+				and(
+					eq(messageFlagPushTable.messageId, messageId),
+					eq(messageFlagPushTable.flagName, flagName),
+				),
+			)
+			.returning();
+		if (!row) {
+			throw new Error(
+				`Cannot update state on a MessageFlagPush that does not exist: ${messageId}/${flagName}`,
+			);
+		}
+		return rowToItem(row);
+	};
+
+	delete = async (messageId: string, flagName: string): Promise<void> => {
+		await this.db
+			.delete(messageFlagPushTable)
+			.where(
+				and(
+					eq(messageFlagPushTable.messageId, messageId),
+					eq(messageFlagPushTable.flagName, flagName),
+				),
+			);
+	};
+
+	listByAccountId = async (
+		accountId: string,
+	): Promise<MessageFlagPushItem[]> => {
+		const rows = await this.db
+			.select()
+			.from(messageFlagPushTable)
+			.where(eq(messageFlagPushTable.accountId, accountId));
+		return rows.map(rowToItem);
+	};
+
+	listByMailboxId = async (
+		mailboxId: string,
+	): Promise<MessageFlagPushItem[]> => {
+		const rows = await this.db
+			.select()
+			.from(messageFlagPushTable)
+			.where(eq(messageFlagPushTable.mailboxId, mailboxId));
+		return rows.map(rowToItem);
+	};
+}

package/src/repos/i4-message-placement-move.test.ts

@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { createTestDb, randomId, type TestDb } from "../test-db.js";
+import { MessagePlacementMoveRepo } from "./i4-message-placement-move.js";
+
+describe("MessagePlacementMoveRepo (Postgres counterpart to MessagePlacementMoveService)", () => {
+	let db: TestDb;
+	let close: () => Promise<void>;
+	let repo: MessagePlacementMoveRepo;
+
+	const seedInput = (
+		overrides: Partial<{
+			messageId: string;
+			accountId: string;
+			accountConfigId: string;
+			sourceMailboxId: string;
+			destinationMailboxId: string;
+		}> = {},
+	) => ({
+		messageId: randomId(),
+		accountId: randomId(),
+		accountConfigId: randomId(),
+		sourceMailboxId: randomId(),
+		destinationMailboxId: randomId(),
+		...overrides,
+	});
+
+	before(async () => {
+		({ db, close } = await createTestDb());
+		repo = new MessagePlacementMoveRepo(db as never);
+	});
+
+	after(async () => {
+		await close();
+	});
+
+	test("find returns null when no marker exists — the normal steady state", async () => {
+		const found = await repo.find(randomId());
+		assert.equal(found, null);
+	});
+
+	test("put then find round-trips the marker, using the given messageId as the primary key, defaulting state to pending", async () => {
+		const input = seedInput();
+		await repo.put(input);
+
+		const found = await repo.find(input.messageId);
+		assert.ok(found);
+		assert.equal(found?.messageId, input.messageId);
+		assert.equal(found?.sourceMailboxId, input.sourceMailboxId);
+		assert.equal(found?.destinationMailboxId, input.destinationMailboxId);
+		assert.equal(found?.state, "pending");
+	});
+
+	test("updateState advances the state engine without touching other fields", async () => {
+		const input = seedInput();
+		await repo.put(input);
+
+		const queued = await repo.updateState(input.messageId, "queued");
+		assert.equal(queued.state, "queued");
+		assert.equal(queued.destinationMailboxId, input.destinationMailboxId);
+
+		const processing = await repo.updateState(input.messageId, "processing");
+		assert.equal(processing.state, "processing");
+
+		const found = await repo.find(input.messageId);
+		assert.equal(found?.state, "processing");
+	});
+
+	test("updateState throws on a marker that does not exist", async () => {
+		await assert.rejects(() => repo.updateState(randomId(), "queued"));
+	});
+
+	test("put resets state back to pending — a fresh decision always starts a new lifecycle", async () => {
+		const input = seedInput();
+		await repo.put(input);
+		await repo.updateState(input.messageId, "processing");
+
+		await repo.put(seedInput({ messageId: input.messageId }));
+
+		const found = await repo.find(input.messageId);
+		assert.equal(found?.state, "pending");
+	});
+
+	test("put is idempotent — a later decision replaces the marker (later intent wins locally)", async () => {
+		const messageId = randomId();
+		const firstDestination = randomId();
+		const secondDestination = randomId();
+
+		await repo.put(
+			seedInput({ messageId, destinationMailboxId: firstDestination }),
+		);
+		await repo.put(
+			seedInput({ messageId, destinationMailboxId: secondDestination }),
+		);
+
+		const found = await repo.find(messageId);
+		assert.equal(found?.destinationMailboxId, secondDestination);
+	});
+
+	test("delete clears the marker (confirmed move / superseded / external delete)", async () => {
+		const input = seedInput();
+		await repo.put(input);
+		await repo.delete(input.messageId);
+
+		const found = await repo.find(input.messageId);
+		assert.equal(found, null);
+	});
+
+	test("delete on an absent marker is a no-op, never throws", async () => {
+		await assert.doesNotReject(() => repo.delete(randomId()));
+	});
+
+	test("listByAccountId returns every pending marker for the account, none for another", async () => {
+		const accountId = randomId();
+		const otherAccountId = randomId();
+
+		const first = seedInput({ accountId });
+		const second = seedInput({ accountId });
+		const foreign = seedInput({ accountId: otherAccountId });
+
+		await repo.put(first);
+		await repo.put(second);
+		await repo.put(foreign);
+
+		const markers = await repo.listByAccountId(accountId);
+		const messageIds = markers.map((m) => m.messageId).sort();
+
+		assert.deepEqual(messageIds, [first.messageId, second.messageId].sort());
+	});
+
+	test("listByAccountId returns an empty list for an account with no pending moves", async () => {
+		const markers = await repo.listByAccountId(randomId());
+		assert.deepEqual(markers, []);
+	});
+});

package/src/repos/i4-message-placement-move.ts

@@ -0,0 +1,144 @@
+import { eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { messagePlacementMoveTable } from "../schema/i4-message-placement-move.js";
+
+type DB = NodePgDatabase<Record<string, unknown>>;
+
+export type MessagePlacementMoveState =
+	| "pending"
+	| "queued"
+	| "processing"
+	| "processed";
+
+export interface MessagePlacementMoveItem {
+	messageId: string;
+	accountId: string;
+	accountConfigId: string;
+	sourceMailboxId: string;
+	destinationMailboxId: string;
+	state: MessagePlacementMoveState;
+	createdAt: number;
+	updatedAt: number;
+}
+
+export type PutMessagePlacementMoveInput = Omit<
+	MessagePlacementMoveItem,
+	"state" | "createdAt" | "updatedAt"
+>;
+
+const DEFAULT_STATE: MessagePlacementMoveState = "pending";
+
+function rowToItem(
+	row: typeof messagePlacementMoveTable.$inferSelect,
+): MessagePlacementMoveItem {
+	return {
+		messageId: row.messageId,
+		accountId: row.accountId,
+		accountConfigId: row.accountConfigId,
+		sourceMailboxId: row.sourceMailboxId,
+		destinationMailboxId: row.destinationMailboxId,
+		state: row.state,
+		createdAt: row.createdAt,
+		updatedAt: row.updatedAt,
+	};
+}
+
+/**
+ * Postgres counterpart to `MessagePlacementMoveService` (remit-electrodb-service).
+ * Same public shape (`put`/`find`/`delete`/`listByAccountId`) so both backends
+ * satisfy the same structural contract for read-time count prediction
+ * (`mailbox.ts`'s `loadPendingMoves`, epic #1281 invariant 4).
+ *
+ * `messageId` is the marker's primary key — always our internal message id,
+ * NEVER a fresh generated one. The generated `messagePlacementMoveTable`
+ * schema defaults `messageId` via `$defaultFn` (matching every other
+ * @key-scalar column the emitter sees) — that default must never fire here,
+ * so every insert below supplies `messageId` explicitly.
+ */
+export class MessagePlacementMoveRepo {
+	constructor(private db: DB) {}
+
+	put = async (
+		input: PutMessagePlacementMoveInput,
+	): Promise<MessagePlacementMoveItem> => {
+		const now = Date.now();
+		// A fresh put ALWAYS resets state to `pending` (the field's default) —
+		// a new placement decision starts a new lifecycle regardless of
+		// whatever state the row it replaces was in.
+		const [row] = await this.db
+			.insert(messagePlacementMoveTable)
+			.values({
+				...input,
+				state: DEFAULT_STATE,
+				createdAt: now,
+				updatedAt: now,
+			})
+			.onConflictDoUpdate({
+				target: messagePlacementMoveTable.messageId,
+				set: {
+					accountId: input.accountId,
+					accountConfigId: input.accountConfigId,
+					sourceMailboxId: input.sourceMailboxId,
+					destinationMailboxId: input.destinationMailboxId,
+					state: DEFAULT_STATE,
+					updatedAt: now,
+				},
+			})
+			.returning();
+		if (!row) {
+			throw new Error(
+				`Failed to upsert MessagePlacementMove: ${input.messageId}`,
+			);
+		}
+		return rowToItem(row);
+	};
+
+	find = async (
+		messageId: string,
+	): Promise<MessagePlacementMoveItem | null> => {
+		const [row] = await this.db
+			.select()
+			.from(messagePlacementMoveTable)
+			.where(eq(messagePlacementMoveTable.messageId, messageId));
+		return row ? rowToItem(row) : null;
+	};
+
+	/**
+	 * Advance the marker's state engine. Never touches any other field — a
+	 * state transition is not a new decision, so the mailbox ids must not
+	 * change here (a genuinely new decision goes through `put`, which fully
+	 * replaces the row).
+	 */
+	updateState = async (
+		messageId: string,
+		state: MessagePlacementMoveState,
+	): Promise<MessagePlacementMoveItem> => {
+		const [row] = await this.db
+			.update(messagePlacementMoveTable)
+			.set({ state, updatedAt: Date.now() })
+			.where(eq(messagePlacementMoveTable.messageId, messageId))
+			.returning();
+		if (!row) {
+			throw new Error(
+				`Cannot update state on a MessagePlacementMove that does not exist: ${messageId}`,
+			);
+		}
+		return rowToItem(row);
+	};
+
+	delete = async (messageId: string): Promise<void> => {
+		await this.db
+			.delete(messagePlacementMoveTable)
+			.where(eq(messagePlacementMoveTable.messageId, messageId));
+	};
+
+	listByAccountId = async (
+		accountId: string,
+	): Promise<MessagePlacementMoveItem[]> => {
+		const rows = await this.db
+			.select()
+			.from(messagePlacementMoveTable)
+			.where(eq(messagePlacementMoveTable.accountId, accountId));
+		return rows.map(rowToItem);
+	};
+}