uql-orm 0.95.0 → 0.96.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 (80) hide show
  1. package/dist/browser/uql-browser.min.js +2 -2
  2. package/dist/browser/uql-browser.min.js.map +3 -3
  3. package/dist/d1/d1Querier.d.ts +2 -0
  4. package/dist/d1/d1Querier.js +4 -0
  5. package/dist/dialect/abstractSqlDialect.d.ts +4 -4
  6. package/dist/dialect/abstractSqlDialect.js +28 -20
  7. package/dist/dialect/mysqlLikeSqlDialect.js +3 -6
  8. package/dist/dialect/pgLikeSqlDialect.d.ts +2 -2
  9. package/dist/dialect/pgLikeSqlDialect.js +4 -4
  10. package/dist/dialect/queryContext.d.ts +0 -2
  11. package/dist/dialect/queryContext.js +0 -6
  12. package/dist/libsql/libsqlDialect.d.ts +4 -1
  13. package/dist/libsql/libsqlDialect.js +4 -1
  14. package/dist/libsql/libsqlQuerierPool.d.ts +1 -1
  15. package/dist/libsql/libsqlQuerierPool.js +1 -1
  16. package/dist/maria/mariadbQuerier.d.ts +4 -0
  17. package/dist/maria/mariadbQuerier.js +14 -2
  18. package/dist/maria/mariadbQuerierPool.js +1 -1
  19. package/dist/migrate/bin.js +2 -4
  20. package/dist/migrate/cli.js +8 -4
  21. package/dist/migrate/codegen/entityTypes.js +6 -15
  22. package/dist/migrate/ddl/indexDdl.d.ts +1 -6
  23. package/dist/migrate/ddl/indexDdl.js +0 -10
  24. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +5 -5
  25. package/dist/migrate/ddl/mysqlIndexDdl.js +11 -6
  26. package/dist/migrate/ddl/tableDdl.d.ts +8 -2
  27. package/dist/migrate/ddl/tableDdl.js +11 -3
  28. package/dist/migrate/drift/driftDetector.js +2 -10
  29. package/dist/migrate/introspection/sqliteIntrospector.d.ts +1 -1
  30. package/dist/migrate/introspection/sqliteIntrospector.js +4 -7
  31. package/dist/migrate/migrator.d.ts +2 -4
  32. package/dist/migrate/migrator.js +12 -20
  33. package/dist/migrate/schemaGenerator.d.ts +5 -0
  34. package/dist/migrate/schemaGenerator.js +18 -9
  35. package/dist/mongo/mongoDialect.d.ts +2 -2
  36. package/dist/mongo/mongoDialect.js +2 -3
  37. package/dist/mongo/mongoIntrospector.js +3 -4
  38. package/dist/mongo/mongoMigrationStorage.d.ts +2 -3
  39. package/dist/mongo/mongoMigrationStorage.js +2 -3
  40. package/dist/mongo/mongoSchemaGenerator.d.ts +6 -4
  41. package/dist/mongo/mongoSchemaGenerator.js +5 -10
  42. package/dist/mongo/mongodbQuerier.js +1 -1
  43. package/dist/mssql/mssqlDialect.d.ts +1 -1
  44. package/dist/mssql/mssqlDialect.js +1 -1
  45. package/dist/mssql/mssqlQuerier.d.ts +6 -3
  46. package/dist/mssql/mssqlQuerier.js +6 -8
  47. package/dist/mssql/mssqlQuerierPool.d.ts +1 -5
  48. package/dist/mssql/mssqlQuerierPool.js +21 -10
  49. package/dist/mysql/mysql2Querier.d.ts +5 -1
  50. package/dist/mysql/mysql2Querier.js +8 -5
  51. package/dist/mysql/mysql2QuerierPool.d.ts +0 -1
  52. package/dist/mysql/mysql2QuerierPool.js +6 -18
  53. package/dist/pglite/pgliteQuerier.d.ts +2 -2
  54. package/dist/pglite/pgliteQuerier.js +1 -1
  55. package/dist/postgres/abstractPgQuerierPool.d.ts +3 -2
  56. package/dist/postgres/abstractPgQuerierPool.js +3 -0
  57. package/dist/postgres/pgQuerier.d.ts +1 -0
  58. package/dist/querier/abstractQuerier.d.ts +10 -5
  59. package/dist/querier/abstractQuerier.js +44 -37
  60. package/dist/querier/abstractSqlQuerier.d.ts +4 -3
  61. package/dist/querier/abstractSqlQuerier.js +46 -41
  62. package/dist/schema/indexColumns.d.ts +8 -0
  63. package/dist/schema/indexColumns.js +28 -0
  64. package/dist/schema/indexDifferences.js +4 -7
  65. package/dist/schema/schemaASTBuilder.js +18 -23
  66. package/dist/schema/sqlExpression.d.ts +2 -2
  67. package/dist/schema/sqlExpression.js +2 -2
  68. package/dist/sqlite/hranaQuerier.d.ts +5 -6
  69. package/dist/sqlite/sqliteDialect.d.ts +1 -1
  70. package/dist/sqlite/sqliteDialect.js +1 -1
  71. package/dist/turso/tursoDialect.d.ts +3 -3
  72. package/dist/turso/tursoDialect.js +5 -10
  73. package/dist/type/dialect.d.ts +7 -3
  74. package/dist/type/entity.d.ts +2 -2
  75. package/dist/type/migration.d.ts +2 -9
  76. package/dist/util/object.util.js +3 -0
  77. package/dist/util/sql.util.d.ts +0 -2
  78. package/dist/util/sql.util.js +0 -6
  79. package/package.json +6 -6
  80. package/skills/uql-orm/SKILL.md +2 -2
@@ -40,13 +40,14 @@ function groupByInsertShape(meta, payload) {
40
40
  return [...groups.values()];
41
41
  }
42
42
  /**
43
- * A group's row indexes split into statements of at most `maxRows` rows within the bind budget, payload order
44
- * kept, a row with no column to write in one of its own. `DEFAULT` cells bind no parameter, so fields-per-record
45
- * is a safe upper bound. Every multi-row write splits on this: D1 allows 100 binds, which a couple of dozen reach.
43
+ * A group's row indexes split into statements of at most `maxRows` rows within the bind budget, payload order kept,
44
+ * and a statement whose rows name no column into one per row, as `DEFAULT VALUES` writes. `DEFAULT` cells bind no
45
+ * parameter, so fields-per-record is a safe upper bound. D1 allows 100 binds, which a couple of dozen rows reach.
46
46
  */
47
47
  function chunkWithinLimits(meta, payload, group, maxBindValues, maxRows = Infinity) {
48
- const fieldsPerRecord = getInsertFieldKeys(meta, group.map((index) => payload[index])).length;
49
- return chunk(group, fieldsPerRecord ? Math.max(1, Math.min(maxRows, Math.floor(maxBindValues / fieldsPerRecord))) : 1);
48
+ const width = (indexes) => getInsertFieldKeys(meta, indexes.map((index) => payload[index])).length;
49
+ const size = Math.max(1, Math.min(maxRows, Math.floor(maxBindValues / (width(group) || 1))));
50
+ return chunk(group, size).flatMap((indexes) => (width(indexes) ? [indexes] : chunk(indexes, 1)));
50
51
  }
51
52
  export class AbstractSqlQuerier extends AbstractQuerier {
52
53
  dialect;
@@ -72,12 +73,12 @@ export class AbstractSqlQuerier extends AbstractQuerier {
72
73
  /**
73
74
  * The `auto_increment_increment` stride used to infer the ids of a multi-row insert from the
74
75
  * single id the driver reports (MySQL, which has no `RETURNING`). It is 1 on a standalone server
75
- * but can be higher on a cluster (e.g. Galera). Only called for `firstId` dialects.
76
+ * but can be higher on a cluster (e.g. Galera), and `buildUpdateResult` takes any other as 1.
77
+ * Only called for `firstId` dialects.
76
78
  */
77
79
  async loadInsertIdIncrement() {
78
- const rows = await this.all('SELECT @@auto_increment_increment AS v');
79
- const value = Number(rows[0]?.v);
80
- return Number.isInteger(value) && value > 0 ? value : 1;
80
+ const [row] = await this.all('SELECT @@auto_increment_increment AS v');
81
+ return Number(row.v);
81
82
  }
82
83
  /**
83
84
  * Hook for subclasses (e.g. pool queriers) to establish a connection. Called before every query and
@@ -247,18 +248,11 @@ export class AbstractSqlQuerier extends AbstractQuerier {
247
248
  // relation that only the populated ones need.
248
249
  for (const key in meta.relations) {
249
250
  const value = row[key];
250
- if (!value)
251
- continue;
252
251
  const rel = meta.relations[key];
253
- if (!rel)
252
+ if (!value || !rel)
254
253
  continue;
255
254
  const relEntity = rel.entity();
256
- if (typeof value === 'string' || Array.isArray(value)) {
257
- // A to-many's rows, as flat as a statement's own.
258
- const rows = typeof value === 'string' ? JSON.parse(value) : value;
259
- row[key] = rows.map(this.rowReader(relEntity));
260
- }
261
- else if (isRecord(value)) {
255
+ if (isRecord(value)) {
262
256
  const relMeta = getMeta(relEntity);
263
257
  if (value[relMeta.ids[0]] == null) {
264
258
  delete row[key];
@@ -267,16 +261,21 @@ export class AbstractSqlQuerier extends AbstractQuerier {
267
261
  this.hydrateFields(relMeta, this.dialect.hydratableFields(relEntity), value);
268
262
  }
269
263
  }
264
+ else {
265
+ // A to-many's rows, as flat as a statement's own.
266
+ const rows = Array.isArray(value) ? value : JSON.parse(String(value));
267
+ row[key] = rows.map(this.rowReader(relEntity));
268
+ }
270
269
  }
271
270
  }
272
271
  /**
273
272
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
274
- * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
275
- * a catalog that does not know the table answers with no row, which is nothing counted.
273
+ * a caller supplying their own `types` replaces the decoding the pools do at the wire, and reads a `NULL`
274
+ * as 0; no row is 0 too, since a catalog that does not know the table answers with none.
276
275
  */
277
276
  async runCount(build) {
278
277
  const [row] = await this.query(build);
279
- return Number(row?.[AGGREGATE_VALUE_ALIAS] ?? 0);
278
+ return row ? Number(row[AGGREGATE_VALUE_ALIAS]) : 0;
280
279
  }
281
280
  async internalCount(entity, q, opts) {
282
281
  return this.runCount((ctx) => this.dialect.count(ctx, entity, q, opts));
@@ -305,20 +304,27 @@ export class AbstractSqlQuerier extends AbstractQuerier {
305
304
  const sole = meta.ids.length === 1;
306
305
  const idField = sole ? meta.fields[idKey] : undefined;
307
306
  const generatedKey = !!idField && isAutoIncrement(idField, true);
308
- for (const group of partitionBySuppliedId(rows, idKey)) {
309
- // Header ids are only sound where every row of this statement left its key to the database, so
310
- // the batch is split on that alone, and a supplied id cannot void the others.
307
+ // Per group, not per batch: the two carry different columns - one names the key, one does not - so a budget
308
+ // taken over their union would under-fill the statement that is missing one. Header ids are only sound where
309
+ // every row of a statement left its key to the database, so a supplied id cannot void the others.
310
+ const statements = partitionBySuppliedId(rows, idKey).flatMap((group) => {
311
311
  const idsReliable = sole &&
312
312
  (this.dialect.insertIdSource === 'returning' ||
313
313
  (generatedKey && group.every((index) => rows[index][idKey] === undefined)));
314
- // Inferring multiple ids from the single header id (MySQL) assumes a known stride; a clustered
315
- // server may set `auto_increment_increment` > 1, so probe it (once, cached) before inferring.
316
- if (idsReliable && group.length > 1 && this.dialect.insertIdSource === 'firstId') {
317
- this.#insertIdIncrement ??= await this.loadInsertIdIncrement();
318
- }
319
- // Per group, not per batch: the two carry different columns - one names the key, one does not -
320
- // so a budget taken over their union would under-fill the statement that is missing one.
321
- for (const indexes of chunkWithinLimits(meta, rows, group, this.dialect.maxBindValues, this.dialect.maxInsertRows)) {
314
+ const { maxBindValues, maxInsertRows } = this.dialect;
315
+ return chunkWithinLimits(meta, rows, group, maxBindValues, maxInsertRows).map((indexes) => ({
316
+ indexes,
317
+ idsReliable,
318
+ }));
319
+ });
320
+ // Inferring multiple ids from the single header id (MySQL) assumes a known stride; a clustered
321
+ // server may set `auto_increment_increment` > 1, so probe it (once, cached) before inferring.
322
+ if (this.dialect.insertIdSource === 'firstId' &&
323
+ statements.some(({ indexes, idsReliable }) => idsReliable && indexes.length > 1)) {
324
+ this.#insertIdIncrement ??= await this.loadInsertIdIncrement();
325
+ }
326
+ const insert = async () => {
327
+ for (const { indexes, idsReliable } of statements) {
322
328
  const statementRows = indexes.map((index) => rows[index]);
323
329
  const { ids = [] } = await this.exec((ctx) => this.dialect.insert(ctx, entity, statementRows));
324
330
  if (idsReliable) {
@@ -327,7 +333,8 @@ export class AbstractSqlQuerier extends AbstractQuerier {
327
333
  }
328
334
  }
329
335
  }
330
- }
336
+ };
337
+ await (statements.length > 1 ? this.atomically(insert) : insert());
331
338
  }
332
339
  async internalUpdateMany(entity, q, payload, opts) {
333
340
  const { changes = 0 } = await this.exec((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
@@ -342,20 +349,18 @@ export class AbstractSqlQuerier extends AbstractQuerier {
342
349
  }
343
350
  payload = clone(payload);
344
351
  const meta = getMeta(entity);
345
- // One statement per shape, each split again to stay inside the bind budget, less what its assignments bind
346
- // once. Grouping first is what makes that one figure: every row of a group carries the same columns, so
347
- // they assign the same. No row cap: SQL Server upserts through a MERGE, whose source takes any number.
352
+ // One statement per shape, each split again to fit the bind budget, less what its assignments bind once.
353
+ // Grouping first is what makes that one figure: every row of a group carries the same columns. No row cap:
354
+ // the one engine with one, SQL Server, upserts through a MERGE, whose source takes any number.
348
355
  const statements = groupByInsertShape(meta, payload).flatMap((group) => {
349
- const rows = group.map((index) => payload[index]);
350
- const assigned = this.dialect.upsertAssignmentBinds(entity, conflictPaths, rows, update);
356
+ const assigned = this.dialect.upsertAssignmentBinds(entity, conflictPaths, payload[group[0]], update);
351
357
  return chunkWithinLimits(meta, payload, group, this.dialect.maxBindValues - assigned);
352
358
  });
353
359
  if (statements.length === 1) {
354
360
  return this.runUpsert(entity, conflictPaths, payload, update);
355
361
  }
356
- // An upsert's assignment list is the statement's, so rows of different shapes go in statements
357
- // of their own, together in a transaction (`transaction` is re-entrant).
358
- return this.transaction(async () => {
362
+ // An upsert's assignment list is the statement's, so rows of different shapes go in statements of their own.
363
+ return this.atomically(async () => {
359
364
  let changes = 0;
360
365
  // Placed by index, since grouping by shape reorders the rows. A statement reporting fewer ids
361
366
  // than it wrote places none.
@@ -1,3 +1,11 @@
1
+ import type { IndexColumnSchema } from '../type/index.js';
1
2
  import type { ColumnNode, IndexNode } from './types.js';
2
3
  /** The table columns an index's entries resolve to, in order; an expression entry resolves to none. */
3
4
  export declare function indexColumns(index: IndexNode): ColumnNode[];
5
+ /** Whether an entry is its column as stored, rather than an expression or a path the engine reprints in its own words. */
6
+ export declare function isColumnEntry(entry: IndexColumnSchema): boolean;
7
+ /**
8
+ * The columns an index can look every row up by, in order, as far as its entries are whole columns: none
9
+ * where it holds only some rows (partial) or is of a type an equality lookup does not read.
10
+ */
11
+ export declare function lookupColumns(index: IndexNode): string[];
@@ -2,3 +2,31 @@
2
2
  export function indexColumns(index) {
3
3
  return index.entries.flatMap((entry) => (entry.expression ? [] : (index.table.columns.get(entry.column) ?? [])));
4
4
  }
5
+ /** Whether an entry is its column as stored, rather than an expression or a path the engine reprints in its own words. */
6
+ export function isColumnEntry(entry) {
7
+ return !entry.expression && !entry.jsonPath && !entry.jsonArray;
8
+ }
9
+ /** Whether an equality lookup reads each index type; the rest answer text, vector or range questions. Total, so a new type says. */
10
+ const ANSWERS_LOOKUP = {
11
+ btree: true,
12
+ hash: true,
13
+ gin: false,
14
+ gist: false,
15
+ brin: false,
16
+ fulltext: false,
17
+ hnsw: false,
18
+ ivfflat: false,
19
+ vector: false,
20
+ vectorSearch: false,
21
+ };
22
+ /**
23
+ * The columns an index can look every row up by, in order, as far as its entries are whole columns: none
24
+ * where it holds only some rows (partial) or is of a type an equality lookup does not read.
25
+ */
26
+ export function lookupColumns(index) {
27
+ if (index.where !== undefined || !ANSWERS_LOOKUP[index.type ?? 'btree']) {
28
+ return [];
29
+ }
30
+ const whole = index.entries.findIndex((entry) => !isColumnEntry(entry) || entry.length !== undefined);
31
+ return index.entries.slice(0, whole === -1 ? undefined : whole).map((entry) => entry.column);
32
+ }
@@ -1,17 +1,14 @@
1
1
  import { indexDistance, isVectorIndexType } from '../type/vector.js';
2
2
  import { fulltextConfig } from '../util/dialect.util.js';
3
3
  import { derivedIndexName } from '../util/sql.util.js';
4
+ import { isColumnEntry } from './indexColumns.js';
4
5
  import { matchByKey } from './matchByKey.js';
5
- /** An entry the engine reprints in its own words, so never compared as written. */
6
- function isReprinted(entry) {
7
- return Boolean(entry.expression || entry.jsonPath || entry.jsonArray);
8
- }
9
6
  /**
10
7
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
11
8
  * over an expression, whose text the engine reprints, falls back to its name.
12
9
  */
13
10
  export function indexSignature(index) {
14
- const comparable = !index.entries.some(isReprinted);
11
+ const comparable = index.entries.every(isColumnEntry);
15
12
  const identity = comparable
16
13
  ? index.entries.map((entry) => entry.column).join(',')
17
14
  : `name:${indexNameStem(index.name)}`;
@@ -58,7 +55,7 @@ export function indexChanges(table, declared, current, facets) {
58
55
  * the `idx_Order_total` it wrote until 0.42.1.
59
56
  */
60
57
  function hasDerivedName(table, index) {
61
- const parts = index.entries.map((entry, at) => (isReprinted(entry) ? `expr${at}` : entry.column));
58
+ const parts = index.entries.map((entry, at) => (isColumnEntry(entry) ? entry.column : `expr${at}`));
62
59
  const derived = [
63
60
  derivedIndexName(table, parts),
64
61
  derivedIndexName(table, parts, true),
@@ -80,7 +77,7 @@ const KIND_PREFIX = /^(?:idx|fk|ck|pk|uk|uq)_/i;
80
77
  */
81
78
  export function describeIndexDifferences(source, target, facets) {
82
79
  const differences = [];
83
- const comparableEntries = ![...source.entries, ...target.entries].some(isReprinted);
80
+ const comparableEntries = [...source.entries, ...target.entries].every(isColumnEntry);
84
81
  if (comparableEntries) {
85
82
  const [sourceColumns, targetColumns] = [source, target].map((index) => textFieldOrder(index, facets, index.entries.map((entry) => entrySignature(entry, facets))).join(', '));
86
83
  if (sourceColumns !== targetColumns) {
@@ -2,10 +2,11 @@ import { fieldOf, foreignKeysOf, getMeta } from '../entity/metadata/definition.j
2
2
  import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../util/ddlExpression.util.js';
3
3
  import { fulltextWeights, textWeightSteps } from '../util/dialect.util.js';
4
4
  import { declaresNotNull, isAutoIncrement, isInlinedExpression, isSoleIdField } from '../util/field.util.js';
5
- import { definedEntries } from '../util/object.util.js';
6
- import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
5
+ import { definedEntries, entityName } from '../util/object.util.js';
6
+ import { derivedForeignKeyName, derivedIndexName } from '../util/sql.util.js';
7
7
  import { UqlUsageError } from '../util/uqlError.js';
8
8
  import { resolveColumnCanonicalType } from './canonicalType.js';
9
+ import { lookupColumns } from './indexColumns.js';
9
10
  import { createTableNode, keyOfColumns, SchemaAST } from './schemaAST.js';
10
11
  import { schemaDefault } from './sqlExpression.js';
11
12
  import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
@@ -20,8 +21,8 @@ export function buildSchemaAST(entities, options = {}) {
20
21
  const compileDdl = options.compileDdl ?? refuseDdl;
21
22
  const ctx = {
22
23
  ast: new SchemaAST(),
23
- resolveTableName: options.resolveTableName ??
24
- ((m) => namingStrategy?.tableName(m.name ?? m.entity.name) ?? m.name ?? m.entity.name),
24
+ tables: new Map(),
25
+ resolveTableName: options.resolveTableName ?? ((m) => namingStrategy?.tableName(entityName(m)) ?? entityName(m)),
25
26
  resolveSchema: options.resolveSchema ?? ((m) => m.schema),
26
27
  resolveColumnName: options.resolveColumnName ?? ((k, f) => namingStrategy?.columnName(f.name ?? k) ?? f.name ?? k),
27
28
  defaultForeignKeyAction: options.defaultForeignKeyAction ?? DEFAULT_FOREIGN_KEY_ACTION,
@@ -30,9 +31,13 @@ export function buildSchemaAST(entities, options = {}) {
30
31
  textScoreIndexes: options.textScoreIndexes ?? false,
31
32
  vectorIndexRequiresNotNull: options.vectorIndexRequiresNotNull ?? false,
32
33
  };
33
- for (const pass of [addTableFromEntity, addRelationshipsFromEntity, addIndexesFromEntity]) {
34
- for (const entity of entities) {
35
- pass(ctx, getMeta(entity));
34
+ for (const entity of entities) {
35
+ const meta = getMeta(entity);
36
+ ctx.tables.set(meta, addTableFromEntity(ctx, meta));
37
+ }
38
+ for (const pass of [addRelationshipsFromEntity, addIndexesFromEntity]) {
39
+ for (const [meta, table] of ctx.tables) {
40
+ pass(ctx, meta, table);
36
41
  }
37
42
  }
38
43
  return ctx.ast;
@@ -85,22 +90,16 @@ function addTableFromEntity(ctx, meta) {
85
90
  }
86
91
  table.primaryKey = keyOfColumns(columns.values());
87
92
  ctx.ast.addTable(table);
88
- }
89
- /** The node an entity maps to, found under the key {@link SchemaAST} stores it by. */
90
- function tableOf(ctx, meta) {
91
- return ctx.ast.getTable(qualifyName(ctx.resolveTableName(meta), ctx.resolveSchema(meta)));
93
+ return table;
92
94
  }
93
95
  /**
94
96
  * Add a relationship for each foreign key the entity holds, whether a relation declares it or a bare
95
97
  * `@Field({ references })` does.
96
98
  */
97
- function addRelationshipsFromEntity(ctx, meta) {
98
- const table = tableOf(ctx, meta);
99
- if (!table)
100
- return;
99
+ function addRelationshipsFromEntity(ctx, meta, table) {
101
100
  for (const foreignKey of foreignKeysOf(meta)) {
102
101
  const relatedMeta = getMeta(foreignKey.entity());
103
- const relatedTable = tableOf(ctx, relatedMeta);
102
+ const relatedTable = ctx.tables.get(relatedMeta);
104
103
  if (!relatedTable)
105
104
  continue;
106
105
  // Every pair, not just the first: a composite key is one constraint over all its columns, and
@@ -135,10 +134,7 @@ function addRelationshipsFromEntity(ctx, meta) {
135
134
  * Add indexes from field options (`@Field({ index })`), from `@Index`, and for every foreign
136
135
  * key none of those already serves.
137
136
  */
138
- function addIndexesFromEntity(ctx, meta) {
139
- const table = tableOf(ctx, meta);
140
- if (!table)
141
- return;
137
+ function addIndexesFromEntity(ctx, meta, table) {
142
138
  for (const idxMeta of declaredIndexes(meta)) {
143
139
  addCompositeIndex(ctx, table, meta, idxMeta);
144
140
  }
@@ -163,11 +159,10 @@ function addForeignKeyIndexes(ctx, meta, table) {
163
159
  });
164
160
  }
165
161
  }
166
- /** Whether the key or an index already leads with `columns`, which is all a lookup needs. */
162
+ /** Whether the key or an index the engine can look rows up by already leads with `columns`. */
167
163
  function isIndexedBy(table, columns) {
168
164
  const leads = (indexed) => columns.every((column, at) => indexed[at] === column);
169
- return (leads(table.primaryKey?.columns ?? []) ||
170
- table.indexes.some((index) => leads(index.entries.map((entry) => entry.expression || entry.jsonPath || entry.jsonArray ? undefined : entry.column))));
165
+ return leads(table.primaryKey?.columns ?? []) || table.indexes.some((index) => leads(lookupColumns(index)));
171
166
  }
172
167
  /** An `include` column is named like any other, so a naming strategy has to reach it too. */
173
168
  function resolveIncludeColumn(ctx, meta, column) {
@@ -25,7 +25,7 @@ export declare class SqlExpression {
25
25
  */
26
26
  export declare function schemaDefault(value: unknown, compile: (sql: QueryRaw) => string): unknown;
27
27
  /**
28
- * A default as text for an exact comparison: numbers as their digits, and objects (SQL included) and text
29
- * holding a JSON document as JSON with its keys in order, since a `jsonb` column reprints what it stores.
28
+ * A default as text to compare: numbers as their digits, other text as written, and objects (SQL included) and text
29
+ * holding a JSON object or list as JSON with its keys in order, equal as documents, since `jsonb` reprints them.
30
30
  */
31
31
  export declare function writtenDefault(value: unknown): string;
@@ -38,8 +38,8 @@ export function schemaDefault(value, compile) {
38
38
  return value instanceof QueryRaw ? SqlExpression.parenthesized(compile(value)) : value;
39
39
  }
40
40
  /**
41
- * A default as text for an exact comparison: numbers as their digits, and objects (SQL included) and text
42
- * holding a JSON document as JSON with its keys in order, since a `jsonb` column reprints what it stores.
41
+ * A default as text to compare: numbers as their digits, other text as written, and objects (SQL included) and text
42
+ * holding a JSON object or list as JSON with its keys in order, equal as documents, since `jsonb` reprints them.
43
43
  */
44
44
  export function writtenDefault(value) {
45
45
  const document = typeof value === 'string' ? jsonDocument(value) : value;
@@ -1,12 +1,6 @@
1
1
  import type { ExtraOptions, RawRow } from '../type/index.js';
2
2
  import { AbstractSqliteQuerier, type SqliteBindValue } from './abstractSqliteQuerier.js';
3
3
  import type { SqliteDialect } from './sqliteDialect.js';
4
- /**
5
- * Structural subset of the Hrana client API, the wire protocol shared by `@libsql/client` and
6
- * `@tursodatabase/serverless/compat`. Declared here rather than imported so a querier works with
7
- * any client of this shape (including `@libsql/client/web` and `@libsql/client-wasm`) without
8
- * depending on vendor types.
9
- */
10
4
  export type HranaInValue = SqliteBindValue | ArrayBuffer | Date;
11
5
  export type HranaResultSet = {
12
6
  rows: unknown[];
@@ -22,6 +16,11 @@ export type HranaTransaction = HranaExecutor & {
22
16
  commit(): Promise<void>;
23
17
  rollback(): Promise<void>;
24
18
  };
19
+ /**
20
+ * The part of a Hrana client the querier uses: `@libsql/client` in any of its builds (`/web`,
21
+ * `@libsql/client-wasm`). Declared here rather than imported, so a client the caller built fits
22
+ * without the vendor's types.
23
+ */
25
24
  export type HranaClient = HranaExecutor & {
26
25
  transaction(mode?: 'write' | 'read' | 'deferred'): Promise<HranaTransaction>;
27
26
  close(): void;
@@ -85,6 +85,6 @@ export declare class SqliteDialect extends AbstractSqlDialect {
85
85
  protected jsonCast(operand: string): string;
86
86
  /** `JSON` keeps each element's JSON type in the array, which answers `[]` for no rows. */
87
87
  protected jsonArrayOf(elem: string): string;
88
- /** `[#]` appends, creating the array where it is absent: `JSON_SET`, since Turso's `JSON_INSERT` will not touch an existing array. */
88
+ /** `[#]` appends, creating the array where it is absent. */
89
89
  protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;
90
90
  }
@@ -218,7 +218,7 @@ export class SqliteDialect extends AbstractSqlDialect {
218
218
  jsonArrayOf(elem) {
219
219
  return `JSON_GROUP_ARRAY(JSON(${elem}))`;
220
220
  }
221
- /** `[#]` appends, creating the array where it is absent: `JSON_SET`, since Turso's `JSON_INSERT` will not touch an existing array. */
221
+ /** `[#]` appends, creating the array where it is absent. */
222
222
  jsonPush(ctx, expr, push) {
223
223
  return jsonSetCall((value) => this.jsonScalarParam(ctx, value), expr, push, this.maxFunctionArgs, '[#]');
224
224
  }
@@ -1,10 +1,10 @@
1
1
  import { LibsqlDialect } from '../libsql/libsqlDialect.js';
2
2
  import type { SqlDialectFeatures } from '../type/index.js';
3
3
  /**
4
- * Turso Cloud, as every database there accepts: libSQL's vector functions and argument cap, and no
5
- * `ORDER BY` inside an aggregate, which its Rust engine lacks. Imports no driver.
4
+ * Turso Cloud, as every database there accepts: libSQL's, and the Rust engine's of one created as
5
+ * `tursodb`. Imports no driver.
6
6
  */
7
7
  export declare class TursoDialect extends LibsqlDialect {
8
- /** The Rust engine takes no `ORDER BY` inside an aggregate, nor a subquery reading the table a write changes. */
8
+ /** The Rust engine cannot read the table a write changes from inside a subquery. */
9
9
  readonly features: SqlDialectFeatures;
10
10
  }
@@ -1,14 +1,9 @@
1
- import { LibsqlDialect } from '../libsql/libsqlDialect.js';
2
- import { SQLITE_FEATURES } from '../sqlite/sqliteDialect.js';
1
+ import { LIBSQL_FEATURES, LibsqlDialect } from '../libsql/libsqlDialect.js';
3
2
  /**
4
- * Turso Cloud, as every database there accepts: libSQL's vector functions and argument cap, and no
5
- * `ORDER BY` inside an aggregate, which its Rust engine lacks. Imports no driver.
3
+ * Turso Cloud, as every database there accepts: libSQL's, and the Rust engine's of one created as
4
+ * `tursodb`. Imports no driver.
6
5
  */
7
6
  export class TursoDialect extends LibsqlDialect {
8
- /** The Rust engine takes no `ORDER BY` inside an aggregate, nor a subquery reading the table a write changes. */
9
- features = {
10
- ...SQLITE_FEATURES,
11
- orderedJsonAggregates: false,
12
- correlatedWrites: false,
13
- };
7
+ /** The Rust engine cannot read the table a write changes from inside a subquery. */
8
+ features = { ...LIBSQL_FEATURES, correlatedWrites: false };
14
9
  }
@@ -392,12 +392,16 @@ export type RelationAggregateProjection = {
392
392
  };
393
393
  /**
394
394
  * A relation aggregate as a `computed` field holds it: an {@link AggregateCall} over the rows of the
395
- * relation it names, capped where it declared a page.
395
+ * relation it names, capped where it declared a page. A distance is a `$sort`'s, which pages nothing.
396
396
  */
397
397
  export type RelationAggregateSpec = RelationAggregateProjection & Pick<AggregateCall, 'where'> & {
398
398
  readonly relation: string;
399
- readonly page?: RelationAggregatePage;
400
- };
399
+ } & ({
400
+ readonly page?: never;
401
+ } | {
402
+ readonly page: RelationAggregatePage;
403
+ readonly search?: never;
404
+ });
401
405
  /** The page of a relation's rows an aggregate reads, and the order picking them. */
402
406
  export type RelationAggregatePage = Pick<RelationQuery, '$sort' | '$limit' | '$skip'>;
403
407
  /**
@@ -330,8 +330,8 @@ export type OnFieldCallback<V = TsTypeOf<FieldType>> = V | QueryRaw | (() => V |
330
330
  * `'{}'`. The erased `FieldOptions` takes them all, so every field's options stay assignable to it.
331
331
  */
332
332
  type DdlDefault<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? JsonDdlDefault : [TsTypeOf<FieldType>] extends [T] ? JsonDdlDefault | T : T;
333
- /** What a JSON column, and the field-less `FieldOptions`, may default to: a document, a list included. */
334
- type JsonDdlDefault = Scalar | object;
333
+ /** What a JSON column, and the field-less `FieldOptions`, may default to: a document, a list included, or its text. */
334
+ type JsonDdlDefault = Scalar | Record<string, unknown> | readonly unknown[];
335
335
  /**
336
336
  * The TypeScript type a declared `type` implies, the inverse of {@link TypeFor}: a decorator checks the
337
337
  * property against it, `defineEntity` the other way round. `entityOptions.test-d.ts` keeps them agreeing.
@@ -44,10 +44,6 @@ export interface MigrationStorage {
44
44
  * Remove a migration from the executed list, on the querier that reverted it
45
45
  */
46
46
  unlogWithQuerier(querier: Querier, migrationName: string): Promise<void>;
47
- /**
48
- * Ensure the storage is initialized (e.g., create migrations table)
49
- */
50
- ensureStorage(): Promise<void>;
51
47
  }
52
48
  /**
53
49
  * Configuration options for the Migrator
@@ -257,15 +253,12 @@ export interface CreateSchemaOptions {
257
253
  * already exists. Constraints still resolve against the full entity graph.
258
254
  */
259
255
  readonly only?: readonly string[];
260
- /**
261
- * Emit the tables without their foreign keys. Only the integration fixtures want this, and only until
262
- * their data stops relying on dangling references; a migration always wants the constraints.
263
- */
264
- readonly foreignKeys?: boolean;
265
256
  }
266
257
  export interface DropSchemaOptions {
267
258
  readonly ifExists?: boolean;
268
259
  readonly cascade?: boolean;
260
+ /** The schema as it stands, whose foreign keys are dropped before any table, since a cycle of them has no drop order. */
261
+ readonly existing?: SchemaAST;
269
262
  }
270
263
  /** The triggers uql installed on one table, by name, each with the statements that recreate it as it stands. */
271
264
  export type InstalledTriggers = ReadonlyMap<string, readonly string[]>;
@@ -9,6 +9,9 @@ export function clone(value) {
9
9
  }
10
10
  /** `items` in consecutive lists of at most `size`, in order: one list where `size` is unbounded. */
11
11
  export function chunk(items, size) {
12
+ if (!(size >= 1)) {
13
+ throw new RangeError(`a chunk holds at least one item, not ${size}`);
14
+ }
12
15
  const chunks = [];
13
16
  for (let start = 0; start < items.length; start += size) {
14
17
  chunks.push(items.slice(start, start + size));
@@ -1,7 +1,5 @@
1
1
  import type { InsertIdSource, QueryUpdateResult, RawRow } from '../type/index.js';
2
2
  import type { PrimaryKey } from '../type/utility.js';
3
- /** Every row nested as {@link unflatObject} nests one, by the columns the first row names. */
4
- export declare function unflatObjects<T extends object>(objects: RawRow[]): T[];
5
3
  /** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
6
4
  export declare function unflatObject<T extends object>(row: RawRow, attrsPaths: Record<string, string[]>): T;
7
5
  export declare function obtainAttrsPaths<T extends object>(row: T): {
@@ -3,12 +3,6 @@ import { hasKeys, isRecord } from './object.util.js';
3
3
  import { fnv1a } from './string.util.js';
4
4
  /** Pre-computed regex for each SQL identifier escape character to avoid per-call allocation. */
5
5
  const escapeIdRegexCache = { '`': /`/g, '"': /"/g };
6
- /** Every row nested as {@link unflatObject} nests one, by the columns the first row names. */
7
- export function unflatObjects(objects) {
8
- const [first] = objects;
9
- const attrsPaths = first ? obtainAttrsPaths(first) : {};
10
- return objects.map((row) => unflatObject(row, attrsPaths));
11
- }
12
6
  /** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
13
7
  export function unflatObject(row, attrsPaths) {
14
8
  if (!hasKeys(attrsPaths)) {
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "homepage": "https://uql-orm.dev",
4
4
  "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
5
5
  "license": "MIT",
6
- "version": "0.95.0",
6
+ "version": "0.96.0",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=24"
@@ -69,8 +69,8 @@
69
69
  "@neondatabase/serverless": ">=0.9.0",
70
70
  "@nestjs/common": ">=10.0.0",
71
71
  "@nestjs/core": ">=10.0.0",
72
- "@tursodatabase/database": ">=0.7.0",
73
- "@tursodatabase/serverless": ">=1.3.0",
72
+ "@tursodatabase/database": ">=0.8.2",
73
+ "@tursodatabase/serverless": ">=1.4.1",
74
74
  "better-sqlite3": ">=9.0.0",
75
75
  "express": ">=5.0.0",
76
76
  "mariadb": ">=3.0.0",
@@ -139,8 +139,8 @@
139
139
  "@nestjs/common": "^12.1.2",
140
140
  "@nestjs/core": "^12.1.2",
141
141
  "@nestjs/testing": "^12.1.2",
142
- "@tursodatabase/database": "^0.8.1",
143
- "@tursodatabase/serverless": "^1.4.0",
142
+ "@tursodatabase/database": "^0.8.2",
143
+ "@tursodatabase/serverless": "^1.4.1",
144
144
  "@types/better-sqlite3": "^9.6.0",
145
145
  "@types/express": "^5.0.6",
146
146
  "@types/mssql": "^12.3.0",
@@ -150,7 +150,7 @@
150
150
  "express": "^5.2.1",
151
151
  "mariadb": "^3.5.4",
152
152
  "mongodb": "^7.7.0",
153
- "mssql": "^12",
153
+ "mssql": "^12.7.4",
154
154
  "mysql2": "^3.24.5",
155
155
  "pg": "^8.23.1",
156
156
  "pg-query-stream": "^4.17.1",
@@ -87,8 +87,8 @@ export class Post {
87
87
  ## Queries
88
88
 
89
89
  ```ts
90
- import { pool } from './uql.config.js';
91
90
  import { User } from './entities.js';
91
+ import { pool } from './uql.config.js';
92
92
 
93
93
  const users = await pool.findMany(User, {
94
94
  $select: { id: true, email: true },
@@ -130,7 +130,7 @@ await pool.transaction(async (querier) => {
130
130
 
131
131
  Inside the callback, call `querier`, never `pool`: a `pool` call runs on another connection, outside the transaction. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
132
132
 
133
- A `findManyStream` holds its querier until the loop ends, which refuses any other statement meanwhile: inside the loop, run them on another connection, or after the loop on SQLite and PGlite, whose pool has one. A statement binding more values than the engine takes (100 on D1, 2098 on SQL Server) is refused too: split a long `$in`.
133
+ A `findManyStream` holds its querier until the loop ends, which refuses any other statement meanwhile: inside the loop, run them on another connection; inside a transaction, or on SQLite and PGlite (one shared connection), run them after the loop. That includes an `@AfterLoad` querying through its `querier` on a streamed row. A statement binding more values than the engine takes (100 on D1, 2098 on SQL Server) is refused too: split a long `$in`.
134
134
 
135
135
  ## Migrations
136
136