uql-orm 0.100.2 → 0.101.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 (50) hide show
  1. package/README.md +8 -70
  2. package/dist/bunSql/bunSqlQuerierPool.js +3 -1
  3. package/dist/dialect/abstractSqlDialect.d.ts +35 -23
  4. package/dist/dialect/abstractSqlDialect.js +90 -72
  5. package/dist/dialect/hydrateColumn.d.ts +4 -5
  6. package/dist/dialect/hydrateColumn.js +2 -8
  7. package/dist/dialect/mysqlLikeSqlDialect.d.ts +4 -4
  8. package/dist/dialect/mysqlLikeSqlDialect.js +7 -6
  9. package/dist/dialect/pgLikeSqlDialect.d.ts +8 -2
  10. package/dist/dialect/pgLikeSqlDialect.js +11 -3
  11. package/dist/entity/metadata/definition.js +1 -1
  12. package/dist/http/fetchHandler.d.ts +1 -1
  13. package/dist/http/fetchHandler.js +1 -1
  14. package/dist/index.d.ts +2 -1
  15. package/dist/index.js +1 -1
  16. package/dist/mariadb/mariaDialect.d.ts +2 -2
  17. package/dist/mariadb/mariaDialect.js +1 -0
  18. package/dist/migrate/cli-config.d.ts +4 -7
  19. package/dist/migrate/cli-config.js +11 -9
  20. package/dist/mongodb/mongoDialect.js +11 -9
  21. package/dist/mssql/mssqlDialect.d.ts +2 -2
  22. package/dist/mssql/mssqlDialect.js +1 -0
  23. package/dist/pglite/pgliteQuerierPool.js +6 -12
  24. package/dist/postgres/abstractPgQuerierPool.d.ts +0 -1
  25. package/dist/postgres/abstractPgQuerierPool.js +0 -3
  26. package/dist/postgres/pgQuerier.d.ts +6 -0
  27. package/dist/postgres/pgQuerier.js +10 -0
  28. package/dist/postgres/pgWireTypes.d.ts +11 -7
  29. package/dist/postgres/pgWireTypes.js +47 -11
  30. package/dist/querier/abstractPoolQuerier.d.ts +2 -0
  31. package/dist/querier/abstractPoolQuerier.js +5 -1
  32. package/dist/querier/abstractQuerier.d.ts +5 -5
  33. package/dist/querier/abstractQuerier.js +59 -53
  34. package/dist/querier/abstractSqlQuerier.d.ts +3 -13
  35. package/dist/querier/abstractSqlQuerier.js +24 -84
  36. package/dist/querier/rowReader.d.ts +8 -0
  37. package/dist/querier/rowReader.js +88 -0
  38. package/dist/sqlite/sqliteDialect.d.ts +2 -2
  39. package/dist/sqlite/sqliteDialect.js +2 -1
  40. package/dist/util/dialect.util.d.ts +2 -11
  41. package/dist/util/dialect.util.js +8 -21
  42. package/dist/util/query.util.js +16 -8
  43. package/dist/util/relationQuery.util.d.ts +21 -12
  44. package/dist/util/relationQuery.util.js +30 -14
  45. package/dist/util/sql.util.d.ts +0 -5
  46. package/dist/util/sql.util.js +0 -33
  47. package/dist/util/wideNumber.d.ts +4 -3
  48. package/dist/util/wideNumber.js +17 -6
  49. package/package.json +3 -4
  50. package/skills/uql-orm/SKILL.md +4 -2
package/README.md CHANGED
@@ -9,7 +9,7 @@
9
9
 
10
10
  <h3>JSON-native ORM for TypeScript</h3>
11
11
 
12
- <p align="left">UQL queries SQL databases and MongoDB with plain, type-safe JSON-syntax.
12
+ <p align="left">UQL hanldes SQL databases and MongoDB with plain & type-safe JSON-syntax.
13
13
  </p>
14
14
 
15
15
  <p>
@@ -97,13 +97,12 @@ export default { pool, entities: [User, Post] } satisfies Config;
97
97
  ```
98
98
 
99
99
  ```sh
100
+ npm i -D tsx # Node only: the CLI loads uql.config.ts through it
100
101
  npx uql-migrate generate:entities initial # diffs the entities against the database into a migration you review
101
102
  npx uql-migrate up # applies it
102
103
  ```
103
104
 
104
- On Node, `npm i -D tsx`: Node's type stripping does not run decorators, and the CLI imports a TypeScript config through the project's `tsx`. Bun needs nothing.
105
-
106
- ### 3. Query on the server
105
+ ### 3. Query
107
106
 
108
107
  ```ts
109
108
  import { Post } from './entities.js';
@@ -123,82 +122,21 @@ const posts = await pool.findMany(Post, {
123
122
 
124
123
  The result is typed to what the query selected: `posts[0].author?.email` compiles, `posts[0].likes` does not.
125
124
 
126
- ### 4. Or serve it over HTTP, scoped to the signed-in user
127
-
128
- ```ts
129
- // server.ts: Bun, Deno, Cloudflare Workers, or any framework that takes a fetch handler
130
- import { defineFilter } from 'uql-orm';
131
- import { createFetchHandler } from 'uql-orm/http';
132
- import { authenticate } from './auth.js';
133
- import { Post } from './entities.js';
134
- import { pool } from './uql.config.js';
135
-
136
- declare module 'uql-orm' {
137
- interface UqlContext {
138
- userId?: number;
139
- }
140
- }
141
-
142
- // Scopes every read and write on Post: no `$where` widens it, a new post gets `authorId`, and with no user it throws.
143
- defineFilter(Post, 'ownPosts', {
144
- where: (ctx) => (ctx?.userId != null ? { authorId: ctx.userId } : undefined),
145
- security: true,
146
- });
147
-
148
- export default {
149
- fetch: createFetchHandler({
150
- pool,
151
- include: [Post],
152
- // From your verified session, never from client input.
153
- getContext: async (request) => ({ userId: (await authenticate(request)).userId }),
154
- }),
155
- };
156
- ```
157
-
158
- The client sends a query as JSON and gets the same typed result, never touching the database:
159
-
160
- ```ts
161
- // client.ts
162
- import { HttpQuerier } from 'uql-orm/browser';
163
- import { Post } from './entities.js';
164
-
165
- const api = new HttpQuerier('https://api.example.com');
166
-
167
- const { data: posts } = await api.findMany(Post, {
168
- $select: { title: true },
169
- $where: { likes: { $gte: 10 } },
170
- $sort: { likes: 'desc' },
171
- $limit: 10,
172
- });
173
- ```
174
-
175
- Only the entities in `include` are served: a `$populate: { author: true }` here is a `400`, as `User` is not. More in [HTTP](https://uql-orm.dev/http) and [multi-tenancy](https://uql-orm.dev/multi-tenancy).
176
-
177
- ### When CRUD is not enough
178
-
179
- - [`raw()`](https://uql-orm.dev/querying/raw-sql) fits anywhere a value or a field goes, and a migration can be plain SQL.
180
- - [Computed fields](https://uql-orm.dev/entities/computed-fields) are SQL expressions that you can filter and sort on. [Triggers](https://uql-orm.dev/entities/triggers) run inside the database.
181
- - [Transactions](https://uql-orm.dev/querying/transactions) hold one connection across many operations, and [lifecycle hooks](https://uql-orm.dev/entities/lifecycle-hooks) run your code around each write.
182
- - Anything the CRUD routes do not cover goes in a route you write, beside the handler and under the same prefix.
125
+ The same queries run from the browser too: [serve them over HTTP](https://uql-orm.dev/http), scoped to the signed-in user by [filters no `$where` can widen](https://uql-orm.dev/multi-tenancy).
183
126
 
184
127
  ## Why UQL?
185
128
 
186
- - **One API, everywhere it runs.** PostgreSQL, PGlite, CockroachDB, MySQL, MariaDB, MSSQL, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun's native SQL, and even MongoDB. The same code on Node 24+, Bun, Deno, [Cloudflare Workers](https://uql-orm.dev/cloudflare-d1), [AWS Lambda and Vercel](https://uql-orm.dev/serverless), and [the browser](https://uql-orm.dev/browser), with no native binaries on the `fetch`-based drivers.
129
+ - **One API, everywhere it runs.** PostgreSQL, PGlite, CockroachDB, MySQL, MariaDB, MSSQL, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun's native SQL, and even MongoDB. The same code on Node 22.18+, Bun, [Cloudflare Workers](https://uql-orm.dev/cloudflare-d1), [AWS Lambda and Vercel](https://uql-orm.dev/serverless), and [the browser](https://uql-orm.dev/browser), with no native binaries on the `fetch`-based drivers.
187
130
  - **Type-safe to the leaf, nothing to generate.** Every key is checked against your entity, down into populated relations and [JSON/JSONB](https://uql-orm.dev/querying/json) dot-paths, so `$like` on a numeric column is a compile error. No `.prisma` file, no generated client.
188
131
  - **Relations without N+1.** [`$populate`](https://uql-orm.dev/querying/relations) reads a to-many inside the parent's statement, so a read is one round trip. Nothing is lazy, so nothing fires behind your back in a serializer.
189
132
  - **Light.** Zero runtime dependencies and every dialect in one package, yet `uql-orm/postgres` is about 27 kB gzipped. See [what we deleted to get there](https://uql-orm.dev/blog/zero-dependencies).
190
133
  - **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [multi-tenant filters you cannot bypass by accident](https://uql-orm.dev/multi-tenancy), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [drift checks](https://uql-orm.dev/migrations) that catch a database that no longer matches.
191
- - **The fastest ORM.** On a full PostgreSQL round trip it adds the least over hand-written driver code of any ORM in our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), on Bun, Node and Deno alike. The same benchmark [scores the types](https://github.com/rogerpadilla/ts-orm-benchmark#type-safety) by compiling ordinary mistakes in each ORM's API: UQL is the only one that catches them all.
134
+ - **SQL when you need it.** [`raw()`](https://uql-orm.dev/querying/raw-sql) fits anywhere a value or a field goes, [computed fields](https://uql-orm.dev/entities/computed-fields) are SQL you can filter and sort on, and a migration can be plain SQL.
135
+ - **The fastest ORM.** On a full PostgreSQL round trip it adds the least over hand-written driver code of any ORM in our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), on Bun and Node alike. The same benchmark [scores the types](https://github.com/rogerpadilla/ts-orm-benchmark#type-safety) by compiling ordinary mistakes in each ORM's API: UQL is the only one that catches them all.
192
136
 
193
137
  ## Get started
194
138
 
195
- **[uql-orm.dev](https://uql-orm.dev)** has the full docs. Good places to start:
196
-
197
- - [Quick Start](https://uql-orm.dev/getting-started) - install, define an entity, run a query
198
- - [Querying](https://uql-orm.dev/querying/querier) - operators, relations, aggregates, transactions
199
- - [Entities](https://uql-orm.dev/entities/basic) - decorators, relations, hooks, or the decorator-free [imperative API](https://uql-orm.dev/entities/imperative)
200
- - [Switching to UQL](https://uql-orm.dev/switching-to-uql) - coming from Prisma, Drizzle, TypeORM, or MikroORM
201
- - [Examples](examples) - runnable apps on [Node](examples/node), [Bun](examples/bun), [Next.js](examples/nextjs) and [Cloudflare D1](examples/cloudflare-d1), each checked in CI
139
+ Follow the [Quick Start](https://uql-orm.dev/getting-started), or [switch from](https://uql-orm.dev/switching-to-uql) Prisma, Drizzle, TypeORM or MikroORM. The [examples](examples) are runnable apps on Node, Bun, Next.js and Cloudflare D1, each checked in CI.
202
140
 
203
141
  Using a coding agent? The package ships a [skill](skills/uql-orm/SKILL.md) for it, and every docs page is Markdown: [set it up](https://uql-orm.dev/ai-agents).
204
142
 
@@ -40,7 +40,9 @@ export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
40
40
  */
41
41
  get pool() {
42
42
  return {
43
- query: (text, values) => this.sql.unsafe(text, this.dialect.normalizeValues(values)).then((res) => {
43
+ query: (text, values) => this.sql
44
+ .unsafe(text, values?.map((value) => this.dialect.normalizeValue(value)))
45
+ .then((res) => {
44
46
  const rows = Array.from(res, decodeBigInts);
45
47
  return { rows, rowCount: getAffectedRows(res) ?? rows.length };
46
48
  }),
@@ -15,7 +15,7 @@ type InsertShape<E> = {
15
15
  readonly columns: string[];
16
16
  readonly kinds: PersistKind[];
17
17
  };
18
- /** One entry of {@link AbstractSqlDialect.hydratableFields}: a field key and how it decodes. */
18
+ /** A column read by its flat key, and how its value decodes. */
19
19
  type HydratableField = readonly [string, HydrateKind];
20
20
  /** A sort term's direction. A vector distance has none: it always ranks nearest first. */
21
21
  type SortOrder = Partial<SortDirection>;
@@ -25,12 +25,21 @@ export type SortRef = SortOrder & {
25
25
  };
26
26
  /**
27
27
  * One column of a read's projection: the key its row answers under, none for a raw expression written
28
- * without an alias, and whether `sql` already answers under it, being a column of that very name.
28
+ * without an alias, and whether `sql` already answers under it, being a column of that very name. The rest
29
+ * is how the row reads back, fixed as its SQL is written: see `querier/rowReader.ts`.
29
30
  */
30
31
  export type SelectTerm = {
31
32
  readonly sql: string;
32
33
  readonly key?: string;
33
34
  readonly bare?: boolean;
35
+ /** How its value decodes, where the driver leaves that to the field. */
36
+ readonly kind?: HydrateKind;
37
+ /** Columns read by their flat key, each with how it decodes: a `*`'s fields, or an aggregate's aliases. */
38
+ readonly kinds?: readonly HydratableField[];
39
+ /** A to-many's rows, each answering under these terms. */
40
+ readonly rows?: readonly SelectTerm[];
41
+ /** A joined row's key, whose `NULL` says the join matched no row. */
42
+ readonly joinedKey?: boolean;
34
43
  };
35
44
  /** What a read selected, and for a relation's rows, the columns carrying their sort terms out. */
36
45
  export type ReadProjection = {
@@ -66,10 +75,11 @@ export type RelationRows = {
66
75
  readonly distinct: boolean;
67
76
  };
68
77
  /**
69
- * A relation's rows as a derived table: `from` is the table clause, `pairs` each key of a row with the
70
- * column holding it, and `order` what their aggregate orders them by.
78
+ * A relation's rows as a derived table: `terms` how each reads, `from` the table clause, `pairs` each key of a
79
+ * row with the column holding it, and `order` what their aggregate orders them by.
71
80
  */
72
81
  export type DerivedRelation = {
82
+ readonly terms: readonly SelectTerm[];
73
83
  readonly from: string;
74
84
  readonly pairs: readonly (readonly [key: string, sql: string])[];
75
85
  readonly order: string;
@@ -149,10 +159,6 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
149
159
  * driver here binds it exactly where a number would round past 2^53; a driver that refuses one (D1) overrides.
150
160
  */
151
161
  normalizeValue(value: unknown): unknown;
152
- /**
153
- * Normalizes a list of parameter values.
154
- */
155
- normalizeValues(values: readonly unknown[] | undefined): unknown[] | undefined;
156
162
  placeholder(_index: number): string;
157
163
  /** `RETURNING <id column> id`, or nothing on a composite key, whose every column the payload already names. */
158
164
  returningId<E>(meta: EntityMeta<E>): string;
@@ -411,7 +417,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
411
417
  * caller reached for this to avoid, and only say so by taking a long time.
412
418
  */
413
419
  estimatedCount<E>(_ctx: QueryContext, _entity: Type<E>): void;
414
- aggregate<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(ctx: QueryContext, entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryRenderOptions): void;
420
+ aggregate<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(ctx: QueryContext, entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryRenderOptions): readonly SelectTerm[];
415
421
  /**
416
422
  * What one entry reads: a grouped field, through the join its path passes, or an aggregate's argument,
417
423
  * narrowed by its own `$where` to `CASE WHEN … THEN … END`. Bare where it is a column or `'*'`.
@@ -441,7 +447,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
441
447
  * LIMIT/OFFSET, so what it counts is the whole match rather than the page cut out of it.
442
448
  */
443
449
  protected readonly totalOverExpr = "COUNT(*) OVER ()";
444
- find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryRenderOptions, totalAlias?: string): void;
450
+ /** A read, answering with the terms its rows answer under, which say how each reads back. */
451
+ find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryRenderOptions, totalAlias?: string): readonly SelectTerm[];
445
452
  /**
446
453
  * A read's whole statement. The lock is appended here rather than in `search`, which `count`,
447
454
  * `update` and `delete` share: it belongs to a SELECT alone, and every engine spells it last.
@@ -556,14 +563,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
556
563
  protected formatPersistableValue(ctx: QueryContext, field: FieldOptions | undefined, value: unknown): void;
557
564
  /** How a column's values are written: a function of the column, so a bulk insert classifies each once. */
558
565
  protected persistKind(field: FieldOptions | undefined): PersistKind;
559
- /**
560
- * The columns a read decodes, and how, cached per entity and revision. They are the ones the wire cannot
561
- * decide alone: a boolean stored as an integer, a decimal read as text, a `BigInt`, and a related row's
562
- * values, which cross JSON as text.
563
- */
564
- hydratableFields<E>(entity: Type<E>): readonly HydratableField[];
565
- /** The same for an aggregate's row, per query: each alias decodes by {@link aggregateKind}. */
566
- hydratableAggregates<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>): readonly HydratableField[];
566
+ /** How an aggregate's entry decodes: as the column it reads, or a number where it reads none (a tally, a mean). */
567
+ private groupEntryKind;
567
568
  /**
568
569
  * What an aggregate's value decodes as, which the engine widens beyond the column it read: a tally
569
570
  * (`COUNT` to Postgres's `bigint`) and a mean (`AVG` to `numeric`) are numbers whatever they counted,
@@ -573,11 +574,15 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
573
574
  * One rule for both readers: a relation aggregate a field declares, and an aggregate a query names.
574
575
  */
575
576
  private aggregateKind;
576
- /** What a field decodes as: its column's kind, or a relation aggregate's {@link aggregateKind} over the target's column. */
577
+ /**
578
+ * What a field decodes as: its column's kind, or a relation aggregate's {@link aggregateKind}. `undecoded` is a
579
+ * value the driver decodes nothing of, one crossing JSON or an aggregate; on the wire it may decode some itself.
580
+ */
577
581
  private fieldKind;
578
582
  /** What one column decodes as, the inverse of {@link persistKind}. `BigInt` first, since it shares the numeric family. */
579
- protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
580
- private readonly hydratable;
583
+ private hydrateKind;
584
+ /** Whether this dialect's drivers hand a column of `kind` back decoded already, as a row on the wire. */
585
+ protected decodedAtWire(_kind: HydrateKind, _field: FieldOptions | undefined): boolean;
581
586
  /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
582
587
  private writePersistableValue;
583
588
  protected appendJsonValue(ctx: QueryContext, value: unknown, _type: JsonColumnType): void;
@@ -701,15 +706,22 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
701
706
  private appendCorrelation;
702
707
  /**
703
708
  * A junction's rows pairing the parent with the relation's targets, as far as its own filters let them
704
- * through, since a soft-deleted link is not a link; and the column naming each row's target.
709
+ * through, since a soft-deleted link is not a link; and the column each of them holds a target's key in.
705
710
  */
706
711
  private junctionRows;
712
+ /**
713
+ * Tests that the `outer` side's row has a partner among the rows of `from`, the other side's, a pair per key
714
+ * column: an `IN` over the one column each holds a lone key in, an `EXISTS` correlating every pair for several,
715
+ * which an `IN` cannot say. `from` is the junction's rows, already filtered, where the target is the outer side;
716
+ * `tail` writes the partner rows' own filters.
717
+ */
718
+ private appendPartner;
707
719
  /**
708
720
  * A relation's rows as one JSON array, in the engine's own spelling: an aggregate over them read as
709
721
  * a derived table ({@link derivedRelation}), or over the related table itself where the engine cannot
710
722
  * correlate a derived table. [The design](../../../../architecture/relations-in-one-statement.md).
711
723
  */
712
- protected abstract appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
724
+ protected abstract appendRelationArray(ctx: QueryContext, rows: RelationRows): readonly SelectTerm[];
713
725
  /**
714
726
  * The rows read as a derived table, their values crossing JSON and, where the aggregate orders, each
715
727
  * sort term carried out beside them for it to order by, since a derived table's order is not promised
@@ -1,8 +1,8 @@
1
- import { fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
1
+ import { fieldOf, getMeta, relationOf } from '../entity/index.js';
2
2
  import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, } from '../type/index.js';
3
3
  import { utcTimestamp } from '../util/date.js';
4
4
  import { isExactDecimal, isInlinedExpression, jsonKey, jsonPathKeys } from '../util/field.util.js';
5
- import { isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetKeyColumns, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
5
+ import { isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetJoins, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
6
6
  import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
7
7
  import { kindOf, UqlUsageError } from '../util/uqlError.js';
8
8
  import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn, } from './aliases.js';
@@ -209,12 +209,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
209
209
  }
210
210
  return value;
211
211
  }
212
- /**
213
- * Normalizes a list of parameter values.
214
- */
215
- normalizeValues(values) {
216
- return values?.map((v) => this.normalizeValue(v));
217
- }
218
212
  placeholder(_index) {
219
213
  return '?';
220
214
  }
@@ -265,7 +259,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
265
259
  const missingIds = opts.joined ? meta.ids.filter((key) => !selected.includes(key)) : [];
266
260
  const keys = missingIds.length ? [...missingIds, ...selected] : selected;
267
261
  if (!keys.length) {
268
- return [{ sql: `${this.escapeId(opts.prefix, true, true)}*`, bare: true }];
262
+ const kinds = definedEntries(meta.fields).flatMap(([key, field]) => {
263
+ const kind = this.fieldKind(meta, field);
264
+ return kind ? [[key, kind]] : [];
265
+ });
266
+ return [{ sql: `${this.escapeId(opts.prefix, true, true)}*`, bare: true, kinds }];
269
267
  }
270
268
  return keys.map((key) => key instanceof QueryRaw
271
269
  ? { sql: this.rawFragment(ctx, key, opts.prefix), key: key[RAW_ALIAS] }
@@ -274,17 +272,18 @@ export class AbstractSqlDialect extends VectorSqlDialect {
274
272
  /** One field's column, or the expression an inlined one stands for, as the projection reads it. */
275
273
  fieldTerm(ctx, meta, key, opts) {
276
274
  const field = fieldOf(meta, key);
275
+ const kind = this.fieldKind(meta, field, opts.json);
277
276
  if (isInlinedExpression(field)) {
278
277
  // Qualified even when nothing else in this statement is: the expression is spliced in, and one
279
278
  // that opens a correlated subquery has the inner table's columns in scope, so a bare `"id"`
280
279
  // would bind to *that* table instead of this one.
281
280
  const sql = this.rawFragment(ctx, field.computed, opts.prefix ?? this.resolveTableAlias(meta), meta.entity);
282
- return { sql: opts.json ? this.carried(`(${sql})`, field) : sql, key };
281
+ return { sql: opts.json ? this.carried(`(${sql})`, field) : sql, key, kind };
283
282
  }
284
283
  const columnName = this.resolveColumnName(key, field);
285
284
  const column = this.escapeId(opts.prefix, true, true) + this.escapeId(columnName);
286
285
  const sql = opts.json ? this.carried(column, field) : this.selectFieldExpr(column, field);
287
- return { sql, key, bare: sql === column && columnName === key };
286
+ return { sql, key, bare: sql === column && columnName === key, kind };
288
287
  }
289
288
  /**
290
289
  * What follows `SELECT` before the projection. Empty everywhere but SQL Server, whose `FETCH` will
@@ -460,8 +459,16 @@ export class AbstractSqlDialect extends VectorSqlDialect {
460
459
  ...this.selectTerms(ctx, join.entity, join.query.$select, opts, join.query.$exclude),
461
460
  ...this.selectToManyRelations(ctx, join.meta, join.query.$populate, join.alias, distinct),
462
461
  ];
462
+ const [idKey] = join.meta.ids;
463
463
  for (const term of row) {
464
- terms.push({ sql: term.sql, key: `${join.path}.${relationTermKey(term)}` });
464
+ const key = relationTermKey(term);
465
+ terms.push({
466
+ sql: term.sql,
467
+ kind: term.kind,
468
+ rows: term.rows,
469
+ key: `${join.path}.${key}`,
470
+ joinedKey: key === idKey,
471
+ });
465
472
  }
466
473
  }
467
474
  return terms;
@@ -1069,6 +1076,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1069
1076
  // may name these and nothing else, so one map answers both "is this legal?" and "what do I
1070
1077
  // emit for it?".
1071
1078
  const emittedColumns = {};
1079
+ const kinds = [];
1072
1080
  for (const { entry, value } of reads) {
1073
1081
  const column = derived ? this.escapeId(entry.alias) : value.sql;
1074
1082
  const expr = entry.kind === 'key' ? column : this.aggregateFn(entry.op, value.sql === '*' ? '*' : column, entry.distinct);
@@ -1077,6 +1085,10 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1077
1085
  }
1078
1086
  emittedColumns[entry.alias] = expr;
1079
1087
  selectParts.push(named(expr, entry.alias));
1088
+ const kind = this.groupEntryKind(meta, joins, entry);
1089
+ if (kind) {
1090
+ kinds.push([entry.alias, kind]);
1091
+ }
1080
1092
  }
1081
1093
  const columns = reads.flatMap(({ entry, value }) => (value.sql === '*' ? [] : [named(value.sql, entry.alias)]));
1082
1094
  ctx.append(`SELECT ${selectParts.join(', ')} FROM ${derived ? `(SELECT ${columns.join(', ')} FROM ` : ''}${table.ref}`);
@@ -1091,6 +1103,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1091
1103
  this.having(ctx, q.$having ?? {}, emittedColumns);
1092
1104
  const sorted = this.aggregateSort(ctx, q.$sort, emittedColumns);
1093
1105
  this.pager(ctx, q, sorted);
1106
+ return [{ sql: selectParts.join(', '), kinds }];
1094
1107
  }
1095
1108
  /**
1096
1109
  * What one entry reads: a grouped field, through the join its path passes, or an aggregate's argument,
@@ -1184,13 +1197,14 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1184
1197
  * LIMIT/OFFSET, so what it counts is the whole match rather than the page cut out of it.
1185
1198
  */
1186
1199
  totalOverExpr = 'COUNT(*) OVER ()';
1200
+ /** A read, answering with the terms its rows answer under, which say how each reads back. */
1187
1201
  find(ctx, entity, q = {}, opts, totalAlias) {
1188
1202
  const meta = getMeta(entity);
1189
1203
  const read = this.readOptions(ctx, meta, opts);
1190
1204
  // The one statement that can join, so the one that resolves the join set; everything else renders
1191
1205
  // against `NO_JOINS` and rejects a `$sort` that would need one. The joins claim their aliases after
1192
1206
  // the table's own.
1193
- this.read(ctx, entity, q, read, resolveQueryJoins(meta, q, (path) => ctx.claimAlias(path)), totalAlias);
1207
+ return this.read(ctx, entity, q, read, resolveQueryJoins(meta, q, (path) => ctx.claimAlias(path)), totalAlias).terms;
1194
1208
  }
1195
1209
  /**
1196
1210
  * A read's whole statement. The lock is appended here rather than in `search`, which `count`,
@@ -1578,46 +1592,15 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1578
1592
  const family = columnFamily(field?.type);
1579
1593
  return family === 'json' || family === 'vector' ? family : 'plain';
1580
1594
  }
1581
- /**
1582
- * The columns a read decodes, and how, cached per entity and revision. They are the ones the wire cannot
1583
- * decide alone: a boolean stored as an integer, a decimal read as text, a `BigInt`, and a related row's
1584
- * values, which cross JSON as text.
1585
- */
1586
- hydratableFields(entity) {
1587
- const meta = getMeta(entity);
1588
- const cached = this.hydratable.get(entity);
1589
- // Against the revision, not merely present: a field added to an entity already read - a content
1590
- // type the admin extended - would otherwise decode by the list its columns are missing from.
1591
- if (cached?.[0] === meta.revision) {
1592
- return cached[1];
1593
- }
1594
- const decoded = [];
1595
- for (const [key, field] of Object.entries(meta.fields)) {
1596
- const kind = this.fieldKind(meta, field);
1597
- if (kind) {
1598
- decoded.push([key, kind]);
1599
- }
1595
+ /** How an aggregate's entry decodes: as the column it reads, or a number where it reads none (a tally, a mean). */
1596
+ groupEntryKind(meta, joins, entry) {
1597
+ const source = aggregateColumnField(meta, joins, entry);
1598
+ if (!source) {
1599
+ return 'number';
1600
1600
  }
1601
- this.hydratable.set(entity, [meta.revision, decoded]);
1602
- return decoded;
1603
- }
1604
- /** The same for an aggregate's row, per query: each alias decodes by {@link aggregateKind}. */
1605
- hydratableAggregates(entity, q) {
1606
- const meta = getMeta(entity);
1607
- const { joins } = resolveGroupJoins(meta, q);
1608
- const decoded = [];
1609
- for (const entry of parseGroupMap(q.$group, q.$select)) {
1610
- const source = aggregateColumnField(meta, joins, entry);
1611
- const kind = !source
1612
- ? 'number'
1613
- : source.join
1614
- ? this.fieldKind(source.join.meta, source.field)
1615
- : this.fieldKind(meta, source.field);
1616
- if (kind) {
1617
- decoded.push([entry.alias, kind]);
1618
- }
1619
- }
1620
- return decoded;
1601
+ return source.join
1602
+ ? this.fieldKind(source.join.meta, source.field, true)
1603
+ : this.fieldKind(meta, source.field, true);
1621
1604
  }
1622
1605
  /**
1623
1606
  * What an aggregate's value decodes as, which the engine widens beyond the column it read: a tally
@@ -1630,14 +1613,18 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1630
1613
  aggregateKind(op, fieldKind) {
1631
1614
  return op === '$count' || op === '$avg' ? 'number' : fieldKind;
1632
1615
  }
1633
- /** What a field decodes as: its column's kind, or a relation aggregate's {@link aggregateKind} over the target's column. */
1634
- fieldKind(meta, field) {
1616
+ /**
1617
+ * What a field decodes as: its column's kind, or a relation aggregate's {@link aggregateKind}. `undecoded` is a
1618
+ * value the driver decodes nothing of, one crossing JSON or an aggregate; on the wire it may decode some itself.
1619
+ */
1620
+ fieldKind(meta, field, undecoded) {
1635
1621
  const spec = aggregateOf(field);
1636
1622
  if (!spec) {
1637
- return this.hydrateKind(field);
1623
+ const kind = this.hydrateKind(field);
1624
+ return kind && !undecoded && this.decodedAtWire(kind, field) ? undefined : kind;
1638
1625
  }
1639
1626
  const target = getMeta(relationOf(meta, spec.relation).entity());
1640
- return this.aggregateKind(spec.op, spec.field ? this.fieldKind(target, target.fields[spec.field]) : undefined);
1627
+ return this.aggregateKind(spec.op, spec.field ? this.fieldKind(target, target.fields[spec.field], true) : undefined);
1641
1628
  }
1642
1629
  /** What one column decodes as, the inverse of {@link persistKind}. `BigInt` first, since it shares the numeric family. */
1643
1630
  hydrateKind(field) {
@@ -1665,7 +1652,10 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1665
1652
  return undefined;
1666
1653
  }
1667
1654
  }
1668
- hydratable = new WeakMap();
1655
+ /** Whether this dialect's drivers hand a column of `kind` back decoded already, as a row on the wire. */
1656
+ decodedAtWire(_kind, _field) {
1657
+ return false;
1658
+ }
1669
1659
  /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
1670
1660
  writePersistableValue(ctx, kind, field, value) {
1671
1661
  if (value instanceof QueryRaw) {
@@ -1845,11 +1835,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1845
1835
  ctx.append(junction.from);
1846
1836
  if (hasKeys(targetWhere)) {
1847
1837
  const related = this.tableRef(relatedMeta, ctx.claimAlias(relKey));
1848
- const targetKey = soleIdOf(relatedMeta, 'a many-to-many target');
1849
- ctx.append(` AND ${junction.target} IN (`);
1850
- ctx.append(`SELECT ${this.escapedColumn(related.alias, relatedMeta, targetKey)} FROM ${related.ref}`);
1851
- this.renderWhere(ctx, relatedEntity, targetWhere, { prefix: related.alias, clause: 'WHERE' });
1852
- ctx.append(')');
1838
+ ctx.append(' AND ');
1839
+ this.appendPartner(ctx, junction.targets.map(({ key, column }) => ({
1840
+ junction: column,
1841
+ target: this.escapedColumn(related.alias, relatedMeta, key),
1842
+ })), 'junction', related.ref, (clause) => this.renderWhere(ctx, relatedEntity, targetWhere, { prefix: related.alias, clause }));
1853
1843
  }
1854
1844
  }
1855
1845
  else {
@@ -1938,7 +1928,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1938
1928
  correlation(meta, rel, parent, alias, joinedMeta) {
1939
1929
  const escapedParent = this.escapeId(parent, true, true);
1940
1930
  return parentJoins(rel, meta.ids.length)
1941
- .map(({ parent: key, joined }) => `${this.escapedColumn(alias, joinedMeta, joined)} = ${escapedParent}${this.escapedColumnName(meta, key)}`)
1931
+ .map(({ key, column }) => `${this.escapedColumn(alias, joinedMeta, column)} = ${escapedParent}${this.escapedColumnName(meta, key)}`)
1942
1932
  .join(' AND ');
1943
1933
  }
1944
1934
  /**
@@ -1948,15 +1938,19 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1948
1938
  selectToManyRelations(ctx, meta, populate, parent, distinct) {
1949
1939
  return getRelationRequestSummary(meta, populate).toManyKeys.map((relKey) => {
1950
1940
  const { query } = parseRelationAtKey(relKey, populate);
1951
- const sql = this.buildFragment(ctx, (fragmentCtx) => this.appendToManyRelation(fragmentCtx, meta, relKey, query, parent, distinct));
1952
- return { sql, key: relKey };
1941
+ let rows = [];
1942
+ const sql = this.buildFragment(ctx, (fragmentCtx) => {
1943
+ rows = this.appendToManyRelation(fragmentCtx, meta, relKey, query, parent, distinct);
1944
+ });
1945
+ return { sql, key: relKey, rows };
1953
1946
  });
1954
1947
  }
1955
1948
  /** Each relation a read's `$count` tallies, as a correlated count of its select list. */
1956
1949
  selectRelationCounts(ctx, meta, count, parent) {
1957
1950
  return countedRelations(meta, count).map(({ relKey, relation, where }) => {
1958
1951
  const sql = this.buildFragment(ctx, (fragmentCtx) => this.appendRelationSubquery(fragmentCtx, meta, relKey, relation, { prefix: parent }, { op: '$count', where }));
1959
- return { sql, key: `${COUNT_RESULT_KEY}.${relKey}` };
1952
+ // A tally comes back as its driver reads a COUNT, which on some is text.
1953
+ return { sql, key: `${COUNT_RESULT_KEY}.${relKey}`, kind: 'number' };
1960
1954
  });
1961
1955
  }
1962
1956
  /**
@@ -1972,7 +1966,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1972
1966
  const correlation = raw(({ ctx: rowsCtx }) => this.appendCorrelation(rowsCtx, meta, relation, parent, alias));
1973
1967
  const rows = { ...query, $where: whereAnd(query.$where, [correlation]) };
1974
1968
  const joins = resolveQueryJoins(relMeta, rows, (path) => ctx.claimAlias(path));
1975
- this.appendRelationArray(ctx, { entity, query: rows, alias, joins, distinct });
1969
+ return this.appendRelationArray(ctx, { entity, query: rows, alias, joins, distinct });
1976
1970
  }
1977
1971
  /**
1978
1972
  * A relation that deduplicates its rows is sorted only by what it selects: `SELECT DISTINCT` orders by
@@ -2000,23 +1994,46 @@ export class AbstractSqlDialect extends VectorSqlDialect {
2000
1994
  return;
2001
1995
  }
2002
1996
  const junction = this.junctionRows(ctx, meta, rel, rel.through(), parent);
2003
- const targetKey = soleIdOf(relMeta, 'a many-to-many target');
2004
- ctx.append(`${this.escapedColumn(alias, relMeta, targetKey)} IN (SELECT ${junction.target} FROM ${junction.from})`);
1997
+ this.appendPartner(ctx, junction.targets.map(({ key, column }) => ({
1998
+ junction: column,
1999
+ target: this.escapedColumn(alias, relMeta, key),
2000
+ })), 'target', junction.from);
2005
2001
  }
2006
2002
  /**
2007
2003
  * A junction's rows pairing the parent with the relation's targets, as far as its own filters let them
2008
- * through, since a soft-deleted link is not a link; and the column naming each row's target.
2004
+ * through, since a soft-deleted link is not a link; and the column each of them holds a target's key in.
2009
2005
  */
2010
2006
  junctionRows(ctx, meta, rel, junction, parent) {
2011
2007
  const junctionMeta = getMeta(junction);
2012
2008
  const { alias, ref } = this.tableRef(junctionMeta, ctx.claimAlias(this.resolveTableAlias(junctionMeta), parent));
2013
2009
  const scope = this.buildFragment(ctx, (fragmentCtx) => this.where(fragmentCtx, junction, {}, { prefix: alias, clause: 'AND' }));
2014
- const [target] = targetKeyColumns(rel, meta.ids.length);
2015
2010
  return {
2016
2011
  from: `${ref} WHERE ${this.correlation(meta, rel, parent, alias, junctionMeta)}${scope}`,
2017
- target: this.escapedColumn(alias, junctionMeta, target),
2012
+ targets: targetJoins(rel, meta.ids.length).map(({ key, column }) => ({
2013
+ key,
2014
+ column: this.escapedColumn(alias, junctionMeta, column),
2015
+ })),
2018
2016
  };
2019
2017
  }
2018
+ /**
2019
+ * Tests that the `outer` side's row has a partner among the rows of `from`, the other side's, a pair per key
2020
+ * column: an `IN` over the one column each holds a lone key in, an `EXISTS` correlating every pair for several,
2021
+ * which an `IN` cannot say. `from` is the junction's rows, already filtered, where the target is the outer side;
2022
+ * `tail` writes the partner rows' own filters.
2023
+ */
2024
+ appendPartner(ctx, pairs, outer, from, tail) {
2025
+ const inner = outer === 'junction' ? 'target' : 'junction';
2026
+ if (pairs.length === 1) {
2027
+ ctx.append(`${pairs[0][outer]} IN (SELECT ${pairs[0][inner]} FROM ${from}`);
2028
+ tail?.('WHERE');
2029
+ }
2030
+ else {
2031
+ const links = pairs.map((pair) => `${pair.junction} = ${pair.target}`).join(' AND ');
2032
+ ctx.append(`EXISTS (SELECT 1 FROM ${from} ${outer === 'target' ? 'AND' : 'WHERE'} ${links}`);
2033
+ tail?.('AND');
2034
+ }
2035
+ ctx.append(')');
2036
+ }
2020
2037
  /**
2021
2038
  * The rows read as a derived table, their values crossing JSON and, where the aggregate orders, each
2022
2039
  * sort term carried out beside them for it to order by, since a derived table's order is not promised
@@ -2028,6 +2045,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
2028
2045
  const { terms, order = [] } = this.read(rowsCtx, rows.entity, rows.query, readOpts, rows.joins);
2029
2046
  const alias = this.escapeId(rows.alias, true);
2030
2047
  return {
2048
+ terms,
2031
2049
  from: `(${rowsCtx.sql}) ${alias}`,
2032
2050
  pairs: terms.map((term) => {
2033
2051
  const key = relationTermKey(term);
@@ -7,13 +7,12 @@ import { type VectorCast } from './vectorCast.js';
7
7
  * a vector bound as bytes (`DialectFeatures.vectorBytes`).
8
8
  */
9
9
  export type HydrateKind = 'json' | 'boolean' | 'number' | 'bigint' | 'decimal' | 'date' | 'bytes' | 'float32' | VectorCast;
10
- /**
11
- * Decodes one non-null cell. A no-op where the driver already decoded it, since that varies per driver,
12
- * and untouched where it does not match its column's format.
13
- */
14
- export declare function decodeColumn(value: unknown, kind: HydrateKind): unknown;
10
+ type Decoder = (value: unknown) => unknown;
11
+ /** How a non-null cell of each kind decodes, keeping one already decoded or not in its kind's format. */
12
+ export declare const DECODERS: Readonly<Record<HydrateKind, Decoder>>;
15
13
  /**
16
14
  * What bytes crossing JSON start with, before two hex digits per byte: Postgres's own text for `bytea`,
17
15
  * which every dialect spells, so a string a driver reads from a column on its own is never mistaken.
18
16
  */
19
17
  export declare const BYTES_PREFIX = "\\x";
18
+ export {};
@@ -2,13 +2,6 @@ import { hexToBytes } from '../util/bytes.js';
2
2
  import { decodeDate } from '../util/date.js';
3
3
  import { decodeWideNumber } from '../util/wideNumber.js';
4
4
  import { decodeFloat32s, parseVectorLiteral } from './vectorCast.js';
5
- /**
6
- * Decodes one non-null cell. A no-op where the driver already decoded it, since that varies per driver,
7
- * and untouched where it does not match its column's format.
8
- */
9
- export function decodeColumn(value, kind) {
10
- return DECODERS[kind](value);
11
- }
12
5
  /** A decoder of the text a driver returned; anything else it already decoded, and is kept. */
13
6
  function fromText(decode) {
14
7
  return (value) => {
@@ -30,7 +23,8 @@ const float32Decoder = (value) => {
30
23
  }
31
24
  return value instanceof Uint8Array ? decodeFloat32s(value) : denseVector(value);
32
25
  };
33
- const DECODERS = {
26
+ /** How a non-null cell of each kind decodes, keeping one already decoded or not in its kind's format. */
27
+ export const DECODERS = {
34
28
  // 0/1 from SQLite's INTEGER or MySQL's TINYINT(1). Already a boolean on Postgres.
35
29
  boolean: (value) => (typeof value === 'boolean' ? value : Boolean(value)),
36
30
  date: (value) => (typeof value === 'string' ? decodeDate(value) : value),