Add MariaDB queue table. Fix Bugs

dist/types/index.d.ts

@@ -74,6 +74,24 @@ export interface BUN_MARIADB_TableSchemaType {
      */
     childTableDbId?: string | number;
     collation?: (typeof MariaDBCollations)[number];
+    /**
+     * Make this table a job queue. Adds the `QueueFields` columns and
+     * `QueueIndexes`, and routes state changes through `BunMariaDB.queue`.
+     * Pass an options object to set the queue's defaults.
+     */
+    queue_table?: boolean | BUN_MARIADB_QueueTableOptions;
+}
+/**
+ * Defaults for a queue table. Per-call arguments to `BunMariaDB.queue`
+ * override them.
+ */
+export interface BUN_MARIADB_QueueTableOptions {
+    /** Attempts before a job is marked `failed`. Defaults to 5 */
+    max_attempts?: number;
+    /** How long a claim lasts before another worker may take the job. Defaults to 30s */
+    lease_ms?: number;
+    /** `ack` marks jobs `done` and keeps them instead of deleting them */
+    keep_completed?: boolean;
 }
 /**
  * Reference object used to link a table to one of its child tables.
@@ -1425,6 +1443,28 @@ export type BunMariaDBConfigReturn = {
  * Default fields automatically suggested for new tables.
  */
 export declare const DefaultFields: BUN_MARIADB_FieldSchemaType[];
+/**
+ * Lifecycle of a queue row. Only `pending` jobs are claimed.
+ * - `done`: acknowledged, kept because of `keep_completed` (otherwise deleted)
+ * - `failed`: used up its attempts (dead letter)
+ * - `cancelled`: removed from the queue with `queue.cancel`
+ */
+export declare const QueueStatuses: readonly ["pending", "processing", "done", "failed", "cancelled"];
+export type QueueStatus = (typeof QueueStatuses)[number];
+/**
+ * Fields added to every table with `queue_table: true`.
+ */
+export declare const QueueFields: BUN_MARIADB_FieldSchemaType[];
+/**
+ * Queue fields only the queue API may write. `queue_available_at` can be set
+ * on insert and update.
+ */
+export declare const QueueProtectedFields: readonly ["queue_status", "queue_attempts", "queue_lease_expires_at", "queue_lock_token", "queue_last_error"];
+/**
+ * Indexes added to queue tables. Claims scan `idx_queue_claim` in order, so
+ * `LIMIT` stops the scan early and only the claimed rows get locked.
+ */
+export declare const QueueIndexes: BUN_MARIADB_IndexSchemaType[];
 export type BunMariaDBQueryFieldValues<F extends string = string, T extends string = string> = {
     field: F;
     table?: T;

dist/types/index.js

@@ -235,6 +235,87 @@ export const DefaultFields = [
         fieldDescription: "The time when the record was updated. (Unix Timestamp)",
     },
 ];
+/**
+ * Lifecycle of a queue row. Only `pending` jobs are claimed.
+ * - `done`: acknowledged, kept because of `keep_completed` (otherwise deleted)
+ * - `failed`: used up its attempts (dead letter)
+ * - `cancelled`: removed from the queue with `queue.cancel`
+ */
+export const QueueStatuses = [
+    "pending",
+    "processing",
+    "done",
+    "failed",
+    "cancelled",
+];
+/**
+ * Fields added to every table with `queue_table: true`.
+ */
+export const QueueFields = [
+    {
+        fieldName: "queue_status",
+        dataType: "ENUM",
+        options: [...QueueStatuses],
+        notNullValue: true,
+        defaultValue: "pending",
+        fieldDescription: "Queue state of the job.",
+    },
+    {
+        fieldName: "queue_available_at",
+        dataType: "BIGINT",
+        notNullValue: true,
+        defaultValue: 0,
+        fieldDescription: "The job cannot be claimed before this time. (Unix Timestamp, ms)",
+    },
+    {
+        fieldName: "queue_attempts",
+        dataType: "INT",
+        notNullValue: true,
+        defaultValue: 0,
+        fieldDescription: "How many times the job has been claimed.",
+    },
+    {
+        fieldName: "queue_lease_expires_at",
+        dataType: "BIGINT",
+        fieldDescription: "When the current claim expires and the job can be reclaimed. (Unix Timestamp, ms)",
+    },
+    {
+        fieldName: "queue_lock_token",
+        dataType: "VARCHAR",
+        dataLength: 64,
+        fieldDescription: "Token of the current claim. Required to ack, fail or extend the job.",
+    },
+    {
+        fieldName: "queue_last_error",
+        dataType: "TEXT",
+        fieldDescription: "Error message from the last failed attempt.",
+    },
+];
+/**
+ * Queue fields only the queue API may write. `queue_available_at` can be set
+ * on insert and update.
+ */
+export const QueueProtectedFields = [
+    "queue_status",
+    "queue_attempts",
+    "queue_lease_expires_at",
+    "queue_lock_token",
+    "queue_last_error",
+];
+/**
+ * Indexes added to queue tables. Claims scan `idx_queue_claim` in order, so
+ * `LIMIT` stops the scan early and only the claimed rows get locked.
+ */
+export const QueueIndexes = [
+    {
+        indexName: "idx_queue_claim",
+        indexTableFields: ["queue_status", "queue_available_at"],
+    },
+    {
+        indexName: "idx_queue_lease",
+        indexTableFields: ["queue_status", "queue_lease_expires_at"],
+    },
+];
 export const RequiredENVs = [
     "BUN_MARIADB_SERVER_HOST",
     "BUN_MARIADB_SERVER_PORT",