uql-orm 0.104.1 → 0.105.1

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 (161) hide show
  1. package/README.md +24 -10
  2. package/dist/browser/querier/httpQuerier.d.ts +3 -3
  3. package/dist/browser/type/clientQuerier.d.ts +1 -1
  4. package/dist/browser/uql-browser.min.js +2 -2
  5. package/dist/browser/uql-browser.min.js.map +9 -9
  6. package/dist/cockroachdb/cockroachDialect.d.ts +2 -2
  7. package/dist/dialect/abstractDialect.d.ts +3 -3
  8. package/dist/dialect/abstractSqlDialect.d.ts +39 -37
  9. package/dist/dialect/abstractSqlDialect.js +35 -32
  10. package/dist/dialect/aliases.d.ts +2 -0
  11. package/dist/dialect/aliases.js +2 -0
  12. package/dist/dialect/jsonSql.js +2 -2
  13. package/dist/dialect/mergeSqlDialect.d.ts +2 -2
  14. package/dist/dialect/mysqlLikeSqlDialect.d.ts +7 -7
  15. package/dist/dialect/mysqlLikeSqlDialect.js +1 -1
  16. package/dist/dialect/operators.js +2 -4
  17. package/dist/dialect/queryJoins.d.ts +4 -2
  18. package/dist/dialect/vectorSqlDialect.d.ts +1 -1
  19. package/dist/dialect/vectorSqlDialect.js +1 -1
  20. package/dist/entity/column.d.ts +3 -0
  21. package/dist/entity/column.js +3 -0
  22. package/dist/entity/columnOptionsBuilder.d.ts +54 -0
  23. package/dist/entity/columnOptionsBuilder.js +108 -0
  24. package/dist/entity/decorator/bag.d.ts +5 -5
  25. package/dist/entity/decorator/entity.d.ts +3 -20
  26. package/dist/entity/decorator/entity.js +3 -37
  27. package/dist/entity/decorator/members.d.ts +46 -76
  28. package/dist/entity/decorator/members.js +18 -7
  29. package/dist/entity/index.d.ts +2 -1
  30. package/dist/entity/index.js +2 -1
  31. package/dist/entity/metadata/definition.d.ts +15 -26
  32. package/dist/entity/metadata/definition.js +344 -148
  33. package/dist/entity/metadata/schemaFixture/animal.d.ts +54 -0
  34. package/dist/entity/metadata/schemaFixture/animal.js +7 -0
  35. package/dist/entity/metadata/schemaFixture/author.d.ts +140 -0
  36. package/dist/entity/metadata/schemaFixture/author.js +25 -0
  37. package/dist/entity/metadata/schemaFixture/book.d.ts +192 -0
  38. package/dist/entity/metadata/schemaFixture/book.js +23 -0
  39. package/dist/http/contract.d.ts +2 -2
  40. package/dist/http/handler.d.ts +2 -2
  41. package/dist/http/query.js +12 -13
  42. package/dist/index.d.ts +2 -2
  43. package/dist/index.js +2 -1
  44. package/dist/mariadb/mariaDialect.d.ts +2 -2
  45. package/dist/mariadb/mariaDialect.js +1 -1
  46. package/dist/mariadb/mariadbQuerier.js +1 -3
  47. package/dist/migrate/builder/columnBuilder.d.ts +20 -68
  48. package/dist/migrate/builder/columnBuilder.js +104 -110
  49. package/dist/migrate/builder/migrationBuilder.d.ts +3 -3
  50. package/dist/migrate/builder/migrationBuilder.js +7 -6
  51. package/dist/migrate/builder/tableBuilder.d.ts +3 -55
  52. package/dist/migrate/builder/tableBuilder.js +88 -204
  53. package/dist/migrate/builder/types.d.ts +52 -151
  54. package/dist/migrate/builder/types.js +0 -6
  55. package/dist/migrate/codegen/entityCodeGenerator.d.ts +2 -2
  56. package/dist/migrate/codegen/entityCodeGenerator.js +24 -24
  57. package/dist/migrate/codegen/entityTypes.d.ts +2 -2
  58. package/dist/migrate/codegen/fieldOptionsSource.d.ts +3 -1
  59. package/dist/migrate/codegen/fieldOptionsSource.js +35 -34
  60. package/dist/migrate/codegen/indexEntrySource.d.ts +16 -0
  61. package/dist/migrate/codegen/{indexDecoratorSource.js → indexEntrySource.js} +54 -27
  62. package/dist/migrate/ddl/defaultSql.js +7 -6
  63. package/dist/migrate/ddl/indexCapabilities.d.ts +8 -7
  64. package/dist/migrate/ddl/indexCapabilities.js +26 -13
  65. package/dist/migrate/ddl/indexDdl.d.ts +13 -13
  66. package/dist/migrate/ddl/indexDdl.js +33 -30
  67. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +6 -11
  68. package/dist/migrate/ddl/mysqlIndexDdl.js +17 -28
  69. package/dist/migrate/ddl/pgIndexDdl.d.ts +2 -2
  70. package/dist/migrate/ddl/sqliteIndexDdl.d.ts +2 -2
  71. package/dist/migrate/drift/driftDetector.js +2 -2
  72. package/dist/migrate/generator/definitionToNode.d.ts +8 -2
  73. package/dist/migrate/generator/definitionToNode.js +4 -5
  74. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +11 -2
  75. package/dist/migrate/introspection/jsonIndexEntry.d.ts +6 -0
  76. package/dist/migrate/introspection/jsonIndexEntry.js +120 -0
  77. package/dist/migrate/introspection/mysqlIntrospector.d.ts +4 -4
  78. package/dist/migrate/introspection/mysqlIntrospector.js +25 -21
  79. package/dist/migrate/introspection/postgresIntrospector.d.ts +1 -1
  80. package/dist/migrate/introspection/postgresIntrospector.js +3 -4
  81. package/dist/migrate/introspection/sqliteIntrospector.js +24 -9
  82. package/dist/migrate/introspection/tableSchemaAST.js +5 -1
  83. package/dist/migrate/migrator.d.ts +2 -2
  84. package/dist/migrate/schemaChange.d.ts +3 -3
  85. package/dist/migrate/schemaChange.js +3 -2
  86. package/dist/migrate/schemaGenerator.d.ts +5 -5
  87. package/dist/migrate/schemaGenerator.js +1 -1
  88. package/dist/migrate/storage/databaseStorage.js +4 -4
  89. package/dist/mongodb/mongoDialect.d.ts +41 -44
  90. package/dist/mongodb/mongoDialect.js +118 -32
  91. package/dist/mongodb/mongoIntrospector.d.ts +3 -1
  92. package/dist/mongodb/mongoIntrospector.js +11 -5
  93. package/dist/mongodb/mongoSchemaGenerator.d.ts +4 -4
  94. package/dist/mongodb/mongoSchemaGenerator.js +35 -27
  95. package/dist/mongodb/mongodbQuerier.d.ts +1 -11
  96. package/dist/mongodb/mongodbQuerier.js +9 -43
  97. package/dist/mssql/mssqlDialect.d.ts +4 -4
  98. package/dist/postgres/postgresDialect.d.ts +2 -2
  99. package/dist/querier/abstractQuerier.d.ts +0 -1
  100. package/dist/querier/abstractQuerier.js +1 -20
  101. package/dist/querier/abstractSqlQuerier.d.ts +1 -1
  102. package/dist/querier/keyset.js +3 -3
  103. package/dist/schema/declaredColumn.d.ts +11 -0
  104. package/dist/schema/declaredColumn.js +21 -0
  105. package/dist/schema/indexColumns.d.ts +0 -3
  106. package/dist/schema/indexColumns.js +11 -7
  107. package/dist/schema/indexDifferences.d.ts +10 -5
  108. package/dist/schema/indexDifferences.js +42 -28
  109. package/dist/schema/schemaASTBuilder.d.ts +4 -4
  110. package/dist/schema/schemaASTBuilder.js +28 -36
  111. package/dist/schema/schemaASTDiffer.js +8 -4
  112. package/dist/schema/sqlExpression.d.ts +21 -17
  113. package/dist/schema/sqlExpression.js +11 -23
  114. package/dist/type/column.d.ts +328 -0
  115. package/dist/type/column.js +2 -0
  116. package/dist/type/config.d.ts +3 -3
  117. package/dist/type/dialect.d.ts +15 -14
  118. package/dist/type/dialect.js +1 -0
  119. package/dist/type/entity.d.ts +292 -281
  120. package/dist/type/entity.js +6 -1
  121. package/dist/type/index.d.ts +2 -0
  122. package/dist/type/index.js +2 -0
  123. package/dist/type/migration.d.ts +11 -11
  124. package/dist/type/querier.d.ts +2 -2
  125. package/dist/type/query.d.ts +44 -40
  126. package/dist/type/query.js +2 -3
  127. package/dist/type/queryAggregate.d.ts +22 -12
  128. package/dist/type/querySql.d.ts +22 -6
  129. package/dist/type/querySql.js +27 -9
  130. package/dist/type/schemaEntity.d.ts +194 -0
  131. package/dist/type/schemaEntity.js +1 -0
  132. package/dist/type/utility.d.ts +4 -7
  133. package/dist/type/vector.d.ts +1 -1
  134. package/dist/util/ddlExpression.util.d.ts +12 -13
  135. package/dist/util/ddlExpression.util.js +12 -21
  136. package/dist/util/dialect.util.d.ts +11 -5
  137. package/dist/util/dialect.util.js +31 -37
  138. package/dist/util/field.util.d.ts +10 -9
  139. package/dist/util/field.util.js +14 -10
  140. package/dist/util/fieldOption.util.d.ts +11 -95
  141. package/dist/util/fieldOption.util.js +49 -16
  142. package/dist/util/hook.util.d.ts +3 -15
  143. package/dist/util/hook.util.js +3 -16
  144. package/dist/util/index.d.ts +1 -0
  145. package/dist/util/index.js +1 -0
  146. package/dist/util/indexEntry.util.d.ts +45 -0
  147. package/dist/util/indexEntry.util.js +138 -0
  148. package/dist/util/relationQuery.util.d.ts +0 -1
  149. package/dist/util/relationQuery.util.js +0 -5
  150. package/dist/util/sql.d.ts +13 -10
  151. package/dist/util/sql.js +34 -16
  152. package/dist/util/sql.util.d.ts +4 -5
  153. package/dist/util/sql.util.js +7 -16
  154. package/dist/util/string.util.d.ts +2 -0
  155. package/dist/util/string.util.js +4 -0
  156. package/dist/util/triggerWrite.d.ts +5 -5
  157. package/dist/util/uqlError.d.ts +1 -1
  158. package/dist/util/uqlError.js +1 -1
  159. package/package.json +1 -1
  160. package/skills/uql-orm/SKILL.md +76 -25
  161. package/dist/migrate/codegen/indexDecoratorSource.d.ts +0 -16
@@ -8,7 +8,7 @@ export const idKey = Symbol('idKey');
8
8
  export const versionKey = Symbol('versionKey');
9
9
  /** Brands the fields an insert may leave out, which a default fills, `[filledKey]?: 'units' | 'createdAt'`; each stays present on every read. */
10
10
  export const filledKey = Symbol('filledKey');
11
- /** The filter `@Field({ softDelete })` registers, a name reserved against an entity's own filters. */
11
+ /** The filter a `softDelete()` column registers, a name reserved against an entity's own filters. */
12
12
  export const SOFT_DELETE_FILTER = 'softDelete';
13
13
  /** Every SQL column type a field may declare, by family: the unions below and `columnFamily` both read it. */
14
14
  export const COLUMN_TYPES = {
@@ -34,3 +34,8 @@ export const COLUMN_TYPES = {
34
34
  boolean: ['bool', 'boolean'],
35
35
  vector: ['vector', 'halfvec', 'sparsevec'],
36
36
  };
37
+ /**
38
+ * Marks what a section's helper returned, so a section takes only what TypeScript checked: it checks a literal
39
+ * passed to a function, and never one a callback returns, where `{ uniqe: true }` would pass silently.
40
+ */
41
+ export const SECTION_ENTRY = Symbol('sectionEntry');
@@ -11,8 +11,10 @@ export * from './query.js';
11
11
  export * from './queryAggregate.js';
12
12
  export * from './queryLock.js';
13
13
  export * from './querySql.js';
14
+ export * from './schemaEntity.js';
14
15
  export * from './queryWhere.js';
15
16
  export * from './universalQuerier.js';
16
17
  export * from './utility.js';
17
18
  export * from './vector.js';
18
19
  export * from './wire.js';
20
+ export * from './column.js';
@@ -11,8 +11,10 @@ export * from './query.js';
11
11
  export * from './queryAggregate.js';
12
12
  export * from './queryLock.js';
13
13
  export * from './querySql.js';
14
+ export * from './schemaEntity.js';
14
15
  export * from './queryWhere.js';
15
16
  export * from './universalQuerier.js';
16
17
  export * from './utility.js';
17
18
  export * from './vector.js';
18
19
  export * from './wire.js';
20
+ export * from './column.js';
@@ -2,7 +2,7 @@ import type { AnyMigrationOperation } from '../migrate/builder/types.js';
2
2
  import type { SchemaAST } from '../schema/schemaAST.js';
3
3
  import type { DiffOptions } from '../schema/schemaASTDiffer.js';
4
4
  import type { CheckSchema, ColumnNode, ForeignKeyAction, IndexType, TableNode, TriggerSchema } from '../schema/types.js';
5
- import type { Except, IndexColumnSchema, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
5
+ import type { Except, IndexEntry, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, AbstractType, VectorIndexOptions } from './index.js';
6
6
  /**
7
7
  * Defines a migration using a simple object literal. `Q` is `MongoQuerier` for a MongoDB migration.
8
8
  */
@@ -59,7 +59,7 @@ export interface MigratorOptions {
59
59
  /**
60
60
  * Entities to use for schema generation
61
61
  */
62
- readonly entities?: Type<object>[];
62
+ readonly entities?: AbstractType<object>[];
63
63
  /**
64
64
  * Default action for foreign key ON DELETE and ON UPDATE clauses.
65
65
  */
@@ -128,10 +128,10 @@ export interface IndexSchema extends VectorIndexOptions, IndexedVectorField {
128
128
  /**
129
129
  * What the index is over, in order. Named `entries` and not `columns` because an entry need not be
130
130
  * a column at all: ``sql`lower(email)` `` is one, and so is a column carrying a prefix length or a
131
- * stored order. The authored form, `@Index`, still spells this `columns`, since that is what
132
- * it reads like at the call site.
131
+ * stored order. An entity's `indexes` entry, as authored, still spells this `columns`, since that is
132
+ * what it reads like there.
133
133
  */
134
- readonly entries: readonly IndexColumnSchema[];
134
+ readonly entries: readonly IndexEntry<string>[];
135
135
  readonly unique: boolean;
136
136
  /** Index type (btree, hnsw, ivfflat, etc.) */
137
137
  readonly type?: IndexType;
@@ -150,7 +150,7 @@ export interface ForeignKeySchema {
150
150
  readonly columns: string[];
151
151
  /**
152
152
  * The far end, as one thing. Same shape and same name as everywhere else a relationship's target is
153
- * described - `@Field({ references })`, `addForeignKey`'s `target`, a `RelationshipNode`'s `to` -
153
+ * described - `f.references()`, `addForeignKey`'s `target`, a `RelationshipNode`'s `to` -
154
154
  * so nothing has to be destructured on the way between them.
155
155
  */
156
156
  readonly references: {
@@ -225,7 +225,7 @@ export interface SyncOptions {
225
225
  readonly drop?: boolean;
226
226
  readonly logging?: boolean;
227
227
  /** One entity instead of every registered one, for a schema that grows while the process runs. */
228
- readonly entity?: Type<object>;
228
+ readonly entity?: AbstractType<object>;
229
229
  /** Drop every table and recreate it. Development only: it is the one option that loses data. */
230
230
  readonly force?: boolean;
231
231
  }
@@ -250,13 +250,13 @@ export interface DropSchemaOptions {
250
250
  */
251
251
  export interface SchemaGenerator {
252
252
  /** The whole schema for `entities`, tables then the foreign keys between them, which need every entity at once. */
253
- generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
253
+ generateCreateSchema(entities: readonly AbstractType<object>[], options?: CreateSchemaOptions): string[];
254
254
  /**
255
255
  * Every `DROP TABLE` for `entities`, dependents first. The inverse of {@link generateCreateSchema},
256
256
  * and the reason it takes the whole set: dropping in any order that ignores the relation graph is
257
257
  * rejected once the foreign keys are really there.
258
258
  */
259
- generateDropSchema(entities: readonly Type<object>[], options?: DropSchemaOptions): string[];
259
+ generateDropSchema(entities: readonly AbstractType<object>[], options?: DropSchemaOptions): string[];
260
260
  /** The statements taking a table through `diff`; its rollback is `rollbackDiff(diff)`. */
261
261
  generateAlterTable(diff: SchemaDiff): string[];
262
262
  /**
@@ -269,9 +269,9 @@ export interface SchemaGenerator {
269
269
  * a foreign key here points at, or those keys read as matching.
270
270
  * `renamedColumns` are columns `currentTable` already holds under their new names.
271
271
  */
272
- diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST, renamedColumns?: readonly Rename[]): SchemaDiff | undefined;
272
+ diffSchema(entity: AbstractType<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST, renamedColumns?: readonly Rename[]): SchemaDiff | undefined;
273
273
  /** The entities as one AST, built once per run for every {@link diffSchema}. Absent on MongoDB, which diffs only indexes and a validator. */
274
- buildAST?(entities: readonly Type<object>[]): SchemaAST;
274
+ buildAST?(entities: readonly AbstractType<object>[]): SchemaAST;
275
275
  /** How this engine's diff compares types and defaults. Absent where {@link buildAST} is. */
276
276
  diffOptions?(): DiffOptions;
277
277
  }
@@ -6,7 +6,7 @@ import type { NamingStrategy } from './namingStrategy.js';
6
6
  import type { Captured, QueryFilter, QueryFindResult, QueryOptions, QueryPage, QuerySearch, QueryUpdateResult, WriteResults, WriteOptions } from './query.js';
7
7
  import type { QuerySql, SqlStatement } from './querySql.js';
8
8
  import type { EntityRead, ReadResults, ReadQueries, UniversalQuerier } from './universalQuerier.js';
9
- import type { BooleanLike, RawRow, Type } from './utility.js';
9
+ import type { BooleanLike, Type, RawRow, AbstractType } from './utility.js';
10
10
  /**
11
11
  * Isolation levels for transactions.
12
12
  */
@@ -136,7 +136,7 @@ export declare function isSqlQuerier(querier: Querier): querier is SqlQuerier;
136
136
  * Context passed to global querier listeners.
137
137
  */
138
138
  export type ListenerContext<E extends object = object> = {
139
- readonly entity: Type<E>;
139
+ readonly entity: AbstractType<E>;
140
140
  readonly querier: Querier;
141
141
  readonly payloads: readonly E[];
142
142
  readonly event: HookEvent;
@@ -1,4 +1,4 @@
1
- import type { FieldKey, FieldKeyOf, JsonFieldPaths, RelationKey, RelationTarget, ToManyRelationKey, WrittenId } from './entity.js';
1
+ import type { FieldKey, FieldKeyOf, JsonFieldPaths, MethodKey, RelationKey, RelationTarget, ToManyRelationKey, WrittenId } from './entity.js';
2
2
  import type { QueryLock } from './queryLock.js';
3
3
  import type { QuerySql } from './querySql.js';
4
4
  import type { QueryWhere } from './queryWhere.js';
@@ -53,11 +53,6 @@ export type QuerySelect<E, F extends keyof E = FieldKey<E>, V = BooleanLike> = {
53
53
  * (e.g. ``[sql`*`, sql`LOG10(points)`.as('score')]``). The raw form is SQL-only.
54
54
  */
55
55
  export type QuerySelectValue<E, Sql = QuerySql> = QuerySelect<E> | readonly Sql[];
56
- /**
57
- * Fields to exclude from the query result - `{ name: true }` blacklists fields.
58
- * Mutually exclusive with positive field selections in `$select`.
59
- */
60
- export type QueryExclude<E> = QuerySelect<E>;
61
56
  /**
62
57
  * relation population map.
63
58
  */
@@ -105,7 +100,7 @@ export type FilterWhere<E> = QueryWhere<E> | ((context: UqlContext | undefined)
105
100
  */
106
101
  export type FilterOnMissing = 'skip' | 'throw';
107
102
  /**
108
- * Authoring shape for `@Entity({ filters })` / `@Filter` / `defineFilter`.
103
+ * Authoring shape for `@Entity({ filters })` and a schema's `filters`.
109
104
  */
110
105
  export type FilterOptions<E = unknown> = {
111
106
  readonly where: FilterWhere<E>;
@@ -163,11 +158,6 @@ export type QuerySortByText = {
163
158
  readonly $order?: QuerySortDirection;
164
159
  };
165
160
  };
166
- /**
167
- * A row with the value a `$sort` projects under the name its `$project` gives - a vector's distance, or a
168
- * `$text` relevance - which is not inferred: `(await querier.findMany(Post, q)) as WithProjection<Post, 'score'>[]`.
169
- */
170
- export type WithProjection<E, K extends string> = E & Record<K, number>;
171
161
  /**
172
162
  * A sort by fields, JSON paths, a to-one relation's fields, a to-many's `$count` or nearest row, a vector
173
163
  * distance, or - where `Root` says it sorts the queried entity itself, not a relation's rows - a `$text`
@@ -223,9 +213,10 @@ export type QuerySearch<E, Sql = QuerySql> = QueryPage<E, Sql> & {
223
213
  */
224
214
  export type Query<E, Sql = QuerySql> = {
225
215
  /**
226
- * field selection - `{ name: true }` whitelists fields, or raw SQL projections
227
- * (``[sql`LOG10(points)`.as('score')]``, SQL dialects only - MongoDB rejects the raw-array form).
228
- * Mutually exclusive with `$exclude`.
216
+ * field selection - `{ name: true }` whitelists fields, `{ body: false }` leaves fields out, or raw SQL
217
+ * projections (``[sql`LOG10(points)`.as('score')]``, SQL dialects only - MongoDB rejects the raw-array form).
218
+ * A map with a positive entry selects those alone. Keys a relation is assembled from (a joined row's primary
219
+ * key, a to-many's foreign key) are read regardless, since leaving them out would leave the relation unfilled.
229
220
  */
230
221
  $select?: QuerySelectValue<E, Sql>;
231
222
  /**
@@ -236,12 +227,6 @@ export type Query<E, Sql = QuerySql> = {
236
227
  * how many rows each named relation holds, under `_count` on every row. See {@link QueryCount}.
237
228
  */
238
229
  $count?: QueryCount<E, Sql>;
239
- /**
240
- * field exclusion - `{ name: true }` blacklists fields. Mutually exclusive with positive `$select`.
241
- * Keys a relation is assembled from (a joined row's primary key, a to-many's foreign key) are kept
242
- * regardless, since subtracting them would leave the relation unfilled.
243
- */
244
- $exclude?: QueryExclude<E>;
245
230
  /**
246
231
  * sorting options, vector similarity search included: a SELECT is the one statement with a
247
232
  * projection list to hold the distance such a search computes.
@@ -281,11 +266,13 @@ export type Query<E, Sql = QuerySql> = {
281
266
  export type WireQuery<E> = Query<E, never>;
282
267
  /**
283
268
  * 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 `sql` clause only in the statement itself.
269
+ * populated relation's own query, a `statement` clause only in the statement itself, and a `wire: false`
270
+ * clause never over HTTP.
285
271
  */
286
272
  export type QueryClause = {
287
273
  readonly value: 'object' | 'number' | 'boolean' | 'string';
288
274
  readonly scope: 'relation' | 'statement';
275
+ readonly wire?: false;
289
276
  };
290
277
  /**
291
278
  * Every clause of `Query` and `QueryKeyset`, read by both the wire parser and the relation query check. It
@@ -300,10 +287,6 @@ export declare const QUERY_CLAUSES: {
300
287
  readonly value: 'object';
301
288
  readonly scope: 'relation';
302
289
  };
303
- readonly $exclude: {
304
- readonly value: 'object';
305
- readonly scope: 'relation';
306
- };
307
290
  readonly $where: {
308
291
  readonly value: 'object';
309
292
  readonly scope: 'relation';
@@ -335,6 +318,7 @@ export declare const QUERY_CLAUSES: {
335
318
  readonly $lock: {
336
319
  readonly value: 'object';
337
320
  readonly scope: 'statement';
321
+ readonly wire: false;
338
322
  };
339
323
  readonly $after: {
340
324
  readonly value: 'string';
@@ -366,7 +350,7 @@ export type QueryOne<E, Sql = QuerySql> = Except<Query<E, Sql>, '$limit'>;
366
350
  /**
367
351
  * options to get an unique record.
368
352
  */
369
- export type QueryUnique<E, Sql = QuerySql> = Pick<QueryOne<E, Sql>, '$select' | '$exclude' | '$populate' | '$where'>;
353
+ export type QueryUnique<E, Sql = QuerySql> = Pick<QueryOne<E, Sql>, '$select' | '$populate' | '$where'>;
370
354
  /**
371
355
  * A query as a read captures it: `Q` is inferred from the literal, so the row sees every clause at every
372
356
  * depth, while the parameter is `Concrete` itself, so a typo'd key fails its excess-property check at any
@@ -401,37 +385,57 @@ export type CursorPage<T> = {
401
385
  };
402
386
  /**
403
387
  * A find's row: the entity narrowed to what the query `Q` projected and populated, at every depth, so
404
- * reading anything else does not compile. The entity itself where nothing narrows it. A key union names
405
- * a projection by hand. `K` is internal: `Q` whole, for a key union the test on `Q` distributes over.
388
+ * reading anything else does not compile, plus {@link SortProjections}. The entity itself where nothing
389
+ * narrows it. A key union names a projection by hand.
406
390
  * @example `QueryFindResult<User, 'id' | 'name'>`, `QueryFindResult<User, typeof query>`
407
391
  */
408
- export type QueryFindResult<E, Q = {}, K extends Q = Q> = Q extends ShapingQuery ? ShapedRow<E, Q> : [K] extends [PropertyKey] ? Pick<E, K & keyof E> : E;
392
+ export type QueryFindResult<E, Q = {}> = [Q] extends [PropertyKey] ? Pick<E, Q & keyof E> : FindRow<E, Q>;
393
+ /** What a `$sort` projects, each a number under the name its `$project` gives. */
394
+ type SortProjections<Q> = Q extends {
395
+ readonly $sort: {
396
+ readonly [key: string]: infer V;
397
+ };
398
+ } ? Projected<ProjectedName<V>> : unknown;
399
+ type ProjectedName<V> = V extends {
400
+ readonly $project: infer N extends string;
401
+ } ? N : never;
402
+ type Projected<N extends string> = [N] extends [never] ? unknown : {
403
+ readonly [K in N]: number;
404
+ };
409
405
  /** The clauses that shape a row; a query naming none of them reads the entity as it is. */
410
406
  type ShapingQuery = {
411
407
  readonly $select: object;
412
- } | {
413
- readonly $exclude: object;
414
408
  } | {
415
409
  readonly $populate: object;
416
410
  } | {
417
411
  readonly $count: object;
418
412
  };
419
413
  /**
420
- * A nested relation's row, as {@link QueryFindResult} without the key-union form. Every alias layer and
421
- * conditional from here down is paid on each read, measured with `bun run ts.perf`.
414
+ * A row at any depth, as {@link QueryFindResult} without the key-union form. Every alias layer and
415
+ * conditional from here down is paid on each read, measured with `bun run ts.perf`: the shaping is
416
+ * written twice so a read with no `$sort` skips the projections, cheaper than an alias over it.
417
+ */
418
+ type FindRow<E, Q> = Q extends {
419
+ readonly $sort: object;
420
+ } ? (Q extends ShapingQuery ? ShapedRow<E, Q> : DataRow<E>) & SortProjections<Q> : Q extends ShapingQuery ? ShapedRow<E, Q> : DataRow<E>;
421
+ /**
422
+ * The entity as a row reads it: plain data, so a method of the class it is read through is `never` and does not
423
+ * compile. Still an `E`, which generic code returning or indexing its rows relies on.
422
424
  */
423
- type FindRow<E, Q> = Q extends ShapingQuery ? ShapedRow<E, Q> : E;
425
+ type DataRow<E> = E & MethodMask<E>;
426
+ /** Each method of `E` as `never`, built once per entity and laid over any row read off it. */
427
+ type MethodMask<E, M extends keyof E = MethodKey<E>> = [M] extends [never] ? unknown : {
428
+ readonly [K in M]: never;
429
+ };
424
430
  /**
425
431
  * The row's own fields, and its relations beside them. A positive `$select` entry wins outright at runtime, so a
426
- * map with one selects its positive keys alone; one with none subtracts, as a truthy `$exclude` entry does. `Pick`,
432
+ * map with one selects its positive keys alone; one with none leaves its keys out. `Pick`,
427
433
  * not a key remap: an entity keyed by an index signature, a content type defined at runtime, has `string` for its
428
434
  * keys, which a remap drops.
429
435
  */
430
436
  type ShapedRow<E, Q> = Q extends {
431
437
  readonly $select: infer M;
432
- } ? (M extends readonly unknown[] ? WholeRow<E, Q> : M[keyof M] extends true | 1 ? Pick<E, ([keyof M] extends [never] ? FieldKey<E> : keyof M) & keyof E> : M[keyof M] extends Off ? Pick<E, Exclude<FieldKey<E>, keyof M> & keyof E> : Pick<E, OnKeys<M> & keyof E> & MaybeFields<E, M>) & RelatedRows<E, Q> : Q extends {
433
- readonly $exclude: infer M;
434
- } ? (M[keyof M] extends true | 1 ? Pick<E, Exclude<FieldKey<E>, keyof M> & keyof E> : Pick<E, Exclude<FieldKey<E>, OnKeys<M> | MaybeKeys<M>> & keyof E> & MaybeFields<E, M>) & RelatedRows<E, Q> : WholeRow<E, Q> & RelatedRows<E, Q>;
438
+ } ? (M extends readonly unknown[] ? WholeRow<E, Q> : M[keyof M] extends true | 1 ? Pick<E, ([keyof M] extends [never] ? FieldKey<E> : keyof M) & keyof E> : M[keyof M] extends Off ? Pick<E, Exclude<FieldKey<E>, keyof M> & keyof E> : Pick<E, OnKeys<M> & keyof E> & MaybeFields<E, M>) & RelatedRows<E, Q> : WholeRow<E, Q> & RelatedRows<E, Q>;
435
439
  type Off = false | 0 | undefined;
436
440
  /** The keys of a clause's map whose entry asks for something. */
437
441
  type OnKeys<M> = {
@@ -446,7 +450,7 @@ type MaybeFields<E, M> = [MaybeKeys<M>] extends [never] ? unknown : Partial<Pick
446
450
  /** The entity, less the relations {@link RelatedRows} fills in, so none comes back as declared. */
447
451
  type WholeRow<E, Q> = Q extends {
448
452
  readonly $populate: infer M;
449
- } ? Omit<E, keyof M & keyof E> : E;
453
+ } ? Omit<E, keyof M & keyof E> & MethodMask<E> : DataRow<E>;
450
454
  /** The populated relations, and the `_count` a query asked for. */
451
455
  type RelatedRows<E, Q> = Q extends {
452
456
  readonly $populate: infer M;
@@ -10,7 +10,6 @@ export const COUNT_RESULT_KEY = '_count';
10
10
  export const QUERY_CLAUSES = {
11
11
  $select: { value: 'object', scope: 'relation' },
12
12
  $populate: { value: 'object', scope: 'relation' },
13
- $exclude: { value: 'object', scope: 'relation' },
14
13
  $where: { value: 'object', scope: 'relation' },
15
14
  $sort: { value: 'object', scope: 'relation' },
16
15
  $skip: { value: 'number', scope: 'relation' },
@@ -20,8 +19,8 @@ export const QUERY_CLAUSES = {
20
19
  $count: { value: 'object', scope: 'statement' },
21
20
  // A vector search ranks only the statement's rows, so a relation's own query has nothing for it to tune.
22
21
  $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' },
22
+ // Each request commits on its own, so a lock taken over HTTP would be released before its response.
23
+ $lock: { value: 'object', scope: 'statement', wire: false },
25
24
  // Statement only: keyset paging per parent of a populated relation is not supported.
26
25
  $after: { value: 'string', scope: 'statement' },
27
26
  $before: { value: 'string', scope: 'statement' },
@@ -1,4 +1,4 @@
1
- import type { FieldKey, FieldKeyOf, RelationKey, RelationTarget } from './entity.js';
1
+ import type { FieldKey, FieldKeyOf, IsUnion, RelationKey, RelationTarget } from './entity.js';
2
2
  import type { QueryPager, QuerySelect, QuerySortDirection } from './query.js';
3
3
  import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
4
4
  import type { ExactlyOne, IsMany } from './utility.js';
@@ -83,11 +83,14 @@ type CountingOp = OpsOf<'$count' | '$countDistinct'>;
83
83
  type ColumnTypedOp = SummingOp | OpsOf<'$min' | '$max'>;
84
84
  /**
85
85
  * A field a group key reads, by the path to it: `{ orderId: true }`, or through a to-one relation,
86
- * `{ transaction: { orderId: true } }`. A to-many is `never`, since joining one multiplies the rows.
86
+ * `{ transaction: { orderId: true } }`. A to-many is `never`, since joining one multiplies the rows. Every key
87
+ * is optional, which a literal checks against cheaply; {@link OnePath} says a captured one names a single field.
87
88
  */
88
- export type QueryGroupRef<E, K extends keyof E = FieldKey<E> | RelationKey<E>> = ExactlyOne<Required<{
89
- [P in K]: P extends RelationKey<E> ? IsMany<E[P]> extends true ? never : QueryGroupRef<RelationTarget<E[P]>> : true;
90
- }>>;
89
+ export type QueryGroupRef<E, K extends keyof E = FieldKey<E> | RelationKey<E>> = {
90
+ readonly [P in K]?: P extends RelationKey<E> ? IsMany<E[P]> extends true ? never : QueryGroupRef<RelationTarget<E[P]>> : true;
91
+ };
92
+ /** `unknown` where a path names one key at each step down to a `true`, `never` otherwise. */
93
+ type OnePath<R> = R extends object ? [keyof R] extends [never] ? never : true extends IsUnion<keyof R> ? never : R[keyof R] extends true ? unknown : OnePath<R[keyof R]> : never;
91
94
  /** The columns to group by: a field switched on, `{ status: true }`, or an alias for a field a path reads. */
92
95
  export type QueryGroupMap<E> = {
93
96
  readonly [key: string]: true | QueryGroupRef<E>;
@@ -162,7 +165,7 @@ type ClosedAggregateQuery<E, G, A> = {
162
165
  * an alias for a to-one relation's field by the path to it, `{ orderId: { transaction: { orderId: true } } }`.
163
166
  */
164
167
  readonly $group?: Readonly<QuerySelect<E, FieldKey<E>, true>> & {
165
- readonly [K in Exclude<keyof G, FieldKey<E>>]: QueryGroupRef<E>;
168
+ readonly [K in Exclude<keyof G, FieldKey<E>>]: QueryGroupRef<E> & OnePath<G[K]>;
166
169
  };
167
170
  /**
168
171
  * The computed columns by alias. An alias repeating a `$group` column is refused, since both would come back
@@ -172,17 +175,24 @@ type ClosedAggregateQuery<E, G, A> = {
172
175
  readonly [K in keyof A]: K extends keyof G ? never : QueryAggregateFn<E>;
173
176
  };
174
177
  /** Filtering after grouping, by a result column, each value typed as that column is. */
175
- readonly $having?: {
176
- readonly [K in keyof AggregateRow<E, G, A>]?: QueryWhereFieldValue<AggregateRow<E, G, A>[K]>;
177
- };
178
+ readonly $having?: HavingOf<AggregateRow<E, G, A>>;
178
179
  /**
179
180
  * Sort the aggregated results by a grouped column or a computed alias - an aggregate's rows are
180
181
  * its groups, so any other entity field names a value the statement never produced.
181
182
  */
182
- readonly $sort?: {
183
- readonly [K in keyof AggregateRow<E, G, A>]?: QuerySortDirection;
184
- };
183
+ readonly $sort?: SortOf<AggregateRow<E, G, A>>;
185
184
  } & QueryPager;
185
+ /**
186
+ * A `$having` over a row's columns, each value typed as its column is. Mapped over the row once it is resolved,
187
+ * which TypeScript does once, where mapping its key set reads each column back through the row.
188
+ */
189
+ type HavingOf<R> = {
190
+ readonly [K in keyof R]?: QueryWhereFieldValue<R[K]>;
191
+ };
192
+ /** A `$sort` over a row's columns, mapped as {@link HavingOf} is. */
193
+ type SortOf<R> = {
194
+ readonly [K in keyof R]?: QuerySortDirection;
195
+ };
186
196
  /** The `$group` and `$select` maps of a captured aggregate query, or none where it names none. */
187
197
  type AggregateGroup<Q> = Q extends {
188
198
  readonly $group?: infer G;
@@ -1,5 +1,5 @@
1
1
  import type { QueryContext, RelationAggregateSpec, SqlQueryDialect, TriggerRows } from './dialect.js';
2
- import type { Scalar, Type } from './utility.js';
2
+ import type { Scalar, AbstractType } from './utility.js';
3
3
  /** What a `sql` callback receives. See {@link QuerySqlFn}. */
4
4
  export type QuerySqlRenderOptions = {
5
5
  /** The dialect rendering the SQL. */
@@ -14,7 +14,7 @@ export type QuerySqlRenderOptions = {
14
14
  * The entity being rendered, which a ref read off a definition's map resolves its column against: a
15
15
  * computed field's own, or the one whose schema is built. Absent where a statement renders SQL.
16
16
  */
17
- entity?: Type<unknown>;
17
+ entity?: AbstractType<unknown>;
18
18
  /**
19
19
  * The rows a set-based trigger's writes read. Absent where the body reads `NEW` and `OLD` bare, and
20
20
  * outside a trigger.
@@ -35,6 +35,12 @@ export declare const RAW_ALIAS: unique symbol;
35
35
  export declare const SQL_TEXT: unique symbol;
36
36
  /** Keys the phantom a ref or an aggregate carries its value type in, which no value ever fills. */
37
37
  export declare const SQL_VALUE_TYPE: unique symbol;
38
+ /** The member a ref names. A symbol, as each of a ref's own keys is, so every string key is the data's. */
39
+ export declare const REF_KEY: unique symbol;
40
+ /** The dotted path a {@link JsonPathRef} reads down its column's document. */
41
+ export declare const JSON_PATH: unique symbol;
42
+ /** Keys the phantom a {@link JsonPathRef} carries the value at its path in. */
43
+ export declare const JSON_VALUE: unique symbol;
38
44
  /**
39
45
  * What a `sql` template interpolates: a value it binds, a list of them (`= ANY(${ids})`), or SQL it renders in
40
46
  * place. Never `undefined`, which would bind nothing: leave it out, or interpolate `null`.
@@ -57,19 +63,29 @@ export declare class QuerySql {
57
63
  });
58
64
  /** The same expression under an alias, for a `$select` projection. */
59
65
  as(alias: string): QuerySql;
60
- /** Writes the expression into `opts.ctx`. The alias is the projection's to write, after the term. */
61
- render(opts: QuerySqlRenderOptions): void;
62
66
  }
67
+ /** Writes `statement` into `opts.ctx`. The alias is the projection's to write, after the term. */
68
+ export declare function renderSql(statement: QuerySql, opts: QuerySqlRenderOptions): void;
63
69
  /**
64
70
  * A field of an entity as SQL, read off `refs(Entity)` or a definition's refs: interpolated into `sql`, it
65
- * renders as the field's column. Its `key` is how an index tells a column from an expression, and `V`,
71
+ * renders as the field's column. Its key is how an index tells a column from an expression, and `V`,
66
72
  * the field's type, is what a value slot checks it against: see {@link SqlFor}.
67
73
  */
68
74
  export declare class ColumnRef<K extends string = string, V = unknown> extends QuerySql {
69
- readonly key: K;
70
75
  readonly [SQL_VALUE_TYPE]?: V;
76
+ readonly [REF_KEY]: K;
71
77
  constructor(key: K, value: QuerySqlFn);
72
78
  }
79
+ /**
80
+ * A path inside a JSON column, read off an index's refs as the `$where` key it is: `user.settings.theme`
81
+ * for `'settings.theme'`. `V`, the value at the path, decides how the index has to read it.
82
+ */
83
+ export declare class JsonPathRef<V = unknown> {
84
+ readonly [JSON_VALUE]?: V;
85
+ readonly [REF_KEY]: string;
86
+ readonly [JSON_PATH]: string;
87
+ constructor(key: string, path: string);
88
+ }
73
89
  /**
74
90
  * SQL where a value of type `V` goes: bare SQL, whose type is its author's to know, or a ref to a column
75
91
  * holding one, nullability aside. `Sql` is what the transport carries, so the wire's `never` stays one.
@@ -3,6 +3,12 @@ export const RAW_ALIAS = Symbol('rawAlias');
3
3
  export const SQL_TEXT = Symbol('sqlText');
4
4
  /** Keys the phantom a ref or an aggregate carries its value type in, which no value ever fills. */
5
5
  export const SQL_VALUE_TYPE = Symbol('sqlValueType');
6
+ /** The member a ref names. A symbol, as each of a ref's own keys is, so every string key is the data's. */
7
+ export const REF_KEY = Symbol('refKey');
8
+ /** The dotted path a {@link JsonPathRef} reads down its column's document. */
9
+ export const JSON_PATH = Symbol('jsonPath');
10
+ /** Keys the phantom a {@link JsonPathRef} carries the value at its path in. */
11
+ export const JSON_VALUE = Symbol('jsonValue');
6
12
  export class QuerySql {
7
13
  [SQL_FN];
8
14
  [RAW_ALIAS];
@@ -21,24 +27,36 @@ export class QuerySql {
21
27
  as(alias) {
22
28
  return new QuerySql(this[SQL_FN], { alias, text: this[SQL_TEXT] });
23
29
  }
24
- /** Writes the expression into `opts.ctx`. The alias is the projection's to write, after the term. */
25
- render(opts) {
26
- const emitted = this[SQL_FN](opts);
27
- if (typeof emitted === 'string' || (typeof emitted === 'number' && !Number.isNaN(emitted))) {
28
- opts.ctx.append(String(emitted));
29
- }
30
+ }
31
+ /** Writes `statement` into `opts.ctx`. The alias is the projection's to write, after the term. */
32
+ export function renderSql(statement, opts) {
33
+ const emitted = statement[SQL_FN](opts);
34
+ if (typeof emitted === 'string' || (typeof emitted === 'number' && !Number.isNaN(emitted))) {
35
+ opts.ctx.append(String(emitted));
30
36
  }
31
37
  }
32
38
  /**
33
39
  * A field of an entity as SQL, read off `refs(Entity)` or a definition's refs: interpolated into `sql`, it
34
- * renders as the field's column. Its `key` is how an index tells a column from an expression, and `V`,
40
+ * renders as the field's column. Its key is how an index tells a column from an expression, and `V`,
35
41
  * the field's type, is what a value slot checks it against: see {@link SqlFor}.
36
42
  */
37
43
  export class ColumnRef extends QuerySql {
38
- key;
44
+ [REF_KEY];
39
45
  constructor(key, value) {
40
46
  super(value);
41
- this.key = key;
47
+ this[REF_KEY] = key;
48
+ }
49
+ }
50
+ /**
51
+ * A path inside a JSON column, read off an index's refs as the `$where` key it is: `user.settings.theme`
52
+ * for `'settings.theme'`. `V`, the value at the path, decides how the index has to read it.
53
+ */
54
+ export class JsonPathRef {
55
+ [REF_KEY];
56
+ [JSON_PATH];
57
+ constructor(key, path) {
58
+ this[REF_KEY] = key;
59
+ this[JSON_PATH] = path;
42
60
  }
43
61
  }
44
62
  /**