uql-orm 0.107.3 → 0.108.1

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 (89) hide show
  1. package/dist/browser/uql-browser.min.js +2 -2
  2. package/dist/browser/uql-browser.min.js.map +5 -5
  3. package/dist/cockroachdb/cockroachDialect.d.ts +1 -4
  4. package/dist/cockroachdb/cockroachDialect.js +1 -5
  5. package/dist/dialect/abstractSqlDialect.d.ts +84 -43
  6. package/dist/dialect/abstractSqlDialect.js +270 -192
  7. package/dist/dialect/aliases.d.ts +2 -0
  8. package/dist/dialect/aliases.js +2 -0
  9. package/dist/dialect/jsonSql.d.ts +9 -7
  10. package/dist/dialect/jsonSql.js +16 -10
  11. package/dist/dialect/mergeSqlDialect.d.ts +5 -7
  12. package/dist/dialect/mergeSqlDialect.js +20 -19
  13. package/dist/dialect/mysqlLikeSqlDialect.d.ts +12 -6
  14. package/dist/dialect/mysqlLikeSqlDialect.js +34 -12
  15. package/dist/dialect/operators.d.ts +7 -1
  16. package/dist/dialect/operators.js +37 -2
  17. package/dist/dialect/pgLikeSqlDialect.d.ts +4 -4
  18. package/dist/dialect/pgLikeSqlDialect.js +8 -7
  19. package/dist/entity/index.d.ts +1 -1
  20. package/dist/entity/index.js +1 -1
  21. package/dist/entity/metadata/definedFixture/author.d.ts +4 -4
  22. package/dist/entity/metadata/definedFixture/book.d.ts +5 -5
  23. package/dist/entity/metadata/definition.d.ts +2 -0
  24. package/dist/entity/metadata/definition.js +19 -11
  25. package/dist/index.d.ts +1 -1
  26. package/dist/index.js +1 -1
  27. package/dist/mariadb/mariaDialect.d.ts +2 -2
  28. package/dist/mariadb/mariaDialect.js +3 -2
  29. package/dist/migrate/codegen/fieldOptionsSource.js +28 -7
  30. package/dist/migrate/ddl/defaultSql.d.ts +3 -2
  31. package/dist/migrate/ddl/defaultSql.js +8 -12
  32. package/dist/migrate/ddl/mysqlTableDdl.js +1 -1
  33. package/dist/migrate/ddl/tableDdl.d.ts +1 -1
  34. package/dist/migrate/drift/driftDetector.js +10 -3
  35. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +2 -2
  36. package/dist/migrate/introspection/mssqlIntrospector.d.ts +2 -2
  37. package/dist/migrate/introspection/mysqlIntrospector.d.ts +2 -2
  38. package/dist/migrate/introspection/postgresIntrospector.d.ts +2 -2
  39. package/dist/migrate/introspection/sqliteIntrospector.d.ts +2 -2
  40. package/dist/migrate/migrator.js +2 -1
  41. package/dist/migrate/schemaChange.d.ts +0 -2
  42. package/dist/migrate/schemaChange.js +1 -4
  43. package/dist/migrate/schemaGenerator.d.ts +2 -2
  44. package/dist/migrate/triggerSql.js +11 -15
  45. package/dist/mongodb/mongoDialect.d.ts +6 -1
  46. package/dist/mongodb/mongoDialect.js +90 -46
  47. package/dist/mongodb/mongoSchemaGenerator.js +2 -2
  48. package/dist/mongodb/mongodbQuerier.d.ts +7 -9
  49. package/dist/mongodb/mongodbQuerier.js +54 -47
  50. package/dist/mssql/mssqlDialect.d.ts +9 -9
  51. package/dist/mssql/mssqlDialect.js +51 -28
  52. package/dist/mssql/mssqlWireTypes.d.ts +1 -4
  53. package/dist/mssql/mssqlWireTypes.js +19 -10
  54. package/dist/querier/abstractQuerier.d.ts +53 -29
  55. package/dist/querier/abstractQuerier.js +154 -102
  56. package/dist/querier/abstractSqlQuerier.d.ts +41 -10
  57. package/dist/querier/abstractSqlQuerier.js +145 -79
  58. package/dist/schema/declaredColumn.js +2 -2
  59. package/dist/schema/schemaASTDiffer.d.ts +3 -3
  60. package/dist/schema/sqlExpression.d.ts +7 -5
  61. package/dist/schema/sqlExpression.js +20 -16
  62. package/dist/schema/types.d.ts +8 -2
  63. package/dist/sqlite/sqliteDialect.js +1 -2
  64. package/dist/type/definedEntity.d.ts +5 -5
  65. package/dist/type/dialect.d.ts +26 -15
  66. package/dist/type/entity.d.ts +14 -8
  67. package/dist/type/query.d.ts +7 -2
  68. package/dist/type/queryAggregate.d.ts +4 -4
  69. package/dist/type/querySql.d.ts +4 -1
  70. package/dist/type/querySql.js +5 -1
  71. package/dist/type/queryWhere.d.ts +16 -11
  72. package/dist/type/universalQuerier.d.ts +7 -7
  73. package/dist/util/ddlExpression.util.d.ts +5 -0
  74. package/dist/util/ddlExpression.util.js +9 -2
  75. package/dist/util/dialect.util.d.ts +14 -6
  76. package/dist/util/dialect.util.js +17 -13
  77. package/dist/util/field.util.d.ts +12 -0
  78. package/dist/util/field.util.js +17 -1
  79. package/dist/util/fieldOption.util.js +5 -1
  80. package/dist/util/object.util.d.ts +4 -0
  81. package/dist/util/object.util.js +13 -0
  82. package/dist/util/query.util.d.ts +5 -3
  83. package/dist/util/query.util.js +7 -2
  84. package/dist/util/sql.d.ts +25 -7
  85. package/dist/util/sql.js +58 -18
  86. package/dist/util/triggerWrite.d.ts +7 -4
  87. package/dist/util/triggerWrite.js +5 -4
  88. package/package.json +1 -1
  89. package/skills/uql-orm/SKILL.md +27 -19
@@ -1,29 +1,38 @@
1
1
  import { decodeWideNumber } from '../util/wideNumber.js';
2
2
  /**
3
- * Decodes `BIGINT`, which `tedious` returns as text, by `decodeWideNumber`: `type: Number` maps to
4
- * BIGINT, so otherwise every generated key reads back as a string. At the wire, which every result crosses.
3
+ * How a column of each type `tedious` mistranslates is read: a `BIGINT`, which it returns as text because
4
+ * `type: Number` maps to BIGINT, by `decodeWideNumber`; a `UNIQUEIDENTIFIER`, which SQL Server returns in capitals,
5
+ * lowercased to read back as every other engine does.
5
6
  */
7
+ const DECODERS = new Map([
8
+ ['BigInt', decodeWideNumber],
9
+ ['UniqueIdentifier', (value) => value.toLowerCase()],
10
+ ]);
11
+ /** Decodes the columns {@link DECODERS} names, at the wire, which every result crosses. */
6
12
  export function decodeWireTypes(rows, columns) {
7
13
  if (!rows?.length || !columns) {
8
14
  return rows ?? [];
9
15
  }
10
- const wide = Object.keys(columns).filter((name) => typeName(columns[name]?.type) === 'BigInt');
11
- if (!wide.length) {
16
+ const decoded = Object.keys(columns).flatMap((name) => {
17
+ const decode = DECODERS.get(typeName(columns[name]?.type));
18
+ return decode ? [{ name, decode }] : [];
19
+ });
20
+ if (!decoded.length) {
12
21
  // The overwhelmingly common case, so an ordinary read copies nothing.
13
22
  return rows;
14
23
  }
15
24
  return rows.map((row) => {
16
- const decoded = { ...row };
17
- for (const name of wide) {
18
- const value = decoded[name];
25
+ const values = { ...row };
26
+ for (const { name, decode } of decoded) {
27
+ const value = values[name];
19
28
  if (typeof value === 'string') {
20
- decoded[name] = decodeWideNumber(value);
29
+ values[name] = decode(value);
21
30
  }
22
31
  }
23
- return decoded;
32
+ return values;
24
33
  });
25
34
  }
26
35
  /** `tedious` reports a column's type as its factory function, whose `name` is the type's own. */
27
36
  function typeName(type) {
28
- return typeof type === 'function' ? type.name : undefined;
37
+ return typeof type === 'function' ? type.name : '';
29
38
  }
@@ -1,13 +1,17 @@
1
1
  import type { AbstractDialect } from '../dialect/abstractDialect.js';
2
- import type { BooleanLike, CursorPage, Captured, EntityData, EntityId, EntityWrite, ExtraOptions, FieldKey, Querier, Query, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryKeyset, QueryOne, QueryOptions, QueryPage, QuerySearch, SavepointCommand, TransactionOptions, Type, UpdatePayload, UpdateWrite, WriteResults, WriteOptions, PrimaryKey, WrittenId, RawRow } from '../type/index.js';
2
+ import type { BooleanLike, CursorPage, Captured, EntityData, EntityId, EntityWrite, EntityMeta, ExtraOptions, FieldKey, Querier, Query, QueryAggregate, QueryAggregateResult, QueryConflictKeys, QueryUpsert, QueryFilter, QueryFindResult, QueryKeyset, QueryOne, QueryOptions, QueryPage, QuerySearch, SavepointCommand, TransactionOptions, Type, UpdatePayload, UpdateWrite, WriteResults, WriteOptions, PrimaryKey, WrittenId, RawRow, ReportedWrite } from '../type/index.js';
3
3
  import { LoggerWrapper } from '../util/index.js';
4
4
  import { type TransactionScope } from './transaction.js';
5
5
  /** What an upsert reports of a row: the value a driver answers for a lone key, or the key the read back names. */
6
6
  export type UpsertedId<E> = PrimaryKey | WrittenId<E>;
7
- /** An `UPDATE` and a `DELETE` of one statement each, reporting the rows they wrote with the fields `keys` names. */
8
- export type WritesReturning = {
7
+ /** Each write as one statement reporting the rows it wrote with the fields `keys` names. */
8
+ export type ReportingWrites = {
9
9
  update<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts: QueryOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
10
10
  delete<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts: QueryOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
11
+ /** Inserts `rows`, reporting each in their order and placing its key on it, as `internalInsertMany` does. */
12
+ insert<E extends object>(entity: Type<E>, rows: EntityData<E>[], keys: readonly FieldKey<E>[]): Promise<E[]>;
13
+ /** The rows of `payload` the upsert writes, in its order, `undefined` for one it kept. */
14
+ upsert<E extends object>(entity: Type<E>, q: QueryUpsert<E>, payload: E[], update: UpdatePayload<E> | undefined, keys: readonly FieldKey<E>[]): Promise<(E | undefined)[]>;
11
15
  };
12
16
  /** Base class for all database queriers. */
13
17
  export declare abstract class AbstractQuerier implements Querier {
@@ -110,16 +114,23 @@ export declare abstract class AbstractQuerier implements Querier {
110
114
  abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
111
115
  insertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V>): Promise<WriteResults<E, S, V>['inserted']>;
112
116
  insertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V>): Promise<WriteResults<E, S, V>['inserted'][]>;
117
+ /**
118
+ * What an insert reports: the ids, or the rows `returning` asks for, off the insert's own statement where
119
+ * {@link reportingWrites} can, else read back.
120
+ */
121
+ private insertWritten;
113
122
  /**
114
123
  * The ids of the rows inserted, in payload order. The `onInsert` values are filled before the write, so
115
124
  * the after hooks and the ids read the same rows the statement wrote.
116
125
  */
117
126
  private insertIds;
127
+ /** `insert` of `payload` between the insert hooks, {@link atomically} where it writes relations too. */
128
+ private inserting;
118
129
  /**
119
- * The ids `write` reports, or, where `opts` asks for `returning`, the rows they name, read back in the same
120
- * transaction with only the fields it lists.
130
+ * The ids `write` reports, or, where `opts` asks for `returning`, the rows they name, read back
131
+ * {@link atomically} with the write and only the fields it lists.
121
132
  */
122
- private writeReturning;
133
+ private writtenOrReadBack;
123
134
  /**
124
135
  * The rows `ids` names, in their order, each with only the fields `keys` names: as written, whatever a filter
125
136
  * says of them, since a soft-deleted row inserted is still written.
@@ -129,8 +140,8 @@ export declare abstract class AbstractQuerier implements Querier {
129
140
  private returned;
130
141
  /**
131
142
  * Writes `rows` and their relations: the to-ones they hold the keys of first, so each row inserts
132
- * pointing at its own, then the rows, then their children by the keys the rows got. An insert, and the
133
- * insert half of a read upsert.
143
+ * pointing at its own, then the rows, by `insert`, then their children by the keys the rows got. An insert,
144
+ * and the insert half of a read upsert. Answers what `insert` reports.
134
145
  */
135
146
  private insertRows;
136
147
  /** Writes `rows`, its columns only, and onto each one the key the database generated for it, where it can tell. */
@@ -143,8 +154,8 @@ export declare abstract class AbstractQuerier implements Querier {
143
154
  */
144
155
  private updateWhere;
145
156
  /**
146
- * An update of one statement reporting the rows it wrote, between the update hooks. A payload writing no
147
- * column writes nothing, so the rows it names are read instead.
157
+ * An update of one statement reporting the rows it wrote. A row writing no column writes nothing, so the rows
158
+ * it names are read instead.
148
159
  */
149
160
  private updateReturning;
150
161
  /**
@@ -174,7 +185,7 @@ export declare abstract class AbstractQuerier implements Querier {
174
185
  * Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or
175
186
  * delete, and one without {@link DialectFeatures.correlatedWrites} cannot read a relation in its filter.
176
187
  */
177
- protected settlesWrite<E extends object>(entity: Type<E>, q: QuerySearch<E>): boolean;
188
+ private settlesWrite;
178
189
  /**
179
190
  * `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed,
180
191
  * inside its caller's transaction, so a write split to fit the engine still lands whole.
@@ -187,31 +198,42 @@ export declare abstract class AbstractQuerier implements Querier {
187
198
  /**
188
199
  * The rows a write reads before it writes, held until the open transaction ends where the engine has row
189
200
  * locks, so a racing writer waits for the commit; outside a transaction a lock would hold nothing. Elsewhere
190
- * the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite and MongoDB fail the racer.
201
+ * the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite fails the racer, and so
202
+ * does MongoDB inside a transaction the caller opens.
191
203
  */
192
204
  private readForWrite;
193
- /** How the engine writes rows and reports them in one statement, or `undefined` where a write reads them first. */
194
- protected get writesReturning(): WritesReturning | undefined;
205
+ /** How the engine writes rows of `meta` and reports them in one statement, or `undefined` where `write` reads them. */
206
+ protected reportingWrites<E>(_meta: EntityMeta<E>, _write: ReportedWrite): ReportingWrites | undefined;
195
207
  /** Runs one UPDATE over `q`, which names its rows by id wherever {@link updateMany} settled them. */
196
208
  protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
197
209
  restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;
198
210
  restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
211
+ upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QueryUpsert<E>, payload: EntityWrite<E>, update?: UpdateWrite<E>, opts?: WriteOptions<E, S, V>): Promise<WriteResults<E, S, V>['inserted']>;
212
+ upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QueryUpsert<E>, payload: readonly EntityWrite<E>[], update?: UpdateWrite<E>, opts?: WriteOptions<E, S, V>): Promise<WriteResults<E, S, V>['inserted'][]>;
213
+ /** Upserts `rows`, reading first where {@link upsertsByReading} says so, and answers the id each row got. */
214
+ private upsertIds;
215
+ /**
216
+ * An upsert of one statement reporting each row as it stands after it: off its `RETURNING` where it wrote the row,
217
+ * else, where its `$where` or an empty `update` kept it, read by the conflict keys.
218
+ */
219
+ private upsertReturning;
199
220
  /**
200
- * An update the library writes of its own, hooked as a caller's is but carrying no version: a restore's
201
- * cleared stamp, or a row pointed at the relation just inserted for it.
221
+ * Refuses a row an upsert wrote or kept that no row matches by its conflict key, as read back: the engine stores
222
+ * the key otherwise than the row spells it, a uuid in other letters, and a row left out would misalign the rest.
202
223
  */
203
- private unversionedUpdate;
204
- upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>, update?: UpdateWrite<E>, opts?: WriteOptions<E, S, V>): Promise<WriteResults<E, S, V>['inserted']>;
205
- upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[], update?: UpdateWrite<E>, opts?: WriteOptions<E, S, V>): Promise<WriteResults<E, S, V>['inserted'][]>;
224
+ private unmatched;
206
225
  /**
207
226
  * An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
208
- * as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
209
- * tenant's. A found row is held until the write, and a row inserted concurrently fails on its key. See
210
- * architecture/security-filter-writes.md.
227
+ * by id as `updateOne` does, a versioned one at its version, and the rest insert, so either branch writes its
228
+ * relations and a guarded row stays its tenant's. Inside a transaction a found row is held until the write, and
229
+ * a row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
211
230
  */
212
231
  private readThenUpsert;
213
- /** Upserts `payload`, answering each row's key in payload order, `undefined` for one the engine did not report. */
214
- protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[]>;
232
+ /**
233
+ * Upserts `payload` as `q` names its rows, answering each row's key in payload order, `undefined` for one the
234
+ * engine did not report.
235
+ */
236
+ protected abstract internalUpsertMany<E extends object>(entity: Type<E>, q: QueryUpsert<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[]>;
215
237
  deleteOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<WriteResults<E, S, V>['affected']>;
216
238
  /** Delete records matching the query, the entity passed first or as `$entity`; soft-deletes unless `opts.hardDelete`. */
217
239
  deleteMany<E extends object>(q: QuerySearch<E> & {
@@ -318,17 +340,19 @@ export declare abstract class AbstractQuerier implements Querier {
318
340
  * listens.
319
341
  */
320
342
  private emitLoaded;
343
+ /** The ids of `rows`, read by the columns an upsert matches them on, as {@link rowsByConflict} reads them. */
344
+ private idsByConflict;
321
345
  /**
322
- * The ids of `rows`, read by the columns an upsert matches them on, soft-deleted rows included since a unique key
323
- * holds across both, each read held as {@link readForWrite} holds its rows. A row no found row matches, or two do,
324
- * reads none, since a missing id is honest where a guessed one is not; a null key never conflicts, so is not read.
346
+ * The row each of `rows` matches on the columns an upsert matches on, with `select`, soft-deleted rows included
347
+ * since a unique key holds across both, held as {@link readForWrite} holds its rows. One no row matches, or two do,
348
+ * reads none, since a missing row is honest where a guessed one is not; a null key never conflicts, so is not read.
325
349
  */
326
- protected idsByConflict<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, rows: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
350
+ private rowsByConflict;
327
351
  /**
328
352
  * `ids` completed where an upsert reported no id for a row whose key it does not keep (`kept`, asked before the
329
353
  * write fills one in): read back by the conflict columns.
330
354
  */
331
- protected withUnreportedIds<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[], ids: (UpsertedId<E> | undefined)[], kept: readonly boolean[]): Promise<(UpsertedId<E> | undefined)[]>;
355
+ protected withUnreportedIds<E extends object>(entity: Type<E>, conflictKeys: QueryConflictKeys<E>, payload: EntityData<E>[], ids: (UpsertedId<E> | undefined)[], kept: readonly boolean[]): Promise<(UpsertedId<E> | undefined)[]>;
332
356
  /** Reads of the rows matching one of `rows` on `keys`, as many per statement as a key list takes, selecting `select`. */
333
357
  private keyedReads;
334
358
  /**