uql-orm 0.91.1 → 0.93.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 (165) hide show
  1. package/dist/browser/http/bus.js +3 -4
  2. package/dist/browser/http/http.d.ts +1 -2
  3. package/dist/browser/http/http.js +8 -7
  4. package/dist/browser/index.d.ts +0 -1
  5. package/dist/browser/index.js +0 -1
  6. package/dist/browser/querier/httpQuerier.d.ts +18 -20
  7. package/dist/browser/querier/httpQuerier.js +20 -56
  8. package/dist/browser/type/index.d.ts +0 -1
  9. package/dist/browser/type/index.js +0 -1
  10. package/dist/browser/uql-browser.min.js +2 -2
  11. package/dist/browser/uql-browser.min.js.map +11 -12
  12. package/dist/cockroachdb/cockroachDialect.d.ts +4 -1
  13. package/dist/cockroachdb/cockroachDialect.js +6 -2
  14. package/dist/dialect/abstractDialect.d.ts +1 -1
  15. package/dist/dialect/abstractDialect.js +4 -1
  16. package/dist/dialect/abstractSqlDialect.d.ts +68 -37
  17. package/dist/dialect/abstractSqlDialect.js +185 -107
  18. package/dist/dialect/aliases.d.ts +4 -1
  19. package/dist/dialect/aliases.js +5 -2
  20. package/dist/dialect/hydrateColumn.js +3 -10
  21. package/dist/dialect/jsonSql.d.ts +4 -1
  22. package/dist/dialect/jsonSql.js +4 -1
  23. package/dist/dialect/mergeSqlDialect.d.ts +14 -4
  24. package/dist/dialect/mergeSqlDialect.js +32 -15
  25. package/dist/dialect/mysqlLikeSqlDialect.d.ts +16 -24
  26. package/dist/dialect/mysqlLikeSqlDialect.js +38 -52
  27. package/dist/dialect/pgLikeSqlDialect.d.ts +8 -8
  28. package/dist/dialect/pgLikeSqlDialect.js +19 -22
  29. package/dist/http/contract.d.ts +4 -0
  30. package/dist/http/contract.js +1 -0
  31. package/dist/http/handler.d.ts +2 -2
  32. package/dist/http/handler.js +17 -19
  33. package/dist/http/query.d.ts +5 -3
  34. package/dist/http/query.js +42 -42
  35. package/dist/index.d.ts +2 -2
  36. package/dist/index.js +2 -2
  37. package/dist/maria/mariaDialect.d.ts +4 -3
  38. package/dist/maria/mariaDialect.js +4 -6
  39. package/dist/migrate/builder/columnBuilder.d.ts +5 -15
  40. package/dist/migrate/builder/columnBuilder.js +50 -86
  41. package/dist/migrate/builder/index.d.ts +0 -1
  42. package/dist/migrate/builder/index.js +0 -1
  43. package/dist/migrate/builder/migrationBuilder.d.ts +3 -11
  44. package/dist/migrate/builder/migrationBuilder.js +41 -81
  45. package/dist/migrate/builder/tableBuilder.d.ts +0 -7
  46. package/dist/migrate/builder/tableBuilder.js +19 -30
  47. package/dist/migrate/builder/types.d.ts +2 -2
  48. package/dist/migrate/codegen/entityCodeGenerator.js +3 -3
  49. package/dist/migrate/codegen/entityTypes.js +2 -2
  50. package/dist/migrate/codegen/fieldOptionsSource.d.ts +2 -2
  51. package/dist/migrate/codegen/fieldOptionsSource.js +22 -14
  52. package/dist/migrate/codegen/indexDecoratorSource.js +64 -41
  53. package/dist/migrate/ddl/defaultSql.d.ts +31 -0
  54. package/dist/migrate/ddl/defaultSql.js +109 -0
  55. package/dist/migrate/ddl/index.d.ts +2 -4
  56. package/dist/migrate/ddl/index.js +14 -5
  57. package/dist/migrate/ddl/mssqlTableDdl.d.ts +1 -0
  58. package/dist/migrate/ddl/mssqlTableDdl.js +4 -1
  59. package/dist/migrate/ddl/mysqlTableDdl.d.ts +17 -0
  60. package/dist/migrate/ddl/mysqlTableDdl.js +33 -0
  61. package/dist/migrate/ddl/pgTableDdl.d.ts +7 -0
  62. package/dist/migrate/ddl/pgTableDdl.js +17 -0
  63. package/dist/migrate/ddl/tableDdl.d.ts +15 -10
  64. package/dist/migrate/ddl/tableDdl.js +31 -32
  65. package/dist/migrate/drift/driftDetector.js +46 -59
  66. package/dist/migrate/generator/definitionToNode.d.ts +11 -7
  67. package/dist/migrate/generator/definitionToNode.js +27 -34
  68. package/dist/migrate/generator/indexNodeToSchema.d.ts +3 -3
  69. package/dist/migrate/generator/indexNodeToSchema.js +5 -4
  70. package/dist/migrate/index.js +1 -1
  71. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +10 -5
  72. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +9 -0
  73. package/dist/migrate/introspection/baseSqlIntrospector.d.ts +0 -1
  74. package/dist/migrate/introspection/baseSqlIntrospector.js +6 -8
  75. package/dist/migrate/introspection/mssqlIntrospector.js +3 -8
  76. package/dist/migrate/introspection/mysqlIntrospector.d.ts +11 -4
  77. package/dist/migrate/introspection/mysqlIntrospector.js +27 -11
  78. package/dist/migrate/introspection/postgresIntrospector.d.ts +2 -2
  79. package/dist/migrate/introspection/postgresIntrospector.js +3 -3
  80. package/dist/migrate/introspection/sqliteIntrospector.d.ts +1 -1
  81. package/dist/migrate/introspection/sqliteIntrospector.js +7 -10
  82. package/dist/migrate/migrationTarget.js +3 -3
  83. package/dist/migrate/schemaGenerator.d.ts +8 -12
  84. package/dist/migrate/schemaGenerator.js +36 -62
  85. package/dist/migrate/storage/databaseStorage.js +2 -2
  86. package/dist/migrate/triggerSql.d.ts +1 -1
  87. package/dist/migrate/triggerSql.js +17 -8
  88. package/dist/mongo/mongoDialect.d.ts +4 -3
  89. package/dist/mongo/mongoDialect.js +52 -38
  90. package/dist/mongo/mongoIntrospector.js +1 -1
  91. package/dist/mongo/mongoSchemaGenerator.d.ts +7 -4
  92. package/dist/mongo/mongoSchemaGenerator.js +18 -21
  93. package/dist/mongo/mongodbQuerier.d.ts +15 -8
  94. package/dist/mongo/mongodbQuerier.js +48 -33
  95. package/dist/mssql/mssqlDialect.d.ts +9 -5
  96. package/dist/mssql/mssqlDialect.js +23 -8
  97. package/dist/postgres/postgresDialect.d.ts +5 -2
  98. package/dist/postgres/postgresDialect.js +6 -6
  99. package/dist/querier/abstractQuerier.d.ts +20 -15
  100. package/dist/querier/abstractQuerier.js +93 -41
  101. package/dist/querier/abstractQuerierPool.d.ts +26 -24
  102. package/dist/querier/abstractQuerierPool.js +26 -64
  103. package/dist/querier/abstractSqlQuerier.d.ts +5 -6
  104. package/dist/querier/abstractSqlQuerier.js +15 -33
  105. package/dist/querier/cursor.d.ts +10 -0
  106. package/dist/querier/cursor.js +81 -0
  107. package/dist/querier/keyset.d.ts +19 -0
  108. package/dist/querier/keyset.js +198 -0
  109. package/dist/schema/canonicalType.d.ts +3 -3
  110. package/dist/schema/canonicalType.js +13 -12
  111. package/dist/schema/indexDifferences.d.ts +14 -7
  112. package/dist/schema/indexDifferences.js +7 -5
  113. package/dist/schema/schemaAST.d.ts +0 -1
  114. package/dist/schema/schemaAST.js +0 -2
  115. package/dist/schema/schemaASTBuilder.js +14 -20
  116. package/dist/schema/schemaASTDiffer.d.ts +7 -9
  117. package/dist/schema/schemaASTDiffer.js +54 -107
  118. package/dist/schema/sqlExpression.d.ts +28 -0
  119. package/dist/schema/sqlExpression.js +42 -0
  120. package/dist/schema/types.d.ts +48 -105
  121. package/dist/sqlite/sqliteDialect.d.ts +10 -13
  122. package/dist/sqlite/sqliteDialect.js +19 -30
  123. package/dist/type/dialect.d.ts +46 -11
  124. package/dist/type/dialect.js +2 -0
  125. package/dist/type/entity.d.ts +18 -3
  126. package/dist/type/migration.d.ts +7 -7
  127. package/dist/type/querier.d.ts +19 -26
  128. package/dist/type/query.d.ts +116 -25
  129. package/dist/type/query.js +21 -28
  130. package/dist/type/universalQuerier.d.ts +33 -7
  131. package/dist/type/utility.d.ts +10 -0
  132. package/dist/util/bytes.d.ts +7 -0
  133. package/dist/util/bytes.js +22 -0
  134. package/dist/util/date.d.ts +5 -0
  135. package/dist/util/date.js +5 -0
  136. package/dist/util/dialect.util.d.ts +1 -25
  137. package/dist/util/dialect.util.js +4 -50
  138. package/dist/util/field.util.d.ts +9 -0
  139. package/dist/util/field.util.js +15 -0
  140. package/dist/util/fieldOption.util.js +2 -2
  141. package/dist/util/index.d.ts +2 -1
  142. package/dist/util/index.js +2 -1
  143. package/dist/util/object.util.d.ts +0 -2
  144. package/dist/util/object.util.js +0 -7
  145. package/dist/util/query.util.d.ts +40 -0
  146. package/dist/util/query.util.js +76 -0
  147. package/dist/util/raw.d.ts +16 -1
  148. package/dist/util/raw.js +31 -0
  149. package/dist/util/relationQuery.util.js +18 -16
  150. package/dist/util/rowKey.util.js +2 -3
  151. package/dist/util/sql.util.d.ts +8 -2
  152. package/dist/util/sql.util.js +16 -17
  153. package/dist/util/sqlLiteral.js +2 -12
  154. package/dist/util/string.util.d.ts +5 -0
  155. package/dist/util/string.util.js +12 -0
  156. package/dist/util/triggerWrite.d.ts +11 -1
  157. package/dist/util/triggerWrite.js +14 -0
  158. package/package.json +1 -1
  159. package/skills/uql-orm/SKILL.md +22 -10
  160. package/dist/browser/options.d.ts +0 -4
  161. package/dist/browser/options.js +0 -13
  162. package/dist/browser/type/clientQuerierPool.d.ts +0 -4
  163. package/dist/browser/type/clientQuerierPool.js +0 -1
  164. package/dist/migrate/builder/expressions.d.ts +0 -69
  165. package/dist/migrate/builder/expressions.js +0 -145
@@ -1,9 +1,8 @@
1
- import { AbstractSqlDialect, } from '../dialect/abstractSqlDialect.js';
1
+ import { ANSI_SQL_VALUES, AbstractSqlDialect, } from '../dialect/abstractSqlDialect.js';
2
2
  import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
3
- import { chainedCall, groupsPerCall, jsonSetCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
3
+ import { chainedCall, groupsPerCall, jsonSetCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, } from '../dialect/jsonSql.js';
4
4
  import { QueryRaw, } from '../type/index.js';
5
5
  import { indexDistance, isVectorIndexType } from '../type/vector.js';
6
- import { utcTimestamp } from '../util/date.js';
7
6
  import { declaredIndexName } from '../util/ddlExpression.util.js';
8
7
  import { findVectorIndex, findVectorSort, textSearchFields, vectorCandidates } from '../util/dialect.util.js';
9
8
  import { isIntegerColumn } from '../util/field.util.js';
@@ -32,6 +31,7 @@ export const SQLITE_FEATURES = {
32
31
  serverSideCursors: false,
33
32
  correlatedWrites: true,
34
33
  rowLocks: false,
34
+ nullsSortLowest: true,
35
35
  nullsOrdering: 'clause',
36
36
  textScoreIndexes: false,
37
37
  orderedUpsertReturning: true,
@@ -40,13 +40,13 @@ export const SQLITE_FEATURES = {
40
40
  vectorTuningNeedsTransaction: false,
41
41
  serialDeclaresPrimaryKey: true,
42
42
  triggers: {
43
- preamble: '',
44
43
  assignsRow: false,
45
44
  body: 'inline',
46
45
  fires: 'eachRowWhen',
47
46
  layout: 'timingFirst',
48
47
  scope: 'schema',
49
48
  before: true,
49
+ deferrable: false,
50
50
  },
51
51
  };
52
52
  export class SqliteDialect extends AbstractSqlDialect {
@@ -54,16 +54,23 @@ export class SqliteDialect extends AbstractSqlDialect {
54
54
  dialectName = 'sqlite';
55
55
  escapeIdChar = '`';
56
56
  autoIncrementSuffix = 'PRIMARY KEY AUTOINCREMENT';
57
- tableOptions = '';
58
57
  beginTransactionCommand = 'BEGIN TRANSACTION';
59
- commitTransactionCommand = 'COMMIT';
60
- rollbackTransactionCommand = 'ROLLBACK';
61
58
  isolationLevelStrategy = 'none';
62
59
  booleanLiteral = 'integer';
60
+ /**
61
+ * The clock and today in the same text as a bound `Date`, where `CURRENT_TIMESTAMP` writes whole seconds and
62
+ * `CURRENT_DATE` no time, so neither would compare correctly. The parentheses let SQLite take each as a default.
63
+ */
64
+ sqlValues = {
65
+ ...ANSI_SQL_VALUES,
66
+ currentTimestamp: "(strftime('%Y-%m-%d %H:%M:%f', 'now'))",
67
+ currentDate: "(strftime('%Y-%m-%d 00:00:00.000', 'now'))",
68
+ };
69
+ refusal(message) {
70
+ return `SELECT RAISE(ABORT, ${message});`;
71
+ }
63
72
  /** SQLite's own cap on a function call before 3.48, which libSQL and `bun:sqlite`'s build still have. */
64
73
  maxFunctionArgs = 127;
65
- // SQLite supports `RETURNING` (including on `INSERT ... ON CONFLICT`), so IDs are exact per row.
66
- insertIdSource = 'returning';
67
74
  /**
68
75
  * The [sqlite-vec](https://github.com/asg017/sqlite-vec) functions, which need that extension
69
76
  * loaded on the connection (see `Sqlite3QuerierPool`'s `extensions` option). libSQL and Turso ship
@@ -123,21 +130,9 @@ export class SqliteDialect extends AbstractSqlDialect {
123
130
  neExpr(field, ph) {
124
131
  return `${field} IS NOT ${ph}`;
125
132
  }
126
- normalizeValue(value) {
127
- if (value instanceof Date)
128
- return utcTimestamp(value);
129
- return super.normalizeValue(value);
130
- }
131
- /**
132
- * `OFFSET` is only legal after a `LIMIT` here too, so a bare `$skip` needs one - `-1` being
133
- * SQLite's own spelling of "no limit", where the MySQL family uses its largest `BIGINT`.
134
- */
135
- pager(ctx, opts) {
136
- if (opts.$limit === undefined && opts.$skip !== undefined) {
137
- ctx.append(' LIMIT -1');
138
- }
139
- super.pager(ctx, opts);
140
- }
133
+ dateZone = '';
134
+ /** SQLite's own spelling of no limit. */
135
+ unboundedLimit = '-1';
141
136
  /** `json_group_array` of each row's object, ordered by the sort terms carried out beside them. */
142
137
  appendRelationArray(ctx, rows) {
143
138
  const { from, pairs, order } = this.derivedRelation(ctx, rows);
@@ -222,14 +217,8 @@ export class SqliteDialect extends AbstractSqlDialect {
222
217
  jsonArrayOf(elem) {
223
218
  return `JSON_GROUP_ARRAY(JSON(${elem}))`;
224
219
  }
225
- jsonSet(ctx, expr, set, field) {
226
- return jsonSetCall((value) => this.jsonScalarParam(ctx, value), jsonSetTarget(expr, field, `'{}'`), set, this.maxFunctionArgs);
227
- }
228
220
  /** `[#]` appends, creating the array where it is absent: `JSON_SET`, since Turso's `JSON_INSERT` will not touch an existing array. */
229
221
  jsonPush(ctx, expr, push) {
230
222
  return jsonSetCall((value) => this.jsonScalarParam(ctx, value), expr, push, this.maxFunctionArgs, '[#]');
231
223
  }
232
- jsonUnset(_ctx, expr, unset) {
233
- return jsonRemoveCall(expr, unset, this.maxFunctionArgs);
234
- }
235
224
  }
@@ -1,10 +1,15 @@
1
1
  import type { EntityMeta, EntityPredicate, UpdatePayload } from './entity.js';
2
- import type { Query, QueryConflictPaths, QueryPage, QueryRenderOptions, QuerySearch, RelationQuery } from './query.js';
2
+ import type { Query, QueryConflictPaths, QueryPage, QueryRenderOptions, QuerySearch, RelationQuery, UpsertOptions } from './query.js';
3
3
  import type { QueryAggMap, QueryAggregate, QueryAggregateOp, QueryGroupMap } from './queryAggregate.js';
4
4
  import type { QueryRawRenderOptions } from './queryRaw.js';
5
5
  import type { QueryWhere } from './queryWhere.js';
6
6
  import type { Type } from './utility.js';
7
7
  import type { QueryVectorQuery } from './vector.js';
8
+ /** The values the database computes that uql exports by name: `currentTimestamp`, `uuid`, ... */
9
+ export declare const SQL_VALUE_NAMES: readonly ['currentTimestamp', 'currentDate', 'currentTime', 'uuid', 'uuidv7'];
10
+ export type SqlValueName = (typeof SQL_VALUE_NAMES)[number];
11
+ /** An engine's SQL for each {@link SqlValueName}, `undefined` where it has none. */
12
+ export type SqlValues = Readonly<Record<SqlValueName, string | undefined>>;
8
13
  /**
9
14
  * comparison options.
10
15
  */
@@ -135,6 +140,12 @@ export interface DialectFeatures {
135
140
  * value rather than a flag each, since the details mean nothing without a lock.
136
141
  */
137
142
  readonly rowLocks: RowLockFeatures | false;
143
+ /**
144
+ * Whether a sort without `NULLS FIRST/LAST` treats nulls as lower than every value, putting them first on
145
+ * `asc`. True everywhere but Postgres, which treats them as higher. Cursor pagination reads it to know which
146
+ * side of a value the nulls fall on.
147
+ */
148
+ readonly nullsSortLowest: boolean;
138
149
  }
139
150
  /** How a dialect spells a row lock, once {@link DialectFeatures.rowLocks} says it has one. */
140
151
  export interface RowLockFeatures {
@@ -204,11 +215,17 @@ export interface TriggerFeatures {
204
215
  */
205
216
  readonly layout: 'timingFirst' | 'tableFirst';
206
217
  /**
207
- * What every body opens with, or `''`. T-SQL wants `SET NOCOUNT ON`: a trigger running its own DML
218
+ * SQL that every trigger body starts with, if any. T-SQL wants `SET NOCOUNT ON`: a trigger running its own DML
208
219
  * otherwise sends a rowcount of its own back, and the client reads that as what the original statement
209
- * affected. Nothing else here needs a preamble.
220
+ * affected.
221
+ */
222
+ readonly preamble?: string;
223
+ /**
224
+ * SQL a stamp that restates its row runs first, to return early when its own write fired it; unset where not
225
+ * needed. SQL Server fires a trigger once per statement, even for no rows, and reads its clock anew each time,
226
+ * so two stamps on one table would otherwise keep firing each other up to the nesting limit.
210
227
  */
211
- readonly preamble: string;
228
+ readonly reentryGuard?: string;
212
229
  /**
213
230
  * Whether a body may assign to the row it was handed, `NEW."col" := ...`. SQLite forbids writing `NEW`
214
231
  * at all, and SQL Server is handed a set rather than a row, so on both a trigger that fills a column
@@ -221,6 +238,8 @@ export interface TriggerFeatures {
221
238
  * so a `before*` event is refused there rather than silently made to mean something else.
222
239
  */
223
240
  readonly before: boolean;
241
+ /** Whether it can be deferred to commit, as a Postgres constraint trigger is; nowhere else can. */
242
+ readonly deferrable: boolean;
224
243
  }
225
244
  /**
226
245
  * The rows a set-based trigger's writes read: the tables `from` names, `inserted` and the like, narrowed
@@ -233,22 +252,32 @@ export type TriggerRows = {
233
252
  /** Where DDL's SQL sits: the row a trigger's predicate reads, as its prefix, and a set-based body's rows. */
234
253
  export type DdlRenderOptions = Pick<QueryComparisonOptions, 'escapedPrefix' | 'operand'> & Pick<QueryRawRenderOptions, 'rows'>;
235
254
  /**
236
- * A write a trigger's body runs, as `insertInto`, `updateTable` and `deleteFrom` state it. Held untyped
237
- * here, past those helpers' typing, since the dialect renders it by the entity's metadata alone.
255
+ * A write a trigger's body runs, as `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse` state
256
+ * it. Held untyped here, past those helpers' typing, since the dialect renders it by the entity's metadata alone.
238
257
  */
239
258
  export type TriggerWrite = {
240
- readonly entity: Type<object>;
241
- } & ({
242
259
  readonly kind: 'insert';
260
+ readonly entity: Type<object>;
243
261
  readonly row: Readonly<Record<string, unknown>>;
262
+ } | {
263
+ readonly kind: 'upsert';
264
+ readonly entity: Type<object>;
265
+ readonly conflictPaths: Readonly<Record<string, unknown>>;
266
+ readonly row: Readonly<Record<string, unknown>>;
267
+ readonly update?: Readonly<Record<string, unknown>>;
244
268
  } | {
245
269
  readonly kind: 'update';
270
+ readonly entity: Type<object>;
246
271
  readonly set: Readonly<Record<string, unknown>>;
247
272
  readonly where: EntityPredicate<object>;
248
273
  } | {
249
274
  readonly kind: 'delete';
275
+ readonly entity: Type<object>;
250
276
  readonly where: EntityPredicate<object>;
251
- });
277
+ } | {
278
+ readonly kind: 'refuse';
279
+ readonly message: string;
280
+ };
252
281
  /**
253
282
  * What a SQL statement is rendered through, as a `raw` callback and a query context see it:
254
283
  * `AbstractSqlDialect` is the one implementation.
@@ -270,6 +299,12 @@ export interface SqlQueryDialect {
270
299
  readonly escapeIdChar: '"' | '`';
271
300
  /** What the engine can do. */
272
301
  readonly features: SqlDialectFeatures;
302
+ /**
303
+ * Each {@link SqlValueName}'s SQL on this engine, `undefined` where it has none. `currentTimestamp` is UTC to
304
+ * the millisecond in the form of a bound `Date`, which a bare `CURRENT_TIMESTAMP` is not on SQLite, MySQL
305
+ * or SQL Server.
306
+ */
307
+ readonly sqlValues: SqlValues;
273
308
  /** A read; with `totalAlias`, every row also carries the unpaged match count under that alias. */
274
309
  find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryRenderOptions, totalAlias?: string): void;
275
310
  /** A count of the records matching the filter, or of those a page of it takes. */
@@ -278,8 +313,8 @@ export interface SqlQueryDialect {
278
313
  insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryRenderOptions): void;
279
314
  /** An update of the records the query matches. */
280
315
  update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryRenderOptions): void;
281
- /** An upsert of one record or many by their conflict paths. */
282
- upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
316
+ /** An upsert of one record or many by their conflict paths, taking the options `upsertMany` takes. */
317
+ upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], opts?: UpsertOptions<E>): void;
283
318
  /** A write in a trigger's body; `rows` are what a set-based engine's body reads, narrowed to the ones it fires for. */
284
319
  triggerWrite(ctx: QueryContext, write: TriggerWrite, rows?: TriggerRows): void;
285
320
  /** A delete of the records the query matches, a soft delete where the entity has one. */
@@ -1,3 +1,5 @@
1
+ /** The values the database computes that uql exports by name: `currentTimestamp`, `uuid`, ... */
2
+ export const SQL_VALUE_NAMES = ['currentTimestamp', 'currentDate', 'currentTime', 'uuid', 'uuidv7'];
1
3
  /**
2
4
  * An index capability some engines lack, named in the words an error reports it in. Introspectors use
3
5
  * the same vocabulary for what they can read back, a separate set: MySQL emits an expression index it
@@ -280,7 +280,7 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
280
280
  /**
281
281
  * Where {@link FieldOptions.computed} lives instead of being spliced into each read. `true` makes it a
282
282
  * generated column, which takes only an immutable expression; a list of events makes it a stamp a trigger
283
- * writes on each, whoever writes the row - how `CURRENT_TIMESTAMP` is kept, where `onUpdate` sees only uql's writes.
283
+ * writes on each, whoever writes the row. It keeps a `currentTimestamp` current; `onUpdate` sees only uql's writes.
284
284
  */
285
285
  readonly stored?: boolean | readonly StampEvent[];
286
286
  readonly updatable?: boolean;
@@ -312,8 +312,8 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
312
312
  readonly scale?: number;
313
313
  readonly nullable?: boolean;
314
314
  readonly unique?: boolean;
315
- /** The column's DDL default. */
316
- readonly defaultValue?: DdlDefault<V>;
315
+ /** The column's DDL default: a literal, or SQL the database evaluates per inserted row (`currentTimestamp`, `raw`). */
316
+ readonly defaultValue?: DdlDefault<V> | QueryRaw;
317
317
  /** Whether the database generates the value; a numeric sole key does unless something else fills it. */
318
318
  readonly autoIncrement?: boolean;
319
319
  /**
@@ -771,6 +771,11 @@ type TriggerRun<E, Ev extends TriggerEvent> = TriggerBody<E, Ev> | Readonly<AtLe
771
771
  */
772
772
  export type TriggerOptions<E = unknown> = {
773
773
  [Ev in TriggerEvent]: {
774
+ /**
775
+ * The write that fires the trigger and on which side of it, `beforeUpdate` or `afterDelete`. The rows
776
+ * the body has follow from it: the incoming one on an insert, the outgoing one on a delete, both on an
777
+ * update.
778
+ */
774
779
  readonly on: Ev;
775
780
  /**
776
781
  * What to call this trigger within the entity, for a clearer identifier than its event and position.
@@ -790,6 +795,16 @@ export type TriggerOptions<E = unknown> = {
790
795
  * rendered on every engine from the one declaration, or SQL off them for what no predicate states.
791
796
  */
792
797
  readonly where?: TriggerPredicate<E, Ev> | TriggerBody<E, Ev>;
798
+ /**
799
+ * Fire at commit rather than after each statement, so a check over many rows (a ledger's entries
800
+ * summing to zero) sees the transaction's every write. Postgres only, and only after the write.
801
+ */
802
+ readonly deferred?: Ev extends `after${string}` ? boolean : never;
803
+ /**
804
+ * The body, as SQL off the rows, `(newRow, oldRow) => raw`...``: the incoming row first and the
805
+ * outgoing one second, the one `on` lacks typed `never`. One for every engine, or a map naming one
806
+ * per engine where their SQL differs.
807
+ */
793
808
  readonly run: TriggerRun<E, Ev>;
794
809
  };
795
810
  }[TriggerEvent];
@@ -3,7 +3,7 @@ import type { IndexFacet } from '../schema/indexDifferences.js';
3
3
  import type { SchemaAST } from '../schema/schemaAST.js';
4
4
  import type { DiffOptions } from '../schema/schemaASTDiffer.js';
5
5
  import type { ColumnNode, ForeignKeyAction, IndexType, TableNode } from '../schema/types.js';
6
- import type { EntityMeta, EntityWhereMeta, FieldOptions, IndexColumnSchema, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
6
+ import type { EntityMeta, EntityWhereMeta, Except, FieldOptions, IndexColumnSchema, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
7
7
  /**
8
8
  * Defines a migration using a simple object literal. `Q` is `MongoQuerier` for a MongoDB migration.
9
9
  */
@@ -102,7 +102,7 @@ export interface MigrationResult {
102
102
  readonly error?: Error;
103
103
  }
104
104
  /** A column as a statement renders one: a {@link ColumnNode} with the engine's type spelling and no graph links. */
105
- export interface ColumnSchema extends Omit<ColumnNode, 'type' | 'table' | 'referencedBy' | 'references'> {
105
+ export interface ColumnSchema extends Except<ColumnNode, 'type' | 'table' | 'referencedBy' | 'references'> {
106
106
  /**
107
107
  * The engine's own type spelling, `TINYINT(1)`, compared as stored: canonical types would differ where
108
108
  * the engine stores them alike. `sqlToCanonical` reads it.
@@ -182,11 +182,6 @@ export interface ForeignKeySchema {
182
182
  readonly onDelete?: ForeignKeyAction;
183
183
  readonly onUpdate?: ForeignKeyAction;
184
184
  }
185
- /**
186
- * One object's change: added (`to` alone), dropped (`from` alone), or altered (both), each whole so the
187
- * change is undone by swapping its ends. No engine alters an index, a key or a foreign key in place, so
188
- * an alter of one is its drop and its add, which safe mode holds back together.
189
- */
190
185
  /** A column's change, and whether it can lose what the column holds: a drop, or a retype that narrows it. */
191
186
  export type ColumnChange = Change<ColumnSchema> & {
192
187
  readonly isBreaking?: boolean;
@@ -198,6 +193,11 @@ export type Rename = {
198
193
  };
199
194
  /** Renamed columns by qualified table name. */
200
195
  export type ColumnRenames = ReadonlyMap<string, readonly Rename[]>;
196
+ /**
197
+ * One object's change: added (`to` alone), dropped (`from` alone), or altered (both). Each side is the whole
198
+ * object, so swapping them undoes the change. No engine alters an index, a key or a foreign key in place, so
199
+ * altering one is a drop plus an add, which safe mode holds back together.
200
+ */
201
201
  export interface Change<T> {
202
202
  readonly from?: T;
203
203
  readonly to?: T;
@@ -3,9 +3,10 @@ import type { SqlDialectName } from './dialect.js';
3
3
  import type { FieldKey, HookEvent, RelationKey } from './entity.js';
4
4
  import type { LoggingOptions } from './logger.js';
5
5
  import type { NamingStrategy } from './namingStrategy.js';
6
- import type { QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpdateResult } from './query.js';
7
- import type { UniversalQuerier } from './universalQuerier.js';
6
+ import type { QueryFilter, QueryFindResult, QueryOptions, QueryPage, QuerySearch, QueryUpdateResult } from './query.js';
7
+ import type { ProjectedQuery, ProjectedRead, ProjectedResult, UniversalQuerier } from './universalQuerier.js';
8
8
  import type { Type } from './utility.js';
9
+ import type { QuerierRaw } from './wire.js';
9
10
  /**
10
11
  * Isolation levels for transactions.
11
12
  */
@@ -22,32 +23,23 @@ export type TransactionOptions = {
22
23
  };
23
24
  export type DialectName = SqlDialectName | 'mongodb';
24
25
  /**
25
- * The read and delete methods below take the entity as an argument or as the query's `$entity` key.
26
- * In each pair the `$entity` overload comes **first** on purpose: when no overload matches,
27
- * TypeScript reports the error from the *last* one, so keeping the entity-argument form last is
28
- * what makes a typo'd query key report as itself rather than as a missing `$entity`.
26
+ * A projected read that takes the entity first or as the query's `$entity`. The `$entity` form comes
27
+ * **first** on purpose: when no signature matches, TypeScript reports the error of the *last* one, so a
28
+ * typo'd query key is reported as itself rather than as a missing `$entity`.
29
29
  */
30
+ type DualRead<Q extends keyof ProjectedQuery<object, never, never, never, never, never, never>, R extends keyof ProjectedResult<'server', unknown>> = (<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: ProjectedQuery<E, S, V, X, P, C, QuerierRaw<'server'>>[Q] & {
31
+ $entity: Type<E>;
32
+ }, opts?: QueryOptions) => ProjectedResult<'server', QueryFindResult<E, S, V, X, P, C>>[R]) & ProjectedRead<Q, R, 'server', QueryOptions>;
33
+ /** The reads, counts and deletes below take the entity first or as the query's `$entity`, as {@link DualRead} does. */
30
34
  export interface Querier extends UniversalQuerier {
31
- /** Find one record, the entity passed first or as the query's `$entity`. */
32
- findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryOneProjected<E, S, V, X, P, C> & {
33
- $entity: Type<E>;
34
- }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
35
- findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
36
- /** Find many records, the entity passed first or as the query's `$entity`. */
37
- findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
38
- $entity: Type<E>;
39
- }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
40
- findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
41
- /** Stream records with the relations and counts `findMany` reads, the entity passed first or as `$entity`. No hooks fire. */
42
- findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
43
- $entity: Type<E>;
44
- }, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
45
- findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
46
- /** Find many records and count every match, the entity passed first or as the query's `$entity`. */
47
- findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
48
- $entity: Type<E>;
49
- }, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P, C>[], number]>;
50
- findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P, C>[], number]>;
35
+ findOne: DualRead<'one', 'one'>;
36
+ findMany: DualRead<'many', 'many'>;
37
+ /** Stream records with the relations and counts `findMany` reads. No hooks fire. */
38
+ findManyStream: DualRead<'many', 'stream'>;
39
+ /** Find many records and count every match. */
40
+ findManyAndCount: DualRead<'many', 'counted'>;
41
+ /** Read a page of records from a cursor. */
42
+ findManyPage: DualRead<'page', 'page'>;
51
43
  /** Count records, the entity passed first or as the query's `$entity`. */
52
44
  count<E extends object>(q: QueryPage<E> & {
53
45
  $entity: Type<E>;
@@ -149,3 +141,4 @@ export type ExtraOptions = {
149
141
  readonly schema?: string;
150
142
  readonly listeners?: readonly QuerierListener[];
151
143
  };
144
+ export {};
@@ -1,4 +1,4 @@
1
- import type { FieldKey, FieldKeyOf, JsonFieldPaths, RelationKey, RelationTarget, ToManyRelationKey, WrittenId } from './entity.js';
1
+ import type { FieldKey, FieldKeyOf, JsonFieldPaths, RelationKey, RelationTarget, ToManyRelationKey, UpdatePayload, WrittenId } from './entity.js';
2
2
  import type { QueryLock } from './queryLock.js';
3
3
  import type { QueryRaw } from './queryRaw.js';
4
4
  import type { QueryWhere } from './queryWhere.js';
@@ -126,8 +126,8 @@ export type FilterOptions<E = unknown> = {
126
126
  /**
127
127
  * direction for the sort, and where nulls land in it.
128
128
  *
129
- * Unqualified, each engine has its own answer - Postgres and CockroachDB sort nulls last on `asc`, the
130
- * rest sort them first - so a placement is the only portable one. Engines with no `NULLS FIRST/LAST`
129
+ * Without a placement, engines disagree: Postgres sorts nulls last on `asc` and the rest sort them first,
130
+ * so only an explicit placement is portable. Engines with no `NULLS FIRST/LAST`
131
131
  * emulate it with a leading term, which no index can serve, which is why it is asked for and never
132
132
  * applied by default.
133
133
  */
@@ -280,31 +280,83 @@ export type Query<E, Raw = QueryRaw> = {
280
280
  */
281
281
  export type WireQuery<E> = Query<E, never>;
282
282
  /**
283
- * `Query`'s clauses grouped by the shape of their value, for the wire parser and the relation query
284
- * check alike; `satisfies` keeps them in step with `Query`.
283
+ * The type of a clause's value, and where the clause may appear: a `relation` clause is also allowed in a
284
+ * populated relation's own query, a `statement` clause only in the statement itself.
285
285
  */
286
- export declare const QUERY_OBJECT_CLAUSES: readonly ["$select", "$populate", "$exclude", "$where", "$sort"];
287
- /**
288
- * Object clauses only the statement itself takes: a populated relation's rows keep their declared type,
289
- * so a `$count` inside one would have no `_count` to land in.
290
- */
291
- export declare const QUERY_ROOT_OBJECT_CLAUSES: readonly ["$count"];
292
- export declare const QUERY_NUMBER_CLAUSES: readonly ["$skip", "$limit"];
293
- /**
294
- * Number clauses only the statement itself takes - the numeric mirror of {@link QUERY_ROOT_OBJECT_CLAUSES}.
295
- * `$candidates` tunes the index behind a vector search, and a vector search only ever ranks the rows
296
- * the statement returns, so a relation's own query has nothing to tune.
297
- */
298
- export declare const QUERY_ROOT_NUMBER_CLAUSES: readonly ["$candidates"];
299
- export declare const QUERY_BOOLEAN_CLAUSES: readonly ["$distinct"];
300
- /** The clauses that describe the statement, which a populated relation's own query refuses by name. */
301
- export declare const QUERY_STATEMENT_CLAUSES: readonly ["$lock", "$count", "$candidates"];
302
- type RelationClause = (typeof QUERY_OBJECT_CLAUSES | typeof QUERY_NUMBER_CLAUSES | typeof QUERY_BOOLEAN_CLAUSES)[number];
286
+ export type QueryClause = {
287
+ readonly value: 'object' | 'number' | 'boolean' | 'string';
288
+ readonly scope: 'relation' | 'statement';
289
+ };
303
290
  /**
304
- * A populated relation's own query: the clause groups its runtime check accepts, so the two cannot
305
- * drift, and a clause added to {@link Query} stays off it until it joins one of them.
291
+ * Every clause of `Query` and `QueryKeyset`, read by both the wire parser and the relation query check. It
292
+ * must cover both types, so a clause added to either fails to compile until it is declared here.
306
293
  */
307
- export type RelationQuery<E = object, Raw = QueryRaw> = Pick<Query<E, Raw>, RelationClause> & {
294
+ export declare const QUERY_CLAUSES: {
295
+ readonly $select: {
296
+ readonly value: 'object';
297
+ readonly scope: 'relation';
298
+ };
299
+ readonly $populate: {
300
+ readonly value: 'object';
301
+ readonly scope: 'relation';
302
+ };
303
+ readonly $exclude: {
304
+ readonly value: 'object';
305
+ readonly scope: 'relation';
306
+ };
307
+ readonly $where: {
308
+ readonly value: 'object';
309
+ readonly scope: 'relation';
310
+ };
311
+ readonly $sort: {
312
+ readonly value: 'object';
313
+ readonly scope: 'relation';
314
+ };
315
+ readonly $skip: {
316
+ readonly value: 'number';
317
+ readonly scope: 'relation';
318
+ };
319
+ readonly $limit: {
320
+ readonly value: 'number';
321
+ readonly scope: 'relation';
322
+ };
323
+ readonly $distinct: {
324
+ readonly value: 'boolean';
325
+ readonly scope: 'relation';
326
+ };
327
+ readonly $count: {
328
+ readonly value: 'object';
329
+ readonly scope: 'statement';
330
+ };
331
+ readonly $candidates: {
332
+ readonly value: 'number';
333
+ readonly scope: 'statement';
334
+ };
335
+ readonly $lock: {
336
+ readonly value: 'object';
337
+ readonly scope: 'statement';
338
+ };
339
+ readonly $after: {
340
+ readonly value: 'string';
341
+ readonly scope: 'statement';
342
+ };
343
+ readonly $before: {
344
+ readonly value: 'string';
345
+ readonly scope: 'statement';
346
+ };
347
+ };
348
+ type QueryClauseKey = keyof typeof QUERY_CLAUSES;
349
+ /** The keys of the `QUERY_CLAUSES` entries that match `Shape`, such as `{ scope: 'relation' }`. */
350
+ export type QueryClauseOf<Shape extends Partial<QueryClause>> = {
351
+ [K in QueryClauseKey]: (typeof QUERY_CLAUSES)[K] extends Shape ? K : never;
352
+ }[QueryClauseKey];
353
+ /**
354
+ * A populated relation's own query: the clauses {@link QUERY_CLAUSES} gives the `relation` scope. Its runtime
355
+ * check reads the same table, so the two cannot drift.
356
+ */
357
+ export type RelationQuery<E = object, Raw = QueryRaw> = Pick<Query<E, Raw>, QueryClauseOf<{
358
+ scope: 'relation';
359
+ }>> & {
308
360
  $required?: boolean;
309
361
  };
310
362
  /**
@@ -334,6 +386,34 @@ export type QueryProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P
334
386
  * A {@link QueryOne} whose projection is captured, so {@link QueryFindResult} can shape the row.
335
387
  */
336
388
  export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never, Raw = QueryRaw> = QueryOne<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;
389
+ /**
390
+ * The query `findManyPage` takes: a {@link Query} paged by cursor instead of offset, so it has no `$skip` and
391
+ * `$limit` is the page size. `$after` reads the page after a cursor, `$before` the page before it.
392
+ */
393
+ export type QueryKeyset<E, Raw = QueryRaw> = Except<Query<E, Raw>, '$skip'> & {
394
+ /** The page size, required here although `Query` leaves it optional. */
395
+ $limit: number;
396
+ /** A page's `endCursor`, to read the rows after it. */
397
+ $after?: string;
398
+ /** A page's `startCursor`, to read the rows before it. */
399
+ $before?: string;
400
+ };
401
+ /** A {@link QueryKeyset} with its projection captured, so {@link QueryFindResult} can narrow the row. */
402
+ export type QueryKeysetProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never, Raw = QueryRaw> = QueryKeyset<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;
403
+ /**
404
+ * One page of `findManyPage`. Each cursor is opaque, and absent on an empty page. The flag in the reading
405
+ * direction is exact. The other one only says whether the page was read from a cursor (`hasPrevPage` forward,
406
+ * `hasNextPage` backward), since checking for rows on that side would cost another statement.
407
+ */
408
+ export type CursorPage<T> = {
409
+ readonly items: T[];
410
+ /** Pass as `$before` to read the page before this one. */
411
+ readonly startCursor?: string;
412
+ /** Pass as `$after` to read the page after this one. */
413
+ readonly endCursor?: string;
414
+ readonly hasNextPage: boolean;
415
+ readonly hasPrevPage: boolean;
416
+ };
337
417
  /**
338
418
  * The keys a query comes back with, as the runtime projects them: a positive `$select`'s, or every
339
419
  * field minus what `$select` or `$exclude` subtracts, plus the populated relations.
@@ -367,6 +447,17 @@ Pick<E, Exclude<ProjectedKeys<E, S, V, X, P>, PopulatedToMany<E, P>> & keyof E>
367
447
  } : E;
368
448
  /** The to-many relations a query populated, which come back as lists rather than as optional ones. */
369
449
  type PopulatedToMany<E, P> = Extract<P, ToManyRelationKey<E>>;
450
+ /**
451
+ * How an upsert treats a row its conflict paths find: by default it takes the payload, less those paths. `U` is
452
+ * what a trigger's `upsertInto` narrows the update to.
453
+ */
454
+ export type UpsertOptions<E, U = UpdatePayload<E>> = {
455
+ /**
456
+ * What such a row takes instead, as an update does, `{ uses: { $inc: 1 } }` counting; `{}` leaves it as it is,
457
+ * inserting only where none is. The payload still inserts.
458
+ */
459
+ readonly update?: U;
460
+ };
370
461
  /** What upserting one row reports. `created` is only knowable for a single statement, so a batch has none. */
371
462
  export type QueryUpsertOneResult<E> = {
372
463
  readonly id?: WrittenId<E>;
@@ -4,32 +4,25 @@
4
4
  */
5
5
  export const COUNT_RESULT_KEY = '_count';
6
6
  /**
7
- * `Query`'s clauses grouped by the shape of their value, for the wire parser and the relation query
8
- * check alike; `satisfies` keeps them in step with `Query`.
7
+ * Every clause of `Query` and `QueryKeyset`, read by both the wire parser and the relation query check. It
8
+ * must cover both types, so a clause added to either fails to compile until it is declared here.
9
9
  */
10
- export const QUERY_OBJECT_CLAUSES = [
11
- '$select',
12
- '$populate',
13
- '$exclude',
14
- '$where',
15
- '$sort',
16
- ];
17
- /**
18
- * Object clauses only the statement itself takes: a populated relation's rows keep their declared type,
19
- * so a `$count` inside one would have no `_count` to land in.
20
- */
21
- export const QUERY_ROOT_OBJECT_CLAUSES = ['$count'];
22
- export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
23
- /**
24
- * Number clauses only the statement itself takes - the numeric mirror of {@link QUERY_ROOT_OBJECT_CLAUSES}.
25
- * `$candidates` tunes the index behind a vector search, and a vector search only ever ranks the rows
26
- * the statement returns, so a relation's own query has nothing to tune.
27
- */
28
- export const QUERY_ROOT_NUMBER_CLAUSES = ['$candidates'];
29
- export const QUERY_BOOLEAN_CLAUSES = ['$distinct'];
30
- /** The clauses that describe the statement, which a populated relation's own query refuses by name. */
31
- export const QUERY_STATEMENT_CLAUSES = [
32
- '$lock',
33
- ...QUERY_ROOT_OBJECT_CLAUSES,
34
- ...QUERY_ROOT_NUMBER_CLAUSES,
35
- ];
10
+ export const QUERY_CLAUSES = {
11
+ $select: { value: 'object', scope: 'relation' },
12
+ $populate: { value: 'object', scope: 'relation' },
13
+ $exclude: { value: 'object', scope: 'relation' },
14
+ $where: { value: 'object', scope: 'relation' },
15
+ $sort: { value: 'object', scope: 'relation' },
16
+ $skip: { value: 'number', scope: 'relation' },
17
+ $limit: { value: 'number', scope: 'relation' },
18
+ $distinct: { value: 'boolean', scope: 'relation' },
19
+ // A populated relation's rows keep their declared type, so they have no `_count` for a `$count` to fill.
20
+ $count: { value: 'object', scope: 'statement' },
21
+ // A vector search ranks only the statement's rows, so a relation's own query has nothing for it to tune.
22
+ $candidates: { value: 'number', scope: 'statement' },
23
+ // Never decoded: HTTP refuses it, because a request cannot hold a lock past its response.
24
+ $lock: { value: 'object', scope: 'statement' },
25
+ // Statement only: keyset paging per parent of a populated relation is not supported.
26
+ $after: { value: 'string', scope: 'statement' },
27
+ $before: { value: 'string', scope: 'statement' },
28
+ };