uql-orm 0.102.6 → 0.103.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 (109) hide show
  1. package/README.md +1 -1
  2. package/dist/browser/uql-browser.min.js +2 -2
  3. package/dist/browser/uql-browser.min.js.map +3 -3
  4. package/dist/bunSql/bunSqlQuerier.d.ts +9 -3
  5. package/dist/bunSql/bunSqlQuerier.js +7 -15
  6. package/dist/cockroachdb/crdbQuerierPool.d.ts +2 -2
  7. package/dist/context/context.d.ts +0 -6
  8. package/dist/context/context.js +1 -7
  9. package/dist/d1/d1Querier.d.ts +18 -14
  10. package/dist/d1/d1Querier.js +21 -8
  11. package/dist/d1/d1QuerierPool.d.ts +0 -1
  12. package/dist/d1/d1QuerierPool.js +0 -1
  13. package/dist/d1/d1SqliteDialect.d.ts +2 -0
  14. package/dist/d1/d1SqliteDialect.js +3 -0
  15. package/dist/dialect/abstractDialect.d.ts +3 -0
  16. package/dist/dialect/abstractDialect.js +6 -2
  17. package/dist/dialect/abstractSqlDialect.d.ts +26 -7
  18. package/dist/dialect/abstractSqlDialect.js +89 -60
  19. package/dist/dialect/mysqlLikeSqlDialect.js +6 -1
  20. package/dist/dialect/operators.d.ts +9 -3
  21. package/dist/dialect/operators.js +32 -9
  22. package/dist/dialect/vectorSqlDialect.js +2 -2
  23. package/dist/entity/metadata/definition.d.ts +11 -1
  24. package/dist/entity/metadata/definition.js +18 -0
  25. package/dist/mariadb/mariadbQuerier.d.ts +5 -2
  26. package/dist/mariadb/mariadbQuerier.js +5 -10
  27. package/dist/migrate/ddl/defaultSql.js +1 -1
  28. package/dist/migrate/ddl/indexDdl.d.ts +3 -3
  29. package/dist/migrate/ddl/indexDdl.js +7 -7
  30. package/dist/migrate/ddl/mysqlIndexDdl.js +2 -2
  31. package/dist/migrate/ddl/tableDdl.js +2 -2
  32. package/dist/migrate/indexPredicate.d.ts +4 -3
  33. package/dist/migrate/indexPredicate.js +5 -5
  34. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +2 -6
  35. package/dist/migrate/schemaGenerator.js +1 -1
  36. package/dist/migrate/triggerSql.js +7 -5
  37. package/dist/mongodb/mongoDialect.js +17 -41
  38. package/dist/mongodb/mongoSchemaGenerator.js +12 -12
  39. package/dist/mongodb/mongodbQuerier.d.ts +4 -3
  40. package/dist/mongodb/mongodbQuerier.js +75 -102
  41. package/dist/mssql/mssqlDialect.js +4 -9
  42. package/dist/mssql/mssqlQuerier.d.ts +9 -3
  43. package/dist/mssql/mssqlQuerier.js +9 -11
  44. package/dist/mysql/mysql2Querier.d.ts +11 -2
  45. package/dist/mysql/mysql2Querier.js +4 -7
  46. package/dist/neon/index.d.ts +2 -0
  47. package/dist/neon/index.js +2 -0
  48. package/dist/neon/neonDialect.d.ts +7 -0
  49. package/dist/neon/neonDialect.js +8 -0
  50. package/dist/neon/neonQuerier.d.ts +26 -0
  51. package/dist/neon/neonQuerier.js +42 -0
  52. package/dist/neon/neonQuerierPool.d.ts +16 -6
  53. package/dist/neon/neonQuerierPool.js +48 -5
  54. package/dist/pglite/pgliteQuerier.d.ts +9 -5
  55. package/dist/pglite/pgliteQuerier.js +7 -11
  56. package/dist/postgres/abstractPgQuerierPool.d.ts +6 -6
  57. package/dist/postgres/pgExecution.d.ts +8 -0
  58. package/dist/postgres/pgExecution.js +3 -0
  59. package/dist/postgres/pgQuerier.d.ts +8 -11
  60. package/dist/postgres/pgQuerier.js +5 -9
  61. package/dist/postgres/pgQuerierPool.d.ts +2 -2
  62. package/dist/querier/abstractQuerier.d.ts +24 -20
  63. package/dist/querier/abstractQuerier.js +79 -58
  64. package/dist/querier/abstractQuerierPool.d.ts +2 -4
  65. package/dist/querier/abstractQuerierPool.js +2 -0
  66. package/dist/querier/abstractSqlQuerier.d.ts +46 -30
  67. package/dist/querier/abstractSqlQuerier.js +141 -119
  68. package/dist/querier/queryError.d.ts +2 -0
  69. package/dist/querier/queryError.js +9 -0
  70. package/dist/querier/transaction.js +3 -7
  71. package/dist/schema/canonicalType.d.ts +3 -3
  72. package/dist/schema/canonicalType.js +4 -10
  73. package/dist/sqlite/bindValues.d.ts +10 -0
  74. package/dist/sqlite/bindValues.js +8 -0
  75. package/dist/sqlite/hranaQuerier.d.ts +17 -11
  76. package/dist/sqlite/hranaQuerier.js +16 -5
  77. package/dist/sqlite/index.d.ts +1 -1
  78. package/dist/sqlite/index.js +0 -1
  79. package/dist/sqlite/localSqliteQuerierPool.js +19 -9
  80. package/dist/sqlite/sqliteQuerier.d.ts +9 -4
  81. package/dist/sqlite/sqliteQuerier.js +14 -8
  82. package/dist/turso/tursoQuerierPool.d.ts +0 -2
  83. package/dist/turso/tursoQuerierPool.js +0 -2
  84. package/dist/turso/tursoSessionQuerier.d.ts +19 -7
  85. package/dist/turso/tursoSessionQuerier.js +31 -20
  86. package/dist/type/dialect.d.ts +3 -0
  87. package/dist/type/querier.d.ts +12 -0
  88. package/dist/type/querier.js +10 -0
  89. package/dist/type/vector.d.ts +2 -1
  90. package/dist/type/vector.js +2 -2
  91. package/dist/util/asyncScope.d.ts +11 -0
  92. package/dist/util/asyncScope.js +29 -0
  93. package/dist/util/dialect.util.d.ts +21 -6
  94. package/dist/util/dialect.util.js +34 -9
  95. package/dist/util/filters.util.d.ts +5 -4
  96. package/dist/util/filters.util.js +4 -7
  97. package/dist/util/logger.js +2 -6
  98. package/dist/util/object.util.d.ts +7 -0
  99. package/dist/util/object.util.js +17 -0
  100. package/dist/util/query.util.d.ts +3 -2
  101. package/dist/util/sql.js +1 -1
  102. package/dist/util/sql.util.d.ts +18 -16
  103. package/dist/util/sql.util.js +8 -6
  104. package/package.json +5 -8
  105. package/skills/uql-orm/SKILL.md +4 -2
  106. package/dist/context/context.browser.d.ts +0 -12
  107. package/dist/context/context.browser.js +0 -33
  108. package/dist/sqlite/abstractSqliteQuerier.d.ts +0 -28
  109. package/dist/sqlite/abstractSqliteQuerier.js +0 -36
@@ -46,29 +46,31 @@ export declare function derivedForeignKeyName(table: string, columns: readonly s
46
46
  /** Escapes an identifier with `escapeIdChar`, refusing a dotted one where `forbidQualified`, with a trailing dot where `addDot`. */
47
47
  export declare function escapeSqlId(val: string | undefined, escapeIdChar?: '`' | '"', forbidQualified?: boolean, addDot?: boolean): string;
48
48
  /**
49
- * Payload for building a QueryUpdateResult.
49
+ * What a statement came back with: the rows it read (a `RETURNING`'s included), how many rows it changed where
50
+ * the driver tells it, and the first id a header reports (MySQL's `insertId`).
50
51
  */
51
- export interface BuildUpdateResultPayload {
52
- /** The count of rows affected by the statement. */
53
- changes?: number;
54
- /** The raw rows returned by the query (for RETURNING clauses). */
55
- rows?: RawRow[];
56
- /** The first auto-generated ID from the driver header (MySQL `insertId`; no `RETURNING`). */
57
- id?: PrimaryKey;
58
- /** How the dialect surfaces inserted IDs (see {@link InsertIdSource}). */
59
- insertIdSource?: InsertIdSource;
52
+ export type SqlExecution = {
53
+ readonly rows: RawRow[];
54
+ readonly changes?: number | null;
55
+ readonly id?: PrimaryKey;
56
+ };
57
+ /** The column a `RETURNING` reports ids under: uql's own statements alias the key to it, and a raw `run()` names it so. */
58
+ export declare const RETURNED_ID = "id";
59
+ /** A statement's result, and how its dialect reports inserted ids, to build a {@link QueryUpdateResult} from. */
60
+ export type BuildUpdateResultPayload = SqlExecution & {
61
+ readonly insertIdSource?: InsertIdSource;
60
62
  /**
61
63
  * Auto-increment stride for header-derived id inference. Defaults to 1; a clustered MySQL
62
64
  * server (e.g. Galera, group replication) may set `auto_increment_increment` higher.
63
65
  */
64
- insertIdIncrement?: number;
65
- }
66
+ readonly insertIdIncrement?: number;
67
+ };
66
68
  /**
67
- * A driver's result as a {@link QueryUpdateResult}: `RETURNING` rows name their id `id`; a MySQL header's
68
- * first id is extended by the increment, which holds only where auto-increment allocation is contiguous
69
- * (`innodb_autoinc_lock_mode` 0 or 1).
69
+ * A driver's result as a {@link QueryUpdateResult}: a statement returning rows counts them, which a driver's own
70
+ * count is not always (Hrana answers 0); `RETURNING` rows name their id {@link RETURNED_ID}; a MySQL header's first id is extended
71
+ * by the increment, which holds only where auto-increment allocation is contiguous (`innodb_autoinc_lock_mode` 0, 1).
70
72
  */
71
- export declare function buildUpdateResult(payload: BuildUpdateResultPayload): QueryUpdateResult;
73
+ export declare function buildUpdateResult(payload: BuildUpdateResultPayload): Required<QueryUpdateResult>;
72
74
  /**
73
75
  * Checks if a value is of a primary key type (string, number, or bigint).
74
76
  */
@@ -112,20 +112,22 @@ export function escapeSqlId(val, escapeIdChar = '`', forbidQualified, addDot) {
112
112
  : `${escapeIdChar}${val.replaceAll(escapeIdChar, escapeIdChar + escapeIdChar)}${escapeIdChar}`;
113
113
  return addDot ? `${escaped}.` : escaped;
114
114
  }
115
+ /** The column a `RETURNING` reports ids under: uql's own statements alias the key to it, and a raw `run()` names it so. */
116
+ export const RETURNED_ID = 'id';
115
117
  /**
116
- * A driver's result as a {@link QueryUpdateResult}: `RETURNING` rows name their id `id`; a MySQL header's
117
- * first id is extended by the increment, which holds only where auto-increment allocation is contiguous
118
- * (`innodb_autoinc_lock_mode` 0 or 1).
118
+ * A driver's result as a {@link QueryUpdateResult}: a statement returning rows counts them, which a driver's own
119
+ * count is not always (Hrana answers 0); `RETURNING` rows name their id {@link RETURNED_ID}; a MySQL header's first id is extended
120
+ * by the increment, which holds only where auto-increment allocation is contiguous (`innodb_autoinc_lock_mode` 0, 1).
119
121
  */
120
122
  export function buildUpdateResult(payload) {
121
123
  const { rows, id, insertIdSource } = payload;
122
- const changes = payload.changes ?? rows?.length ?? 0;
124
+ const changes = rows.length || payload.changes || 0;
123
125
  const stride = payload.insertIdIncrement && payload.insertIdIncrement > 0 ? payload.insertIdIncrement : 1;
124
126
  // Ids from `RETURNING` are exact; otherwise from the header's first id onward, which assumes `changes`
125
127
  // counts the rows (false for a MySQL upsert batch, whose querier reads ids back instead). `0` means none.
126
128
  let ids = [];
127
- if (rows?.length) {
128
- ids = rows.map((r) => r['id']);
129
+ if (rows.length) {
130
+ ids = rows.map((r) => r[RETURNED_ID]);
129
131
  }
130
132
  else if (insertIdSource !== 'returning' && isPrimaryKey(id) && id) {
131
133
  if (typeof id === 'string') {
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "homepage": "https://uql-orm.dev",
4
4
  "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
5
5
  "license": "MIT",
6
- "version": "0.102.6",
6
+ "version": "0.103.0",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -11,9 +11,6 @@
11
11
  "sideEffects": false,
12
12
  "main": "./dist/index.js",
13
13
  "types": "./dist/index.d.ts",
14
- "browser": {
15
- "./dist/context/context.js": "./dist/context/context.browser.js"
16
- },
17
14
  "bin": {
18
15
  "uql-migrate": "./dist/migrate/bin.js"
19
16
  },
@@ -130,9 +127,9 @@
130
127
  "@electric-sql/pglite-pgvector": "0.0.11",
131
128
  "@libsql/client": "^0.18.0",
132
129
  "@neondatabase/serverless": "^1.2.0",
133
- "@nestjs/common": "^12.1.3",
134
- "@nestjs/core": "^12.1.3",
135
- "@nestjs/testing": "^12.1.3",
130
+ "@nestjs/common": "^12.2.0",
131
+ "@nestjs/core": "^12.2.0",
132
+ "@nestjs/testing": "^12.2.0",
136
133
  "@tursodatabase/database": "^0.8.3",
137
134
  "@tursodatabase/serverless": "^1.4.1",
138
135
  "@types/better-sqlite3": "^9.6.0",
@@ -144,7 +141,7 @@
144
141
  "express": "^5.3.0",
145
142
  "mariadb": "^3.5.4",
146
143
  "mongodb": "^7.7.0",
147
- "mssql": "^12.7.9",
144
+ "mssql": "^12.7.10",
148
145
  "mysql2": "^3.24.6",
149
146
  "pg": "^8.23.1",
150
147
  "pg-query-stream": "^4.17.1",
@@ -116,7 +116,7 @@ const users = await pool.findMany(User, {
116
116
  - NULL compares as the engine does: on SQL, `$ne`, `$nin`, `$not` and `$nor` drop NULL rows, where MongoDB keeps them. To keep them, name NULL: `{ $or: [{ col: { $ne: 'a' } }, { col: null }] }`. Ask for NULL with `{ col: null }` and its absence with `{ col: { $ne: null } }`.
117
117
  - Full-text: `$text: { $value }` in `$where`, through an `@Index(..., { type: 'fulltext', config })`. `$sort: { $text: 'desc' }` ranks by relevance, and `{ $text: { $project: 'score' } }` returns the score, typed `WithProjection<E, 'score'>`.
118
118
  - `findManyPage(User, { $sort: { createdAt: -1, id: 1 }, $limit: 20, $after })` pages by cursor, so page 1,000 costs what page 1 does. It returns `{ items, startCursor, endCursor, hasNextPage, hasPrevPage }`. Pass `endCursor` as `$after`, or `startCursor` as `$before`. `$sort` must end in the key or a unique `nullable: false` field, and takes no `$skip`. A nullable leading sort key pages correctly but cannot use an index.
119
- - `upsertOne(Entity, { email: true }, row, update?)`: a conflicting row takes `update`, an update payload with operators (`{ uses: { $inc: 1 } }`). An empty `{}` leaves a conflicting row alone. Cascaded relations write on either branch. Resolves to the row's id.
119
+ - `upsertOne(Entity, { email: true }, row, update?)`: a conflicting row takes `update`, an update payload with operators (`{ uses: { $inc: 1 } }`). An empty `{}` leaves a conflicting row alone. Without `update`, a conflicting row takes the payload and its `onUpdate` fills, but keeps its own key: the payload's key, and its `onInsert` fills, apply only to a row it inserts. Cascaded relations write on either branch. Resolves to the row's id.
120
120
  - Writes take `{ returning: { id: true } }` as their last argument and resolve to those rows, read back in the same transaction. Without it, inserts and upserts resolve to ids, and updates and deletes to a count. An update or delete writes exactly the rows it reports. One that reads its rows first holds them, so a racing writer waits for the commit. SQLite and MongoDB have no row locks and fail the racing writer with a retryable error instead.
121
121
  - A query is plain data, so it can be sent from a browser to `uql-orm/http`. Its handler serves only the entities its required `include` names.
122
122
  - `updateMany` and `deleteMany` that name no rows throw: no `$where` holding a value, and no `$limit`. Pass `{ unfiltered: true }` to mean the whole table.
@@ -139,7 +139,9 @@ await pool.transaction(async (querier) => {
139
139
 
140
140
  The callback commits when it returns and rolls back when it throws. Inside it, `pool` calls run on its querier. A transaction holds its connection: a statement from outside its callback waits for it. A nested `transaction()` is a savepoint, whose failure undoes its own writes alone; MongoDB refuses it. For a transaction that opens in one place and ends in another, use `beginTransaction`, `commitTransaction` and `rollbackTransaction`. `{ readOnly: true }` opens a read-only transaction: Postgres, CockroachDB, MySQL and MariaDB refuse its writes, and libSQL and Turso skip the write lock they take at `BEGIN`. `querier.onCommit(fn)` runs `fn` after the outermost commit and never on rollback: use it for mail and queued jobs. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
141
141
 
142
- A `findManyStream` holds its querier until the loop ends, and other statements on it are refused meanwhile. Inside the loop, run them on another connection. Inside a transaction, or on SQLite and PGlite (one shared connection), run them after the loop. That includes an `@AfterLoad` querying through its `querier` on a streamed row. A statement binding more values than the engine takes (100 on D1, 2098 on SQL Server) is refused: split a long `$in`.
142
+ A call uql splits into several statements (an `insertMany` past the engine's bind cap, an `upsertMany` of mixed shapes) runs them all or none: one request on D1, libSQL, Turso and Neon (over HTTP), a transaction elsewhere, joining an open one.
143
+
144
+ A `findManyStream` holds its querier until the loop ends, and other statements on it are refused meanwhile. Inside the loop, run them on another connection. Inside a transaction, or on SQLite and PGlite (one shared connection), run them after the loop. That includes an `@AfterLoad` querying through its `querier` on a streamed row. A statement binding more values than the engine takes (100 on D1, 2098 on SQL Server, 32,767 on Neon) is refused: split a long `$in`.
143
145
 
144
146
  ## Migrations
145
147
 
@@ -1,12 +0,0 @@
1
- import type { UqlContext } from '../type/index.js';
2
- /** A value held for a synchronous callback. See `context.ts` for the server behavior. */
3
- export declare function asyncScope<T>(): {
4
- run<R>(value: T, callback: () => R): R;
5
- get(): T | undefined;
6
- };
7
- /** Runs `callback` with an ambient {@link UqlContext}. See `context.ts` for the server behavior. */
8
- export declare function withContext<T>(context: UqlContext, callback: () => T): T;
9
- /** The ambient context set by the nearest enclosing {@link withContext}, or `undefined`. */
10
- export declare function getContext(): UqlContext | undefined;
11
- /** Captures the current context and returns a runner that re-establishes it later. See `context.ts`. */
12
- export declare function captureContext(): <T>(callback: () => T) => T;
@@ -1,33 +0,0 @@
1
- // The browser's `context.ts`, without `node:async_hooks`. Filters never resolve in a browser, so this
2
- // only keeps the API; it does not carry a value across `await`s.
3
- /** A value held for a synchronous callback. See `context.ts` for the server behavior. */
4
- export function asyncScope() {
5
- let current;
6
- return {
7
- run: (value, callback) => {
8
- const previous = current;
9
- current = value;
10
- try {
11
- return callback();
12
- }
13
- finally {
14
- current = previous;
15
- }
16
- },
17
- get: () => current,
18
- };
19
- }
20
- const contextScope = asyncScope();
21
- /** Runs `callback` with an ambient {@link UqlContext}. See `context.ts` for the server behavior. */
22
- export function withContext(context, callback) {
23
- return contextScope.run(context, callback);
24
- }
25
- /** The ambient context set by the nearest enclosing {@link withContext}, or `undefined`. */
26
- export function getContext() {
27
- return contextScope.get();
28
- }
29
- /** Captures the current context and returns a runner that re-establishes it later. See `context.ts`. */
30
- export function captureContext() {
31
- const context = getContext();
32
- return (callback) => (context ? withContext(context, callback) : callback());
33
- }
@@ -1,28 +0,0 @@
1
- import { AbstractSqlQuerier } from '../querier/index.js';
2
- import type { RawRow } from '../type/index.js';
3
- /** What every SQLite driver binds. No `boolean`, which the drivers refuse and the dialect writes as an integer. */
4
- export type SqliteBindValue = null | string | number | bigint | Uint8Array;
5
- /** What a statement came back with on a SQLite driver: the rows it read, and how many rows it changed. */
6
- export type SqliteExecution = {
7
- readonly rows: RawRow[];
8
- readonly changes: number;
9
- };
10
- /**
11
- * Querier for every SQLite driver. Each supplies {@link execute}, and {@link iterate} where it steps a
12
- * statement row by row; what they share - the values bound as SQLite takes them, the wide-integer
13
- * decode, and a RETURNING statement counted by its rows - is written once here.
14
- */
15
- export declare abstract class AbstractSqliteQuerier extends AbstractSqlQuerier {
16
- /** Runs one statement, answering its rows as the driver read them. */
17
- protected abstract execute(query: string, values: SqliteBindValue[]): Promise<SqliteExecution>;
18
- /** A statement's rows as the driver answers them: read whole, unless it steps them one at a time. */
19
- protected iterate(query: string, values: SqliteBindValue[]): Promise<Iterable<RawRow> | AsyncIterable<RawRow>>;
20
- internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
21
- internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
22
- internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, unknown>;
23
- /**
24
- * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
25
- * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
26
- */
27
- internalRelease(): Promise<void>;
28
- }
@@ -1,36 +0,0 @@
1
- import { AbstractSqlQuerier } from '../querier/index.js';
2
- import { decodeBigInts } from '../util/wideNumber.js';
3
- /**
4
- * Querier for every SQLite driver. Each supplies {@link execute}, and {@link iterate} where it steps a
5
- * statement row by row; what they share - the values bound as SQLite takes them, the wide-integer
6
- * decode, and a RETURNING statement counted by its rows - is written once here.
7
- */
8
- export class AbstractSqliteQuerier extends AbstractSqlQuerier {
9
- /** A statement's rows as the driver answers them: read whole, unless it steps them one at a time. */
10
- async iterate(query, values) {
11
- return (await this.execute(query, values)).rows;
12
- }
13
- async internalAll(query, values) {
14
- const { rows } = await this.execute(query, toBindValues(values));
15
- return rows.map(decodeBigInts);
16
- }
17
- async internalRun(query, values) {
18
- const { rows, changes } = await this.execute(query, toBindValues(values));
19
- // A driver's own count is unreliable for a RETURNING statement (Hrana answers 0), so its rows answer.
20
- return this.buildUpdateResult({ rows: rows.map(decodeBigInts), changes: rows.length || changes });
21
- }
22
- async *internalStream(query, values) {
23
- for await (const row of await this.iterate(query, toBindValues(values))) {
24
- yield decodeBigInts(row);
25
- }
26
- }
27
- /**
28
- * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
29
- * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
30
- */
31
- async internalRelease() { }
32
- }
33
- /** The compiler hands values over untyped, which the dialect has already normalized to what SQLite binds. */
34
- function toBindValues(values = []) {
35
- return values;
36
- }