uql-orm 0.114.3 → 0.115.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 (85) hide show
  1. package/dist/cockroachdb/cockroachDialect.d.ts +2 -0
  2. package/dist/cockroachdb/cockroachDialect.js +5 -0
  3. package/dist/d1/d1Querier.d.ts +2 -4
  4. package/dist/d1/d1Querier.js +0 -4
  5. package/dist/d1/d1SqliteDialect.js +1 -1
  6. package/dist/dialect/abstractDialect.d.ts +17 -8
  7. package/dist/dialect/abstractDialect.js +30 -16
  8. package/dist/dialect/abstractSqlDialect.d.ts +11 -2
  9. package/dist/dialect/abstractSqlDialect.js +17 -2
  10. package/dist/dialect/mysqlLikeSqlDialect.js +2 -0
  11. package/dist/dialect/operators.d.ts +2 -2
  12. package/dist/dialect/pgLikeSqlDialect.d.ts +8 -1
  13. package/dist/dialect/pgLikeSqlDialect.js +20 -0
  14. package/dist/entity/columnOptionsBuilder.d.ts +2 -1
  15. package/dist/entity/columnOptionsBuilder.js +3 -0
  16. package/dist/entity/metadata/definedFixture/author.d.ts +1 -1
  17. package/dist/entity/metadata/definedFixture/book.d.ts +2 -2
  18. package/dist/entity/metadata/definedFixture/folder.d.ts +1 -1
  19. package/dist/entity/metadata/definition.js +69 -30
  20. package/dist/http/api.d.ts +1 -1
  21. package/dist/http/wireQuery.js +1 -1
  22. package/dist/index.d.ts +2 -0
  23. package/dist/index.js +2 -0
  24. package/dist/migrate/ddl/tableDdl.d.ts +5 -0
  25. package/dist/migrate/ddl/tableDdl.js +9 -0
  26. package/dist/migrate/drift/driftDetector.js +2 -1
  27. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +3 -1
  28. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +7 -1
  29. package/dist/migrate/introspection/postgresIntrospector.d.ts +3 -1
  30. package/dist/migrate/introspection/postgresIntrospector.js +14 -1
  31. package/dist/migrate/introspection/tableSchemaAST.js +1 -0
  32. package/dist/migrate/policySql.d.ts +12 -0
  33. package/dist/migrate/policySql.js +74 -0
  34. package/dist/migrate/schemaChange.js +1 -0
  35. package/dist/migrate/schemaGenerator.d.ts +2 -0
  36. package/dist/migrate/schemaGenerator.js +37 -11
  37. package/dist/mongodb/mongoDialect.js +3 -1
  38. package/dist/mongodb/mongodbQuerier.d.ts +2 -5
  39. package/dist/mongodb/mongodbQuerier.js +14 -26
  40. package/dist/mssql/mssqlDialect.js +2 -0
  41. package/dist/neon/neonQuerier.d.ts +1 -2
  42. package/dist/nestjs/uqlContextInterceptor.d.ts +1 -1
  43. package/dist/nestjs/uqlContextInterceptor.js +1 -1
  44. package/dist/nestjs/uqlModule.d.ts +2 -2
  45. package/dist/nestjs/uqlModule.js +1 -1
  46. package/dist/querier/abstractQuerier.d.ts +68 -30
  47. package/dist/querier/abstractQuerier.js +249 -168
  48. package/dist/querier/abstractQuerierPool.js +2 -0
  49. package/dist/querier/abstractSqlQuerier.d.ts +22 -13
  50. package/dist/querier/abstractSqlQuerier.js +75 -27
  51. package/dist/querier/queryError.js +1 -0
  52. package/dist/schema/schemaAST.js +1 -0
  53. package/dist/schema/schemaASTBuilder.d.ts +3 -1
  54. package/dist/schema/schemaASTBuilder.js +1 -0
  55. package/dist/schema/schemaASTDiffer.js +4 -2
  56. package/dist/schema/types.d.ts +12 -4
  57. package/dist/sqlite/bindValues.d.ts +1 -1
  58. package/dist/sqlite/hranaQuerier.d.ts +2 -2
  59. package/dist/sqlite/sqliteDialect.js +2 -0
  60. package/dist/turso/tursoSessionQuerier.d.ts +2 -2
  61. package/dist/type/column.d.ts +10 -0
  62. package/dist/type/definedEntity.d.ts +9 -4
  63. package/dist/type/dialect.d.ts +13 -0
  64. package/dist/type/entity.d.ts +10 -0
  65. package/dist/type/index.d.ts +1 -0
  66. package/dist/type/index.js +1 -0
  67. package/dist/type/migration.d.ts +5 -1
  68. package/dist/type/policy.d.ts +91 -0
  69. package/dist/type/policy.js +1 -0
  70. package/dist/type/querier.d.ts +16 -2
  71. package/dist/type/querierPool.d.ts +2 -2
  72. package/dist/type/query.d.ts +20 -35
  73. package/dist/type/query.js +2 -0
  74. package/dist/type/universalQuerier.d.ts +6 -6
  75. package/dist/util/contextRefs.d.ts +6 -0
  76. package/dist/util/contextRefs.js +5 -0
  77. package/dist/util/dialect.util.d.ts +10 -16
  78. package/dist/util/dialect.util.js +70 -64
  79. package/dist/util/fieldOption.util.js +1 -0
  80. package/dist/util/policy.util.d.ts +100 -0
  81. package/dist/util/policy.util.js +234 -0
  82. package/dist/util/uqlError.d.ts +2 -5
  83. package/dist/util/uqlError.js +2 -5
  84. package/package.json +1 -1
  85. package/skills/uql-orm/SKILL.md +24 -14
@@ -1,9 +1,7 @@
1
1
  import type { AbstractDialect } from '../dialect/abstractDialect.js';
2
- import type { BooleanLike, CursorPage, Captured, EntityData, EntityId, EntityWrite, EntityMeta, ExtraOptions, FieldKey, Querier, Query, QueryAggregate, QueryAggregateResult, QueryConflictKeys, QueryUpsert, QueryFilter, QueryFindResult, QueryKeyset, QueryOne, QueryOptions, StatementOptions, QueryPage, QuerySearch, SavepointCommand, TransactionOptions, Type, UpdatePayload, UpdateWrite, WriteResults, WriteOptions, PrimaryKey, WrittenId, RawRow, ReportedWrite } from '../type/index.js';
2
+ import type { BooleanLike, CursorPage, Captured, EntityData, EntityId, EntityWrite, EntityMeta, ExtraOptions, FieldKey, Querier, Query, QueryAggregate, QueryAggregateResult, QueryUpsert, QueryFilter, QueryFindResult, QueryKeyset, QueryOne, QueryOptions, StatementOptions, QueryPage, QuerySearch, SavepointCommand, TransactionOptions, Type, UpdatePayload, UpdateWrite, WriteResults, WriteOptions, WrittenId, RawRow, ReportedWrite } from '../type/index.js';
3
3
  import { LoggerWrapper } from '../util/index.js';
4
4
  import { type TransactionScope } from './transaction.js';
5
- /** What an upsert reports of a row: the value a driver answers for a lone key, or the key the read back names. */
6
- export type UpsertedId<E> = PrimaryKey | WrittenId<E>;
7
5
  /** Each write as one statement reporting the rows it wrote with the fields `keys` names. */
8
6
  export type ReportingWrites = {
9
7
  update<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts: StatementOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
@@ -117,18 +115,22 @@ export declare abstract class AbstractQuerier implements Querier {
117
115
  protected abstract internalAggregate<E extends object>(entity: Type<E>, q: QueryAggregate<E>, opts?: QueryOptions): Promise<RawRow[]>;
118
116
  /** Abstract outright: nothing is shared to do around it. See {@link UniversalQuerier.estimatedCount}. */
119
117
  abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
120
- insertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted']>;
121
- insertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted'][]>;
118
+ insertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
119
+ insertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
122
120
  /**
123
121
  * What an insert reports: the ids, or the rows `returning` asks for, off the insert's own statement where
124
122
  * {@link reportingWrites} can, else read back.
125
123
  */
126
124
  private insertWritten;
125
+ /** Inserts `rows` as {@link insertRows} does, reporting each with the fields `keys` names off its own statement. */
126
+ private insertReturning;
127
127
  /**
128
128
  * The ids of the rows inserted, in payload order. The `onInsert` values are filled before the write, so
129
129
  * the after hooks and the ids read the same rows the statement wrote.
130
130
  */
131
131
  private insertIds;
132
+ /** Inserts `rows` as {@link insertRows} does, answering the key each got. */
133
+ private insertedIds;
132
134
  /** `insert` of `payload` between the insert hooks, {@link atomically} where it writes relations too. */
133
135
  private inserting;
134
136
  /**
@@ -149,6 +151,24 @@ export declare abstract class AbstractQuerier implements Querier {
149
151
  * and the insert half of a read upsert. Answers what `insert` reports.
150
152
  */
151
153
  private insertRows;
154
+ /**
155
+ * {@link guardWrite} under a pool holding writes to the policies, answering how the write of `rows` runs: alone, or
156
+ * with the rows it wrote read back against the check they could not settle, in a transaction undoing it where one
157
+ * does not hold. Where the database holds the policies the rows still get their pinned fields and an early refusal,
158
+ * and nothing is read back. A checked write is refused where this querier holds no transaction to undo it in.
159
+ */
160
+ private guarded;
161
+ /**
162
+ * {@link guardWrite} where this pool reads written rows back, answering the check to read them against; else
163
+ * {@link pinUpserted}'s pinning alone, where it guards writes at all.
164
+ */
165
+ private guardRows;
166
+ /** {@link pinWrite} where this pool guards writes: an upsert's branches check what they write, or its database does. */
167
+ private pinUpserted;
168
+ /** Whether {@link atomically} undoes every step of a write that fails partway: a transaction holds them. */
169
+ private undoesSteps;
170
+ /** Refuses, undoing the write, where any row `ids` names does not hold `check` once written. */
171
+ private holdToCheck;
152
172
  /** Writes `rows`, its columns only, and onto each one the key the database generated for it, where it can tell. */
153
173
  protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
154
174
  updateOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['affected']>;
@@ -185,7 +205,10 @@ export declare abstract class AbstractQuerier implements Querier {
185
205
  * still costs one statement. Best effort by nature - the row can change again while we ask.
186
206
  */
187
207
  private throwStaleVersion;
188
- /** What every update does to its row before its statement: writes the to-ones it holds, fills and guards it. */
208
+ /**
209
+ * What every update does to its row before its statement: writes the to-ones it holds, fills and guards it.
210
+ * Answers how its write runs, as {@link guarded} does.
211
+ */
189
212
  private prepareUpdate;
190
213
  /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
191
214
  private updateColumns;
@@ -221,19 +244,41 @@ export declare abstract class AbstractQuerier implements Querier {
221
244
  restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
222
245
  upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(q: QueryUpsert<E> & {
223
246
  $entity: Type<E>;
224
- }, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted']>;
225
- upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted']>;
247
+ }, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
248
+ upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
226
249
  upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(q: QueryUpsert<E> & {
227
250
  $entity: Type<E>;
228
- }, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted'][]>;
229
- upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted'][]>;
230
- /** Upserts `rows`, reading first where {@link upsertsByReading} says so, and answers the id each row got. */
251
+ }, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
252
+ upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
253
+ /**
254
+ * Whether an upsert has to read before it writes: `ON CONFLICT` updates a row the querier holds to policies whatever
255
+ * tenant it belongs to, writes no relation, and cannot tell a found row it skipped for a stale version. A database
256
+ * holding the policies itself holds the conflicting row to them in the one statement.
257
+ */
258
+ private upsertsByReading;
259
+ /** Upserts `rows`, each naming every conflict key, reading first where `reads`: the id each got. */
231
260
  private upsertIds;
232
261
  /**
233
- * An upsert of one statement reporting each row as it stands after it: off its `RETURNING` where it wrote the row,
234
- * else, where its `$where` or an empty `$update` kept it, read by the conflict keys.
262
+ * The id of each of `rows` the engine's upsert reports, or {@link withKept} reads back. A row matched on its own key
263
+ * names it, so needs neither.
264
+ */
265
+ private reportedOrKeptIds;
266
+ /**
267
+ * `written`, an upsert's report of each of `rows`, with each row it reported none of, kept by its `$where` or an
268
+ * empty `$update`, read back by its conflict keys selecting `select`: `undefined` where no row matches.
269
+ */
270
+ private withKept;
271
+ /**
272
+ * An upsert of one statement, of rows each naming every conflict key, reporting each row as it stands after it: off
273
+ * its `RETURNING` where it wrote the row, else, where its `$where` or an empty `$update` kept it, read by the
274
+ * conflict keys.
235
275
  */
236
276
  private upsertReturning;
277
+ /**
278
+ * Writes each of `rows` through the writer `branch` names for it, the writers in their order, answering each row's
279
+ * result in `rows` order; {@link atomically} where more than one branch but those `idle` names, which write nothing.
280
+ */
281
+ private writeEach;
237
282
  /**
238
283
  * Refuses a row an upsert wrote or kept that no row matches by its conflict key, as read back: the engine stores
239
284
  * the key otherwise than the row spells it, a uuid in other letters, and a row left out would misalign the rest.
@@ -242,15 +287,15 @@ export declare abstract class AbstractQuerier implements Querier {
242
287
  /**
243
288
  * An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
244
289
  * by id as `updateOne` does, a versioned one at its version, and the rest insert, so either branch writes its
245
- * relations and a guarded row stays its tenant's. Inside a transaction a found row is held until the write, and
246
- * a row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
290
+ * relations and a policied row stays its tenant's. Inside a transaction a found row is held until the write, and
291
+ * a row inserted concurrently fails on its key. See architecture/row-level-security.md.
247
292
  */
248
293
  private readThenUpsert;
249
294
  /**
250
- * Upserts `payload` as `q` names its rows, answering each row's key in payload order, `undefined` for one the
251
- * engine did not report.
295
+ * Upserts `payload`, at least one row, each naming every conflict key, as `q` names its rows, answering each row's
296
+ * key in payload order, `undefined` for one the engine did not report, which a found row it kept may be.
252
297
  */
253
- protected abstract internalUpsertMany<E extends object>(entity: Type<E>, q: QueryUpsert<E>, payload: E[]): Promise<(UpsertedId<E> | undefined)[]>;
298
+ protected abstract internalUpsertMany<E extends object>(entity: Type<E>, q: QueryUpsert<E>, payload: E[]): Promise<(WrittenId<E> | undefined)[]>;
254
299
  deleteOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions & WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['affected']>;
255
300
  /** Delete records matching the query, the entity passed first or as `$entity`; soft-deletes unless `opts.hardDelete`. */
256
301
  deleteMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(q: QuerySearch<E> & {
@@ -269,8 +314,8 @@ export declare abstract class AbstractQuerier implements Querier {
269
314
  private deleteRows;
270
315
  /** Runs one DELETE (or soft-delete stamp) over `q`, which names its rows by id wherever {@link deleteMany} settled them. */
271
316
  protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: StatementOptions): Promise<number>;
272
- saveOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted']>;
273
- saveMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted'][]>;
317
+ saveOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
318
+ saveMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
274
319
  /**
275
320
  * Whether a row names its key decides its statement, never whether the row exists: a named row
276
321
  * upserts on that key, so a stale id is written rather than silently missed, and an unnamed one
@@ -354,19 +399,12 @@ export declare abstract class AbstractQuerier implements Querier {
354
399
  * listens.
355
400
  */
356
401
  private emitLoaded;
357
- /** The ids of `rows`, read by the columns an upsert matches them on, as {@link rowsByConflict} reads them. */
358
- private idsByConflict;
359
402
  /**
360
- * The row each of `rows` matches on the columns an upsert matches on, with `select`, soft-deleted rows included
361
- * since a unique key holds across both, held as {@link readForWrite} holds its rows. One no row matches, or two do,
362
- * reads none, since a missing row is honest where a guessed one is not; a null key never conflicts, so is not read.
403
+ * The row each of `rows` matches on the columns an upsert matches on, each naming every one, with `select`,
404
+ * soft-deleted rows included since a unique key holds across both, held as {@link readForWrite} holds its rows. One
405
+ * no row matches, or two do, reads none, since a missing row is honest where a guessed one is not.
363
406
  */
364
407
  private rowsByConflict;
365
- /**
366
- * `ids` completed where an upsert reported no id for a row whose key it does not keep (`kept`, asked before the
367
- * write fills one in): read back by the conflict columns.
368
- */
369
- protected withUnreportedIds<E extends object>(entity: Type<E>, conflictKeys: QueryConflictKeys<E>, payload: EntityData<E>[], ids: (UpsertedId<E> | undefined)[], kept: readonly boolean[]): Promise<(UpsertedId<E> | undefined)[]>;
370
408
  /** Reads of the rows matching one of `rows` on `keys`, as many per statement as a key list takes, selecting `select`. */
371
409
  private keyedReads;
372
410
  /**