@sigil-dev/plugin-sql 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/README.md CHANGED
@@ -9,7 +9,7 @@ proves one behaves, and an official adapter for `Bun.SQL`.
9
9
  import { adapter } from "@sigil-dev/plugin-sql/bun";
10
10
 
11
11
  export default {
12
- plugins: [adapter(process.env.DATABASE_URL!, { maxTotal: 20 })],
12
+ plugins: [adapter({ env: "DATABASE_URL", maxTotal: 20 })],
13
13
  };
14
14
  ```
15
15
 
package/package.json CHANGED
@@ -11,7 +11,7 @@
11
11
  "module": "src/index.ts",
12
12
  "type": "module",
13
13
  "private": false,
14
- "version": "0.9.28",
14
+ "version": "0.9.30",
15
15
  "keywords": [
16
16
  "grimoire",
17
17
  "sigil",
@@ -26,7 +26,7 @@
26
26
  ],
27
27
  "peerDependencies": {
28
28
  "typescript": "^5",
29
- "@sigil-dev/grimoire": "0.9.28"
29
+ "@sigil-dev/grimoire": "0.9.30"
30
30
  },
31
31
  "exports": {
32
32
  ".": "./src/index.ts",
package/src/bun.ts CHANGED
@@ -13,12 +13,11 @@
13
13
  * in that file rather than here.
14
14
  */
15
15
 
16
-
17
16
  import {
18
17
  defineSqlAdapter,
19
- sql,
20
18
  type SqlAdapter,
21
19
  type SqlPluginOptions,
20
+ sql,
22
21
  } from "./contract.ts";
23
22
  import type { DatabasePlugin, SqlHandle } from "./database.ts";
24
23
 
@@ -67,7 +66,12 @@ export interface BunSqlOptions {
67
66
  */
68
67
  export type BunSqlConnection =
69
68
  | string
70
- | ({ url?: string; maxTotal?: number } & Record<string, unknown>);
69
+ | ({ url?: string; maxTotal?: number } & Record<string, unknown>)
70
+ | ({
71
+ /** The variable holding the URL, read when the server starts. */
72
+ env: string;
73
+ maxTotal?: number;
74
+ } & Record<string, unknown>);
71
75
 
72
76
  /**
73
77
  * Split a connection into driver options and the budget, refusing the one
@@ -77,7 +81,8 @@ function connectionOf(
77
81
  dsn: BunSqlConnection,
78
82
  opts: BunSqlOptions,
79
83
  ): { driver: Record<string, unknown>; maxTotal: number | undefined } {
80
- if (typeof dsn === "string") return { driver: { url: dsn }, maxTotal: opts.maxTotal };
84
+ if (typeof dsn === "string")
85
+ return { driver: { url: dsn }, maxTotal: opts.maxTotal };
81
86
  const { maxTotal: inline, ...driver } = dsn;
82
87
  if ("max" in driver) {
83
88
  // `max` is Bun.SQL's per-client pool size. Passed here it goes
@@ -89,7 +94,11 @@ function connectionOf(
89
94
  "deployment; it is divided by the worker count for you.",
90
95
  );
91
96
  }
92
- if (inline !== undefined && opts.maxTotal !== undefined && inline !== opts.maxTotal) {
97
+ if (
98
+ inline !== undefined &&
99
+ opts.maxTotal !== undefined &&
100
+ inline !== opts.maxTotal
101
+ ) {
93
102
  throw new Error(
94
103
  `bunSqlAdapter: maxTotal is ${inline} in the connection and ` +
95
104
  `${opts.maxTotal} in the options. Give it once.`,
@@ -108,15 +117,19 @@ function connectionOf(
108
117
  * ```
109
118
  */
110
119
  export function bunSqlAdapter(
111
- dsn: BunSqlConnection,
120
+ dsn: BunSqlConnection | (() => BunSqlConnection),
112
121
  opts: BunSqlOptions = {},
113
122
  ): SqlAdapter<SQL> {
114
- // Split now, so a wrong spelling fails where the config is written.
115
- const { driver, maxTotal } = connectionOf(dsn, opts);
123
+ // Split now, so a wrong spelling fails where the config is written. A
124
+ // function is a connection read when the server starts (`adapter()`
125
+ // reading DATABASE_URL), so it is split then.
126
+ const eager = typeof dsn === "function" ? undefined : connectionOf(dsn, opts);
116
127
  return defineSqlAdapter<SQL>({
117
128
  contract: 1,
118
129
  name: "bun-sql",
119
130
  create({ workers }) {
131
+ const { driver, maxTotal } =
132
+ eager ?? connectionOf((dsn as () => BunSqlConnection)(), opts);
120
133
  const total = maxTotal;
121
134
  // Bun.SQL is a value, and this module is type-only about it
122
135
  // otherwise — naming the type keeps the public signature honest.
@@ -169,7 +182,10 @@ export function bunSqlAdapter(
169
182
  * `client.array(xs, t)`, on the client that runs the query.
170
183
  */
171
184
  helper(target, method, args) {
172
- const c = target as unknown as Record<string, (...a: unknown[]) => unknown> &
185
+ const c = target as unknown as Record<
186
+ string,
187
+ (...a: unknown[]) => unknown
188
+ > &
173
189
  ((...a: unknown[]) => unknown);
174
190
  if (method === undefined) return c(...args);
175
191
  const fn = c[method];
@@ -180,9 +196,11 @@ export function bunSqlAdapter(
180
196
  },
181
197
  /** `SAVEPOINT`, so a nested transaction can roll back alone. */
182
198
  savepoint: (tx, fn) =>
183
- (tx as unknown as {
184
- savepoint<R>(fn: (sp: SQL) => Promise<R>): Promise<R>;
185
- }).savepoint(fn),
199
+ (
200
+ tx as unknown as {
201
+ savepoint<R>(fn: (sp: SQL) => Promise<R>): Promise<R>;
202
+ }
203
+ ).savepoint(fn),
186
204
  },
187
205
  });
188
206
  }
@@ -196,9 +214,17 @@ const templates = new WeakMap<readonly string[], TemplateStringsArray>();
196
214
  function templateOf(strings: readonly string[]): TemplateStringsArray {
197
215
  let t = templates.get(strings);
198
216
  if (!t) {
199
- t = Object.freeze(
200
- Object.assign([...strings], { raw: Object.freeze([...strings]) }),
201
- ) as unknown as TemplateStringsArray;
217
+ // Shaped like a real template object: `raw` must be non-enumerable
218
+ // (Bun >= 1.4's `isTemplateObject` rejects an enumerable one), and
219
+ // both arrays frozen. `Object.assign` would make `raw` enumerable.
220
+ const arr = [...strings];
221
+ Object.defineProperty(arr, "raw", {
222
+ value: Object.freeze([...strings]),
223
+ enumerable: false,
224
+ writable: false,
225
+ configurable: false,
226
+ });
227
+ t = Object.freeze(arr) as unknown as TemplateStringsArray;
202
228
  templates.set(strings, t);
203
229
  }
204
230
  return t;
@@ -224,15 +250,20 @@ export interface AdapterOptions extends BunSqlOptions, SqlPluginOptions<SQL> {
224
250
  * import { adapter } from "@sigil-dev/plugin-sql/bun";
225
251
  *
226
252
  * export default {
227
- * plugins: [adapter(Bun.env.DATABASE_URL!, { maxTotal: 20 })],
253
+ * plugins: [adapter()], // DATABASE_URL, read when the server starts
228
254
  * };
229
255
  * ```
230
256
  *
257
+ * Name the variable to use another one, or to add options:
258
+ * `adapter({ env: "VIEWER_DB_URL", maxTotal: 20 })`. It is read when the
259
+ * server starts, not while the config loads, so `sigil build` and the CLI
260
+ * never need the secret.
261
+ *
231
262
  * The connection may be one object that also carries the plugin's identity,
232
263
  * which is the form to prefer when there is more than one database:
233
264
  *
234
265
  * ```ts
235
- * adapter({ key: "userDb", url: env.VIEWER_DB_URL, maxTotal: 4, optional: true })
266
+ * adapter({ key: "userDb", env: "VIEWER_DB_URL", maxTotal: 4, optional: true })
236
267
  * ```
237
268
  *
238
269
  * The result is a plugin with a `.database` handle, so another plugin can be
@@ -247,17 +278,57 @@ export interface AdapterOptions extends BunSqlOptions, SqlPluginOptions<SQL> {
247
278
  * rather than reimplementing the lifecycle, so there is one code path to be
248
279
  * wrong about.
249
280
  */
281
+ /** The key a database lands on in `locals`: the options' `key`, the connection's, or "db". */
282
+ type KeyOf<D, O> = O extends { key: infer K extends string }
283
+ ? K
284
+ : D extends { key: infer K extends string }
285
+ ? K
286
+ : "db";
287
+ type IsOptional<D, O> = O extends { optional: true }
288
+ ? true
289
+ : D extends { optional: true }
290
+ ? true
291
+ : false;
292
+
293
+ /** What `adapter()` returns: the plugin, typed with what it puts on `locals`. */
294
+ export type BunDatabasePlugin<
295
+ K extends string = "db",
296
+ Optional = false,
297
+ > = DatabasePlugin<SQL> & {
298
+ readonly $locals?: Optional extends true
299
+ ? { [P in K]?: BunSqlHandle }
300
+ : { [P in K]: BunSqlHandle };
301
+ };
302
+
303
+ export function adapter<
304
+ const D extends BunSqlConnection | undefined = undefined,
305
+ const O extends AdapterOptions = {},
306
+ >(dsn?: D, options?: O): BunDatabasePlugin<KeyOf<D, O>, IsOptional<D, O>>;
250
307
  export function adapter(
251
- dsn: BunSqlConnection | undefined,
308
+ dsn?: BunSqlConnection | undefined,
252
309
  options: AdapterOptions = {},
253
310
  ): DatabasePlugin<SQL> {
311
+ // `adapter()` with nothing is `adapter({ env: "DATABASE_URL" })`.
312
+ if (arguments.length === 0) dsn = { env: "DATABASE_URL" };
254
313
  // Plugin identity may ride in the connection object. Pull it out so it
255
314
  // never reaches Bun.SQL, and so a second place to say it is not a second
256
315
  // answer: a key given twice must agree.
316
+ let envName: string | undefined;
257
317
  if (dsn && typeof dsn === "object") {
258
- const { key: k, optional: o, perRequestTx: p, ...rest } = dsn as Record<string, unknown>;
318
+ const {
319
+ key: k,
320
+ optional: o,
321
+ perRequestTx: p,
322
+ env: e,
323
+ ...rest
324
+ } = dsn as Record<string, unknown>;
259
325
  if (k !== undefined && options.key !== undefined && k !== options.key) {
260
- throw new Error(`adapter: key is "${String(k)}" in the connection and "${options.key}" in the options. Give it once.`);
326
+ throw new Error(
327
+ `adapter: key is "${String(k)}" in the connection and "${options.key}" in the options. Give it once.`,
328
+ );
329
+ }
330
+ if (e !== undefined && "url" in rest) {
331
+ throw new Error("adapter: give either `url` or `env`, not both.");
261
332
  }
262
333
  options = {
263
334
  ...options,
@@ -265,28 +336,79 @@ export function adapter(
265
336
  optional: (o as boolean | undefined) ?? options.optional,
266
337
  perRequestTx: (p as boolean | undefined) ?? options.perRequestTx,
267
338
  };
339
+ envName = e as string | undefined;
268
340
  dsn = rest as BunSqlConnection;
269
341
  }
270
342
  const { optional, perRequestTx, key, ...budget } = options;
343
+ const name = key ?? "db";
344
+
345
+ // `env`: the URL is read when the server starts, not here. This config
346
+ // is also imported by `sigil build` and the CLI, where the server's
347
+ // secrets are usually unset, and reading them here broke the build.
348
+ if (envName !== undefined) {
349
+ const variable = envName;
350
+ const driver = dsn as Record<string, unknown>;
351
+ // The URL waits; a wrong spelling of the options still fails here.
352
+ connectionOf({ ...driver, url: "" }, budget);
353
+ // Optional means "start without it", which has to be decided now:
354
+ // hasDatabase() answers from the registry as soon as this returns.
355
+ if (optional && !process.env[variable]) {
356
+ return {
357
+ name: `sql:${name} (not configured)`,
358
+ key: name,
359
+ database: undefined,
360
+ };
361
+ }
362
+ const plugin = sql(
363
+ bunSqlAdapter(() => {
364
+ const url = process.env[variable];
365
+ if (!url) throw missingUrl(name, variable);
366
+ return { ...driver, url };
367
+ }, budget),
368
+ { perRequestTx, key },
369
+ );
370
+ return optional
371
+ ? plugin
372
+ : Object.assign(plugin, { requiredEnv: [variable] });
373
+ }
374
+
271
375
  const missing =
272
376
  dsn === undefined ||
273
377
  dsn === "" ||
274
378
  (typeof dsn === "object" && "url" in dsn && !dsn.url);
275
379
  if (missing) {
276
- const name = key ?? "db";
277
380
  if (optional) {
278
- return { name: `sql:${name} (not configured)`, key: name, database: undefined };
381
+ return {
382
+ name: `sql:${name} (not configured)`,
383
+ key: name,
384
+ database: undefined,
385
+ };
279
386
  }
280
387
  // Bun.SQL with no url connects to localhost with the OS user, which
281
388
  // fails later with a credentials error that never mentions the
282
- // variable that was empty.
283
- throw new Error(
284
- `adapter: database "${name}" has no connection URL — the environment ` +
285
- "variable is probably unset. Pass { optional: true } if the app " +
286
- "should start without it.",
389
+ // variable that was empty. So it fails, but when the server starts:
390
+ // failing here also failed `sigil build` and every CLI command.
391
+ return sql(
392
+ bunSqlAdapter(() => {
393
+ throw missingUrl(name);
394
+ }),
395
+ { perRequestTx, key },
287
396
  );
288
397
  }
289
- return sql(bunSqlAdapter(dsn as BunSqlConnection, budget), { perRequestTx, key });
398
+ return sql(bunSqlAdapter(dsn as BunSqlConnection, budget), {
399
+ perRequestTx,
400
+ key,
401
+ });
402
+ }
403
+
404
+ function missingUrl(name: string, variable?: string): Error {
405
+ return new Error(
406
+ `adapter: database "${name}" has no connection URL — ` +
407
+ (variable
408
+ ? `${variable} is unset`
409
+ : "the environment variable is probably unset") +
410
+ ". Pass { optional: true } if the app should start without it.",
411
+ );
290
412
  }
291
413
 
292
414
  export default adapter;
package/src/contract.ts CHANGED
@@ -18,12 +18,16 @@
18
18
  * ```
19
19
  */
20
20
 
21
- import { type GrimoirePlugin } from "@sigil-dev/grimoire";
22
- import { createDatabase, type Database, type DatabasePlugin } from "./database.ts";
23
21
  import {
24
- workerContext,
22
+ type GrimoirePlugin,
25
23
  type WorkerContext,
24
+ workerContext,
26
25
  } from "@sigil-dev/grimoire";
26
+ import {
27
+ createDatabase,
28
+ type Database,
29
+ type DatabasePlugin,
30
+ } from "./database.ts";
27
31
 
28
32
  export type { WorkerContext };
29
33
  export { workerContext };
@@ -107,10 +111,17 @@ export interface SqlCapabilities<C, Tx> {
107
111
  setLocal?(tx: Tx, key: string, value: string): Promise<void>;
108
112
 
109
113
  /** Subscribe to `LISTEN`/`NOTIFY`. Returns an unsubscribe function. */
110
- listen?(client: C, channel: string, cb: (payload: string) => void): Promise<() => void>;
114
+ listen?(
115
+ client: C,
116
+ channel: string,
117
+ cb: (payload: string) => void,
118
+ ): Promise<() => void>;
111
119
 
112
120
  /** Called after every query with its text and duration. */
113
- instrument?(client: C, onQuery: (q: { sql: string; ms: number }) => void): void;
121
+ instrument?(
122
+ client: C,
123
+ onQuery: (q: { sql: string; ms: number }) => void,
124
+ ): void;
114
125
 
115
126
  /**
116
127
  * Run a parameterised query and return rows.
@@ -155,7 +166,11 @@ export interface SqlCapabilities<C, Tx> {
155
166
  * Without this, `db.sql(...)` and `db.sql.array(...)` throw when called,
156
167
  * rather than binding an object the driver does not understand.
157
168
  */
158
- helper?(target: C | Tx, method: string | undefined, args: readonly unknown[]): unknown;
169
+ helper?(
170
+ target: C | Tx,
171
+ method: string | undefined,
172
+ args: readonly unknown[],
173
+ ): unknown;
159
174
  }
160
175
 
161
176
  /**
@@ -245,5 +260,8 @@ export function sql<C, Tx = C>(
245
260
  perRequestTx: opts.perRequestTx,
246
261
  key,
247
262
  });
248
- return Object.assign(db.plugin, { key, database: db as Database<C, Tx> | undefined });
263
+ return Object.assign(db.plugin, {
264
+ key,
265
+ database: db as Database<C, Tx> | undefined,
266
+ });
249
267
  }
package/src/database.ts CHANGED
@@ -1,18 +1,18 @@
1
1
  import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { type GrimoirePlugin, workerContext } from "@sigil-dev/grimoire";
3
+ import {
4
+ SQL_CONTRACT_VERSION,
5
+ type SqlAdapter,
6
+ type SqlCapabilities,
7
+ } from "./contract.ts";
2
8
  import {
3
9
  createFragment,
4
10
  createHelper,
5
- isHelper,
6
11
  type Fragment,
7
12
  type FragmentRunner,
13
+ isHelper,
8
14
  type SqlHelper,
9
15
  } from "./fragment.ts";
10
- import { workerContext, type GrimoirePlugin } from "@sigil-dev/grimoire";
11
- import {
12
- SQL_CONTRACT_VERSION,
13
- type SqlAdapter,
14
- type SqlCapabilities,
15
- } from "./contract.ts";
16
16
 
17
17
  /**
18
18
  * The `db.sql` tag. `T` is the row type; a run resolves to `T[]`.
@@ -29,10 +29,7 @@ import {
29
29
  */
30
30
  export interface SqlTag {
31
31
  // biome-ignore lint/suspicious/noExplicitAny: the default row, as in Bun.SQL
32
- <T = any>(
33
- strings: TemplateStringsArray,
34
- ...values: unknown[]
35
- ): Fragment<T>;
32
+ <T = any>(strings: TemplateStringsArray, ...values: unknown[]): Fragment<T>;
36
33
  (value: unknown, ...columns: string[]): SqlHelper;
37
34
  /** A postgres array parameter, e.g. for `= any(...)`. */
38
35
  array(values: readonly unknown[], type?: string): SqlHelper;
@@ -48,7 +45,10 @@ const isTemplate = (v: unknown): v is TemplateStringsArray =>
48
45
  */
49
46
  function buildTag(
50
47
  name: string,
51
- caps: () => { adapter: string; capabilities: SqlCapabilities<unknown, unknown> },
48
+ caps: () => {
49
+ adapter: string;
50
+ capabilities: SqlCapabilities<unknown, unknown>;
51
+ },
52
52
  pick: Pick<FragmentRunner, "run" | "runTx" | "runPool">,
53
53
  ): SqlTag {
54
54
  const runner: FragmentRunner = {
@@ -85,7 +85,10 @@ function buildTag(
85
85
  if (!capabilities.query || !capabilities.helper) {
86
86
  refuse("sql helpers", "helper");
87
87
  }
88
- return createHelper("array", type === undefined ? [values] : [values, type]);
88
+ return createHelper(
89
+ "array",
90
+ type === undefined ? [values] : [values, type],
91
+ );
89
92
  };
90
93
  return tag;
91
94
  }
@@ -265,7 +268,7 @@ export interface CreateDatabaseOptions {
265
268
  *
266
269
  * Held here rather than in the Database object so that every object with
267
270
  * the same name sees the same client. Two things create a second object:
268
- * the dev server re-evaluating `src/lib/server/db.ts` after an edit, and a
271
+ * the dev server re-evaluating `src/db/index.ts` after an edit, and a
269
272
  * bundle that inlines its own copy of that module. Without this, either one
270
273
  * holds a Database whose client was never opened, and fails with "used
271
274
  * before its client was opened" while the one the config registered works.
@@ -555,9 +558,9 @@ export function createDatabase<C, Tx = C>(
555
558
  if (typeof fn !== "function") {
556
559
  // Not the callback form (`begin()` with no callback, say):
557
560
  // leave it to the driver.
558
- return (active() as Record<PropertyKey, (...a: unknown[]) => unknown>)[
559
- prop as string
560
- ]!(...args);
561
+ return (
562
+ active() as Record<PropertyKey, (...a: unknown[]) => unknown>
563
+ )[prop as string]!(...args);
561
564
  }
562
565
  const body = fn as (tx: Tx) => Promise<unknown>;
563
566
  if (args.length === 1 || current() !== undefined) {
package/src/fragment.ts CHANGED
@@ -257,8 +257,7 @@ export function createFragment<T = any>(
257
257
  // `x.runTx().catch()` does not.
258
258
  const exec = (pick: () => unknown): Promise<T[]> =>
259
259
  Promise.resolve().then(
260
- () =>
261
- resolve.query(pick(), text, s.values, s.strings) as Promise<T[]>,
260
+ () => resolve.query(pick(), text, s.values, s.strings) as Promise<T[]>,
262
261
  );
263
262
 
264
263
  const frag: Fragment<T> = {
package/src/index.ts CHANGED
@@ -34,34 +34,34 @@
34
34
  */
35
35
 
36
36
  export {
37
+ type ClientOf,
37
38
  defineSqlAdapter,
38
- sql,
39
39
  SQL_CONTRACT_VERSION,
40
- workerContext,
41
- type ClientOf,
42
40
  type SqlAdapter,
43
41
  type SqlCapabilities,
44
42
  type SqlPluginOptions,
43
+ sql,
45
44
  type TxOf,
46
45
  type WorkerContext,
46
+ workerContext,
47
47
  } from "./contract.ts";
48
48
 
49
49
  export {
50
- createDatabase,
51
- database,
52
- hasDatabase,
53
50
  type CreateDatabaseOptions,
51
+ createDatabase,
54
52
  type Database,
55
53
  type DatabasePlugin,
54
+ database,
55
+ hasDatabase,
56
56
  type SqlHandle,
57
57
  type SqlTag,
58
58
  } from "./database.ts";
59
59
  export {
60
+ type Fragment,
60
61
  fragmentParts,
61
62
  isFragment,
62
63
  isHelper,
63
64
  SQL_FRAGMENT,
64
65
  SQL_HELPER,
65
- type Fragment,
66
66
  type SqlHelper,
67
67
  } from "./fragment.ts";
package/src/testing.ts CHANGED
@@ -17,7 +17,14 @@
17
17
  * dialect. It is `bun:test`-only, which suits a Bun-first framework.
18
18
  */
19
19
 
20
- import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
20
+ import {
21
+ afterAll,
22
+ beforeAll,
23
+ beforeEach,
24
+ describe,
25
+ expect,
26
+ test,
27
+ } from "bun:test";
21
28
  import type { SqlAdapter, WorkerContext } from "./contract.ts";
22
29
 
23
30
  /**