uql-orm 0.107.3 → 0.108.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 (89) hide show
  1. package/dist/browser/uql-browser.min.js +2 -2
  2. package/dist/browser/uql-browser.min.js.map +5 -5
  3. package/dist/cockroachdb/cockroachDialect.d.ts +1 -4
  4. package/dist/cockroachdb/cockroachDialect.js +1 -5
  5. package/dist/dialect/abstractSqlDialect.d.ts +84 -43
  6. package/dist/dialect/abstractSqlDialect.js +270 -192
  7. package/dist/dialect/aliases.d.ts +2 -0
  8. package/dist/dialect/aliases.js +2 -0
  9. package/dist/dialect/jsonSql.d.ts +9 -7
  10. package/dist/dialect/jsonSql.js +16 -10
  11. package/dist/dialect/mergeSqlDialect.d.ts +5 -7
  12. package/dist/dialect/mergeSqlDialect.js +20 -19
  13. package/dist/dialect/mysqlLikeSqlDialect.d.ts +12 -6
  14. package/dist/dialect/mysqlLikeSqlDialect.js +34 -12
  15. package/dist/dialect/operators.d.ts +7 -1
  16. package/dist/dialect/operators.js +37 -2
  17. package/dist/dialect/pgLikeSqlDialect.d.ts +4 -4
  18. package/dist/dialect/pgLikeSqlDialect.js +8 -7
  19. package/dist/entity/index.d.ts +1 -1
  20. package/dist/entity/index.js +1 -1
  21. package/dist/entity/metadata/definedFixture/author.d.ts +4 -4
  22. package/dist/entity/metadata/definedFixture/book.d.ts +5 -5
  23. package/dist/entity/metadata/definition.d.ts +2 -0
  24. package/dist/entity/metadata/definition.js +19 -11
  25. package/dist/index.d.ts +1 -1
  26. package/dist/index.js +1 -1
  27. package/dist/mariadb/mariaDialect.d.ts +2 -2
  28. package/dist/mariadb/mariaDialect.js +3 -2
  29. package/dist/migrate/codegen/fieldOptionsSource.js +28 -7
  30. package/dist/migrate/ddl/defaultSql.d.ts +3 -2
  31. package/dist/migrate/ddl/defaultSql.js +8 -12
  32. package/dist/migrate/ddl/mysqlTableDdl.js +1 -1
  33. package/dist/migrate/ddl/tableDdl.d.ts +1 -1
  34. package/dist/migrate/drift/driftDetector.js +10 -3
  35. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +2 -2
  36. package/dist/migrate/introspection/mssqlIntrospector.d.ts +2 -2
  37. package/dist/migrate/introspection/mysqlIntrospector.d.ts +2 -2
  38. package/dist/migrate/introspection/postgresIntrospector.d.ts +2 -2
  39. package/dist/migrate/introspection/sqliteIntrospector.d.ts +2 -2
  40. package/dist/migrate/migrator.js +2 -1
  41. package/dist/migrate/schemaChange.d.ts +0 -2
  42. package/dist/migrate/schemaChange.js +1 -4
  43. package/dist/migrate/schemaGenerator.d.ts +2 -2
  44. package/dist/migrate/triggerSql.js +11 -15
  45. package/dist/mongodb/mongoDialect.d.ts +6 -1
  46. package/dist/mongodb/mongoDialect.js +90 -46
  47. package/dist/mongodb/mongoSchemaGenerator.js +2 -2
  48. package/dist/mongodb/mongodbQuerier.d.ts +7 -9
  49. package/dist/mongodb/mongodbQuerier.js +54 -47
  50. package/dist/mssql/mssqlDialect.d.ts +9 -9
  51. package/dist/mssql/mssqlDialect.js +51 -28
  52. package/dist/mssql/mssqlWireTypes.d.ts +1 -4
  53. package/dist/mssql/mssqlWireTypes.js +19 -10
  54. package/dist/querier/abstractQuerier.d.ts +53 -29
  55. package/dist/querier/abstractQuerier.js +154 -102
  56. package/dist/querier/abstractSqlQuerier.d.ts +41 -10
  57. package/dist/querier/abstractSqlQuerier.js +145 -79
  58. package/dist/schema/declaredColumn.js +2 -2
  59. package/dist/schema/schemaASTDiffer.d.ts +3 -3
  60. package/dist/schema/sqlExpression.d.ts +7 -5
  61. package/dist/schema/sqlExpression.js +20 -16
  62. package/dist/schema/types.d.ts +8 -2
  63. package/dist/sqlite/sqliteDialect.js +1 -2
  64. package/dist/type/definedEntity.d.ts +5 -5
  65. package/dist/type/dialect.d.ts +26 -15
  66. package/dist/type/entity.d.ts +14 -8
  67. package/dist/type/query.d.ts +7 -2
  68. package/dist/type/queryAggregate.d.ts +4 -4
  69. package/dist/type/querySql.d.ts +4 -1
  70. package/dist/type/querySql.js +5 -1
  71. package/dist/type/queryWhere.d.ts +16 -11
  72. package/dist/type/universalQuerier.d.ts +7 -7
  73. package/dist/util/ddlExpression.util.d.ts +5 -0
  74. package/dist/util/ddlExpression.util.js +9 -2
  75. package/dist/util/dialect.util.d.ts +14 -6
  76. package/dist/util/dialect.util.js +17 -13
  77. package/dist/util/field.util.d.ts +12 -0
  78. package/dist/util/field.util.js +17 -1
  79. package/dist/util/fieldOption.util.js +5 -1
  80. package/dist/util/object.util.d.ts +4 -0
  81. package/dist/util/object.util.js +13 -0
  82. package/dist/util/query.util.d.ts +5 -3
  83. package/dist/util/query.util.js +7 -2
  84. package/dist/util/sql.d.ts +25 -7
  85. package/dist/util/sql.js +58 -18
  86. package/dist/util/triggerWrite.d.ts +7 -4
  87. package/dist/util/triggerWrite.js +5 -4
  88. package/package.json +1 -1
  89. package/skills/uql-orm/SKILL.md +10 -8
@@ -1,7 +1,7 @@
1
1
  import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
2
2
  import { getMeta } from '../entity/index.js';
3
- import { generatesKey, soleId } from '../entity/metadata/definition.js';
4
- import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, upsertKeepsOwnKey, } from '../util/index.js';
3
+ import { generatesKey, idOf, namesEvery, namesKey, soleId } from '../entity/metadata/definition.js';
4
+ import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, upsertKeepsOwnKey, getKeys, rowKey, } from '../util/index.js';
5
5
  import { statementOf } from '../util/sql.js';
6
6
  import { UqlUsageError } from '../util/uqlError.js';
7
7
  import { AbstractQuerier } from './abstractQuerier.js';
@@ -27,18 +27,7 @@ function partitionBySuppliedId(payload, idKey) {
27
27
  * assignment list for the whole statement, so rows of different shapes cannot share one at all.
28
28
  */
29
29
  function groupByInsertShape(meta, payload) {
30
- const groups = new Map();
31
- for (let index = 0; index < payload.length; index++) {
32
- const shape = insertShapeOf(meta, payload[index]);
33
- const group = groups.get(shape);
34
- if (group) {
35
- group.push(index);
36
- }
37
- else {
38
- groups.set(shape, [index]);
39
- }
40
- }
41
- return [...groups.values()];
30
+ return [...Map.groupBy(payload.keys(), (index) => insertShapeOf(meta, payload[index])).values()];
42
31
  }
43
32
  /**
44
33
  * A group's row indexes split into statements of at most `maxRows` rows within the bind budget, payload order kept,
@@ -55,6 +44,24 @@ function chunkWithinLimits(meta, payload, group, maxBindValues, maxRows = Infini
55
44
  // A split can leave a chunk whose rows name no column; one chunk is the whole group, which names some.
56
45
  return chunks.length === 1 ? chunks : chunks.flatMap((indexes) => (width(indexes) ? [indexes] : chunk(indexes, 1)));
57
46
  }
47
+ /** Orders keys the engine generated by the order it numbered them in, a key past 2^53 decoded as its text included. */
48
+ function byGeneratedKey(a, b) {
49
+ return typeof a === 'number' && typeof b === 'number' ? a - b : Number(BigInt(String(a)) - BigInt(String(b)));
50
+ }
51
+ /**
52
+ * `reported`, the rows an insert of `rows` answered, in the order of `rows`: by key where each names its own, else
53
+ * ascending by the key the engine generated, which it numbers in the order the rows are listed. Never in the order
54
+ * the engine answers them, which none promises. A key it defaults otherwise, `.default(uuid)`, orders nothing: such
55
+ * rows are written one per statement.
56
+ */
57
+ function inPayloadOrder(meta, rows, reported) {
58
+ if (rows.every((row) => namesKey(meta, row))) {
59
+ const byKey = new Map(reported.map((row) => [rowKey(row, meta.ids), row]));
60
+ return rows.map((row) => byKey.get(rowKey(row, meta.ids)));
61
+ }
62
+ const [idKey] = meta.ids;
63
+ return generatesKey(meta) ? reported.toSorted((a, b) => byGeneratedKey(a[idKey], b[idKey])) : reported;
64
+ }
58
65
  export class AbstractSqlQuerier extends AbstractQuerier {
59
66
  dialect;
60
67
  extra;
@@ -130,6 +137,13 @@ export class AbstractSqlQuerier extends AbstractQuerier {
130
137
  onConnection(task) {
131
138
  return this.serialize(() => this.lazyConnect().then(task));
132
139
  }
140
+ /** The read `build` writes, bound as {@link bound} binds a statement, with the terms its rows are read as. */
141
+ boundRead(build) {
142
+ const ctx = this.dialect.createContext();
143
+ const terms = build(ctx);
144
+ this.assertBindBudget(ctx.values);
145
+ return [{ sql: ctx.sql, values: ctx.values }, terms];
146
+ }
133
147
  /** The statement `build` writes, refused past the bind budget before the driver fails it. */
134
148
  bound(build) {
135
149
  const { sql, values } = this.dialect.compile(build);
@@ -199,15 +213,21 @@ export class AbstractSqlQuerier extends AbstractQuerier {
199
213
  const build = (ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias);
200
214
  return this.readRows(build, tuning, this.tunedInTransaction(tuning));
201
215
  }
202
- /** The rows of a statement the dialect builds, each as the terms it returns say, after the `leading` ones. */
216
+ /**
217
+ * The rows of a statement the dialect builds, each as the terms it returns say, after the `leading` ones. Every read
218
+ * takes it, so it builds no list {@link readEach} would: measured in `pgAllocation.test.ts`.
219
+ */
203
220
  async readRows(build, leading = [], atomic = false) {
204
- let terms = [];
205
- const statement = this.bound((ctx) => {
206
- terms = build(ctx);
207
- });
221
+ const [statement, terms] = this.boundRead(build);
208
222
  const results = await this.runStatements([...leading, statement], atomic);
209
223
  return results[leading.length].rows.map(rowReader(terms));
210
224
  }
225
+ /** The rows of each statement the dialect builds, read as its terms say, all or none where two or more. */
226
+ async readEach(builds) {
227
+ const reads = builds.map((build) => this.boundRead(build));
228
+ const results = await this.runStatements(reads.map(([statement]) => statement), reads.length > 1);
229
+ return results.map((result, at) => result.rows.map(rowReader(reads[at][1])));
230
+ }
211
231
  /**
212
232
  * The one read not going through `runStatements`: it holds the connection for its loop, so it checks its budget
213
233
  * and connects on its own, its values going as the context holds them, each normalized as it was bound. Tuning
@@ -266,19 +286,14 @@ export class AbstractSqlQuerier extends AbstractQuerier {
266
286
  const [idKey] = meta.ids;
267
287
  const sole = soleId(meta);
268
288
  const generatedKey = generatesKey(meta);
269
- // Per group, not per batch: the two carry different columns - one names the key, one does not - so a budget
270
- // taken over their union would under-fill the statement that is missing one. Header ids are only sound where
271
- // every row of a statement left its key to the database, so a supplied id cannot void the others.
272
- const statements = partitionBySuppliedId(rows, idKey).flatMap((group) => {
273
- const idsReliable = !!sole &&
274
- (this.dialect.insertIdSource === 'returning' ||
275
- (generatedKey && group.every((index) => rows[index][idKey] === undefined)));
276
- const { maxBindValues, maxInsertRows } = this.dialect;
277
- return chunkWithinLimits(meta, rows, group, maxBindValues, maxInsertRows).map((indexes) => ({
278
- indexes,
279
- idsReliable,
280
- }));
281
- });
289
+ // Only a statement whose every row left its key to the database needs its ids, which a supplied one would void
290
+ // in a header: a `RETURNING` reports them all, a header only a generated key's.
291
+ const statements = this.insertChunks(meta, rows).map((indexes) => ({
292
+ indexes,
293
+ idsReliable: !!sole &&
294
+ indexes.every((index) => rows[index][idKey] === undefined) &&
295
+ (this.dialect.insertIdSource === 'returning' || generatedKey),
296
+ }));
282
297
  // Inferring multiple ids from the single header id (MySQL) assumes a known stride; a clustered
283
298
  // server may set `auto_increment_increment` > 1, so probe it (once, cached) before inferring.
284
299
  if (this.dialect.insertIdSource === 'firstId' &&
@@ -293,74 +308,125 @@ export class AbstractSqlQuerier extends AbstractQuerier {
293
308
  const { indexes, idsReliable } = statements[at];
294
309
  if (idsReliable) {
295
310
  const { ids } = this.updateResultOf(result);
311
+ // Ascending, as the engine numbered the rows, whatever order its `RETURNING` lists them in.
312
+ if (generatedKey && ids.some((id, position) => position && byGeneratedKey(ids[position - 1], id) > 0)) {
313
+ ids.sort(byGeneratedKey);
314
+ }
296
315
  indexes.forEach((index, position) => {
297
- rows[index][idKey] ??= ids[position];
316
+ rows[index][idKey] = ids[position];
298
317
  });
299
318
  }
300
319
  });
301
320
  }
321
+ /**
322
+ * The statements an insert of `rows` takes, as the indexes of the rows each writes. Grouped by whether a row names
323
+ * its key, as the two carry different columns: a budget taken over their union would under-fill the statement
324
+ * missing one. One row per statement where its `RETURNING` reports a key nothing orders, as {@link inPayloadOrder} says.
325
+ */
326
+ insertChunks(meta, rows) {
327
+ const { maxBindValues, maxInsertRows, insertIdSource } = this.dialect;
328
+ const unordered = (row) => insertIdSource === 'returning' && !!soleId(meta) && !generatesKey(meta) && !namesKey(meta, row);
329
+ return partitionBySuppliedId(rows, meta.ids[0]).flatMap((group) => chunkWithinLimits(meta, rows, group, maxBindValues, unordered(rows[group[0]]) ? 1 : maxInsertRows));
330
+ }
331
+ /** Inserts `rows`, reporting each, in their order, with the fields `keys` names, off its own `RETURNING`, and placing its key on it. */
332
+ async insertedRows(entity, rows, keys) {
333
+ const meta = getMeta(entity);
334
+ const chunks = this.insertChunks(meta, rows);
335
+ const read = await this.readEach(chunks.map((indexes) => (ctx) => this.dialect.insert(ctx, entity, indexes.map((index) => rows[index]), keys)));
336
+ const reported = new Array(rows.length);
337
+ read.forEach((statementRows, at) => {
338
+ const indexes = chunks[at];
339
+ const placed = inPayloadOrder(meta, indexes.map((index) => rows[index]), statementRows).filter((row) => row !== undefined);
340
+ if (placed.length !== indexes.length) {
341
+ throw new UqlUsageError(`${this.dialect.engineName} reported ${placed.length} of the ${indexes.length} '${entity.name}' rows its insert wrote`);
342
+ }
343
+ placed.forEach((row, position) => {
344
+ reported[indexes[position]] = row;
345
+ });
346
+ });
347
+ rows.forEach((row, index) => {
348
+ for (const key of meta.ids) {
349
+ row[key] ??= reported[index][key];
350
+ }
351
+ });
352
+ return reported;
353
+ }
302
354
  async internalUpdateMany(entity, q, payload, opts) {
303
355
  const { changes } = await this.changesOf((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
304
356
  return changes;
305
357
  }
306
- /** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
307
- get writesReturning() {
308
- return this.dialect.features.writeReturning ? this.#returningWrites : undefined;
309
- }
310
- #returningWrites = {
311
- update: (entity, q, payload, opts, keys) => this.reportedRows(entity, keys, (ctx) => this.dialect.update(ctx, entity, q, payload, opts)),
312
- delete: (entity, q, opts, keys) => this.reportedRows(entity, keys, (ctx) => this.dialect.delete(ctx, entity, q, opts)),
358
+ /** The writes reading their rows off their own statement, where {@link AbstractSqlDialect.reportsWrite} says so. */
359
+ reportingWrites(meta, write) {
360
+ return this.dialect.reportsWrite(meta, write) ? this.#reportingWrites : undefined;
361
+ }
362
+ #reportingWrites = {
363
+ update: (entity, q, payload, opts, keys) => this.readRows((ctx) => this.dialect.update(ctx, entity, q, payload, opts, keys)),
364
+ delete: (entity, q, opts, keys) => this.readRows((ctx) => this.dialect.delete(ctx, entity, q, opts, keys)),
365
+ upsert: (entity, q, payload, update, keys) => {
366
+ const nullKey = getKeys(q.$conflict).find((key) => payload.some((row) => row[key] === null));
367
+ if (nullKey !== undefined) {
368
+ throw new UqlUsageError(`a row's '${nullKey}' is null: no row reads back by it, so its upsert cannot report it`);
369
+ }
370
+ return this.upsertedRows(entity, q, clone(payload), update, keys);
371
+ },
372
+ insert: (entity, rows, keys) => this.insertedRows(entity, rows, keys),
313
373
  };
314
- /** The rows the write `build` renders reports, `RETURNING` the fields `keys` names. */
315
- reportedRows(entity, keys, build) {
316
- return this.readRows((ctx) => {
317
- build(ctx);
318
- return this.dialect.returning(ctx, entity, keys);
319
- });
320
- }
321
- async internalUpsertMany(entity, conflictPaths, payload, update) {
374
+ /**
375
+ * The id each row got: off the upsert's `RETURNING` where it has one, else off the header. A row reported none of,
376
+ * skipped by `DO NOTHING` or its `$where`, is read back by its conflict keys, unless it keeps its own key (`kept`,
377
+ * asked before the statement fills `onInsert` keys in).
378
+ */
379
+ async internalUpsertMany(entity, q, payload, update) {
322
380
  if (!payload.length) {
323
381
  return [];
324
382
  }
325
383
  payload = clone(payload);
326
384
  const meta = getMeta(entity);
327
- // One statement per shape, each split again to fit the bind budget, less what its assignments bind once.
328
- // Grouping first is what makes that one figure: every row of a group carries the same columns. No row cap:
329
- // the one engine with one, SQL Server, upserts through a MERGE, whose source takes any number.
330
- const groups = groupByInsertShape(meta, payload).flatMap((group) => {
331
- const { binds, assigns } = this.dialect.upsertAssignments(entity, conflictPaths, payload[group[0]], update);
385
+ const kept = payload.map((row) => upsertKeepsOwnKey(meta, q.$conflict, row));
386
+ const ids = this.dialect.features.reportsWrites.includes('upsert')
387
+ ? (await this.upsertedRows(entity, q, payload, update, [...meta.ids, ...getKeys(q.$conflict)])).map((row) => row && idOf(meta, row))
388
+ : await this.headerIds(entity, q, payload, update);
389
+ return this.withUnreportedIds(entity, q.$conflict, payload, ids, kept);
390
+ }
391
+ /** The ids an upsert's header reports, by index: a statement of one row assigning a found row names its key. */
392
+ async headerIds(entity, q, payload, update) {
393
+ const groups = this.upsertGroups(entity, q, payload, update);
394
+ const results = await this.runStatements(groups.map(({ indexes }) => this.bound((ctx) => this.dialect.upsert(ctx, entity, q, indexes.map((index) => payload[index]), update))), groups.length > 1);
395
+ const ids = new Array(payload.length);
396
+ groups.forEach(({ indexes, reports }, group) => {
397
+ if (reports && results[group].id) {
398
+ ids[indexes[0]] = results[group].id;
399
+ }
400
+ });
401
+ return ids;
402
+ }
403
+ /**
404
+ * The rows of `payload` an upsert writes, in its order, with the fields `keys` names, off its `RETURNING`: matched by
405
+ * the conflict keys `keys` includes, as no engine promises that order. `undefined` for a row it kept, or with no
406
+ * conflict key. The statement fills `payload`'s `onInsert` fields.
407
+ */
408
+ async upsertedRows(entity, q, payload, update, keys) {
409
+ const conflictKeys = getKeys(q.$conflict);
410
+ const read = await this.readEach(this.upsertGroups(entity, q, payload, update).map(({ indexes }) => (ctx) => this.dialect.upsert(ctx, entity, q, indexes.map((index) => payload[index]), update, keys)));
411
+ const written = new Map(read.flat().map((row) => [rowKey(row, conflictKeys), row]));
412
+ return payload.map((row) => namesEvery(row, conflictKeys) ? written.get(rowKey(row, conflictKeys)) : undefined);
413
+ }
414
+ /**
415
+ * An upsert's statements: one per shape, each split again to fit the bind budget, less what its assignments bind
416
+ * once. Grouping first is what makes that one figure: every row of a group carries the same columns. No row cap:
417
+ * the one engine with one, SQL Server, upserts through a MERGE, whose source takes any number. `reports`: the
418
+ * statement's header names its row's id, which spares the read back.
419
+ */
420
+ upsertGroups(entity, q, payload, update) {
421
+ const meta = getMeta(entity);
422
+ return groupByInsertShape(meta, payload).flatMap((group) => {
423
+ const { binds, assigns } = this.dialect.upsertAssignments(entity, q, payload[group[0]], update);
332
424
  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
425
  return chunks.map((indexes) => ({
335
426
  indexes,
336
427
  reports: assigns && this.dialect.upsertReportsIds(meta, indexes.length),
337
428
  }));
338
429
  });
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
- });
352
- }
353
- });
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;
362
- }
363
- return result.id ? [result.id] : [];
364
430
  }
365
431
  async internalDeleteMany(entity, q, opts) {
366
432
  const { changes } = await this.changesOf((ctx) => this.dialect.delete(ctx, entity, q, opts));
@@ -1,4 +1,4 @@
1
- import { declaresNotNull, isAutoIncrement } from '../util/field.util.js';
1
+ import { declaresNotNull, fieldFamily, isAutoIncrement } from '../util/field.util.js';
2
2
  import { resolveColumnCanonicalType } from './canonicalType.js';
3
3
  import { schemaDefault } from './sqlExpression.js';
4
4
  /**
@@ -10,7 +10,7 @@ export function declaredColumn(field, { name, soleKey, compile, }) {
10
10
  name,
11
11
  type: resolveColumnCanonicalType(field),
12
12
  nullable: !declaresNotNull(field),
13
- defaultValue: schemaDefault(field.defaultValue, compile),
13
+ defaultValue: schemaDefault(field.defaultValue, compile, fieldFamily(field) === 'json'),
14
14
  isPrimaryKey: field.isId === true,
15
15
  isAutoIncrement: isAutoIncrement(field, soleKey),
16
16
  isUnique: field.unique ?? false,
@@ -1,6 +1,6 @@
1
1
  import type { ColumnRenames, Rename } from '../type/migration.js';
2
2
  import type { SchemaAST } from './schemaAST.js';
3
- import type { CanonicalType } from './types.js';
3
+ import type { CanonicalType, ColumnDefault } from './types.js';
4
4
  import type { ForeignKeyAction, RelationshipDiff, RelationshipNode, SchemaDiffResult, TableDiff, TableNode } from './types.js';
5
5
  /**
6
6
  * Options for schema diffing.
@@ -14,7 +14,7 @@ export interface DiffOptions {
14
14
  */
15
15
  normalizeType?: (type: CanonicalType) => CanonicalType;
16
16
  /** Whether two defaults are one value, as the dialect that reprinted them can tell: `'a'::character varying` is `'a'`. */
17
- defaultsEqual?: (expected: unknown, actual: unknown) => boolean;
17
+ defaultsEqual?: (expected: ColumnDefault | undefined, actual: ColumnDefault | undefined) => boolean;
18
18
  }
19
19
  /** The differences between the expected schema (the entities) and the actual one (the database). */
20
20
  export declare function diffSchemas(source: SchemaAST, target: SchemaAST, options?: DiffOptions): SchemaDiffResult;
@@ -54,4 +54,4 @@ export declare function referentialActions(rel: RelationshipNode): {
54
54
  * Compares two defaults exactly as written, for when no dialect renders them: SQL must match to the letter.
55
55
  * Migrations and drift use the generator's equality instead, which knows how its engine reprints SQL.
56
56
  */
57
- export declare function defaultsEqualAsWritten(expected: unknown, actual: unknown): boolean;
57
+ export declare function defaultsEqualAsWritten(expected: ColumnDefault | undefined, actual: ColumnDefault | undefined): boolean;
@@ -1,4 +1,5 @@
1
1
  import { QuerySql, type SqlValueName } from '../type/index.js';
2
+ import type { ColumnDefault } from './types.js';
2
3
  declare const EXPRESSION: unique symbol;
3
4
  /**
4
5
  * A column default that is SQL rather than a literal: a value uql exports by name, which each engine spells for the
@@ -24,12 +25,13 @@ export declare const SqlExpression: {
24
25
  export declare function sqlExpressionText(expression: SqlExpression): string;
25
26
  /**
26
27
  * A default in schema form: a value uql exports (`currentTimestamp`) becomes its kind, so each engine spells it
27
- * for the column it fills; other `raw` becomes the SQL `compile` renders, parenthesized; a literal is kept.
28
+ * for the column it fills; other `raw` the SQL `compile` renders, parenthesized; a document, or any value of a
29
+ * `json` column, its JSON text, which is how the database reports it back; another literal is kept.
28
30
  */
29
- export declare function schemaDefault(value: unknown, compile: (sql: QuerySql) => string): unknown;
31
+ export declare function schemaDefault(value: unknown, compile: (sql: QuerySql) => string, json?: boolean): ColumnDefault | undefined;
30
32
  /**
31
- * A default as text to compare: numbers as their digits, other text as written, and objects (SQL included) and text
32
- * holding a JSON object or list as JSON with its keys in order, equal as documents, since `jsonb` reprints them.
33
+ * A default as text to compare: numbers as their digits, other text as written, and SQL and text holding a JSON
34
+ * object or list as JSON with its keys in order, equal as documents, since `jsonb` reprints them.
33
35
  */
34
- export declare function writtenDefault(value: unknown): string;
36
+ export declare function writtenDefault(value: ColumnDefault): string;
35
37
  export {};
@@ -1,6 +1,7 @@
1
1
  import { QuerySql, SQL_VALUE_NAMES } from '../type/index.js';
2
- import { isRecord } from '../util/object.util.js';
2
+ import { byCodeUnit, isJsonScalar, isRecord, jsonDocument } from '../util/object.util.js';
3
3
  import { SQL_VALUES } from '../util/sql.js';
4
+ import { UqlUsageError } from '../util/uqlError.js';
4
5
  const EXPRESSION = Symbol('sqlExpression');
5
6
  export const SqlExpression = {
6
7
  named: (kind) => ({ [EXPRESSION]: true, kind }),
@@ -16,33 +17,36 @@ export function sqlExpressionText(expression) {
16
17
  const NAME_OF = new Map(SQL_VALUE_NAMES.map((name) => [SQL_VALUES[name], name]));
17
18
  /**
18
19
  * A default in schema form: a value uql exports (`currentTimestamp`) becomes its kind, so each engine spells it
19
- * for the column it fills; other `raw` becomes the SQL `compile` renders, parenthesized; a literal is kept.
20
+ * for the column it fills; other `raw` the SQL `compile` renders, parenthesized; a document, or any value of a
21
+ * `json` column, its JSON text, which is how the database reports it back; another literal is kept.
20
22
  */
21
- export function schemaDefault(value, compile) {
23
+ export function schemaDefault(value, compile, json = false) {
22
24
  const name = NAME_OF.get(value);
23
25
  if (name) {
24
26
  return SqlExpression.named(name);
25
27
  }
26
- return value instanceof QuerySql ? SqlExpression.parenthesized(compile(value)) : value;
28
+ if (value instanceof QuerySql) {
29
+ return SqlExpression.parenthesized(compile(value));
30
+ }
31
+ if (value === undefined || value === null || SqlExpression.isExpression(value)) {
32
+ return value;
33
+ }
34
+ if (typeof value === 'number' && !Number.isFinite(value)) {
35
+ throw new UqlUsageError(`a default cannot be ${value}: no SQL literal holds it`);
36
+ }
37
+ return !json && (isJsonScalar(value) || typeof value === 'bigint' || value instanceof Date)
38
+ ? value
39
+ : JSON.stringify(value);
27
40
  }
28
41
  /**
29
- * A default as text to compare: numbers as their digits, other text as written, and objects (SQL included) and text
30
- * holding a JSON object or list as JSON with its keys in order, equal as documents, since `jsonb` reprints them.
42
+ * A default as text to compare: numbers as their digits, other text as written, and SQL and text holding a JSON
43
+ * object or list as JSON with its keys in order, equal as documents, since `jsonb` reprints them.
31
44
  */
32
45
  export function writtenDefault(value) {
33
46
  const document = typeof value === 'string' ? jsonDocument(value) : value;
34
47
  return typeof document === 'object' && document !== null ? JSON.stringify(document, keysInOrder) : String(value);
35
48
  }
36
- /** What `text` spells as JSON, or nothing where it is no JSON at all. */
37
- function jsonDocument(text) {
38
- try {
39
- return JSON.parse(text);
40
- }
41
- catch {
42
- return undefined;
43
- }
44
- }
45
49
  /** A `JSON.stringify` replacer writing each object's keys in order. */
46
50
  function keysInOrder(_key, value) {
47
- return isRecord(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : 1))) : value;
51
+ return isRecord(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => byCodeUnit(a, b))) : value;
48
52
  }
@@ -1,5 +1,7 @@
1
1
  import type { Alteration, Change, ForeignKeySchema, IndexSchema, PrimaryKeySchema, StoredDefinition } from '../type/migration.js';
2
+ import type { JsonScalar } from '../type/utility.js';
2
3
  import type { IndexFacet } from './indexDifferences.js';
4
+ import type { SqlExpression } from './sqlExpression.js';
3
5
  /**
4
6
  * Type categories universal across SQL dialects.
5
7
  * These represent logical/semantic types, not specific SQL types.
@@ -70,6 +72,11 @@ export type RelationshipType = 'OneToOne' | 'OneToMany' | 'ManyToOne' | 'ManyToM
70
72
  */
71
73
  export declare const INDEX_TYPES: readonly ['btree', 'hash', 'gin', 'gist', 'brin', 'fulltext', 'hnsw', 'ivfflat', 'vector', 'vectorSearch'];
72
74
  export type IndexType = (typeof INDEX_TYPES)[number];
75
+ /**
76
+ * A column's default as the schema holds it, from either side: a literal, an object or a JSON column's
77
+ * value as the JSON text the catalogue reports, or an `SqlExpression` for SQL.
78
+ */
79
+ export type ColumnDefault = JsonScalar | bigint | Date | null | SqlExpression;
73
80
  /**
74
81
  * Column node in the schema graph.
75
82
  * Represents a single column in a database table.
@@ -81,8 +88,7 @@ export interface ColumnNode {
81
88
  readonly type: CanonicalType;
82
89
  /** Whether the column allows NULL values */
83
90
  readonly nullable: boolean;
84
- /** The column's default: a literal value, or an `SqlExpression` for SQL. */
85
- readonly defaultValue?: unknown;
91
+ readonly defaultValue?: ColumnDefault;
86
92
  /** Whether this column is part of the primary key */
87
93
  readonly isPrimaryKey: boolean;
88
94
  /** Whether this column auto-increments */
@@ -31,11 +31,10 @@ export const SQLITE_FEATURES = {
31
31
  serverSideCursors: false,
32
32
  correlatedWrites: true,
33
33
  rowLocks: false,
34
- writeReturning: true,
34
+ reportsWrites: ['insert', 'update', 'delete', 'upsert'],
35
35
  nullsSortLowest: true,
36
36
  nullsOrdering: 'clause',
37
37
  textScoreIndexes: false,
38
- orderedUpsertReturning: true,
39
38
  orderedJsonAggregates: true,
40
39
  narrowVectorTypes: false,
41
40
  vectorTuningNeedsTransaction: false,
@@ -70,14 +70,14 @@ type AggregateRefs<R> = {
70
70
  } ? RelationRef<Columns> : never;
71
71
  };
72
72
  type RelationValue<P> = P extends () => DefinedRelation<infer T, infer C, unknown> ? C extends '1m' | 'mm' ? T[] : T : never;
73
- /** A relation's derived field as its callback declares it: a thunk, so it is read lazily like a relation is. */
74
- export type DerivedFields = {
73
+ /** A value over the relations as their second callback declares it: a thunk, so it is read lazily like a relation is. */
74
+ export type AggregateFields = {
75
75
  readonly [key: string]: () => RelationAggregate<unknown> | Column<{
76
76
  readonly computed: QuerySql;
77
77
  }>;
78
78
  };
79
- /** The derived fields a `relations` callback declares, as a row reads them, never written. */
80
- export type DerivedRow<A> = {
79
+ /** The aggregate fields a `relations` callback declares, as a row reads them, never written. */
80
+ export type AggregateRow<A> = {
81
81
  readonly [K in keyof A]-?: A[K] extends () => infer F ? FieldValue<F> : never;
82
82
  };
83
83
  /** The relations as a row reads them; exported, as a defined entity's emitted declaration names it. */
@@ -160,7 +160,7 @@ type DefinedSections<Row, Key, Columns, B, Abstract> = {
160
160
  * The relations, each read lazily so entities pointing at each other declare in either order, and the values
161
161
  * read over the to-many ones, its base's too: `(author) => ({ postCount: () => author.posts.count() })`.
162
162
  */
163
- relations<const R, const A extends DerivedFields = {}>(relations: (rel: RelationBuilder<Columns>) => R, derived?: (refs: RefMap<Columns> & AggregateRefs<R> & ToManyRefs<B, Exclude<ToManyRelationKey<B>, keyof R>>) => A): RelatedEntity<Row & RelationRow<R> & DerivedRow<A>, Key, Columns, Abstract>;
163
+ relations<const R, const A extends AggregateFields = {}>(relations: (rel: RelationBuilder<Columns>) => R, aggregates?: (refs: RefMap<Columns> & AggregateRefs<R> & ToManyRefs<B, Exclude<ToManyRelationKey<B>, keyof R>>) => A): RelatedEntity<Row & RelationRow<R> & AggregateRow<A>, Key, Columns, Abstract>;
164
164
  };
165
165
  /** A defined entity's class once its relations are in: its filters may follow, and read through them. */
166
166
  export type RelatedEntity<Row, Key, Columns, Abstract = false> = DefinedClass<Row, Key, Columns, Abstract> & {
@@ -1,11 +1,14 @@
1
- import type { EntityMeta, EntityPredicate, UpdatePayload } from './entity.js';
1
+ import type { SelectTerm } from '../dialect/abstractSqlDialect.js';
2
+ import type { EntityMeta, EntityPredicate, FieldKey, UpdatePayload } from './entity.js';
2
3
  import type { EngineName } from './querier.js';
3
- import type { Query, QueryConflictPaths, QueryPage, QueryRenderOptions, QuerySearch, RelationQuery } from './query.js';
4
+ import type { Query, QueryPage, QueryRenderOptions, QuerySearch, QueryUpsert, RelationQuery } from './query.js';
4
5
  import type { QueryAggregate, QueryAggregateOp } from './queryAggregate.js';
5
6
  import type { QuerySqlRenderOptions } from './querySql.js';
6
7
  import type { QueryWhere } from './queryWhere.js';
7
8
  import type { AbstractType } from './utility.js';
8
9
  import type { QueryVectorQuery } from './vector.js';
10
+ /** A write a statement of which can report the rows it wrote. */
11
+ export type ReportedWrite = 'insert' | 'update' | 'delete' | 'upsert';
9
12
  /** The values the database computes that uql exports by name: `currentTimestamp`, `uuid`, ... */
10
13
  export declare const SQL_VALUE_NAMES: readonly ['currentTimestamp', 'currentDate', 'currentTime', 'uuid', 'uuidv7'];
11
14
  export type SqlValueName = (typeof SQL_VALUE_NAMES)[number];
@@ -136,11 +139,10 @@ export interface DialectFeatures {
136
139
  */
137
140
  readonly correlatedWrites: boolean;
138
141
  /**
139
- * Whether an `UPDATE` and a `DELETE` report the rows they wrote (`RETURNING`), so a write `returning` them
140
- * in one statement reads them off it: the Postgres and SQLite families. MariaDB returns from a `DELETE`
141
- * only, and SQL Server's `OUTPUT` fails on a table with a trigger, so both read their rows first.
142
+ * The writes whose statement reports the rows it wrote, `RETURNING` or SQL Server's `OUTPUT`, so a write
143
+ * `returning` them reads them off it. MySQL reports none, MariaDB every write but `UPDATE`, the others all four.
142
144
  */
143
- readonly writeReturning: boolean;
145
+ readonly reportsWrites: readonly ReportedWrite[];
144
146
  /**
145
147
  * What the engine's row locks can do, or `false` where it has none: the SQLite family locks the
146
148
  * database and MongoDB has no row lock at all, so both refuse `$lock` rather than ignoring it. One
@@ -184,8 +186,6 @@ export interface SqlDialectFeatures extends DialectFeatures {
184
186
  * again would read `'123'` as `123`.
185
187
  */
186
188
  readonly jsonArrivesDecoded: boolean;
187
- /** Whether a multi-row upsert's `RETURNING` lists its rows in payload order; where not, the ids are read back. */
188
- readonly orderedUpsertReturning: boolean;
189
189
  /** Whether a JSON aggregate takes an `ORDER BY` of its own; where not, a relation's rows keep their derived table's order. */
190
190
  readonly orderedJsonAggregates: boolean;
191
191
  /** Whether the engine has pgvector's `halfvec` and `sparsevec`; elsewhere both map onto `vector`. */
@@ -281,7 +281,7 @@ export type TriggerWrite = {
281
281
  } | {
282
282
  readonly kind: 'upsert';
283
283
  readonly entity: AbstractType<object>;
284
- readonly conflictPaths: Readonly<Record<string, unknown>>;
284
+ readonly q: QueryUpsert<object>;
285
285
  readonly row: Readonly<Record<string, unknown>>;
286
286
  readonly update?: Readonly<Record<string, unknown>>;
287
287
  } | {
@@ -330,16 +330,19 @@ export interface SqlQueryDialect {
330
330
  find<E>(ctx: QueryContext, entity: AbstractType<E>, q: Query<E>, opts?: QueryRenderOptions, totalAlias?: string): void;
331
331
  /** A count of the records matching the filter, or of those a page of it takes. */
332
332
  count<E>(ctx: QueryContext, entity: AbstractType<E>, q: QueryPage<E>, opts?: QueryRenderOptions): void;
333
- /** An insert of one record or many. */
334
- insert<E>(ctx: QueryContext, entity: AbstractType<E>, payload: E | E[], opts?: QueryRenderOptions): void;
333
+ /**
334
+ * Each write reports the fields `returning` names of the rows it writes, where {@link DialectFeatures.reportsWrites}
335
+ * has it, answering the terms they read as; an insert naming none reports each id instead.
336
+ */
337
+ insert<E>(ctx: QueryContext, entity: AbstractType<E>, payload: E | E[], returning?: readonly FieldKey<E>[]): readonly SelectTerm[];
335
338
  /** An update of the records the query matches. */
336
- update<E>(ctx: QueryContext, entity: AbstractType<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryRenderOptions): void;
337
- /** An upsert of one record or many by their conflict paths, a conflicting row taking `update` where given. */
338
- upsert<E>(ctx: QueryContext, entity: AbstractType<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], update?: UpdatePayload<E>): void;
339
+ update<E>(ctx: QueryContext, entity: AbstractType<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryRenderOptions, returning?: readonly FieldKey<E>[]): readonly SelectTerm[];
340
+ /** An upsert of one record or many as `q` names its rows, a conflicting row taking `update` where given. */
341
+ upsert<E>(ctx: QueryContext, entity: AbstractType<E>, q: QueryUpsert<E>, payload: E | E[], update?: UpdatePayload<E>, returning?: readonly FieldKey<E>[]): readonly SelectTerm[];
339
342
  /** A write in a trigger's body; `rows` are what a set-based engine's body reads, narrowed to the ones it fires for. */
340
343
  triggerWrite(ctx: QueryContext, write: TriggerWrite, rows?: TriggerRows): void;
341
344
  /** A delete of the records the query matches, a soft delete where the entity has one. */
342
- delete<E>(ctx: QueryContext, entity: AbstractType<E>, q: QuerySearch<E>, opts?: QueryRenderOptions): void;
345
+ delete<E>(ctx: QueryContext, entity: AbstractType<E>, q: QuerySearch<E>, opts?: QueryRenderOptions, returning?: readonly FieldKey<E>[]): readonly SelectTerm[];
343
346
  /**
344
347
  * escape an identifier.
345
348
  * @param val the value to be escaped
@@ -370,6 +373,14 @@ export interface SqlQueryDialect {
370
373
  * The column a field of `meta` is stored in, named the way this dialect names columns.
371
374
  */
372
375
  columnOf<E>(meta: EntityMeta<E>, key: string): string;
376
+ /**
377
+ * The table of `meta` as a FROM names it, through the naming strategy and under its schema, and the alias its
378
+ * columns are read off: `alias`, else the table's own.
379
+ */
380
+ tableRef<E>(meta: EntityMeta<E>, alias?: string): {
381
+ alias: string;
382
+ ref: string;
383
+ };
373
384
  /**
374
385
  * Build an aggregate query.
375
386
  */
@@ -62,9 +62,12 @@ type FilledKey<E> = SoleIdKey<E> | VersionKey<E> | (BrandNames<E, typeof filledK
62
62
  export type EntityWrite<E> = EntityData<E, Exclude<WritableKey<E>, FilledKey<E>>> & ([FilledKey<E>] extends [never] ? unknown : {
63
63
  [P in WritableKey<E> & FilledKey<E>]?: E[P];
64
64
  });
65
- /** A row a trigger's body writes: each writable field its value, or SQL - a row's ref most often. */
66
- export type WriteRow<E, F extends keyof E = WritableKey<E>> = {
67
- readonly [K in F]?: E[K] | SqlFor<QuerySql, E[K]>;
65
+ /**
66
+ * A row a trigger's body inserts: an {@link EntityWrite}, the same fields required, each its value or SQL
67
+ * holding one, a row's ref most often.
68
+ */
69
+ export type WriteRow<E> = {
70
+ readonly [K in keyof EntityWrite<E>]: EntityWrite<E>[K] | SqlFor<QuerySql, EntityWrite<E>[K]>;
68
71
  };
69
72
  /**
70
73
  * The property an entity brands with {@link versionKey} as its optimistic lock, `never` where it
@@ -348,12 +351,15 @@ export type FieldOptions<V = unknown> = {
348
351
  };
349
352
  export type OnFieldCallback<V = unknown> = V | QuerySql | (() => V | QuerySql);
350
353
  /**
351
- * What a column may default to: its value, or on a JSON column the document it stores, `[]`, or its SQL text,
352
- * `'{}'`. The erased `FieldOptions` takes them all, so every field's options stay assignable to it.
354
+ * What a column may default to: its value, or on a JSON column a document its payload admits, any document on
355
+ * an untyped one, a string being a JSON string. The erased `FieldOptions` takes them all, so every field's
356
+ * options stay assignable to it.
353
357
  */
354
- export type DdlDefault<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? JsonDdlDefault : [TsTypeOf<FieldType>] extends [T] ? JsonDdlDefault | T : T;
355
- /** What a JSON column, and the field-less `FieldOptions`, may default to: a document, a list included, or its text. */
356
- type JsonDdlDefault = Scalar | Record<string, unknown> | readonly unknown[];
358
+ export type DdlDefault<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? unknown extends JsonDocument<T> ? JsonDdlDefault : NonNullable<JsonDocument<T>> : [TsTypeOf<FieldType>] extends [T] ? JsonDdlDefault | T : T;
359
+ /** The document a JSON column declared as `T` stores: its payload, or a list of them for `Json<P>[]`. */
360
+ type JsonDocument<T> = IsJson<T> extends true ? UnwrapJson<T> : readonly UnwrapJson<NonNullable<Unpacked<T>>>[];
361
+ /** What a JSON column, and the field-less `FieldOptions`, may default to: a document, a list or a scalar included. */
362
+ type JsonDdlDefault = JsonScalar | Record<string, unknown> | readonly unknown[];
357
363
  /** The TypeScript type a declared `type` implies: a decorator checks the property against it, a defined entity derives it. */
358
364
  export type TsTypeOf<T> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BigIntConstructor ? bigint : T extends BooleanConstructor ? boolean : T extends DateConstructor ? Date : T extends StringColumnType | TimeColumnType | DecimalColumnType ? string : T extends NumericColumnType ? number | bigint : T extends BooleanColumnType ? boolean : T extends DateColumnType ? Date : T extends JsonColumnType ? JsonBrand | readonly JsonBrand[] : T extends BlobColumnType ? Uint8Array : T extends VectorColumnType ? readonly number[] : unknown;
359
365
  /** The entity a relation points at: `Company` for `company?: Company` and `companies?: Company[]` alike. */