vite-plugin-postgres-import 0.8.1 → 0.10.0

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
@@ -73,25 +73,25 @@ const rowsUpdated = await UpdateQuery({ id: 1, newFoo: "baz" }, { db: tx });
73
73
 
74
74
  The only 4 sqlc annotations that are available are the following:
75
75
 
76
- - `:execresult` - default if neither of the 3 below are provided, returns `QueryResult`.
76
+ - `:execresult` - default if neither of the 3 below are provided, returns `QueryResult`.
77
77
 
78
78
  ex.: `Query<R extends QueryResultRow = { ... }>(params?, config?): Promise<QueryResult<R>>`
79
79
 
80
- - `:one` - returns template argument, or the default-parsed ones from the select/returning clause.
80
+ - `:one` - returns template argument, or the default-parsed ones from the select/returning clause.
81
81
 
82
82
  ex.: `Query<R extends QueryResultRow = { ... }>(params?, config?): Promise<R>`
83
83
 
84
- - `:many` - returns template argument as an array, or the default-parsed ones from the select/returning clause.
84
+ - `:many` - returns template argument as an array, or the default-parsed ones from the select/returning clause.
85
85
 
86
86
  ex.: `Query<R extends QueryResultRow = { ... }>(params?, config?): Promise<R[]>`
87
87
 
88
- - `:execrows` - returns number of affected rows.
88
+ - `:execrows` - returns number of affected rows.
89
89
 
90
90
  ex.: `Query(params?, config?): Promise<number>`
91
91
 
92
92
  4 additional annotations not found in sqlc are available:
93
93
 
94
- - `:prepare` - prepares the statement by passing query's name to query config.
94
+ - `:prepare` - prepares the statement by passing query's name to query config.
95
95
 
96
96
  > [!Warning]
97
97
  >
@@ -131,7 +131,7 @@ The only 4 sqlc annotations that are available are the following:
131
131
  >
132
132
  > At best, you'd get an error in the provided example, due to mismatch in provided values, and at worst, assuming different examples, you'd be getting obscure bugs related to incorrect data.
133
133
 
134
- - `:array` - sets `rowMode` to `'array'`. Modifies to type declarations accordingly:
134
+ - `:array` - sets `rowMode` to `'array'`. Modifies to type declarations accordingly:
135
135
 
136
136
  ex. `:execresult`: `Query<R extends any[] = [ ... ]>(params?, config?): Promise<QueryArrayResult<R>>`
137
137
 
@@ -139,8 +139,8 @@ The only 4 sqlc annotations that are available are the following:
139
139
 
140
140
  ex. `:many`: `Query<R extends any[] = [ ... ]>(params?, config?): Promise<R[]>`
141
141
 
142
- - `:iterable` - returns an `AsyncGenerator`. Once [Async Iterator Helpers](https://github.com/tc39/proposal-async-iterator-helpers)
143
- are in the standard, you can use crazy piping as following:
142
+ - `:iterable` - returns an `AsyncGenerator`. Once [Async Iterator Helpers](https://github.com/tc39/proposal-async-iterator-helpers)
143
+ are in the standard, you can use crazy piping as following:
144
144
 
145
145
  ```js
146
146
  const result = await IterableQuery<{ ... }>({ foo: 'bar' })
@@ -152,7 +152,7 @@ const result = await IterableQuery<{ ... }>({ foo: 'bar' })
152
152
  Well maybe that didn't look too crazy, but if some filtering forces your squeel to become convoluted, and you're fine with moving
153
153
  some of that computation to JS, you can finally do that! Or at least when that proposal is in the language, that is.
154
154
 
155
- - `:cursor` - returns an `Cursor`
155
+ - `:cursor` - returns an `Cursor`
156
156
 
157
157
  ex.: `Query<R extends QueryResultRow = { ... }>(params?, config?): Promise<Cursor<R>>`
158
158
 
@@ -178,11 +178,162 @@ _default:_ `process.cwd()`
178
178
 
179
179
  Where the default runtime comes from:
180
180
 
181
- - `module` - specifier every generated module imports the runtime from. Point it at a module of yours
182
- (typically via a subpath import) that provides the database connection. _default:_ `'#db-runtime'`
183
- - `export` - named export of `module` holding the runtime. _default:_ `'db'`
184
- - `type` - either `'object'` — the export is a `Queryable` (or a promise of one) — or `'function'` — the export
185
- is called on each query invocation and returns a `Queryable` (or a promise of one). _default:_ `'object'`
181
+ - `module` - specifier every generated module imports the runtime from. Point it at a module of yours
182
+ (typically via a subpath import) that provides the database connection. _default:_ `'#db-runtime'`
183
+ - `export` - named export of `module` holding the runtime. _default:_ `'db'`
184
+ - `type` - either `'object'` — the export is a `Queryable` (or a promise of one) — or `'function'` — the export
185
+ is called on each query invocation and returns a `Queryable` (or a promise of one). _default:_ `'object'`
186
+
187
+ ### `describe`
188
+
189
+ Types params and result columns from a live database instead of guessing them from the query text.
190
+ Every query is parsed and described the way psql's `\gdesc` does it - nothing gets executed.
191
+
192
+ - `true` - connect using the standard `PG*` environment variables
193
+ - a connection string or a `pg` client config
194
+
195
+ ```js
196
+ postgres({ describe: process.env.DATABASE_URL ?? false });
197
+ ```
198
+
199
+ ```sql
200
+ -- name: GetUser :one
201
+ select id, name, bio, mood
202
+ from users
203
+ where id = :id!;
204
+ ```
205
+
206
+ ```ts
207
+ function GetUser<
208
+ R1 extends QueryResultRow = {
209
+ id: string;
210
+ name: string;
211
+ bio: string | null;
212
+ mood: "sad" | "ok" | "happy";
213
+ },
214
+ >(params: { id: number | bigint | string }, config?): Promise<R1>;
215
+ ```
216
+
217
+ - column types follow `pg`'s default type parsers (`int8` and `numeric` are strings, `timestamptz` is a `Date`, etc.),
218
+ enums become unions of their labels, `json` and `jsonb` are `unknown`
219
+ - columns are non-null only when they come straight from a `not null` table column and the query has no outer joins
220
+ nor `rollup`, `cube` or `grouping sets`, unless [hinted](#column-nullability)
221
+ - params of multi-statement queries are always required `string`s, as they're embedded into sql string
222
+ - queries that fail to describe are reported as warnings and fall back to the naive types
223
+ - connecting times out after 5 seconds unless `connectionTimeoutMillis` is set, after which describing is skipped
224
+ for 10 seconds
225
+
226
+ Only the generated `.d.ts` files depend on it, the generated JS stays the same. Hence the database is only ever
227
+ connected to by the dev server, `vite build` and vitest don't connect, nor do they touch the `.d.ts` files
228
+ describing has generated.
229
+
230
+ _default:_ `false`
231
+
232
+ ### `typesOverrides`
233
+
234
+ TypeScript types to generate for postgres types when `describe` is enabled, e.g. when you've changed `pg`'s parsers
235
+ via `types.setTypeParser`. Keyed by type name, optionally schema-qualified. A string applies to both params and columns,
236
+ an object sets them separately:
237
+
238
+ ```js
239
+ postgres({
240
+ describe: true,
241
+ typesOverrides: {
242
+ int8: "bigint",
243
+ "int8[]": "bigint[]",
244
+ jsonb: "import('#types').Json",
245
+ "public.email": { input: "string", output: "import('#types').Email" },
246
+ },
247
+ });
248
+ ```
249
+
250
+ - builtins, enums, composites and domains can be overridden
251
+ - `pg` parses arrays separately from their elements, so array columns need their own `name[]` entry,
252
+ array params fall back to the element's override
253
+ - domain columns pick up their override only when selected straight from a table, otherwise the base type's applies
254
+ - types are inserted verbatim into the generated `.d.ts`, so don't use relative paths in `import()`
255
+
256
+ _default:_ `{}`
257
+
258
+ ## Params
259
+
260
+ Params are written as `:name`. Since nullability of a param can't be inferred, a described param of type `T`
261
+ is generated as an optional `name?: T | null`. Append a `!` to have it generated as a required `name: T`.
262
+ Params that aren't described are always required, as `unknown`, or `{}` with a `!`:
263
+
264
+ ```sql
265
+ -- name: UpdateBio :execrows
266
+ update users
267
+ set bio = :bio
268
+ where id = :id!;
269
+ ```
270
+
271
+ ```ts
272
+ function UpdateBio(params: { bio?: string | null; id: number | bigint | string }, config?): Promise<number>;
273
+ ```
274
+
275
+ ## Slots
276
+
277
+ `@` symbol turns parameter into a slot, which is injected into the sql string directly. Slots may reference
278
+ params with the same `:name` syntax, these have to be declared in braces after the slot:
279
+
280
+ ```sql
281
+ -- name: ListUsers :many
282
+ select *
283
+ from users
284
+ where org = :org! and @filter{status?, since?}
285
+ order by @orderBy;
286
+ ```
287
+
288
+ ```js
289
+ await ListUsers({
290
+ org,
291
+ filter: [status && "status = :status", since && "created_at > :since"].filter(Boolean).join(" and ") || "true",
292
+ orderBy: desc ? "id desc" : "id",
293
+ status,
294
+ since,
295
+ });
296
+ ```
297
+
298
+ ```ts
299
+ function ListUsers<R1 extends QueryResultRow = { [column: string]: unknown }>(
300
+ params: { org: {}; filter: string; orderBy: string; status?: unknown; since?: unknown },
301
+ config?,
302
+ ): Promise<R1[]>;
303
+ ```
304
+
305
+ - slot params are bound as positional params, numbered after the query's own ones and only when referenced.
306
+ params outside the slot's can be referenced by the slot string without explicit enumeration
307
+ - undeclared `:names` are left as is, you must declare all slots' possible params,
308
+ not all of them must be present in the slot string
309
+ - slots are inserted verbatim, never pass user input into them
310
+ - declared params are typed like undescribed params: required `unknown`, `{}` with a `!`,
311
+ and `?` makes them optional. they're not validated at runtime
312
+ - queries with slots can't be `:prepare`d, nor described
313
+
314
+ > [!Warning]
315
+ >
316
+ > Postgres has a prefix `@` operator for absolute values, write it as `@ x` or `abs(x)` instead.
317
+
318
+ ## Column nullability
319
+
320
+ When `describe` can't tell whether a column is nullable, e.g. for `count(*)` or columns behind an outer join you know
321
+ always matches, suffix its alias with `!` to make it non-null, or with `?` to make it nullable.
322
+ The suffix is stripped from the alias and all of its references in the query that gets sent, so rows have plain
323
+ `total` and `bio` keys:
324
+
325
+ ```sql
326
+ -- name: Stats :one
327
+ select count(*) as "total!", u.bio as "bio?"
328
+ from users u
329
+ group by u.bio;
330
+ ```
331
+
332
+ ```ts
333
+ function Stats<R1 extends QueryResultRow = { total: string; bio: string | null }>(params?, config?): Promise<R1>;
334
+ ```
335
+
336
+ Only quoted `as "alias!"` aliases are recognized.
186
337
 
187
338
  ## Import aliases
188
339
 
@@ -204,8 +355,7 @@ Exact and conditional (`{ "node": ..., "default": ... }`) targets are supported
204
355
 
205
356
  With the `'function'` runtime type, the runtime is re-evaluated on every query call — which means it can
206
357
  consult [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) and pick up
207
- an _ambient_ transaction: queries anywhere down the call stack automatically run on the transaction's client,
208
- no threading of `{ db }` through your functions. Combined with
358
+ an _ambient_ transaction which queries are going to run on down the call stack. Combined with
209
359
  [explicit resource management](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/await_using)
210
360
  you get commit-explicitly, rollback-on-dispose semantics without any callback wrapping.
211
361
 
@@ -286,16 +436,14 @@ await InsertAudit({ id: 1 }); // same transaction, however deep the call stack
286
436
  await tx.commit(); // anything thrown before this point rolls back on scope exit
287
437
  ```
288
438
 
289
- ## Jump to source
439
+ ## Go to Defintion
290
440
 
291
- Generated `.d.ts` files ship with declaration maps pointing back at the original `.sql` file,
292
- so "Go to Definition" / "Go to Source Definition" on an imported function (or the import path itself) lands you
293
- on the query source itself. The vite transform also emits a sourcemap, so runtime stack traces
294
- and debugger stepping map back to the `.sql` source.
441
+ Generated `.d.ts` files contain source maps that point to query start in `.sql` files. Triggering
442
+ "Go to Definition" on a query function takes you straight to the source `.sql` file.
295
443
 
296
444
  ## What this plugin does NOT do
297
445
 
298
- This plugin does not connect to the database or scan a schema folder, instead naively
446
+ Unless `describe` is enabled, this plugin does not connect to the database or scan a schema folder, instead naively
299
447
  parsing select or returning clauses to figure out potential response types.
300
448
 
301
449
  ## License
package/describe.js ADDED
@@ -0,0 +1,353 @@
1
+ import { bindParams, stripHints } from "./parse.js";
2
+
3
+ /**
4
+ * @import { Client, ClientConfig, FieldDef } from "pg"
5
+ * @import { parseModule } from "./parse.js"
6
+ */
7
+
8
+ /** @typedef {ReturnType<typeof parseModule> extends Generator<infer T> ? T : never} Module */
9
+ /** @typedef {{ params: number[], fields: FieldDef[] }} Description */
10
+
11
+ // mirrors pg-types' default text parsers, oids absent here come back as strings
12
+ /** @type {Record<number, string>} */
13
+ const outputTypes = {
14
+ 16: "boolean",
15
+ 17: "Buffer",
16
+ 21: "number",
17
+ 23: "number",
18
+ 26: "number",
19
+ 114: "unknown",
20
+ 600: "{ x: number; y: number }",
21
+ 700: "number",
22
+ 701: "number",
23
+ 718: "{ x: number; y: number; radius: number }",
24
+ 1082: "Date",
25
+ 1114: "Date",
26
+ 1184: "Date",
27
+ 1186: "Interval",
28
+ 3802: "unknown",
29
+ };
30
+
31
+ /** @type {Record<number, string>} */
32
+ const inputTypes = {
33
+ 16: "boolean",
34
+ 17: "Buffer",
35
+ 20: "number | bigint | string",
36
+ 21: "number",
37
+ 23: "number",
38
+ 26: "number",
39
+ 114: "unknown",
40
+ 700: "number",
41
+ 701: "number",
42
+ 1082: "Date | string",
43
+ 1114: "Date | string",
44
+ 1184: "Date | string",
45
+ 1186: "Interval | string",
46
+ 1700: "number | string",
47
+ 3802: "unknown",
48
+ };
49
+
50
+ const stringTypes = new Set([18, 19, 20, 25, 142, 650, 790, 829, 869, 1042, 1043, 1083, 1266, 1560, 1562, 1700, 2950]);
51
+
52
+ // array oid -> element oid, only for arrays pg-types parses, the rest come back as raw strings
53
+ /** @type {Record<number, number>} */
54
+ const arrays = {
55
+ 199: 114,
56
+ 651: 650,
57
+ 791: 790,
58
+ 1000: 16,
59
+ 1001: 17,
60
+ 1005: 21,
61
+ 1007: 23,
62
+ 1008: 24,
63
+ 1009: 25,
64
+ 1014: 1042,
65
+ 1015: 1043,
66
+ 1016: 20,
67
+ 1017: 600,
68
+ 1021: 700,
69
+ 1022: 701,
70
+ 1028: 26,
71
+ 1040: 829,
72
+ 1041: 869,
73
+ 1115: 1114,
74
+ 1182: 1082,
75
+ 1183: 1083,
76
+ 1185: 1184,
77
+ 1187: 1186,
78
+ 1231: 1700,
79
+ 1270: 1266,
80
+ 2951: 2950,
81
+ 3807: 3802,
82
+ 3907: 3906,
83
+ };
84
+
85
+ const catalogQuery = `select
86
+ (select coalesce(json_agg(json_build_array(
87
+ t.oid::int8,
88
+ case when t.typcategory = 'A' then t.typelem::int8 else 0 end,
89
+ case when t.typtype = 'd' then t.typbasetype::int8 else 0 end,
90
+ n.nspname,
91
+ t.typname,
92
+ (select json_agg(e.enumlabel order by e.enumsortorder) from pg_enum e where e.enumtypid = t.oid)
93
+ )), '[]')
94
+ from pg_type t
95
+ join pg_namespace n on n.oid = t.typnamespace
96
+ where t.oid = any($1::oid[])
97
+ or t.oid in (select case when typcategory = 'A' then typelem else typbasetype end from pg_type where oid = any($1::oid[]))) as types,
98
+ (select coalesce(json_agg(json_build_array(
99
+ a.attrelid::int8,
100
+ a.attnum,
101
+ a.attnotnull,
102
+ case when t.typtype = 'd' then json_build_array(n.nspname, t.typname) end
103
+ )), '[]')
104
+ from unnest($2::oid[], $3::int2[]) c(rel, num)
105
+ join pg_attribute a on a.attrelid = c.rel and a.attnum = c.num
106
+ join pg_type t on t.oid = a.atttypid
107
+ join pg_namespace n on n.oid = t.typnamespace) as columns`;
108
+
109
+ // both null out columns of otherwise not null table columns
110
+ const nullifying = /\b(left|right|full)\s+(outer\s+)?join\b|\b(rollup|cube|grouping\s+sets)\s*\(/i;
111
+
112
+ /** Parses and describes statements without executing them, the way psql's \gdesc does. */
113
+ class Describe {
114
+ /** @param {string[]} texts */
115
+ constructor(texts) {
116
+ this.texts = texts;
117
+ /** @type {Description[]} */
118
+ this.results = [];
119
+ /** @type {Promise<{ results: Description[], error?: Error }>} */
120
+ this.promise = new Promise((resolve) => (this.resolve = resolve));
121
+ /** @type {import("events").EventEmitter | undefined} */
122
+ this.connection = undefined;
123
+ this.onParams = (/** @type {{ dataTypeIDs: number[] }} */ msg) =>
124
+ // pg-protocol reads these as signed int32, unlike row description oids
125
+ this.results.push({ params: msg.dataTypeIDs.map((oid) => oid >>> 0), fields: [] });
126
+ }
127
+
128
+ /** @param {any} connection */
129
+ submit(connection) {
130
+ this.connection = connection;
131
+ connection.on("parameterDescription", this.onParams);
132
+ for (const text of this.texts) {
133
+ connection.parse({ text });
134
+ connection.describe({ type: "S" });
135
+ }
136
+ connection.sync();
137
+ }
138
+
139
+ /** @param {{ fields: FieldDef[] }} msg */
140
+ handleRowDescription(msg) {
141
+ this.results[this.results.length - 1].fields = msg.fields;
142
+ }
143
+
144
+ handleReadyForQuery() {
145
+ this.done();
146
+ }
147
+
148
+ /** @param {Error} error */
149
+ handleError(error) {
150
+ this.done(error);
151
+ }
152
+
153
+ /** @param {Error} [error] */
154
+ done(error) {
155
+ this.connection?.off("parameterDescription", this.onParams);
156
+ this.resolve?.({ results: this.results, error });
157
+ }
158
+ }
159
+
160
+ /**
161
+ * @param {true | string | ClientConfig} config
162
+ * @param {Record<string, string | { input?: string, output?: string }>} [typesOverrides]
163
+ */
164
+ export function describer(config, typesOverrides = {}) {
165
+ const overrides = new Map(
166
+ Object.entries(typesOverrides).map(([k, v]) => [k, typeof v === "string" ? { input: v, output: v } : v]),
167
+ );
168
+
169
+ /** @type {Promise<{ client: Client, DatabaseError: Function }> | undefined} */
170
+ let connection;
171
+ /** @type {Promise<unknown>} */
172
+ let tail = Promise.resolve();
173
+
174
+ /**
175
+ * pg no longer allows queueing queries on a client, so concurrent transforms take turns.
176
+ * @template T
177
+ * @param {() => Promise<T>} fn
178
+ */
179
+ function exclusive(fn) {
180
+ const run = tail.then(fn);
181
+ tail = run.catch(() => {});
182
+ return run;
183
+ }
184
+
185
+ /** @type {WeakSet<object>} */
186
+ const reported = new WeakSet();
187
+
188
+ function connect() {
189
+ if (connection) return connection;
190
+ const pending = (connection = import("pg").then(async ({ default: pg }) => {
191
+ const client = new pg.Client({
192
+ connectionTimeoutMillis: 5000,
193
+ ...(config === true ? {} : typeof config === "string" ? { connectionString: config } : config),
194
+ });
195
+ client.on("error", (err) => {
196
+ console.warn(`[postgres] connection error: ${err.message}`);
197
+ if (connection === pending) connection = undefined;
198
+ });
199
+ await client.connect();
200
+ return { client, DatabaseError: pg.DatabaseError };
201
+ }));
202
+ // fail fast for a while, instead of every file waiting out the timeout again
203
+ pending.catch(() =>
204
+ setTimeout(() => {
205
+ if (connection === pending) connection = undefined;
206
+ }, 10_000).unref(),
207
+ );
208
+ return pending;
209
+ }
210
+
211
+ /**
212
+ * Pipelines every statement in a single round trip, re-sending the ones following a failed statement.
213
+ * @param {string[]} texts
214
+ * @returns {Promise<(Description | { error: Error })[]>}
215
+ */
216
+ async function describe(texts) {
217
+ const { client, DatabaseError } = await connect();
218
+ /** @type {(Description | { error: Error })[]} */
219
+ const out = [];
220
+ while (out.length < texts.length) {
221
+ const query = new Describe(texts.slice(out.length));
222
+ client.query(/** @type {any} */ (query));
223
+ const { results, error } = await query.promise;
224
+ out.push(...results);
225
+ if (!error) break;
226
+ if (!(error instanceof DatabaseError)) throw error;
227
+ out.push({ error });
228
+ }
229
+ return out;
230
+ }
231
+
232
+ return {
233
+ /**
234
+ * Sets `columns` and `paramTypes` on each statement from what the database reports.
235
+ * @param {(Module | Module[])[]} modules
236
+ * @param {string} filename
237
+ */
238
+ async annotate(modules, filename) {
239
+ // slots' sql is only known at runtime
240
+ const statements = modules.flat().filter((s) => !s.slots.size);
241
+ if (!statements.length) return;
242
+ const texts = statements.map((s) => bindParams(stripHints(s.query), s.params));
243
+
244
+ /** @type {Map<number, { elem: number, base: number, name: [schema: string, name: string], labels: string[] | null }>} */
245
+ const catalog = new Map();
246
+ /** @type {Map<string, { notnull: boolean, domain: [schema: string, name: string] | null }>} */
247
+ const columns = new Map();
248
+ /** @type {Awaited<ReturnType<typeof describe>>} */
249
+ let described = [];
250
+ try {
251
+ await exclusive(async () => {
252
+ described = await describe(texts);
253
+
254
+ /** @type {Set<number>} */
255
+ const lookup = new Set();
256
+ const rels = [];
257
+ const nums = [];
258
+ for (const d of described) {
259
+ if (!("params" in d)) continue;
260
+ for (const oid of [...d.params, ...d.fields.map((f) => f.dataTypeID)]) {
261
+ if (overrides.size || !(oid in outputTypes || oid in inputTypes || oid in arrays || stringTypes.has(oid))) {
262
+ lookup.add(oid);
263
+ }
264
+ }
265
+ for (const f of d.fields) {
266
+ if (f.tableID) {
267
+ rels.push(f.tableID);
268
+ nums.push(f.columnID);
269
+ }
270
+ }
271
+ }
272
+ if (lookup.size || rels.length) {
273
+ const { client } = await connect();
274
+ const { rows } = await client.query(catalogQuery, [[...lookup], rels, nums]);
275
+ for (const [oid, elem, base, schema, name, labels] of rows[0].types) {
276
+ catalog.set(oid, { elem, base, name: [schema, name], labels });
277
+ }
278
+ for (const [rel, num, notnull, domain] of rows[0].columns) columns.set(`${rel}.${num}`, { notnull, domain });
279
+ }
280
+ });
281
+ } catch (err) {
282
+ if (!reported.has(/** @type {Error} */ (err))) {
283
+ reported.add(/** @type {Error} */ (err));
284
+ console.warn(`[postgres] could not describe ${filename}: ${/** @type {Error} */ (err).message}`);
285
+ }
286
+ return;
287
+ }
288
+
289
+ const labels = (/** @type {number} */ oid) => catalog.get(oid)?.labels?.map((l) => JSON.stringify(l)).join(" | ");
290
+
291
+ /** @returns {[schema: string, name: string] | undefined} */
292
+ const typeName = (/** @type {number} */ oid) => {
293
+ const t = catalog.get(oid);
294
+ if (!t?.elem) return t?.name;
295
+ const elem = catalog.get(t.elem)?.name;
296
+ return elem && [elem[0], `${elem[1]}[]`];
297
+ };
298
+
299
+ const override = (/** @type {[string, string] | null | undefined} */ type, /** @type {"input" | "output"} */ side) =>
300
+ type && (overrides.get(`${type[0]}.${type[1]}`) ?? overrides.get(type[1]))?.[side];
301
+
302
+ // pg parses arrays separately from their elements, so element overrides don't apply to them
303
+ /** @returns {string} */
304
+ const baseOutput = (/** @type {number} */ oid) =>
305
+ outputTypes[oid] ??
306
+ (oid in arrays ? `${wrap(oid === 1231 ? "number" : baseOutput(arrays[oid]))}[]` : labels(oid) ?? "string");
307
+
308
+ const output = (/** @type {number} */ oid) => override(typeName(oid), "output") ?? baseOutput(oid);
309
+
310
+ /** @returns {string} */
311
+ const input = (/** @type {number} */ oid) => {
312
+ const type = override(typeName(oid), "input") ?? inputTypes[oid];
313
+ if (type) return type;
314
+ const t = catalog.get(oid);
315
+ const elem = arrays[oid] ?? t?.elem;
316
+ if (elem) return `${wrap(input(elem))}[]`;
317
+ if (t?.base) return input(t.base);
318
+ return labels(oid) ?? (oid ? "string" : "unknown");
319
+ };
320
+
321
+ for (let i = 0; i < statements.length; ++i) {
322
+ const s = statements[i];
323
+ const d = described[i];
324
+ if ("error" in d) {
325
+ console.warn(`[postgres] ${filename}: ${s.name}: ${d.error.message}`);
326
+ continue;
327
+ }
328
+ const nullified = nullifying.test(s.query);
329
+ s.columns = d.fields.map((f) => {
330
+ const column = columns.get(`${f.tableID}.${f.columnID}`);
331
+ const type = override(column?.domain, "output") ?? output(f.dataTypeID);
332
+ const hint = s.hints.get(f.name);
333
+ const nullable = hint ? hint === "?" : nullified || !column?.notnull;
334
+ return [
335
+ /^[A-Za-z_$][\w$]*$/.test(f.name) ? f.name : JSON.stringify(f.name),
336
+ type === "unknown" || !nullable ? type : `${type} | null`,
337
+ ];
338
+ });
339
+ s.paramTypes = new Map(s.params.values().map((p, j) => [p, input(d.params[j])]));
340
+ }
341
+ },
342
+
343
+ end() {
344
+ const pending = connection;
345
+ connection = undefined;
346
+ pending?.then(({ client }) => client.end()).catch(() => {});
347
+ },
348
+ };
349
+ }
350
+
351
+ function wrap(/** @type {string} */ type) {
352
+ return type.includes("|") ? `(${type})` : type;
353
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "vite-plugin-postgres-import",
3
3
  "description": "Vite plugin for importing SQL files as JS modules with sqlc-style annotations",
4
- "version": "0.8.1",
4
+ "version": "0.10.0",
5
5
  "main": "plugin.js",
6
6
  "types": "plugin.d.ts",
7
7
  "type": "module",
@@ -12,7 +12,9 @@
12
12
  "license": "MIT",
13
13
  "repository": "github:sirkostya009/vite-plugin-postgres-import",
14
14
  "files": [
15
+ "describe.js",
15
16
  "parse.js",
17
+ "runtime.js",
16
18
  "plugin.d.ts",
17
19
  "plugin.d.ts.map"
18
20
  ],
@@ -44,4 +46,4 @@
44
46
  "engines": {
45
47
  "node": ">=22.0.0"
46
48
  }
47
- }
49
+ }
package/parse.js CHANGED
@@ -1,4 +1,32 @@
1
1
  const annotationRegex = /--\s*name:\s*(?<name>[a-zA-Z][\w_]*)\s*(?<tags>(:\w+\s*)*)?\r?\n/g;
2
+ const paramRegex = /(?<![\w\\:]):(\w+)(!(?![=~]))?/g;
3
+ const slotRegex = /(?<![\w\\@<])@(\w+)(?:\{([\w\s,!?]*)\})?/g;
4
+ const markerRank = { "?": 0, "": 1, "!": 2 };
5
+
6
+ /** Sets a slot param's `!`/`?` marker, the stricter of conflicting ones wins. */
7
+ function mergeMarker(/** @type {Map<string, string>} */ map, /** @type {string} */ param, /** @type {string} */ marker) {
8
+ const prev = map.get(param);
9
+ if (prev === undefined || markerRank[marker] > markerRank[prev]) map.set(param, marker);
10
+ }
11
+ const hintRegex = /\bas\s+"([^"]+?)([!?])"/gi;
12
+
13
+ /** Strips `!` and `?` nullability hints off of `as "alias!"` column aliases and all references to them. */
14
+ export function stripHints(/** @type {string} */ query) {
15
+ const hinted = new Set(query.matchAll(hintRegex).map((m) => `"${m[1]}${m[2]}"`));
16
+ return hinted.size ? query.replaceAll(/"[^"]+"/g, (q) => (hinted.has(q) ? `${q.slice(0, -2)}"` : q)) : query;
17
+ }
18
+
19
+ /**
20
+ * Replaces `:param` (and `:param!`) placeholders, `$1`, `$2`, ... by default.
21
+ * @param {string} query
22
+ * @param {Iterable<string>} params
23
+ */
24
+ export function bindParams(query, params, replace = (/** @type {string} */ _, /** @type {number} */ i) => `$${i + 1}`) {
25
+ const index = new Map([...params].map((p, i) => [p, i]));
26
+ return query.replaceAll(paramRegex, (m, /** @type {string} */ param) =>
27
+ index.has(param) ? replace(param, /** @type {number} */ (index.get(param))) : m,
28
+ );
29
+ }
2
30
 
3
31
  export function* parseModule(/** @type {string} */ sql) {
4
32
  annotationRegex.lastIndex = 0;
@@ -102,6 +130,17 @@ function metadata(/** @type {string} */ s, /** @type {ReturnType<typeof metadata
102
130
  const match = firstMeta ? /--\s*(?<tags>(:\w+\s*)*)\r?\n/.exec(s) : annotationRegex.exec(s);
103
131
  const meta = match?.groups;
104
132
  const query = s.substring(match?.[0]?.length ?? 0).trim();
133
+ const stripped = stripHints(query);
134
+ const params = query.matchAll(paramRegex).toArray();
135
+ /** @type {Map<string, Map<string, string>>} */
136
+ const slots = new Map();
137
+ for (const [, slot, declared] of query.matchAll(slotRegex)) {
138
+ const declarations = slots.get(slot) ?? slots.set(slot, new Map()).get(slot);
139
+ for (const d of declared?.matchAll(/(\w+)([!?]?)/g) ?? []) mergeMarker(declarations, d[1], d[2]);
140
+ }
141
+ for (const [, p] of params) {
142
+ if (slots.has(p)) throw new Error(`${meta?.name ?? firstMeta?.name}: @${p} slot shares its name with a param`);
143
+ }
105
144
 
106
145
  return {
107
146
  name: firstMeta?.name || meta?.name,
@@ -110,17 +149,26 @@ function metadata(/** @type {string} */ s, /** @type {ReturnType<typeof metadata
110
149
  mode: /:cursor|:iterable/.exec(meta?.tags)?.[0],
111
150
  rowArray: meta?.tags?.includes(":array"),
112
151
  query,
113
- params: new Set(query.matchAll(/(?<![\w_\\:]):[\w_]+/g).map((m) => m?.[0]?.substring(1))),
114
- selectFields: selectList(/(with.*\))?\s*select\s+(?<select>.*)/ims.exec(query)?.groups?.select)
152
+ params: new Set(params.map((m) => m[1])),
153
+ required: new Set(params.filter((m) => m[2]).map((m) => m[1])),
154
+ slots,
155
+ /** @type {[key: string, type: string][] | undefined} */
156
+ columns: undefined,
157
+ /** @type {Map<string, string> | undefined} */
158
+ paramTypes: undefined,
159
+ hints: new Map(query.matchAll(hintRegex).map((m) => [m[1], m[2]])),
160
+ selectFields: selectList(/(with.*\))?\s*select\s+(?<select>.*)/ims.exec(stripped)?.groups?.select)
115
161
  .map(parseResultSymbol)
116
162
  .toArray(),
117
- returningClause: selectList(/returning\s+(?<returning>[\w\s\.\",\*]+);?$/im.exec(query)?.groups?.returning)
163
+ returningClause: selectList(/returning\s+(?<returning>[\w\s\.\",\*]+);?$/im.exec(stripped)?.groups?.returning)
118
164
  .map(parseResultSymbol)
119
165
  .toArray(),
120
166
  };
121
167
 
122
168
  function parseResultSymbol(/** @type {string} */ s) {
123
169
  s = s.trim();
170
+ slotRegex.lastIndex = 0;
171
+ if (slotRegex.test(s)) return "[column: string]";
124
172
  while (s.startsWith("(") && s.endsWith(")")) {
125
173
  // unwrap
126
174
  s = s.substring(1, s.length - 1).trim();
@@ -172,8 +220,10 @@ export function codegen(
172
220
  ) {
173
221
  let dts = [
174
222
  // `declare module '${modulePrefix}${filename}.sql' {`
175
- `import type { QueryResultRow, QueryResult, QueryArrayResult } from 'pg';\nimport { Queryable } from 'vite-plugin-postgres-import';`,
223
+ `import type { QueryResultRow, QueryResult, QueryArrayResult } from 'pg';\nimport type { Queryable, Interval } from 'vite-plugin-postgres-import';`,
176
224
  ];
225
+ const returnSymbols = (/** @type {ReturnType<typeof metadata>} */ m) =>
226
+ m.columns ?? (m.returningClause?.length ? m.returningClause : m.selectFields).map((s) => [s, "unknown"]);
177
227
  let js = [
178
228
  `import { escapeLiteral } from 'pg';\nimport { ${runtime.export} as __runtime } from '${runtime.module}';`,
179
229
  ];
@@ -186,19 +236,31 @@ export function codegen(
186
236
  ...module[0],
187
237
  query: module.flatMap((m) => m.query).join(";\n\n"),
188
238
  params: new Set(module.flatMap((m) => [...m.params])),
239
+ required: new Set(module.flatMap((m) => [...m.required])),
240
+ slots: module.reduce((acc, m) => {
241
+ for (const [slot, declarations] of m.slots) {
242
+ const merged = acc.get(slot) ?? acc.set(slot, new Map()).get(slot);
243
+ for (const [p, marker] of declarations) mergeMarker(merged, p, marker);
244
+ }
245
+ return acc;
246
+ }, new Map()),
247
+ // values are inlined with escapeLiteral, which only accepts strings
248
+ paramTypes: module.some((m) => m.paramTypes)
249
+ ? new Map(module.flatMap((m) => [...m.params]).map((p) => [p, "string"]))
250
+ : undefined,
189
251
  execution: module.map((m) => m.execution),
190
- returnSymbols: module.map((m) => (m.returningClause?.length ? m.returningClause : m.selectFields)),
252
+ returnSymbols: module.map(returnSymbols),
191
253
  multiStatement: true,
192
254
  }
193
255
  : {
194
256
  ...module,
195
257
  execution: [module.execution],
196
- returnSymbols: [module.returningClause?.length ? module.returningClause : module.selectFields],
258
+ returnSymbols: [returnSymbols(module)],
197
259
  multiStatement: "",
198
260
  };
199
261
 
200
262
  if (!module.rowArray) {
201
- module.returnSymbols = module.returnSymbols.map((rs) => [...new Set(rs)]);
263
+ module.returnSymbols = module.returnSymbols.map((rs) => [...new Map(rs)]);
202
264
  }
203
265
 
204
266
  mappings.push({ name: module.name, srcLine: module.srcLine ?? 0, srcCol: module.srcCol ?? 0 });
@@ -208,11 +270,22 @@ export function codegen(
208
270
  js[0] += `\nimport Cursor from 'pg-cursor';`;
209
271
  }
210
272
 
211
- const keys = module.params
212
- .values()
213
- .map((k) => `'${k}'`)
214
- .toArray()
215
- .join(" | ");
273
+ /** @type {Map<string, string>} */
274
+ const slotParams = new Map();
275
+ for (const declarations of module.slots.values()) {
276
+ for (const [p, marker] of declarations) if (!module.params.has(p)) mergeMarker(slotParams, p, marker);
277
+ }
278
+ let optionalParams = !module.slots.size;
279
+ const keys = [
280
+ ...module.params.values().map((p) => {
281
+ const type = module.paramTypes?.get(p) ?? "unknown";
282
+ if (type !== "unknown" && !module.required.has(p) && !module.multiStatement) return `${p}?: ${type} | null`;
283
+ optionalParams = false;
284
+ return `${p}: ${type === "unknown" && module.required.has(p) ? "{}" : type}`;
285
+ }),
286
+ ...module.slots.keys().map((s) => `${s}: string`),
287
+ ...slotParams.entries().map(([p, marker]) => `${p}${marker === "?" ? "?: unknown" : marker ? ": {}" : ": unknown"}`),
288
+ ].join("; ");
216
289
 
217
290
  dts.push(`/**
218
291
  * ${"```"}sql
@@ -223,16 +296,16 @@ export function ${module.name}<${module.returnSymbols
223
296
  .map((r, i) =>
224
297
  module.rowArray
225
298
  ? `R${i + 1} extends any[] = ${
226
- r.find((k) => k.startsWith("[column: string]"))
299
+ r.find(([k]) => k.startsWith("[column: string]"))
227
300
  ? `unknown[]`
228
- : `[ ${r?.map(() => `unknown`)?.join(", ") ?? ""} ]`
301
+ : `[ ${r.map(([, t]) => t).join(", ")} ]`
229
302
  }`
230
- : `R${i + 1} extends QueryResultRow = {${r.length > 3 ? "\n\t" : " "}${
231
- r?.map((r) => `${r}: unknown`)?.join(r.length > 3 ? ";\n\t" : "; ") ?? ""
232
- }${r.length > 3 ? "\n" : " "}}`
303
+ : `R${i + 1} extends QueryResultRow = {${r.length > 3 ? "\n\t" : " "}${r
304
+ .map(([k, t]) => `${k}: ${t}`)
305
+ .join(r.length > 3 ? ";\n\t" : "; ")}${r.length > 3 ? "\n" : " "}}`
233
306
  )
234
307
  .join(", ")}>(
235
- ${keys ? `params: Record<${keys}, unknown>` : `params?: Record<string, never>`},
308
+ ${keys ? `params${optionalParams ? "?" : ""}: { ${keys} }` : `params?: Record<string, never>`},
236
309
  config?: { db?: Queryable${module.mode === ":iterable" ? "; read?: number" : ""} },
237
310
  ): ${
238
311
  module.mode === ":cursor"
@@ -259,16 +332,39 @@ export function ${module.name}<${module.returnSymbols
259
332
  .reduce((curr, p) => [...curr, p], [])
260
333
  .join();
261
334
 
262
- module.query = module.query.replaceAll("`", "\\`");
263
-
264
- module.params.values().forEach(
265
- (param, i) =>
266
- (module.query = module.query.replaceAll(
267
- new RegExp(`(?<![\w_]):${param}(?![\w_])`, "gi"),
268
- module.multiStatement ? `\${escapeLiteral(${param})}` : `$${i + 1}` // the escapists
269
- ))
335
+ const escaped = module.query.replaceAll("\\", "\\\\").replaceAll("`", "\\`").replaceAll("${", "\\${");
336
+ module.query = bindParams(stripHints(escaped), module.params, (param, i) =>
337
+ module.multiStatement ? `\${escapeLiteral(${param})}` : `$${i + 1}` // the escapists
270
338
  );
271
339
 
340
+ const slotted = module.slots.size > 0;
341
+ let args = `{ ${paramsString} } = {}`;
342
+ let values = `[ ${paramsString} ]`;
343
+ let pre = "";
344
+ if (slotted) {
345
+ if (module.prepared) throw new Error(`${module.name}: queries with slots can't be prepared`);
346
+ if (!js[0].includes("__slots")) {
347
+ js[0] += `\nimport { slot as __slot, slots as __slots } from 'vite-plugin-postgres-import/runtime.js';`;
348
+ }
349
+ const state = `__${module.name}`;
350
+ js.push(
351
+ `const ${state} = __slots(${JSON.stringify([...module.params])}, ${JSON.stringify([...slotParams.keys()])}${
352
+ module.multiStatement ? ", escapeLiteral" : ""
353
+ });`,
354
+ );
355
+ module.query = module.query.replaceAll(
356
+ slotRegex,
357
+ (_, slot) => `\${__slot(${slot}, ${module.multiStatement ? "null" : "__v"}, __p, ${state})}`,
358
+ );
359
+ args = "__p = {}";
360
+ values = "__v";
361
+ pre = `const { ${[...module.params, ...module.slots.keys()].join()} } = __p${
362
+ module.multiStatement ? "" : `, __v = [ ${paramsString} ]`
363
+ };`;
364
+ }
365
+ const body = (/** @type {string} */ expr) => (slotted ? `{\n\t${pre}\n\treturn ${expr};\n}` : expr);
366
+ const valuesArg = slotted ? (module.multiStatement ? "" : ", __v") : paramsString && `, ${values}`;
367
+
272
368
  if (module.prepared && module.execution.size > 1) {
273
369
  console.warn(
274
370
  "Postgres does not support preparing multi-statement queries. You will get an error, just sayin'"
@@ -277,12 +373,14 @@ export function ${module.name}<${module.returnSymbols
277
373
 
278
374
  js.push(
279
375
  module.mode === ":cursor"
280
- ? `export const ${module.name} = async ({ ${paramsString} } = {}, { db: __db = ${rt} } = {}) => (await __db).query(new Cursor(\`${
281
- module.query
282
- }\`${paramsString && `, [ ${paramsString} ]`}${module.rowArray ? `, { rowMode: "array" }` : ""}));`
376
+ ? `export const ${module.name} = async (${args}, { db: __db = ${rt} } = {}) => ${body(
377
+ `(await __db).query(new Cursor(\`${module.query}\`${valuesArg}${
378
+ module.rowArray ? `, { rowMode: "array" }` : ""
379
+ }))`,
380
+ )};`
283
381
  : module.mode === ":iterable"
284
- ? `export async function* ${module.name}({ ${paramsString} } = {}, { db: __db = ${rt}, read = 10 } = {}) {
285
- const cursor = (await __db).query(new Cursor(\`${module.query}\`${paramsString && `, [ ${paramsString} ]`}${
382
+ ? `export async function* ${module.name}(${args}, { db: __db = ${rt}, read = 10 } = {}) {${pre && `\n\t${pre}`}
383
+ const cursor = (await __db).query(new Cursor(\`${module.query}\`${valuesArg}${
286
384
  module.rowArray ? `, { rowMode: "array" }` : ""
287
385
  }));
288
386
  try {
@@ -295,10 +393,10 @@ export function ${module.name}<${module.returnSymbols
295
393
  await cursor.close();
296
394
  }
297
395
  }`
298
- : `export const ${module.name} = async ({ ${paramsString} } = {}, { db: __db = ${rt} } = {}) => (await __db).query({
396
+ : `export const ${module.name} = async (${args}, { db: __db = ${rt} } = {}) => ${body(`(await __db).query({
299
397
  ${module.prepared ? `name: "${module.name}",` : ""}
300
398
  text: \`${module.query}\`,
301
- ${module.multiStatement ? "" : `values: [ ${paramsString} ],`}
399
+ ${module.multiStatement ? "" : `values: ${values},`}
302
400
  ${module.rowArray ? `rowMode: "array",` : ""}
303
401
  }).then((${module.multiStatement && "["}${module.returnSymbols.map((_, i) => `r${i + 1}`).join()}${
304
402
  module.multiStatement && "]"
@@ -314,7 +412,7 @@ export function ${module.name}<${module.returnSymbols
314
412
  ? `.rowCount`
315
413
  : "")
316
414
  )
317
- .join()}${module.multiStatement && "]"});`
415
+ .join()}${module.multiStatement && "]"})`)};`
318
416
  );
319
417
  }
320
418
 
package/plugin.d.ts CHANGED
@@ -1,5 +1,17 @@
1
- import type { QueryArrayConfig, QueryArrayResult, QueryConfig, QueryConfigValues, QueryResult, QueryResultRow, Submittable } from "pg";
1
+ import type { ClientConfig, QueryArrayConfig, QueryArrayResult, QueryConfig, QueryConfigValues, QueryResult, QueryResultRow, Submittable } from "pg";
2
2
  import type { Plugin } from "vite";
3
+ export type Interval = {
4
+ years?: number;
5
+ months?: number;
6
+ days?: number;
7
+ hours?: number;
8
+ minutes?: number;
9
+ seconds?: number;
10
+ milliseconds?: number;
11
+ toPostgres(): string;
12
+ toISO(): string;
13
+ toISOString(): string;
14
+ };
3
15
  export type QueryableObject = {
4
16
  query<T extends Submittable>(queryStream: T): T;
5
17
  query<R extends any[] = any[], I = any[]>(queryConfig: QueryArrayConfig<I>, values?: QueryConfigValues<I>): Promise<QueryArrayResult<R>>;
@@ -20,6 +32,17 @@ export type PostgresOptions = {
20
32
  * Where the default runtime comes from.
21
33
  */
22
34
  runtime?: RuntimeOptions;
35
+ /**
36
+ * Type params and result columns by describing every query against a live database, only ever done by the dev server. `true` connects using the `PG*` environment variables, a connection string or `pg` client config may be given instead. Defaults to `false`.
37
+ */
38
+ describe?: boolean | string | ClientConfig;
39
+ /**
40
+ * TypeScript types to use for postgres types when `describe` is enabled, keyed by type name (`int8`, `public.mood`, `int8[]`). A string applies to both params (`input`) and columns (`output`).
41
+ */
42
+ typesOverrides?: Record<string, string | {
43
+ input?: string;
44
+ output?: string;
45
+ }>;
23
46
  };
24
47
  export type RuntimeOptions = {
25
48
  /**
@@ -36,9 +59,24 @@ export type RuntimeOptions = {
36
59
  type?: "object" | "function";
37
60
  };
38
61
  /**
39
- * @import { QueryArrayConfig, QueryArrayResult, QueryConfig, QueryConfigValues, QueryResult, QueryResultRow, Submittable } from "pg"
62
+ * @import { ClientConfig, QueryArrayConfig, QueryArrayResult, QueryConfig, QueryConfigValues, QueryResult, QueryResultRow, Submittable } from "pg"
40
63
  * @import { Plugin, TransformResult } from "vite"
41
64
  */
65
+ /**
66
+ * Value pg parses `interval` columns into.
67
+ * @typedef {{
68
+ * years?: number;
69
+ * months?: number;
70
+ * days?: number;
71
+ * hours?: number;
72
+ * minutes?: number;
73
+ * seconds?: number;
74
+ * milliseconds?: number;
75
+ * toPostgres(): string;
76
+ * toISO(): string;
77
+ * toISOString(): string;
78
+ * }} Interval
79
+ */
42
80
  /**
43
81
  * @typedef {{
44
82
  * query<T extends Submittable>(queryStream: T): T;
@@ -53,6 +91,8 @@ export type RuntimeOptions = {
53
91
  * @property {string} [typesFolder] Path to a folder where all declaration are kept relative to `rootFolder`, i.e. a file at path `src/sql/module.sql` will have its `.d.ts` file generated into `${typesFolder}/src/sql/module.sql.d.ts`. Make sure you include this one in your `tsconfig.json`. Defaults to `"node_modules/@types/vite-plugin-postgres-import/"`.
54
92
  * @property {string} [rootFolder] Root folder relative to which path calculation will be happening. Defaults to `process.cwd()`.
55
93
  * @property {RuntimeOptions} [runtime] Where the default runtime comes from.
94
+ * @property {boolean | string | ClientConfig} [describe] Type params and result columns by describing every query against a live database, only ever done by the dev server. `true` connects using the `PG*` environment variables, a connection string or `pg` client config may be given instead. Defaults to `false`.
95
+ * @property {Record<string, string | { input?: string, output?: string }>} [typesOverrides] TypeScript types to use for postgres types when `describe` is enabled, keyed by type name (`int8`, `public.mood`, `int8[]`). A string applies to both params (`input`) and columns (`output`).
56
96
  */
57
97
  /**
58
98
  * @typedef {object} RuntimeOptions
package/plugin.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["plugin.js"],"names":[],"mappings":"AAKG,OAAQ,KAAA,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,IAAI,CAClI;AAAA,OAAQ,KAAA,EAAE,MAAM,EAAmB,MAAM,MAAM,CAAA;AAI/C,YAKG,eAAe,GALR;IACR,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;IAChD,KAAK,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzI,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACrG,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,EAAE,iBAAiB,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;CACtJ,CAAiB;AAGjB,YAAsD,SAAS,GAArD,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAW;AAGhE,YAAkB,eAAe,GACjC;;;;IAAoB,WAAW,AAA/B,CACA,EADW,MAAM,CACjB;;;;IAAoB,UAAU,AAA9B,CACA,EADW,MAAM,CACjB;;;;IAA4B,OAAO,AAAnC,CACF,EADa,cAAc,CAC3B;CAAA,CAAA;AAGE,YAAkB,cAAc,GAChC;;;;IAAoB,MAAM,AAA1B,CACA,EADW,MAAM,CACjB;;;;IAAoB,MAAM,AAA1B,CACA,EADW,MAAM,CACjB;;;;IAAmC,IAAI,AAAvC,CACF,EADa,QAAQ,GAAG,UAAU,CAClC;CAAA,CAAA;AA5BD;;;GAGG;AAEH;;;;;;;GAOG;AAEH,sEAAsE;AAEtE;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;GAGG;AACH,wBAA8B,QAAQ,CAAC,IAAI,AAHxC,CACA,EADQ,eAGqC,GAFnC,OAAO,CAAC,MAAM,CAAC,CAiJ3B"}
1
+ {"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["plugin.js"],"names":[],"mappings":"AAMG,OAAQ,KAAA,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,IAAI,CAChJ;AAAA,OAAQ,KAAA,EAAE,MAAM,EAAmB,MAAM,MAAM,CAAA;AAK/C,YAWG,QAAQ,GAXD;IACR,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,IAAI,MAAM,CAAC;IACrB,KAAK,IAAI,MAAM,CAAC;IAChB,WAAW,IAAI,MAAM,CAAC;CACvB,CAAU;AAIX,YAKG,eAAe,GALR;IACR,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;IAChD,KAAK,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzI,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACrG,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,EAAE,iBAAiB,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;CACtJ,CAAiB;AAGjB,YAAsD,SAAS,GAArD,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAW;AAGhE,YAAkB,eAAe,GACjC;;;;IAAoB,WAAW,AAA/B,CACA,EADW,MAAM,CACjB;;;;IAAoB,UAAU,AAA9B,CACA,EADW,MAAM,CACjB;;;;IAA4B,OAAO,AAAnC,CACA,EADW,cAAc,CACzB;;;;IAA6C,QAAQ,AAArD,CACA,EADW,OAAO,GAAG,MAAM,GAAG,YAAY,CAC1C;;;;IAA0E,cAAc,AAAxF,CACF,EADa,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CACzE;CAAA,CAAA;AAGE,YAAkB,cAAc,GAChC;;;;IAAoB,MAAM,AAA1B,CACA,EADW,MAAM,CACjB;;;;IAAoB,MAAM,AAA1B,CACA,EADW,MAAM,CACjB;;;;IAAmC,IAAI,AAAvC,CACF,EADa,QAAQ,GAAG,UAAU,CAClC;CAAA,CAAA;AA9CD;;;GAGG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AAEH,sEAAsE;AAEtE;;;;;;;GAOG;AAEH;;;;;GAKG;AAEH;;;GAGG;AACH,wBAA8B,QAAQ,CAAC,IAAI,AAHxC,CACA,EADQ,eAGqC,GAFnC,OAAO,CAAC,MAAM,CAAC,CAiK3B"}
package/plugin.js CHANGED
@@ -1,12 +1,29 @@
1
1
  import fs from "node:fs/promises";
2
2
  import path from "node:path";
3
+ import { describer } from "./describe.js";
3
4
  import { codegen, encodeMappings, exportMappings, parseModule } from "./parse.js";
4
5
 
5
6
  /**
6
- * @import { QueryArrayConfig, QueryArrayResult, QueryConfig, QueryConfigValues, QueryResult, QueryResultRow, Submittable } from "pg"
7
+ * @import { ClientConfig, QueryArrayConfig, QueryArrayResult, QueryConfig, QueryConfigValues, QueryResult, QueryResultRow, Submittable } from "pg"
7
8
  * @import { Plugin, TransformResult } from "vite"
8
9
  */
9
10
 
11
+ /**
12
+ * Value pg parses `interval` columns into.
13
+ * @typedef {{
14
+ * years?: number;
15
+ * months?: number;
16
+ * days?: number;
17
+ * hours?: number;
18
+ * minutes?: number;
19
+ * seconds?: number;
20
+ * milliseconds?: number;
21
+ * toPostgres(): string;
22
+ * toISO(): string;
23
+ * toISOString(): string;
24
+ * }} Interval
25
+ */
26
+
10
27
  /**
11
28
  * @typedef {{
12
29
  * query<T extends Submittable>(queryStream: T): T;
@@ -23,6 +40,8 @@ import { codegen, encodeMappings, exportMappings, parseModule } from "./parse.js
23
40
  * @property {string} [typesFolder] Path to a folder where all declaration are kept relative to `rootFolder`, i.e. a file at path `src/sql/module.sql` will have its `.d.ts` file generated into `${typesFolder}/src/sql/module.sql.d.ts`. Make sure you include this one in your `tsconfig.json`. Defaults to `"node_modules/@types/vite-plugin-postgres-import/"`.
24
41
  * @property {string} [rootFolder] Root folder relative to which path calculation will be happening. Defaults to `process.cwd()`.
25
42
  * @property {RuntimeOptions} [runtime] Where the default runtime comes from.
43
+ * @property {boolean | string | ClientConfig} [describe] Type params and result columns by describing every query against a live database, only ever done by the dev server. `true` connects using the `PG*` environment variables, a connection string or `pg` client config may be given instead. Defaults to `false`.
44
+ * @property {Record<string, string | { input?: string, output?: string }>} [typesOverrides] TypeScript types to use for postgres types when `describe` is enabled, keyed by type name (`int8`, `public.mood`, `int8[]`). A string applies to both params (`input`) and columns (`output`).
26
45
  */
27
46
 
28
47
  /**
@@ -41,8 +60,12 @@ export default async function postgres(opts = {}) {
41
60
  typesFolder = "node_modules/@types/vite-plugin-postgres-import/",
42
61
  rootFolder = process.cwd(),
43
62
  runtime: { module: runtimeModule = "#db-runtime", export: runtimeExport = "db", type: runtimeType = "object" } = {},
63
+ describe = false,
64
+ typesOverrides,
44
65
  } = opts;
45
66
  const runtime = { module: runtimeModule, export: runtimeExport, type: runtimeType };
67
+ const db = describe ? describer(describe, typesOverrides) : undefined;
68
+ let dev = false;
46
69
  const imports = await fs
47
70
  .readFile(path.join(rootFolder, "package.json"), "utf8")
48
71
  .then((s) => JSON.parse(s).imports)
@@ -77,6 +100,9 @@ export default async function postgres(opts = {}) {
77
100
 
78
101
  return {
79
102
  name: "vite-plugin-sql-postgres",
103
+ configResolved(config) {
104
+ dev = config.command === "serve" && config.mode !== "test";
105
+ },
80
106
  transform: {
81
107
  filter: {
82
108
  id: /\.sql$/,
@@ -102,6 +128,9 @@ export default async function postgres(opts = {}) {
102
128
  handleHotUpdate({ modules }) {
103
129
  return modules;
104
130
  },
131
+ buildEnd() {
132
+ db?.end();
133
+ },
105
134
  };
106
135
 
107
136
  /** @returns {Promise<TransformResult | undefined>} */
@@ -111,57 +140,63 @@ export default async function postgres(opts = {}) {
111
140
  }
112
141
  const filename = path.relative(rootFolder, id);
113
142
 
143
+ const modules = parseModule(sql).toArray();
144
+ if (dev) await db?.annotate(modules, filename);
145
+
114
146
  const { js, dts, moduleDeclaration, mappings } = codegen(
115
- parseModule(sql),
147
+ modules,
116
148
  filename,
117
149
  moduleName(filename),
118
150
  runtime,
119
151
  );
120
152
 
121
- const dtsFolder = path.join(typesFolder, path.relative(rootFolder, path.dirname(id)));
122
- const dtsName = path.basename(filename, ".sql") + ".sql.d.ts";
123
- await fs.mkdir(dtsFolder, { recursive: true });
124
- await fs.writeFile(path.join(dtsFolder, dtsName), dts + `//# sourceMappingURL=${dtsName}.map\n`);
125
- await fs.writeFile(
126
- path.join(dtsFolder, dtsName + ".map"),
127
- JSON.stringify({
128
- version: 3,
129
- file: dtsName,
130
- sources: [path.relative(dtsFolder, id).replaceAll(path.sep, "/")],
131
- names: [],
132
- mappings: encodeMappings([
133
- { genLine: 0, genCol: 0, srcLine: 0, srcCol: 0 },
134
- ...exportMappings(dts, mappings),
135
- ]),
136
- }),
137
- );
138
- if (moduleDeclaration.length) {
139
- moduleDeclarations.set(filename, { text: moduleDeclaration.join("\n"), mappings, id });
140
- let line = 0;
141
- const sources = [];
142
- const combined = [];
143
- const texts = [];
144
- for (const { text, mappings, id } of moduleDeclarations.values()) {
145
- const srcIdx = sources.push(path.relative(typesFolder, id).replaceAll(path.sep, "/")) - 1;
146
- combined.push({ genLine: line, genCol: 0, srcIdx, srcLine: 0, srcCol: 0 });
147
- combined.push(...exportMappings(text, mappings, srcIdx, line));
148
- texts.push(text);
149
- line += text.split("\n").length;
150
- }
153
+ // described types must not be overwritten by naive ones outside of dev
154
+ if (!db || dev) {
155
+ const dtsFolder = path.join(typesFolder, path.relative(rootFolder, path.dirname(id)));
156
+ const dtsName = path.basename(filename, ".sql") + ".sql.d.ts";
157
+ await fs.mkdir(dtsFolder, { recursive: true });
158
+ await fs.writeFile(path.join(dtsFolder, dtsName), dts + `//# sourceMappingURL=${dtsName}.map\n`);
151
159
  await fs.writeFile(
152
- path.join(typesFolder, "modules.sql.d.ts"),
153
- texts.join("\n") + "\n//# sourceMappingURL=modules.sql.d.ts.map\n",
154
- );
155
- await fs.writeFile(
156
- path.join(typesFolder, "modules.sql.d.ts.map"),
160
+ path.join(dtsFolder, dtsName + ".map"),
157
161
  JSON.stringify({
158
162
  version: 3,
159
- file: "modules.sql.d.ts",
160
- sources,
163
+ file: dtsName,
164
+ sources: [path.relative(dtsFolder, id).replaceAll(path.sep, "/")],
161
165
  names: [],
162
- mappings: encodeMappings(combined),
166
+ mappings: encodeMappings([
167
+ { genLine: 0, genCol: 0, srcLine: 0, srcCol: 0 },
168
+ ...exportMappings(dts, mappings),
169
+ ]),
163
170
  }),
164
171
  );
172
+ if (moduleDeclaration.length) {
173
+ moduleDeclarations.set(filename, { text: moduleDeclaration.join("\n"), mappings, id });
174
+ let line = 0;
175
+ const sources = [];
176
+ const combined = [];
177
+ const texts = [];
178
+ for (const { text, mappings, id } of moduleDeclarations.values()) {
179
+ const srcIdx = sources.push(path.relative(typesFolder, id).replaceAll(path.sep, "/")) - 1;
180
+ combined.push({ genLine: line, genCol: 0, srcIdx, srcLine: 0, srcCol: 0 });
181
+ combined.push(...exportMappings(text, mappings, srcIdx, line));
182
+ texts.push(text);
183
+ line += text.split("\n").length;
184
+ }
185
+ await fs.writeFile(
186
+ path.join(typesFolder, "modules.sql.d.ts"),
187
+ texts.join("\n") + "\n//# sourceMappingURL=modules.sql.d.ts.map\n",
188
+ );
189
+ await fs.writeFile(
190
+ path.join(typesFolder, "modules.sql.d.ts.map"),
191
+ JSON.stringify({
192
+ version: 3,
193
+ file: "modules.sql.d.ts",
194
+ sources,
195
+ names: [],
196
+ mappings: encodeMappings(combined),
197
+ }),
198
+ );
199
+ }
165
200
  }
166
201
 
167
202
  return {
package/runtime.js ADDED
@@ -0,0 +1,94 @@
1
+ /**
2
+ * @typedef {{
3
+ * index: Map<string, number>,
4
+ * k: number,
5
+ * ph: string[],
6
+ * pos: Int32Array,
7
+ * mark: Float64Array,
8
+ * epoch: number,
9
+ * cur: unknown[] | null,
10
+ * esc: ((value: string) => string) | undefined,
11
+ * }} Slots
12
+ */
13
+
14
+ /**
15
+ * Static binding state of a query with slots. Own params map to their `$N`, slot params to `~j`.
16
+ * @param {string[]} own
17
+ * @param {string[]} extra
18
+ * @param {(value: string) => string} [esc] inlines values instead of binding them, for multi-statement queries
19
+ * @returns {Slots}
20
+ */
21
+ export function slots(own, extra, esc) {
22
+ const index = new Map(own.map((p, i) => [p, i + 1]));
23
+ for (let j = 0; j < extra.length; ++j) if (!index.has(extra[j])) index.set(extra[j], ~j);
24
+ const ph = [];
25
+ for (let i = 1; i <= own.length + extra.length; ++i) ph.push("$" + i);
26
+ return {
27
+ index,
28
+ k: own.length,
29
+ ph,
30
+ pos: new Int32Array(extra.length),
31
+ mark: new Float64Array(extra.length),
32
+ epoch: 0,
33
+ cur: null,
34
+ esc,
35
+ };
36
+ }
37
+
38
+ const word = (/** @type {number} */ c) => (c >= 48 && c <= 57) || (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c === 95;
39
+
40
+ /**
41
+ * Binds `:param` placeholders of a slot's text, appending slot params to `values` on first use.
42
+ *
43
+ * A call is identified by its `values` array, a different one starts a new epoch.
44
+ * `pos[j]` is only trusted when `mark[j]` was set in the current epoch.
45
+ * @param {string} s
46
+ * @param {unknown[] | null} values
47
+ * @param {Record<string, unknown>} params
48
+ * @param {Slots} q
49
+ */
50
+ export function slot(s, values, params, q) {
51
+ let i = s.indexOf(":");
52
+ if (i < 0) return s;
53
+ let out = "";
54
+ let last = 0;
55
+ for (; i >= 0; i = s.indexOf(":", i + 1)) {
56
+ const prev = i ? s.charCodeAt(i - 1) : 0;
57
+ if (prev === 58 || prev === 92 || word(prev)) continue;
58
+ let end = i + 1;
59
+ while (end < s.length && word(s.charCodeAt(end))) ++end;
60
+ if (end === i + 1) continue;
61
+ const name = s.slice(i + 1, end);
62
+ const n = q.index.get(name);
63
+ if (n === undefined) {
64
+ i = end - 1;
65
+ continue;
66
+ }
67
+ let p;
68
+ if (q.esc) {
69
+ p = q.esc(/** @type {string} */ (params[name]));
70
+ } else if (n > 0) {
71
+ p = q.ph[n - 1];
72
+ } else {
73
+ const j = ~n;
74
+ if (q.cur !== values) {
75
+ q.cur = values;
76
+ ++q.epoch;
77
+ }
78
+ let N = q.pos[j];
79
+ if (q.mark[j] !== q.epoch) {
80
+ N = q.pos[j] = /** @type {unknown[]} */ (values).push(params[name]);
81
+ q.mark[j] = q.epoch;
82
+ }
83
+ p = q.ph[N - 1] ?? "$" + N;
84
+ }
85
+ if (s.charCodeAt(end) === 33) {
86
+ const c = s.charCodeAt(end + 1);
87
+ if (c !== 61 && c !== 126) ++end;
88
+ }
89
+ out += s.slice(last, i) + p;
90
+ last = end;
91
+ i = end - 1;
92
+ }
93
+ return last ? out + s.slice(last) : s;
94
+ }