@remit/drizzle-service 0.0.1

package/drizzle.config.ts

@@ -0,0 +1,15 @@
+const url =
+	process.env.DATABASE_URL ??
+	process.env.PG_CONNECTION_URL ??
+	"postgresql://remit:remit@localhost:5432/remit_dev";
+
+export default {
+	dialect: "postgresql",
+	schema: "./src/schema.ts",
+	out: "./.drizzle",
+	dbCredentials: { url },
+	// The better-auth identity tables (auth_*) share this database but are owned
+	// by remit-auth-service's own drizzle config. Exclude them here so an entity
+	// push never proposes dropping tables it does not manage.
+	tablesFilter: ["!auth_*"],
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@remit/drizzle-service",
+  "version": "0.0.1",
+  "description": "Drizzle ORM service parameterized by dialect (Postgres / SQLite)",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "test:typecheck": "tsgo --noEmit -p tsconfig.json",
+    "test:run:pg": "node --env-file=../../localhost-test-unit.env --import tsx --test 'src/**/!(*.sqlite).test.ts'",
+    "test:run:sqlite": "node --env-file=../../localhost-test-unit-sqlite.env --import tsx --test 'src/**/*.sqlite.test.ts'",
+    "test:run": "npm run test:run:pg && npm run test:run:sqlite",
+    "test": "npm run test:typecheck && npm run test:run",
+    "fix": "biome check --write src"
+  },
+  "devDependencies": {
+    "@remit/api-zod-schemas": "*",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/pg": "^8.0.0",
+    "better-sqlite3": "^12.11.1",
+    "drizzle-kit": "^0.31.1",
+    "embedded-postgres": "^18.4.0-beta.17",
+    "tsx": "*",
+    "zod": "*"
+  },
+  "dependencies": {
+    "@remit/data-ports": "*",
+    "@remit/domain-enums": "*",
+    "drizzle-orm": "^0.45.2",
+    "pg": "^8.0.0",
+    "postgres": "^3.4.5",
+    "short-uuid": "*",
+    "uuid": "*",
+    "@remit/drizzle-pg-schema": "*",
+    "@remit/drizzle-sqlite-schema": "*"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remit-mail/remit.git",
+    "directory": "packages/drizzle-service"
+  }
+}

package/src/db.ts

@@ -0,0 +1,13 @@
+import type { NodePgQueryResultHKT } from "drizzle-orm/node-postgres";
+import type { PgDatabase } from "drizzle-orm/pg-core";
+
+/**
+ * A drizzle handle a repository can run on: the top-level database or a
+ * transaction (or savepoint) bound to one. Both share the query-builder API, so
+ * a repo constructed with either behaves the same — standalone, or enlisted in a
+ * unit-of-work transaction.
+ */
+export type Db<TSchema extends Record<string, unknown>> = PgDatabase<
+	NodePgQueryResultHKT,
+	TSchema
+>;

package/src/dialect.ts

@@ -0,0 +1,13 @@
+// The SQL dialect this process runs against (RFC 036 D1). One deployment is
+// one backend, chosen once at startup by `DATA_BACKEND`: `sqlite` selects the
+// SQLite entity tables, outbox table, transaction strategy, and search
+// predicates; anything else keeps the Postgres behavior that predates this
+// switch. Read once at module load — the repos and schema facade branch on it,
+// and a single process never mixes dialects.
+
+export type SqlDialect = "postgres" | "sqlite";
+
+export const SQL_DIALECT: SqlDialect =
+	process.env.DATA_BACKEND === "sqlite" ? "sqlite" : "postgres";
+
+export const isSqlite = (): boolean => SQL_DIALECT === "sqlite";

package/src/error.ts

@@ -0,0 +1,37 @@
+// Re-export the shared error contract so an error thrown by a pg repo is the
+// same class the backend handlers and workers already catch (they import these
+// from @remit/data-ports/errors). Defining parallel classes here made
+// `instanceof NotFoundError` false across the adapter boundary — a fresh user's
+// GET /config surfaced a 404 fatal overlay instead of the empty-config path.
+export {
+	CreateFailedConflictError,
+	ForbiddenError,
+	NotFoundError,
+} from "@remit/data-ports/errors";
+
+export class NotImplementedError extends Error {
+	name = "NotImplementedError";
+	statusCode = 501;
+}
+
+const PG_UNIQUE_VIOLATION = "23505";
+// better-sqlite3 raises a `SqliteError` whose `.code` is one of these for a
+// primary-key or unique-index collision (RFC 036 D1).
+const SQLITE_UNIQUE_VIOLATIONS = new Set([
+	"SQLITE_CONSTRAINT_UNIQUE",
+	"SQLITE_CONSTRAINT_PRIMARYKEY",
+]);
+
+// Drizzle wraps the underlying driver error and carries the original (with its
+// SQLSTATE / SQLite `code`) on `.cause`, so walk the cause chain — covers both
+// the pg and better-sqlite3 drivers.
+export const isUniqueViolation = (error: unknown): boolean => {
+	let current: unknown = error;
+	while (current) {
+		const code = (current as { code?: string }).code;
+		if (code === PG_UNIQUE_VIOLATION) return true;
+		if (code !== undefined && SQLITE_UNIQUE_VIOLATIONS.has(code)) return true;
+		current = (current as { cause?: unknown }).cause;
+	}
+	return false;
+};

package/src/id.ts

@@ -0,0 +1,50 @@
+import shortUuid from "short-uuid";
+import { v5 as uuidv5 } from "uuid";
+
+const REMIT_NAMESPACE = "9e89694d-214b-4d9b-99f5-214b4d9b99f5";
+
+const base36 = shortUuid.createTranslator(shortUuid.constants.uuid25Base36);
+
+// A 25-char base36-encoded UUID, matching the id format the API contract
+// enforces (path params carry minLength 25) and the electrodb adapter's
+// base36uuid. The prior Math.random-based generator produced variable-length
+// ids (~19 chars) that failed `{accountId}`/`{messageId}` path validation.
+export const randomId = (): string => base36.generate();
+
+export const generateDeterministicId = (name: string): string =>
+	uuidv5(name, REMIT_NAMESPACE);
+
+// Deterministic base36-encoded UUIDv5, byte-identical to the electrodb
+// adapter's `base36uuidv5` so a `MessageLabel` derived from the same
+// (messageId, labelId) keys the same row on either backend.
+export const deterministicBase36Id = (name: string): string =>
+	base36.fromUUID(uuidv5(name, REMIT_NAMESPACE));
+
+export const bodyPartId = (messageId: string, partPath: string): string =>
+	generateDeterministicId(`${messageId}:${partPath}`);
+
+export const rootBodyPartId = (messageId: string): string =>
+	bodyPartId(messageId, "0");
+
+export const bodyPartParameterId = (
+	messageId: string,
+	partPath: string,
+	parameterName: string,
+): string =>
+	generateDeterministicId(`${messageId}:${partPath}:${parameterName}`);
+
+export const envelopeId = (messageId: string): string =>
+	generateDeterministicId(`envelope:${messageId}`);
+
+export const envelopeAddressId = (
+	messageId: string,
+	role: string,
+	order: number,
+): string =>
+	generateDeterministicId(`envelopeaddress:${messageId}:${role}:${order}`);
+
+export const bodyPartContentId = (
+	messageId: string,
+	bodyPartId: string,
+): string =>
+	generateDeterministicId(`bodypartcontent:${messageId}:${bodyPartId}`);

package/src/index.ts

@@ -0,0 +1,62 @@
+export { CreateFailedConflictError, NotFoundError } from "./error.js";
+export {
+	type CascadeDeleteLogger,
+	type CascadeDeleter,
+	type CascadeEntity,
+	createCascadeDeleter,
+	createSqliteCascadeDeleter,
+	runDrizzleCascadeDelete,
+} from "./repos/cascade-delete.js";
+export { DrizzleEnvelopeRepository } from "./repos/envelope.js";
+export { FilterRepo } from "./repos/filter.js";
+export { FilterAnchorRepo } from "./repos/filter-anchor.js";
+export * from "./repos/i4-account.js";
+export * from "./repos/i4-account-config.js";
+export * from "./repos/i4-account-export-request.js";
+export * from "./repos/i4-account-setting.js";
+export * from "./repos/i4-address.js";
+export * from "./repos/i4-mailbox.js";
+export * from "./repos/i4-mailbox-lock.js";
+export * from "./repos/i4-mailbox-special-use.js";
+export {
+	type FlagPushOperation,
+	type MessageFlagPushItem,
+	MessageFlagPushRepo,
+	type MessageFlagPushState,
+	type PutMessageFlagPushInput,
+} from "./repos/i4-message-flag-push.js";
+export {
+	type MessagePlacementMoveItem,
+	MessagePlacementMoveRepo,
+	type PutMessagePlacementMoveInput,
+} from "./repos/i4-message-placement-move.js";
+export * from "./repos/i4-organize-job-request.js";
+export * from "./repos/i4-outbox-message.js";
+export { LabelRepo } from "./repos/label.js";
+export {
+	DrizzleMessageRepository,
+	deleteMessageSubtree,
+	MESSAGE_REMOVED_EVENT,
+} from "./repos/message.js";
+export { DrizzleMessageFlagRepository } from "./repos/message-flag.js";
+export { MessageLabelRepo } from "./repos/message-label.js";
+export { DrizzleThreadMessageRepository } from "./repos/thread-message.js";
+export { DrizzleUnitOfWork } from "./repos/unit-of-work.js";
+export * from "./schema/i4-account-config.js";
+export * from "./schema/i4-account-export-request.js";
+export * from "./schema/i4-account-setting.js";
+export * from "./schema/i4-address.js";
+export * from "./schema/i4-mailbox.js";
+export * from "./schema/i4-mailbox-lock.js";
+export * from "./schema/i4-message-flag-push.js";
+export * from "./schema/i4-message-placement-move.js";
+export * from "./schema/i4-organize-job-request.js";
+export * from "./schema/i4-outbox-message.js";
+export * from "./schema/message-data.js";
+export { messageDataSchema } from "./schema/message-data.js";
+export {
+	createSqliteDatabase,
+	type SqliteClient,
+	type SqliteClientOptions,
+} from "./sqlite-client.js";
+export { runInTransaction, serializeSqliteWrites } from "./tx.js";

package/src/pagination.ts

@@ -0,0 +1,29 @@
+import type { ResultList } from "@remit/data-ports";
+
+export function encodeToken(data: Record<string, unknown>): string {
+	return Buffer.from(JSON.stringify(data)).toString("base64url");
+}
+
+export function decodeToken(
+	token: string,
+): Record<string, unknown> | undefined {
+	try {
+		return JSON.parse(
+			Buffer.from(token, "base64url").toString("utf8"),
+		) as Record<string, unknown>;
+	} catch {
+		return undefined;
+	}
+}
+
+export function resultList<T>(
+	items: T[],
+	limit: number | undefined,
+	lastKey?: Record<string, unknown>,
+): ResultList<T> {
+	const continuationToken =
+		lastKey && limit !== undefined && items.length === limit
+			? encodeToken(lastKey)
+			: undefined;
+	return { items, continuationToken };
+}

package/src/repos/cascade-delete.sqlite.test.ts

@@ -0,0 +1,159 @@
+import assert from "node:assert/strict";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, before, describe, test } from "node:test";
+import { MailboxCursorState } from "@remit/domain-enums";
+import Database from "better-sqlite3";
+import { messageDataSchema } from "../schema/message-data.js";
+import {
+	accountTable,
+	envelopeTable,
+	mailboxTable,
+	messageTable,
+} from "../schema.js";
+import { createSqliteTestDb } from "../test-db-sqlite.js";
+import {
+	type CascadeEntity,
+	createSqliteCascadeDeleter,
+} from "./cascade-delete.js";
+
+// createSqliteCascadeDeleter opens the shared SQLite file itself, so the schema
+// this harness pushes must live on a real file (not the in-memory default) for
+// the deleter's own connection to see it. `deleteMessageSubtree` touches every
+// message-data child table, so push the full message-data schema plus the
+// account and mailbox containers.
+const CASCADE_SCHEMA = {
+	...messageDataSchema,
+	account: accountTable,
+	mailbox: mailboxTable,
+};
+
+const log = { info: () => {} };
+const NOW = 1700000000000;
+const ACCOUNT_CONFIG_ID = "cfg-sqlite-1";
+const ACCOUNT_ID = "acc-sqlite-1";
+const MAILBOX_ID = "mbx-sqlite-1";
+const MESSAGE_ID = "msg-sqlite-1";
+const ENVELOPE_ID = "00000000-0000-4000-8000-0000000000a1";
+const ROOT_BODY_PART_ID = "00000000-0000-4000-8000-0000000000a2";
+
+describe("createSqliteCascadeDeleter", () => {
+	let filename: string;
+	let close: () => Promise<void>;
+
+	before(async () => {
+		const dir = await mkdtemp(join(tmpdir(), "remit-sqlite-cascade-"));
+		filename = join(dir, "cascade.db");
+		const created = await createSqliteTestDb(CASCADE_SCHEMA, { filename });
+		close = created.close;
+		const { db } = created;
+
+		await db.insert(accountTable).values({
+			accountId: ACCOUNT_ID,
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			username: "u",
+			email: "u@example.com",
+			authType: "password",
+			imapHost: "imap.example.com",
+			imapPort: 993,
+			imapTls: true,
+			imapStartTls: false,
+			smtpPort: 587,
+			isActive: true,
+			connectionState: "authenticated",
+			createdAt: NOW,
+			updatedAt: NOW,
+		});
+		await db.insert(mailboxTable).values({
+			mailboxId: MAILBOX_ID,
+			accountId: ACCOUNT_ID,
+			namespaceType: "personal",
+			namespacePrefix: "",
+			hierarchyDelimiter: "/",
+			fullPath: "INBOX",
+			uidValidity: 1,
+			uidNext: 1,
+			highestModseq: 0,
+			messageCount: 0,
+			unseenCount: 0,
+			deletedCount: 0,
+			totalSize: 0,
+			lastSyncUid: 0,
+			highWaterMarkUid: 0,
+			lastMessageSyncAt: NOW,
+			cursorState: MailboxCursorState.normal,
+			createdAt: NOW,
+			updatedAt: NOW,
+		});
+		await db.insert(messageTable).values({
+			messageId: MESSAGE_ID,
+			mailboxId: MAILBOX_ID,
+			uid: 1,
+			sequenceNumber: 1,
+			rfc822Size: 10,
+			internalDate: NOW,
+			envelopeId: ENVELOPE_ID,
+			rootBodyPartId: ROOT_BODY_PART_ID,
+			status: "active",
+			syncStatus: "synced",
+			category: "uncategorized",
+			createdAt: NOW,
+			updatedAt: NOW,
+		});
+		await db.insert(envelopeTable).values({
+			envelopeId: ENVELOPE_ID,
+			messageId: MESSAGE_ID,
+			dateValue: NOW,
+			dateRaw: "Mon, 14 Nov 2023 08:00:00 +0000",
+			createdAt: NOW,
+			updatedAt: NOW,
+		});
+
+		// Close the seeding connection so the deleter's own WAL connection owns
+		// the file without a cross-connection lock.
+		await close();
+	});
+
+	after(async () => {
+		// The seeding connection is already closed; nothing else to release.
+	});
+
+	test("deletes the message subtree, mailbox, and account over SQLite, emitting a removal event", async () => {
+		const entities: CascadeEntity[] = [
+			{ entityType: "Message", key: { messageId: MESSAGE_ID } },
+			{ entityType: "Envelope", key: { envelopeId: ENVELOPE_ID } },
+			{ entityType: "Mailbox", key: { mailboxId: MAILBOX_ID } },
+			{ entityType: "Account", key: { accountId: ACCOUNT_ID } },
+		];
+
+		const deleter = await createSqliteCascadeDeleter(filename);
+		await deleter(entities, log);
+
+		const sqlite = new Database(filename);
+		const count = (table: string, column: string, value: string): number =>
+			(
+				sqlite
+					.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE ${column} = ?`)
+					.get(value) as { n: number }
+			).n;
+
+		assert.equal(count("message", "message_id", MESSAGE_ID), 0, "message gone");
+		assert.equal(
+			count("envelope", "message_id", MESSAGE_ID),
+			0,
+			"envelope gone",
+		);
+		assert.equal(count("mailbox", "mailbox_id", MAILBOX_ID), 0, "mailbox gone");
+		assert.equal(count("account", "account_id", ACCOUNT_ID), 0, "account gone");
+
+		const outboxRows = (
+			sqlite.prepare("SELECT COUNT(*) AS n FROM outbox").get() as { n: number }
+		).n;
+		assert.ok(
+			outboxRows >= 1,
+			"a message-removed outbox row must be emitted for search-index cleanup",
+		);
+		sqlite.close();
+	});
+});