uql-orm 0.100.2 → 0.100.3

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 (45) hide show
  1. package/README.md +8 -70
  2. package/dist/bunSql/bunSqlQuerierPool.js +3 -1
  3. package/dist/dialect/abstractSqlDialect.d.ts +27 -22
  4. package/dist/dialect/abstractSqlDialect.js +54 -59
  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/http/fetchHandler.d.ts +1 -1
  12. package/dist/http/fetchHandler.js +1 -1
  13. package/dist/mariadb/mariaDialect.d.ts +2 -2
  14. package/dist/mariadb/mariaDialect.js +1 -0
  15. package/dist/migrate/cli-config.d.ts +2 -4
  16. package/dist/migrate/cli-config.js +4 -4
  17. package/dist/mongodb/mongoDialect.js +9 -7
  18. package/dist/mssql/mssqlDialect.d.ts +2 -2
  19. package/dist/mssql/mssqlDialect.js +1 -0
  20. package/dist/pglite/pgliteQuerierPool.js +6 -12
  21. package/dist/postgres/abstractPgQuerierPool.d.ts +0 -1
  22. package/dist/postgres/abstractPgQuerierPool.js +0 -3
  23. package/dist/postgres/pgQuerier.d.ts +6 -0
  24. package/dist/postgres/pgQuerier.js +10 -0
  25. package/dist/postgres/pgWireTypes.d.ts +11 -7
  26. package/dist/postgres/pgWireTypes.js +47 -11
  27. package/dist/querier/abstractPoolQuerier.d.ts +2 -0
  28. package/dist/querier/abstractPoolQuerier.js +5 -1
  29. package/dist/querier/abstractQuerier.d.ts +1 -5
  30. package/dist/querier/abstractQuerier.js +18 -17
  31. package/dist/querier/abstractSqlQuerier.d.ts +3 -13
  32. package/dist/querier/abstractSqlQuerier.js +24 -84
  33. package/dist/querier/rowReader.d.ts +8 -0
  34. package/dist/querier/rowReader.js +88 -0
  35. package/dist/sqlite/sqliteDialect.d.ts +2 -2
  36. package/dist/sqlite/sqliteDialect.js +2 -1
  37. package/dist/util/dialect.util.d.ts +2 -11
  38. package/dist/util/dialect.util.js +8 -21
  39. package/dist/util/query.util.js +16 -8
  40. package/dist/util/sql.util.d.ts +0 -5
  41. package/dist/util/sql.util.js +0 -33
  42. package/dist/util/wideNumber.d.ts +4 -3
  43. package/dist/util/wideNumber.js +17 -6
  44. package/package.json +2 -3
  45. package/skills/uql-orm/SKILL.md +2 -2
@@ -1,13 +1,12 @@
1
1
  import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
2
- import { decodeColumn } from '../dialect/hydrateColumn.js';
3
2
  import { getMeta, namesKey } from '../entity/index.js';
4
- import { COUNT_RESULT_KEY } from '../type/index.js';
5
- import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement, isRecord, obtainAttrsPaths, unflatObject, } from '../util/index.js';
3
+ import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement } from '../util/index.js';
6
4
  import { statementOf } from '../util/raw.js';
7
5
  import { UqlUsageError } from '../util/uqlError.js';
8
6
  import { AbstractQuerier } from './abstractQuerier.js';
9
7
  import { streamViaCursor } from './cursorStream.js';
10
8
  import { enrichError } from './queryError.js';
9
+ import { rowReader } from './rowReader.js';
11
10
  /**
12
11
  * Row indexes split by whether the row names its key, the one thing that changes what an insert can
13
12
  * report; coarser than {@link groupByInsertShape} on purpose, since an insert fills a missing column with `DEFAULT`.
@@ -47,8 +46,13 @@ function groupByInsertShape(meta, payload) {
47
46
  */
48
47
  function chunkWithinLimits(meta, payload, group, maxBindValues, maxRows = Infinity) {
49
48
  const width = (indexes) => getInsertFieldKeys(meta, indexes.map((index) => payload[index])).length;
50
- const size = Math.max(1, Math.min(maxRows, Math.floor(maxBindValues / (width(group) || 1))));
51
- return chunk(group, size).flatMap((indexes) => (width(indexes) ? [indexes] : chunk(indexes, 1)));
49
+ const groupWidth = width(group);
50
+ if (!groupWidth) {
51
+ return chunk(group, 1);
52
+ }
53
+ const chunks = chunk(group, Math.max(1, Math.min(maxRows, Math.floor(maxBindValues / groupWidth))));
54
+ // A split can leave a chunk whose rows name no column; one chunk is the whole group, which names some.
55
+ return chunks.length === 1 ? chunks : chunks.flatMap((indexes) => (width(indexes) ? [indexes] : chunk(indexes, 1)));
52
56
  }
53
57
  export class AbstractSqlQuerier extends AbstractQuerier {
54
58
  dialect;
@@ -118,7 +122,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
118
122
  this.assertBindBudget(values);
119
123
  return this.serialize(async () => {
120
124
  await this.lazyConnect();
121
- return this.timed(sql, values, () => task(sql, this.dialect.normalizeValues(values)));
125
+ return this.timed(sql, values, () => task(sql, values));
122
126
  });
123
127
  }
124
128
  /**
@@ -141,7 +145,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
141
145
  }
142
146
  }
143
147
  async internalFindMany(entity, q, opts) {
144
- return (await this.selectRows(entity, q, opts)).map(this.rowReader(entity));
148
+ return this.selectRows(entity, q, opts);
145
149
  }
146
150
  /** Every row `q` matches past its page, deduplicated where it reads `$distinct`. */
147
151
  countUnpaged(entity, q, opts) {
@@ -164,8 +168,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
164
168
  for (const row of rows) {
165
169
  delete row[TOTAL_ALIAS];
166
170
  }
167
- return [rows.map(this.rowReader(entity)), total];
171
+ return [rows, total];
168
172
  }
173
+ /** The rows a read of `entity` matches, each as its statement reads it. */
169
174
  async selectRows(entity, q, opts, totalAlias) {
170
175
  // Guarded rather than awaited unconditionally, here and in the stream below: an `await` on this
171
176
  // path defers a microtask on every read, which reorders the two statements `findManyAndCount`
@@ -173,7 +178,15 @@ export class AbstractSqlQuerier extends AbstractQuerier {
173
178
  if (q.$candidates !== undefined) {
174
179
  await this.applyVectorTuning(entity, q);
175
180
  }
176
- return this.query((ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias));
181
+ return this.readRows((ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias));
182
+ }
183
+ /** The rows of a read the dialect builds, each as the terms it returns say. */
184
+ async readRows(build) {
185
+ let terms = [];
186
+ const rows = await this.query((ctx) => {
187
+ terms = build(ctx);
188
+ });
189
+ return rows.map(rowReader(terms));
177
190
  }
178
191
  /**
179
192
  * The one read not going through `all`, so it checks its budget and connects on its own; its values go as
@@ -181,13 +194,12 @@ export class AbstractSqlQuerier extends AbstractQuerier {
181
194
  */
182
195
  async *internalFindManyStream(entity, q, opts) {
183
196
  const ctx = this.dialect.createContext();
184
- this.dialect.find(ctx, entity, q, opts);
197
+ const read = rowReader(this.dialect.find(ctx, entity, q, opts));
185
198
  this.assertBindBudget(ctx.values);
186
199
  if (q.$candidates !== undefined) {
187
200
  await this.applyVectorTuning(entity, q);
188
201
  }
189
202
  await this.lazyConnect();
190
- const read = this.rowReader(entity);
191
203
  for await (const row of this.timedStream(ctx.sql, ctx.values, this.internalStream(ctx.sql, ctx.values))) {
192
204
  yield read(row);
193
205
  }
@@ -204,68 +216,6 @@ export class AbstractSqlQuerier extends AbstractQuerier {
204
216
  }
205
217
  yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, !!this.scopeHere());
206
218
  }
207
- /**
208
- * How each row of one statement becomes the entity's, for a read, a stream and a to-many alike: its dotted
209
- * columns nested as the first row names them, and its values decoded as `hydratableFields` says, resolved
210
- * once. Both live with the dialect, because a `sparsevec` is only sparse on Postgres.
211
- */
212
- rowReader(entity) {
213
- const meta = getMeta(entity);
214
- const fields = this.dialect.hydratableFields(entity);
215
- let attrsPaths;
216
- return (row) => {
217
- attrsPaths ??= obtainAttrsPaths(row);
218
- const found = unflatObject(row, attrsPaths);
219
- this.hydrateFields(meta, fields, found);
220
- return found;
221
- };
222
- }
223
- /**
224
- * One row of {@link rowReader}. A related row arrives as its parent's statement read it: a to-one
225
- * joined and unflattened, there only when its key is, since an unmatched join still fills a computed
226
- * column or a to-many's empty array; a to-many as a JSON array, which a driver may hand over as text.
227
- * Each is an object of its own, so the walk reaches none twice.
228
- */
229
- hydrateFields(meta, fields, dto) {
230
- const row = dto;
231
- for (const [key, kind] of fields) {
232
- const value = row[key];
233
- if (value != null) {
234
- row[key] = decodeColumn(value, kind);
235
- }
236
- }
237
- // A tally read inside the statement comes back as its driver reads a COUNT, which on some is text.
238
- const counts = row[COUNT_RESULT_KEY];
239
- if (isRecord(counts)) {
240
- for (const relKey in counts) {
241
- counts[relKey] = Number(counts[relKey]);
242
- }
243
- }
244
- // The value is read before the relation's target is resolved: a query that populated nothing
245
- // still walks every relation the entity declares, and `rel.entity()` is a call per row per
246
- // relation that only the populated ones need.
247
- for (const key in meta.relations) {
248
- const value = row[key];
249
- const rel = meta.relations[key];
250
- if (!value || !rel)
251
- continue;
252
- const relEntity = rel.entity();
253
- if (isRecord(value)) {
254
- const relMeta = getMeta(relEntity);
255
- if (value[relMeta.ids[0]] == null) {
256
- delete row[key];
257
- }
258
- else {
259
- this.hydrateFields(relMeta, this.dialect.hydratableFields(relEntity), value);
260
- }
261
- }
262
- else {
263
- // A to-many's rows, as flat as a statement's own.
264
- const rows = Array.isArray(value) ? value : JSON.parse(String(value));
265
- row[key] = rows.map(this.rowReader(relEntity));
266
- }
267
- }
268
- }
269
219
  /**
270
220
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
271
221
  * a caller supplying their own `types` replaces the decoding the pools do at the wire, and reads a `NULL`
@@ -282,17 +232,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
282
232
  return this.runCount((ctx) => this.dialect.estimatedCount(ctx, entity));
283
233
  }
284
234
  async internalAggregate(entity, q, opts) {
285
- const rows = await this.query((ctx) => this.dialect.aggregate(ctx, entity, q, opts));
286
- const hydratable = this.dialect.hydratableAggregates(entity, q);
287
- for (const row of rows) {
288
- const cells = row;
289
- for (const [alias, kind] of hydratable) {
290
- if (cells[alias] != null) {
291
- cells[alias] = decodeColumn(cells[alias], kind);
292
- }
293
- }
294
- }
295
- return rows;
235
+ return this.readRows((ctx) => this.dialect.aggregate(ctx, entity, q, opts));
296
236
  }
297
237
  async internalInsertMany(entity, rows) {
298
238
  const meta = getMeta(entity);
@@ -0,0 +1,8 @@
1
+ import type { SelectTerm } from '../dialect/abstractSqlDialect.js';
2
+ import type { RawRow } from '../type/index.js';
3
+ /**
4
+ * How each row of one statement becomes the entity's, from the terms its SQL was written with: its dotted
5
+ * columns nested, a joined row kept only where its key is, a to-many's rows read by their own terms, and each
6
+ * value the driver leaves to the field decoded. Resolved once per statement, so a row pays for no discovery.
7
+ */
8
+ export declare function rowReader<T>(terms: readonly SelectTerm[]): (row: RawRow) => T;
@@ -0,0 +1,88 @@
1
+ import { DECODERS } from '../dialect/hydrateColumn.js';
2
+ import { isRecord } from '../util/index.js';
3
+ const TOP = [];
4
+ const slotAt = (path) => ({ parent: path.slice(0, -1), key: path[path.length - 1] });
5
+ /**
6
+ * How each row of one statement becomes the entity's, from the terms its SQL was written with: its dotted
7
+ * columns nested, a joined row kept only where its key is, a to-many's rows read by their own terms, and each
8
+ * value the driver leaves to the field decoded. Resolved once per statement, so a row pays for no discovery.
9
+ */
10
+ export function rowReader(terms) {
11
+ const dotted = new Map();
12
+ const joined = [];
13
+ const mapped = [];
14
+ for (const { key, kind, kinds, rows, joinedKey } of terms) {
15
+ for (const [field, fieldKind] of kinds ?? []) {
16
+ mapped.push({ parent: TOP, key: field, map: DECODERS[fieldKind] });
17
+ }
18
+ if (key === undefined) {
19
+ continue;
20
+ }
21
+ const path = key.split('.');
22
+ const slot = slotAt(path);
23
+ if (path.length > 1) {
24
+ dotted.set(key, path);
25
+ if (joinedKey) {
26
+ joined.push({ ...slotAt(slot.parent), idKey: slot.key });
27
+ }
28
+ }
29
+ if (rows) {
30
+ const read = rowReader(rows);
31
+ mapped.push({ ...slot, map: (value) => (Array.isArray(value) ? value : JSON.parse(String(value))).map(read) });
32
+ }
33
+ if (kind) {
34
+ mapped.push({ ...slot, map: DECODERS[kind] });
35
+ }
36
+ }
37
+ const [firstDotted] = dotted.keys();
38
+ return (raw) => {
39
+ // All of a row's columns are flat or none is: SQL Server's `FOR JSON` nests a related row itself.
40
+ const row = firstDotted !== undefined && firstDotted in raw ? nest(raw, dotted) : raw;
41
+ for (const { parent, key, idKey } of joined) {
42
+ const holder = holderAt(row, parent);
43
+ const joinedRow = holder?.[key];
44
+ if (holder && isRecord(joinedRow) && joinedRow[idKey] == null) {
45
+ delete holder[key];
46
+ }
47
+ }
48
+ for (const { parent, key, map } of mapped) {
49
+ const holder = holderAt(row, parent);
50
+ const value = holder?.[key];
51
+ if (holder && value != null) {
52
+ holder[key] = map(value);
53
+ }
54
+ }
55
+ // A raw row becomes the entity here, as a parsed JSON value does: its shape is what the statement selected.
56
+ return row;
57
+ };
58
+ }
59
+ /** `row` with its dotted columns nested under the paths `dotted` names. */
60
+ function nest(row, dotted) {
61
+ const nested = {};
62
+ for (const column in row) {
63
+ const path = dotted.get(column);
64
+ if (!path) {
65
+ nested[column] = row[column];
66
+ continue;
67
+ }
68
+ let target = nested;
69
+ for (let i = 0; i < path.length - 1; i++) {
70
+ const next = target[path[i]];
71
+ target = isRecord(next) ? next : (target[path[i]] = {});
72
+ }
73
+ target[path[path.length - 1]] = row[column];
74
+ }
75
+ return nested;
76
+ }
77
+ /** The object at `path` in `row`, `row` itself for an empty one, if every step to it is one. */
78
+ function holderAt(row, path) {
79
+ let target = row;
80
+ for (const step of path) {
81
+ const next = target[step];
82
+ if (!isRecord(next)) {
83
+ return undefined;
84
+ }
85
+ target = next;
86
+ }
87
+ return target;
88
+ }
@@ -1,4 +1,4 @@
1
- import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from '../dialect/abstractSqlDialect.js';
1
+ import { AbstractSqlDialect, type DerivedRelation, type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
2
2
  import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
3
3
  import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type SqlValues, type VectorDistance, type VectorMetric } from '../type/index.js';
4
4
  /** What SQLite and the engines derived from it have. */
@@ -43,7 +43,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
43
43
  /** SQLite's own spelling of no limit. */
44
44
  protected readonly unboundedLimit = "-1";
45
45
  /** `json_group_array` of each row's object, ordered by the sort terms carried out beside them. */
46
- protected appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
46
+ protected appendRelationArray(ctx: QueryContext, rows: RelationRows): readonly SelectTerm[];
47
47
  /**
48
48
  * `json_object` of each key and its column. A row wider than one call takes inserts the rest into it,
49
49
  * addressing each key as one path segment.
@@ -137,8 +137,9 @@ export class SqliteDialect extends AbstractSqlDialect {
137
137
  unboundedLimit = '-1';
138
138
  /** `json_group_array` of each row's object, ordered by the sort terms carried out beside them. */
139
139
  appendRelationArray(ctx, rows) {
140
- const { from, pairs, order } = this.derivedRelation(ctx, rows);
140
+ const { terms, from, pairs, order } = this.derivedRelation(ctx, rows);
141
141
  ctx.append(`(SELECT json_group_array(${this.jsonObject(pairs)}${order ? ` ORDER BY ${order}` : ''}) FROM ${from})`);
142
+ return terms;
142
143
  }
143
144
  /**
144
145
  * `json_object` of each key and its column. A row wider than one call takes inserts the rest into it,
@@ -22,17 +22,8 @@ export declare function getFieldCallbackValue(val: OnFieldCallback): string | nu
22
22
  export declare function getSoftDeleteValue(field: FieldOptions): string | number | bigint | boolean | Date | import("../type/utility.js").JsonBrand | QueryRaw | readonly number[] | readonly import("../type/utility.js").JsonBrand[] | Uint8Array<ArrayBufferLike>;
23
23
  /** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
24
24
  export declare function fillOnFields<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, payload: R | R[], callbackKey: CallbackKey): R[];
25
- /**
26
- * The relation keys present in `payload` whose cascade configuration allows `action`. Only
27
- * `payload`'s keys are read, so any keys-bearing object works (an entity, an update payload,
28
- * or `meta.relations` itself to enumerate every cascadable relation).
29
- */
30
- export declare function filterPersistableRelationKeys<E>(meta: EntityMeta<E>, payload: object, action: CascadeType): RelationKey<E>[];
31
- /**
32
- * Whether deleting this entity has to delete anything else, which is the reason a delete resolves the
33
- * matching ids before issuing anything: a child is reached through the ids of its parent.
34
- */
35
- export declare function cascadesOnDelete<E>(meta: EntityMeta<E>): boolean;
25
+ /** The relations a write cascades `action` to, in declaration order. */
26
+ export declare function cascadingRelations<E>(meta: EntityMeta<E>, action: CascadeType): RelationKey<E>[];
36
27
  export declare function isCascadable(action: CascadeType, configuration?: boolean | CascadeType): boolean;
37
28
  /**
38
29
  * Whether `q` carries an ordering or a page, so a write has to settle its rows with a read and name
@@ -50,7 +50,7 @@ export function getInsertFieldKeys(meta, payloads) {
50
50
  for (const record of payloads) {
51
51
  addInsertFieldKeys(meta, record, seen, keys);
52
52
  }
53
- return [...keys, ...fieldKeys(meta, (field) => field.onInsert !== undefined).filter((key) => !seen.has(key))];
53
+ return [...keys, ...filledKeys(meta, 'onInsert').filter((key) => !seen.has(key))];
54
54
  }
55
55
  export function getFieldCallbackValue(val) {
56
56
  return typeof val === 'function' ? val() : val;
@@ -65,9 +65,7 @@ export function getSoftDeleteValue(field) {
65
65
  /** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
66
66
  export function fillOnFields(meta, payload, callbackKey) {
67
67
  const payloads = Array.isArray(payload) ? payload : [payload];
68
- // By presence, not truthiness, as `addInsertFieldKeys` above reads it: `onInsert: 0` and `onInsert: ''`
69
- // are values a caller meant, and a falsy one was silently never filled.
70
- const keys = fieldKeys(meta, (field) => field[callbackKey] !== undefined);
68
+ const keys = filledKeys(meta, callbackKey);
71
69
  if (keys.length === 0) {
72
70
  return payloads;
73
71
  }
@@ -80,24 +78,13 @@ export function fillOnFields(meta, payload, callbackKey) {
80
78
  }
81
79
  return payloads;
82
80
  }
83
- /**
84
- * The relation keys present in `payload` whose cascade configuration allows `action`. Only
85
- * `payload`'s keys are read, so any keys-bearing object works (an entity, an update payload,
86
- * or `meta.relations` itself to enumerate every cascadable relation).
87
- */
88
- export function filterPersistableRelationKeys(meta, payload, action) {
89
- const keys = getKeys(payload);
90
- return keys.filter((key) => {
91
- const relOpts = meta.relations[key];
92
- return relOpts && isCascadable(action, relOpts.cascade);
93
- });
81
+ /** The fields `callbackKey` fills where the caller left them unset. By presence: `onInsert: 0` is a value meant. */
82
+ function filledKeys(meta, callbackKey) {
83
+ return fieldKeys(meta, (field) => field[callbackKey] !== undefined);
94
84
  }
95
- /**
96
- * Whether deleting this entity has to delete anything else, which is the reason a delete resolves the
97
- * matching ids before issuing anything: a child is reached through the ids of its parent.
98
- */
99
- export function cascadesOnDelete(meta) {
100
- return filterPersistableRelationKeys(meta, meta.relations, 'delete').length > 0;
85
+ /** The relations a write cascades `action` to, in declaration order. */
86
+ export function cascadingRelations(meta, action) {
87
+ return getKeys(meta.relations).filter((key) => isCascadable(action, meta.relations[key]?.cascade));
101
88
  }
102
89
  export function isCascadable(action, configuration) {
103
90
  if (typeof configuration === 'boolean') {
@@ -65,28 +65,36 @@ export function assertWhere(meta, where) {
65
65
  * as no condition at all: `{ email: maybeEmail }` reading any row. `what` names the map in the error.
66
66
  */
67
67
  export function assertNoUndefined(map, what) {
68
- const path = undefinedPath(map, []);
68
+ const path = undefinedPath(map);
69
69
  if (path) {
70
70
  throw new UqlUsageError(`${what} holds undefined at '${path.join('.')}': leave the key out not to filter by it, or name null`);
71
71
  }
72
72
  }
73
- /** The path to the first `undefined` in a plain object or array, read depth first. */
74
- function undefinedPath(value, path) {
73
+ /**
74
+ * The path to the first `undefined` in a plain object or array, read depth first. Built on the way back out,
75
+ * so a filter holding none, which is every one that runs, allocates nothing.
76
+ */
77
+ function undefinedPath(value) {
75
78
  if (value === undefined) {
76
- return path;
79
+ return [];
77
80
  }
78
- if (!Array.isArray(value) && !isPlainObject(value)) {
81
+ if (!isWalkable(value)) {
79
82
  return undefined;
80
83
  }
81
- for (const [key, item] of Object.entries(value)) {
82
- const found = undefinedPath(item, [...path, key]);
84
+ for (const key in value) {
85
+ const found = undefinedPath(value[key]);
83
86
  if (found) {
87
+ found.unshift(key);
84
88
  return found;
85
89
  }
86
90
  }
87
91
  return undefined;
88
92
  }
89
- function isPlainObject(value) {
93
+ /** An array or a plain object: what a filter nests, and not a `Date`, a `raw` or a driver's value. */
94
+ function isWalkable(value) {
95
+ if (Array.isArray(value)) {
96
+ return true;
97
+ }
90
98
  if (!isRecord(value)) {
91
99
  return false;
92
100
  }
@@ -1,10 +1,5 @@
1
1
  import type { InsertIdSource, QueryUpdateResult, RawRow } from '../type/index.js';
2
2
  import type { PrimaryKey } from '../type/utility.js';
3
- /** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
4
- export declare function unflatObject<T extends object>(row: RawRow, attrsPaths: Record<string, string[]>): T;
5
- export declare function obtainAttrsPaths<T extends object>(row: T): {
6
- [k: string]: string[];
7
- };
8
3
  /**
9
4
  * A name behind its namespace, or bare where there is none: the one place the two are joined, so a
10
5
  * table's key, its statement operand and its escaped form cannot spell it differently. Never the
@@ -1,38 +1,5 @@
1
1
  import { OWNED_PREFIX } from '../dialect/aliases.js';
2
- import { hasKeys, isRecord } from './object.util.js';
3
2
  import { fnv1a } from './string.util.js';
4
- /** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
5
- export function unflatObject(row, attrsPaths) {
6
- if (!hasKeys(attrsPaths)) {
7
- return row;
8
- }
9
- const dto = {};
10
- for (const col in row) {
11
- const attrPath = attrsPaths[col];
12
- if (attrPath) {
13
- let target = dto;
14
- for (let i = 0; i < attrPath.length - 1; i++) {
15
- const seg = attrPath[i];
16
- const next = target[seg];
17
- target = isRecord(next) ? next : (target[seg] = {});
18
- }
19
- target[attrPath[attrPath.length - 1]] = row[col];
20
- }
21
- else {
22
- dto[col] = row[col];
23
- }
24
- }
25
- return dto;
26
- }
27
- export function obtainAttrsPaths(row) {
28
- const paths = {};
29
- for (const col in row) {
30
- if (col.includes('.')) {
31
- paths[col] = col.split('.');
32
- }
33
- }
34
- return paths;
35
- }
36
3
  /**
37
4
  * A name behind its namespace, or bare where there is none: the one place the two are joined, so a
38
5
  * table's key, its statement operand and its escaped form cannot spell it differently. Never the
@@ -7,9 +7,10 @@ import type { RawRow } from '../type/index.js';
7
7
  */
8
8
  export declare function decodeWideNumber(value: string | bigint): number | string;
9
9
  /**
10
- * {@link decodeWideNumber} over every `bigint` cell of a row, for the drivers that hand a BIGINT back as
11
- * one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In place: the row is the driver's fresh
12
- * object, and a copy per row cost more than the decode it carried. One argument, so it maps rows as is.
10
+ * {@link decodeWideNumber} over every `bigint` cell of a row, an array's elements included, for the
11
+ * drivers that hand a BIGINT back as one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In
12
+ * place: the row is the driver's fresh object, and a copy per row cost more than the decode it carried.
13
+ * One argument, so it maps rows as is.
13
14
  */
14
15
  export declare function decodeBigInts(row: RawRow): RawRow;
15
16
  /** {@link decodeBigInts}, keeping the cells `exact` names: what MongoDB reads a `BigInt` field into. */
@@ -9,9 +9,10 @@ export function decodeWideNumber(value) {
9
9
  return Math.abs(decoded) <= Number.MAX_SAFE_INTEGER ? decoded : String(value);
10
10
  }
11
11
  /**
12
- * {@link decodeWideNumber} over every `bigint` cell of a row, for the drivers that hand a BIGINT back as
13
- * one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In place: the row is the driver's fresh
14
- * object, and a copy per row cost more than the decode it carried. One argument, so it maps rows as is.
12
+ * {@link decodeWideNumber} over every `bigint` cell of a row, an array's elements included, for the
13
+ * drivers that hand a BIGINT back as one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In
14
+ * place: the row is the driver's fresh object, and a copy per row cost more than the decode it carried.
15
+ * One argument, so it maps rows as is.
15
16
  */
16
17
  export function decodeBigInts(row) {
17
18
  return decodeBigIntsExcept(row, () => false);
@@ -19,10 +20,20 @@ export function decodeBigInts(row) {
19
20
  /** {@link decodeBigInts}, keeping the cells `exact` names: what MongoDB reads a `BigInt` field into. */
20
21
  export function decodeBigIntsExcept(row, exact) {
21
22
  for (const key in row) {
22
- const value = row[key];
23
- if (typeof value === 'bigint' && !exact(key)) {
24
- row[key] = decodeWideNumber(value);
23
+ if (!exact(key)) {
24
+ row[key] = decodeBigIntsIn(row[key]);
25
25
  }
26
26
  }
27
27
  return row;
28
28
  }
29
+ function decodeBigIntsIn(value) {
30
+ if (typeof value === 'bigint') {
31
+ return decodeWideNumber(value);
32
+ }
33
+ if (Array.isArray(value)) {
34
+ value.forEach((element, index) => {
35
+ value[index] = decodeBigIntsIn(element);
36
+ });
37
+ }
38
+ return value;
39
+ }
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "uql-orm",
3
3
  "homepage": "https://uql-orm.dev",
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.",
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.100.2",
6
+ "version": "0.100.3",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=24"
@@ -196,7 +196,6 @@
196
196
  "d1",
197
197
  "cloudflare",
198
198
  "bun",
199
- "deno",
200
199
  "node",
201
200
  "nodejs",
202
201
  "edge",
@@ -20,7 +20,7 @@ The full docs are Markdown at https://uql-orm.dev/llms.txt, one page per URL. Re
20
20
  npm install uql-orm pg # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/client, ...
21
21
  ```
22
22
 
23
- ESM only. Node 24+, Bun, Deno or an edge runtime, TypeScript 5.7+. Decorators are the TC39 standard: never enable `experimentalDecorators` or `emitDecoratorMetadata`, never import `reflect-metadata`. In `tsconfig.json`, `module` is `nodenext` or `preserve`, and `target` is a dated one (`es2022`+), not `esnext`.
23
+ ESM only. Node 24+, Bun or an edge runtime, TypeScript 5.7+. Decorators are the TC39 standard: never enable `experimentalDecorators` or `emitDecoratorMetadata`, never import `reflect-metadata`. In `tsconfig.json`, `module` is `nodenext` or `preserve`, and `target` is a dated one (`es2022`+), not `esnext`.
24
24
 
25
25
  Node's type stripping runs no decorators: on Node, add `tsx` (`npm i -D tsx`), which `uql-migrate` imports `uql.config.ts` through. Next.js compiles TC39 decorators only through a `babel.config.json` with `@babel/plugin-proposal-decorators` at `version: '2023-11'`. A bundle that minifies class names (Next's server build, or any bundler's `minify`) needs `@Entity({ name: 'todo' })`: a table name is the class name otherwise.
26
26
 
@@ -118,7 +118,7 @@ const users = await pool.findMany(User, {
118
118
  - An update takes `{ stock: { $inc: -1 } }` to add, or `$mul` to multiply, in the statement, a NULL counting as 0, so a guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. On SQL the step may be a ref or `raw` of the field's type (`{ total: { $inc: newRow.amount } }` in a trigger). JSON fields take `$set`, `$unset`, `$push`, `$pull`.
119
119
  - `$lock: true` locks the rows a read returns (`{ $wait: 'skip' | 'nowait' }` says what to do about a row someone else holds) and needs an open transaction; SQLite, libSQL, Turso, D1 and MongoDB have no row lock and refuse it.
120
120
  - `queryErrorKind(err)` names any failure the same on every engine - `uniqueViolation`, `foreignKeyViolation`, `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage`, `security` - so catch by kind rather than by a driver's code or an `instanceof`. Every error UQL raises itself is a `UqlError`.
121
- - ``pool.all`SELECT ... WHERE id = ${id}` `` runs a `SELECT` and ``pool.run`...` `` a write: both are tags, each interpolated value bound: a scalar, `null` or a list of them, never `undefined` or a plain object (bind `JSON.stringify(doc)`). `raw` builds a fragment to embed anywhere a value or field goes, or to compose a statement, and `raw.join(fragments, ' AND ')` joins them. `raw.text(sql)` runs trusted SQL held in a string, binding nothing: never build it from user input. Migrations write ``querier.run`CREATE TABLE ...` ``. `raw` is a tag, so ``raw(`...`)`` does not compile. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.
121
+ - ``pool.all`SELECT ... WHERE id = ${id}` `` runs a `SELECT` and ``pool.run`...` `` a write, one statement per call: both are tags, each interpolated value bound: a scalar, `null` or a list of them, never `undefined` or a plain object (bind `JSON.stringify(doc)`). `raw` builds a fragment to embed anywhere a value or field goes, or to compose a statement, and `raw.join(fragments, ' AND ')` joins them. `raw.text(sql)` runs trusted SQL held in a string, binding nothing: never build it from user input. Migrations write ``querier.run`CREATE TABLE ...` ``. `raw` is a tag, so ``raw(`...`)`` does not compile. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.
122
122
 
123
123
  ## Connections and transactions
124
124