@nest-native/jobs 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @nest-native/jobs
+
+<p align="center">Background jobs for NestJS without Redis — a Drizzle-backed job queue (SQLite, Postgres &amp; MySQL) with transactional enqueue, retries, delayed and unique jobs.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@nest-native/jobs"><img src="https://img.shields.io/npm/v/@nest-native/jobs.svg" alt="NPM Version" /></a>
+  <a href="https://www.npmjs.com/package/@nest-native/jobs"><img src="https://img.shields.io/npm/dm/@nest-native/jobs.svg" alt="NPM Downloads" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="Package License" /></a>
+  <img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Test Coverage" />
+</p>
+
+> [!NOTE]
+> **v0.x — early but stable.** The producer, claimer, handler discovery, and the three Drizzle stores are implemented and tested at 100% coverage. SQLite, Postgres, and MySQL are supported.
+
+## The problem it solves
+
+Most NestJS apps grow a first background job long before they need a queueing *system*: send a welcome email after signup, generate a report, retry a flaky webhook. The official NestJS answer is `@nestjs/bullmq` — which means **operating Redis** for what is often a handful of jobs a minute. And because Redis is a second system, the classic dual-write bug appears on day one: the signup commits but the process crashes before `queue.add()` — the email is never sent. Or `queue.add()` succeeds and the transaction rolls back — a welcome email for a user that does not exist.
+
+`@nest-native/jobs` stores jobs in the **same Drizzle database your app already has**:
+
+- **Transactional enqueue** — `enqueue()` inserts the job row *inside your business transaction* (via [`@nestjs-cls/transactional`](https://www.npmjs.com/package/@nestjs-cls/transactional)). The job exists if and only if your writes committed.
+- **Nest-native execution** — declare a class with `@JobHandler('email.welcome')`, register it as a provider, and the claimer dispatches to it with full DI. Handlers are discovered at bootstrap; duplicate names throw at startup.
+- **Retries, delays, priorities, unique jobs** — jittered exponential backoff (or `RetryableError`'s explicit `delayMs`), `PermanentError` to fail fast, `runAt`/`delayMs` scheduling, `priority` ordering, and `uniqueKey` dedup among active jobs.
+- **Zero runtime dependencies** — everything (Nest, Drizzle, your driver) is a peer you already installed.
+
+## Install
+
+```bash
+npm install @nest-native/jobs
+# plus your driver (peer dependencies):
+npm install drizzle-orm @nestjs-cls/transactional better-sqlite3   # or pg / mysql2
+```
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@nest-native/jobs` | core engine — `JobsService` (enqueue), `JobsClaimer` + `runWorkerLoop`, `@JobHandler` + `JobsHandlerExplorer`, `RetryableError`/`PermanentError`, the `JobStore` seam, `JobsModule` |
+| `@nest-native/jobs/sqlite` | better-sqlite3 (synchronous) store + the `jobs` table definition |
+| `@nest-native/jobs/postgres` | node-postgres (async) store + table definition |
+| `@nest-native/jobs/mysql` | mysql2 (async) store + table definition |
+| `@nest-native/jobs/testing` | `drainJobs` + `RecordingJobHandler` for hermetic tests |
+
+## Usage
+
+```ts
+// app.module.ts — wire CLS + the dialect store once
+JobsModule.forRoot({
+  drizzleInstanceToken: DRIZZLE,
+  store: new SqliteJobStore(),
+});
+
+// user.service.ts — enqueue inside the business transaction
+@Injectable()
+export class UserService {
+  constructor(
+    @InjectTransaction() private readonly db: AppDatabase,
+    private readonly jobs: JobsService<SqliteJobStore>,
+  ) {}
+
+  @Transactional()
+  register(email: string) {
+    this.db.insert(users).values({ email }).run();
+    this.jobs.enqueue({
+      name: 'email.welcome',
+      payload: { email },
+      uniqueKey: `welcome:${email}`, // dedup among active jobs
+    });
+    // both rows commit atomically; a throw rolls both back
+  }
+}
+
+// welcome-email.handler.ts — executed by the claimer, with full DI
+@JobHandler('email.welcome')
+@Injectable()
+export class WelcomeEmailHandler implements JobHandler {
+  async handle(payload: Record<string, unknown>, ctx: JobContext) {
+    await this.mailer.send(String(payload.email)); // throw RetryableError / PermanentError to steer retries
+  }
+}
+
+// worker (same process or a dedicated one)
+const controller = new AbortController();
+void runWorkerLoop(app.get(JobsClaimer), { signal: controller.signal });
+```
+
+Delivery is **at-least-once**: a worker crash mid-job means the row is reclaimed after `stuckTimeoutMs` and run again. Make handlers idempotent or key their side effects on `ctx.jobId`.
+
+### The uniqueKey contract
+
+`uniqueKey` means "unique among **active** jobs", identically on all three dialects: a full unique index on `(name, unique_key)`, and terminal transitions (`completed`, `failed`) clear the key. Enqueueing a duplicate `(name, uniqueKey)` while one is pending/processing is a **no-op that returns the existing row**; once that job finishes, the key is free again. Jobs without a `uniqueKey` never collide.
+
+## Honest comparison
+
+| | BullMQ (`@nestjs/bullmq`) | pg-boss | `@nest-native/jobs` |
+| --- | --- | --- | --- |
+| Backing store | Redis (required) | Postgres only | the Drizzle DB you already run — SQLite, Postgres, or MySQL |
+| NestJS integration | official wrapper module | none (framework-agnostic) | native — module, DI, `@JobHandler` decorators |
+| Enqueue in your DB transaction | no (Redis is a second system) | yes (raw SQL in your tx) | yes — first-class, via `@nestjs-cls/transactional` |
+| Delivery | Redis push (blocking ops) | polling + LISTEN/NOTIFY | polling claimer |
+| Throughput | very high | high | right-sized — polling batches, fine for most apps' background work |
+| Repeatable / cron jobs | yes | yes | no (non-goal — use `@nestjs/schedule`) |
+| Dashboards, rate limiting | yes | partial | no |
+| Runtime dependencies | Redis server + client | `pg` | zero (peers you already have) |
+
+If you need tens of thousands of jobs per second, sandboxed processors, or a dashboard, use BullMQ — it is excellent at that. If you run Postgres without Nest, pg-boss is battle-tested. This library is for the large middle: NestJS + Drizzle apps that want reliable background jobs **without operating another system**.
+
+## Non-goals (v0.1)
+
+- **Cron / repeatable jobs** — `@nestjs/schedule` already does this well; combine it with `enqueue()` if you want scheduled work to flow through the queue.
+- **Dashboards / UI**, **rate limiting**, **concurrency groups**.
+- **LISTEN/NOTIFY push** — the claimer polls; `pollIntervalMs` is your latency knob.
+- **Redis-class throughput** — this is a polling claimer over your relational DB, by design.
+
+Part of the [nest-native](https://github.com/nest-native) family. Not affiliated with the NestJS core team. MIT licensed.

package/dist/dialects/mysql/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schema';
+export * from './job-store';

package/dist/dialects/mysql/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// @nest-native/jobs/mysql — the mysql2 (async) dialect:
+// the `jobs` table definition + the MySQL store.
+__exportStar(require("./schema"), exports);
+__exportStar(require("./job-store"), exports);
+//# sourceMappingURL=index.js.map

package/dist/dialects/mysql/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../dialects/mysql/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wDAAwD;AACxD,iDAAiD;AACjD,2CAAyB;AACzB,8CAA4B"}

package/dist/dialects/mysql/job-store.d.ts

@@ -0,0 +1,35 @@
+import type { EnqueueJobInput, JobRow, JobStore, ResolvedRunnerConfig } from '../../interfaces';
+/**
+ * MySQL surfaces a unique-constraint violation as error code `ER_DUP_ENTRY`
+ * (errno `1062`). mysql2 sets both `error.code === 'ER_DUP_ENTRY'` and
+ * `error.errno === 1062`; Drizzle wraps driver errors in a `DrizzleQueryError`,
+ * so the code/errno may instead sit on `error.cause`. Check the code **and**
+ * the errno, on the error and on its `cause`, so the predicate is robust to
+ * both the driver's shape and Drizzle's wrapping.
+ */
+export declare function isMysqlUniqueViolation(error: unknown): boolean;
+/**
+ * MySQL (mysql2) job store. Every method is **asynchronous** — `enqueue`
+ * awaits the insert (call it with `await` inside an async `@Transactional`
+ * body), and the claimer's batch claim runs in an async transaction.
+ *
+ * Unlike Postgres, MySQL's `INSERT` has no `RETURNING`, so `enqueue` inserts
+ * the row (client-generated UUID id) and reads it back by id to return the
+ * canonical {@link JobRow}. A `(name, unique_key)` unique violation is the
+ * active-dedup no-op: the store returns the EXISTING active row instead.
+ */
+export declare class MysqlJobStore implements JobStore {
+    enqueue(db: unknown, input: EnqueueJobInput<object>): Promise<JobRow>;
+    /**
+     * On a unique violation with a `uniqueKey`, the ACTIVE row that owns the
+     * `(name, uniqueKey)` pair — terminal rows cannot own it (their key is
+     * cleared to NULL). Any other error, or a vanished row (the owner completed
+     * between the insert and this read), resolves undefined so the caller
+     * rethrows the original error.
+     */
+    private findActiveDuplicate;
+    claimBatch(db: unknown, cfg: ResolvedRunnerConfig): Promise<JobRow[]>;
+    markCompleted(db: unknown, id: string): Promise<void>;
+    retry(db: unknown, id: string, delayMs: number, lastError?: string): Promise<void>;
+    markFailed(db: unknown, id: string, reason: string): Promise<void>;
+}

package/dist/dialects/mysql/job-store.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MysqlJobStore = void 0;
+exports.isMysqlUniqueViolation = isMysqlUniqueViolation;
+const node_crypto_1 = require("node:crypto");
+const drizzle_orm_1 = require("drizzle-orm");
+const enqueue_input_1 = require("../../enqueue-input");
+const schema_1 = require("./schema");
+/**
+ * MySQL surfaces a unique-constraint violation as error code `ER_DUP_ENTRY`
+ * (errno `1062`). mysql2 sets both `error.code === 'ER_DUP_ENTRY'` and
+ * `error.errno === 1062`; Drizzle wraps driver errors in a `DrizzleQueryError`,
+ * so the code/errno may instead sit on `error.cause`. Check the code **and**
+ * the errno, on the error and on its `cause`, so the predicate is robust to
+ * both the driver's shape and Drizzle's wrapping.
+ */
+function isMysqlUniqueViolation(error) {
+    return isDuplicate(error) || isDuplicate(error?.cause);
+}
+function isDuplicate(error) {
+    return hasProp(error, 'code', 'ER_DUP_ENTRY') || hasProp(error, 'errno', 1062);
+}
+function hasProp(error, key, value) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        key in error &&
+        error[key] === value);
+}
+/**
+ * MySQL (mysql2) job store. Every method is **asynchronous** — `enqueue`
+ * awaits the insert (call it with `await` inside an async `@Transactional`
+ * body), and the claimer's batch claim runs in an async transaction.
+ *
+ * Unlike Postgres, MySQL's `INSERT` has no `RETURNING`, so `enqueue` inserts
+ * the row (client-generated UUID id) and reads it back by id to return the
+ * canonical {@link JobRow}. A `(name, unique_key)` unique violation is the
+ * active-dedup no-op: the store returns the EXISTING active row instead.
+ */
+class MysqlJobStore {
+    async enqueue(db, input) {
+        const id = (0, node_crypto_1.randomUUID)();
+        const availableAt = (0, enqueue_input_1.resolveAvailableAt)(input).toISOString();
+        try {
+            await db.insert(schema_1.jobs).values({
+                id,
+                name: input.name,
+                // The one place the structural input payload widens to the stored shape.
+                payload: input.payload,
+                status: 'pending',
+                maxAttempts: input.maxAttempts ?? 10,
+                uniqueKey: input.uniqueKey ?? null,
+                priority: input.priority ?? 0,
+                availableAt,
+                createdAt: new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            const existing = await this.findActiveDuplicate(db, input, error);
+            if (!existing)
+                throw error;
+            return existing;
+        }
+        const [row] = await db.select().from(schema_1.jobs).where((0, drizzle_orm_1.eq)(schema_1.jobs.id, id));
+        return row;
+    }
+    /**
+     * On a unique violation with a `uniqueKey`, the ACTIVE row that owns the
+     * `(name, uniqueKey)` pair — terminal rows cannot own it (their key is
+     * cleared to NULL). Any other error, or a vanished row (the owner completed
+     * between the insert and this read), resolves undefined so the caller
+     * rethrows the original error.
+     */
+    async findActiveDuplicate(db, input, error) {
+        if (!isMysqlUniqueViolation(error) || input.uniqueKey == null) {
+            return undefined;
+        }
+        const [existing] = await db
+            .select()
+            .from(schema_1.jobs)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.jobs.name, input.name), (0, drizzle_orm_1.eq)(schema_1.jobs.uniqueKey, input.uniqueKey)));
+        return existing;
+    }
+    async claimBatch(db, cfg) {
+        const now = new Date();
+        const nowIso = now.toISOString();
+        const stuckCutoff = new Date(now.getTime() - cfg.stuckTimeoutMs).toISOString();
+        return db.transaction(async (tx) => {
+            const candidates = await tx
+                .select({ id: schema_1.jobs.id })
+                .from(schema_1.jobs)
+                .where((0, drizzle_orm_1.or)((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.jobs.status, 'pending'), (0, drizzle_orm_1.lte)(schema_1.jobs.availableAt, nowIso)), (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.jobs.status, 'processing'), (0, drizzle_orm_1.lte)(schema_1.jobs.claimedAt, stuckCutoff))))
+                .orderBy((0, drizzle_orm_1.desc)(schema_1.jobs.priority), (0, drizzle_orm_1.asc)(schema_1.jobs.availableAt))
+                .limit(cfg.batchSize);
+            if (candidates.length === 0)
+                return [];
+            const ids = candidates.map((c) => c.id);
+            await tx
+                .update(schema_1.jobs)
+                .set({ status: 'processing', claimedAt: nowIso, claimedBy: cfg.workerInstanceId })
+                .where((0, drizzle_orm_1.inArray)(schema_1.jobs.id, ids));
+            return tx
+                .select()
+                .from(schema_1.jobs)
+                .where((0, drizzle_orm_1.inArray)(schema_1.jobs.id, ids))
+                .orderBy((0, drizzle_orm_1.desc)(schema_1.jobs.priority), (0, drizzle_orm_1.asc)(schema_1.jobs.availableAt));
+        });
+    }
+    async markCompleted(db, id) {
+        await db
+            .update(schema_1.jobs)
+            .set({
+            status: 'completed',
+            processedAt: new Date().toISOString(),
+            lastError: null,
+            // Terminal → release the active-dedup key.
+            uniqueKey: null,
+        })
+            .where((0, drizzle_orm_1.eq)(schema_1.jobs.id, id));
+    }
+    async retry(db, id, delayMs, lastError) {
+        const nextAvailable = new Date(Date.now() + delayMs).toISOString();
+        await db
+            .update(schema_1.jobs)
+            .set({
+            status: 'pending',
+            attempts: (0, drizzle_orm_1.sql) `${schema_1.jobs.attempts} + 1`,
+            availableAt: nextAvailable,
+            claimedAt: null,
+            claimedBy: null,
+            lastError: lastError ?? null,
+            // Still active → the uniqueKey stays claimed.
+        })
+            .where((0, drizzle_orm_1.eq)(schema_1.jobs.id, id));
+    }
+    async markFailed(db, id, reason) {
+        await db
+            .update(schema_1.jobs)
+            .set({
+            status: 'failed',
+            attempts: (0, drizzle_orm_1.sql) `${schema_1.jobs.attempts} + 1`,
+            lastError: reason,
+            processedAt: new Date().toISOString(),
+            // Terminal → release the active-dedup key.
+            uniqueKey: null,
+        })
+            .where((0, drizzle_orm_1.eq)(schema_1.jobs.id, id));
+    }
+}
+exports.MysqlJobStore = MysqlJobStore;
+//# sourceMappingURL=job-store.js.map

package/dist/dialects/mysql/job-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-store.js","sourceRoot":"","sources":["../../../dialects/mysql/job-store.ts"],"names":[],"mappings":";;;AAsBA,wDAEC;AAxBD,6CAAyC;AACzC,6CAAwE;AAExE,uDAAyD;AAOzD,qCAAgC;AAIhC;;;;;;;GAOG;AACH,SAAgB,sBAAsB,CAAC,KAAc;IACnD,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,WAAW,CAAE,KAA6B,EAAE,KAAK,CAAC,CAAC;AAClF,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,OAAO,CAAC,KAAc,EAAE,GAAW,EAAE,KAAc;IAC1D,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,GAAG,IAAI,KAAK;QACX,KAAiC,CAAC,GAAG,CAAC,KAAK,KAAK,CAClD,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAa,aAAa;IACxB,KAAK,CAAC,OAAO,CAAC,EAAW,EAAE,KAA8B;QACvD,MAAM,EAAE,GAAG,IAAA,wBAAU,GAAE,CAAC;QACxB,MAAM,WAAW,GAAG,IAAA,kCAAkB,EAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5D,IAAI,CAAC;YACH,MAAO,EAAS,CAAC,MAAM,CAAC,aAAI,CAAC,CAAC,MAAM,CAAC;gBACnC,EAAE;gBACF,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,yEAAyE;gBACzE,OAAO,EAAE,KAAK,CAAC,OAAkC;gBACjD,MAAM,EAAE,SAAS;gBACjB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;gBACpC,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;gBAClC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,CAAC;gBAC7B,WAAW;gBACX,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;YAClE,IAAI,CAAC,QAAQ;gBAAE,MAAM,KAAK,CAAC;YAC3B,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,MAAO,EAAS,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,aAAI,CAAC,CAAC,KAAK,CAAC,IAAA,gBAAE,EAAC,aAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1E,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,mBAAmB,CAC/B,EAAW,EACX,KAA8B,EAC9B,KAAc;QAEd,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;YAC9D,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAO,EAAS;aAChC,MAAM,EAAE;aACR,IAAI,CAAC,aAAI,CAAC;aACV,KAAK,CAAC,IAAA,iBAAG,EAAC,IAAA,gBAAE,EAAC,aAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAA,gBAAE,EAAC,aAAI,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC9E,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,EAAW,EAAE,GAAyB;QACrD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QACjC,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,CAAC;QAC/E,OAAQ,EAAS,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YACzC,MAAM,UAAU,GAAG,MAAM,EAAE;iBACxB,MAAM,CAAC,EAAE,EAAE,EAAE,aAAI,CAAC,EAAE,EAAE,CAAC;iBACvB,IAAI,CAAC,aAAI,CAAC;iBACV,KAAK,CACJ,IAAA,gBAAE,EACA,IAAA,iBAAG,EAAC,IAAA,gBAAE,EAAC,aAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,IAAA,iBAAG,EAAC,aAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,EAC9D,IAAA,iBAAG,EAAC,IAAA,gBAAE,EAAC,aAAI,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,IAAA,iBAAG,EAAC,aAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CACrE,CACF;iBACA,OAAO,CAAC,IAAA,kBAAI,EAAC,aAAI,CAAC,QAAQ,CAAC,EAAE,IAAA,iBAAG,EAAC,aAAI,CAAC,WAAW,CAAC,CAAC;iBACnD,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACxB,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACxC,MAAM,EAAE;iBACL,MAAM,CAAC,aAAI,CAAC;iBACZ,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,gBAAgB,EAAE,CAAC;iBACjF,KAAK,CAAC,IAAA,qBAAO,EAAC,aAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;YAChC,OAAO,EAAE;iBACN,MAAM,EAAE;iBACR,IAAI,CAAC,aAAI,CAAC;iBACV,KAAK,CAAC,IAAA,qBAAO,EAAC,aAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;iBAC5B,OAAO,CAAC,IAAA,kBAAI,EAAC,aAAI,CAAC,QAAQ,CAAC,EAAE,IAAA,iBAAG,EAAC,aAAI,CAAC,WAAW,CAAC,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,EAAW,EAAE,EAAU;QACzC,MAAO,EAAS;aACb,MAAM,CAAC,aAAI,CAAC;aACZ,GAAG,CAAC;YACH,MAAM,EAAE,WAAW;YACnB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,SAAS,EAAE,IAAI;YACf,2CAA2C;YAC3C,SAAS,EAAE,IAAI;SAChB,CAAC;aACD,KAAK,CAAC,IAAA,gBAAE,EAAC,aAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,KAAK,CACT,EAAW,EACX,EAAU,EACV,OAAe,EACf,SAAkB;QAElB,MAAM,aAAa,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QACnE,MAAO,EAAS;aACb,MAAM,CAAC,aAAI,CAAC;aACZ,GAAG,CAAC;YACH,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,IAAA,iBAAG,EAAA,GAAG,aAAI,CAAC,QAAQ,MAAM;YACnC,WAAW,EAAE,aAAa;YAC1B,SAAS,EAAE,IAAI;YACf,SAAS,EAAE,IAAI;YACf,SAAS,EAAE,SAAS,IAAI,IAAI;YAC5B,8CAA8C;SAC/C,CAAC;aACD,KAAK,CAAC,IAAA,gBAAE,EAAC,aAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,EAAW,EAAE,EAAU,EAAE,MAAc;QACtD,MAAO,EAAS;aACb,MAAM,CAAC,aAAI,CAAC;aACZ,GAAG,CAAC;YACH,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,IAAA,iBAAG,EAAA,GAAG,aAAI,CAAC,QAAQ,MAAM;YACnC,SAAS,EAAE,MAAM;YACjB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,2CAA2C;YAC3C,SAAS,EAAE,IAAI;SAChB,CAAC;aACD,KAAK,CAAC,IAAA,gBAAE,EAAC,aAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;CACF;AA7HD,sCA6HC"}

package/dist/dialects/mysql/schema.d.ts

@@ -0,0 +1,255 @@
+/**
+ * MySQL `jobs` table. Add it to your Drizzle schema and generate a migration
+ * with drizzle-kit. Timestamps are stored as ISO-8601 `varchar` so the row
+ * shape is identical across dialects (ISO-8601 compares lexicographically,
+ * which the claimer's `available_at` range query relies on).
+ */
+export declare const jobs: import("drizzle-orm/mysql-core").MySqlTableWithColumns<{
+    name: "jobs";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "id";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "name";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        payload: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "payload";
+            tableName: "jobs";
+            dataType: "json";
+            columnType: "MySqlJson";
+            data: Record<string, unknown>;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        status: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "status";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: "pending" | "processing" | "completed" | "failed";
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: "pending" | "processing" | "completed" | "failed";
+        }>;
+        attempts: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "attempts";
+            tableName: "jobs";
+            dataType: "number";
+            columnType: "MySqlInt";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        maxAttempts: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "max_attempts";
+            tableName: "jobs";
+            dataType: "number";
+            columnType: "MySqlInt";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        uniqueKey: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "unique_key";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: string;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        priority: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "priority";
+            tableName: "jobs";
+            dataType: "number";
+            columnType: "MySqlInt";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        availableAt: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "available_at";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        claimedAt: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "claimed_at";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: string;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        claimedBy: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "claimed_by";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: string;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        processedAt: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "processed_at";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: string;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        lastError: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "last_error";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "created_at";
+            tableName: "jobs";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "mysql";
+}>;

package/dist/dialects/mysql/schema.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jobs = void 0;
+const mysql_core_1 = require("drizzle-orm/mysql-core");
+// MySQL-specific schema choices (documented so they are deliberate, not
+// accidental divergence from the Postgres/SQLite definitions):
+//
+// - **`varchar` on every indexed column.** MySQL cannot index a `TEXT`/`BLOB`
+//   column without a prefix length, so `id`, `name`, `status`, `unique_key`,
+//   and `available_at` are `varchar(n)`. 191 is the classic utf8mb4-safe
+//   single-column index width; the composite `(name, unique_key)` index at
+//   255 + 191 utf8mb4 chars stays well under InnoDB's 3072-byte key limit.
+//   The ISO-8601 timestamp columns fit comfortably in `varchar(32)`;
+//   free-form `last_error` stays `text`.
+// - **The SAME full unique index on `(name, unique_key)`** as the other
+//   dialects. MySQL has no partial indexes, but none are needed: a UNIQUE
+//   index over a nullable column permits multiple `NULL`s (SQL treats `NULL`
+//   as distinct), and terminal transitions clear `unique_key` to `NULL` — so
+//   "unique among ACTIVE jobs" holds with identical semantics everywhere.
+// - **`json` payload.** MySQL's native JSON type; mysql2 returns it already
+//   parsed, so the row shape matches `JobRow`.
+/**
+ * MySQL `jobs` table. Add it to your Drizzle schema and generate a migration
+ * with drizzle-kit. Timestamps are stored as ISO-8601 `varchar` so the row
+ * shape is identical across dialects (ISO-8601 compares lexicographically,
+ * which the claimer's `available_at` range query relies on).
+ */
+exports.jobs = (0, mysql_core_1.mysqlTable)('jobs', {
+    id: (0, mysql_core_1.varchar)('id', { length: 191 }).primaryKey(),
+    name: (0, mysql_core_1.varchar)('name', { length: 255 }).notNull(),
+    payload: (0, mysql_core_1.json)('payload').$type().notNull(),
+    status: (0, mysql_core_1.varchar)('status', { length: 32 }).$type().notNull(),
+    attempts: (0, mysql_core_1.int)('attempts').notNull().default(0),
+    maxAttempts: (0, mysql_core_1.int)('max_attempts').notNull().default(10),
+    uniqueKey: (0, mysql_core_1.varchar)('unique_key', { length: 191 }),
+    priority: (0, mysql_core_1.int)('priority').notNull().default(0),
+    availableAt: (0, mysql_core_1.varchar)('available_at', { length: 32 }).notNull(),
+    claimedAt: (0, mysql_core_1.varchar)('claimed_at', { length: 32 }),
+    claimedBy: (0, mysql_core_1.varchar)('claimed_by', { length: 191 }),
+    processedAt: (0, mysql_core_1.varchar)('processed_at', { length: 32 }),
+    lastError: (0, mysql_core_1.text)('last_error'),
+    createdAt: (0, mysql_core_1.varchar)('created_at', { length: 32 }).notNull(),
+}, (table) => [
+    (0, mysql_core_1.uniqueIndex)('jobs_name_unique_key_unique').on(table.name, table.uniqueKey),
+    (0, mysql_core_1.index)('jobs_status_available_idx').on(table.status, table.availableAt),
+]);
+//# sourceMappingURL=schema.js.map

package/dist/dialects/mysql/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../dialects/mysql/schema.ts"],"names":[],"mappings":";;;AAAA,uDAQgC;AAGhC,wEAAwE;AACxE,+DAA+D;AAC/D,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,yEAAyE;AACzE,2EAA2E;AAC3E,2EAA2E;AAC3E,qEAAqE;AACrE,yCAAyC;AACzC,wEAAwE;AACxE,0EAA0E;AAC1E,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,4EAA4E;AAC5E,+CAA+C;AAE/C;;;;;GAKG;AACU,QAAA,IAAI,GAAG,IAAA,uBAAU,EAC5B,MAAM,EACN;IACE,EAAE,EAAE,IAAA,oBAAO,EAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,UAAU,EAAE;IAC/C,IAAI,EAAE,IAAA,oBAAO,EAAC,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE;IAChD,OAAO,EAAE,IAAA,iBAAI,EAAC,SAAS,CAAC,CAAC,KAAK,EAA2B,CAAC,OAAO,EAAE;IACnE,MAAM,EAAE,IAAA,oBAAO,EAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,EAAa,CAAC,OAAO,EAAE;IACtE,QAAQ,EAAE,IAAA,gBAAG,EAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9C,WAAW,EAAE,IAAA,gBAAG,EAAC,cAAc,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACtD,SAAS,EAAE,IAAA,oBAAO,EAAC,YAAY,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACjD,QAAQ,EAAE,IAAA,gBAAG,EAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9C,WAAW,EAAE,IAAA,oBAAO,EAAC,cAAc,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;IAC9D,SAAS,EAAE,IAAA,oBAAO,EAAC,YAAY,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAChD,SAAS,EAAE,IAAA,oBAAO,EAAC,YAAY,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACjD,WAAW,EAAE,IAAA,oBAAO,EAAC,cAAc,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACpD,SAAS,EAAE,IAAA,iBAAI,EAAC,YAAY,CAAC;IAC7B,SAAS,EAAE,IAAA,oBAAO,EAAC,YAAY,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;CAC3D,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,IAAA,wBAAW,EAAC,6BAA6B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1E,IAAA,kBAAK,EAAC,2BAA2B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC;CACvE,CACF,CAAC"}

package/dist/dialects/postgres/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schema';
+export * from './job-store';