uql-orm 0.107.3 → 0.108.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 (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 +10 -8
package/dist/util/sql.js CHANGED
@@ -88,15 +88,41 @@ export const SQL_VALUES = {
88
88
  };
89
89
  /**
90
90
  * The fields of `entity` as {@link ColumnRef}s, each rendering inside `sql` as its column: named the way
91
- * the dialect names it, so the naming strategy and `.name()` apply, and qualified by the alias
92
- * in scope. Metadata is read when a ref renders, so the map serves before the fields are registered.
91
+ * the dialect names it, so the naming strategy and `.name()` apply, and qualified by `alias`, or else by the
92
+ * alias in scope. Metadata is read when a ref renders, so the map serves before the fields are registered.
93
93
  */
94
- export function refs(entity) {
95
- return refMap((key) => columnRef(entity, key));
94
+ export function refs(entity, alias) {
95
+ const qualifier = alias === undefined ? undefined : { alias };
96
+ return refMap((key) => columnRef(entity, key, qualifier), () => tableSql(entity, alias));
96
97
  }
97
- /** A map answering each string key with `ref(key)`, typed as the caller's map, whose keys say what it holds. */
98
- function refMap(ref) {
99
- return new Proxy({}, { get: (_, key) => ref(String(key)) });
98
+ /**
99
+ * The table `source` names, an entity or the refs read off one under their alias, `"order" "o"`, for raw SQL
100
+ * reading another table than its statement's: `sql`SELECT ${o.state} FROM ${tableOf(o)}``, `o = refs(Order, 'o')`.
101
+ */
102
+ export function tableOf(source) {
103
+ if (typeof source === 'function') {
104
+ return tableSql(source);
105
+ }
106
+ const table = Reflect.get(source, TABLE);
107
+ if (!(table instanceof QuerySql)) {
108
+ throw new UqlUsageError(`tableOf takes an entity or the refs() read off one, not a definition's refs`);
109
+ }
110
+ return table;
111
+ }
112
+ /** `entity`'s table as its statements name it, under `alias` where one is given. */
113
+ function tableSql(entity, alias) {
114
+ return sql(({ ctx, dialect }) => {
115
+ ctx.append(dialect.tableRef(getMeta(entity), alias).ref);
116
+ });
117
+ }
118
+ /** Where a refs map keeps the table it reads, for {@link tableOf}: a symbol, so no field can shadow it. */
119
+ const TABLE = Symbol('table');
120
+ /**
121
+ * A map answering each string key with `ref(key)`, typed as the caller's map, whose keys say what it holds, and
122
+ * {@link TABLE} with what renders the table where it reads one. No other symbol, so nothing probing it sees more.
123
+ */
124
+ function refMap(ref, table) {
125
+ return new Proxy({}, { get: (_, key) => (key === TABLE ? table?.() : typeof key === 'string' ? ref(key) : undefined) });
100
126
  }
101
127
  /**
102
128
  * The refs a definition's callbacks read: a check's, a computed field's, a predicate's. A member decorator
@@ -162,33 +188,43 @@ function relationAggregate(spec) {
162
188
  * {@link refs} are, so each names its own column wherever it renders, a write to another table included.
163
189
  * Columns only: a relation's aggregate is a subquery, and a trigger fires on one row, not over a table.
164
190
  */
165
- export function rowRefs(entity, qualifier) {
166
- return new Proxy({}, { get: (_, key) => columnRef(entity, String(key), qualifier) });
191
+ export function rowRefs(entity, row) {
192
+ return refMap((key) => columnRef(entity, key, { row }));
167
193
  }
168
194
  /**
169
- * One field as SQL, against its own entity or, read off a definition, the entity rendering it. A
170
- * `qualifier` names the row it reads from, `NEW` or `OLD`, instead of the alias in scope.
195
+ * One field as SQL, against its own entity or, read off a definition, the entity rendering it, read off the
196
+ * alias in scope unless a `qualifier` names another.
171
197
  */
172
198
  export function columnRef(entity, key, qualifier) {
173
199
  return new ColumnRef(key, (opts) => {
174
- const owner = entity ?? opts.entity;
175
- if (!owner) {
176
- throw new UqlUsageError(`'${key}' was read off a definition's refs, so it renders only inside its entity's SQL`);
200
+ const owner = refOwner(entity, key, opts);
201
+ const scope = opts.entity;
202
+ if (!qualifier && scope && scope !== owner && !(scope.prototype instanceof owner)) {
203
+ throw new UqlUsageError(`a ref of '${owner.name}' cannot render against '${scope.name}', the table in scope: ` +
204
+ `read it off its own alias, refs(${owner.name}, 'alias')`);
177
205
  }
178
206
  renderColumn(getMeta(owner), key, { ...opts, entity: owner }, qualifier);
179
- });
207
+ }, entity);
208
+ }
209
+ /** The entity a ref of `key` reads its column of: its own, or, read off a definition, the entity in scope. */
210
+ export function refOwner(entity, key, scope) {
211
+ const owner = entity ?? scope.entity;
212
+ if (!owner) {
213
+ throw new UqlUsageError(`'${key}' was read off a definition's refs, so it renders only inside its entity's SQL`);
214
+ }
215
+ return owner;
180
216
  }
181
217
  /**
182
218
  * A field's column, or the expression an inlined computed one stands for, as a `$where` on it reads it.
183
- * Under a `qualifier` the column is read off that row rather than off the alias in scope, and the row is
219
+ * Under a `qualifier` the column is read off that row or alias rather than off the alias in scope. A row is
184
220
  * written verbatim: it is a record the engine declares, not an identifier to quote and case-fold.
185
221
  */
186
222
  function renderColumn(meta, key, opts, qualifier) {
187
- const scope = qualifier === undefined ? opts : { ...opts, escapedPrefix: `${qualifier}.` };
223
+ const scope = qualifier ? { ...opts, ...qualifiedBy(qualifier, opts) } : opts;
188
224
  const field = meta.fields[key];
189
225
  if (field && isInlinedExpression(field)) {
190
226
  // A relation aggregate is a subquery correlated to a table in scope, and a trigger's row is not one.
191
- if (qualifier !== undefined && aggregateOf(field)) {
227
+ if (qualifier?.row && aggregateOf(field)) {
192
228
  throw new UqlUsageError(`'${entityName(meta)}.${key}' reads a relation, which a trigger's row cannot: it fires on one row, ` +
193
229
  'with no table in scope to correlate a subquery to. Name the columns it is derived from instead.');
194
230
  }
@@ -197,6 +233,10 @@ function renderColumn(meta, key, opts, qualifier) {
197
233
  }
198
234
  scope.ctx.append(scope.escapedPrefix + scope.dialect.escapeId(scope.dialect.columnOf(meta, key), true));
199
235
  }
236
+ /** The prefix a `qualifier` reads columns off, as the render options spell one. */
237
+ function qualifiedBy({ row, alias }, { dialect }) {
238
+ return row ? { escapedPrefix: `${row}.` } : { prefix: alias, escapedPrefix: dialect.escapeId(alias, true, true) };
239
+ }
200
240
  /**
201
241
  * An inlined computed field's expression as every clause splices it: grouped, so a comparison inside cannot
202
242
  * chain with one around it (`a <= b = ?`). A relation aggregate is a subquery, grouped already.
@@ -1,4 +1,4 @@
1
- import { type EntityPredicate, type QueryConflictPaths, type QuerySql, type TriggerWrite, type AbstractType, type UpdatePayload, type WritableKey, type WriteRow } from '../type/index.js';
1
+ import { type EntityPredicate, type QueryUpsert, type QuerySql, type TriggerWrite, type AbstractType, type UpdatePayload, type WritableKey, type WriteRow } from '../type/index.js';
2
2
  /**
3
3
  * A row inserted by a trigger's body, into any table: `insertInto(PostAudit, { postId: newRow.id })`.
4
4
  * Each value is a literal or SQL, a row's ref most often, and every engine renders it, SQL Server's
@@ -6,10 +6,13 @@ import { type EntityPredicate, type QueryConflictPaths, type QuerySql, type Trig
6
6
  */
7
7
  export declare function insertInto<E extends object>(entity: AbstractType<E>, row: WriteRow<E>): QuerySql;
8
8
  /**
9
- * A row inserted by a trigger's body, or what its conflict paths find taking `update` instead, as `upsertOne`
10
- * does: `upsertInto(Tally, { postId: true }, { postId: newRow.id, count: 1 }, { count: { $inc: 1 } })`.
9
+ * A row inserted by a trigger's body, or what `q.$conflict` finds taking `update` instead where it matches
10
+ * `q.$where`, as `upsertOne` does: `upsertInto(Tally, { $conflict: { postId: true } }, { postId: newRow.id, count: 1 },
11
+ * { count: { $inc: 1 } })`.
11
12
  */
12
- export declare function upsertInto<E extends object>(entity: AbstractType<E>, conflictPaths: QueryConflictPaths<E>, row: WriteRow<E>, update?: UpdatePayload<E, QuerySql, WritableKey<E>, never>): QuerySql;
13
+ export declare function upsertInto<E extends object>(entity: AbstractType<E>, q: QueryUpsert<E> & {
14
+ readonly $where?: EntityPredicate<E>;
15
+ }, row: WriteRow<E>, update?: UpdatePayload<E, QuerySql, WritableKey<E>, never>): QuerySql;
13
16
  /** The rows `q.$where` names updated by a trigger's body: `updateTable(Post, { $where: { id: newRow.postId } }, set)`. */
14
17
  export declare function updateTable<E extends object>(entity: AbstractType<E>, q: {
15
18
  readonly $where: EntityPredicate<E>;
@@ -8,11 +8,12 @@ export function insertInto(entity, row) {
8
8
  return written({ kind: 'insert', entity, row });
9
9
  }
10
10
  /**
11
- * A row inserted by a trigger's body, or what its conflict paths find taking `update` instead, as `upsertOne`
12
- * does: `upsertInto(Tally, { postId: true }, { postId: newRow.id, count: 1 }, { count: { $inc: 1 } })`.
11
+ * A row inserted by a trigger's body, or what `q.$conflict` finds taking `update` instead where it matches
12
+ * `q.$where`, as `upsertOne` does: `upsertInto(Tally, { $conflict: { postId: true } }, { postId: newRow.id, count: 1 },
13
+ * { count: { $inc: 1 } })`.
13
14
  */
14
- export function upsertInto(entity, conflictPaths, row, update) {
15
- return written({ kind: 'upsert', entity, conflictPaths, row, update });
15
+ export function upsertInto(entity, q, row, update) {
16
+ return written({ kind: 'upsert', entity, q, row, update });
16
17
  }
17
18
  /** The rows `q.$where` names updated by a trigger's body: `updateTable(Post, { $where: { id: newRow.postId } }, set)`. */
18
19
  export function updateTable(entity, q, set) {
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.107.3",
6
+ "version": "0.108.0",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -43,8 +43,8 @@ The pool's first argument is the driver's own config; set an acquire timeout the
43
43
 
44
44
  Two forms, mixable per entity, producing the same queries and types:
45
45
 
46
- - **Decorators**: a named class type, base classes carrying fields and relations, and column-level foreign keys (`f.references`), so entities may reference each other in any order. Each field is written twice (builder and property), and it needs the TC39 decorator transform.
47
- - **`defineEntity`**: the row type is derived, nothing written twice; no transform, so it fits projects on legacy decorators (NestJS, Angular), and it can be built at run time. Cheaper to type-check. Relations come last, and the row type needs a `type X = InstanceType<typeof X>` alias.
46
+ - **Decorators**: a named class type, and column-level foreign keys (`f.references`), so entities may reference each other in any order. Slightly stricter: a property may be typed narrower than its column (a branded id), and `mappedBy` must name a relation or foreign key at compile time. Each field is written twice (builder and property), and it needs the TC39 decorator transform.
47
+ - **`defineEntity`**: the row type is derived, nothing written twice; no transform, so it fits projects on legacy decorators (NestJS, Angular), and it can be built at run time. Cheaper to type-check. Relations come last, and the row type needs a `type X = InstanceType<typeof X>` alias. A shared set of fields spreads into `fields`.
48
48
 
49
49
  `uql-codemod` cannot convert one form into the other. Details: https://uql-orm.dev/entities/define-entity.md
50
50
 
@@ -88,15 +88,15 @@ export class Post {
88
88
 
89
89
  - A column is a builder: `f.string()`, `f.text()`, `f.uuid()`, `f.number()`, `f.bigint()`, `f.decimal(precision?, scale?)`, `f.boolean()`, `f.date()`, `f.json(schema?)`, `f.jsonb(schema?)`, `f.vector(dimensions)`, `f.enum(values)`, `f.version()`, `f.column(type)` for any other type, and `f.references(() => Target)` for a foreign key typed as the target's key. Only the methods a column's type takes exist: `.length()` is a string's, `.precision()` a number's or a date's.
90
90
  - A column is NOT NULL unless `.nullable()`. Declare a NOT NULL property `!` (`email!: string`), and `?` what an insert may omit: nullable columns (`title?: string | null`), `.eager(false)` and computed fields, relations, and the single-column key and version uql fills. A NOT NULL field a default fills (`.default()`, `.onInsert()`) stays `!` and is listed in the class's `[filledKey]?: 'stock' | 'createdAt'`: inserts may omit it, reads always have it.
91
- - `.default()` takes a value of the field's type, or SQL the database evaluates per row: `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``sql`...` ``. A plain string is always text, `'CURRENT_TIMESTAMP'` included.
91
+ - `.default()` takes a value of the field's type, or SQL the database evaluates per row: `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``sql`...` ``. A plain string is always text, `'CURRENT_TIMESTAMP'` included. A JSON column defaults to a value, `.default({})` or `.default(0)`, never its JSON text (`'{}'`, `'0'` are refused); any other string there is a JSON string.
92
92
  - `Date` is an instant, stored in UTC to the millisecond on every engine. `f.decimal()` is exact text (`price?: string | null`); `f.number().precision(10).scale(2)` opts into a rounding JS number.
93
93
  - A JSON column's property is `Json<T>`: `settings?: Json<{ theme?: string }> | null`. A plain object type reads as a relation, which `$where`, `$sort` and the update operators refuse.
94
- - `mappedBy` and `references` may be left out where only one member fits. `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names the junction entity. `cascade: true` writes related rows in the same transaction; an update replaces a to-many's rows.
94
+ - `mappedBy` and `references` may be left out where only one member fits. `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names the junction entity. `cascade: true` writes related rows with their row, in one transaction on SQL and, on MongoDB, inside one the caller opens; an update replaces a to-many's rows.
95
95
  - A class inherits its base's fields, relations, hooks, filters, indexes, checks and triggers. A base of fields alone needs no `@Entity()`; one declaring entity options but no table is `@Entity({ abstract: true, ... }) abstract class`, which cannot be queried.
96
- - Optimistic lock: `@Field(f.version())` with `[versionKey]?: 'version'` on the class. An update must carry the version it read; a stale one throws `UqlOptimisticLockError`.
96
+ - Optimistic lock: `@Field(f.version())` with `[versionKey]?: 'version'` on the class. An update, and an upsert or save of a row that exists, must carry the version it read; a stale one throws `UqlOptimisticLockError`.
97
97
  - Computed fields are `readonly`: ``@Computed((u) => f.string().as(sql`${u.first} || ' ' || ${u.last}`))``, `.stored()` for a generated column, or a relation aggregate, `@Computed((user) => user.posts.count())`.
98
98
  - Indexes, checks, filters and triggers are `@Entity` options, each entry made by the helper the callback is handed. A partial index's predicate is a query: `indexes: (post, index) => [index([post.authorId], { where: { archived: { $ne: true } } })]`. A JSON path is indexed off the column's ref, `index([user.settings.theme])`: https://uql-orm.dev/entities/indexes.md
99
- - Triggers run in the database: `triggers: (post, trigger) => [trigger({ on: 'afterUpdate', of: [post.status], run })]`, where `run` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`. They skip uql's fills and entity filters. MongoDB has none: https://uql-orm.dev/entities/triggers.md
99
+ - Triggers run in the database: `triggers: (post, trigger) => [trigger({ on: 'afterUpdate', of: [post.status], run })]`, where `run` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`. They skip entity filters and run no JavaScript: an insert fills an `.onInsert()` value or SQL, but an `insertInto` names every required column a callback fills (`.onInsert(() => crypto.randomUUID())`) where no database default does. MongoDB has none: https://uql-orm.dev/entities/triggers.md
100
100
  - Hooks are methods with `this` bound to the payload: `@BeforeInsert()`, `@AfterInsert()`, and the same pairs for update, upsert and delete, plus `@AfterLoad()`. Changes to `this` in a before-hook are written. `upsert*` runs only the upsert pair, and `save*` the upsert pair for a row carrying its key. Each receives `{ querier, onCommit }`: send mail from `onCommit`, never straight from an after-hook.
101
101
  - **MongoDB:** a `f.number()` key left to the database is refused, since MongoDB only generates ObjectIds. Declare it a string, or give it an `.onInsert()` generator.
102
102
 
@@ -139,7 +139,7 @@ export const Book = defineEntity({
139
139
 
140
140
  - Columns are the same builders. No `!`, `?` or brands to write: a `.nullable()` column reads `| null`, a default makes it optional on insert, `f.enum()` gives the literal union.
141
141
  - `defineEntity` takes `name` (the table derives from it), `table`, `schema`, `extends`, `abstract` and `fields`. Every other option is a section chained after it, each called at most once: `computed`, `indexes`, `checks`, `triggers`, `filters`, `hooks`, then `relations` last; only a `filters` reading through relations follows it.
142
- - A relation is a thunk, so entities pointing at each other can sit in any order and file. A foreign key is a plain field that a `manyToOne` names as `references`, checked against the target's key type. `relations`' second callback declares derived fields: aggregates over a to-many, or expressions mixing them with columns.
142
+ - A relation is a thunk, so entities pointing at each other can sit in any order and file. A foreign key is a plain field that a `manyToOne` names as `references`, checked against the target's key type. `relations`' second callback declares aggregate fields: aggregates over a to-many, or expressions mixing them with columns.
143
143
  - A JSON column's payload is any Standard Schema (Zod, Valibot, ArkType), typed by its output. uql never runs it, so a write is not validated.
144
144
  - A hook is a function of the row and `{ querier, onCommit }`. Behaviour is a plain function of the row (`label(author: Author)`): a row reads back as a plain object, so a method would never be there.
145
145
 
@@ -215,14 +215,16 @@ const users = await pool.findMany(User, {
215
215
  ### Writes
216
216
 
217
217
  - Without options, inserts and upserts resolve to ids, updates and deletes to a count. A last argument `{ returning: { id: true } }` resolves to those rows instead.
218
- - `upsertOne(Entity, { email: true }, row, update?)`: a conflicting row takes `update` (an update payload), else the payload but keeping its own key.
218
+ - `upsertOne(Entity, { $conflict: { email: true }, $where? }, row, update?)`: a conflicting row matching `$where` takes `update` (an update payload), else the payload but keeping its own key; one not matching stays as it is. `upsertInto` in a trigger takes the same query. On MySQL and MariaDB, a `$where` may read only one column the update sets.
219
219
  - `updateMany` and `deleteMany` that name no rows (no `$where` holding a value, no `$limit`) throw. Pass `{ unfiltered: true }` to mean the whole table.
220
220
  - Update operators: `{ stock: { $inc: -1 } }` or `$mul`, with NULL counted as 0. A guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. JSON fields take `$pull`, `$set`, `$push`, `$addToSet`, then `$unset`, applied in that order; `$set` and `$unset` take dotted paths and create parents: `settings: { $set: { 'billing.plan': 'pro' } }`.
221
221
 
222
222
  ### Raw SQL and errors
223
223
 
224
224
  - ``pool.all`SELECT ... WHERE id = ${id}` `` for a `SELECT`, ``pool.run`...` `` for a write. Interpolated values bind: a scalar, `null` or a list, never `undefined` or a plain object. `sql` builds a fragment, `sql.join(fragments, ' AND ')` joins them, and `sql.text(s)` runs trusted SQL held in a string: never user input.
225
+ - An operator compares a field with another column through its ref, wherever it takes a value: `{ effectiveTo: { $gt: rate.effectiveFrom } }` off `refs(Rate)` or a check's refs, `$between`, `$in` and `$ne` alike, on every engine, MongoDB included. A JSON path compared with one reads as that column's type. A ref names a column of the entity in scope: one of another entity is refused, and reads off its own alias, `refs(Other, 'o')`.
225
226
  - A condition no operator expresses is a `sql` fragment beside the others, naming columns through `refs()`, never by string: ``const item = refs(Item); $where: { $and: [{ companyId: 1 }, sql`${item.price} * ${item.stock} > ${10000}`] }``. SQL databases only.
227
+ - SQL reading another table names it with `tableOf`, its columns off refs read under an alias, so a rename reaches them: ``const o = refs(Order, 'o'); sql`(SELECT ${o.state} FROM ${tableOf(o)} WHERE ${o.checkoutId} = ${checkout.id} LIMIT 1)` ``. Two aliases read one table twice.
226
228
  - `queryErrorKind(err)` names a failure the same on every engine: `uniqueViolation`, `foreignKeyViolation`, `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage`, `security`. Catch by kind, not by driver code.
227
229
 
228
230
  ## Aggregates