@sigil-dev/plugin-jobs 0.9.21 → 0.9.22

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.
Files changed (8) hide show
  1. package/README.md +159 -154
  2. package/index.ts +480 -452
  3. package/package.json +3 -3
  4. package/queue.ts +396 -396
  5. package/store-bun.ts +137 -137
  6. package/store-drizzle.ts +86 -86
  7. package/store.ts +117 -117
  8. package/worker.ts +128 -128
package/store-bun.ts CHANGED
@@ -1,137 +1,137 @@
1
- import { database } from "@sigil-dev/plugin-sql";
2
- import type { Capabilities, JobStore } from "./store.ts";
3
-
4
- /**
5
- * A JobStore over `Bun.SQL`, with the dialect capabilities detected from the
6
- * DSN.
7
- *
8
- * The queue is dialect-agnostic on purpose. This is where the dialect
9
- * knowledge lives, in one place, from a value the user already gave us.
10
- *
11
- * The three capabilities are read off the URL scheme, not probed at runtime,
12
- * because probing means running queries at boot against a database that may
13
- * not be up yet — and this plugin deliberately does not open a connection
14
- * until the queue is used. A wrong guess is loud here: a missing
15
- * `spaceSeparatedTimestamp` on MySQL fails the first INSERT with
16
- * "Incorrect datetime value", not silently.
17
- */
18
- export function bunSqlStore(url: string, extra: Partial<Capabilities> = {}): JobStore {
19
- return bunStore(new Bun.SQL({ url, max: 1 }), url, extra);
20
- }
21
-
22
- /**
23
- * A JobStore over a `Bun.SQL` the caller already owns.
24
- *
25
- * This is the bridge that lets the queue run on the connection the SQL plugin
26
- * opened, rather than a second pool. `bunSqlStore(url)` is for when the queue
27
- * is the only thing using the database; this is for when an app already
28
- * registered `@sigil-dev/plugin-sql` and the budget should be spent once:
29
- *
30
- * import { adapter } from "@sigil-dev/plugin-sql/bun";
31
- * import { jobs, bunStore } from "@sigil-dev/plugin-jobs";
32
- *
33
- * const db = adapter(url, { maxTotal: 12 });
34
- * const queue = jobs({
35
- * // read from the plugin's own client, don't open a second pool
36
- * store: (services) => bunStore(services.db as Bun.SQL),
37
- * });
38
- *
39
- * The dialect is read from the client, which already parsed the DSN, so
40
- * `url` is only a fallback for a client that does not say. Through
41
- * plugin-sql's `locals.db`, a job enqueued during a `perRequestTx` request
42
- * is part of that request's transaction and rolls back with it.
43
- *
44
- * The placeholder translation is the same one `bunSqlStore` uses, because
45
- * the queue speaks `?` and postgres wants $1. It lives in this function
46
- * rather than in either caller so the two cannot drift.
47
- */
48
- type Dialect = "postgres" | "mysql" | "sqlite";
49
-
50
- /**
51
- * Which database a `Bun.SQL` client talks to.
52
- *
53
- * Asked of the client first: Bun.SQL already parsed the DSN, including the
54
- * spellings a scheme check misses — `postgresql://`, which Neon and Supabase
55
- * hand out, and `mariadb://`. Reading the scheme alone sent a `postgresql://`
56
- * client `?` placeholders.
57
- */
58
- function dialectOf(db: Bun.SQL, url?: string): Dialect {
59
- const fromClient = (db as unknown as { options?: { adapter?: string } })
60
- .options?.adapter;
61
- const raw = (fromClient ?? url?.split(":")[0] ?? "").toLowerCase();
62
- if (raw === "postgres" || raw === "postgresql" || raw === "pg") return "postgres";
63
- if (raw === "mysql" || raw === "mariadb") return "mysql";
64
- // A bare path is a SQLite file to Bun.SQL, and so it is here.
65
- return "sqlite";
66
- }
67
-
68
- export function bunStore(
69
- db: Bun.SQL,
70
- url?: string,
71
- extra: Partial<Capabilities> = {},
72
- ): JobStore {
73
- const dialect = dialectOf(db, url);
74
- const capabilities: Capabilities = {
75
- skipLocked: dialect === "postgres" || dialect === "mysql",
76
- spaceSeparatedTimestamp: dialect === "mysql",
77
- ...extra,
78
- };
79
-
80
- // Two things have to be reconciled for the queue's `?` placeholders:
81
- // postgres wants $1, $2, and mysql wants ? (so it passes through).
82
- // Doing it here means queue.ts contains no dialect knowledge at all.
83
- const placeholder = (text: string): string => {
84
- if (dialect !== "postgres") return text;
85
- let i = 0;
86
- return text.replace(/\?/g, () => `$${++i}`);
87
- };
88
-
89
- return {
90
- capabilities,
91
- async query<T>(text: string, params: unknown[] = []): Promise<T[]> {
92
- // unsafe() is required rather than query(): the queue builds its
93
- // SQL as strings, so the values have to be bound separately or
94
- // they are an injection waiting to happen.
95
- return (await db.unsafe(placeholder(text), params as never[])) as T[];
96
- },
97
- };
98
- }
99
-
100
- /**
101
- * A JobStore over a database `@sigil-dev/plugin-sql` registered, by name.
102
- *
103
- * This is what `jobs()` uses when given neither `sql` nor `store`, and it
104
- * removes the three things the `store` bridge made you get right:
105
- *
106
- * - Order. It looks the database up when a query runs, so the jobs plugin
107
- * can sit anywhere in the plugins array.
108
- * - The CLI. `sigil jobs work` has no server to publish services, but it
109
- * has the config, which registered the database; the command opens it.
110
- * - The request transaction. Every query goes through `db()`, so a job
111
- * enqueued during a `perRequestTx` request is part of it, and one
112
- * enqueued anywhere else runs on the pool.
113
- */
114
- export function databaseStore(name = "db", extra: Partial<Capabilities> = {}): JobStore {
115
- const db = database<Bun.SQL>(name);
116
- // The dialect is the client's, and there is no client until the database
117
- // opens — so it is read on first use and kept.
118
- let dialect: ReturnType<typeof dialectOf> | undefined;
119
- const dialectNow = () => (dialect ??= dialectOf(db.pool()));
120
-
121
- return {
122
- get capabilities(): Capabilities {
123
- const d = dialectNow();
124
- return {
125
- skipLocked: d === "postgres" || d === "mysql",
126
- spaceSeparatedTimestamp: d === "mysql",
127
- ...extra,
128
- };
129
- },
130
- async query<T>(text: string, params: unknown[] = []): Promise<T[]> {
131
- let i = 0;
132
- const sql = dialectNow() === "postgres" ? text.replace(/\?/g, () => `$${++i}`) : text;
133
- const client = db.db() as Bun.SQL;
134
- return (await client.unsafe(sql, params as never[])) as T[];
135
- },
136
- };
137
- }
1
+ import { database } from "@sigil-dev/plugin-sql";
2
+ import type { Capabilities, JobStore } from "./store.ts";
3
+
4
+ /**
5
+ * A JobStore over `Bun.SQL`, with the dialect capabilities detected from the
6
+ * DSN.
7
+ *
8
+ * The queue is dialect-agnostic on purpose. This is where the dialect
9
+ * knowledge lives, in one place, from a value the user already gave us.
10
+ *
11
+ * The three capabilities are read off the URL scheme, not probed at runtime,
12
+ * because probing means running queries at boot against a database that may
13
+ * not be up yet — and this plugin deliberately does not open a connection
14
+ * until the queue is used. A wrong guess is loud here: a missing
15
+ * `spaceSeparatedTimestamp` on MySQL fails the first INSERT with
16
+ * "Incorrect datetime value", not silently.
17
+ */
18
+ export function bunSqlStore(url: string, extra: Partial<Capabilities> = {}): JobStore {
19
+ return bunStore(new Bun.SQL({ url, max: 1 }), url, extra);
20
+ }
21
+
22
+ /**
23
+ * A JobStore over a `Bun.SQL` the caller already owns.
24
+ *
25
+ * This is the bridge that lets the queue run on the connection the SQL plugin
26
+ * opened, rather than a second pool. `bunSqlStore(url)` is for when the queue
27
+ * is the only thing using the database; this is for when an app already
28
+ * registered `@sigil-dev/plugin-sql` and the budget should be spent once:
29
+ *
30
+ * import { adapter } from "@sigil-dev/plugin-sql/bun";
31
+ * import { jobs, bunStore } from "@sigil-dev/plugin-jobs";
32
+ *
33
+ * const db = adapter(url, { maxTotal: 12 });
34
+ * const queue = jobs({
35
+ * // read from the plugin's own client, don't open a second pool
36
+ * store: (services) => bunStore(services.db as Bun.SQL),
37
+ * });
38
+ *
39
+ * The dialect is read from the client, which already parsed the DSN, so
40
+ * `url` is only a fallback for a client that does not say. Through
41
+ * plugin-sql's `locals.db`, a job enqueued during a `perRequestTx` request
42
+ * is part of that request's transaction and rolls back with it.
43
+ *
44
+ * The placeholder translation is the same one `bunSqlStore` uses, because
45
+ * the queue speaks `?` and postgres wants $1. It lives in this function
46
+ * rather than in either caller so the two cannot drift.
47
+ */
48
+ type Dialect = "postgres" | "mysql" | "sqlite";
49
+
50
+ /**
51
+ * Which database a `Bun.SQL` client talks to.
52
+ *
53
+ * Asked of the client first: Bun.SQL already parsed the DSN, including the
54
+ * spellings a scheme check misses — `postgresql://`, which Neon and Supabase
55
+ * hand out, and `mariadb://`. Reading the scheme alone sent a `postgresql://`
56
+ * client `?` placeholders.
57
+ */
58
+ function dialectOf(db: Bun.SQL, url?: string): Dialect {
59
+ const fromClient = (db as unknown as { options?: { adapter?: string } })
60
+ .options?.adapter;
61
+ const raw = (fromClient ?? url?.split(":")[0] ?? "").toLowerCase();
62
+ if (raw === "postgres" || raw === "postgresql" || raw === "pg") return "postgres";
63
+ if (raw === "mysql" || raw === "mariadb") return "mysql";
64
+ // A bare path is a SQLite file to Bun.SQL, and so it is here.
65
+ return "sqlite";
66
+ }
67
+
68
+ export function bunStore(
69
+ db: Bun.SQL,
70
+ url?: string,
71
+ extra: Partial<Capabilities> = {},
72
+ ): JobStore {
73
+ const dialect = dialectOf(db, url);
74
+ const capabilities: Capabilities = {
75
+ skipLocked: dialect === "postgres" || dialect === "mysql",
76
+ spaceSeparatedTimestamp: dialect === "mysql",
77
+ ...extra,
78
+ };
79
+
80
+ // Two things have to be reconciled for the queue's `?` placeholders:
81
+ // postgres wants $1, $2, and mysql wants ? (so it passes through).
82
+ // Doing it here means queue.ts contains no dialect knowledge at all.
83
+ const placeholder = (text: string): string => {
84
+ if (dialect !== "postgres") return text;
85
+ let i = 0;
86
+ return text.replace(/\?/g, () => `$${++i}`);
87
+ };
88
+
89
+ return {
90
+ capabilities,
91
+ async query<T>(text: string, params: unknown[] = []): Promise<T[]> {
92
+ // unsafe() is required rather than query(): the queue builds its
93
+ // SQL as strings, so the values have to be bound separately or
94
+ // they are an injection waiting to happen.
95
+ return (await db.unsafe(placeholder(text), params as never[])) as T[];
96
+ },
97
+ };
98
+ }
99
+
100
+ /**
101
+ * A JobStore over a database `@sigil-dev/plugin-sql` registered, by name.
102
+ *
103
+ * This is what `jobs()` uses when given neither `sql` nor `store`, and it
104
+ * removes the three things the `store` bridge made you get right:
105
+ *
106
+ * - Order. It looks the database up when a query runs, so the jobs plugin
107
+ * can sit anywhere in the plugins array.
108
+ * - The CLI. `sigil jobs work` has no server to publish services, but it
109
+ * has the config, which registered the database; the command opens it.
110
+ * - The request transaction. Every query goes through `db()`, so a job
111
+ * enqueued during a `perRequestTx` request is part of it, and one
112
+ * enqueued anywhere else runs on the pool.
113
+ */
114
+ export function databaseStore(name = "db", extra: Partial<Capabilities> = {}): JobStore {
115
+ const db = database<Bun.SQL>(name);
116
+ // The dialect is the client's, and there is no client until the database
117
+ // opens — so it is read on first use and kept.
118
+ let dialect: ReturnType<typeof dialectOf> | undefined;
119
+ const dialectNow = () => (dialect ??= dialectOf(db.pool()));
120
+
121
+ return {
122
+ get capabilities(): Capabilities {
123
+ const d = dialectNow();
124
+ return {
125
+ skipLocked: d === "postgres" || d === "mysql",
126
+ spaceSeparatedTimestamp: d === "mysql",
127
+ ...extra,
128
+ };
129
+ },
130
+ async query<T>(text: string, params: unknown[] = []): Promise<T[]> {
131
+ let i = 0;
132
+ const sql = dialectNow() === "postgres" ? text.replace(/\?/g, () => `$${++i}`) : text;
133
+ const client = db.db() as Bun.SQL;
134
+ return (await client.unsafe(sql, params as never[])) as T[];
135
+ },
136
+ };
137
+ }
package/store-drizzle.ts CHANGED
@@ -1,86 +1,86 @@
1
- import type { JobStore } from "./store.ts";
2
-
3
- /**
4
- * A JobStore for a project that already uses Drizzle.
5
- *
6
- * ## Read this before you use it, because the honest answer is "reach past
7
- * ## drizzle"
8
- *
9
- * Measured against drizzle-orm 0.45.3 with a real Bun.SQL client, real
10
- * MariaDB and real postgres:
11
- *
12
- * - `db.execute("SELECT ? as n", [7])` does NOT bind. The `?` reaches
13
- * MariaDB as literal SQL and the server returns a syntax error. Drizzle's
14
- * `execute` takes a `SQLWrapper`, not a parameter array, and passing one
15
- * is silently ignored.
16
- * - `db.execute(dsql`SELECT ${3}`)` works on postgres and fails on MySQL
17
- * with "Unknown column '$1' in 'SELECT'". The bun-sql driver emits $1
18
- * placeholders unconditionally, so the same call, on the same db object,
19
- * is correct on one database and broken on another. That is a drizzle
20
- * bug, and it is why the obvious implementation of this adapter does not
21
- * work.
22
- * - `client.unsafe("SELECT ? as n", [7])` on the underlying Bun.SQL works.
23
- *
24
- * So the adapter is given a function to run SQL, not a Drizzle db. Passing
25
- * `db` and hoping would have produced a store that works on postgres, fails
26
- * on MySQL, and fails the moment a query has a parameter — which is every
27
- * query the queue runs.
28
- *
29
- * With a real Drizzle project, the connection is already a `Bun.SQL` (or a
30
- * `pg` Pool), so pass that. Drizzle is not in the path here, and the reason
31
- * is written above rather than left for someone to rediscover.
32
- *
33
- * If you want the queue to be a first-class Drizzle table instead — with
34
- * `db.select()`, `db.insert()`, `db.update()` rather than SQL text — that is
35
- * a real change to JobQueue, not an adapter: every query would be written
36
- * twice and the claim guard, which is what makes the queue correct, would
37
- * have to be proven in both paths.
38
- */
39
- export interface SqlRunner {
40
- /** Run SQL with bound parameters and return rows. */
41
- run: (query: string, params: unknown[]) => Promise<unknown>;
42
- }
43
-
44
- export function drizzleStore(
45
- run: SqlRunner,
46
- dialect: "postgres" | "mysql" | "sqlite",
47
- ): JobStore {
48
- const capabilities = {
49
- skipLocked: dialect === "postgres" || dialect === "mysql",
50
- spaceSeparatedTimestamp: dialect === "mysql",
51
- };
52
-
53
- return {
54
- capabilities,
55
- async query<T>(text: string, params: unknown[] = []): Promise<T[]> {
56
- // postgres wants $1..$n, MySQL and sqlite want ?. The queue emits
57
- // `?` because that is the wider convention, so the rewrite happens
58
- // here — once, for one dialect, rather than in every caller.
59
- let i = 0;
60
- const stmt =
61
- dialect === "postgres" ? text.replace(/\?/g, () => `$${++i}`) : text;
62
- const result = await run.run(stmt, params);
63
- // Measured return shapes: a plain row array for both execute(string)
64
- // and dsql.raw. The object cases below are for the node-postgres and
65
- // neon drivers, which wrap rows — a DrizzleLike from those would
66
- // otherwise return { rows: [...] } to the queue and every query
67
- // would look like it matched nothing.
68
- if (Array.isArray(result)) return result as T[];
69
- if (result && typeof result === "object") {
70
- const r = result as Record<string, unknown>;
71
- if (Array.isArray(r.rows)) return r.rows as T[];
72
- }
73
- return [];
74
- },
75
- };
76
- }
77
-
78
- /**
79
- * A runner over a `Bun.SQL` client, which is what a Drizzle bun-sql project
80
- * already holds. This is the supported entry point.
81
- */
82
- export function bunSqlRunner(client: {
83
- unsafe(text: string, params?: unknown[]): Promise<unknown>;
84
- }): SqlRunner {
85
- return { run: (text, params) => client.unsafe(text, params) };
86
- }
1
+ import type { JobStore } from "./store.ts";
2
+
3
+ /**
4
+ * A JobStore for a project that already uses Drizzle.
5
+ *
6
+ * ## Read this before you use it, because the honest answer is "reach past
7
+ * ## drizzle"
8
+ *
9
+ * Measured against drizzle-orm 0.45.3 with a real Bun.SQL client, real
10
+ * MariaDB and real postgres:
11
+ *
12
+ * - `db.execute("SELECT ? as n", [7])` does NOT bind. The `?` reaches
13
+ * MariaDB as literal SQL and the server returns a syntax error. Drizzle's
14
+ * `execute` takes a `SQLWrapper`, not a parameter array, and passing one
15
+ * is silently ignored.
16
+ * - `db.execute(dsql`SELECT ${3}`)` works on postgres and fails on MySQL
17
+ * with "Unknown column '$1' in 'SELECT'". The bun-sql driver emits $1
18
+ * placeholders unconditionally, so the same call, on the same db object,
19
+ * is correct on one database and broken on another. That is a drizzle
20
+ * bug, and it is why the obvious implementation of this adapter does not
21
+ * work.
22
+ * - `client.unsafe("SELECT ? as n", [7])` on the underlying Bun.SQL works.
23
+ *
24
+ * So the adapter is given a function to run SQL, not a Drizzle db. Passing
25
+ * `db` and hoping would have produced a store that works on postgres, fails
26
+ * on MySQL, and fails the moment a query has a parameter — which is every
27
+ * query the queue runs.
28
+ *
29
+ * With a real Drizzle project, the connection is already a `Bun.SQL` (or a
30
+ * `pg` Pool), so pass that. Drizzle is not in the path here, and the reason
31
+ * is written above rather than left for someone to rediscover.
32
+ *
33
+ * If you want the queue to be a first-class Drizzle table instead — with
34
+ * `db.select()`, `db.insert()`, `db.update()` rather than SQL text — that is
35
+ * a real change to JobQueue, not an adapter: every query would be written
36
+ * twice and the claim guard, which is what makes the queue correct, would
37
+ * have to be proven in both paths.
38
+ */
39
+ export interface SqlRunner {
40
+ /** Run SQL with bound parameters and return rows. */
41
+ run: (query: string, params: unknown[]) => Promise<unknown>;
42
+ }
43
+
44
+ export function drizzleStore(
45
+ run: SqlRunner,
46
+ dialect: "postgres" | "mysql" | "sqlite",
47
+ ): JobStore {
48
+ const capabilities = {
49
+ skipLocked: dialect === "postgres" || dialect === "mysql",
50
+ spaceSeparatedTimestamp: dialect === "mysql",
51
+ };
52
+
53
+ return {
54
+ capabilities,
55
+ async query<T>(text: string, params: unknown[] = []): Promise<T[]> {
56
+ // postgres wants $1..$n, MySQL and sqlite want ?. The queue emits
57
+ // `?` because that is the wider convention, so the rewrite happens
58
+ // here — once, for one dialect, rather than in every caller.
59
+ let i = 0;
60
+ const stmt =
61
+ dialect === "postgres" ? text.replace(/\?/g, () => `$${++i}`) : text;
62
+ const result = await run.run(stmt, params);
63
+ // Measured return shapes: a plain row array for both execute(string)
64
+ // and dsql.raw. The object cases below are for the node-postgres and
65
+ // neon drivers, which wrap rows — a DrizzleLike from those would
66
+ // otherwise return { rows: [...] } to the queue and every query
67
+ // would look like it matched nothing.
68
+ if (Array.isArray(result)) return result as T[];
69
+ if (result && typeof result === "object") {
70
+ const r = result as Record<string, unknown>;
71
+ if (Array.isArray(r.rows)) return r.rows as T[];
72
+ }
73
+ return [];
74
+ },
75
+ };
76
+ }
77
+
78
+ /**
79
+ * A runner over a `Bun.SQL` client, which is what a Drizzle bun-sql project
80
+ * already holds. This is the supported entry point.
81
+ */
82
+ export function bunSqlRunner(client: {
83
+ unsafe(text: string, params?: unknown[]): Promise<unknown>;
84
+ }): SqlRunner {
85
+ return { run: (text, params) => client.unsafe(text, params) };
86
+ }