@sigil-dev/plugin-jobs 0.9.28 → 0.9.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/queue.ts CHANGED
@@ -1,79 +1,43 @@
1
- import type {
2
- Capabilities,
3
- EnqueueOptions,
4
- JobRow,
5
- JobStats,
6
- JobStore,
7
- } from "./store.ts";
1
+ import type { Tome } from "@sigil-dev/tome";
2
+ import type { JobsTable } from "./schema.ts";
3
+ import type { JobRow, JobStats } from "./store.ts";
8
4
 
9
- /**
10
- * Schema statements, kept portable.
11
- *
12
- * Deliberately plain: no dialect, no generated columns, no `jsonb`. The
13
- * payload is TEXT holding JSON rather than a JSON column type, because the
14
- * json type is spelled differently everywhere and nothing here needs to
15
- * query inside the payload.
16
- */
17
- export const SCHEMA = `
18
- CREATE TABLE IF NOT EXISTS sigil_jobs (
19
- -- VARCHAR(64), not TEXT: MySQL refuses to index a TEXT primary key
20
- -- without a prefix length ("BLOB/TEXT column 'id' used in key
21
- -- specification without a key length"), so a portable id column has to
22
- -- be a bounded character type. 36 is a UUID with room to spare, and it
23
- -- is what the generated ids actually look like.
24
- id VARCHAR(64) PRIMARY KEY,
25
- name TEXT NOT NULL,
26
- payload TEXT NOT NULL,
27
- -- name is indexed nowhere, so TEXT is fine and keeps long handler
28
- -- names from being truncated by a column width.
29
- run_at TIMESTAMP NOT NULL,
30
- attempts INTEGER NOT NULL DEFAULT 0,
31
- max_attempts INTEGER NOT NULL DEFAULT 5,
32
- last_error TEXT,
33
- claimed_at TIMESTAMP,
34
- -- Which claim took this row. NOT a timestamp: MySQL truncates TIMESTAMP to
35
- -- whole seconds, so two workers claiming in the same second are
36
- -- indistinguishable, and the stale-claim comparison then re-claims a live
37
- -- row. Measured: a second worker re-claimed rows claimed milliseconds
38
- -- earlier. A random token per claim is exact on all three dialects.
39
- claim_token VARCHAR(64),
40
- created_at TIMESTAMP NOT NULL
41
- );
42
- CREATE INDEX IF NOT EXISTS sigil_jobs_ready ON sigil_jobs (run_at);
43
- `;
5
+ /** When and how often a row runs; `job.enqueue` fills it from the job. */
6
+ export interface QueueOptions {
7
+ runAt?: Date;
8
+ maxAttempts?: number;
9
+ }
10
+
11
+ // biome-ignore lint/suspicious/noExplicitAny: the queue works on any schema that holds its table
12
+ type AnyTome = Tome<any, any>;
44
13
 
45
14
  /**
46
- * A durable queue over any client that can run a query and return rows.
15
+ * A durable queue in a tome table.
47
16
  *
48
17
  * Delivery is at-least-once, and that is not a caveat to be apologetic
49
18
  * about — it is the guarantee being bought. A worker can die between doing
50
19
  * the side effect and deleting the row, so a handler must be idempotent.
51
20
  * The alternative is exactly-once, which in practice means transactions
52
21
  * held open across the entire handler, including every HTTP call inside it.
22
+ *
23
+ * Every query goes through tome, so it runs inside the request's
24
+ * transaction when there is one: a job enqueued by a request that fails is
25
+ * rolled back with it.
53
26
  */
54
27
  export class JobQueue {
55
28
  /** Recurring jobs: row id → interval. Set by `ensureSchedules`. */
56
29
  private readonly schedules = new Map<string, number>();
30
+ private readonly db: () => AnyTome;
57
31
 
58
32
  constructor(
59
- private readonly store: JobStore,
60
- private readonly table: string = "sigil_jobs",
61
- ) {}
33
+ db: AnyTome | (() => AnyTome),
34
+ readonly table: JobsTable,
35
+ ) {
36
+ this.db = typeof db === "function" ? db : () => db;
37
+ }
62
38
 
63
- /**
64
- * Every capability defaults to false. A store that declares nothing gets
65
- * the weakest path, which is correct on every dialect rather than correct
66
- * on the one it was written for.
67
- *
68
- * Read on use rather than at construction: a store over a database that
69
- * opens later only knows its dialect once it is open.
70
- */
71
- private get caps(): Required<Capabilities> {
72
- return {
73
- skipLocked: this.store.capabilities?.skipLocked ?? false,
74
- spaceSeparatedTimestamp:
75
- this.store.capabilities?.spaceSeparatedTimestamp ?? false,
76
- };
39
+ private get rows() {
40
+ return this.db().table(this.table);
77
41
  }
78
42
 
79
43
  /** The row id a schedule lives under. */
@@ -100,43 +64,37 @@ export class JobQueue {
100
64
  * clock — and does not run everything the moment a deploy lands.
101
65
  */
102
66
  async ensureSchedules(
103
- schedules: Record<string, { everyMs: number; payload?: unknown }>,
67
+ schedules: Record<
68
+ string,
69
+ { everyMs: number; payload?: unknown; maxAttempts?: number }
70
+ >,
104
71
  ): Promise<void> {
72
+ const j = this.table;
105
73
  this.schedules.clear();
106
- for (const [name, { everyMs, payload }] of Object.entries(schedules)) {
74
+ for (const [name, { everyMs, payload, maxAttempts }] of Object.entries(
75
+ schedules,
76
+ )) {
107
77
  const id = JobQueue.scheduleId(name);
108
78
  this.schedules.set(id, everyMs);
109
- const exists = await this.store.query(
110
- `SELECT id FROM ${this.table} WHERE id = ?`,
111
- [id],
112
- );
113
- if (exists.length > 0) continue;
114
- const now = new Date();
79
+ if (await this.rows.exists(j.id.eq(id))) continue;
115
80
  try {
116
- await this.store.query(
117
- `INSERT INTO ${this.table}
118
- (id, name, payload, run_at, attempts, max_attempts, created_at)
119
- VALUES (?, ?, ?, ?, 0, ?, ?)`,
81
+ await this.rows.insert({
82
+ id,
83
+ name,
84
+ payload: JSON.stringify(payload ?? {}),
120
85
  // First run one interval from now, not at boot: a deploy
121
86
  // should not fire every schedule at once.
122
- [id, name, JSON.stringify(payload ?? {}), this.ts(new Date(now.getTime() + everyMs)), 5, this.ts(now)],
123
- );
87
+ runAt: new Date(Date.now() + everyMs),
88
+ ...(maxAttempts ? { maxAttempts } : {}),
89
+ });
124
90
  } catch (e) {
125
- // Another worker inserted it between our SELECT and INSERT.
126
- const raced = await this.store.query(
127
- `SELECT id FROM ${this.table} WHERE id = ?`,
128
- [id],
129
- );
130
- if (raced.length === 0) throw e;
91
+ // Another worker inserted it between our check and insert.
92
+ if (!(await this.rows.exists(j.id.eq(id)))) throw e;
131
93
  }
132
94
  }
133
95
  const ids = [...this.schedules.keys()];
134
- await this.store.query(
135
- ids.length
136
- ? `DELETE FROM ${this.table} WHERE id LIKE 'schedule:%' AND id NOT IN (${ids.map(() => "?").join(", ")})`
137
- : `DELETE FROM ${this.table} WHERE id LIKE 'schedule:%'`,
138
- ids,
139
- );
96
+ const stale = this.db().delete(j).where(j.id.like("schedule:%"));
97
+ await (ids.length ? stale.where(j.id.notIn(ids)) : stale);
140
98
  }
141
99
 
142
100
  /**
@@ -145,54 +103,22 @@ export class JobQueue {
145
103
  * that failed five times still runs next time.
146
104
  */
147
105
  async reschedule(id: string, lastError: string | null = null): Promise<void> {
106
+ const j = this.table;
148
107
  const every = this.schedules.get(id);
149
108
  if (every === undefined) {
150
- await this.store.query(`DELETE FROM ${this.table} WHERE id = ?`, [id]);
109
+ await this.db().delete(j).where(j.id.eq(id));
151
110
  return;
152
111
  }
153
- await this.store.query(
154
- `UPDATE ${this.table}
155
- SET run_at = ?, attempts = 0, last_error = ?, claimed_at = NULL, claim_token = NULL
156
- WHERE id = ?`,
157
- [this.ts(new Date(Date.now() + every)), lastError?.slice(0, 2000) ?? null, id],
158
- );
159
- }
160
-
161
- /**
162
- * A timestamp in the spelling this dialect accepts.
163
- *
164
- * The obvious thing — pass `Date.toISOString()` and let the driver
165
- * serialise it — is what MariaDB rejects: "Incorrect datetime value:
166
- * '2026-09-27T21:17:22.073Z'". The T and the Z are the problem, not the
167
- * precision.
168
- */
169
- private ts(date: Date): string {
170
- const iso = date.toISOString();
171
- return this.caps.spaceSeparatedTimestamp
172
- ? iso.replace("T", " ").replace("Z", "")
173
- : iso;
174
- }
175
-
176
- async migrate(): Promise<void> {
177
- // SCHEMA names the default table, so a custom `table` option has to be
178
- // substituted here too. It used to be ignored, which produced the
179
- // worst kind of failure: migrate() succeeded, then every query failed
180
- // with "relation does not exist" against a name that looked correct.
181
- const schema = SCHEMA.replaceAll("sigil_jobs", this.table);
182
- for (const stmt of schema.split(";").map((s) => s.trim()).filter(Boolean)) {
183
- try {
184
- await this.store.query(stmt);
185
- } catch {
186
- // Two workers booting together both run CREATE TABLE IF NOT
187
- // EXISTS, and postgres can fail the loser with a duplicate key
188
- // on its own catalog — "IF NOT EXISTS" is checked before the
189
- // insert, not atomically with it. By the time we retry the
190
- // table exists, so the second attempt is a no-op; a real error
191
- // fails again and surfaces.
192
- await new Promise((r) => setTimeout(r, 50 + Math.random() * 100));
193
- await this.store.query(stmt);
194
- }
195
- }
112
+ await this.db()
113
+ .update(j)
114
+ .set({
115
+ runAt: new Date(Date.now() + every),
116
+ attempts: 0,
117
+ lastError: lastError?.slice(0, 2000) ?? null,
118
+ claimedAt: null,
119
+ claimToken: null,
120
+ })
121
+ .where(j.id.eq(id));
196
122
  }
197
123
 
198
124
  /**
@@ -205,192 +131,163 @@ export class JobQueue {
205
131
  async enqueue(
206
132
  name: string,
207
133
  payload: unknown = {},
208
- options: EnqueueOptions = {},
134
+ options: QueueOptions = {},
209
135
  ): Promise<string> {
210
136
  const id = crypto.randomUUID();
211
- const now = new Date();
212
- const runAt = options.runAt ?? now;
213
- await this.store.query(
214
- `INSERT INTO ${this.table}
215
- (id, name, payload, run_at, attempts, max_attempts, created_at)
216
- VALUES (?, ?, ?, ?, 0, ?, ?)`,
217
- [
218
- id,
219
- name,
220
- JSON.stringify(payload ?? {}),
221
- this.ts(runAt),
222
- options.maxAttempts ?? 5,
223
- this.ts(now),
224
- ],
225
- );
137
+ await this.rows.insert({
138
+ id,
139
+ name,
140
+ payload: JSON.stringify(payload ?? {}),
141
+ runAt: options.runAt ?? new Date(),
142
+ maxAttempts: options.maxAttempts ?? 5,
143
+ });
226
144
  return id;
227
145
  }
228
146
 
229
147
  /**
230
148
  * Atomically take up to `limit` due jobs.
231
149
  *
232
- * The safety comes from the claim guard, not from row locking: a row is
233
- * only claimable when `claimed_at` is NULL or an old claim, and that
234
- * check happens as part of the write. Two workers issuing this
235
- * simultaneously both read the same candidate ids, but the second one's
236
- * UPDATE matches nothing because the first has already set `claimed_at`.
237
- * So the loser gets an empty set rather than a duplicate job — which is
238
- * the whole requirement.
239
- *
240
- * Which shape that takes depends on the dialect:
150
+ * One UPDATE picks the candidates in a subquery and claims them, so
151
+ * there is no window between reading and writing. The guard
152
+ * (`claim_token IS NULL OR claimed_at < cutoff`) is repeated in the
153
+ * outer WHERE: two workers whose subqueries pick the same rows both
154
+ * reach the UPDATE, and the second matches nothing because the first
155
+ * already set the token. The loser gets an empty batch, never a
156
+ * duplicate job — which is the whole requirement.
241
157
  *
242
- * - With RETURNING, the ids are chosen and claimed in one statement, so
243
- * there is no window between reading candidates and writing the
244
- * claim.
245
- * - Without it — MariaDB — the candidates are read first and then
246
- * claimed. The window is real but harmless: correctness still comes
247
- * from the `claimed_at` condition inside the UPDATE, so the loser
248
- * updates zero rows and gets an empty batch rather than a duplicate.
249
- * The cost is one extra round trip per claim.
158
+ * On postgres the candidates are locked `FOR UPDATE SKIP LOCKED`, so a
159
+ * second worker takes the next rows instead of waiting for, and then
160
+ * losing, the same ones. SQLite has one writer, so the statement is
161
+ * already exclusive.
250
162
  *
251
- * `SKIP LOCKED` is appended only when the store declares it. It changes
252
- * contention behaviour, not correctness.
253
- *
254
- * The returned rows are NOT in run_at order, and cannot be made to be:
255
- * SQL does not define the order of an UPDATE's RETURNING clause. The
256
- * inner ORDER BY decides which `limit` rows are taken, not the order
257
- * they come back. Sort in the caller if order matters.
163
+ * The rows come back in run_at order. The token is what tells this
164
+ * pass which rows it won.
258
165
  */
259
166
  async claim(limit: number, staleMs = 60_000): Promise<JobRow[]> {
260
- const now = this.ts(new Date());
261
- const cutoff = this.ts(new Date(Date.now() - staleMs));
262
- const skip = this.caps.skipLocked ? " FOR UPDATE SKIP LOCKED" : "";
263
- // One token per claim pass, not per row: a single pass is a single
264
- // atomic event from the point of view of "did I get these rows", and
265
- // one token makes the re-read a single equality test.
167
+ const db = this.db();
168
+ const j = this.table;
169
+ const now = new Date().toISOString();
170
+ const cutoff = new Date(Date.now() - staleMs).toISOString();
266
171
  const token = `c_${crypto.randomUUID()}`;
267
-
268
- // The candidate batch is selected in a derived table rather than a
269
- // plain `WHERE id IN (SELECT ... LIMIT n)` because MariaDB refuses
270
- // the latter outright: "This version of MariaDB doesn't yet support
271
- // 'LIMIT & IN/ALL/ANY/SOME subquery'". A derived table joined on id
272
- // means the same thing and is accepted by all three dialects.
273
- const candidates = `
274
- SELECT id FROM (
275
- SELECT id FROM ${this.table}
276
- WHERE run_at <= ?
277
- AND attempts < max_attempts
278
- AND (claim_token IS NULL OR claimed_at < ?)
279
- ORDER BY run_at
280
- LIMIT ?
281
- ${skip}
282
- ) AS ready`;
283
-
284
- const columns =
285
- "id, name, payload, run_at, attempts, max_attempts, last_error, claimed_at, claim_token, created_at";
286
-
287
- // Claim in one statement. The `claim_token IS NULL OR claimed_at < ?`
288
- // guard is what makes this exclusive: two workers selecting the same
289
- // candidates both issue this UPDATE, and the second one matches
290
- // nothing, because the first has already set claim_token. The loser
291
- // gets an empty batch rather than a duplicate job.
292
- //
293
- // `claim_token` is set to a fresh random value rather than
294
- // claimed_at's own instant, because MySQL truncates TIMESTAMP to whole
295
- // seconds. Two workers claiming in the same second would be
296
- // indistinguishable, the second would match the first's rows, and
297
- // both would run the same job. Measured, not theorised.
298
- await this.store.query(
299
- `UPDATE ${this.table}
300
- SET claimed_at = ?, claim_token = ?, attempts = attempts + 1
301
- WHERE id IN (${candidates})
302
- AND attempts < max_attempts
303
- AND (claim_token IS NULL OR claimed_at < ?)`,
304
- [now, token, now, cutoff, limit, cutoff],
305
- );
306
-
307
- // Read back only the rows this pass won, by token. A dialect without
308
- // RETURNING cannot tell us which ids the UPDATE matched — MariaDB
309
- // returns [] even when it updated two rows — so the token is what
310
- // makes the answer knowable, and it works identically on all three.
311
- return this.store.query<JobRow>(
312
- `SELECT ${columns} FROM ${this.table} WHERE claim_token = ?`,
313
- [token],
314
- );
172
+ if (db.dialect === "postgres") {
173
+ await db.sql`
174
+ update ${j}
175
+ set claimed_at = ${now}, claim_token = ${token}, attempts = attempts + 1
176
+ where id in (
177
+ select id from ${j}
178
+ where run_at <= ${now}
179
+ and attempts < max_attempts
180
+ and (claim_token is null or claimed_at < ${cutoff})
181
+ order by run_at
182
+ limit ${limit}
183
+ for update skip locked
184
+ )
185
+ and attempts < max_attempts
186
+ and (claim_token is null or claimed_at < ${cutoff})`;
187
+ } else {
188
+ await db.sql`
189
+ update ${j}
190
+ set claimed_at = ${now}, claim_token = ${token}, attempts = attempts + 1
191
+ where id in (
192
+ select id from ${j}
193
+ where run_at <= ${now}
194
+ and attempts < max_attempts
195
+ and (claim_token is null or claimed_at < ${cutoff})
196
+ order by run_at
197
+ limit ${limit}
198
+ )
199
+ and attempts < max_attempts
200
+ and (claim_token is null or claimed_at < ${cutoff})`;
201
+ }
202
+ return (await db
203
+ .from(j)
204
+ .where(j.claimToken.eq(token))
205
+ .orderBy(j.runAt)) as JobRow[];
315
206
  }
316
207
 
317
208
  async complete(id: string): Promise<void> {
318
209
  if (this.isScheduled(id)) return this.reschedule(id);
319
- await this.store.query(`DELETE FROM ${this.table} WHERE id = ?`, [id]);
210
+ const j = this.table;
211
+ await this.db().delete(j).where(j.id.eq(id));
320
212
  }
321
213
 
322
214
  /**
323
215
  * Record a failure.
324
216
  *
325
- * The row stays, because retry is the point. `claimed_at` is cleared so
326
- * the next pass can take it, and `run_at` is pushed into the future for
327
- * a failed job so a persistently broken handler does not spin — a
328
- * crash-looping job would otherwise burn a worker in a tight loop.
217
+ * The row stays, because retry is the point. The claim is cleared so the
218
+ * next pass can take it, and `run_at` is pushed into the future so a
219
+ * persistently broken handler does not spin — a crash-looping job would
220
+ * otherwise burn a worker in a tight loop.
329
221
  */
330
222
  async fail(id: string, error: unknown, backoffMs = 30_000): Promise<void> {
223
+ const j = this.table;
331
224
  const message = error instanceof Error ? error.message : String(error);
332
- const nextRun = this.ts(new Date(Date.now() + backoffMs));
333
- await this.store.query(
334
- `UPDATE ${this.table}
335
- SET last_error = ?, claimed_at = NULL, claim_token = NULL, run_at = ?
336
- WHERE id = ?`,
337
- [message.slice(0, 2000), nextRun, id],
338
- );
225
+ await this.db()
226
+ .update(j)
227
+ .set({
228
+ lastError: message.slice(0, 2000),
229
+ claimedAt: null,
230
+ claimToken: null,
231
+ runAt: new Date(Date.now() + backoffMs),
232
+ })
233
+ .where(j.id.eq(id));
339
234
  }
340
235
 
341
236
  /**
342
- * Put a job back on the queue immediately, for manual recovery.
343
- *
344
- * Reports whether the row existed. That used to come from
345
- * `UPDATE ... RETURNING id`, which no dialect other than postgres and
346
- * sqlite has, so a store without RETURNING has to check first. One extra
347
- * query in exchange for an honest return value on every dialect —
348
- * returning `true` unconditionally would tell a caller it had recovered a
349
- * job that does not exist.
237
+ * Stop retrying a job: it stays in the table as failed, with the reason,
238
+ * for `sigil jobs retry` once whatever was wrong is fixed. For a failure
239
+ * another try cannot fix, like a payload the job no longer accepts.
350
240
  */
241
+ async bury(id: string, reason: string): Promise<void> {
242
+ const j = this.table;
243
+ await this.db()
244
+ .update(j)
245
+ .set({
246
+ lastError: reason.slice(0, 2000),
247
+ claimedAt: null,
248
+ claimToken: null,
249
+ attempts: this.db().sql`max_attempts`,
250
+ })
251
+ .where(j.id.eq(id));
252
+ }
253
+
254
+ /** Put a job back on the queue now, for manual recovery. False when there is no such job. */
351
255
  async retry(id: string): Promise<boolean> {
352
- const found = await this.store.query<{ id: string }>(
353
- `SELECT id FROM ${this.table} WHERE id = ?`,
354
- [id],
355
- );
356
- if (found.length === 0) return false;
357
- await this.store.query(
358
- `UPDATE ${this.table}
359
- SET attempts = 0, last_error = NULL, claimed_at = NULL, claim_token = NULL, run_at = ?
360
- WHERE id = ?`,
361
- [this.ts(new Date()), id],
362
- );
363
- return true;
256
+ const j = this.table;
257
+ const updated = await this.db()
258
+ .update(j)
259
+ .set({
260
+ attempts: 0,
261
+ lastError: null,
262
+ claimedAt: null,
263
+ claimToken: null,
264
+ runAt: new Date(),
265
+ })
266
+ .where(j.id.eq(id));
267
+ return updated.length > 0;
364
268
  }
365
269
 
366
270
  async list(limit = 20): Promise<JobRow[]> {
367
- return this.store.query<JobRow>(
368
- `SELECT ${"id, name, payload, run_at, attempts, max_attempts, last_error, claimed_at, claim_token, created_at"}
369
- FROM ${this.table}
370
- ORDER BY created_at DESC
371
- LIMIT ?`,
372
- [limit],
373
- );
271
+ const j = this.table;
272
+ return (await this.db()
273
+ .from(j)
274
+ .orderBy(j.createdAt.desc())
275
+ .limit(limit)) as JobRow[];
374
276
  }
375
277
 
376
278
  async stats(): Promise<JobStats> {
377
- const rows = await this.store.query<{ bucket: string; count: number }>(
378
- `SELECT
379
- CASE
380
- WHEN attempts >= max_attempts THEN 'failed'
381
- WHEN claimed_at IS NOT NULL THEN 'claimed'
382
- ELSE 'pending'
383
- END AS bucket,
384
- COUNT(*) AS count
385
- FROM ${this.table}
386
- GROUP BY bucket`,
387
- );
388
- const stats: JobStats = { pending: 0, claimed: 0, failed: 0 };
389
- for (const row of rows) {
390
- if (row.bucket === "failed") stats.failed = Number(row.count);
391
- else if (row.bucket === "claimed") stats.claimed = Number(row.count);
392
- else stats.pending = Number(row.count);
393
- }
394
- return stats;
279
+ const db = this.db();
280
+ const j = this.table;
281
+ const [row] = (await db.sql`
282
+ select
283
+ sum(case when attempts >= max_attempts then 1 else 0 end) as failed,
284
+ sum(case when attempts < max_attempts and claimed_at is not null then 1 else 0 end) as claimed,
285
+ sum(case when attempts < max_attempts and claimed_at is null then 1 else 0 end) as pending
286
+ from ${j}`) as { failed: unknown; claimed: unknown; pending: unknown }[];
287
+ return {
288
+ pending: Number(row?.pending ?? 0),
289
+ claimed: Number(row?.claimed ?? 0),
290
+ failed: Number(row?.failed ?? 0),
291
+ };
395
292
  }
396
293
  }
package/schema.ts ADDED
@@ -0,0 +1,46 @@
1
+ import { index, t, table } from "@sigil-dev/tome";
2
+
3
+ /**
4
+ * The queue's table, as a tome table: spread it into the schema and tome's
5
+ * migrations create it like any other.
6
+ *
7
+ * `payload` is JSON kept as text, not a json column: a row whose payload
8
+ * cannot be read fails that one job in the worker, instead of failing the
9
+ * claim that decodes the whole batch.
10
+ */
11
+ export function jobsTable<const N extends string = "sigil_jobs">(
12
+ name: N = "sigil_jobs" as N,
13
+ ) {
14
+ // One object per name: tome finds a table by identity, and two jobs()
15
+ // for the same table (a second module, a test) must agree on it.
16
+ const cached = made.get(name);
17
+ if (cached) return cached as ReturnType<typeof define<N>>;
18
+ const built = define(name);
19
+ made.set(name, built);
20
+ return built;
21
+ }
22
+
23
+ const made = new Map<string, unknown>();
24
+
25
+ function define<const N extends string>(name: N) {
26
+ return table(
27
+ name,
28
+ {
29
+ id: t.text().primaryKey(),
30
+ name: t.text(),
31
+ payload: t.text(),
32
+ runAt: t.timestamp(),
33
+ attempts: t.integer().default(0),
34
+ maxAttempts: t.integer().default(5),
35
+ lastError: t.text().nullable(),
36
+ claimedAt: t.timestamp().nullable(),
37
+ // Which claim pass took the row: a random token, so the pass can
38
+ // read back exactly the rows it won.
39
+ claimToken: t.text().nullable(),
40
+ createdAt: t.timestamp().defaultNow(),
41
+ },
42
+ (j) => [index(j.runAt)],
43
+ );
44
+ }
45
+
46
+ export type JobsTable = ReturnType<typeof define<string>>;