@beignet/provider-db-drizzle 0.0.32 → 0.0.34

package/src/shared/idempotency-core.ts

@@ -175,11 +175,15 @@ export function createIdempotencyPortCore(
     const expiresAt = resolveIdempotencyExpiresAt(input.ttlSec, now);
     const storageKey = createIdempotencyStorageKey(input);
     const scopeKey = normalizeIdempotencyScope(input.scope);
-
-    await tx.run(sql`delete from ${tx.table}
-      where storage_key = ${storageKey}
-        and expires_at is not null
-        and expires_at <= ${nowIso}`);
+    const reserved = (): IdempotencyReservation => ({
+      status: "reserved",
+      namespace: input.namespace,
+      key: input.key,
+      scopeKey,
+      fingerprint: input.fingerprint,
+      reservedAt: now,
+      expiresAt,
+    });
 
     const rowsAffected = await tx.run(sql`${tx.insertPrefix} ${tx.table} (
       storage_key,
@@ -208,15 +212,30 @@ export function createIdempotencyPortCore(
     )${tx.insertConflictSuffix}`);
 
     if (rowsAffected === undefined || rowsAffected > 0) {
-      return {
-        status: "reserved",
-        namespace: input.namespace,
-        key: input.key,
-        scopeKey,
-        fingerprint: input.fingerprint,
-        reservedAt: now,
-        expiresAt,
-      };
+      return reserved();
+    }
+
+    // Reset an expired reservation in place after the insert conflict. Doing
+    // this after the insert avoids MySQL gap-lock deadlocks when several
+    // transactions reserve the same previously missing storage key.
+    const expiredRowsAffected = await tx.run(sql`update ${tx.table}
+      set
+        namespace = ${input.namespace},
+        idempotency_key = ${input.key},
+        scope_key = ${scopeKey},
+        fingerprint = ${input.fingerprint},
+        status = 'in-progress',
+        result_json = null,
+        reserved_at = ${nowIso},
+        completed_at = null,
+        expires_at = ${expiresAt ? encodeTimestamp(expiresAt) : null},
+        updated_at = ${nowIso}
+      where storage_key = ${storageKey}
+        and expires_at is not null
+        and expires_at <= ${nowIso}`);
+
+    if (expiredRowsAffected !== undefined && expiredRowsAffected > 0) {
+      return reserved();
     }
 
     const row = (await tx.row(

package/src/shared/outbox-core.ts

@@ -13,11 +13,20 @@ import {
   type ClaimedOutboxMessage,
   createOutboxMessage,
   DEFAULT_OUTBOX_LEASE_MS,
+  OutboxAdminError,
+  type OutboxAdminPort,
   OutboxClaimError,
+  type OutboxCountMessagesOptions,
+  type OutboxDeleteResult,
   type OutboxEnqueueInput,
+  type OutboxListMessagesOptions,
   type OutboxMessage,
+  type OutboxMessageQuery,
   type OutboxMessageStatus,
   type OutboxPort,
+  type OutboxPruneDeliveredInput,
+  type OutboxPurgeDeadLetteredInput,
+  type OutboxRequeueMessageInput,
   serializeOutboxError,
 } from "@beignet/core/outbox";
 import { type SQL, sql } from "drizzle-orm";
@@ -25,6 +34,7 @@ import {
   encodeTimestamp,
   type OutboxRow,
   rowToClaimedMessage,
+  rowToMessage,
 } from "./rows.js";
 
 /**
@@ -93,6 +103,24 @@ function nowFrom(options: OutboxPortCoreOptions): Date {
   return options.now?.() ?? new Date();
 }
 
+function assertNonEmptyString(name: string, value: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function assertValidDate(name: string, value: Date): void {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new Error(`${name} must be a valid Date`);
+  }
+}
+
 function createClaimToken(): string {
   return crypto.randomUUID();
 }
@@ -107,6 +135,124 @@ async function getOutboxRow(
   return row as OutboxRow | undefined;
 }
 
+function normalizeStatusFilter(
+  status: OutboxMessageQuery["status"],
+): readonly OutboxMessageStatus[] | undefined {
+  if (status === undefined) return undefined;
+  if (typeof status === "string") return [status];
+  return status;
+}
+
+function orConditions(conditions: readonly SQL[]): SQL {
+  if (conditions.length === 0) return sql`1 = 0`;
+  let condition = conditions[0] ?? sql`1 = 0`;
+  for (const next of conditions.slice(1)) {
+    condition = sql`${condition} or ${next}`;
+  }
+  return sql`(${condition})`;
+}
+
+function andConditions(conditions: readonly SQL[]): SQL {
+  let condition = conditions[0] ?? sql`1 = 1`;
+  for (const next of conditions.slice(1)) {
+    condition = sql`${condition} and ${next}`;
+  }
+  return condition;
+}
+
+function whereClause(conditions: readonly SQL[]): SQL {
+  if (conditions.length === 0) return sql.raw("");
+  return sql` where ${andConditions(conditions)}`;
+}
+
+function messageQueryConditions(query: OutboxMessageQuery = {}): SQL[] {
+  const conditions: SQL[] = [];
+  const statuses = normalizeStatusFilter(query.status);
+  if (statuses !== undefined) {
+    conditions.push(
+      orConditions(statuses.map((status) => sql`status = ${status}`)),
+    );
+  }
+  if (query.kind !== undefined) conditions.push(sql`kind = ${query.kind}`);
+  if (query.name !== undefined) {
+    assertNonEmptyString("name", query.name);
+    conditions.push(sql`name = ${query.name}`);
+  }
+  if (query.updatedBefore !== undefined) {
+    assertValidDate("updatedBefore", query.updatedBefore);
+    conditions.push(sql`updated_at < ${encodeTimestamp(query.updatedBefore)}`);
+  }
+  if (query.deliveredBefore !== undefined) {
+    assertValidDate("deliveredBefore", query.deliveredBefore);
+    conditions.push(sql`delivered_at is not null`);
+    conditions.push(
+      sql`delivered_at < ${encodeTimestamp(query.deliveredBefore)}`,
+    );
+  }
+  return conditions;
+}
+
+function readCount(row: Record<string, unknown> | undefined): number {
+  const value = row?.count;
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string") return Number(value);
+  return 0;
+}
+
+function adminListLimit(limit: number | undefined): number {
+  const resolved = limit ?? 50;
+  assertPositiveInteger("limit", resolved);
+  return resolved;
+}
+
+async function countRows(
+  executor: OutboxSqlExecutor,
+  conditions: readonly SQL[],
+): Promise<number> {
+  const row = await executor.row(
+    sql`select count(*) as count from ${executor.table}${whereClause(conditions)}`,
+  );
+  return readCount(row);
+}
+
+function limitedDeleteQuery(
+  executor: OutboxSqlExecutor,
+  conditions: readonly SQL[],
+  limit: number | undefined,
+  orderBy: SQL,
+): SQL {
+  const where = whereClause(conditions);
+  if (limit === undefined) {
+    return sql`delete from ${executor.table}${where}`;
+  }
+
+  return sql`delete from ${executor.table}
+    where id in (
+      select id from (
+        select id from ${executor.table}${where}
+        order by ${orderBy}
+        limit ${limit}
+      ) as beignet_outbox_admin_delete
+    )`;
+}
+
+async function deleteRows(
+  executor: OutboxSqlExecutor,
+  conditions: readonly SQL[],
+  limit: number | undefined,
+  orderBy: SQL = sql`updated_at asc, created_at asc, id asc`,
+): Promise<OutboxDeleteResult> {
+  if (limit !== undefined) assertPositiveInteger("limit", limit);
+  const expected = await countRows(executor, conditions);
+  const cappedExpected =
+    limit === undefined ? expected : Math.min(expected, limit);
+  const rowsAffected = await executor.run(
+    limitedDeleteQuery(executor, conditions, limit, orderBy),
+  );
+  return { deleted: rowsAffected ?? cappedExpected };
+}
+
 function assertClaimedRowSucceeded(
   row: OutboxRow | undefined,
   input: { id: string; expectedStatus: OutboxMessageStatus },
@@ -320,3 +466,135 @@ export function createOutboxPortCore(
     },
   };
 }
+
+/**
+ * Create the dialect-independent outbox admin port orchestration on top of a
+ * dialect's `OutboxSqlExecutor`.
+ */
+export function createOutboxAdminPortCore(
+  executor: OutboxSqlExecutor,
+  options: OutboxPortCoreOptions = {},
+): OutboxAdminPort {
+  return {
+    async listMessages(
+      input: OutboxListMessagesOptions = {},
+    ): Promise<readonly OutboxMessage[]> {
+      const limit = adminListLimit(input.limit);
+      const conditions = messageQueryConditions(input);
+      const rows =
+        (await executor.rows(sql`select * from ${executor.table}${whereClause(
+          conditions,
+        )}
+        order by updated_at desc, created_at desc, id desc
+        limit ${limit}`)) as unknown as OutboxRow[];
+
+      return rows.map(rowToMessage);
+    },
+
+    async countMessages(
+      input: OutboxCountMessagesOptions = {},
+    ): Promise<number> {
+      return countRows(executor, messageQueryConditions(input));
+    },
+
+    async getMessage(id: string): Promise<OutboxMessage | null> {
+      assertNonEmptyString("id", id);
+      const row = await getOutboxRow(executor, id);
+      return row ? rowToMessage(row) : null;
+    },
+
+    async requeueMessage(
+      input: OutboxRequeueMessageInput,
+    ): Promise<OutboxMessage> {
+      assertNonEmptyString("id", input.id);
+      const existing = await getOutboxRow(executor, input.id);
+      if (!existing) {
+        throw new OutboxAdminError({
+          id: input.id,
+          message: `Outbox message "${input.id}" does not exist.`,
+        });
+      }
+      if (existing.status !== "deadLettered") {
+        throw new OutboxAdminError({
+          id: input.id,
+          message: `Outbox message "${input.id}" is not dead-lettered.`,
+        });
+      }
+
+      const now = input.now ?? nowFrom(options);
+      const availableAt = input.availableAt ?? now;
+      assertValidDate("now", now);
+      assertValidDate("availableAt", availableAt);
+      const nowIso = encodeTimestamp(now);
+      const availableAtIso = encodeTimestamp(availableAt);
+
+      const rowsAffected = input.resetAttempts
+        ? await executor.run(sql`update ${executor.table}
+            set
+              status = 'pending',
+              attempts = 0,
+              available_at = ${availableAtIso},
+              claimed_at = null,
+              locked_until = null,
+              claim_token = null,
+              updated_at = ${nowIso}
+            where id = ${input.id} and status = 'deadLettered'`)
+        : await executor.run(sql`update ${executor.table}
+            set
+              status = 'pending',
+              available_at = ${availableAtIso},
+              claimed_at = null,
+              locked_until = null,
+              claim_token = null,
+              updated_at = ${nowIso}
+            where id = ${input.id} and status = 'deadLettered'`);
+
+      if (rowsAffected !== undefined && rowsAffected <= 0) {
+        throw new OutboxAdminError({
+          id: input.id,
+          message: `Outbox message "${input.id}" could not be requeued because it changed state.`,
+        });
+      }
+
+      const requeued = await getOutboxRow(executor, input.id);
+      if (!requeued) {
+        throw new OutboxAdminError({
+          id: input.id,
+          message: `Outbox message "${input.id}" could not be requeued because it no longer exists.`,
+        });
+      }
+
+      return rowToMessage(requeued);
+    },
+
+    async purgeDeadLettered(
+      input: OutboxPurgeDeadLetteredInput = {},
+    ): Promise<OutboxDeleteResult> {
+      const conditions: SQL[] = [sql`status = 'deadLettered'`];
+      if (input.before !== undefined) {
+        assertValidDate("before", input.before);
+        conditions.push(sql`updated_at < ${encodeTimestamp(input.before)}`);
+      }
+
+      return deleteRows(executor, conditions, input.limit);
+    },
+
+    async pruneDelivered(
+      input: OutboxPruneDeliveredInput,
+    ): Promise<OutboxDeleteResult> {
+      assertValidDate("before", input.before);
+      const conditions: SQL[] = [
+        sql`status = 'delivered'`,
+        sql`delivered_at is not null`,
+        sql`delivered_at < ${encodeTimestamp(input.before)}`,
+      ];
+
+      return deleteRows(
+        executor,
+        conditions,
+        input.limit,
+        sql`delivered_at asc, updated_at asc, created_at asc, id asc`,
+      );
+    },
+  };
+}

package/src/sqlite/index.ts

@@ -30,7 +30,7 @@
  */
 
 import type { IdempotencyPort } from "@beignet/core/idempotency";
-import type { OutboxPort } from "@beignet/core/outbox";
+import type { OutboxAdminPort, OutboxPort } from "@beignet/core/outbox";
 import {
   type AuditLogPort,
   type BufferedDomainEventRecorder,
@@ -63,6 +63,7 @@ import {
 import { quoteIdentifier } from "../shared/identifiers.js";
 import { createDbQueryLogger } from "../shared/instrumentation.js";
 import {
+  createOutboxAdminPortCore,
   createOutboxPortCore,
   type OutboxSqlExecutor,
   type SqlExecutorBase,
@@ -83,13 +84,6 @@ export interface DbPort<
    */
   drizzle: LibSQLDatabase<TSchema>;
 
-  /**
-   * Backwards-compatible alias for `drizzle`.
-   *
-   * @deprecated Use `drizzle` for the Drizzle ORM instance.
-   */
-  db: LibSQLDatabase<TSchema>;
-
   /**
    * The underlying libSQL client instance.
    * Use this for advanced operations not covered by Drizzle ORM.
@@ -123,6 +117,32 @@ export type DrizzleSqliteTransaction<
   TSchema extends Record<string, unknown> = Record<string, unknown>,
 > = LibSQLTransaction<TSchema, ExtractTablesWithRelations<TSchema>>;
 
+const sqliteTransactionTails = new WeakMap<object, Promise<void>>();
+
+/**
+ * Queue Beignet-owned transactions per Drizzle client. SQLite only permits one
+ * writer at a time, while the local libSQL driver otherwise exposes concurrent
+ * transaction attempts as SQLITE_BUSY instead of waiting for the active write.
+ */
+function runSerializedSqliteTransaction<Result>(
+  db: object,
+  transaction: () => Promise<Result>,
+): Promise<Result> {
+  const previous = sqliteTransactionTails.get(db) ?? Promise.resolve();
+  const result = previous.then(transaction);
+  const tail = result.then(
+    () => undefined,
+    () => undefined,
+  );
+  sqliteTransactionTails.set(db, tail);
+
+  return result.finally(() => {
+    if (sqliteTransactionTails.get(db) === tail) {
+      sqliteTransactionTails.delete(db);
+    }
+  });
+}
+
 async function checkSqliteHealth(client: Client): Promise<DbHealth> {
   try {
     await client.execute("select 1");
@@ -185,13 +205,15 @@ export function createDrizzleSqliteUnitOfWork<
     ): Promise<Result> {
       const events = createDomainEventRecorder();
 
-      const result = await options.db.transaction(async (tx) => {
-        const txPorts = options.createTransactionPorts(
-          tx as DrizzleSqliteTransaction<TSchema>,
-          events,
-        );
-        return work(txPorts);
-      }, options.transactionConfig);
+      const result = await runSerializedSqliteTransaction(options.db, () =>
+        options.db.transaction(async (tx) => {
+          const txPorts = options.createTransactionPorts(
+            tx as DrizzleSqliteTransaction<TSchema>,
+            events,
+          );
+          return work(txPorts);
+        }, options.transactionConfig),
+      );
 
       if (options.eventBus) {
         await events.flush(options.eventBus);
@@ -336,6 +358,11 @@ function createSqliteExecutor<TSchema extends Record<string, unknown>>(
     },
 
     async row(query) {
+      if ("all" in db && typeof db.all === "function") {
+        const rows = await db.all<Record<string, unknown>>(query);
+        return rows[0];
+      }
+
       return db.get<Record<string, unknown> | undefined>(query);
     },
 
@@ -345,8 +372,12 @@ function createSqliteExecutor<TSchema extends Record<string, unknown>>(
 
     withTransaction(fn) {
       if ("transaction" in db && typeof db.transaction === "function") {
-        return db.transaction((tx) =>
-          fn(createSqliteExecutor(tx as DrizzleSqliteDatabase<TSchema>, table)),
+        return runSerializedSqliteTransaction(db, () =>
+          db.transaction((tx) =>
+            fn(
+              createSqliteExecutor(tx as DrizzleSqliteDatabase<TSchema>, table),
+            ),
+          ),
         );
       }
 
@@ -411,6 +442,26 @@ export function createDrizzleSqliteOutboxPort<
   return createOutboxPortCore(executor, { now: adapterOptions.now });
 }
 
+/**
+ * Create a Beignet outbox admin port backed by a Drizzle SQLite database.
+ *
+ * Wire this only into operational contexts that need to inspect, requeue,
+ * purge, or prune outbox messages.
+ */
+export function createDrizzleSqliteOutboxAdminPort<
+  TSchema extends Record<string, unknown>,
+>(
+  db: DrizzleSqliteDatabase<TSchema>,
+  adapterOptions: DrizzleSqliteOutboxOptions = {},
+): OutboxAdminPort {
+  const table = sql.raw(
+    quoteIdentifier(adapterOptions.tableName ?? "outbox_messages", '"'),
+  );
+  const executor: OutboxSqlExecutor = createSqliteExecutor(db, table);
+
+  return createOutboxAdminPortCore(executor, { now: adapterOptions.now });
+}
+
 /**
  * Options for a Drizzle SQLite-backed idempotency port.
  */
@@ -645,7 +696,6 @@ export function createDrizzleSqliteProvider<
       // 3. Build a typed DbPort
       const dbPort: DbPort<TSchema> = {
         drizzle: db,
-        db,
         client,
         checkHealth: () => checkSqliteHealth(client),
       };