uql-orm 0.98.0 → 0.100.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 (174) hide show
  1. package/LICENSE.md +22 -0
  2. package/README.md +1 -1
  3. package/dist/browser/uql-browser.min.js +2 -2
  4. package/dist/browser/uql-browser.min.js.map +5 -5
  5. package/dist/bunSql/bunSql.util.js +2 -2
  6. package/dist/bunSql/bunSqlQuerier.js +0 -1
  7. package/dist/bunSql/bunSqlQuerierPool.js +1 -1
  8. package/dist/cockroachdb/cockroachDialect.js +1 -0
  9. package/dist/context/context.browser.d.ts +5 -0
  10. package/dist/context/context.browser.js +21 -11
  11. package/dist/context/context.d.ts +5 -0
  12. package/dist/context/context.js +8 -3
  13. package/dist/dialect/abstractDialect.js +4 -2
  14. package/dist/dialect/abstractSqlDialect.d.ts +5 -5
  15. package/dist/dialect/abstractSqlDialect.js +26 -18
  16. package/dist/dialect/aliases.d.ts +0 -2
  17. package/dist/dialect/aliases.js +0 -2
  18. package/dist/dialect/hydrateColumn.d.ts +3 -3
  19. package/dist/dialect/hydrateColumn.js +1 -0
  20. package/dist/dialect/index.js +0 -2
  21. package/dist/dialect/jsonSql.d.ts +2 -3
  22. package/dist/dialect/jsonSql.js +4 -6
  23. package/dist/dialect/mysqlLikeSqlDialect.d.ts +1 -1
  24. package/dist/dialect/mysqlLikeSqlDialect.js +5 -3
  25. package/dist/dialect/operators.d.ts +2 -3
  26. package/dist/dialect/operators.js +3 -4
  27. package/dist/dialect/pgLikeSqlDialect.js +12 -12
  28. package/dist/entity/decorator/members.d.ts +4 -12
  29. package/dist/entity/metadata/definition.js +8 -5
  30. package/dist/http/handler.d.ts +6 -6
  31. package/dist/http/handler.js +20 -5
  32. package/dist/index.d.ts +6 -5
  33. package/dist/index.js +6 -5
  34. package/dist/{maria → mariadb}/mariadbQuerier.js +1 -1
  35. package/dist/migrate/builder/columnBuilder.d.ts +3 -3
  36. package/dist/migrate/builder/columnBuilder.js +1 -1
  37. package/dist/migrate/builder/index.d.ts +0 -3
  38. package/dist/migrate/builder/index.js +0 -3
  39. package/dist/migrate/builder/migrationBuilder.d.ts +6 -6
  40. package/dist/migrate/builder/migrationBuilder.js +7 -7
  41. package/dist/migrate/builder/tableBuilder.d.ts +25 -25
  42. package/dist/migrate/builder/tableBuilder.js +5 -5
  43. package/dist/migrate/builder/types.d.ts +37 -37
  44. package/dist/migrate/cli-config.d.ts +9 -0
  45. package/dist/migrate/cli-config.js +14 -4
  46. package/dist/migrate/cli.js +9 -18
  47. package/dist/migrate/codegen/entityCodeGenerator.js +1 -1
  48. package/dist/migrate/codegen/migrationFile.d.ts +7 -7
  49. package/dist/migrate/codegen/migrationFile.js +11 -12
  50. package/dist/migrate/ddl/indexCapabilities.d.ts +2 -0
  51. package/dist/migrate/ddl/indexCapabilities.js +6 -0
  52. package/dist/migrate/ddl/indexDdl.d.ts +8 -0
  53. package/dist/migrate/ddl/indexDdl.js +22 -6
  54. package/dist/migrate/generator/definitionToNode.d.ts +1 -1
  55. package/dist/migrate/generator/definitionToNode.js +1 -1
  56. package/dist/migrate/index.d.ts +1 -3
  57. package/dist/migrate/index.js +0 -3
  58. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +11 -15
  59. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +13 -15
  60. package/dist/migrate/introspection/mssqlIntrospector.d.ts +5 -5
  61. package/dist/migrate/introspection/mssqlIntrospector.js +24 -28
  62. package/dist/migrate/introspection/mysqlIntrospector.d.ts +5 -5
  63. package/dist/migrate/introspection/mysqlIntrospector.js +31 -37
  64. package/dist/migrate/introspection/postgresIntrospector.d.ts +13 -13
  65. package/dist/migrate/introspection/postgresIntrospector.js +35 -39
  66. package/dist/migrate/introspection/registry.js +1 -1
  67. package/dist/migrate/introspection/sqliteIntrospector.d.ts +6 -4
  68. package/dist/migrate/introspection/sqliteIntrospector.js +15 -12
  69. package/dist/migrate/migrationLock.d.ts +38 -0
  70. package/dist/migrate/migrationLock.js +103 -0
  71. package/dist/migrate/migrationTarget.d.ts +6 -2
  72. package/dist/migrate/migrationTarget.js +30 -14
  73. package/dist/migrate/migrator.d.ts +47 -37
  74. package/dist/migrate/migrator.js +154 -131
  75. package/dist/migrate/schemaGenerator.d.ts +3 -1
  76. package/dist/migrate/schemaGenerator.js +14 -5
  77. package/dist/migrate/storage/databaseStorage.d.ts +28 -20
  78. package/dist/migrate/storage/databaseStorage.js +36 -54
  79. package/dist/migrate/storage/index.d.ts +0 -1
  80. package/dist/migrate/storage/index.js +0 -1
  81. package/dist/{mongo → mongodb}/index.d.ts +0 -1
  82. package/dist/{mongo → mongodb}/index.js +0 -1
  83. package/dist/{mongo → mongodb}/mongoCommand.d.ts +17 -1
  84. package/dist/{mongo → mongodb}/mongoCommand.js +15 -2
  85. package/dist/{mongo → mongodb}/mongoDialect.js +8 -12
  86. package/dist/{mongo → mongodb}/mongoIntrospector.js +12 -3
  87. package/dist/{mongo → mongodb}/mongoMigrationStorage.d.ts +5 -5
  88. package/dist/{mongo → mongodb}/mongoMigrationStorage.js +8 -12
  89. package/dist/{mongo → mongodb}/mongoQuerier.d.ts +3 -1
  90. package/dist/{mongo → mongodb}/mongoSchemaGenerator.d.ts +11 -1
  91. package/dist/{mongo → mongodb}/mongoSchemaGenerator.js +56 -11
  92. package/dist/{mongo → mongodb}/mongodbQuerier.d.ts +7 -18
  93. package/dist/{mongo → mongodb}/mongodbQuerier.js +44 -78
  94. package/dist/mssql/mssqlDialect.d.ts +6 -4
  95. package/dist/mssql/mssqlDialect.js +20 -10
  96. package/dist/mssql/mssqlQuerier.d.ts +2 -2
  97. package/dist/mssql/mssqlQuerier.js +3 -3
  98. package/dist/mssql/mssqlQuerierPool.d.ts +1 -1
  99. package/dist/mssql/mssqlQuerierPool.js +2 -2
  100. package/dist/mysql/mysql2Querier.js +1 -5
  101. package/dist/namingStrategy/defaultNamingStrategy.d.ts +0 -1
  102. package/dist/namingStrategy/defaultNamingStrategy.js +0 -3
  103. package/dist/pglite/pgliteDialect.d.ts +3 -0
  104. package/dist/pglite/pgliteDialect.js +3 -1
  105. package/dist/pglite/pgliteQuerier.d.ts +2 -0
  106. package/dist/pglite/pgliteQuerier.js +4 -0
  107. package/dist/postgres/postgresDialect.d.ts +3 -4
  108. package/dist/postgres/postgresDialect.js +5 -6
  109. package/dist/querier/abstractQuerier.d.ts +119 -36
  110. package/dist/querier/abstractQuerier.js +465 -161
  111. package/dist/querier/abstractQuerierPool.d.ts +5 -6
  112. package/dist/querier/abstractQuerierPool.js +20 -6
  113. package/dist/querier/abstractSqlQuerier.d.ts +15 -10
  114. package/dist/querier/abstractSqlQuerier.js +54 -47
  115. package/dist/querier/abstractSqlQuerierPool.d.ts +5 -3
  116. package/dist/querier/abstractSqlQuerierPool.js +7 -4
  117. package/dist/querier/transaction.d.ts +46 -0
  118. package/dist/querier/transaction.js +56 -0
  119. package/dist/schema/canonicalType.js +2 -2
  120. package/dist/schema/schemaASTDiffer.d.ts +11 -3
  121. package/dist/schema/schemaASTDiffer.js +20 -8
  122. package/dist/sqlite/nodeSqliteQuerierPool.d.ts +1 -1
  123. package/dist/sqlite/nodeSqliteQuerierPool.js +1 -1
  124. package/dist/sqlite/sqliteDialect.d.ts +1 -1
  125. package/dist/sqlite/sqliteDialect.js +3 -1
  126. package/dist/sqlite/sqliteQuerier.d.ts +2 -0
  127. package/dist/sqlite/sqliteQuerier.js +4 -0
  128. package/dist/sqlite/sqliteQuerierPool.d.ts +4 -4
  129. package/dist/sqlite/sqliteQuerierPool.js +1 -1
  130. package/dist/type/dialect.d.ts +16 -2
  131. package/dist/type/entity.d.ts +32 -32
  132. package/dist/type/migration.d.ts +10 -27
  133. package/dist/type/namingStrategy.d.ts +0 -4
  134. package/dist/type/querier.d.ts +18 -10
  135. package/dist/type/query.d.ts +7 -22
  136. package/dist/type/queryRaw.d.ts +11 -6
  137. package/dist/type/queryRaw.js +2 -3
  138. package/dist/type/universalQuerier.d.ts +26 -28
  139. package/dist/type/utility.d.ts +7 -2
  140. package/dist/util/dialect.util.d.ts +2 -2
  141. package/dist/util/dialect.util.js +4 -1
  142. package/dist/util/field.util.d.ts +12 -0
  143. package/dist/util/field.util.js +24 -0
  144. package/dist/util/hook.util.d.ts +3 -2
  145. package/dist/util/query.util.d.ts +5 -0
  146. package/dist/util/query.util.js +34 -1
  147. package/dist/util/raw.d.ts +8 -2
  148. package/dist/util/raw.js +22 -0
  149. package/dist/util/relationQuery.util.d.ts +2 -0
  150. package/dist/util/relationQuery.util.js +4 -0
  151. package/dist/util/sql.util.d.ts +0 -5
  152. package/dist/util/sql.util.js +3 -9
  153. package/dist/util/uqlError.d.ts +0 -6
  154. package/dist/util/uqlError.js +0 -5
  155. package/package.json +20 -26
  156. package/skills/uql-orm/SKILL.md +13 -10
  157. package/dist/migrate/storage/jsonStorage.d.ts +0 -14
  158. package/dist/migrate/storage/jsonStorage.js +0 -33
  159. /package/dist/{maria → mariadb}/index.d.ts +0 -0
  160. /package/dist/{maria → mariadb}/index.js +0 -0
  161. /package/dist/{maria → mariadb}/mariaDialect.d.ts +0 -0
  162. /package/dist/{maria → mariadb}/mariaDialect.js +0 -0
  163. /package/dist/{maria → mariadb}/mariadbQuerier.d.ts +0 -0
  164. /package/dist/{maria → mariadb}/mariadbQuerierPool.d.ts +0 -0
  165. /package/dist/{maria → mariadb}/mariadbQuerierPool.js +0 -0
  166. /package/dist/{mongo → mongodb}/mongoDialect.d.ts +0 -0
  167. /package/dist/{mongo → mongodb}/mongoIntrospector.d.ts +0 -0
  168. /package/dist/{mongo → mongodb}/mongoQuerier.js +0 -0
  169. /package/dist/{mongo → mongodb}/mongodbQuerierPool.d.ts +0 -0
  170. /package/dist/{mongo → mongodb}/mongodbQuerierPool.js +0 -0
  171. /package/dist/{mongo → mongodb}/textLanguage.d.ts +0 -0
  172. /package/dist/{mongo → mongodb}/textLanguage.js +0 -0
  173. /package/dist/{mongo → mongodb}/vectorDistance.d.ts +0 -0
  174. /package/dist/{mongo → mongodb}/vectorDistance.js +0 -0
@@ -1,6 +1,7 @@
1
1
  import type { AbstractDialect } from '../dialect/abstractDialect.js';
2
- import type { CursorPage, EntityData, EntityId, EntityWrite, ExtraOptions, FieldKey, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryKeysetProjected, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, UpdateWrite, WrittenId } from '../type/index.js';
2
+ import type { BooleanLike, CursorPage, EntityData, EntityId, EntityWrite, ExtraOptions, FieldKey, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryKeysetProjected, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, PrimaryKey, RelationKey, SavepointCommand, TransactionOptions, Type, UpdatePayload, UpdateWrite, ReturningResult, WriteOptions, WrittenId } from '../type/index.js';
3
3
  import { LoggerWrapper } from '../util/index.js';
4
+ import { type TransactionScope } from './transaction.js';
4
5
  /** Base class for all database queriers. */
5
6
  export declare abstract class AbstractQuerier implements Querier {
6
7
  #private;
@@ -19,6 +20,11 @@ export declare abstract class AbstractQuerier implements Querier {
19
20
  protected readonly logger: LoggerWrapper;
20
21
  abstract readonly dialect: AbstractDialect;
21
22
  constructor(extra?: ExtraOptions | undefined);
23
+ /**
24
+ * What the transaction this querier opens belongs to: the querier itself, its own connection, unless every
25
+ * querier of its pool is one session (SQLite, PGlite), whose queriers then name that handle and share it.
26
+ */
27
+ protected get connection(): object;
22
28
  /** What every read is checked for before it runs, whichever backend runs it. */
23
29
  protected validateReadQuery<E extends object>(entity: Type<E>, q: Query<E>): void;
24
30
  /**
@@ -93,19 +99,39 @@ export declare abstract class AbstractQuerier implements Querier {
93
99
  protected abstract internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
94
100
  /** Abstract outright: nothing is shared to do around it. See {@link UniversalQuerier.estimatedCount}. */
95
101
  abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
96
- insertOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
102
+ insertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V>): Promise<ReturningResult<S, WrittenId<E> | undefined, QueryFindResult<E, S, V>>>;
103
+ insertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V>): Promise<ReturningResult<S, (WrittenId<E> | undefined)[], QueryFindResult<E, S, V>[]>>;
104
+ /**
105
+ * The ids of the rows inserted, in payload order. The `onInsert` values are filled before the write, so
106
+ * the after hooks and the ids read the same rows the statement wrote.
107
+ */
108
+ private insertIds;
97
109
  /**
98
- * The `onInsert` values are filled here, before the write, so the after hooks and the ids read the
99
- * same rows the statement wrote.
110
+ * The ids `write` reports, or, where `opts` asks for `returning`, the rows they name, read back in the same
111
+ * transaction with only the fields it lists.
112
+ */
113
+ private writeReturning;
114
+ /** The rows `q` matches with the fields `keys` names and their keys, through `afterLoad` as a read's are. */
115
+ private readReturning;
116
+ /** The rows `ids` names, in their order, each with only the fields `keys` names. */
117
+ private readWritten;
118
+ /**
119
+ * Writes `rows` and their relations: the to-ones they hold the keys of first, so each row inserts
120
+ * pointing at its own, then the rows, then their children by the keys the rows got. An insert, and the
121
+ * insert half of a read upsert.
100
122
  */
101
- insertMany<E extends object>(entity: Type<E>, payload: readonly EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
102
- /** Fills and guards `rows`, then writes them and their relations: an insert, and the insert half of a read upsert. */
103
123
  private insertRows;
104
124
  /** Writes `rows`, its columns only, and onto each one the key the database generated for it, where it can tell. */
105
125
  protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
106
- updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
107
- /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
108
- updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
126
+ updateOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V> | undefined>>;
127
+ updateMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V>[]>>;
128
+ /**
129
+ * The number of rows the update changed, or the rows `returning` reads back: their ids settled first, so a
130
+ * payload changing what `$where` reads still names them, and read back by those ids in the same transaction.
131
+ */
132
+ private updateWhere;
133
+ /** Updates the rows `q` matches between the update hooks, atomically where the payload writes relations too. */
134
+ private updateMatching;
109
135
  /**
110
136
  * The write every update runs, matching the version `lockKey` names where one is being held. Only a
111
137
  * restore passes none: it writes no content, so there is no update of anyone's to lose.
@@ -130,7 +156,7 @@ export declare abstract class AbstractQuerier implements Querier {
130
156
  * in one transaction where there are several, so a write split to fit the engine still lands whole.
131
157
  */
132
158
  protected writeBatches<T>(rows: readonly T[], keyCount: number, write: (batch: T[]) => Promise<number>): Promise<number>;
133
- /** Runs a write split into several statements as one, in a transaction that joins an open one. */
159
+ /** Runs a write of several statements as one: in a transaction of its own, or the one already open. */
134
160
  protected atomically<T>(write: () => Promise<T>): Promise<T>;
135
161
  /** The ids `q` matches, in its own order and page. */
136
162
  protected settleIds<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<EntityId<E>[]>;
@@ -143,49 +169,100 @@ export declare abstract class AbstractQuerier implements Querier {
143
169
  * cleared stamp, or a row pointed at the relation just inserted for it.
144
170
  */
145
171
  private unversionedUpdate;
146
- /** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
147
- upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>, update?: UpdateWrite<E>): Promise<QueryUpsertOneResult<E>>;
148
- upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[], update?: UpdateWrite<E>): Promise<QueryUpsertManyResult<E>>;
172
+ upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>, update?: UpdateWrite<E>, opts?: WriteOptions<E, S, V>): Promise<ReturningResult<S, WrittenId<E> | undefined, QueryFindResult<E, S, V>>>;
173
+ upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[], update?: UpdateWrite<E>, opts?: WriteOptions<E, S, V>): Promise<ReturningResult<S, (WrittenId<E> | undefined)[], QueryFindResult<E, S, V>[]>>;
149
174
  /**
150
175
  * An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
151
176
  * as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
152
177
  * tenant's. A row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
153
178
  */
154
179
  private readThenUpsert;
155
- protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E, update?: UpdatePayload<E>): Promise<QueryUpdateResult>;
156
- protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<QueryUpdateResult>;
157
- deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
180
+ /** Upserts `payload`, answering each row's key in payload order where the engine reports every one. */
181
+ protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<(PrimaryKey | undefined)[] | undefined>;
182
+ deleteOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V> | undefined>>;
158
183
  /** Delete records matching the query, the entity passed first or as `$entity`; soft-deletes unless `opts.hardDelete`. */
159
184
  deleteMany<E extends object>(q: QuerySearch<E> & {
160
185
  $entity: Type<E>;
161
186
  }, opts?: QueryOptions): Promise<number>;
162
- deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
187
+ deleteMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V>[]>>;
188
+ /** The number of rows deleted, or the rows `returning` reads as they were, before the delete and in its transaction. */
189
+ private deleteWhere;
190
+ private deleteRows;
163
191
  /** Runs one DELETE (or soft-delete stamp) over `q`, which names its rows by id wherever {@link deleteMany} settled them. */
164
192
  protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
165
- saveOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
193
+ saveOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V>): Promise<ReturningResult<S, WrittenId<E> | undefined, QueryFindResult<E, S, V>>>;
194
+ saveMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V>): Promise<ReturningResult<S, (WrittenId<E> | undefined)[], QueryFindResult<E, S, V>[]>>;
166
195
  /**
167
196
  * Whether a row names its key decides its statement, never whether the row exists: a named row
168
197
  * upserts on that key, so a stale id is written rather than silently missed, and an unnamed one
169
198
  * inserts. A composite is always named. The hooks follow the statement: a named row fires the upsert pair.
170
199
  */
171
- saveMany<E extends object>(entity: Type<E>, payload: readonly EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
172
- /** Writes each inserted row's relations, one set of statements per relation whatever the number of rows. */
173
- private insertRelations;
174
- /** `EntityId` because a settled composite row is an object, which {@link childrenOf} reads each foreign key column out of. */
175
- private deleteRelations;
200
+ private saveIds;
201
+ /**
202
+ * Writes the target of each to-one `rows` hold the key of, and points each row at its own: a row naming
203
+ * only its key is a link and writes nothing, any other saves as `saveMany` does, and `null` clears the key.
204
+ */
205
+ private writeHeldReferences;
206
+ /** Writes each inserted row's children, one set of statements per relation whatever the number of rows. */
207
+ private insertChildren;
208
+ /**
209
+ * Makes `value` the children of each parent `ids` names, which it owns: the rows it lists are saved,
210
+ * keeping what each does not write, and the parent's other children (a junction's other links) go.
211
+ */
212
+ private replaceChildren;
213
+ /** Writes each parent's children: rows pointed at their parent, or targets linked through the junction. */
214
+ private saveChildren;
215
+ /**
216
+ * Saves the rows a relation points at, each one's id what the pointer needs: a MySQL batch mixing supplied and
217
+ * generated keys cannot report it, so one it could not is refused rather than left pointing nowhere.
218
+ */
219
+ private saveTargets;
176
220
  /**
177
- * Writes each parent's value into one relation. The parent owns what it points at: an update replaces
178
- * it, and a `null` only clears it.
221
+ * Deletes the children of the parents `ids` names, as the parents go: a hard delete takes them all, a soft
222
+ * delete stamps those that can be stamped and keeps the rest, junction links included, for a restore.
223
+ * `EntityId` because a settled composite row is an object, which {@link childrenOf} reads each foreign key column out of.
179
224
  */
180
- private saveRelation;
181
- /** Each parent gets its own referenced row, and its own column pointing at it. */
182
- private saveManyToOne;
225
+ private deleteChildren;
183
226
  abstract readonly hasOpenTransaction: boolean;
184
227
  /**
185
- * Runs `callback` in a transaction, joining one already open. A rollback that fails is logged, never
186
- * thrown over the original error, and the connection stays with whoever acquired it.
228
+ * The transaction this flow runs in on this connection, the innermost where they nest: the callback's,
229
+ * or a `beginTransaction` of this querier's. `undefined` outside one, or inside another flow's.
230
+ */
231
+ protected scopeHere(): TransactionScope | undefined;
232
+ /**
233
+ * Runs `callback` in a transaction. Inside one this flow already runs, it is a savepoint: its failure undoes
234
+ * its own writes alone. A transaction another flow holds on this connection is waited for, never joined.
187
235
  */
188
236
  transaction<T>(callback: () => Promise<T>, opts?: TransactionOptions): Promise<T>;
237
+ /** A transaction inside `parent`, after any other it runs: a savepoint where the engine has them. */
238
+ private nested;
239
+ /** `callback` between a savepoint and its release, rolled back to it on failure, its `onCommit` callbacks kept only where it succeeds. */
240
+ private savepointed;
241
+ /**
242
+ * Opens, releases or rolls back to a savepoint, which a SQL engine overrides. Elsewhere (MongoDB) there is
243
+ * none, so a transaction inside another is refused: it could not undo its own writes apart.
244
+ */
245
+ protected savepoint(_kind: SavepointCommand, _name: string): Promise<void>;
246
+ /**
247
+ * Runs `callback` once the outermost transaction this flow is in commits, and dropped if it rolls back:
248
+ * a mail sent for a row that never landed is not sent. With no transaction open it runs now.
249
+ */
250
+ onCommit(callback: () => unknown): Promise<void>;
251
+ /** Waits for the connection's transaction, if another flow holds one, then opens `scope`'s on it. */
252
+ private open;
253
+ /** Whether the transaction its connection holds is this querier's. */
254
+ private holds;
255
+ /**
256
+ * Commits, or rolls back, the transaction this querier holds, in turn on its connection. With none held a
257
+ * rollback has nothing to do, and a commit refuses: a `release` inside the callback rolled it back.
258
+ */
259
+ private close;
260
+ /**
261
+ * Commits, or rolls back, the transaction this querier holds. A commit that fails can leave it open (SQLite
262
+ * answers `SQLITE_BUSY` and keeps it) for the rollback after it; a failed rollback ends it, leaving the
263
+ * connection unusable.
264
+ */
265
+ private end;
189
266
  /** Whether anything at all - a global listener or the entity itself - handles `event`. */
190
267
  private hasHook;
191
268
  /** Whether an `afterLoad` listens on the entity a read returns or on any relation it populated. */
@@ -210,8 +287,12 @@ export declare abstract class AbstractQuerier implements Querier {
210
287
  private hooked;
211
288
  /** Fires the global listeners first, then the entity's own hooks. */
212
289
  private emitHook;
213
- /** Runs `task` after everything already queued, one at a time. Not re-entrant: never nest `serialize` calls. */
290
+ /**
291
+ * Runs `task` after everything already queued, one at a time, once no transaction of another flow holds the
292
+ * connection: a statement from outside one never lands in it. Not re-entrant: never nest `serialize` calls.
293
+ */
214
294
  protected serialize<T>(task: () => Promise<T>): Promise<T>;
295
+ private enqueue;
215
296
  /** Runs `task`, logs `query` with its duration, and tags a failure with it: a method, since a decorator would lose the generics. */
216
297
  protected timed<T>(query: string, values: readonly unknown[] | undefined, task: () => Promise<T>): Promise<T>;
217
298
  /**
@@ -219,22 +300,24 @@ export declare abstract class AbstractQuerier implements Querier {
219
300
  * time after it is the loop's, and a failure tagged with `query`.
220
301
  */
221
302
  protected timedStream<T>(query: string, values: readonly unknown[] | undefined, rows: AsyncIterable<T>): AsyncGenerator<T>;
303
+ /** Opens a transaction that holds this querier until `commitTransaction` or `rollbackTransaction`, whatever flow calls them. */
222
304
  beginTransaction(opts?: TransactionOptions): Promise<void>;
223
305
  /** Strict: this is the check that catches a forgotten `beginTransaction`. */
224
306
  commitTransaction(): Promise<void>;
225
307
  /**
226
- * Rolls the open transaction back, or does nothing when there is none: it is called from `catch` and
227
- * `finally`, where the caller cannot know whether `beginTransaction` got far enough to open one.
308
+ * Rolls back the transaction this querier holds, or does nothing when there is none: it is called from `catch`
309
+ * and `finally`, where the caller cannot know whether `beginTransaction` got far enough to open one. A
310
+ * transaction another flow's callback holds is waited for, and so has ended by then.
228
311
  */
229
312
  rollbackTransaction(): Promise<void>;
230
- /** Opens a transaction on the engine, after `beginTransaction` has queued the call and checked none is open. */
313
+ /** Opens a transaction on the engine, once `open` has claimed the connection for it. */
231
314
  protected abstract openTransaction(opts?: TransactionOptions): Promise<void>;
232
315
  /** Commits the open transaction on the engine, or rolls it back when `commit` is false. */
233
316
  protected abstract endTransaction(commit: boolean): Promise<void>;
234
317
  /**
235
318
  * Closes a stream left open and rolls back an unfinished transaction, then hands the connection back,
236
- * discarding it if either failed: the pool would otherwise take one still reading. Never throws first,
237
- * since `await using` has no other way to release.
319
+ * discarding it where it is unusable: the pool would otherwise take one still reading, or in a state the
320
+ * next borrower inherits. Never throws first, since `await using` has no other way to release.
238
321
  */
239
322
  release(): Promise<void>;
240
323
  [Symbol.asyncDispose](): Promise<void>;