@holo-js/queue-db 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import { Dialect, DatabaseContext } from '@holo-js/db';
+import * as _holo_js_queue from '@holo-js/queue';
+import { QueueJsonValue, QueueFailedJobRecord, QueueJobEnvelope, QueueAsyncDriver, NormalizedQueueDatabaseConnectionConfig, QueueDriverFactoryContext, QueueDriverDispatchResult, QueueReservedJob, QueueReleaseOptions, QueueDriverFactory, QueueFailedJobStore } from '@holo-js/queue';
+
+type StoredQueueJobRow = {
+    id: unknown;
+    job: unknown;
+    connection: unknown;
+    queue: unknown;
+    payload: unknown;
+    attempts: unknown;
+    max_attempts: unknown;
+    available_at?: unknown;
+    created_at: unknown;
+};
+type StoredFailedQueueJobRow = {
+    id: unknown;
+    job_id: unknown;
+    payload: unknown;
+    exception: unknown;
+    failed_at: unknown;
+};
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function assertQueueJsonValue(value: unknown, path: string, seen?: Set<unknown>): asserts value is QueueJsonValue;
+declare function normalizeIdentifierPath(value: string, label: string): string;
+declare function quoteIdentifierPath(dialect: Dialect, path: string): string;
+declare function createPlaceholderList(dialect: Dialect, count: number, startIndex?: number): string;
+declare function coerceRequiredString(value: unknown, label: string): string;
+declare function coerceRequiredInteger(value: unknown, label: string): number;
+declare function coerceOptionalInteger(value: unknown, label: string): number | undefined;
+declare function parseStoredPayload(value: unknown, label: string): QueueJsonValue;
+declare function parseStoredQueueJobRow(row: StoredQueueJobRow): QueueJobEnvelope<QueueJsonValue>;
+declare function parseStoredQueueEnvelope(value: unknown): QueueJobEnvelope<QueueJsonValue>;
+declare function parseStoredFailedQueueJobRow(row: StoredFailedQueueJobRow): QueueFailedJobRecord;
+declare function serializeQueueJson(value: unknown): string;
+declare function ensureConnectionReady(connection: DatabaseContext): Promise<DatabaseContext>;
+
+declare const queueDatabaseInternals: {
+    assertQueueJsonValue: typeof assertQueueJsonValue;
+    coerceOptionalInteger: typeof coerceOptionalInteger;
+    coerceRequiredInteger: typeof coerceRequiredInteger;
+    coerceRequiredString: typeof coerceRequiredString;
+    createPlaceholderList: typeof createPlaceholderList;
+    ensureConnectionReady: typeof ensureConnectionReady;
+    isPlainObject: typeof isPlainObject;
+    normalizeIdentifierPath: typeof normalizeIdentifierPath;
+    parseStoredFailedQueueJobRow: typeof parseStoredFailedQueueJobRow;
+    parseStoredQueueEnvelope: typeof parseStoredQueueEnvelope;
+    parseStoredPayload: typeof parseStoredPayload;
+    parseStoredQueueJobRow: typeof parseStoredQueueJobRow;
+    quoteIdentifierPath: typeof quoteIdentifierPath;
+    serializeQueueJson: typeof serializeQueueJson;
+};
+
+declare function normalizeDatabaseErrorMessage(error: unknown): string;
+declare class DatabaseQueueDriverError extends Error {
+    constructor(connectionName: string, action: string, cause: unknown);
+}
+declare function wrapDatabaseError(connectionName: string, action: string, error: unknown): DatabaseQueueDriverError;
+declare function normalizeQueueNames(queueNames: readonly string[] | undefined, fallbackQueueName: string): readonly string[];
+declare class DatabaseQueueDriver implements QueueAsyncDriver {
+    private readonly connection;
+    private readonly context;
+    readonly name: string;
+    readonly driver: "database";
+    readonly mode: "async";
+    private readonly tableName;
+    constructor(connection: NormalizedQueueDatabaseConnectionConfig, context: QueueDriverFactoryContext);
+    private getConnection;
+    private getQuotedTable;
+    private getExpiredReservationCutoff;
+    private createReservedJob;
+    dispatch<TPayload extends QueueJsonValue = QueueJsonValue, TResult = unknown>(job: QueueJobEnvelope<TPayload>): Promise<QueueDriverDispatchResult<TResult>>;
+    reserve<TPayload extends QueueJsonValue = QueueJsonValue>(input: {
+        readonly queueNames: readonly string[];
+        readonly workerId: string;
+    }): Promise<QueueReservedJob<TPayload> | null>;
+    acknowledge(job: QueueReservedJob): Promise<void>;
+    release(job: QueueReservedJob, options?: QueueReleaseOptions): Promise<void>;
+    delete(job: QueueReservedJob): Promise<void>;
+    clear(input?: {
+        readonly queueNames?: readonly string[];
+    }): Promise<number>;
+    close(): Promise<void>;
+}
+declare const databaseQueueDriverFactory: QueueDriverFactory<NormalizedQueueDatabaseConnectionConfig>;
+declare const databaseQueueDriverInternals: {
+    normalizeDatabaseErrorMessage: typeof normalizeDatabaseErrorMessage;
+    normalizeQueueNames: typeof normalizeQueueNames;
+    wrapDatabaseError: typeof wrapDatabaseError;
+};
+
+declare function getFailedStoreConfig(): false | _holo_js_queue.NormalizedQueueFailedStoreConfig;
+declare function getFailedStoreConnection(): Promise<{
+    connection: DatabaseContext;
+    tableName: string;
+} | null>;
+declare const queueDbFailedJobStore: QueueFailedJobStore;
+declare const queueDbFailedStoreInternals: {
+    getFailedStoreConfig: typeof getFailedStoreConfig;
+    getFailedStoreConnection: typeof getFailedStoreConnection;
+};
+
+declare function createQueueDbRuntimeOptions(): Readonly<{
+    driverFactories: _holo_js_queue.QueueDriverFactory<_holo_js_queue.NormalizedQueueDatabaseConnectionConfig>[];
+    failedJobStore: _holo_js_queue.QueueFailedJobStore;
+}>;
+
+export { DatabaseQueueDriver, DatabaseQueueDriverError, type StoredFailedQueueJobRow, type StoredQueueJobRow, createQueueDbRuntimeOptions, databaseQueueDriverFactory, databaseQueueDriverInternals, queueDatabaseInternals, queueDbFailedJobStore, queueDbFailedStoreInternals };

package/dist/index.mjs

@@ -0,0 +1,516 @@
+// src/database.ts
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function assertQueueJsonValue(value, path, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`[Holo Queue] ${path} must be JSON-serializable.`);
+    }
+    return;
+  }
+  if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+    throw new TypeError(`[Holo Queue] ${path} must be JSON-serializable.`);
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      throw new TypeError(`[Holo Queue] ${path} contains a circular reference.`);
+    }
+    seen.add(value);
+    for (let index = 0; index < value.length; index += 1) {
+      assertQueueJsonValue(value[index], `${path}[${index}]`, seen);
+    }
+    seen.delete(value);
+    return;
+  }
+  if (!isPlainObject(value)) {
+    throw new TypeError(`[Holo Queue] ${path} must be a plain JSON object, array, or primitive.`);
+  }
+  if (seen.has(value)) {
+    throw new TypeError(`[Holo Queue] ${path} contains a circular reference.`);
+  }
+  seen.add(value);
+  for (const [key, nested] of Object.entries(value)) {
+    assertQueueJsonValue(nested, `${path}.${key}`, seen);
+  }
+  seen.delete(value);
+}
+function normalizeIdentifierPath(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`[Holo Queue] ${label} must be a non-empty string.`);
+  }
+  const segments = normalized.split(".");
+  if (segments.some((segment) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(segment))) {
+    throw new Error(`[Holo Queue] ${label} must contain only valid SQL identifier segments.`);
+  }
+  return normalized;
+}
+function quoteIdentifierPath(dialect, path) {
+  return normalizeIdentifierPath(path, "Queue table name").split(".").map((segment) => dialect.quoteIdentifier(segment)).join(".");
+}
+function createPlaceholderList(dialect, count, startIndex = 1) {
+  if (!Number.isInteger(count) || count < 1) {
+    throw new Error("[Holo Queue] Placeholder lists require at least one binding.");
+  }
+  return Array.from({ length: count }, (_, index) => dialect.createPlaceholder(startIndex + index)).join(", ");
+}
+function coerceRequiredString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`[Holo Queue] ${label} must be a non-empty string.`);
+  }
+  return value;
+}
+function coerceRequiredInteger(value, label) {
+  if (typeof value === "number") {
+    if (!Number.isInteger(value)) {
+      throw new Error(`[Holo Queue] ${label} must be an integer.`);
+    }
+    return value;
+  }
+  if (typeof value === "string" && /^-?\d+$/.test(value)) {
+    return Number.parseInt(value, 10);
+  }
+  throw new Error(`[Holo Queue] ${label} must be an integer.`);
+}
+function coerceOptionalInteger(value, label) {
+  if (value === null || typeof value === "undefined") {
+    return void 0;
+  }
+  return coerceRequiredInteger(value, label);
+}
+function parseStoredPayload(value, label) {
+  const serialized = coerceRequiredString(value, label);
+  const parsed = JSON.parse(serialized);
+  assertQueueJsonValue(parsed, label);
+  return parsed;
+}
+function parseStoredQueueJobRow(row) {
+  return Object.freeze({
+    id: coerceRequiredString(row.id, "Stored queue job id"),
+    name: coerceRequiredString(row.job, "Stored queue job name"),
+    connection: coerceRequiredString(row.connection, "Stored queue job connection"),
+    queue: coerceRequiredString(row.queue, "Stored queue job queue"),
+    payload: parseStoredPayload(row.payload, "Stored queue job payload"),
+    attempts: coerceRequiredInteger(row.attempts, "Stored queue job attempts"),
+    maxAttempts: coerceRequiredInteger(row.max_attempts, "Stored queue job max attempts"),
+    ...typeof row.available_at === "undefined" || row.available_at === null ? {} : { availableAt: coerceRequiredInteger(row.available_at, "Stored queue job availability") },
+    createdAt: coerceRequiredInteger(row.created_at, "Stored queue job creation time")
+  });
+}
+function parseStoredQueueEnvelope(value) {
+  if (!isPlainObject(value)) {
+    throw new Error("[Holo Queue] Stored queue job payload must serialize a queue job envelope object.");
+  }
+  const record = value;
+  return Object.freeze({
+    id: coerceRequiredString(record.id, "Stored queue job id"),
+    name: coerceRequiredString(record.name, "Stored queue job name"),
+    connection: coerceRequiredString(record.connection, "Stored queue job connection"),
+    queue: coerceRequiredString(record.queue, "Stored queue job queue"),
+    payload: (() => {
+      assertQueueJsonValue(record.payload, "Stored queue job payload");
+      return record.payload;
+    })(),
+    attempts: coerceRequiredInteger(record.attempts, "Stored queue job attempts"),
+    maxAttempts: coerceRequiredInteger(record.maxAttempts, "Stored queue job max attempts"),
+    ...typeof record.availableAt === "undefined" || record.availableAt === null ? {} : { availableAt: coerceRequiredInteger(record.availableAt, "Stored queue job availability") },
+    createdAt: coerceRequiredInteger(record.createdAt, "Stored queue job creation time")
+  });
+}
+function parseStoredFailedQueueJobRow(row) {
+  return Object.freeze({
+    id: coerceRequiredString(row.id, "Stored failed job id"),
+    jobId: coerceRequiredString(row.job_id, "Stored failed job job id"),
+    job: parseStoredQueueEnvelope(parseStoredPayload(row.payload, "Stored failed job payload")),
+    exception: coerceRequiredString(row.exception, "Stored failed job exception"),
+    failedAt: coerceRequiredInteger(row.failed_at, "Stored failed job timestamp")
+  });
+}
+function serializeQueueJson(value) {
+  assertQueueJsonValue(value, "Queue JSON payload");
+  return JSON.stringify(value);
+}
+async function ensureConnectionReady(connection) {
+  await connection.initialize();
+  return connection;
+}
+var queueDatabaseInternals = {
+  assertQueueJsonValue,
+  coerceOptionalInteger,
+  coerceRequiredInteger,
+  coerceRequiredString,
+  createPlaceholderList,
+  ensureConnectionReady,
+  isPlainObject,
+  normalizeIdentifierPath,
+  parseStoredFailedQueueJobRow,
+  parseStoredQueueEnvelope,
+  parseStoredPayload,
+  parseStoredQueueJobRow,
+  quoteIdentifierPath,
+  serializeQueueJson
+};
+
+// src/drivers/database.ts
+import { randomUUID } from "crypto";
+import { DB } from "@holo-js/db";
+function normalizeDatabaseErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+var DatabaseQueueDriverError = class extends Error {
+  constructor(connectionName, action, cause) {
+    super(
+      `[Holo Queue] Database queue connection "${connectionName}" failed to ${action}: ${normalizeDatabaseErrorMessage(cause)}`,
+      { cause }
+    );
+    this.name = "DatabaseQueueDriverError";
+  }
+};
+function wrapDatabaseError(connectionName, action, error) {
+  if (error instanceof DatabaseQueueDriverError) {
+    return error;
+  }
+  return new DatabaseQueueDriverError(connectionName, action, error);
+}
+function normalizeQueueNames(queueNames, fallbackQueueName) {
+  if (!queueNames || queueNames.length === 0) {
+    return Object.freeze([fallbackQueueName]);
+  }
+  const normalized = [...new Set(queueNames.map((name) => name.trim()).filter(Boolean))];
+  return Object.freeze(normalized.length > 0 ? normalized : [fallbackQueueName]);
+}
+function createPlaceholders(connection, count, startIndex = 1) {
+  return queueDatabaseInternals.createPlaceholderList(connection.getDialect(), count, startIndex).split(", ");
+}
+var DatabaseQueueDriver = class {
+  constructor(connection, context) {
+    this.connection = connection;
+    this.context = context;
+    this.name = connection.name;
+    this.tableName = queueDatabaseInternals.normalizeIdentifierPath(connection.table, "Queue table name");
+  }
+  name;
+  driver = "database";
+  mode = "async";
+  tableName;
+  async getConnection() {
+    return queueDatabaseInternals.ensureConnectionReady(DB.connection(this.connection.connection));
+  }
+  getQuotedTable(connection) {
+    return queueDatabaseInternals.quoteIdentifierPath(connection.getDialect(), this.tableName);
+  }
+  getExpiredReservationCutoff(now) {
+    return now - this.connection.retryAfter * 1e3;
+  }
+  createReservedJob(row, reservationId, reservedAt) {
+    return Object.freeze({
+      reservationId,
+      reservedAt,
+      envelope: queueDatabaseInternals.parseStoredQueueJobRow(row)
+    });
+  }
+  async dispatch(job) {
+    try {
+      const connection = await this.getConnection();
+      const quotedTable = this.getQuotedTable(connection);
+      const placeholders = createPlaceholders(connection, 9);
+      await connection.executeCompiled({
+        sql: `INSERT INTO ${quotedTable} (id, job, connection, queue, payload, attempts, max_attempts, available_at, created_at) VALUES (${placeholders.join(", ")})`,
+        bindings: [
+          job.id,
+          job.name,
+          job.connection,
+          job.queue,
+          queueDatabaseInternals.serializeQueueJson(job.payload),
+          job.attempts,
+          job.maxAttempts,
+          job.availableAt ?? job.createdAt,
+          job.createdAt
+        ],
+        source: `queue:${this.name}:dispatch`
+      });
+      return {
+        jobId: job.id,
+        synchronous: false
+      };
+    } catch (error) {
+      throw wrapDatabaseError(this.name, "enqueue job", error);
+    }
+  }
+  async reserve(input) {
+    try {
+      const connection = await this.getConnection();
+      const quotedTable = this.getQuotedTable(connection);
+      const queueNames = normalizeQueueNames(input.queueNames, this.connection.queue);
+      return await connection.transaction(async (tx) => {
+        for (const queueName of queueNames) {
+          while (true) {
+            const now = Date.now();
+            const expiredReservationCutoff = this.getExpiredReservationCutoff(now);
+            const [queuePlaceholder, availablePlaceholder, expiredPlaceholder] = createPlaceholders(tx, 3);
+            const selected = await tx.queryCompiled({
+              sql: `SELECT id, job, connection, queue, payload, attempts, max_attempts, available_at, created_at FROM ${quotedTable} WHERE queue = ${queuePlaceholder} AND available_at <= ${availablePlaceholder} AND (reserved_at IS NULL OR reserved_at <= ${expiredPlaceholder}) ORDER BY available_at ASC, created_at ASC, id ASC LIMIT 1`,
+              bindings: [queueName, now, expiredReservationCutoff],
+              source: `queue:${this.name}:reserve:select`
+            });
+            const row = selected.rows[0];
+            if (!row) {
+              break;
+            }
+            const reservationId = `${input.workerId}:${randomUUID()}`;
+            const nextAttempts = queueDatabaseInternals.coerceRequiredInteger(row.attempts, "Stored queue job attempts") + 1;
+            const [
+              reservedAtPlaceholder,
+              reservationPlaceholder,
+              attemptsPlaceholder,
+              idPlaceholder,
+              queueNamePlaceholder,
+              expiredCutoffPlaceholder
+            ] = createPlaceholders(tx, 6);
+            const updated = await tx.executeCompiled({
+              sql: `UPDATE ${quotedTable} SET reserved_at = ${reservedAtPlaceholder}, reservation_id = ${reservationPlaceholder}, attempts = ${attemptsPlaceholder} WHERE id = ${idPlaceholder} AND queue = ${queueNamePlaceholder} AND (reserved_at IS NULL OR reserved_at <= ${expiredCutoffPlaceholder})`,
+              bindings: [now, reservationId, nextAttempts, row.id, queueName, expiredReservationCutoff],
+              source: `queue:${this.name}:reserve:update`
+            });
+            if ((updated.affectedRows ?? 0) === 1) {
+              return this.createReservedJob(row, reservationId, now);
+            }
+          }
+        }
+        return null;
+      });
+    } catch (error) {
+      throw wrapDatabaseError(this.name, "reserve job", error);
+    }
+  }
+  async acknowledge(job) {
+    try {
+      const connection = await this.getConnection();
+      const quotedTable = this.getQuotedTable(connection);
+      const [idPlaceholder, reservationPlaceholder] = createPlaceholders(connection, 2);
+      await connection.executeCompiled({
+        sql: `DELETE FROM ${quotedTable} WHERE id = ${idPlaceholder} AND reservation_id = ${reservationPlaceholder}`,
+        bindings: [job.envelope.id, job.reservationId],
+        source: `queue:${this.name}:acknowledge`
+      });
+    } catch (error) {
+      throw wrapDatabaseError(this.name, "acknowledge job", error);
+    }
+  }
+  async release(job, options) {
+    try {
+      const connection = await this.getConnection();
+      const quotedTable = this.getQuotedTable(connection);
+      const now = Date.now();
+      const availableAt = now + (options?.delaySeconds ?? 0) * 1e3;
+      const [availablePlaceholder, idPlaceholder, reservationPlaceholder] = createPlaceholders(connection, 3);
+      await connection.executeCompiled({
+        sql: `UPDATE ${quotedTable} SET reserved_at = NULL, reservation_id = NULL, available_at = ${availablePlaceholder} WHERE id = ${idPlaceholder} AND reservation_id = ${reservationPlaceholder}`,
+        bindings: [availableAt, job.envelope.id, job.reservationId],
+        source: `queue:${this.name}:release`
+      });
+    } catch (error) {
+      throw wrapDatabaseError(this.name, "release job", error);
+    }
+  }
+  async delete(job) {
+    try {
+      const connection = await this.getConnection();
+      const quotedTable = this.getQuotedTable(connection);
+      const [idPlaceholder, reservationPlaceholder] = createPlaceholders(connection, 2);
+      await connection.executeCompiled({
+        sql: `DELETE FROM ${quotedTable} WHERE id = ${idPlaceholder} AND reservation_id = ${reservationPlaceholder}`,
+        bindings: [job.envelope.id, job.reservationId],
+        source: `queue:${this.name}:delete`
+      });
+    } catch (error) {
+      throw wrapDatabaseError(this.name, "delete job", error);
+    }
+  }
+  async clear(input) {
+    try {
+      const connection = await this.getConnection();
+      const quotedTable = this.getQuotedTable(connection);
+      const queueNames = normalizeQueueNames(input?.queueNames, this.connection.queue);
+      const now = Date.now();
+      const expiredReservationCutoff = this.getExpiredReservationCutoff(now);
+      const conditions = [
+        `queue IN (${createPlaceholders(connection, queueNames.length).join(", ")})`,
+        `(reserved_at IS NULL OR reserved_at <= ${connection.getDialect().createPlaceholder(queueNames.length + 1)})`
+      ];
+      const result = await connection.executeCompiled({
+        sql: `DELETE FROM ${quotedTable} WHERE ${conditions.join(" AND ")}`,
+        bindings: [...queueNames, expiredReservationCutoff],
+        source: `queue:${this.name}:clear`
+      });
+      return result.affectedRows ?? 0;
+    } catch (error) {
+      throw wrapDatabaseError(this.name, "clear queued jobs", error);
+    }
+  }
+  async close() {
+    void this.context;
+  }
+};
+var databaseQueueDriverFactory = {
+  driver: "database",
+  create(connection, context) {
+    return new DatabaseQueueDriver(connection, context);
+  }
+};
+var databaseQueueDriverInternals = {
+  normalizeDatabaseErrorMessage,
+  normalizeQueueNames,
+  wrapDatabaseError
+};
+
+// src/failed.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { DB as DB2 } from "@holo-js/db";
+import { getQueueRuntime } from "@holo-js/queue";
+function getFailedStoreConfig() {
+  return getQueueRuntime().config.failed;
+}
+async function getFailedStoreConnection() {
+  const config = getFailedStoreConfig();
+  if (config === false) {
+    return null;
+  }
+  const tableName = queueDatabaseInternals.normalizeIdentifierPath(config.table, "Failed jobs table name");
+  const connection = await queueDatabaseInternals.ensureConnectionReady(DB2.connection(config.connection));
+  return {
+    connection,
+    tableName
+  };
+}
+var queueDbFailedJobStore = {
+  async persistFailedJob(reserved, error) {
+    const failedStore = await getFailedStoreConnection();
+    if (!failedStore) {
+      return null;
+    }
+    const quotedTable = queueDatabaseInternals.quoteIdentifierPath(failedStore.connection.getDialect(), failedStore.tableName);
+    const placeholders = queueDatabaseInternals.createPlaceholderList(failedStore.connection.getDialect(), 7);
+    const record = Object.freeze({
+      id: randomUUID2(),
+      jobId: reserved.envelope.id,
+      job: reserved.envelope,
+      exception: error.stack || error.message,
+      failedAt: Date.now()
+    });
+    await failedStore.connection.executeCompiled({
+      sql: `INSERT INTO ${quotedTable} (id, job_id, job, connection, queue, payload, exception, failed_at) VALUES (${placeholders}, ${failedStore.connection.getDialect().createPlaceholder(8)})`,
+      bindings: [
+        record.id,
+        record.jobId,
+        reserved.envelope.name,
+        reserved.envelope.connection,
+        reserved.envelope.queue,
+        queueDatabaseInternals.serializeQueueJson(reserved.envelope),
+        record.exception,
+        record.failedAt
+      ],
+      source: "queue:failed:insert"
+    });
+    return record;
+  },
+  async listFailedJobs() {
+    const failedStore = await getFailedStoreConnection();
+    if (!failedStore) {
+      return Object.freeze([]);
+    }
+    const quotedTable = queueDatabaseInternals.quoteIdentifierPath(failedStore.connection.getDialect(), failedStore.tableName);
+    const result = await failedStore.connection.queryCompiled({
+      sql: `SELECT id, job_id, payload, exception, failed_at FROM ${quotedTable} ORDER BY failed_at DESC, id DESC`,
+      source: "queue:failed:list"
+    });
+    return Object.freeze(result.rows.map((row) => queueDatabaseInternals.parseStoredFailedQueueJobRow(row)));
+  },
+  async retryFailedJobs(identifier, retry) {
+    const failedStore = await getFailedStoreConnection();
+    if (!failedStore) {
+      return 0;
+    }
+    const quotedTable = queueDatabaseInternals.quoteIdentifierPath(failedStore.connection.getDialect(), failedStore.tableName);
+    const dialect = failedStore.connection.getDialect();
+    const records = await (identifier === "all" ? await this.listFailedJobs() : (() => {
+      const placeholder = dialect.createPlaceholder(1);
+      return failedStore.connection.queryCompiled({
+        sql: `SELECT id, job_id, payload, exception, failed_at FROM ${quotedTable} WHERE id = ${placeholder}`,
+        bindings: [identifier],
+        source: "queue:failed:load"
+      }).then((result) => Object.freeze(result.rows.map((row) => queueDatabaseInternals.parseStoredFailedQueueJobRow(row))));
+    })());
+    let retried = 0;
+    for (const record of records) {
+      await retry(record);
+      const placeholder = dialect.createPlaceholder(1);
+      await failedStore.connection.executeCompiled({
+        sql: `DELETE FROM ${quotedTable} WHERE id = ${placeholder}`,
+        bindings: [record.id],
+        source: "queue:failed:forget-after-retry"
+      });
+      retried += 1;
+    }
+    return retried;
+  },
+  async forgetFailedJob(id) {
+    const failedStore = await getFailedStoreConnection();
+    if (!failedStore) {
+      return false;
+    }
+    const quotedTable = queueDatabaseInternals.quoteIdentifierPath(failedStore.connection.getDialect(), failedStore.tableName);
+    const placeholder = failedStore.connection.getDialect().createPlaceholder(1);
+    const result = await failedStore.connection.executeCompiled({
+      sql: `DELETE FROM ${quotedTable} WHERE id = ${placeholder}`,
+      bindings: [id],
+      source: "queue:failed:forget"
+    });
+    return (result.affectedRows ?? 0) > 0;
+  },
+  async flushFailedJobs() {
+    const failedStore = await getFailedStoreConnection();
+    if (!failedStore) {
+      return 0;
+    }
+    const quotedTable = queueDatabaseInternals.quoteIdentifierPath(failedStore.connection.getDialect(), failedStore.tableName);
+    const result = await failedStore.connection.executeCompiled({
+      sql: `DELETE FROM ${quotedTable}`,
+      source: "queue:failed:flush"
+    });
+    return result.affectedRows ?? 0;
+  }
+};
+var queueDbFailedStoreInternals = {
+  getFailedStoreConfig,
+  getFailedStoreConnection
+};
+
+// src/runtime.ts
+function createQueueDbRuntimeOptions() {
+  return Object.freeze({
+    driverFactories: [databaseQueueDriverFactory],
+    failedJobStore: queueDbFailedJobStore
+  });
+}
+export {
+  DatabaseQueueDriver,
+  DatabaseQueueDriverError,
+  createQueueDbRuntimeOptions,
+  databaseQueueDriverFactory,
+  databaseQueueDriverInternals,
+  queueDatabaseInternals,
+  queueDbFailedJobStore,
+  queueDbFailedStoreInternals
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@holo-js/queue-db",
+  "version": "0.1.0",
+  "description": "Holo-JS Framework - DB-backed integrations for @holo-js/queue",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "stub": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest --run"
+  },
+  "dependencies": {
+    "@holo-js/db": "workspace:*",
+    "@holo-js/queue": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "tsup": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}