uql-orm 0.102.5 → 0.102.7

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 (98) 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/d1/d1Querier.d.ts +18 -14
  7. package/dist/d1/d1Querier.js +21 -8
  8. package/dist/d1/d1SqliteDialect.d.ts +2 -0
  9. package/dist/d1/d1SqliteDialect.js +3 -0
  10. package/dist/dialect/abstractDialect.d.ts +3 -0
  11. package/dist/dialect/abstractDialect.js +6 -2
  12. package/dist/dialect/abstractSqlDialect.d.ts +24 -5
  13. package/dist/dialect/abstractSqlDialect.js +86 -57
  14. package/dist/dialect/mysqlLikeSqlDialect.js +6 -1
  15. package/dist/dialect/operators.d.ts +9 -3
  16. package/dist/dialect/operators.js +32 -9
  17. package/dist/dialect/vectorSqlDialect.js +2 -2
  18. package/dist/entity/index.d.ts +1 -1
  19. package/dist/entity/index.js +1 -1
  20. package/dist/entity/metadata/definition.d.ts +16 -1
  21. package/dist/entity/metadata/definition.js +26 -1
  22. package/dist/index.d.ts +2 -1
  23. package/dist/index.js +2 -1
  24. package/dist/mariadb/mariadbQuerier.d.ts +5 -2
  25. package/dist/mariadb/mariadbQuerier.js +5 -10
  26. package/dist/migrate/ddl/defaultSql.js +1 -1
  27. package/dist/migrate/ddl/indexDdl.d.ts +3 -3
  28. package/dist/migrate/ddl/indexDdl.js +7 -7
  29. package/dist/migrate/ddl/mysqlIndexDdl.js +2 -2
  30. package/dist/migrate/ddl/tableDdl.js +2 -2
  31. package/dist/migrate/indexPredicate.d.ts +4 -3
  32. package/dist/migrate/indexPredicate.js +5 -5
  33. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +2 -6
  34. package/dist/migrate/schemaGenerator.js +1 -1
  35. package/dist/migrate/triggerSql.js +7 -5
  36. package/dist/mongodb/mongoDialect.js +17 -41
  37. package/dist/mongodb/mongoSchemaGenerator.js +12 -12
  38. package/dist/mongodb/mongodbQuerier.d.ts +4 -3
  39. package/dist/mongodb/mongodbQuerier.js +75 -102
  40. package/dist/mssql/mssqlDialect.js +2 -7
  41. package/dist/mssql/mssqlQuerier.d.ts +9 -3
  42. package/dist/mssql/mssqlQuerier.js +9 -11
  43. package/dist/mysql/mysql2Querier.d.ts +11 -2
  44. package/dist/mysql/mysql2Querier.js +4 -7
  45. package/dist/neon/index.d.ts +2 -0
  46. package/dist/neon/index.js +2 -0
  47. package/dist/neon/neonDialect.d.ts +7 -0
  48. package/dist/neon/neonDialect.js +8 -0
  49. package/dist/neon/neonQuerier.d.ts +26 -0
  50. package/dist/neon/neonQuerier.js +47 -0
  51. package/dist/neon/neonQuerierPool.d.ts +12 -2
  52. package/dist/neon/neonQuerierPool.js +22 -3
  53. package/dist/pglite/pgliteQuerier.d.ts +9 -5
  54. package/dist/pglite/pgliteQuerier.js +7 -11
  55. package/dist/postgres/pgExecution.d.ts +8 -0
  56. package/dist/postgres/pgExecution.js +3 -0
  57. package/dist/postgres/pgQuerier.d.ts +3 -6
  58. package/dist/postgres/pgQuerier.js +3 -7
  59. package/dist/querier/abstractQuerier.d.ts +24 -20
  60. package/dist/querier/abstractQuerier.js +79 -58
  61. package/dist/querier/abstractSqlQuerier.d.ts +42 -28
  62. package/dist/querier/abstractSqlQuerier.js +134 -116
  63. package/dist/querier/queryError.d.ts +2 -0
  64. package/dist/querier/queryError.js +9 -0
  65. package/dist/querier/transaction.js +2 -6
  66. package/dist/schema/canonicalType.d.ts +3 -3
  67. package/dist/schema/canonicalType.js +4 -10
  68. package/dist/sqlite/bindValues.d.ts +10 -0
  69. package/dist/sqlite/bindValues.js +8 -0
  70. package/dist/sqlite/hranaQuerier.d.ts +17 -11
  71. package/dist/sqlite/hranaQuerier.js +16 -5
  72. package/dist/sqlite/index.d.ts +1 -1
  73. package/dist/sqlite/index.js +0 -1
  74. package/dist/sqlite/localSqliteQuerierPool.js +19 -9
  75. package/dist/sqlite/sqliteQuerier.d.ts +9 -4
  76. package/dist/sqlite/sqliteQuerier.js +14 -8
  77. package/dist/turso/tursoSessionQuerier.d.ts +19 -7
  78. package/dist/turso/tursoSessionQuerier.js +31 -20
  79. package/dist/type/dialect.d.ts +3 -0
  80. package/dist/type/querier.d.ts +12 -0
  81. package/dist/type/querier.js +10 -0
  82. package/dist/type/vector.d.ts +2 -1
  83. package/dist/type/vector.js +2 -2
  84. package/dist/util/dialect.util.d.ts +21 -6
  85. package/dist/util/dialect.util.js +34 -9
  86. package/dist/util/filters.util.d.ts +5 -4
  87. package/dist/util/filters.util.js +4 -7
  88. package/dist/util/logger.js +2 -6
  89. package/dist/util/object.util.d.ts +7 -0
  90. package/dist/util/object.util.js +17 -0
  91. package/dist/util/query.util.d.ts +3 -2
  92. package/dist/util/sql.js +1 -1
  93. package/dist/util/sql.util.d.ts +15 -15
  94. package/dist/util/sql.util.js +5 -5
  95. package/package.json +7 -7
  96. package/skills/uql-orm/SKILL.md +58 -51
  97. package/dist/sqlite/abstractSqliteQuerier.d.ts +0 -28
  98. 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,83 @@ 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));
100
+ }
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();
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
+ });
128
+ }
129
+ /** Runs `task` on the connection, connected, after everything queued before it. */
130
+ onConnection(task) {
131
+ return this.serialize(() => this.lazyConnect().then(task));
132
+ }
133
+ /** The statement `build` writes, refused past the bind budget before the driver fails it. */
134
+ bound(build) {
135
+ const { sql, values } = this.dialect.compile(build);
136
+ this.assertBindBudget(values);
137
+ return { sql, values };
103
138
  }
104
139
  /** Refused before the driver fails it, or PGlite answers it and every read after it wrong. */
105
140
  assertBindBudget(values) {
106
- const { maxBindValues, dialectName } = this.dialect;
141
+ const { maxBindValues, engineName } = this.dialect;
107
142
  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`);
143
+ throw new UqlUsageError(`a statement binding ${values.length} values is past the ${maxBindValues} ${engineName} takes; split the list it binds`);
109
144
  }
110
145
  }
111
- /** The rows of a statement the dialect builds. */
112
- query(build) {
113
- return this.send(build, (sql, values) => this.internalAll(sql, values));
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;
114
150
  }
115
- /** Runs a statement the dialect builds. */
116
- exec(build) {
117
- return this.send(build, (sql, values) => this.internalRun(sql, values));
118
- }
119
- /** Builds a statement and sends it on the connection, in turn, timed and its failure tagged with it. */
120
- async send(build, task) {
121
- const { sql, values } = this.dialect.compile(build);
122
- this.assertBindBudget(values);
123
- return this.serialize(async () => {
124
- await this.lazyConnect();
125
- return this.timed(sql, values, () => task(sql, values));
126
- });
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);
127
155
  }
128
156
  /**
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.
157
+ * The `SET`s tuning an ANN index for the query, leading its read, refused where they would apply to nothing: a
158
+ * `SET LOCAL` outside a transaction. None for a query with no vector search, or on a field with no ANN index,
159
+ * which then demands no transaction either.
131
160
  */
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(...)`);
161
+ vectorTuning(entity, q) {
162
+ if (q.$candidates === undefined) {
163
+ return [];
142
164
  }
143
- for (const statement of statements) {
144
- await this.internalRun(statement);
165
+ const statements = this.dialect.vectorTuningStatements(getMeta(entity), q);
166
+ if (statements.length && this.dialect.features.vectorTuningNeedsTransaction && !this.scopeHere()) {
167
+ throw new UqlUsageError(`$candidates requires an open transaction on ${this.dialect.engineName}; run the query inside pool.transaction(...)`);
145
168
  }
169
+ return statements.map((sql) => ({ sql, values: [] }));
146
170
  }
147
171
  async internalFindMany(entity, q, opts) {
148
172
  return this.selectRows(entity, q, opts);
@@ -170,36 +194,33 @@ export class AbstractSqlQuerier extends AbstractQuerier {
170
194
  }
171
195
  return [rows, total];
172
196
  }
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));
197
+ /** The rows a read of `entity` matches, each as its statement reads it, the vector search's tuning leading it. */
198
+ selectRows(entity, q, opts, totalAlias) {
199
+ const tuning = this.vectorTuning(entity, q);
200
+ return this.readRows((ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias), 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 = []) {
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]);
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.
194
214
  */
195
215
  async *internalFindManyStream(entity, q, opts) {
196
216
  const ctx = this.dialect.createContext();
197
217
  const read = rowReader(this.dialect.find(ctx, entity, q, opts));
198
218
  this.assertBindBudget(ctx.values);
199
- if (q.$candidates !== undefined) {
200
- await this.applyVectorTuning(entity, q);
201
- }
219
+ const tuning = this.vectorTuning(entity, q);
202
220
  await this.lazyConnect();
221
+ for (const { sql } of tuning) {
222
+ await this.timed(sql, undefined, () => this.execute(sql));
223
+ }
203
224
  for await (const row of this.timedStream(ctx.sql, ctx.values, this.internalStream(ctx.sql, ctx.values))) {
204
225
  yield read(row);
205
226
  }
@@ -211,10 +232,10 @@ export class AbstractSqlQuerier extends AbstractQuerier {
211
232
  */
212
233
  async *internalStream(query, values) {
213
234
  if (!this.dialect.features.serverSideCursors) {
214
- yield* await this.internalAll(query, values);
235
+ yield* (await this.execute(query, values)).rows;
215
236
  return;
216
237
  }
217
- yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, !!this.scopeHere());
238
+ yield* streamViaCursor(async (sql, params) => (await this.execute(sql, params)).rows, query, values, !!this.scopeHere());
218
239
  }
219
240
  /**
220
241
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
@@ -222,7 +243,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
222
243
  * as 0; no row is 0 too, since a catalog that does not know the table answers with none.
223
244
  */
224
245
  async runCount(build) {
225
- const [row] = await this.query(build);
246
+ const [row] = await this.rowsOf(build);
226
247
  return row ? Number(row[AGGREGATE_VALUE_ALIAS]) : 0;
227
248
  }
228
249
  async internalCount(entity, q, opts) {
@@ -239,14 +260,13 @@ export class AbstractSqlQuerier extends AbstractQuerier {
239
260
  // What comes back is one column's value, so nothing is read back for a composite: its rows
240
261
  // already carry every column of it. `sole` is what keeps every id path off such a key.
241
262
  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);
263
+ const sole = soleId(meta);
264
+ const generatedKey = !!sole && isAutoIncrement(sole.field, true);
245
265
  // Per group, not per batch: the two carry different columns - one names the key, one does not - so a budget
246
266
  // taken over their union would under-fill the statement that is missing one. Header ids are only sound where
247
267
  // every row of a statement left its key to the database, so a supplied id cannot void the others.
248
268
  const statements = partitionBySuppliedId(rows, idKey).flatMap((group) => {
249
- const idsReliable = sole &&
269
+ const idsReliable = !!sole &&
250
270
  (this.dialect.insertIdSource === 'returning' ||
251
271
  (generatedKey && group.every((index) => rows[index][idKey] === undefined)));
252
272
  const { maxBindValues, maxInsertRows } = this.dialect;
@@ -261,21 +281,22 @@ export class AbstractSqlQuerier extends AbstractQuerier {
261
281
  statements.some(({ indexes, idsReliable }) => idsReliable && indexes.length > 1)) {
262
282
  this.#insertIdIncrement ??= await this.loadInsertIdIncrement();
263
283
  }
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
- }
284
+ const results = await this.runStatements(statements.map(({ indexes }) => {
285
+ const statementRows = indexes.map((index) => rows[index]);
286
+ return this.bound((ctx) => this.dialect.insert(ctx, entity, statementRows));
287
+ }), statements.length > 1);
288
+ results.forEach((result, at) => {
289
+ const { indexes, idsReliable } = statements[at];
290
+ if (idsReliable) {
291
+ const { ids = [] } = this.updateResultOf(result);
292
+ indexes.forEach((index, position) => {
293
+ rows[index][idKey] ??= ids[position];
294
+ });
273
295
  }
274
- };
275
- await (statements.length > 1 ? this.atomically(insert) : insert());
296
+ });
276
297
  }
277
298
  async internalUpdateMany(entity, q, payload, opts) {
278
- const { changes = 0 } = await this.exec((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
299
+ const { changes = 0 } = await this.changesOf((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
279
300
  return changes;
280
301
  }
281
302
  /** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
@@ -302,46 +323,43 @@ export class AbstractSqlQuerier extends AbstractQuerier {
302
323
  // One statement per shape, each split again to fit the bind budget, less what its assignments bind once.
303
324
  // Grouping first is what makes that one figure: every row of a group carries the same columns. No row cap:
304
325
  // 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);
326
+ const groups = groupByInsertShape(meta, payload).flatMap((group) => {
327
+ const { binds, assigns } = this.dialect.upsertAssignments(entity, conflictPaths, payload[group[0]], update);
328
+ const chunks = chunkWithinLimits(meta, payload, group, this.dialect.maxBindValues - binds);
329
+ // `reports`: the statement answers each row's id in order, which spares the read back.
330
+ return chunks.map((indexes) => ({
331
+ indexes,
332
+ reports: assigns && this.dialect.upsertReportsIds(meta, indexes.length),
333
+ }));
308
334
  });
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
- }
335
+ // Asked first: the statement fills an `onInsert` key into these rows whether it inserts them or not.
336
+ const kept = payload.map((row) => upsertKeepsOwnKey(meta, conflictPaths, row));
337
+ const statements = groups.map(({ indexes }) => this.bound((ctx) => this.dialect.upsert(ctx, entity, conflictPaths, indexes.map((index) => payload[index]), update)));
338
+ const results = await this.runStatements(statements, groups.length > 1);
339
+ // Placed by index, since grouping by shape reorders the rows. A statement reporting fewer ids than it
340
+ // wrote places none.
341
+ const ids = new Array(payload.length);
342
+ groups.forEach(({ indexes, reports }, group) => {
343
+ const reported = reports ? this.reportedIds(results[group]) : [];
344
+ if (reported.length === indexes.length) {
345
+ indexes.forEach((index, position) => {
346
+ ids[index] = reported[position];
347
+ });
324
348
  }
325
- return ids;
326
349
  });
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;
350
+ // Where the statement cannot report every row's id in order (see `upsertReportsIds`), or assigns a found row
351
+ // nothing, `DO NOTHING`, which skips it, the ids are read back by the conflict columns.
352
+ return this.withUnreportedIds(entity, conflictPaths, payload, ids, kept);
353
+ }
354
+ /** The ids an upsert reports of its rows: its `RETURNING` rows' in order, or its one row's in the header. */
355
+ reportedIds(result) {
356
+ if (result.rows.length) {
357
+ return this.updateResultOf(result).ids ?? [];
337
358
  }
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;
359
+ return result.id ? [result.id] : [];
342
360
  }
343
361
  async internalDeleteMany(entity, q, opts) {
344
- const { changes = 0 } = await this.exec((ctx) => this.dialect.delete(ctx, entity, q, opts));
362
+ const { changes = 0 } = await this.changesOf((ctx) => this.dialect.delete(ctx, entity, q, opts));
345
363
  return changes;
346
364
  }
347
365
  async openTransaction(opts) {
@@ -392,7 +410,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
392
410
  /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
393
411
  async runTransactionCommand(sql) {
394
412
  try {
395
- await this.internalRun(sql);
413
+ await this.execute(sql);
396
414
  }
397
415
  catch (err) {
398
416
  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
1
  import { asyncScope } from '../context/context.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';
@@ -28,18 +28,28 @@ export function extendSqlite(db, extensions = []) {
28
28
  for (const extension of extensions) {
29
29
  db.loadExtension(extension);
30
30
  }
31
- db.function?.('regexp', { deterministic: true }, regexp);
31
+ db.function?.('regexp', { deterministic: true }, regexp());
32
32
  return db;
33
33
  }
34
34
  const CASELESS_FLAG = '(?i)';
35
- /** `value REGEXP pattern`: NULL where the value is, as an operator answers; a leading `(?i)` folds case, as other engines read it. */
36
- function regexp(pattern, value) {
37
- if (value === null) {
38
- return null;
39
- }
40
- const source = String(pattern);
41
- const caseless = source.startsWith(CASELESS_FLAG);
42
- return Number(new RegExp(caseless ? source.slice(CASELESS_FLAG.length) : source, caseless ? 'i' : '').test(String(value)));
35
+ /**
36
+ * `value REGEXP pattern`: NULL where the value is, as an operator answers; a leading `(?i)` folds case, as other
37
+ * engines read it. The last pattern stays compiled, since a statement tests every row against the same one.
38
+ */
39
+ function regexp() {
40
+ let last;
41
+ return (pattern, value) => {
42
+ if (value === null) {
43
+ return null;
44
+ }
45
+ const text = String(pattern);
46
+ if (last?.pattern !== text) {
47
+ const caseless = text.startsWith(CASELESS_FLAG);
48
+ const compiled = new RegExp(caseless ? text.slice(CASELESS_FLAG.length) : text, caseless ? 'i' : '');
49
+ last = { pattern: text, compiled };
50
+ }
51
+ return Number(last.compiled.test(String(value)));
52
+ };
43
53
  }
44
54
  /** A pool for a database file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
45
55
  export class AbstractLocalSqliteQuerierPool extends AbstractSharedHandleQuerierPool {