uql-orm 0.93.1 → 0.94.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/dist/browser/uql-browser.min.js +1 -1
- package/dist/browser/uql-browser.min.js.map +3 -3
- package/dist/dialect/abstractDialect.d.ts +2 -0
- package/dist/dialect/abstractDialect.js +4 -0
- package/dist/dialect/abstractSqlDialect.d.ts +11 -6
- package/dist/dialect/abstractSqlDialect.js +28 -11
- package/dist/dialect/mysqlLikeSqlDialect.d.ts +1 -0
- package/dist/dialect/mysqlLikeSqlDialect.js +4 -1
- package/dist/dialect/pgLikeSqlDialect.d.ts +2 -0
- package/dist/dialect/pgLikeSqlDialect.js +4 -0
- package/dist/dialect/queryContext.d.ts +2 -0
- package/dist/dialect/queryContext.js +6 -0
- package/dist/maria/mariadbQuerier.d.ts +2 -1
- package/dist/maria/mariadbQuerier.js +2 -8
- package/dist/migrate/drift/driftDetector.js +7 -2
- package/dist/mongo/mongoDialect.d.ts +1 -0
- package/dist/mongo/mongoDialect.js +0 -1
- package/dist/mongo/mongodbQuerier.js +3 -10
- package/dist/mssql/mssqlDialect.d.ts +3 -2
- package/dist/mssql/mssqlDialect.js +3 -2
- package/dist/mssql/mssqlQuerier.d.ts +2 -2
- package/dist/mssql/mssqlQuerier.js +1 -3
- package/dist/mysql/mysql2Querier.d.ts +1 -1
- package/dist/mysql/mysql2Querier.js +1 -9
- package/dist/pglite/index.d.ts +1 -0
- package/dist/pglite/index.js +1 -0
- package/dist/pglite/pgliteDialect.d.ts +6 -0
- package/dist/pglite/pgliteDialect.js +6 -0
- package/dist/pglite/pgliteQuerierPool.d.ts +2 -2
- package/dist/pglite/pgliteQuerierPool.js +2 -2
- package/dist/postgres/pgQuerier.d.ts +2 -4
- package/dist/postgres/pgQuerier.js +1 -9
- package/dist/querier/abstractQuerier.d.ts +21 -3
- package/dist/querier/abstractQuerier.js +86 -17
- package/dist/querier/abstractQuerierPool.d.ts +1 -1
- package/dist/querier/abstractQuerierPool.js +1 -1
- package/dist/querier/abstractSqlQuerier.d.ts +15 -10
- package/dist/querier/abstractSqlQuerier.js +54 -57
- package/dist/querier/cursorStream.d.ts +1 -1
- package/dist/schema/sqlExpression.d.ts +4 -1
- package/dist/schema/sqlExpression.js +20 -2
- package/dist/sqlite/abstractSqliteQuerier.d.ts +1 -1
- package/dist/sqlite/sqliteDialect.d.ts +1 -0
- package/dist/sqlite/sqliteDialect.js +1 -0
- package/dist/type/entity.d.ts +4 -4
- package/dist/type/querier.d.ts +1 -1
- package/dist/type/universalQuerier.d.ts +1 -1
- package/dist/util/object.util.d.ts +2 -0
- package/dist/util/object.util.js +8 -0
- package/dist/util/query.util.d.ts +3 -1
- package/dist/util/query.util.js +7 -0
- package/dist/util/sql.util.d.ts +2 -4
- package/dist/util/sql.util.js +10 -19
- package/package.json +1 -1
- package/skills/uql-orm/SKILL.md +3 -1
|
@@ -2,7 +2,7 @@ import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
|
|
|
2
2
|
import { decodeColumn } from '../dialect/hydrateColumn.js';
|
|
3
3
|
import { getMeta, namesKey } from '../entity/index.js';
|
|
4
4
|
import { COUNT_RESULT_KEY } from '../type/index.js';
|
|
5
|
-
import { buildUpdateResult, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement, isRecord, obtainAttrsPaths, unflatObject,
|
|
5
|
+
import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement, isRecord, obtainAttrsPaths, unflatObject, } from '../util/index.js';
|
|
6
6
|
import { UqlUsageError } from '../util/uqlError.js';
|
|
7
7
|
import { AbstractQuerier } from './abstractQuerier.js';
|
|
8
8
|
import { streamViaCursor } from './cursorStream.js';
|
|
@@ -40,18 +40,13 @@ function groupByInsertShape(meta, payload) {
|
|
|
40
40
|
return [...groups.values()];
|
|
41
41
|
}
|
|
42
42
|
/**
|
|
43
|
-
* A group's row indexes split into statements within the
|
|
44
|
-
* `DEFAULT` cells bind no parameter, so fields-per-record
|
|
45
|
-
* write splits on this: D1 allows 100 binds, which a couple of dozen
|
|
43
|
+
* A group's row indexes split into statements of at most `maxRows` rows within the bind budget, payload order
|
|
44
|
+
* kept, a row with no column to write in one of its own. `DEFAULT` cells bind no parameter, so fields-per-record
|
|
45
|
+
* is a safe upper bound. Every multi-row write splits on this: D1 allows 100 binds, which a couple of dozen reach.
|
|
46
46
|
*/
|
|
47
|
-
function
|
|
47
|
+
function chunkWithinLimits(meta, payload, group, maxBindValues, maxRows = Infinity) {
|
|
48
48
|
const fieldsPerRecord = getInsertFieldKeys(meta, group.map((index) => payload[index])).length;
|
|
49
|
-
|
|
50
|
-
const chunks = [];
|
|
51
|
-
for (let start = 0; start < group.length; start += size) {
|
|
52
|
-
chunks.push(group.slice(start, start + size));
|
|
53
|
-
}
|
|
54
|
-
return chunks;
|
|
49
|
+
return chunk(group, fieldsPerRecord ? Math.max(1, Math.min(maxRows, Math.floor(maxBindValues / fieldsPerRecord))) : 1);
|
|
55
50
|
}
|
|
56
51
|
export class AbstractSqlQuerier extends AbstractQuerier {
|
|
57
52
|
dialect;
|
|
@@ -95,17 +90,26 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
95
90
|
}
|
|
96
91
|
}
|
|
97
92
|
async all(query, values) {
|
|
93
|
+
this.assertBindBudget(values);
|
|
98
94
|
return this.serialize(async () => {
|
|
99
95
|
await this.lazyConnect();
|
|
100
96
|
return this.timed(query, values, () => this.internalAll(query, this.dialect.normalizeValues(values)));
|
|
101
97
|
});
|
|
102
98
|
}
|
|
103
99
|
async run(query, values) {
|
|
100
|
+
this.assertBindBudget(values);
|
|
104
101
|
return this.serialize(async () => {
|
|
105
102
|
await this.lazyConnect();
|
|
106
103
|
return this.timed(query, values, () => this.internalRun(query, this.dialect.normalizeValues(values)));
|
|
107
104
|
});
|
|
108
105
|
}
|
|
106
|
+
/** Refused before the driver fails it, or PGlite answers it and every read after it wrong. */
|
|
107
|
+
assertBindBudget(values) {
|
|
108
|
+
const { maxBindValues, dialectName } = this.dialect;
|
|
109
|
+
if (values && values.length > maxBindValues) {
|
|
110
|
+
throw new UqlUsageError(`a statement binding ${values.length} values is past the ${maxBindValues} ${dialectName} takes; split the list it binds`);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
109
113
|
/** The rows of a statement the dialect builds. */
|
|
110
114
|
query(build) {
|
|
111
115
|
const ctx = this.dialect.createContext();
|
|
@@ -138,7 +142,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
138
142
|
}
|
|
139
143
|
}
|
|
140
144
|
async internalFindMany(entity, q, opts) {
|
|
141
|
-
return
|
|
145
|
+
return (await this.selectRows(entity, q, opts)).map(this.rowReader(entity));
|
|
142
146
|
}
|
|
143
147
|
/** Every row `q` matches past its page, deduplicated where it reads `$distinct`. */
|
|
144
148
|
countUnpaged(entity, q, opts) {
|
|
@@ -161,7 +165,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
161
165
|
for (const row of rows) {
|
|
162
166
|
delete row[TOTAL_ALIAS];
|
|
163
167
|
}
|
|
164
|
-
return [this.
|
|
168
|
+
return [rows.map(this.rowReader(entity)), total];
|
|
165
169
|
}
|
|
166
170
|
async selectRows(entity, q, opts, totalAlias) {
|
|
167
171
|
// Guarded rather than awaited unconditionally, here and in the stream below: an `await` on this
|
|
@@ -172,40 +176,27 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
172
176
|
}
|
|
173
177
|
return this.query((ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias));
|
|
174
178
|
}
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
}
|
|
179
|
+
/**
|
|
180
|
+
* The one read not going through `all`, so it checks its budget and connects on its own; its values go as
|
|
181
|
+
* the context holds them, each normalized as it was bound. The tuning is guarded as `selectRows` says.
|
|
182
|
+
*/
|
|
180
183
|
async *internalFindManyStream(entity, q, opts) {
|
|
181
|
-
|
|
184
|
+
const ctx = this.dialect.createContext();
|
|
185
|
+
this.dialect.find(ctx, entity, q, opts);
|
|
186
|
+
this.assertBindBudget(ctx.values);
|
|
182
187
|
if (q.$candidates !== undefined) {
|
|
183
188
|
await this.applyVectorTuning(entity, q);
|
|
184
189
|
}
|
|
185
|
-
const meta = getMeta(entity);
|
|
186
|
-
// The one path not going through `all`/`run`, so it connects on its own.
|
|
187
190
|
await this.lazyConnect();
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
this.dialect.find(ctx, entity, q, opts);
|
|
192
|
-
const fields = this.dialect.hydratableFields(entity);
|
|
193
|
-
let attrsPaths;
|
|
194
|
-
try {
|
|
195
|
-
for await (const row of this.internalStream(ctx.sql, ctx.values)) {
|
|
196
|
-
attrsPaths ??= obtainAttrsPaths(row);
|
|
197
|
-
const found = unflatObject(row, attrsPaths);
|
|
198
|
-
this.hydrateFields(meta, fields, found);
|
|
199
|
-
yield found;
|
|
200
|
-
}
|
|
201
|
-
}
|
|
202
|
-
catch (err) {
|
|
203
|
-
throw enrichError(err, this.logger, ctx.sql, ctx.values);
|
|
191
|
+
const read = this.rowReader(entity);
|
|
192
|
+
for await (const row of this.timedStream(ctx.sql, ctx.values, this.internalStream(ctx.sql, ctx.values))) {
|
|
193
|
+
yield read(row);
|
|
204
194
|
}
|
|
205
195
|
}
|
|
206
196
|
/**
|
|
207
197
|
* A read's rows one at a time: paged through a server-side cursor where the engine has one, read whole
|
|
208
|
-
* where it has none. A driver that streams on its own overrides this
|
|
198
|
+
* where it has none. A driver that streams on its own overrides this; a Node `Readable` it hands back
|
|
199
|
+
* closes itself when the loop exits early.
|
|
209
200
|
*/
|
|
210
201
|
async *internalStream(query, values) {
|
|
211
202
|
if (!this.dialect.features.serverSideCursors) {
|
|
@@ -215,20 +206,23 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
215
206
|
yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, this.hasOpenTransaction);
|
|
216
207
|
}
|
|
217
208
|
/**
|
|
218
|
-
*
|
|
219
|
-
*
|
|
220
|
-
*
|
|
221
|
-
* only sparse on Postgres.
|
|
209
|
+
* How each row of one statement becomes the entity's, for a read, a stream and a to-many alike: its dotted
|
|
210
|
+
* columns nested as the first row names them, and its values decoded as `hydratableFields` says, resolved
|
|
211
|
+
* once. Both live with the dialect, because a `sparsevec` is only sparse on Postgres.
|
|
222
212
|
*/
|
|
223
|
-
|
|
213
|
+
rowReader(entity) {
|
|
224
214
|
const meta = getMeta(entity);
|
|
225
215
|
const fields = this.dialect.hydratableFields(entity);
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
216
|
+
let attrsPaths;
|
|
217
|
+
return (row) => {
|
|
218
|
+
attrsPaths ??= obtainAttrsPaths(row);
|
|
219
|
+
const found = unflatObject(row, attrsPaths);
|
|
220
|
+
this.hydrateFields(meta, fields, found);
|
|
221
|
+
return found;
|
|
222
|
+
};
|
|
229
223
|
}
|
|
230
224
|
/**
|
|
231
|
-
* One row of {@link
|
|
225
|
+
* One row of {@link rowReader}. A related row arrives as its parent's statement read it: a to-one
|
|
232
226
|
* joined and unflattened, there only when its key is, since an unmatched join still fills a computed
|
|
233
227
|
* column or a to-many's empty array; a to-many as a JSON array, which a driver may hand over as text.
|
|
234
228
|
* Each is an object of its own, so the walk reaches none twice.
|
|
@@ -261,9 +255,8 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
261
255
|
const relEntity = rel.entity();
|
|
262
256
|
if (typeof value === 'string' || Array.isArray(value)) {
|
|
263
257
|
// A to-many's rows, as flat as a statement's own.
|
|
264
|
-
const rows =
|
|
265
|
-
row[key] = rows;
|
|
266
|
-
this.hydrateAll(relEntity, rows);
|
|
258
|
+
const rows = typeof value === 'string' ? JSON.parse(value) : value;
|
|
259
|
+
row[key] = rows.map(this.rowReader(relEntity));
|
|
267
260
|
}
|
|
268
261
|
else if (isRecord(value)) {
|
|
269
262
|
const relMeta = getMeta(relEntity);
|
|
@@ -325,9 +318,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
325
318
|
}
|
|
326
319
|
// Per group, not per batch: the two carry different columns - one names the key, one does not -
|
|
327
320
|
// so a budget taken over their union would under-fill the statement that is missing one.
|
|
328
|
-
for (const indexes of
|
|
329
|
-
const
|
|
330
|
-
const { ids = [] } = await this.exec((ctx) => this.dialect.insert(ctx, entity,
|
|
321
|
+
for (const indexes of chunkWithinLimits(meta, rows, group, this.dialect.maxBindValues, this.dialect.maxInsertRows)) {
|
|
322
|
+
const statementRows = indexes.map((index) => rows[index]);
|
|
323
|
+
const { ids = [] } = await this.exec((ctx) => this.dialect.insert(ctx, entity, statementRows));
|
|
331
324
|
if (idsReliable) {
|
|
332
325
|
for (let position = 0; position < indexes.length; position++) {
|
|
333
326
|
rows[indexes[position]][idKey] ??= ids[position];
|
|
@@ -350,10 +343,14 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
350
343
|
}
|
|
351
344
|
payload = clone(payload);
|
|
352
345
|
const meta = getMeta(entity);
|
|
353
|
-
// One statement per shape, each split again to stay inside the bind budget
|
|
354
|
-
// what makes
|
|
355
|
-
//
|
|
356
|
-
const statements = groupByInsertShape(meta, payload).flatMap((group) =>
|
|
346
|
+
// One statement per shape, each split again to stay inside the bind budget, less what its assignments bind
|
|
347
|
+
// once. Grouping first is what makes that one figure: every row of a group carries the same columns, so
|
|
348
|
+
// they assign the same. No row cap: SQL Server upserts through a MERGE, whose source takes any number.
|
|
349
|
+
const statements = groupByInsertShape(meta, payload).flatMap((group) => {
|
|
350
|
+
const rows = group.map((index) => payload[index]);
|
|
351
|
+
const assigned = this.dialect.upsertAssignmentBinds(entity, conflictPaths, rows, opts.update);
|
|
352
|
+
return chunkWithinLimits(meta, payload, group, this.dialect.maxBindValues - assigned);
|
|
353
|
+
});
|
|
357
354
|
if (statements.length === 1) {
|
|
358
355
|
return this.runUpsert(entity, conflictPaths, payload, opts);
|
|
359
356
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Runs one statement of the cursor protocol on the querier's own connection, which holds the cursor, and
|
|
3
|
-
* not through `all()`,
|
|
3
|
+
* not through `all()`, which refuses a statement while a stream holds the querier.
|
|
4
4
|
*/
|
|
5
5
|
type CursorExecutor<T> = (query: string, values?: unknown[]) => Promise<T[]>;
|
|
6
6
|
/**
|
|
@@ -24,5 +24,8 @@ export declare class SqlExpression {
|
|
|
24
24
|
* for the column it fills; other `raw` becomes the SQL `compile` renders, parenthesized; a literal is kept.
|
|
25
25
|
*/
|
|
26
26
|
export declare function schemaDefault(value: unknown, compile: (sql: QueryRaw) => string): unknown;
|
|
27
|
-
/**
|
|
27
|
+
/**
|
|
28
|
+
* A default as text for an exact comparison: numbers as their digits, and objects (SQL included) and text
|
|
29
|
+
* holding a JSON document as JSON with its keys in order, since a `jsonb` column reprints what it stores.
|
|
30
|
+
*/
|
|
28
31
|
export declare function writtenDefault(value: unknown): string;
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { QueryRaw, SQL_VALUE_NAMES } from '../type/index.js';
|
|
2
|
+
import { isRecord } from '../util/object.util.js';
|
|
2
3
|
import { SQL_VALUES } from '../util/raw.js';
|
|
3
4
|
/**
|
|
4
5
|
* A column default that is SQL rather than a literal, whether an entity or a migration declares it or
|
|
@@ -36,7 +37,24 @@ export function schemaDefault(value, compile) {
|
|
|
36
37
|
}
|
|
37
38
|
return value instanceof QueryRaw ? SqlExpression.parenthesized(compile(value)) : value;
|
|
38
39
|
}
|
|
39
|
-
/**
|
|
40
|
+
/**
|
|
41
|
+
* A default as text for an exact comparison: numbers as their digits, and objects (SQL included) and text
|
|
42
|
+
* holding a JSON document as JSON with its keys in order, since a `jsonb` column reprints what it stores.
|
|
43
|
+
*/
|
|
40
44
|
export function writtenDefault(value) {
|
|
41
|
-
|
|
45
|
+
const document = typeof value === 'string' ? jsonDocument(value) : value;
|
|
46
|
+
return typeof document === 'object' && document !== null ? JSON.stringify(document, keysInOrder) : String(value);
|
|
47
|
+
}
|
|
48
|
+
/** What `text` spells as JSON, or nothing where it is no JSON at all. */
|
|
49
|
+
function jsonDocument(text) {
|
|
50
|
+
try {
|
|
51
|
+
return JSON.parse(text);
|
|
52
|
+
}
|
|
53
|
+
catch {
|
|
54
|
+
return undefined;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
/** A `JSON.stringify` replacer writing each object's keys in order. */
|
|
58
|
+
function keysInOrder(_key, value) {
|
|
59
|
+
return isRecord(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : 1))) : value;
|
|
42
60
|
}
|
|
@@ -19,7 +19,7 @@ export declare abstract class AbstractSqliteQuerier extends AbstractSqlQuerier {
|
|
|
19
19
|
protected iterate(query: string, values: SqliteBindValue[]): Promise<Iterable<RawRow> | AsyncIterable<RawRow>>;
|
|
20
20
|
internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
|
|
21
21
|
internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
|
|
22
|
-
internalStream
|
|
22
|
+
internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, unknown>;
|
|
23
23
|
/**
|
|
24
24
|
* SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
|
|
25
25
|
* a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
|
|
@@ -19,6 +19,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
|
|
|
19
19
|
protected refusal(message: string): string;
|
|
20
20
|
/** SQLite's own cap on a function call before 3.48, which libSQL and `bun:sqlite`'s build still have. */
|
|
21
21
|
readonly maxFunctionArgs: number;
|
|
22
|
+
readonly maxBindValues: number;
|
|
22
23
|
/**
|
|
23
24
|
* The [sqlite-vec](https://github.com/asg017/sqlite-vec) functions, which need that extension
|
|
24
25
|
* loaded on the connection (see `Sqlite3QuerierPool`'s `extensions` option). libSQL and Turso ship
|
|
@@ -71,6 +71,7 @@ export class SqliteDialect extends AbstractSqlDialect {
|
|
|
71
71
|
}
|
|
72
72
|
/** SQLite's own cap on a function call before 3.48, which libSQL and `bun:sqlite`'s build still have. */
|
|
73
73
|
maxFunctionArgs = 127;
|
|
74
|
+
maxBindValues = 32766;
|
|
74
75
|
/**
|
|
75
76
|
* The [sqlite-vec](https://github.com/asg017/sqlite-vec) functions, which need that extension
|
|
76
77
|
* loaded on the connection (see `Sqlite3QuerierPool`'s `extensions` option). libSQL and Turso ship
|
package/dist/type/entity.d.ts
CHANGED
|
@@ -326,12 +326,12 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
|
|
|
326
326
|
};
|
|
327
327
|
export type OnFieldCallback<V = TsTypeOf<FieldType>> = V | QueryRaw | (() => V | QueryRaw);
|
|
328
328
|
/**
|
|
329
|
-
* What a column may default to: its value, or on a JSON column the
|
|
330
|
-
* erased `FieldOptions` takes
|
|
329
|
+
* What a column may default to: its value, or on a JSON column the document it stores, `[]`, or its SQL text,
|
|
330
|
+
* `'{}'`. The erased `FieldOptions` takes them all, so every field's options stay assignable to it.
|
|
331
331
|
*/
|
|
332
332
|
type DdlDefault<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? JsonDdlDefault : [TsTypeOf<FieldType>] extends [T] ? JsonDdlDefault | T : T;
|
|
333
|
-
/** What a JSON column, and the field-less `FieldOptions`, may default to. */
|
|
334
|
-
type JsonDdlDefault = Scalar |
|
|
333
|
+
/** What a JSON column, and the field-less `FieldOptions`, may default to: a document, a list included. */
|
|
334
|
+
type JsonDdlDefault = Scalar | object;
|
|
335
335
|
/**
|
|
336
336
|
* The TypeScript type a declared `type` implies, the inverse of {@link TypeFor}: a decorator checks the
|
|
337
337
|
* property against it, `defineEntity` the other way round. `entityOptions.test-d.ts` keeps them agreeing.
|
package/dist/type/querier.d.ts
CHANGED
|
@@ -34,7 +34,7 @@ type DualRead<Q extends keyof ProjectedQuery<object, never, never, never, never,
|
|
|
34
34
|
export interface Querier extends UniversalQuerier {
|
|
35
35
|
findOne: DualRead<'one', 'one'>;
|
|
36
36
|
findMany: DualRead<'many', 'many'>;
|
|
37
|
-
/** Stream records with the relations and counts `findMany` reads.
|
|
37
|
+
/** Stream records with the relations and counts `findMany` reads, `afterLoad` on each. The querier runs nothing else until the loop ends. */
|
|
38
38
|
findManyStream: DualRead<'many', 'stream'>;
|
|
39
39
|
/** Find many records and count every match. */
|
|
40
40
|
findManyAndCount: DualRead<'many', 'counted'>;
|
|
@@ -81,7 +81,7 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
|
|
|
81
81
|
export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions> {
|
|
82
82
|
/**
|
|
83
83
|
* Stream the records matching the query one at a time, each with the relations and counts `findMany`
|
|
84
|
-
* reads, for bulk reads.
|
|
84
|
+
* reads, for bulk reads. `afterLoad` runs on each row as it arrives.
|
|
85
85
|
*/
|
|
86
86
|
findManyStream: ProjectedRead<'many', 'stream', 'server', QueryOptions>;
|
|
87
87
|
/** Insert a record and resolve to its id. See {@link UniversalQuerier.insertMany}. */
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import type { EntityMeta } from '../type/index.js';
|
|
2
2
|
export declare function clone<T>(value: T): T;
|
|
3
|
+
/** `items` in consecutive lists of at most `size`, in order: one list where `size` is unbounded. */
|
|
4
|
+
export declare function chunk<T>(items: readonly T[], size: number): T[][];
|
|
3
5
|
/** Whether `obj` has at least one enumerable key. Narrows away `undefined`/`null` for callers. */
|
|
4
6
|
export declare function hasKeys<T>(obj: T): obj is NonNullable<T>;
|
|
5
7
|
/**
|
package/dist/util/object.util.js
CHANGED
|
@@ -7,6 +7,14 @@ export function clone(value) {
|
|
|
7
7
|
}
|
|
8
8
|
return { ...value };
|
|
9
9
|
}
|
|
10
|
+
/** `items` in consecutive lists of at most `size`, in order: one list where `size` is unbounded. */
|
|
11
|
+
export function chunk(items, size) {
|
|
12
|
+
const chunks = [];
|
|
13
|
+
for (let start = 0; start < items.length; start += size) {
|
|
14
|
+
chunks.push(items.slice(start, start + size));
|
|
15
|
+
}
|
|
16
|
+
return chunks;
|
|
17
|
+
}
|
|
10
18
|
/** Whether `obj` has at least one enumerable key. Narrows away `undefined`/`null` for callers. */
|
|
11
19
|
export function hasKeys(obj) {
|
|
12
20
|
if (typeof obj !== 'object' || obj === null)
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { EntityId, EntityMeta, FieldKey, Query, QueryConflictPaths, QuerySearch, QuerySortDirection, QuerySortMap, QueryWhere, QueryWhereArray } from '../type/index.js';
|
|
1
|
+
import type { EntityData, EntityId, EntityMeta, FieldKey, Query, QueryConflictPaths, QuerySearch, QuerySortDirection, QuerySortMap, QueryWhere, QueryWhereArray } from '../type/index.js';
|
|
2
2
|
/**
|
|
3
3
|
* Maps each of `keys` to `true`, the shape of a `$select` or conflict paths. This and the builders below hold
|
|
4
4
|
* the casts generic code needs to build a statement: the compiler types these maps per entity, so it does not
|
|
@@ -9,6 +9,8 @@ export declare function keySet<E>(keys: readonly FieldKey<E>[]): QueryConflictPa
|
|
|
9
9
|
export declare function whereWith<E>(key: FieldKey<E>, value: unknown, where?: QueryWhere<E>): QueryWhere<E>;
|
|
10
10
|
export declare function whereEach<E>(keys: readonly FieldKey<E>[], valueOf: (key: FieldKey<E>) => unknown): QueryWhere<E>;
|
|
11
11
|
export declare function whereAnyOf<E>(clauses: QueryWhereArray<E>): QueryWhere<E>;
|
|
12
|
+
/** The rows matching one of `rows` on `keys`: one list where a single key names them, an alternative each where several do. */
|
|
13
|
+
export declare function whereKeysIn<E>(keys: readonly FieldKey<E>[], rows: readonly EntityData<E>[]): QueryWhere<E>;
|
|
12
14
|
/** A `$sort` from `[key, direction]` pairs, sorting by the keys in the order given. */
|
|
13
15
|
export declare function sortOf<E>(entries: readonly (readonly [FieldKey<E>, QuerySortDirection])[]): QuerySortMap<E>;
|
|
14
16
|
/**
|
package/dist/util/query.util.js
CHANGED
|
@@ -19,6 +19,13 @@ export function whereEach(keys, valueOf) {
|
|
|
19
19
|
export function whereAnyOf(clauses) {
|
|
20
20
|
return { $or: clauses };
|
|
21
21
|
}
|
|
22
|
+
/** The rows matching one of `rows` on `keys`: one list where a single key names them, an alternative each where several do. */
|
|
23
|
+
export function whereKeysIn(keys, rows) {
|
|
24
|
+
const [soleKey] = keys;
|
|
25
|
+
return keys.length === 1
|
|
26
|
+
? whereWith(soleKey, rows.map((row) => row[soleKey]))
|
|
27
|
+
: whereAnyOf(rows.map((row) => whereEach(keys, (key) => row[key])));
|
|
28
|
+
}
|
|
22
29
|
/** A `$sort` from `[key, direction]` pairs, sorting by the keys in the order given. */
|
|
23
30
|
export function sortOf(entries) {
|
|
24
31
|
return Object.fromEntries(entries);
|
package/dist/util/sql.util.d.ts
CHANGED
|
@@ -1,10 +1,8 @@
|
|
|
1
1
|
import type { InsertIdSource, QueryUpdateResult, RawRow } from '../type/index.js';
|
|
2
2
|
import type { PrimaryKey } from '../type/utility.js';
|
|
3
|
+
/** Every row nested as {@link unflatObject} nests one, by the columns the first row names. */
|
|
3
4
|
export declare function unflatObjects<T extends object>(objects: RawRow[]): T[];
|
|
4
|
-
/**
|
|
5
|
-
* Unflattens a single raw row using pre-computed attribute paths.
|
|
6
|
-
* Use this for streaming to avoid per-row array allocations.
|
|
7
|
-
*/
|
|
5
|
+
/** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
|
|
8
6
|
export declare function unflatObject<T extends object>(row: RawRow, attrsPaths: Record<string, string[]>): T;
|
|
9
7
|
export declare function obtainAttrsPaths<T extends object>(row: T): {
|
|
10
8
|
[k: string]: string[];
|
package/dist/util/sql.util.js
CHANGED
|
@@ -1,37 +1,28 @@
|
|
|
1
1
|
import { OWNED_PREFIX, UPSERT_CREATED_ALIAS } from '../dialect/aliases.js';
|
|
2
|
-
import { hasKeys } from './object.util.js';
|
|
2
|
+
import { hasKeys, isRecord } from './object.util.js';
|
|
3
3
|
import { fnv1a } from './string.util.js';
|
|
4
4
|
/** Pre-computed regex for each SQL identifier escape character to avoid per-call allocation. */
|
|
5
5
|
const escapeIdRegexCache = { '`': /`/g, '"': /"/g };
|
|
6
|
+
/** Every row nested as {@link unflatObject} nests one, by the columns the first row names. */
|
|
6
7
|
export function unflatObjects(objects) {
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
}
|
|
10
|
-
const attrsPaths = obtainAttrsPaths(objects[0]);
|
|
11
|
-
if (!hasKeys(attrsPaths)) {
|
|
12
|
-
return objects;
|
|
13
|
-
}
|
|
8
|
+
const [first] = objects;
|
|
9
|
+
const attrsPaths = first ? obtainAttrsPaths(first) : {};
|
|
14
10
|
return objects.map((row) => unflatObject(row, attrsPaths));
|
|
15
11
|
}
|
|
16
|
-
/**
|
|
17
|
-
* Unflattens a single raw row using pre-computed attribute paths.
|
|
18
|
-
* Use this for streaming to avoid per-row array allocations.
|
|
19
|
-
*/
|
|
12
|
+
/** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
|
|
20
13
|
export function unflatObject(row, attrsPaths) {
|
|
14
|
+
if (!hasKeys(attrsPaths)) {
|
|
15
|
+
return row;
|
|
16
|
+
}
|
|
21
17
|
const dto = {};
|
|
22
18
|
for (const col in row) {
|
|
23
|
-
if (row[col] === null) {
|
|
24
|
-
continue;
|
|
25
|
-
}
|
|
26
19
|
const attrPath = attrsPaths[col];
|
|
27
20
|
if (attrPath) {
|
|
28
21
|
let target = dto;
|
|
29
22
|
for (let i = 0; i < attrPath.length - 1; i++) {
|
|
30
23
|
const seg = attrPath[i];
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
}
|
|
34
|
-
target = target[seg];
|
|
24
|
+
const next = target[seg];
|
|
25
|
+
target = isRecord(next) ? next : (target[seg] = {});
|
|
35
26
|
}
|
|
36
27
|
target[attrPath[attrPath.length - 1]] = row[col];
|
|
37
28
|
}
|
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, Deno, 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.
|
|
6
|
+
"version": "0.94.0",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"engines": {
|
|
9
9
|
"node": ">=24"
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -72,7 +72,7 @@ export class Post {
|
|
|
72
72
|
- A column is nullable unless it says `nullable: false`, and its property must admit `null` to match: `title?: string | null`. A property typed without `| null` on a nullable column is a compile error.
|
|
73
73
|
- Declare a `nullable: false` column `!` (`email!: string`): reads have it and inserts must name it, except a single-column key and a `version`, which uql fills. Declare `?` whatever an insert may leave out: a nullable, `onInsert`, `defaultValue`, `eager: false` or `computed` field, and relations.
|
|
74
74
|
- An engine's own column type is a `raw` constant, ``columnType: raw`tsvector` ``, rendered verbatim and carrying its own `length`/`precision`: never a bare string.
|
|
75
|
-
- `defaultValue` is a value of the field's type, or SQL the database evaluates per row: one of `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``raw`...` ``. A string is always text, `'CURRENT_TIMESTAMP'` included. The migration builder takes the same.
|
|
75
|
+
- `defaultValue` is a value of the field's type (a JSON column's document, `[]` or `{}`), or SQL the database evaluates per row: one of `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``raw`...` ``. A string is always text, `'CURRENT_TIMESTAMP'` included. The migration builder takes the same.
|
|
76
76
|
- `currentTimestamp` is the database clock, UTC to the millisecond on every engine, where a raw `CURRENT_TIMESTAMP` is not on SQLite, MySQL or SQL Server. Use it for a default, a stamp, `onUpdate` or `$where`.
|
|
77
77
|
- Members are named by callbacks, never by strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.
|
|
78
78
|
- `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names its junction entity.
|
|
@@ -128,6 +128,8 @@ await pool.transaction(async (querier) => {
|
|
|
128
128
|
|
|
129
129
|
Inside the callback, call `querier`, never `pool`: a `pool` call runs on another connection, outside the transaction. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
|
|
130
130
|
|
|
131
|
+
A `findManyStream` holds its querier until the loop ends, which refuses any other statement meanwhile: inside the loop, run them on another connection, or after the loop on SQLite and PGlite, whose pool has one. A statement binding more values than the engine takes (100 on D1, 2098 on SQL Server) is refused too: split a long `$in`.
|
|
132
|
+
|
|
131
133
|
## Migrations
|
|
132
134
|
|
|
133
135
|
`npx uql-migrate` reads `uql.config.ts`:
|