uql-orm 0.102.6 → 0.103.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.
Files changed (109) hide show
  1. package/README.md +1 -1
  2. package/dist/browser/uql-browser.min.js +2 -2
  3. package/dist/browser/uql-browser.min.js.map +3 -3
  4. package/dist/bunSql/bunSqlQuerier.d.ts +9 -3
  5. package/dist/bunSql/bunSqlQuerier.js +7 -15
  6. package/dist/cockroachdb/crdbQuerierPool.d.ts +2 -2
  7. package/dist/context/context.d.ts +0 -6
  8. package/dist/context/context.js +1 -7
  9. package/dist/d1/d1Querier.d.ts +18 -14
  10. package/dist/d1/d1Querier.js +21 -8
  11. package/dist/d1/d1QuerierPool.d.ts +0 -1
  12. package/dist/d1/d1QuerierPool.js +0 -1
  13. package/dist/d1/d1SqliteDialect.d.ts +2 -0
  14. package/dist/d1/d1SqliteDialect.js +3 -0
  15. package/dist/dialect/abstractDialect.d.ts +3 -0
  16. package/dist/dialect/abstractDialect.js +6 -2
  17. package/dist/dialect/abstractSqlDialect.d.ts +26 -7
  18. package/dist/dialect/abstractSqlDialect.js +89 -60
  19. package/dist/dialect/mysqlLikeSqlDialect.js +6 -1
  20. package/dist/dialect/operators.d.ts +9 -3
  21. package/dist/dialect/operators.js +32 -9
  22. package/dist/dialect/vectorSqlDialect.js +2 -2
  23. package/dist/entity/metadata/definition.d.ts +11 -1
  24. package/dist/entity/metadata/definition.js +18 -0
  25. package/dist/mariadb/mariadbQuerier.d.ts +5 -2
  26. package/dist/mariadb/mariadbQuerier.js +5 -10
  27. package/dist/migrate/ddl/defaultSql.js +1 -1
  28. package/dist/migrate/ddl/indexDdl.d.ts +3 -3
  29. package/dist/migrate/ddl/indexDdl.js +7 -7
  30. package/dist/migrate/ddl/mysqlIndexDdl.js +2 -2
  31. package/dist/migrate/ddl/tableDdl.js +2 -2
  32. package/dist/migrate/indexPredicate.d.ts +4 -3
  33. package/dist/migrate/indexPredicate.js +5 -5
  34. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +2 -6
  35. package/dist/migrate/schemaGenerator.js +1 -1
  36. package/dist/migrate/triggerSql.js +7 -5
  37. package/dist/mongodb/mongoDialect.js +17 -41
  38. package/dist/mongodb/mongoSchemaGenerator.js +12 -12
  39. package/dist/mongodb/mongodbQuerier.d.ts +4 -3
  40. package/dist/mongodb/mongodbQuerier.js +75 -102
  41. package/dist/mssql/mssqlDialect.js +4 -9
  42. package/dist/mssql/mssqlQuerier.d.ts +9 -3
  43. package/dist/mssql/mssqlQuerier.js +9 -11
  44. package/dist/mysql/mysql2Querier.d.ts +11 -2
  45. package/dist/mysql/mysql2Querier.js +4 -7
  46. package/dist/neon/index.d.ts +2 -0
  47. package/dist/neon/index.js +2 -0
  48. package/dist/neon/neonDialect.d.ts +7 -0
  49. package/dist/neon/neonDialect.js +8 -0
  50. package/dist/neon/neonQuerier.d.ts +26 -0
  51. package/dist/neon/neonQuerier.js +42 -0
  52. package/dist/neon/neonQuerierPool.d.ts +16 -6
  53. package/dist/neon/neonQuerierPool.js +48 -5
  54. package/dist/pglite/pgliteQuerier.d.ts +9 -5
  55. package/dist/pglite/pgliteQuerier.js +7 -11
  56. package/dist/postgres/abstractPgQuerierPool.d.ts +6 -6
  57. package/dist/postgres/pgExecution.d.ts +8 -0
  58. package/dist/postgres/pgExecution.js +3 -0
  59. package/dist/postgres/pgQuerier.d.ts +8 -11
  60. package/dist/postgres/pgQuerier.js +5 -9
  61. package/dist/postgres/pgQuerierPool.d.ts +2 -2
  62. package/dist/querier/abstractQuerier.d.ts +24 -20
  63. package/dist/querier/abstractQuerier.js +79 -58
  64. package/dist/querier/abstractQuerierPool.d.ts +2 -4
  65. package/dist/querier/abstractQuerierPool.js +2 -0
  66. package/dist/querier/abstractSqlQuerier.d.ts +46 -30
  67. package/dist/querier/abstractSqlQuerier.js +141 -119
  68. package/dist/querier/queryError.d.ts +2 -0
  69. package/dist/querier/queryError.js +9 -0
  70. package/dist/querier/transaction.js +3 -7
  71. package/dist/schema/canonicalType.d.ts +3 -3
  72. package/dist/schema/canonicalType.js +4 -10
  73. package/dist/sqlite/bindValues.d.ts +10 -0
  74. package/dist/sqlite/bindValues.js +8 -0
  75. package/dist/sqlite/hranaQuerier.d.ts +17 -11
  76. package/dist/sqlite/hranaQuerier.js +16 -5
  77. package/dist/sqlite/index.d.ts +1 -1
  78. package/dist/sqlite/index.js +0 -1
  79. package/dist/sqlite/localSqliteQuerierPool.js +19 -9
  80. package/dist/sqlite/sqliteQuerier.d.ts +9 -4
  81. package/dist/sqlite/sqliteQuerier.js +14 -8
  82. package/dist/turso/tursoQuerierPool.d.ts +0 -2
  83. package/dist/turso/tursoQuerierPool.js +0 -2
  84. package/dist/turso/tursoSessionQuerier.d.ts +19 -7
  85. package/dist/turso/tursoSessionQuerier.js +31 -20
  86. package/dist/type/dialect.d.ts +3 -0
  87. package/dist/type/querier.d.ts +12 -0
  88. package/dist/type/querier.js +10 -0
  89. package/dist/type/vector.d.ts +2 -1
  90. package/dist/type/vector.js +2 -2
  91. package/dist/util/asyncScope.d.ts +11 -0
  92. package/dist/util/asyncScope.js +29 -0
  93. package/dist/util/dialect.util.d.ts +21 -6
  94. package/dist/util/dialect.util.js +34 -9
  95. package/dist/util/filters.util.d.ts +5 -4
  96. package/dist/util/filters.util.js +4 -7
  97. package/dist/util/logger.js +2 -6
  98. package/dist/util/object.util.d.ts +7 -0
  99. package/dist/util/object.util.js +17 -0
  100. package/dist/util/query.util.d.ts +3 -2
  101. package/dist/util/sql.js +1 -1
  102. package/dist/util/sql.util.d.ts +18 -16
  103. package/dist/util/sql.util.js +8 -6
  104. package/package.json +5 -8
  105. package/skills/uql-orm/SKILL.md +4 -2
  106. package/dist/context/context.browser.d.ts +0 -12
  107. package/dist/context/context.browser.js +0 -33
  108. package/dist/sqlite/abstractSqliteQuerier.d.ts +0 -28
  109. package/dist/sqlite/abstractSqliteQuerier.js +0 -36
@@ -1,11 +1,12 @@
1
1
  import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
2
- import { getMeta, namesKey } from '../entity/index.js';
3
- import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement } from '../util/index.js';
2
+ import { getMeta } from '../entity/index.js';
3
+ import { soleId } from '../entity/metadata/definition.js';
4
+ import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement, upsertKeepsOwnKey, } from '../util/index.js';
4
5
  import { statementOf } from '../util/sql.js';
5
6
  import { UqlUsageError } from '../util/uqlError.js';
6
7
  import { AbstractQuerier } from './abstractQuerier.js';
7
8
  import { streamViaCursor } from './cursorStream.js';
8
- import { enrichError } from './queryError.js';
9
+ import { enrichError, failedIndexOf } from './queryError.js';
9
10
  import { rowReader } from './rowReader.js';
10
11
  /**
11
12
  * Row indexes split by whether the row names its key, the one thing that changes what an insert can
@@ -65,14 +66,12 @@ export class AbstractSqlQuerier extends AbstractQuerier {
65
66
  this.dialect = dialect;
66
67
  this.extra = extra;
67
68
  }
68
- /**
69
- * Build a QueryUpdateResult with affected changes and calculated IDs.
70
- */
71
- buildUpdateResult(payload) {
69
+ /** What a write reports: the rows it changed, and their ids, inferred from a header's first id where the dialect reads them so. */
70
+ updateResultOf(result) {
72
71
  return buildUpdateResult({
72
+ ...result,
73
73
  insertIdSource: this.dialect.insertIdSource,
74
74
  insertIdIncrement: this.#insertIdIncrement,
75
- ...payload,
76
75
  });
77
76
  }
78
77
  /**
@@ -91,58 +90,79 @@ export class AbstractSqlQuerier extends AbstractQuerier {
91
90
  * caught for every SQL backend.
92
91
  */
93
92
  async lazyConnect() {
94
- if (this.released) {
95
- throw new UqlUsageError('querier already released');
96
- }
93
+ this.assertActive();
97
94
  }
98
95
  all(...statement) {
99
- return this.query(statementOf(statement));
96
+ return this.rowsOf(statementOf(statement));
100
97
  }
101
98
  run(...statement) {
102
- return this.exec(statementOf(statement));
99
+ return this.changesOf(statementOf(statement));
103
100
  }
104
- /** Refused before the driver fails it, or PGlite answers it and every read after it wrong. */
105
- assertBindBudget(values) {
106
- const { maxBindValues, dialectName } = this.dialect;
107
- if (values && values.length > maxBindValues) {
108
- throw new UqlUsageError(`a statement binding ${values.length} values is past the ${maxBindValues} ${dialectName} takes; split the list it binds`);
101
+ /**
102
+ * The one path every statement takes, alone or as a list answering a result each, all or none: one request where
103
+ * the driver has {@link executeBatch}, a failure tagged with the statement it names; else in turn, in a transaction
104
+ * where `atomic` (a split write) asks for one, opened before the queue is taken, which its `BEGIN` waits on.
105
+ */
106
+ runStatements(statements, atomic = false) {
107
+ const executeBatch = statements.length > 1 ? this.executeBatch?.bind(this) : undefined;
108
+ if (!executeBatch) {
109
+ const inTurn = () => this.inTurn(statements);
110
+ return atomic ? this.atomically(inTurn) : inTurn();
109
111
  }
112
+ const sql = statements.map((statement) => statement.sql).join('; ');
113
+ const values = statements.flatMap((statement) => statement.values);
114
+ return this.onConnection(() => this.timed(sql, values, () => executeBatch(statements).catch((error) => {
115
+ const statement = statements[failedIndexOf(error) ?? -1];
116
+ throw statement ? enrichError(error, this.logger, statement.sql, statement.values) : error;
117
+ })));
118
+ }
119
+ /** Runs `statements` one after another on the connection, each timed. */
120
+ inTurn(statements) {
121
+ return this.onConnection(async () => {
122
+ const results = [];
123
+ for (const { sql, values } of statements) {
124
+ results.push(await this.timed(sql, values, () => this.execute(sql, values)));
125
+ }
126
+ return results;
127
+ });
110
128
  }
111
- /** The rows of a statement the dialect builds. */
112
- query(build) {
113
- return this.send(build, (sql, values) => this.internalAll(sql, values));
114
- }
115
- /** Runs a statement the dialect builds. */
116
- exec(build) {
117
- return this.send(build, (sql, values) => this.internalRun(sql, values));
129
+ /** Runs `task` on the connection, connected, after everything queued before it. */
130
+ onConnection(task) {
131
+ return this.serialize(() => this.lazyConnect().then(task));
118
132
  }
119
- /** Builds a statement and sends it on the connection, in turn, timed and its failure tagged with it. */
120
- async send(build, task) {
133
+ /** The statement `build` writes, refused past the bind budget before the driver fails it. */
134
+ bound(build) {
121
135
  const { sql, values } = this.dialect.compile(build);
122
136
  this.assertBindBudget(values);
123
- return this.serialize(async () => {
124
- await this.lazyConnect();
125
- return this.timed(sql, values, () => task(sql, values));
126
- });
137
+ return { sql, values };
127
138
  }
128
- /**
129
- * Runs the `SET`s tuning an ANN index for the query on its connection, refusing where they would apply to
130
- * nothing: a `SET LOCAL` outside a transaction.
131
- */
132
- async applyVectorTuning(entity, q) {
133
- // Resolved before the transaction check, so the refusal fires only where the tuning would have
134
- // meant something: a query with no vector search, or on a field carrying no ANN index, has
135
- // nothing to set and no reason to demand a transaction for it.
136
- const statements = this.dialect.vectorTuningStatements(getMeta(entity), q);
137
- if (!statements.length) {
138
- return;
139
- }
140
- if (this.dialect.features.vectorTuningNeedsTransaction && !this.scopeHere()) {
141
- throw new UqlUsageError(`$candidates requires an open transaction on ${this.dialect.dialectName}; run the query inside pool.transaction(...)`);
139
+ /** Refused before the driver fails it, or PGlite answers it and every read after it wrong. */
140
+ assertBindBudget(values) {
141
+ const { maxBindValues, engineName } = this.dialect;
142
+ if (values && values.length > maxBindValues) {
143
+ throw new UqlUsageError(`a statement binding ${values.length} values is past the ${maxBindValues} ${engineName} takes; split the list it binds`);
142
144
  }
143
- for (const statement of statements) {
144
- await this.internalRun(statement);
145
+ }
146
+ /** The rows of the statement `build` writes, as the caller types them. */
147
+ async rowsOf(build) {
148
+ const [{ rows }] = await this.runStatements([this.bound(build)]);
149
+ return rows;
150
+ }
151
+ /** What the write `build` writes reports. */
152
+ async changesOf(build) {
153
+ const [result] = await this.runStatements([this.bound(build)]);
154
+ return this.updateResultOf(result);
155
+ }
156
+ /** The `SET`s tuning an ANN index for the query, leading its read: none without a vector search or an ANN index. */
157
+ vectorTuning(entity, q) {
158
+ if (q.$candidates === undefined) {
159
+ return [];
145
160
  }
161
+ return this.dialect.vectorTuningStatements(getMeta(entity), q).map((sql) => ({ sql, values: [] }));
162
+ }
163
+ /** Whether `tuning` applies only inside a transaction, as a `SET LOCAL` does: a read opens one, or joins the open one. */
164
+ tunedInTransaction(tuning) {
165
+ return tuning.length > 0 && this.dialect.features.vectorTuningNeedsTransaction;
146
166
  }
147
167
  async internalFindMany(entity, q, opts) {
148
168
  return this.selectRows(entity, q, opts);
@@ -170,36 +190,41 @@ export class AbstractSqlQuerier extends AbstractQuerier {
170
190
  }
171
191
  return [rows, total];
172
192
  }
173
- /** The rows a read of `entity` matches, each as its statement reads it. */
174
- async selectRows(entity, q, opts, totalAlias) {
175
- // Guarded rather than awaited unconditionally, here and in the stream below: an `await` on this
176
- // path defers a microtask on every read, which reorders the two statements `findManyAndCount`
177
- // issues concurrently. Keep the guard at any new call site.
178
- if (q.$candidates !== undefined) {
179
- await this.applyVectorTuning(entity, q);
180
- }
181
- return this.readRows((ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias));
193
+ /**
194
+ * The rows a read of `entity` matches, each as its statement reads it, the vector search's tuning leading it, in a
195
+ * transaction of its own where the tuning needs one and none is open.
196
+ */
197
+ selectRows(entity, q, opts, totalAlias) {
198
+ const tuning = this.vectorTuning(entity, q);
199
+ const build = (ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias);
200
+ return this.readRows(build, tuning, this.tunedInTransaction(tuning));
182
201
  }
183
- /** The rows of a read the dialect builds, each as the terms it returns say. */
184
- async readRows(build) {
202
+ /** The rows of a statement the dialect builds, each as the terms it returns say, after the `leading` ones. */
203
+ async readRows(build, leading = [], atomic = false) {
185
204
  let terms = [];
186
- const rows = await this.query((ctx) => {
205
+ const statement = this.bound((ctx) => {
187
206
  terms = build(ctx);
188
207
  });
189
- return rows.map(rowReader(terms));
208
+ const results = await this.runStatements([...leading, statement], atomic);
209
+ return results[leading.length].rows.map(rowReader(terms));
190
210
  }
191
211
  /**
192
- * The one read not going through `all`, so it checks its budget and connects on its own; its values go as
193
- * the context holds them, each normalized as it was bound. The tuning is guarded as `selectRows` says.
212
+ * The one read not going through `runStatements`: it holds the connection for its loop, so it checks its budget
213
+ * and connects on its own, its values going as the context holds them, each normalized as it was bound. Tuning
214
+ * that needs a transaction is refused outside one, which would otherwise stay open for the whole loop.
194
215
  */
195
216
  async *internalFindManyStream(entity, q, opts) {
217
+ const tuning = this.vectorTuning(entity, q);
218
+ if (this.tunedInTransaction(tuning) && !this.scopeHere()) {
219
+ throw new UqlUsageError(`a streamed $candidates needs an open transaction on ${this.dialect.engineName}; run the stream inside pool.transaction(...)`);
220
+ }
196
221
  const ctx = this.dialect.createContext();
197
222
  const read = rowReader(this.dialect.find(ctx, entity, q, opts));
198
223
  this.assertBindBudget(ctx.values);
199
- if (q.$candidates !== undefined) {
200
- await this.applyVectorTuning(entity, q);
201
- }
202
224
  await this.lazyConnect();
225
+ for (const { sql } of tuning) {
226
+ await this.timed(sql, undefined, () => this.execute(sql));
227
+ }
203
228
  for await (const row of this.timedStream(ctx.sql, ctx.values, this.internalStream(ctx.sql, ctx.values))) {
204
229
  yield read(row);
205
230
  }
@@ -211,10 +236,10 @@ export class AbstractSqlQuerier extends AbstractQuerier {
211
236
  */
212
237
  async *internalStream(query, values) {
213
238
  if (!this.dialect.features.serverSideCursors) {
214
- yield* await this.internalAll(query, values);
239
+ yield* (await this.execute(query, values)).rows;
215
240
  return;
216
241
  }
217
- yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, !!this.scopeHere());
242
+ yield* streamViaCursor(async (sql, params) => (await this.execute(sql, params)).rows, query, values, !!this.scopeHere());
218
243
  }
219
244
  /**
220
245
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
@@ -222,7 +247,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
222
247
  * as 0; no row is 0 too, since a catalog that does not know the table answers with none.
223
248
  */
224
249
  async runCount(build) {
225
- const [row] = await this.query(build);
250
+ const [row] = await this.rowsOf(build);
226
251
  return row ? Number(row[AGGREGATE_VALUE_ALIAS]) : 0;
227
252
  }
228
253
  async internalCount(entity, q, opts) {
@@ -239,14 +264,13 @@ export class AbstractSqlQuerier extends AbstractQuerier {
239
264
  // What comes back is one column's value, so nothing is read back for a composite: its rows
240
265
  // already carry every column of it. `sole` is what keeps every id path off such a key.
241
266
  const [idKey] = meta.ids;
242
- const sole = meta.ids.length === 1;
243
- const idField = sole ? meta.fields[idKey] : undefined;
244
- const generatedKey = !!idField && isAutoIncrement(idField, true);
267
+ const sole = soleId(meta);
268
+ const generatedKey = !!sole && isAutoIncrement(sole.field, true);
245
269
  // Per group, not per batch: the two carry different columns - one names the key, one does not - so a budget
246
270
  // taken over their union would under-fill the statement that is missing one. Header ids are only sound where
247
271
  // every row of a statement left its key to the database, so a supplied id cannot void the others.
248
272
  const statements = partitionBySuppliedId(rows, idKey).flatMap((group) => {
249
- const idsReliable = sole &&
273
+ const idsReliable = !!sole &&
250
274
  (this.dialect.insertIdSource === 'returning' ||
251
275
  (generatedKey && group.every((index) => rows[index][idKey] === undefined)));
252
276
  const { maxBindValues, maxInsertRows } = this.dialect;
@@ -261,21 +285,22 @@ export class AbstractSqlQuerier extends AbstractQuerier {
261
285
  statements.some(({ indexes, idsReliable }) => idsReliable && indexes.length > 1)) {
262
286
  this.#insertIdIncrement ??= await this.loadInsertIdIncrement();
263
287
  }
264
- const insert = async () => {
265
- for (const { indexes, idsReliable } of statements) {
266
- const statementRows = indexes.map((index) => rows[index]);
267
- const { ids = [] } = await this.exec((ctx) => this.dialect.insert(ctx, entity, statementRows));
268
- if (idsReliable) {
269
- for (let position = 0; position < indexes.length; position++) {
270
- rows[indexes[position]][idKey] ??= ids[position];
271
- }
272
- }
288
+ const results = await this.runStatements(statements.map(({ indexes }) => {
289
+ const statementRows = indexes.map((index) => rows[index]);
290
+ return this.bound((ctx) => this.dialect.insert(ctx, entity, statementRows));
291
+ }), statements.length > 1);
292
+ results.forEach((result, at) => {
293
+ const { indexes, idsReliable } = statements[at];
294
+ if (idsReliable) {
295
+ const { ids } = this.updateResultOf(result);
296
+ indexes.forEach((index, position) => {
297
+ rows[index][idKey] ??= ids[position];
298
+ });
273
299
  }
274
- };
275
- await (statements.length > 1 ? this.atomically(insert) : insert());
300
+ });
276
301
  }
277
302
  async internalUpdateMany(entity, q, payload, opts) {
278
- const { changes = 0 } = await this.exec((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
303
+ const { changes } = await this.changesOf((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
279
304
  return changes;
280
305
  }
281
306
  /** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
@@ -302,46 +327,43 @@ export class AbstractSqlQuerier extends AbstractQuerier {
302
327
  // One statement per shape, each split again to fit the bind budget, less what its assignments bind once.
303
328
  // Grouping first is what makes that one figure: every row of a group carries the same columns. No row cap:
304
329
  // the one engine with one, SQL Server, upserts through a MERGE, whose source takes any number.
305
- const statements = groupByInsertShape(meta, payload).flatMap((group) => {
306
- const assigned = this.dialect.upsertAssignmentBinds(entity, conflictPaths, payload[group[0]], update);
307
- return chunkWithinLimits(meta, payload, group, this.dialect.maxBindValues - assigned);
330
+ const groups = groupByInsertShape(meta, payload).flatMap((group) => {
331
+ const { binds, assigns } = this.dialect.upsertAssignments(entity, conflictPaths, payload[group[0]], update);
332
+ const chunks = chunkWithinLimits(meta, payload, group, this.dialect.maxBindValues - binds);
333
+ // `reports`: the statement answers each row's id in order, which spares the read back.
334
+ return chunks.map((indexes) => ({
335
+ indexes,
336
+ reports: assigns && this.dialect.upsertReportsIds(meta, indexes.length),
337
+ }));
308
338
  });
309
- if (statements.length === 1) {
310
- return this.runUpsert(entity, conflictPaths, payload, update);
311
- }
312
- // An upsert's assignment list is the statement's, so rows of different shapes go in statements of their own.
313
- return this.atomically(async () => {
314
- // Placed by index, since grouping by shape reorders the rows. A statement reporting fewer ids
315
- // than it wrote places none.
316
- const ids = new Array(payload.length);
317
- for (const indexes of statements) {
318
- const reported = await this.runUpsert(entity, conflictPaths, indexes.map((index) => payload[index]), update);
319
- if (reported?.length === indexes.length) {
320
- for (let position = 0; position < indexes.length; position++) {
321
- ids[indexes[position]] = reported[position];
322
- }
323
- }
339
+ // Asked first: the statement fills an `onInsert` key into these rows whether it inserts them or not.
340
+ const kept = payload.map((row) => upsertKeepsOwnKey(meta, conflictPaths, row));
341
+ const statements = groups.map(({ indexes }) => this.bound((ctx) => this.dialect.upsert(ctx, entity, conflictPaths, indexes.map((index) => payload[index]), update)));
342
+ const results = await this.runStatements(statements, groups.length > 1);
343
+ // Placed by index, since grouping by shape reorders the rows. A statement reporting fewer ids than it
344
+ // wrote places none.
345
+ const ids = new Array(payload.length);
346
+ groups.forEach(({ indexes, reports }, group) => {
347
+ const reported = reports ? this.reportedIds(results[group]) : [];
348
+ if (reported.length === indexes.length) {
349
+ indexes.forEach((index, position) => {
350
+ ids[index] = reported[position];
351
+ });
324
352
  }
325
- return ids;
326
353
  });
327
- }
328
- async runUpsert(entity, conflictPaths, payload, update) {
329
- const meta = getMeta(entity);
330
- // Asked first: the statement fills an `onInsert` key into these rows whether it inserts them or not.
331
- const unnamed = payload.some((row) => !namesKey(meta, row));
332
- const { ids } = await this.exec((ctx) => this.dialect.upsert(ctx, entity, conflictPaths, payload, update));
333
- const ordered = payload.length === 1 ||
334
- (this.dialect.insertIdSource === 'returning' && this.dialect.features.orderedUpsertReturning);
335
- if (meta.ids.length === 1 && ordered && ids?.length === payload.length) {
336
- return ids;
354
+ // Where the statement cannot report every row's id in order (see `upsertReportsIds`), or assigns a found row
355
+ // nothing, `DO NOTHING`, which skips it, the ids are read back by the conflict columns.
356
+ return this.withUnreportedIds(entity, conflictPaths, payload, ids, kept);
357
+ }
358
+ /** The ids an upsert reports of its rows: its `RETURNING` rows' in order, or its one row's in the header. */
359
+ reportedIds(result) {
360
+ if (result.rows.length) {
361
+ return this.updateResultOf(result).ids;
337
362
  }
338
- // The statement's ids name its rows only in order and for every one. A MySQL batch reports a
339
- // weighted count (1=insert, 2=update) instead, CockroachDB and SQL Server answer out of order, and
340
- // `DO NOTHING` skips rows, so there the ids are read back by the conflict columns.
341
- return unnamed ? this.idsByConflict(entity, conflictPaths, payload) : undefined;
363
+ return result.id ? [result.id] : [];
342
364
  }
343
365
  async internalDeleteMany(entity, q, opts) {
344
- const { changes = 0 } = await this.exec((ctx) => this.dialect.delete(ctx, entity, q, opts));
366
+ const { changes } = await this.changesOf((ctx) => this.dialect.delete(ctx, entity, q, opts));
345
367
  return changes;
346
368
  }
347
369
  async openTransaction(opts) {
@@ -392,7 +414,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
392
414
  /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
393
415
  async runTransactionCommand(sql) {
394
416
  try {
395
- await this.internalRun(sql);
417
+ await this.execute(sql);
396
418
  }
397
419
  catch (err) {
398
420
  throw enrichError(err, this.logger, sql);
@@ -13,6 +13,8 @@ export interface QueryError extends Error {
13
13
  * read, so it works on any driver error, whether or not a querier saw it first.
14
14
  */
15
15
  export declare function queryErrorKind(err: unknown): QueryErrorKind | undefined;
16
+ /** The statement a failed list's driver says failed: libSQL's `statementIndex`, Turso's `batchIndex`. */
17
+ export declare function failedIndexOf(err: unknown): number | undefined;
16
18
  /**
17
19
  * Tags `err` with the query it failed on and hands it back, so `throw enrichError(...)` reads as the
18
20
  * control flow it is. `values` are attached only when `logger?.willLogValues()`: they already surface
@@ -66,6 +66,15 @@ export function queryErrorKind(err) {
66
66
  (Array.isArray(errorLabels) && errorLabels.includes('TransientTransactionError') ? 'retryable' : undefined) ??
67
67
  SQLITE_MESSAGE_KINDS.find(([fragment]) => text.includes(fragment))?.[1]);
68
68
  }
69
+ /** The statement a failed list's driver says failed: libSQL's `statementIndex`, Turso's `batchIndex`. */
70
+ export function failedIndexOf(err) {
71
+ if (!(err instanceof Error)) {
72
+ return undefined;
73
+ }
74
+ const { statementIndex, batchIndex } = err;
75
+ const at = statementIndex ?? batchIndex;
76
+ return typeof at === 'number' ? at : undefined;
77
+ }
69
78
  /**
70
79
  * Tags `err` with the query it failed on and hands it back, so `throw enrichError(...)` reads as the
71
80
  * control flow it is. `values` are attached only when `logger?.willLogValues()`: they already surface
@@ -1,13 +1,9 @@
1
- import { asyncScope } from '../context/context.js';
1
+ import { asyncScope } from '../util/asyncScope.js';
2
+ import { cachedIn } from '../util/object.util.js';
2
3
  const slots = new WeakMap();
3
4
  /** The slot of `connection`, whichever querier on it asks. */
4
5
  export function slotOf(connection) {
5
- let slot = slots.get(connection);
6
- if (!slot) {
7
- slot = {};
8
- slots.set(connection, slot);
9
- }
10
- return slot;
6
+ return cachedIn(slots, connection, () => ({}));
11
7
  }
12
8
  /**
13
9
  * Waits until `slot` holds no transaction, then holds it for `scope`, the root of its own, until {@link free}:
@@ -1,6 +1,6 @@
1
1
  import type { AbstractDialect } from '../dialect/abstractDialect.js';
2
2
  import type { VectorCast } from '../dialect/vectorCast.js';
3
- import type { ColumnType, EntityGetter, FieldMeta, FieldOptions } from '../type/entity.js';
3
+ import type { ColumnType, FieldMeta, FieldOptions } from '../type/entity.js';
4
4
  import { type DialectName } from '../type/index.js';
5
5
  import type { CanonicalType, TypeCategory } from './types.js';
6
6
  /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
@@ -51,7 +51,7 @@ export declare function isBreakingTypeChange(from: CanonicalType, to: CanonicalT
51
51
  export declare function canonicalToColumnType(type: CanonicalType): ColumnType;
52
52
  /**
53
53
  * A field's canonical type, taken from the referenced key where the field gave `references` and no
54
- * `type` (`typeFromReference`), so a foreign key matches the key it points at; `columnType` always wins.
54
+ * `type` (`valueFieldOf`), so a foreign key matches the key it points at; `columnType` always wins.
55
55
  */
56
- export declare function resolveColumnCanonicalType(field: FieldMeta, seen?: Set<EntityGetter>): CanonicalType;
56
+ export declare function resolveColumnCanonicalType(field: FieldMeta): CanonicalType;
57
57
  export {};
@@ -1,5 +1,5 @@
1
1
  // Canonical types, between an engine's SQL types and TypeScript's.
2
- import { fieldOf, getMeta, soleIdOf } from '../entity/metadata/definition.js';
2
+ import { valueFieldOf } from '../entity/metadata/definition.js';
3
3
  import { QuerySql } from '../type/index.js';
4
4
  import { DATE_PRECISION } from '../util/date.js';
5
5
  import { columnFamily, isIntegerColumn } from '../util/field.util.js';
@@ -459,14 +459,8 @@ export function canonicalToColumnType(type) {
459
459
  }
460
460
  /**
461
461
  * A field's canonical type, taken from the referenced key where the field gave `references` and no
462
- * `type` (`typeFromReference`), so a foreign key matches the key it points at; `columnType` always wins.
462
+ * `type` (`valueFieldOf`), so a foreign key matches the key it points at; `columnType` always wins.
463
463
  */
464
- export function resolveColumnCanonicalType(field, seen = new Set()) {
465
- const hasExplicitType = !!field.columnType || !field.typeFromReference;
466
- if (!hasExplicitType && field.references && !seen.has(field.references)) {
467
- seen.add(field.references);
468
- const referencedMeta = getMeta(field.references());
469
- return resolveColumnCanonicalType(fieldOf(referencedMeta, soleIdOf(referencedMeta, 'a foreign key')), seen);
470
- }
471
- return fieldOptionsToCanonical(field);
464
+ export function resolveColumnCanonicalType(field) {
465
+ return fieldOptionsToCanonical(valueFieldOf(field));
472
466
  }
@@ -0,0 +1,10 @@
1
+ import type { BoundStatement } from '../querier/index.js';
2
+ /** What every SQLite driver binds. No `boolean`, which the drivers refuse and the dialect writes as an integer. */
3
+ export type SqliteBindValue = null | string | number | bigint | Uint8Array;
4
+ /** The compiler hands values over untyped, which the dialect has already normalized to what SQLite binds. */
5
+ export declare function toBindValues(values?: readonly unknown[]): SqliteBindValue[];
6
+ /** `statements` as a SQLite driver taking a list names each one: its SQL and the values it binds. */
7
+ export declare function sqliteStatements(statements: readonly BoundStatement[]): {
8
+ sql: string;
9
+ args: SqliteBindValue[];
10
+ }[];
@@ -0,0 +1,8 @@
1
+ /** The compiler hands values over untyped, which the dialect has already normalized to what SQLite binds. */
2
+ export function toBindValues(values = []) {
3
+ return values;
4
+ }
5
+ /** `statements` as a SQLite driver taking a list names each one: its SQL and the values it binds. */
6
+ export function sqliteStatements(statements) {
7
+ return statements.map(({ sql, values }) => ({ sql, args: toBindValues(values) }));
8
+ }
@@ -1,18 +1,23 @@
1
- import type { ExtraOptions, RawRow, TransactionOptions } from '../type/index.js';
2
- import { AbstractSqliteQuerier, type SqliteBindValue } from './abstractSqliteQuerier.js';
1
+ import { AbstractSqlQuerier, type BoundStatement } from '../querier/index.js';
2
+ import type { ExtraOptions, TransactionOptions } from '../type/index.js';
3
+ import type { SqlExecution } from '../util/sql.util.js';
4
+ import { type SqliteBindValue } from './bindValues.js';
3
5
  import type { SqliteDialect } from './sqliteDialect.js';
4
6
  export type HranaInValue = SqliteBindValue | ArrayBuffer | Date;
5
7
  export type HranaResultSet = {
6
8
  rows: unknown[];
7
9
  rowsAffected: number;
8
10
  };
11
+ export type HranaStatement = {
12
+ sql: string;
13
+ args?: HranaInValue[];
14
+ };
9
15
  export type HranaExecutor = {
10
- execute(stmt: {
11
- sql: string;
12
- args?: HranaInValue[];
13
- }): Promise<HranaResultSet>;
16
+ execute(stmt: HranaStatement): Promise<HranaResultSet>;
14
17
  };
18
+ /** An open transaction's handle: its own `batch` runs a list inside it, stopping at the first failure. */
15
19
  export type HranaTransaction = HranaExecutor & {
20
+ batch(stmts: HranaStatement[]): Promise<HranaResultSet[]>;
16
21
  commit(): Promise<void>;
17
22
  rollback(): Promise<void>;
18
23
  };
@@ -22,6 +27,8 @@ export type HranaTransaction = HranaExecutor & {
22
27
  * without the vendor's types.
23
28
  */
24
29
  export type HranaClient = HranaExecutor & {
30
+ /** Runs `stmts` as one request, all or none, in a transaction of `mode`. */
31
+ batch(stmts: HranaStatement[], mode: 'write'): Promise<HranaResultSet[]>;
25
32
  transaction(mode?: 'write' | 'read' | 'deferred'): Promise<HranaTransaction>;
26
33
  close(): void;
27
34
  };
@@ -36,17 +43,16 @@ export type HranaQuerierConnectionOptions = {
36
43
  * @remarks Transactions use the client's own session handle rather than `BEGIN`/`COMMIT` statements,
37
44
  * because over plain HTTP consecutive requests need not share a connection.
38
45
  */
39
- export declare class HranaQuerier extends AbstractSqliteQuerier {
46
+ export declare class HranaQuerier extends AbstractSqlQuerier {
40
47
  readonly client: HranaClient;
41
48
  readonly extra?: ExtraOptions | undefined;
42
49
  private tx?;
43
50
  private readonly closeClientOnRelease;
44
51
  constructor(client: HranaClient, dialect: SqliteDialect, extra?: ExtraOptions | undefined, connection?: HranaQuerierConnectionOptions);
45
52
  /** Runs on the open transaction's handle when there is one. */
46
- protected execute(query: string, values: SqliteBindValue[]): Promise<{
47
- rows: RawRow[];
48
- changes: number;
49
- }>;
53
+ protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
54
+ /** A list as one request: the client's `batch`, all or none; inside an open transaction, its own, which joins it. */
55
+ protected executeBatch(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
50
56
  protected internalBegin(opts?: TransactionOptions): Promise<void>;
51
57
  /**
52
58
  * Both drop the handle before the call, not after: one that outlived a failed commit would carry
@@ -1,11 +1,13 @@
1
- import { AbstractSqliteQuerier } from './abstractSqliteQuerier.js';
1
+ import { AbstractSqlQuerier } from '../querier/index.js';
2
+ import { decodeBigInts } from '../util/wideNumber.js';
3
+ import { sqliteStatements, toBindValues } from './bindValues.js';
2
4
  /**
3
5
  * Querier for SQLite databases reached through a Hrana client.
4
6
  *
5
7
  * @remarks Transactions use the client's own session handle rather than `BEGIN`/`COMMIT` statements,
6
8
  * because over plain HTTP consecutive requests need not share a connection.
7
9
  */
8
- export class HranaQuerier extends AbstractSqliteQuerier {
10
+ export class HranaQuerier extends AbstractSqlQuerier {
9
11
  client;
10
12
  extra;
11
13
  tx;
@@ -17,9 +19,14 @@ export class HranaQuerier extends AbstractSqliteQuerier {
17
19
  this.closeClientOnRelease = connection?.closeClientOnRelease ?? false;
18
20
  }
19
21
  /** Runs on the open transaction's handle when there is one. */
20
- async execute(query, values) {
21
- const res = await (this.tx ?? this.client).execute({ sql: query, args: values });
22
- return { rows: res.rows, changes: res.rowsAffected };
22
+ async execute(sql, values) {
23
+ return executionOf(await (this.tx ?? this.client).execute({ sql, args: toBindValues(values) }));
24
+ }
25
+ /** A list as one request: the client's `batch`, all or none; inside an open transaction, its own, which joins it. */
26
+ async executeBatch(statements) {
27
+ const stmts = sqliteStatements(statements);
28
+ const results = await (this.tx ? this.tx.batch(stmts) : this.client.batch(stmts, 'write'));
29
+ return results.map(executionOf);
23
30
  }
24
31
  async internalBegin(opts) {
25
32
  this.tx = await this.client.transaction(opts?.readOnly ? 'read' : 'write');
@@ -44,3 +51,7 @@ export class HranaQuerier extends AbstractSqliteQuerier {
44
51
  }
45
52
  }
46
53
  }
54
+ /** A result set as the querier reads it: Hrana's rows, read by column name, their wide integers decoded. */
55
+ function executionOf({ rows, rowsAffected }) {
56
+ return { rows: rows.map(decodeBigInts), changes: rowsAffected };
57
+ }
@@ -1,4 +1,4 @@
1
- export * from './abstractSqliteQuerier.js';
1
+ export type { SqliteBindValue } from './bindValues.js';
2
2
  export * from './hranaQuerier.js';
3
3
  export * from './nodeSqliteQuerierPool.js';
4
4
  export { SqliteDialect } from './sqliteDialect.js';
@@ -1,4 +1,3 @@
1
- export * from './abstractSqliteQuerier.js';
2
1
  export * from './hranaQuerier.js';
3
2
  export * from './nodeSqliteQuerierPool.js';
4
3
  export { SqliteDialect } from './sqliteDialect.js';