uql-orm 0.100.2 → 0.101.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 (50) hide show
  1. package/README.md +8 -70
  2. package/dist/bunSql/bunSqlQuerierPool.js +3 -1
  3. package/dist/dialect/abstractSqlDialect.d.ts +35 -23
  4. package/dist/dialect/abstractSqlDialect.js +90 -72
  5. package/dist/dialect/hydrateColumn.d.ts +4 -5
  6. package/dist/dialect/hydrateColumn.js +2 -8
  7. package/dist/dialect/mysqlLikeSqlDialect.d.ts +4 -4
  8. package/dist/dialect/mysqlLikeSqlDialect.js +7 -6
  9. package/dist/dialect/pgLikeSqlDialect.d.ts +8 -2
  10. package/dist/dialect/pgLikeSqlDialect.js +11 -3
  11. package/dist/entity/metadata/definition.js +1 -1
  12. package/dist/http/fetchHandler.d.ts +1 -1
  13. package/dist/http/fetchHandler.js +1 -1
  14. package/dist/index.d.ts +2 -1
  15. package/dist/index.js +1 -1
  16. package/dist/mariadb/mariaDialect.d.ts +2 -2
  17. package/dist/mariadb/mariaDialect.js +1 -0
  18. package/dist/migrate/cli-config.d.ts +4 -7
  19. package/dist/migrate/cli-config.js +11 -9
  20. package/dist/mongodb/mongoDialect.js +11 -9
  21. package/dist/mssql/mssqlDialect.d.ts +2 -2
  22. package/dist/mssql/mssqlDialect.js +1 -0
  23. package/dist/pglite/pgliteQuerierPool.js +6 -12
  24. package/dist/postgres/abstractPgQuerierPool.d.ts +0 -1
  25. package/dist/postgres/abstractPgQuerierPool.js +0 -3
  26. package/dist/postgres/pgQuerier.d.ts +6 -0
  27. package/dist/postgres/pgQuerier.js +10 -0
  28. package/dist/postgres/pgWireTypes.d.ts +11 -7
  29. package/dist/postgres/pgWireTypes.js +47 -11
  30. package/dist/querier/abstractPoolQuerier.d.ts +2 -0
  31. package/dist/querier/abstractPoolQuerier.js +5 -1
  32. package/dist/querier/abstractQuerier.d.ts +5 -5
  33. package/dist/querier/abstractQuerier.js +59 -53
  34. package/dist/querier/abstractSqlQuerier.d.ts +3 -13
  35. package/dist/querier/abstractSqlQuerier.js +24 -84
  36. package/dist/querier/rowReader.d.ts +8 -0
  37. package/dist/querier/rowReader.js +88 -0
  38. package/dist/sqlite/sqliteDialect.d.ts +2 -2
  39. package/dist/sqlite/sqliteDialect.js +2 -1
  40. package/dist/util/dialect.util.d.ts +2 -11
  41. package/dist/util/dialect.util.js +8 -21
  42. package/dist/util/query.util.js +16 -8
  43. package/dist/util/relationQuery.util.d.ts +21 -12
  44. package/dist/util/relationQuery.util.js +30 -14
  45. package/dist/util/sql.util.d.ts +0 -5
  46. package/dist/util/sql.util.js +0 -33
  47. package/dist/util/wideNumber.d.ts +4 -3
  48. package/dist/util/wideNumber.js +17 -6
  49. package/package.json +3 -4
  50. package/skills/uql-orm/SKILL.md +4 -2
@@ -1,7 +1,7 @@
1
- import { assertSoleId, getMeta, idOf, namesKey, relationOf, soleIdOf } from '../entity/index.js';
1
+ import { getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
2
2
  import { namesRows } from '../dialect/operators.js';
3
3
  import { parseQueryLock } from '../type/index.js';
4
- import { cascadesOnDelete, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, hasKeys, holdsForeignKey, getRelationRequestSummary, guardWrite, idOnlyQuery, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, securityConditions, someKey, targetKeyColumns, whereEach, whereIds, whereKeysIn, whereWith, withoutSoftDeleteFilter, } from '../util/index.js';
4
+ import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, forEachRequestedRelation, getKeys, hasKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, securityConditions, someKey, targetJoins, whereEach, whereIds, whereKeysIn, whereWith, withoutSoftDeleteFilter, cascadingRelations, holdsForeignKey, } from '../util/index.js';
5
5
  import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
6
6
  import { keysetRead } from './keyset.js';
7
7
  import { enrichError } from './queryError.js';
@@ -28,10 +28,6 @@ function assertIdValue(entity, id) {
28
28
  throw new UqlUsageError(`'${entity.name}' is addressed by an object carrying every key of its primary key (${ids.join(', ')}); missing ${missing.join(', ')}.`);
29
29
  }
30
30
  }
31
- /** The column a write matches a parent's sole key against, on the junction or the child. */
32
- function soleParentColumn(relOpts) {
33
- return parentJoins(relOpts, 1)[0].joined;
34
- }
35
31
  /**
36
32
  * A bulk write names the rows it changes: a `$where`, or a `$limit` capping how many it reaches. The
37
33
  * caller's own clauses are what count - a filter the entity adds, soft delete's, would otherwise make
@@ -152,11 +148,12 @@ function pickFields(row, keys) {
152
148
  }
153
149
  /** Whether any payload writes a relation it cascades to, which makes the write several statements. */
154
150
  function writesRelations(meta, payloads) {
155
- return payloads.some((payload) => filterPersistableRelationKeys(meta, payload, 'persist').length > 0);
151
+ const keys = cascadingRelations(meta, 'persist');
152
+ return payloads.some((payload) => keys.some((key) => Object.hasOwn(payload, key)));
156
153
  }
157
- /** The relations a payload writes whose rows hold the parent's key: written after the parent, by its id. */
158
- function childRelationKeys(meta, payload) {
159
- return filterPersistableRelationKeys(meta, payload, 'persist').filter((relKey) => !holdsForeignKey(relationOf(meta, relKey)));
154
+ /** The relations a write cascades to whose rows hold the parent's key: written after the parent, by its id. */
155
+ function ownedRelations(meta) {
156
+ return cascadingRelations(meta, 'persist').filter((relKey) => !holdsForeignKey(relationOf(meta, relKey)));
160
157
  }
161
158
  /** A relation's value as the rows it lists: a to-many's list, a to-one's row, none for `null`. */
162
159
  function listedRows(value) {
@@ -174,11 +171,7 @@ const STREAM_HOLDS_QUERIER = 'a stream is reading on this querier: run the state
174
171
  /** Base class for all database queriers. */
175
172
  export class AbstractQuerier {
176
173
  extra;
177
- /**
178
- * Internal promise used to queue database operations.
179
- * This ensures that each operation is executed serially, preventing race conditions
180
- * and ensuring that the database connection is used safely across concurrent calls.
181
- */
174
+ /** The last task {@link serialize} queued, which the next one runs after. */
182
175
  taskQueue = Promise.resolve();
183
176
  /** The stream reading on the connection, from its first row asked for until its loop ends. */
184
177
  #stream;
@@ -204,9 +197,13 @@ export class AbstractQuerier {
204
197
  get connection() {
205
198
  return this;
206
199
  }
207
- /** The transaction the connection holds, which every querier on it reads. */
200
+ #connectionSlot;
201
+ /**
202
+ * The transaction the connection holds, which every querier on it reads: the querier's own where it owns
203
+ * its connection, and the shared session's otherwise, the one case the registry exists for.
204
+ */
208
205
  get #slot() {
209
- return slotOf(this.connection);
206
+ return (this.#connectionSlot ??= this.connection === this ? {} : slotOf(this.connection));
210
207
  }
211
208
  /** What every read is checked for before it runs, whichever backend runs it. */
212
209
  validateReadQuery(entity, q) {
@@ -463,7 +460,7 @@ export class AbstractQuerier {
463
460
  await this.writeHeldReferences(entity, [row]);
464
461
  fillOnFields(meta, [row], 'onUpdate');
465
462
  guardWrite(meta, [row], 'update');
466
- const relKeys = childRelationKeys(meta, row);
463
+ const relKeys = ownedRelations(meta).filter((key) => Object.hasOwn(row, key));
467
464
  const settles = !!relKeys.length || this.settlesWrite(entity, q);
468
465
  if (lockKey) {
469
466
  assertLockableUpdate(meta, q, settles);
@@ -639,7 +636,7 @@ export class AbstractQuerier {
639
636
  }
640
637
  async deleteRows(entity, q, opts) {
641
638
  const meta = getMeta(entity);
642
- const cascades = cascadesOnDelete(meta);
639
+ const cascades = cascadingRelations(meta, 'delete').length > 0;
643
640
  const watched = this.hasHook(entity, 'beforeDelete') || this.hasHook(entity, 'afterDelete');
644
641
  if (!watched && !cascades && !this.settlesWrite(entity, q)) {
645
642
  return this.internalDeleteMany(entity, q, opts);
@@ -726,7 +723,7 @@ export class AbstractQuerier {
726
723
  */
727
724
  async writeHeldReferences(entity, rows) {
728
725
  const meta = getMeta(entity);
729
- for (const relKey of filterPersistableRelationKeys(meta, meta.relations, 'persist')) {
726
+ for (const relKey of cascadingRelations(meta, 'persist')) {
730
727
  const relOpts = relationOf(meta, relKey);
731
728
  const holding = rows.filter((row) => row[relKey] !== undefined);
732
729
  if (!holdsForeignKey(relOpts) || !holding.length) {
@@ -747,11 +744,9 @@ export class AbstractQuerier {
747
744
  /** Writes each inserted row's children, one set of statements per relation whatever the number of rows. */
748
745
  async insertChildren(entity, rows) {
749
746
  const meta = getMeta(entity);
750
- const [idKey] = meta.ids;
751
- for (const relKey of childRelationKeys(meta, meta.relations)) {
752
- const writes = rows.flatMap((row) => (row[relKey] == null ? [] : [{ id: row[idKey], value: row[relKey] }]));
747
+ for (const relKey of ownedRelations(meta)) {
748
+ const writes = rows.flatMap((row) => (row[relKey] == null ? [] : [{ id: idOf(meta, row), value: row[relKey] }]));
753
749
  if (writes.length) {
754
- assertSoleId(meta, 'saving a relation');
755
750
  await this.saveChildren(entity, relKey, writes);
756
751
  }
757
752
  }
@@ -761,52 +756,63 @@ export class AbstractQuerier {
761
756
  * keeping what each does not write, and the parent's other children (a junction's other links) go.
762
757
  */
763
758
  async replaceChildren(entity, relKey, ids, value) {
764
- const meta = getMeta(entity);
765
- assertSoleId(meta, 'saving a relation');
766
- const relOpts = relationOf(meta, relKey);
767
- const relEntity = relOpts.entity();
768
- const relMeta = getMeta(relEntity);
769
- const parentColumn = soleParentColumn(relOpts);
770
- const listed = listedRows(value);
771
- if (relOpts.through) {
772
- const holder = relOpts.through();
773
- const [targetColumn] = targetKeyColumns(relOpts, 1);
774
- const targetIds = await this.saveTargets(entity, relKey, listed);
775
- await this.writeBatches(ids, 1, (batch) => this.deleteMany(holder, { $where: { [parentColumn]: batch, ...(targetIds.length && { [targetColumn]: { $nin: targetIds } }) } }, { hardDelete: true }));
776
- const linked = await this.internalFindMany(holder, {
777
- $where: { [parentColumn]: ids, [targetColumn]: targetIds },
778
- });
779
- const has = new Set(linked.map((link) => rowKey(link, [parentColumn, targetColumn])));
780
- const links = ids.flatMap((id) => targetIds.map((targetId) => ({ [parentColumn]: id, [targetColumn]: targetId })));
781
- const missing = links.filter((link) => !has.has(rowKey(link, [parentColumn, targetColumn])));
782
- await this.insertMany(holder, missing);
759
+ const relOpts = relationOf(getMeta(entity), relKey);
760
+ await (relOpts.through
761
+ ? this.replaceLinks(entity, relKey, relOpts, relOpts.through(), ids, listedRows(value))
762
+ : this.replaceOwned(entity, relKey, relOpts, ids, value));
763
+ }
764
+ /** A many-to-many's links: the targets are saved, the parent's links to any other go, and the missing ones are added. */
765
+ async replaceLinks(entity, relKey, relOpts, holder, ids, listed) {
766
+ const keyCount = getMeta(entity).ids.length;
767
+ const parents = parentJoins(relOpts, keyCount);
768
+ const targets = targetJoins(relOpts, keyCount);
769
+ const targetIds = await this.saveTargets(entity, relKey, listed);
770
+ await this.writeBatches(ids, keyCount, (batch) => this.deleteMany(holder, { $where: { ...childrenOf(parents, batch), ...(targetIds.length && childrenExcept(targets, targetIds)) } }, { hardDelete: true }));
771
+ if (!targetIds.length) {
783
772
  return;
784
773
  }
785
- const keptIds = listed.filter((row) => namesKey(relMeta, row)).map((row) => idOf(relMeta, row));
786
- await this.writeBatches(ids, 1, (batch) => this.deleteMany(relEntity, {
774
+ const linked = await this.internalFindMany(holder, {
775
+ $where: { $and: [childrenOf(parents, ids), childrenOf(targets, targetIds)] },
776
+ });
777
+ const columns = [...parents, ...targets].map(({ column }) => column);
778
+ const has = new Set(linked.map((link) => rowKey(link, columns)));
779
+ const links = ids.flatMap((id) => targetIds.map((targetId) => ({ ...pointAt(parents, id), ...pointAt(targets, targetId) })));
780
+ await this.insertMany(holder, links.filter((link) => !has.has(rowKey(link, columns))));
781
+ }
782
+ /** The rows a parent owns: those it does not list go, and the listed ones are saved pointing at it. */
783
+ async replaceOwned(entity, relKey, relOpts, ids, value) {
784
+ const keyCount = getMeta(entity).ids.length;
785
+ const relEntity = relOpts.entity();
786
+ const relMeta = getMeta(relEntity);
787
+ const parents = parentJoins(relOpts, keyCount);
788
+ const keptIds = listedRows(value)
789
+ .filter((row) => namesKey(relMeta, row))
790
+ .map((row) => idOf(relMeta, row));
791
+ await this.writeBatches(ids, keyCount, (batch) => this.deleteMany(relEntity, {
787
792
  $where: {
788
- [parentColumn]: batch,
789
- ...(keptIds.length && { [soleIdOf(relMeta, 'replacing the rows of a relation')]: { $nin: keptIds } }),
793
+ ...childrenOf(parents, batch),
794
+ ...(keptIds.length && childrenExcept(keyJoins(relMeta.ids), keptIds)),
790
795
  },
791
796
  }));
792
797
  await this.saveChildren(entity, relKey, ids.map((id) => ({ id, value })));
793
798
  }
794
799
  /** Writes each parent's children: rows pointed at their parent, or targets linked through the junction. */
795
800
  async saveChildren(entity, relKey, writes) {
796
- const relOpts = relationOf(getMeta(entity), relKey);
797
- const parentColumn = soleParentColumn(relOpts);
801
+ const meta = getMeta(entity);
802
+ const relOpts = relationOf(meta, relKey);
803
+ const parents = parentJoins(relOpts, meta.ids.length);
798
804
  // Each parent gets its own copies, so a row listed for two parents is written twice.
799
805
  const children = writes.flatMap(({ id, value }) => listedRows(value).map((row) => ({ id, row })));
800
806
  if (!children.length) {
801
807
  return;
802
808
  }
803
809
  if (!relOpts.through) {
804
- await this.saveMany(relOpts.entity(), children.map(({ id, row }) => ({ ...row, [parentColumn]: id })));
810
+ await this.saveMany(relOpts.entity(), children.map(({ id, row }) => ({ ...row, ...pointAt(parents, id) })));
805
811
  return;
806
812
  }
807
813
  const targetIds = await this.saveTargets(entity, relKey, children.map(({ row }) => row));
808
- const [targetColumn] = targetKeyColumns(relOpts, 1);
809
- await this.insertMany(relOpts.through(), children.map(({ id }, index) => ({ [parentColumn]: id, [targetColumn]: targetIds[index] })));
814
+ const targets = targetJoins(relOpts, meta.ids.length);
815
+ await this.insertMany(relOpts.through(), children.map(({ id }, index) => ({ ...pointAt(parents, id), ...pointAt(targets, targetIds[index]) })));
810
816
  }
811
817
  /**
812
818
  * Saves the rows a relation points at, each one's id what the pointer needs: a MySQL batch mixing supplied and
@@ -829,7 +835,7 @@ export class AbstractQuerier {
829
835
  async deleteChildren(entity, ids, opts) {
830
836
  const meta = getMeta(entity);
831
837
  const soft = !!meta.softDelete && !opts?.hardDelete;
832
- for (const relKey of filterPersistableRelationKeys(meta, meta.relations, 'delete')) {
838
+ for (const relKey of cascadingRelations(meta, 'delete')) {
833
839
  const relOpts = relationOf(meta, relKey);
834
840
  const target = relOpts.through ? relOpts.through() : relOpts.entity();
835
841
  if (soft && !getMeta(target).softDelete) {
@@ -57,7 +57,10 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
57
57
  * so those count apart.
58
58
  */
59
59
  protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
60
+ /** The rows a read of `entity` matches, each as its statement reads it. */
60
61
  private selectRows;
62
+ /** The rows of a read the dialect builds, each as the terms it returns say. */
63
+ private readRows;
61
64
  /**
62
65
  * The one read not going through `all`, so it checks its budget and connects on its own; its values go as
63
66
  * the context holds them, each normalized as it was bound. The tuning is guarded as `selectRows` says.
@@ -69,19 +72,6 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
69
72
  * closes itself when the loop exits early.
70
73
  */
71
74
  protected internalStream(query: string, values?: unknown[]): AsyncIterable<RawRow>;
72
- /**
73
- * How each row of one statement becomes the entity's, for a read, a stream and a to-many alike: its dotted
74
- * columns nested as the first row names them, and its values decoded as `hydratableFields` says, resolved
75
- * once. Both live with the dialect, because a `sparsevec` is only sparse on Postgres.
76
- */
77
- private rowReader;
78
- /**
79
- * One row of {@link rowReader}. A related row arrives as its parent's statement read it: a to-one
80
- * joined and unflattened, there only when its key is, since an unmatched join still fills a computed
81
- * column or a to-many's empty array; a to-many as a JSON array, which a driver may hand over as text.
82
- * Each is an object of its own, so the walk reaches none twice.
83
- */
84
- private hydrateFields;
85
75
  /**
86
76
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
87
77
  * a caller supplying their own `types` replaces the decoding the pools do at the wire, and reads a `NULL`
@@ -1,13 +1,12 @@
1
1
  import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
2
- import { decodeColumn } from '../dialect/hydrateColumn.js';
3
2
  import { getMeta, namesKey } from '../entity/index.js';
4
- import { COUNT_RESULT_KEY } from '../type/index.js';
5
- import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement, isRecord, obtainAttrsPaths, unflatObject, } from '../util/index.js';
3
+ import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement } from '../util/index.js';
6
4
  import { statementOf } from '../util/raw.js';
7
5
  import { UqlUsageError } from '../util/uqlError.js';
8
6
  import { AbstractQuerier } from './abstractQuerier.js';
9
7
  import { streamViaCursor } from './cursorStream.js';
10
8
  import { enrichError } from './queryError.js';
9
+ import { rowReader } from './rowReader.js';
11
10
  /**
12
11
  * Row indexes split by whether the row names its key, the one thing that changes what an insert can
13
12
  * report; coarser than {@link groupByInsertShape} on purpose, since an insert fills a missing column with `DEFAULT`.
@@ -47,8 +46,13 @@ function groupByInsertShape(meta, payload) {
47
46
  */
48
47
  function chunkWithinLimits(meta, payload, group, maxBindValues, maxRows = Infinity) {
49
48
  const width = (indexes) => getInsertFieldKeys(meta, indexes.map((index) => payload[index])).length;
50
- const size = Math.max(1, Math.min(maxRows, Math.floor(maxBindValues / (width(group) || 1))));
51
- return chunk(group, size).flatMap((indexes) => (width(indexes) ? [indexes] : chunk(indexes, 1)));
49
+ const groupWidth = width(group);
50
+ if (!groupWidth) {
51
+ return chunk(group, 1);
52
+ }
53
+ const chunks = chunk(group, Math.max(1, Math.min(maxRows, Math.floor(maxBindValues / groupWidth))));
54
+ // A split can leave a chunk whose rows name no column; one chunk is the whole group, which names some.
55
+ return chunks.length === 1 ? chunks : chunks.flatMap((indexes) => (width(indexes) ? [indexes] : chunk(indexes, 1)));
52
56
  }
53
57
  export class AbstractSqlQuerier extends AbstractQuerier {
54
58
  dialect;
@@ -118,7 +122,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
118
122
  this.assertBindBudget(values);
119
123
  return this.serialize(async () => {
120
124
  await this.lazyConnect();
121
- return this.timed(sql, values, () => task(sql, this.dialect.normalizeValues(values)));
125
+ return this.timed(sql, values, () => task(sql, values));
122
126
  });
123
127
  }
124
128
  /**
@@ -141,7 +145,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
141
145
  }
142
146
  }
143
147
  async internalFindMany(entity, q, opts) {
144
- return (await this.selectRows(entity, q, opts)).map(this.rowReader(entity));
148
+ return this.selectRows(entity, q, opts);
145
149
  }
146
150
  /** Every row `q` matches past its page, deduplicated where it reads `$distinct`. */
147
151
  countUnpaged(entity, q, opts) {
@@ -164,8 +168,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
164
168
  for (const row of rows) {
165
169
  delete row[TOTAL_ALIAS];
166
170
  }
167
- return [rows.map(this.rowReader(entity)), total];
171
+ return [rows, total];
168
172
  }
173
+ /** The rows a read of `entity` matches, each as its statement reads it. */
169
174
  async selectRows(entity, q, opts, totalAlias) {
170
175
  // Guarded rather than awaited unconditionally, here and in the stream below: an `await` on this
171
176
  // path defers a microtask on every read, which reorders the two statements `findManyAndCount`
@@ -173,7 +178,15 @@ export class AbstractSqlQuerier extends AbstractQuerier {
173
178
  if (q.$candidates !== undefined) {
174
179
  await this.applyVectorTuning(entity, q);
175
180
  }
176
- return this.query((ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias));
181
+ return this.readRows((ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias));
182
+ }
183
+ /** The rows of a read the dialect builds, each as the terms it returns say. */
184
+ async readRows(build) {
185
+ let terms = [];
186
+ const rows = await this.query((ctx) => {
187
+ terms = build(ctx);
188
+ });
189
+ return rows.map(rowReader(terms));
177
190
  }
178
191
  /**
179
192
  * The one read not going through `all`, so it checks its budget and connects on its own; its values go as
@@ -181,13 +194,12 @@ export class AbstractSqlQuerier extends AbstractQuerier {
181
194
  */
182
195
  async *internalFindManyStream(entity, q, opts) {
183
196
  const ctx = this.dialect.createContext();
184
- this.dialect.find(ctx, entity, q, opts);
197
+ const read = rowReader(this.dialect.find(ctx, entity, q, opts));
185
198
  this.assertBindBudget(ctx.values);
186
199
  if (q.$candidates !== undefined) {
187
200
  await this.applyVectorTuning(entity, q);
188
201
  }
189
202
  await this.lazyConnect();
190
- const read = this.rowReader(entity);
191
203
  for await (const row of this.timedStream(ctx.sql, ctx.values, this.internalStream(ctx.sql, ctx.values))) {
192
204
  yield read(row);
193
205
  }
@@ -204,68 +216,6 @@ export class AbstractSqlQuerier extends AbstractQuerier {
204
216
  }
205
217
  yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, !!this.scopeHere());
206
218
  }
207
- /**
208
- * How each row of one statement becomes the entity's, for a read, a stream and a to-many alike: its dotted
209
- * columns nested as the first row names them, and its values decoded as `hydratableFields` says, resolved
210
- * once. Both live with the dialect, because a `sparsevec` is only sparse on Postgres.
211
- */
212
- rowReader(entity) {
213
- const meta = getMeta(entity);
214
- const fields = this.dialect.hydratableFields(entity);
215
- let attrsPaths;
216
- return (row) => {
217
- attrsPaths ??= obtainAttrsPaths(row);
218
- const found = unflatObject(row, attrsPaths);
219
- this.hydrateFields(meta, fields, found);
220
- return found;
221
- };
222
- }
223
- /**
224
- * One row of {@link rowReader}. A related row arrives as its parent's statement read it: a to-one
225
- * joined and unflattened, there only when its key is, since an unmatched join still fills a computed
226
- * column or a to-many's empty array; a to-many as a JSON array, which a driver may hand over as text.
227
- * Each is an object of its own, so the walk reaches none twice.
228
- */
229
- hydrateFields(meta, fields, dto) {
230
- const row = dto;
231
- for (const [key, kind] of fields) {
232
- const value = row[key];
233
- if (value != null) {
234
- row[key] = decodeColumn(value, kind);
235
- }
236
- }
237
- // A tally read inside the statement comes back as its driver reads a COUNT, which on some is text.
238
- const counts = row[COUNT_RESULT_KEY];
239
- if (isRecord(counts)) {
240
- for (const relKey in counts) {
241
- counts[relKey] = Number(counts[relKey]);
242
- }
243
- }
244
- // The value is read before the relation's target is resolved: a query that populated nothing
245
- // still walks every relation the entity declares, and `rel.entity()` is a call per row per
246
- // relation that only the populated ones need.
247
- for (const key in meta.relations) {
248
- const value = row[key];
249
- const rel = meta.relations[key];
250
- if (!value || !rel)
251
- continue;
252
- const relEntity = rel.entity();
253
- if (isRecord(value)) {
254
- const relMeta = getMeta(relEntity);
255
- if (value[relMeta.ids[0]] == null) {
256
- delete row[key];
257
- }
258
- else {
259
- this.hydrateFields(relMeta, this.dialect.hydratableFields(relEntity), value);
260
- }
261
- }
262
- else {
263
- // A to-many's rows, as flat as a statement's own.
264
- const rows = Array.isArray(value) ? value : JSON.parse(String(value));
265
- row[key] = rows.map(this.rowReader(relEntity));
266
- }
267
- }
268
- }
269
219
  /**
270
220
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
271
221
  * a caller supplying their own `types` replaces the decoding the pools do at the wire, and reads a `NULL`
@@ -282,17 +232,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
282
232
  return this.runCount((ctx) => this.dialect.estimatedCount(ctx, entity));
283
233
  }
284
234
  async internalAggregate(entity, q, opts) {
285
- const rows = await this.query((ctx) => this.dialect.aggregate(ctx, entity, q, opts));
286
- const hydratable = this.dialect.hydratableAggregates(entity, q);
287
- for (const row of rows) {
288
- const cells = row;
289
- for (const [alias, kind] of hydratable) {
290
- if (cells[alias] != null) {
291
- cells[alias] = decodeColumn(cells[alias], kind);
292
- }
293
- }
294
- }
295
- return rows;
235
+ return this.readRows((ctx) => this.dialect.aggregate(ctx, entity, q, opts));
296
236
  }
297
237
  async internalInsertMany(entity, rows) {
298
238
  const meta = getMeta(entity);
@@ -0,0 +1,8 @@
1
+ import type { SelectTerm } from '../dialect/abstractSqlDialect.js';
2
+ import type { RawRow } from '../type/index.js';
3
+ /**
4
+ * How each row of one statement becomes the entity's, from the terms its SQL was written with: its dotted
5
+ * columns nested, a joined row kept only where its key is, a to-many's rows read by their own terms, and each
6
+ * value the driver leaves to the field decoded. Resolved once per statement, so a row pays for no discovery.
7
+ */
8
+ export declare function rowReader<T>(terms: readonly SelectTerm[]): (row: RawRow) => T;
@@ -0,0 +1,88 @@
1
+ import { DECODERS } from '../dialect/hydrateColumn.js';
2
+ import { isRecord } from '../util/index.js';
3
+ const TOP = [];
4
+ const slotAt = (path) => ({ parent: path.slice(0, -1), key: path[path.length - 1] });
5
+ /**
6
+ * How each row of one statement becomes the entity's, from the terms its SQL was written with: its dotted
7
+ * columns nested, a joined row kept only where its key is, a to-many's rows read by their own terms, and each
8
+ * value the driver leaves to the field decoded. Resolved once per statement, so a row pays for no discovery.
9
+ */
10
+ export function rowReader(terms) {
11
+ const dotted = new Map();
12
+ const joined = [];
13
+ const mapped = [];
14
+ for (const { key, kind, kinds, rows, joinedKey } of terms) {
15
+ for (const [field, fieldKind] of kinds ?? []) {
16
+ mapped.push({ parent: TOP, key: field, map: DECODERS[fieldKind] });
17
+ }
18
+ if (key === undefined) {
19
+ continue;
20
+ }
21
+ const path = key.split('.');
22
+ const slot = slotAt(path);
23
+ if (path.length > 1) {
24
+ dotted.set(key, path);
25
+ if (joinedKey) {
26
+ joined.push({ ...slotAt(slot.parent), idKey: slot.key });
27
+ }
28
+ }
29
+ if (rows) {
30
+ const read = rowReader(rows);
31
+ mapped.push({ ...slot, map: (value) => (Array.isArray(value) ? value : JSON.parse(String(value))).map(read) });
32
+ }
33
+ if (kind) {
34
+ mapped.push({ ...slot, map: DECODERS[kind] });
35
+ }
36
+ }
37
+ const [firstDotted] = dotted.keys();
38
+ return (raw) => {
39
+ // All of a row's columns are flat or none is: SQL Server's `FOR JSON` nests a related row itself.
40
+ const row = firstDotted !== undefined && firstDotted in raw ? nest(raw, dotted) : raw;
41
+ for (const { parent, key, idKey } of joined) {
42
+ const holder = holderAt(row, parent);
43
+ const joinedRow = holder?.[key];
44
+ if (holder && isRecord(joinedRow) && joinedRow[idKey] == null) {
45
+ delete holder[key];
46
+ }
47
+ }
48
+ for (const { parent, key, map } of mapped) {
49
+ const holder = holderAt(row, parent);
50
+ const value = holder?.[key];
51
+ if (holder && value != null) {
52
+ holder[key] = map(value);
53
+ }
54
+ }
55
+ // A raw row becomes the entity here, as a parsed JSON value does: its shape is what the statement selected.
56
+ return row;
57
+ };
58
+ }
59
+ /** `row` with its dotted columns nested under the paths `dotted` names. */
60
+ function nest(row, dotted) {
61
+ const nested = {};
62
+ for (const column in row) {
63
+ const path = dotted.get(column);
64
+ if (!path) {
65
+ nested[column] = row[column];
66
+ continue;
67
+ }
68
+ let target = nested;
69
+ for (let i = 0; i < path.length - 1; i++) {
70
+ const next = target[path[i]];
71
+ target = isRecord(next) ? next : (target[path[i]] = {});
72
+ }
73
+ target[path[path.length - 1]] = row[column];
74
+ }
75
+ return nested;
76
+ }
77
+ /** The object at `path` in `row`, `row` itself for an empty one, if every step to it is one. */
78
+ function holderAt(row, path) {
79
+ let target = row;
80
+ for (const step of path) {
81
+ const next = target[step];
82
+ if (!isRecord(next)) {
83
+ return undefined;
84
+ }
85
+ target = next;
86
+ }
87
+ return target;
88
+ }
@@ -1,4 +1,4 @@
1
- import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from '../dialect/abstractSqlDialect.js';
1
+ import { AbstractSqlDialect, type DerivedRelation, type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
2
2
  import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
3
3
  import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type SqlValues, type VectorDistance, type VectorMetric } from '../type/index.js';
4
4
  /** What SQLite and the engines derived from it have. */
@@ -43,7 +43,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
43
43
  /** SQLite's own spelling of no limit. */
44
44
  protected readonly unboundedLimit = "-1";
45
45
  /** `json_group_array` of each row's object, ordered by the sort terms carried out beside them. */
46
- protected appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
46
+ protected appendRelationArray(ctx: QueryContext, rows: RelationRows): readonly SelectTerm[];
47
47
  /**
48
48
  * `json_object` of each key and its column. A row wider than one call takes inserts the rest into it,
49
49
  * addressing each key as one path segment.
@@ -137,8 +137,9 @@ export class SqliteDialect extends AbstractSqlDialect {
137
137
  unboundedLimit = '-1';
138
138
  /** `json_group_array` of each row's object, ordered by the sort terms carried out beside them. */
139
139
  appendRelationArray(ctx, rows) {
140
- const { from, pairs, order } = this.derivedRelation(ctx, rows);
140
+ const { terms, from, pairs, order } = this.derivedRelation(ctx, rows);
141
141
  ctx.append(`(SELECT json_group_array(${this.jsonObject(pairs)}${order ? ` ORDER BY ${order}` : ''}) FROM ${from})`);
142
+ return terms;
142
143
  }
143
144
  /**
144
145
  * `json_object` of each key and its column. A row wider than one call takes inserts the rest into it,
@@ -22,17 +22,8 @@ export declare function getFieldCallbackValue(val: OnFieldCallback): string | nu
22
22
  export declare function getSoftDeleteValue(field: FieldOptions): string | number | bigint | boolean | Date | import("../type/utility.js").JsonBrand | QueryRaw | readonly number[] | readonly import("../type/utility.js").JsonBrand[] | Uint8Array<ArrayBufferLike>;
23
23
  /** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
24
24
  export declare function fillOnFields<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, payload: R | R[], callbackKey: CallbackKey): R[];
25
- /**
26
- * The relation keys present in `payload` whose cascade configuration allows `action`. Only
27
- * `payload`'s keys are read, so any keys-bearing object works (an entity, an update payload,
28
- * or `meta.relations` itself to enumerate every cascadable relation).
29
- */
30
- export declare function filterPersistableRelationKeys<E>(meta: EntityMeta<E>, payload: object, action: CascadeType): RelationKey<E>[];
31
- /**
32
- * Whether deleting this entity has to delete anything else, which is the reason a delete resolves the
33
- * matching ids before issuing anything: a child is reached through the ids of its parent.
34
- */
35
- export declare function cascadesOnDelete<E>(meta: EntityMeta<E>): boolean;
25
+ /** The relations a write cascades `action` to, in declaration order. */
26
+ export declare function cascadingRelations<E>(meta: EntityMeta<E>, action: CascadeType): RelationKey<E>[];
36
27
  export declare function isCascadable(action: CascadeType, configuration?: boolean | CascadeType): boolean;
37
28
  /**
38
29
  * Whether `q` carries an ordering or a page, so a write has to settle its rows with a read and name
@@ -50,7 +50,7 @@ export function getInsertFieldKeys(meta, payloads) {
50
50
  for (const record of payloads) {
51
51
  addInsertFieldKeys(meta, record, seen, keys);
52
52
  }
53
- return [...keys, ...fieldKeys(meta, (field) => field.onInsert !== undefined).filter((key) => !seen.has(key))];
53
+ return [...keys, ...filledKeys(meta, 'onInsert').filter((key) => !seen.has(key))];
54
54
  }
55
55
  export function getFieldCallbackValue(val) {
56
56
  return typeof val === 'function' ? val() : val;
@@ -65,9 +65,7 @@ export function getSoftDeleteValue(field) {
65
65
  /** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
66
66
  export function fillOnFields(meta, payload, callbackKey) {
67
67
  const payloads = Array.isArray(payload) ? payload : [payload];
68
- // By presence, not truthiness, as `addInsertFieldKeys` above reads it: `onInsert: 0` and `onInsert: ''`
69
- // are values a caller meant, and a falsy one was silently never filled.
70
- const keys = fieldKeys(meta, (field) => field[callbackKey] !== undefined);
68
+ const keys = filledKeys(meta, callbackKey);
71
69
  if (keys.length === 0) {
72
70
  return payloads;
73
71
  }
@@ -80,24 +78,13 @@ export function fillOnFields(meta, payload, callbackKey) {
80
78
  }
81
79
  return payloads;
82
80
  }
83
- /**
84
- * The relation keys present in `payload` whose cascade configuration allows `action`. Only
85
- * `payload`'s keys are read, so any keys-bearing object works (an entity, an update payload,
86
- * or `meta.relations` itself to enumerate every cascadable relation).
87
- */
88
- export function filterPersistableRelationKeys(meta, payload, action) {
89
- const keys = getKeys(payload);
90
- return keys.filter((key) => {
91
- const relOpts = meta.relations[key];
92
- return relOpts && isCascadable(action, relOpts.cascade);
93
- });
81
+ /** The fields `callbackKey` fills where the caller left them unset. By presence: `onInsert: 0` is a value meant. */
82
+ function filledKeys(meta, callbackKey) {
83
+ return fieldKeys(meta, (field) => field[callbackKey] !== undefined);
94
84
  }
95
- /**
96
- * Whether deleting this entity has to delete anything else, which is the reason a delete resolves the
97
- * matching ids before issuing anything: a child is reached through the ids of its parent.
98
- */
99
- export function cascadesOnDelete(meta) {
100
- return filterPersistableRelationKeys(meta, meta.relations, 'delete').length > 0;
85
+ /** The relations a write cascades `action` to, in declaration order. */
86
+ export function cascadingRelations(meta, action) {
87
+ return getKeys(meta.relations).filter((key) => isCascadable(action, meta.relations[key]?.cascade));
101
88
  }
102
89
  export function isCascadable(action, configuration) {
103
90
  if (typeof configuration === 'boolean') {