uql-orm 0.104.1 → 0.105.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.
- package/README.md +24 -10
- package/dist/browser/uql-browser.min.js +2 -2
- package/dist/browser/uql-browser.min.js.map +7 -7
- package/dist/dialect/abstractSqlDialect.d.ts +6 -4
- package/dist/dialect/abstractSqlDialect.js +35 -32
- package/dist/dialect/aliases.d.ts +2 -0
- package/dist/dialect/aliases.js +2 -0
- package/dist/dialect/jsonSql.js +2 -2
- package/dist/dialect/mysqlLikeSqlDialect.d.ts +1 -1
- package/dist/dialect/mysqlLikeSqlDialect.js +1 -1
- package/dist/dialect/operators.js +2 -4
- package/dist/dialect/queryJoins.d.ts +2 -0
- package/dist/dialect/vectorSqlDialect.d.ts +1 -1
- package/dist/dialect/vectorSqlDialect.js +1 -1
- package/dist/entity/column.d.ts +3 -0
- package/dist/entity/column.js +3 -0
- package/dist/entity/columnOptionsBuilder.d.ts +54 -0
- package/dist/entity/columnOptionsBuilder.js +108 -0
- package/dist/entity/decorator/bag.d.ts +4 -4
- package/dist/entity/decorator/entity.d.ts +2 -19
- package/dist/entity/decorator/entity.js +3 -37
- package/dist/entity/decorator/members.d.ts +46 -76
- package/dist/entity/decorator/members.js +18 -7
- package/dist/entity/index.d.ts +2 -1
- package/dist/entity/index.js +2 -1
- package/dist/entity/metadata/definition.d.ts +10 -24
- package/dist/entity/metadata/definition.js +329 -147
- package/dist/entity/metadata/schemaFixture/animal.d.ts +54 -0
- package/dist/entity/metadata/schemaFixture/animal.js +7 -0
- package/dist/entity/metadata/schemaFixture/author.d.ts +140 -0
- package/dist/entity/metadata/schemaFixture/author.js +25 -0
- package/dist/entity/metadata/schemaFixture/book.d.ts +192 -0
- package/dist/entity/metadata/schemaFixture/book.js +22 -0
- package/dist/http/query.js +12 -13
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -1
- package/dist/mariadb/mariaDialect.js +1 -1
- package/dist/mariadb/mariadbQuerier.js +1 -3
- package/dist/migrate/builder/columnBuilder.d.ts +20 -68
- package/dist/migrate/builder/columnBuilder.js +104 -110
- package/dist/migrate/builder/migrationBuilder.d.ts +3 -3
- package/dist/migrate/builder/migrationBuilder.js +7 -6
- package/dist/migrate/builder/tableBuilder.d.ts +3 -55
- package/dist/migrate/builder/tableBuilder.js +88 -204
- package/dist/migrate/builder/types.d.ts +52 -151
- package/dist/migrate/builder/types.js +0 -6
- package/dist/migrate/codegen/entityCodeGenerator.d.ts +2 -2
- package/dist/migrate/codegen/entityCodeGenerator.js +24 -24
- package/dist/migrate/codegen/fieldOptionsSource.d.ts +3 -1
- package/dist/migrate/codegen/fieldOptionsSource.js +35 -34
- package/dist/migrate/codegen/indexEntrySource.d.ts +16 -0
- package/dist/migrate/codegen/{indexDecoratorSource.js → indexEntrySource.js} +54 -27
- package/dist/migrate/ddl/defaultSql.js +7 -6
- package/dist/migrate/ddl/indexCapabilities.d.ts +8 -7
- package/dist/migrate/ddl/indexCapabilities.js +26 -13
- package/dist/migrate/ddl/indexDdl.d.ts +13 -13
- package/dist/migrate/ddl/indexDdl.js +33 -30
- package/dist/migrate/ddl/mysqlIndexDdl.d.ts +6 -11
- package/dist/migrate/ddl/mysqlIndexDdl.js +17 -28
- package/dist/migrate/ddl/pgIndexDdl.d.ts +2 -2
- package/dist/migrate/ddl/sqliteIndexDdl.d.ts +2 -2
- package/dist/migrate/drift/driftDetector.js +2 -2
- package/dist/migrate/generator/definitionToNode.d.ts +8 -2
- package/dist/migrate/generator/definitionToNode.js +4 -5
- package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +11 -2
- package/dist/migrate/introspection/jsonIndexEntry.d.ts +6 -0
- package/dist/migrate/introspection/jsonIndexEntry.js +120 -0
- package/dist/migrate/introspection/mysqlIntrospector.d.ts +4 -4
- package/dist/migrate/introspection/mysqlIntrospector.js +25 -21
- package/dist/migrate/introspection/postgresIntrospector.d.ts +1 -1
- package/dist/migrate/introspection/postgresIntrospector.js +3 -4
- package/dist/migrate/introspection/sqliteIntrospector.js +24 -9
- package/dist/migrate/introspection/tableSchemaAST.js +5 -1
- package/dist/migrate/schemaChange.d.ts +3 -3
- package/dist/migrate/schemaChange.js +3 -2
- package/dist/migrate/schemaGenerator.js +1 -1
- package/dist/migrate/storage/databaseStorage.js +4 -4
- package/dist/mongodb/mongoDialect.d.ts +33 -36
- package/dist/mongodb/mongoDialect.js +118 -32
- package/dist/mongodb/mongoIntrospector.d.ts +3 -1
- package/dist/mongodb/mongoIntrospector.js +11 -5
- package/dist/mongodb/mongoSchemaGenerator.js +35 -27
- package/dist/mongodb/mongodbQuerier.d.ts +1 -11
- package/dist/mongodb/mongodbQuerier.js +9 -43
- package/dist/querier/abstractQuerier.d.ts +0 -1
- package/dist/querier/abstractQuerier.js +1 -20
- package/dist/querier/keyset.js +3 -3
- package/dist/schema/declaredColumn.d.ts +11 -0
- package/dist/schema/declaredColumn.js +21 -0
- package/dist/schema/indexColumns.d.ts +0 -3
- package/dist/schema/indexColumns.js +11 -7
- package/dist/schema/indexDifferences.d.ts +10 -5
- package/dist/schema/indexDifferences.js +42 -28
- package/dist/schema/schemaASTBuilder.js +28 -36
- package/dist/schema/schemaASTDiffer.js +8 -4
- package/dist/schema/sqlExpression.d.ts +21 -17
- package/dist/schema/sqlExpression.js +11 -23
- package/dist/type/column.d.ts +328 -0
- package/dist/type/column.js +2 -0
- package/dist/type/config.d.ts +1 -1
- package/dist/type/dialect.d.ts +2 -1
- package/dist/type/dialect.js +1 -0
- package/dist/type/entity.d.ts +290 -279
- package/dist/type/entity.js +6 -1
- package/dist/type/index.d.ts +2 -0
- package/dist/type/index.js +2 -0
- package/dist/type/migration.d.ts +5 -5
- package/dist/type/query.d.ts +44 -40
- package/dist/type/query.js +2 -3
- package/dist/type/queryAggregate.d.ts +22 -12
- package/dist/type/querySql.d.ts +20 -4
- package/dist/type/querySql.js +27 -9
- package/dist/type/schemaEntity.d.ts +190 -0
- package/dist/type/schemaEntity.js +1 -0
- package/dist/type/utility.d.ts +0 -6
- package/dist/type/vector.d.ts +1 -1
- package/dist/util/ddlExpression.util.d.ts +12 -13
- package/dist/util/ddlExpression.util.js +12 -21
- package/dist/util/dialect.util.d.ts +11 -5
- package/dist/util/dialect.util.js +31 -37
- package/dist/util/field.util.d.ts +10 -9
- package/dist/util/field.util.js +14 -10
- package/dist/util/fieldOption.util.d.ts +11 -95
- package/dist/util/fieldOption.util.js +49 -16
- package/dist/util/hook.util.d.ts +2 -14
- package/dist/util/hook.util.js +3 -16
- package/dist/util/index.d.ts +1 -0
- package/dist/util/index.js +1 -0
- package/dist/util/indexEntry.util.d.ts +45 -0
- package/dist/util/indexEntry.util.js +138 -0
- package/dist/util/relationQuery.util.d.ts +0 -1
- package/dist/util/relationQuery.util.js +0 -5
- package/dist/util/sql.d.ts +10 -7
- package/dist/util/sql.js +34 -16
- package/dist/util/sql.util.d.ts +4 -5
- package/dist/util/sql.util.js +7 -16
- package/dist/util/string.util.d.ts +2 -0
- package/dist/util/string.util.js +4 -0
- package/dist/util/uqlError.d.ts +1 -1
- package/dist/util/uqlError.js +1 -1
- package/package.json +1 -1
- package/skills/uql-orm/SKILL.md +76 -25
- package/dist/migrate/codegen/indexDecoratorSource.d.ts +0 -16
package/dist/type/entity.js
CHANGED
|
@@ -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
|
|
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');
|
package/dist/type/index.d.ts
CHANGED
|
@@ -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';
|
package/dist/type/index.js
CHANGED
|
@@ -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';
|
package/dist/type/migration.d.ts
CHANGED
|
@@ -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,
|
|
5
|
+
import type { Except, IndexEntry, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, Type, 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
|
*/
|
|
@@ -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.
|
|
132
|
-
* it reads like
|
|
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
|
|
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 -
|
|
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: {
|
package/dist/type/query.d.ts
CHANGED
|
@@ -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 })`
|
|
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
|
|
227
|
-
* (``[sql`LOG10(points)`.as('score')]``, SQL dialects only - MongoDB rejects the raw-array form).
|
|
228
|
-
*
|
|
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 `
|
|
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' | '$
|
|
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
|
|
405
|
-
*
|
|
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 = {}
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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;
|
package/dist/type/query.js
CHANGED
|
@@ -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
|
-
//
|
|
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>> =
|
|
89
|
-
[P in K]
|
|
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;
|
package/dist/type/querySql.d.ts
CHANGED
|
@@ -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
|
|
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.
|
package/dist/type/querySql.js
CHANGED
|
@@ -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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
|
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
|
-
|
|
44
|
+
[REF_KEY];
|
|
39
45
|
constructor(key, value) {
|
|
40
46
|
super(value);
|
|
41
|
-
this
|
|
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
|
/**
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
import type { ForeignKeyAction } from '../schema/types.js';
|
|
2
|
+
import type { Column, ColumnOptionsOf, ColumnValueOf, FilledOptions, NullOf } from './column.js';
|
|
3
|
+
import type { CheckSection, FilterSection, filledKey, HookContext, HookEvent, idKey, IdValue, IndexSection, IsUnion, RefMap, RelationCardinality, RelationInverseOptions, RelationJoinOptions, RelationOwnerOptions, RelationRef, ToManyRefs, ToManyRelationKey, TriggerSection, versionKey } from './entity.js';
|
|
4
|
+
import type { QuerySql, RelationAggregate } from './querySql.js';
|
|
5
|
+
import type { Type } from './utility.js';
|
|
6
|
+
/**
|
|
7
|
+
* A schema entity's columns, each an `f` builder. A foreign key is declared in `.references()`, once every entity
|
|
8
|
+
* exists: one written here would read its target while that target's own type is still being inferred. A computed
|
|
9
|
+
* column is declared in `.computed()`, where its row is read-only.
|
|
10
|
+
*/
|
|
11
|
+
export type SchemaFields = {
|
|
12
|
+
readonly [key: string]: Column<{
|
|
13
|
+
readonly references?: undefined;
|
|
14
|
+
readonly computed?: undefined;
|
|
15
|
+
} & {
|
|
16
|
+
readonly [key: string]: unknown;
|
|
17
|
+
}>;
|
|
18
|
+
};
|
|
19
|
+
/** The key a class holds: carried beside a schema's, so a cycle never reads its row; read off a decorated one's. */
|
|
20
|
+
export type ReferencedKey<C> = C extends {
|
|
21
|
+
readonly [schemaShape]?: {
|
|
22
|
+
readonly key: infer K;
|
|
23
|
+
};
|
|
24
|
+
} ? unknown extends K ? RowKey<C> : K : RowKey<C>;
|
|
25
|
+
type RowKey<C> = C extends Type<infer R> ? NonNullable<IdValue<R>> : never;
|
|
26
|
+
/** The keys of `F` whose column is a `C`. */
|
|
27
|
+
type FlagKeys<F, C> = {
|
|
28
|
+
[K in keyof F]-?: F[K] extends C ? K : never;
|
|
29
|
+
}[keyof F];
|
|
30
|
+
/**
|
|
31
|
+
* The columns as a row reads them, mapped over parameters constrained to `keyof F` so each key stays linked to
|
|
32
|
+
* its declaration for a rename. A nullable column may be absent on insert and reads `null`.
|
|
33
|
+
*/
|
|
34
|
+
export type ColumnRow<F, Nullable extends keyof F = FlagKeys<F, Column<{
|
|
35
|
+
readonly nullable: true;
|
|
36
|
+
}>>, Present extends keyof F = Exclude<keyof F, Nullable>> = {
|
|
37
|
+
-readonly [K in Present]-?: ColumnValueOf<F[K]>;
|
|
38
|
+
} & {
|
|
39
|
+
-readonly [K in Nullable]?: ColumnValueOf<F[K]> | null;
|
|
40
|
+
};
|
|
41
|
+
/** The computed columns as a row reads them, never written. */
|
|
42
|
+
type ComputedRow<C> = {
|
|
43
|
+
readonly [K in keyof C]?: ColumnValueOf<C[K]> | NullOf<ColumnOptionsOf<C[K]>>;
|
|
44
|
+
};
|
|
45
|
+
/** What `.computed()` returns: columns the database computes, `f.string().as(sql`...`)`. */
|
|
46
|
+
type SchemaComputed = {
|
|
47
|
+
readonly [key: string]: Column<{
|
|
48
|
+
readonly computed: QuerySql;
|
|
49
|
+
}>;
|
|
50
|
+
};
|
|
51
|
+
/** A relation as a schema declares it: what `rel.*` returns, its target carried for the row. */
|
|
52
|
+
export type SchemaRelation<T = object, C extends RelationCardinality = RelationCardinality, Columns = T> = {
|
|
53
|
+
readonly target: Type<T>;
|
|
54
|
+
readonly cardinality: C;
|
|
55
|
+
/** Checked by the builder's signature, so held erased: the registry reads them back as any relation's options. */
|
|
56
|
+
readonly options?: object;
|
|
57
|
+
/** The target's columns, which an aggregate over the relation reads. */
|
|
58
|
+
readonly columns?: Columns;
|
|
59
|
+
};
|
|
60
|
+
/** Each to-many relation as an aggregate reads it, typed by its target's columns, read lazily as the relations are. */
|
|
61
|
+
type AggregateRefs<R> = {
|
|
62
|
+
readonly [K in keyof R]: R[K] extends () => {
|
|
63
|
+
readonly cardinality: '1m' | 'mm';
|
|
64
|
+
readonly columns?: infer Columns;
|
|
65
|
+
} ? RelationRef<Columns> : never;
|
|
66
|
+
};
|
|
67
|
+
/** The aggregates as a row reads them, each a computed column typed by the value it reads, never written. */
|
|
68
|
+
export type AggregateRow<A> = {
|
|
69
|
+
readonly [K in keyof A]?: A[K] extends () => RelationAggregate<infer V> ? V : never;
|
|
70
|
+
};
|
|
71
|
+
type RelationValue<P> = P extends () => SchemaRelation<infer T, infer C, unknown> ? C extends '1m' | 'mm' ? T[] : T : never;
|
|
72
|
+
/** The relations as a row reads them; exported, as a schema's emitted declaration names it. */
|
|
73
|
+
export type RelationRow<R> = {
|
|
74
|
+
-readonly [K in keyof R]?: RelationValue<R[K]>;
|
|
75
|
+
};
|
|
76
|
+
/** The brands the type level reads keys off, derived from the columns rather than written by hand. */
|
|
77
|
+
export type Brands<F> = {
|
|
78
|
+
readonly [idKey]?: FlagKeys<F, Column<{
|
|
79
|
+
readonly isId: true;
|
|
80
|
+
}>>;
|
|
81
|
+
readonly [versionKey]?: FlagKeys<F, Column<{
|
|
82
|
+
readonly version: true;
|
|
83
|
+
}>>;
|
|
84
|
+
readonly [filledKey]?: Exclude<FlagKeys<F, Column<FilledOptions>>, FlagKeys<F, Column<{
|
|
85
|
+
readonly isId: true;
|
|
86
|
+
}>>>;
|
|
87
|
+
};
|
|
88
|
+
/** The relation constructors a schema's `relations` receives, typed by the columns of the entity declaring them. */
|
|
89
|
+
export type RelationBuilder<O> = {
|
|
90
|
+
oneToOne<T extends object, K = IdValue<T>, Columns = T>(target: Type<T> & SchemaShape<K, Columns>, opts: RelationOwnerOptions<T, O, SchemaJoins<T, O, K, Columns>> | RelationInverseOptions<T, SchemaJoins<T, O, K, Columns>>): SchemaRelation<T, '11'>;
|
|
91
|
+
manyToOne<T extends object, K = IdValue<T>, Columns = T>(target: Type<T> & SchemaShape<K, Columns>, opts: RelationOwnerOptions<T, O, SchemaJoins<T, O, K, Columns>>): SchemaRelation<T, 'm1'>;
|
|
92
|
+
/** With no options, it is mapped by the one many-to-one of its target pointing back. */
|
|
93
|
+
oneToMany<T extends object, Columns = T>(target: Type<T> & SchemaShape<unknown, Columns>, opts?: RelationInverseOptions<T, SchemaJoins<T, O, unknown, Columns>> | RelationJoinOptions<T, O, SchemaJoins<T, O, unknown, Columns>>): SchemaRelation<T, '1m', Columns>;
|
|
94
|
+
manyToMany<T extends object, Columns = T>(target: Type<T> & SchemaShape<unknown, Columns>, opts: RelationInverseOptions<T, SchemaJoins<T, O, unknown, Columns>> | RelationJoinOptions<T, O, SchemaJoins<T, O, unknown, Columns>>): SchemaRelation<T, 'mm', Columns>;
|
|
95
|
+
};
|
|
96
|
+
/**
|
|
97
|
+
* A schema's joins: a foreign key and paired columns checked by type, off the target's carried key and columns;
|
|
98
|
+
* `mappedBy` by key alone, its kind checked on first read.
|
|
99
|
+
*/
|
|
100
|
+
type SchemaJoins<T, O, K = unknown, Columns = T> = {
|
|
101
|
+
readonly key: KeyHolding<O, K>;
|
|
102
|
+
readonly pairs: readonly SchemaJoinPair<O, Columns>[];
|
|
103
|
+
readonly mappedBy: keyof T;
|
|
104
|
+
};
|
|
105
|
+
/** One pair of join columns, the local one holding what the target's column does. */
|
|
106
|
+
type SchemaJoinPair<O, Columns> = {
|
|
107
|
+
readonly [F in keyof Columns]-?: {
|
|
108
|
+
readonly local: KeyHolding<O, NonNullable<Columns[F]>>;
|
|
109
|
+
readonly foreign: F;
|
|
110
|
+
};
|
|
111
|
+
}[keyof Columns];
|
|
112
|
+
/** What the first call of a schema states: the class, its table and its columns. */
|
|
113
|
+
export type SchemaEntityOptions<F extends SchemaFields, B = object, BK = unknown, BC = unknown> = {
|
|
114
|
+
/** The class's name, which a naming strategy derives the table's from, as it does a decorated class's. */
|
|
115
|
+
readonly name: string;
|
|
116
|
+
/** The table, exactly as the database names it, where it is not derived from `name`. */
|
|
117
|
+
readonly table?: string;
|
|
118
|
+
/** The schema (a MySQL database) the table lives in; unset follows the pool's. */
|
|
119
|
+
readonly schema?: string;
|
|
120
|
+
/** A base that is never a table: the entities extending it take what it declares. */
|
|
121
|
+
readonly abstract?: true;
|
|
122
|
+
/** The entity it inherits from, which the declared class extends, so its methods and `super` work. */
|
|
123
|
+
readonly extends?: SchemaClass<B, BK, BC>;
|
|
124
|
+
readonly fields: F;
|
|
125
|
+
};
|
|
126
|
+
/** A hook a schema runs on a row; a promise it returns is awaited. */
|
|
127
|
+
type SchemaHook<Row> = (row: Row, ctx: HookContext) => unknown;
|
|
128
|
+
/**
|
|
129
|
+
* Each foreign key column's target, `{ authorId: () => Author }`, or with its delete action. The getter is typed as
|
|
130
|
+
* returning nothing: typing its target would read an entity referencing itself while it is inferred, so the key's
|
|
131
|
+
* kind is checked on first read.
|
|
132
|
+
*/
|
|
133
|
+
type SchemaReferences<Columns> = {
|
|
134
|
+
readonly [K in keyof Columns]?: LazyTarget | {
|
|
135
|
+
readonly entity: LazyTarget;
|
|
136
|
+
readonly onDelete?: ForeignKeyAction;
|
|
137
|
+
};
|
|
138
|
+
};
|
|
139
|
+
/** The entity a foreign key points at, read once every entity exists. */
|
|
140
|
+
type LazyTarget = () => void;
|
|
141
|
+
/**
|
|
142
|
+
* What a schema declares after its columns, each section typed by the columns now fixed, so none is inferred
|
|
143
|
+
* again. `relations` comes last: what follows a relation would read its target while that target is inferred.
|
|
144
|
+
*/
|
|
145
|
+
type SchemaSections<Row, Key, Columns, B> = {
|
|
146
|
+
/** Columns the database computes off the stored ones, `(post) => ({ slug: f.string().as(sql`...`) })`. */
|
|
147
|
+
computed<const C extends SchemaComputed>(computed: (refs: RefMap<Columns>) => C): SchemaEntity<Row & ComputedRow<C>, Key, Columns & ComputedRow<C>, B>;
|
|
148
|
+
indexes(indexes: IndexSection<Columns>): SchemaEntity<Row, Key, Columns, B>;
|
|
149
|
+
checks(checks: CheckSection<Columns>): SchemaEntity<Row, Key, Columns, B>;
|
|
150
|
+
triggers(triggers: TriggerSection<Columns>): SchemaEntity<Row, Key, Columns, B>;
|
|
151
|
+
filters(filters: FilterSection<Row>): SchemaEntity<Row, Key, Columns, B>;
|
|
152
|
+
/** Functions each lifecycle event runs on the row, in order, given the querier writing it. */
|
|
153
|
+
hooks(hooks: {
|
|
154
|
+
readonly [E in HookEvent]?: readonly SchemaHook<Row>[];
|
|
155
|
+
}): SchemaEntity<Row, Key, Columns, B>;
|
|
156
|
+
/** The foreign keys no relation joins on, each column's target: `{ authorId: () => Author }`. */
|
|
157
|
+
references(references: SchemaReferences<Columns>): SchemaEntity<Row, Key, Columns, B>;
|
|
158
|
+
/**
|
|
159
|
+
* The relations, each read lazily so entities pointing at each other declare in either order, and the values
|
|
160
|
+
* read over the to-many ones, its base's too: `(agg) => ({ postCount: () => agg.posts.count() })`.
|
|
161
|
+
*/
|
|
162
|
+
relations<const R, const A = {}>(relations: (rel: RelationBuilder<Columns>) => R, aggregates?: (agg: AggregateRefs<R> & ToManyRefs<B, Exclude<ToManyRelationKey<B>, keyof R>>) => A): SchemaClass<Row & RelationRow<R> & AggregateRow<A>, Key, Columns>;
|
|
163
|
+
};
|
|
164
|
+
/** A schema entity's class while its sections may still be declared. */
|
|
165
|
+
export type SchemaEntity<Row, Key, Columns, B> = SchemaClass<Row, Key, Columns> & SchemaSections<Row, Key, Columns, B>;
|
|
166
|
+
/** The class a schema declares, to use as it is or to extend with behaviour. */
|
|
167
|
+
export type SchemaClass<Row, Key = unknown, Columns = unknown> = (new () => Row) & SchemaShape<Key, Columns>;
|
|
168
|
+
declare const schemaShape: unique symbol;
|
|
169
|
+
/**
|
|
170
|
+
* What a relation or an aggregate pointing at a schema reads of it, its key's type and its columns, carried beside
|
|
171
|
+
* its class rather than read off its row: the columns alone settle both while the row is still being inferred.
|
|
172
|
+
*/
|
|
173
|
+
type SchemaShape<Key, Columns = unknown> = {
|
|
174
|
+
readonly [schemaShape]?: {
|
|
175
|
+
readonly key: Key;
|
|
176
|
+
readonly columns: Columns;
|
|
177
|
+
};
|
|
178
|
+
};
|
|
179
|
+
/**
|
|
180
|
+
* The key's type: its own column's, else the base's it inherits, `never` for a composite, which no one column can
|
|
181
|
+
* reference, and anything for a schema built from data, whose columns are known only at run time.
|
|
182
|
+
*/
|
|
183
|
+
export type SchemaKey<F, Inherited = unknown> = string extends keyof F ? unknown : FlagKeys<F, Column<{
|
|
184
|
+
readonly isId: true;
|
|
185
|
+
}>> extends infer K extends keyof F ? [K] extends [never] ? Inherited : true extends IsUnion<K> ? never : ColumnValueOf<F[K]> : never;
|
|
186
|
+
/** The columns of `O` holding a `V`: a foreign key to a key of that type. */
|
|
187
|
+
type KeyHolding<O, V> = {
|
|
188
|
+
[K in keyof O]-?: NonNullable<O[K]> extends V ? K : never;
|
|
189
|
+
}[keyof O];
|
|
190
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|