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
@@ -35,6 +35,8 @@ export declare const SAVEPOINT_PREFIX = "_uql_sp";
35
35
  export declare const CURSOR_ALIAS = "_uql_cursor";
36
36
  /** The SQL Server table variable an `OUTPUT` fills. */
37
37
  export declare const OUTPUT_TABLE = "@_uql_output";
38
+ /** What SQL Server's report of a write's rows reads {@link OUTPUT_TABLE} as, the table its fields are projected off. */
39
+ export declare const OUTPUT_ALIAS = "_uql_output";
38
40
  /** The field a MongoDB `$sort` by `$text` reads `textScore` from where it projects none, taken back out after. */
39
41
  export declare const TEXT_SCORE_ALIAS = "_uql_text_score";
40
42
  /** A relation's row's distance from the vector its `$sort` ranks by, where it projects none. */
@@ -36,6 +36,8 @@ export const SAVEPOINT_PREFIX = `${OWNED_PREFIX}_sp`;
36
36
  export const CURSOR_ALIAS = `${OWNED_PREFIX}_cursor`;
37
37
  /** The SQL Server table variable an `OUTPUT` fills. */
38
38
  export const OUTPUT_TABLE = `@${OWNED_PREFIX}_output`;
39
+ /** What SQL Server's report of a write's rows reads {@link OUTPUT_TABLE} as, the table its fields are projected off. */
40
+ export const OUTPUT_ALIAS = `${OWNED_PREFIX}_output`;
39
41
  /** The field a MongoDB `$sort` by `$text` reads `textScore` from where it projects none, taken back out after. */
40
42
  export const TEXT_SCORE_ALIAS = `${OWNED_PREFIX}_text_score`;
41
43
  /** A relation's row's distance from the vector its `$sort` ranks by, where it projects none. */
@@ -1,4 +1,4 @@
1
- import type { FieldOptions, FieldType } from '../type/index.js';
1
+ import { type FieldOptions, type FieldType } from '../type/index.js';
2
2
  /**
3
3
  * A `'$.a.b'` JSON path literal, and `'$'` for an empty path, the document itself. `suffix` appends an
4
4
  * accessor such as `[#]` or `[*]`.
@@ -57,12 +57,14 @@ export declare function jsonElemExists(from: string, conditions: readonly string
57
57
  */
58
58
  export type JsonAccessMode = 'json' | 'numeric' | 'text';
59
59
  /**
60
- * How a JSON path compares for equality against `value`: `numeric` casts (so `1` equals `1.0`), `json`
61
- * compares JSON values (the only portable boolean), and `text` compares as extracted, also for mixed
62
- * operands.
60
+ * How a JSON path compares for equality against `value`, each operand in the mode `modeOf` reads it, a ref by its
61
+ * column's type: `numeric` casts (so `1` equals `1.0`), `json` compares JSON values (the only portable boolean), and
62
+ * `text` compares as extracted, also for mixed operands.
63
63
  */
64
- export declare function jsonCompareMode(value: unknown): JsonAccessMode;
64
+ export declare function jsonCompareMode(value: unknown, modeOf: (operand: unknown) => JsonAccessMode): JsonAccessMode;
65
+ /** The mode one operand asks for by its type in JavaScript, as {@link jsonTypeMode} reads a declared one. */
66
+ export declare function literalMode(operand: unknown): JsonAccessMode;
65
67
  /** The mode a declared type asks for, {@link jsonCompareMode}'s twin: an index over a path is reached only by a comparison extracting it alike. */
66
- export declare function jsonTypeMode(type: FieldType): JsonAccessMode;
67
- /** Whether `value` asks for more than JSON containment: an operator map anywhere in it. */
68
+ export declare function jsonTypeMode(type: FieldType | undefined): JsonAccessMode;
69
+ /** Whether `value` asks for more than JSON containment: an operator map or SQL, a ref included, anywhere in it. */
68
70
  export declare function holdsOperator(value: unknown): boolean;
@@ -1,3 +1,4 @@
1
+ import { QuerySql } from '../type/index.js';
1
2
  import { isOperatorMap } from '../util/dialect.util.js';
2
3
  import { columnFamily, declaresNotNull, jsonPathKeys } from '../util/field.util.js';
3
4
  import { isOperatorKey, someKey } from '../util/object.util.js';
@@ -75,19 +76,21 @@ export function jsonElemExists(from, conditions, hint) {
75
76
  return `EXISTS (SELECT ${hint && `${hint} `}1 FROM ${from}${where})`;
76
77
  }
77
78
  /**
78
- * How a JSON path compares for equality against `value`: `numeric` casts (so `1` equals `1.0`), `json`
79
- * compares JSON values (the only portable boolean), and `text` compares as extracted, also for mixed
80
- * operands.
79
+ * How a JSON path compares for equality against `value`, each operand in the mode `modeOf` reads it, a ref by its
80
+ * column's type: `numeric` casts (so `1` equals `1.0`), `json` compares JSON values (the only portable boolean), and
81
+ * `text` compares as extracted, also for mixed operands.
81
82
  */
82
- export function jsonCompareMode(value) {
83
+ export function jsonCompareMode(value, modeOf) {
83
84
  const operands = Array.isArray(value) ? value : [value];
84
- if (operands.length === 0) {
85
- return 'text';
86
- }
87
- if (operands.every((operand) => typeof operand === 'boolean')) {
85
+ const mode = operands.length ? modeOf(operands[0]) : 'text';
86
+ return operands.every((operand) => modeOf(operand) === mode) ? mode : 'text';
87
+ }
88
+ /** The mode one operand asks for by its type in JavaScript, as {@link jsonTypeMode} reads a declared one. */
89
+ export function literalMode(operand) {
90
+ if (typeof operand === 'boolean') {
88
91
  return 'json';
89
92
  }
90
- return operands.every((operand) => typeof operand === 'number') ? 'numeric' : 'text';
93
+ return typeof operand === 'number' ? 'numeric' : 'text';
91
94
  }
92
95
  /** The mode a declared type asks for, {@link jsonCompareMode}'s twin: an index over a path is reached only by a comparison extracting it alike. */
93
96
  export function jsonTypeMode(type) {
@@ -97,8 +100,11 @@ export function jsonTypeMode(type) {
97
100
  }
98
101
  return family === 'boolean' ? 'json' : 'text';
99
102
  }
100
- /** Whether `value` asks for more than JSON containment: an operator map anywhere in it. */
103
+ /** Whether `value` asks for more than JSON containment: an operator map or SQL, a ref included, anywhere in it. */
101
104
  export function holdsOperator(value) {
105
+ if (value instanceof QuerySql) {
106
+ return true;
107
+ }
102
108
  if (Array.isArray(value)) {
103
109
  return value.some(holdsOperator);
104
110
  }
@@ -1,5 +1,5 @@
1
- import type { EntityMeta, QueryConflictPaths, QueryContext, QueryPager, TriggerRows, AbstractType, UpdatePayload } from '../type/index.js';
2
- import { AbstractSqlDialect } from './abstractSqlDialect.js';
1
+ import type { EntityMeta, FieldKey, QueryConflictKeys, QueryUpsert, QueryContext, QueryPager, TriggerRows, AbstractType, UpdatePayload } from '../type/index.js';
2
+ import { AbstractSqlDialect, type ConflictUpdate, type SelectTerm } from './abstractSqlDialect.js';
3
3
  /** What SQL Server and Oracle share: paging and upsert spelled as the standard does. */
4
4
  export declare abstract class MergeSqlDialect extends AbstractSqlDialect {
5
5
  readonly escapeIdChar = "\"";
@@ -12,12 +12,12 @@ export declare abstract class MergeSqlDialect extends AbstractSqlDialect {
12
12
  * assignments bind their values before the rows, though they follow them in the SQL; this works only because
13
13
  * SQL Server numbers each placeholder (`@p1`).
14
14
  */
15
- upsert<E>(ctx: QueryContext, entity: AbstractType<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], update?: UpdatePayload<E>): void;
15
+ upsert<E>(ctx: QueryContext, entity: AbstractType<E>, q: QueryUpsert<E>, payload: E | E[], update?: UpdatePayload<E>, returning?: readonly FieldKey<E>[]): readonly SelectTerm[];
16
16
  /** A trigger's upsert as a `MERGE` of the rows it was handed, `SELECT`ed off them as its source. */
17
- protected appendTriggerUpsert<E>(ctx: QueryContext, meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>, entries: readonly [string, unknown][], assignments: string, rows?: TriggerRows): void;
17
+ protected appendTriggerUpsert<E>(ctx: QueryContext, meta: EntityMeta<E>, conflictKeys: QueryConflictKeys<E>, entries: readonly [string, unknown][], found: ConflictUpdate, rows?: TriggerRows): void;
18
18
  /**
19
19
  * The rest of a `MERGE` once its source is written: the source named, matched on the conflict keys, updated
20
- * by `assignments` where it matched, if any, and inserted where it did not.
20
+ * as `found` says where it matched and its condition holds, if it assigns anything, and inserted where it did not.
21
21
  */
22
22
  private mergeMatch;
23
23
  /** The source row through the alias `MERGE` gives it. */
@@ -30,8 +30,6 @@ export declare abstract class MergeSqlDialect extends AbstractSqlDialect {
30
30
  * holds it across both. Empty on Oracle, which does not have the hint and does not need it.
31
31
  */
32
32
  protected readonly mergeTargetHint: string;
33
- /** How the merge reports the row it wrote: SQL Server's `OUTPUT`. Oracle has no such clause on a `MERGE`. */
34
- protected abstract mergeReturning(expression: string): string;
35
33
  /** `MERGE` must be terminated on SQL Server; nothing else here cares. */
36
34
  protected readonly statementTerminator: string;
37
35
  }
@@ -25,39 +25,40 @@ export class MergeSqlDialect extends AbstractSqlDialect {
25
25
  * assignments bind their values before the rows, though they follow them in the SQL; this works only because
26
26
  * SQL Server numbers each placeholder (`@p1`).
27
27
  */
28
- upsert(ctx, entity, conflictPaths, payload, update) {
28
+ upsert(ctx, entity, q, payload, update, returning) {
29
29
  const meta = getMeta(entity);
30
30
  // Before the row source, which is what fills the payload's `onInsert` fields: a column that
31
31
  // exists only there - the generated key, `createdAt` - must not join the update set, or a row
32
32
  // that already existed has both rewritten.
33
- const assignments = this.getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, update);
34
- const shape = this.insertShape(entity, payload);
35
- ctx.append(`MERGE INTO ${this.escapedTableName(meta)}${this.mergeTargetHint} USING (VALUES `);
36
- this.appendValueRows(ctx, shape);
37
- ctx.append(`)${this.mergeMatch(meta, conflictPaths, shape.columns, assignments)}`);
38
- const returning = this.returningIdExpression(meta);
39
- if (returning) {
40
- ctx.append(` ${this.mergeReturning(returning)}`);
41
- }
42
- ctx.append(this.statementTerminator);
33
+ const found = this.conflictUpdate(ctx, entity, q, payload, update);
34
+ return this.reportedWrite(ctx, entity, returning, 'upsert', (afterTarget) => {
35
+ const shape = this.insertShape(entity, payload);
36
+ ctx.append(`MERGE INTO ${this.escapedTableName(meta)}${this.mergeTargetHint} USING (VALUES `);
37
+ this.appendValueRows(ctx, shape);
38
+ ctx.append(`)${this.mergeMatch(meta, q.$conflict, shape.columns, found)}`);
39
+ // A report ends the statement itself, before the read of what it reported.
40
+ ctx.append(afterTarget ? ` ${afterTarget}` : this.statementTerminator);
41
+ });
43
42
  }
44
43
  /** A trigger's upsert as a `MERGE` of the rows it was handed, `SELECT`ed off them as its source. */
45
- appendTriggerUpsert(ctx, meta, conflictPaths, entries, assignments, rows) {
44
+ appendTriggerUpsert(ctx, meta, conflictKeys, entries, found, rows) {
46
45
  ctx.append(`MERGE INTO ${this.escapedTableName(meta)}${this.mergeTargetHint} USING (SELECT `);
47
46
  this.appendTriggerValues(ctx, meta, entries);
48
47
  const columns = entries.map(([key]) => this.escapedColumnName(meta, key));
49
- ctx.append(`${rows ? fromRows(rows) : ''})${this.mergeMatch(meta, conflictPaths, columns, assignments)};`);
48
+ ctx.append(`${rows ? fromRows(rows) : ''})${this.mergeMatch(meta, conflictKeys, columns, found)};`);
50
49
  }
51
50
  /**
52
51
  * The rest of a `MERGE` once its source is written: the source named, matched on the conflict keys, updated
53
- * by `assignments` where it matched, if any, and inserted where it did not.
52
+ * as `found` says where it matched and its condition holds, if it assigns anything, and inserted where it did not.
54
53
  */
55
- mergeMatch(meta, conflictPaths, columns, assignments) {
54
+ mergeMatch(meta, conflictKeys, columns, { assignments, condition }) {
56
55
  const table = this.escapedTableName(meta);
57
56
  const source = this.escapeId(UPSERT_SOURCE_ALIAS, true);
58
- const matched = assignments ? ` WHEN MATCHED THEN UPDATE SET ${assignments}` : '';
57
+ const matched = assignments
58
+ ? ` WHEN MATCHED${condition && ` AND ${condition}`} THEN UPDATE SET ${assignments}`
59
+ : '';
59
60
  const values = columns.map((col) => `${source}.${col}`).join(', ');
60
- return (` AS ${source} (${columns.join(', ')}) ON ${this.mergeOn(meta, conflictPaths, table, source)}${matched}` +
61
+ return (` AS ${source} (${columns.join(', ')}) ON ${this.mergeOn(meta, conflictKeys, table, source)}${matched}` +
61
62
  ` WHEN NOT MATCHED THEN INSERT (${columns.join(', ')}) VALUES (${values})`);
62
63
  }
63
64
  /** The source row through the alias `MERGE` gives it. */
@@ -65,8 +66,8 @@ export class MergeSqlDialect extends AbstractSqlDialect {
65
66
  return `${this.escapeId(UPSERT_SOURCE_ALIAS, true)}.${column}`;
66
67
  }
67
68
  /** `<target>.<col> = <source>.<col>` for every conflict key, which is what makes a row "the same". */
68
- mergeOn(meta, conflictPaths, table, source) {
69
- return getKeys(conflictPaths)
69
+ mergeOn(meta, conflictKeys, table, source) {
70
+ return getKeys(conflictKeys)
70
71
  .map((key) => {
71
72
  const column = this.escapeId(this.resolveColumnName(key, meta.fields[key]));
72
73
  return `${table}.${column} = ${source}.${column}`;
@@ -1,5 +1,5 @@
1
- import type { EntityMeta, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryTextSearchOptions, RowLockFeatures, SqlDialectFeatures, SqlDialectName, SqlValues, AbstractType, UpdatePayload, TransactionOptions } from '../type/index.js';
2
- import { AbstractSqlDialect, type DerivedRelation, type RelationRows, type SelectTerm } from './abstractSqlDialect.js';
1
+ import type { FieldKey, EntityMeta, InsertIdSource, Query, QueryConflictKeys, QueryContext, QueryOptions, QueryTextSearchOptions, QueryUpsert, QueryWhere, RowLockFeatures, SqlDialectFeatures, SqlDialectName, SqlValues, AbstractType, UpdatePayload, TransactionOptions } from '../type/index.js';
2
+ import { AbstractSqlDialect, type ConflictUpdate, type DerivedRelation, type RelationRows, type SelectTerm } from './abstractSqlDialect.js';
3
3
  import { type JsonContainer, type JsonSlot } from './jsonSql.js';
4
4
  /** Declared apart so MariaDB, which has no `FOR UPDATE OF`, can restate that one part of it. */
5
5
  export declare const MYSQL_ROW_LOCKS: RowLockFeatures;
@@ -29,12 +29,18 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
29
29
  readonly booleanLiteral = "integer";
30
30
  readonly sqlValues: SqlValues;
31
31
  readonly insertIdSource: InsertIdSource;
32
- /** `INSERT ... ON DUPLICATE KEY UPDATE`, the assignments bound after the insert, where a `?` reads them. */
33
- upsert<E>(ctx: QueryContext, entity: AbstractType<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], update?: UpdatePayload<E>): void;
34
- protected appendTriggerUpsert<E>(ctx: QueryContext, meta: EntityMeta<E>, _conflictPaths: QueryConflictPaths<E>, entries: readonly [string, unknown][], assignments: string): void;
32
+ /** `INSERT ... ON DUPLICATE KEY UPDATE`, its rows written before what a found row takes, as a `?` reads them. */
33
+ upsert<E>(ctx: QueryContext, entity: AbstractType<E>, q: QueryUpsert<E>, payload: E | E[], update?: UpdatePayload<E>, returning?: readonly FieldKey<E>[]): readonly SelectTerm[];
34
+ /**
35
+ * `ON DUPLICATE KEY UPDATE` takes no `WHERE`, so each assignment holds `where` itself, a `CASE WHEN`. MySQL assigns
36
+ * left to right, a later assignment reading a column as already set: the one column the condition reads is set
37
+ * last, and a condition reading two the update sets is refused, since no order reads both as found.
38
+ */
39
+ protected foundRowUpdate<E>(ctx: QueryContext, entity: AbstractType<E>, entries: readonly [string, unknown][], where: QueryWhere<E> | undefined): ConflictUpdate;
40
+ protected appendTriggerUpsert<E>(ctx: QueryContext, meta: EntityMeta<E>, _conflictKeys: QueryConflictKeys<E>, entries: readonly [string, unknown][], { assignments }: ConflictUpdate): void;
35
41
  /**
36
42
  * `insert` on a duplicate key: `ON DUPLICATE KEY UPDATE` with the new row named, or `INSERT IGNORE` where there
37
- * is nothing to assign. MySQL matches on any unique key, not just the conflict paths, which it cannot name.
43
+ * is nothing to assign. MySQL matches on any unique key, not just the conflict keys, which it cannot name.
38
44
  */
39
45
  private onDuplicateKey;
40
46
  /** The new row through the alias it is given, or `VALUE(col)` where the dialect has no such syntax. */
@@ -1,10 +1,12 @@
1
1
  import { getMeta } from '../entity/index.js';
2
2
  import { textSearchFields } from '../util/index.js';
3
3
  import { escapeMysqlSqlLiteral } from '../util/sqlLiteral.js';
4
+ import { UqlUsageError } from '../util/uqlError.js';
4
5
  import { ANSI_SQL_VALUES, AbstractSqlDialect, isolationSetBefore, } from './abstractSqlDialect.js';
5
6
  import { AGGREGATE_VALUE_ALIAS } from './aliases.js';
6
7
  import { BYTES_PREFIX } from './hydrateColumn.js';
7
8
  import { jsonPath, unlessThen } from './jsonSql.js';
9
+ import { fieldsRead, namesRows } from './operators.js';
8
10
  import { aggregatesRelations } from './queryJoins.js';
9
11
  /**
10
12
  * The largest `BIGINT UNSIGNED`: the row count MySQL's manual gives for "all rows from the offset on",
@@ -29,11 +31,10 @@ export const MYSQL_FEATURES = {
29
31
  serverSideCursors: false,
30
32
  correlatedWrites: true,
31
33
  rowLocks: MYSQL_ROW_LOCKS,
32
- writeReturning: false,
34
+ reportsWrites: [],
33
35
  nullsSortLowest: true,
34
36
  nullsOrdering: 'expression',
35
37
  textScoreIndexes: true,
36
- orderedUpsertReturning: true,
37
38
  orderedJsonAggregates: true,
38
39
  narrowVectorTypes: false,
39
40
  vectorTuningNeedsTransaction: false,
@@ -99,28 +100,49 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
99
100
  // No `RETURNING` support, so multi-row insert IDs are inferred from the header - see the
100
101
  // `innodb_autoinc_lock_mode` caveat on `buildUpdateResult` in `util/sql.util.ts`.
101
102
  insertIdSource = 'firstId';
102
- /** `INSERT ... ON DUPLICATE KEY UPDATE`, the assignments bound after the insert, where a `?` reads them. */
103
- upsert(ctx, entity, conflictPaths, payload, update) {
103
+ /** `INSERT ... ON DUPLICATE KEY UPDATE`, its rows written before what a found row takes, as a `?` reads them. */
104
+ upsert(ctx, entity, q, payload, update, returning) {
104
105
  const meta = getMeta(entity);
105
- const updateCtx = this.createContext();
106
- const assignments = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, update);
106
+ const entries = this.conflictEntries(entity, q, payload, update);
107
107
  const insert = this.buildFragment(ctx, (fragment) => this.appendInsertValues(fragment, entity, payload));
108
- const idReturning = this.insertedIdReturning(meta);
108
+ const { assignments } = this.foundRowUpdate(ctx, entity, entries, q.$where);
109
109
  const rows = Array.isArray(payload) ? payload.length : 1;
110
- const headerId = assignments && this.insertIdSource === 'firstId' && this.upsertReportsIds(meta, rows);
110
+ const headerId = assignments && this.upsertReportsIds(meta, rows);
111
111
  // Qualified: where the rows name the key, the new row's alias carries a column of the same name.
112
112
  const key = headerId ? `${this.escapedTableName(meta)}.${this.escapedColumnName(meta, meta.ids[0])}` : '';
113
113
  const assigned = key ? `${key} = LAST_INSERT_ID(${key}), ${assignments}` : assignments;
114
- ctx.append(`${this.onDuplicateKey(insert, assigned)}${idReturning && ` ${idReturning}`}`);
115
- ctx.pushValue(...updateCtx.values);
114
+ return this.reportedWrite(ctx, entity, returning, 'upsert', () => {
115
+ ctx.append(this.onDuplicateKey(insert, assigned));
116
+ });
116
117
  }
117
- appendTriggerUpsert(ctx, meta, _conflictPaths, entries, assignments) {
118
+ /**
119
+ * `ON DUPLICATE KEY UPDATE` takes no `WHERE`, so each assignment holds `where` itself, a `CASE WHEN`. MySQL assigns
120
+ * left to right, a later assignment reading a column as already set: the one column the condition reads is set
121
+ * last, and a condition reading two the update sets is refused, since no order reads both as found.
122
+ */
123
+ foundRowUpdate(ctx, entity, entries, where) {
124
+ if (!where || !namesRows(where)) {
125
+ return super.foundRowUpdate(ctx, entity, entries, undefined);
126
+ }
127
+ const fields = fieldsRead(getMeta(entity), where);
128
+ const reads = ([key]) => !fields || fields.has(key);
129
+ const read = entries.filter(reads);
130
+ if (read.length > 1) {
131
+ throw new UqlUsageError(`an upsert's $where on ${this.engineName} ${fields ? 'reads' : 'may read, through its SQL,'} ` +
132
+ `${read.map(([key]) => `'${key}'`).join(', ')}, which its update sets too: the engine sets them one by one, ` +
133
+ 'each later one reading the others as already set');
134
+ }
135
+ const guard = (fragment) => this.foundRowCondition(fragment, entity, where);
136
+ const ordered = [...entries.filter((entry) => !reads(entry)), ...read];
137
+ return { assignments: this.foundRowAssignments(ctx, entity, ordered, guard), condition: '' };
138
+ }
139
+ appendTriggerUpsert(ctx, meta, _conflictKeys, entries, { assignments }) {
118
140
  const insert = this.buildFragment(ctx, (fragmentCtx) => this.appendTriggerInsert(fragmentCtx, meta, entries));
119
141
  ctx.append(`${this.onDuplicateKey(insert, assignments)};`);
120
142
  }
121
143
  /**
122
144
  * `insert` on a duplicate key: `ON DUPLICATE KEY UPDATE` with the new row named, or `INSERT IGNORE` where there
123
- * is nothing to assign. MySQL matches on any unique key, not just the conflict paths, which it cannot name.
145
+ * is nothing to assign. MySQL matches on any unique key, not just the conflict keys, which it cannot name.
124
146
  */
125
147
  onDuplicateKey(insert, assignments) {
126
148
  if (!assignments) {
@@ -1,4 +1,4 @@
1
- import { type QueryCompareOp, type QueryGroupOp, type QueryOrderedOp, type QuerySizeComparisonOps, type QueryVectorQuery, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOp } from '../type/index.js';
1
+ import { type EntityMeta, type QueryCompareOp, type QueryGroupOp, type QueryOrderedOp, type QuerySizeComparisonOps, type QueryVectorQuery, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOp } from '../type/index.js';
2
2
  /**
3
3
  * How each grouping operator renders: the operator joining its clauses, and whether the group is
4
4
  * negated (`$not` is `NOT (a AND b)`). Total over {@link QueryGroupOp}.
@@ -34,6 +34,12 @@ export declare function groupClauses<E>(key: QueryGroupOp, val: QueryWhereArray<
34
34
  * none of whose clauses names one render nothing, which a write reads as the whole table.
35
35
  */
36
36
  export declare function namesRows<E>(where: QueryWhere<E> | undefined): boolean;
37
+ /**
38
+ * The fields of `meta` a `$where` reads, through every group: each key, a JSON path by its column, and each ref to
39
+ * one of `meta`'s own. `undefined` where it reads what the query does not show: raw SQL, a field computed by it, a
40
+ * relation or its aggregate, a `$` key.
41
+ */
42
+ export declare function fieldsRead<E>(meta: EntityMeta<E>, where: QueryWhere<E>): ReadonlySet<string> | undefined;
37
43
  /**
38
44
  * A WHERE value as the operators it applies: an array is `$in`, an operator map its own entries, and
39
45
  * anything else `$eq`. Each key is checked here, once, refused as `refusal` where it is no operator.
@@ -1,6 +1,7 @@
1
- import { QuerySql, VECTOR_QUERY_KEYS, } from '../type/index.js';
1
+ import { ColumnRef, QuerySql, REF_ENTITY, REF_KEY, VECTOR_QUERY_KEYS, } from '../type/index.js';
2
2
  import { isOperatorMap } from '../util/dialect.util.js';
3
- import { getKeys, hasKeys, isWhereMap, someKey } from '../util/object.util.js';
3
+ import { aggregateOf, isInlinedExpression } from '../util/field.util.js';
4
+ import { getKeys, hasKeys, isOperatorKey, isRecord, isWhereMap, someKey } from '../util/object.util.js';
4
5
  import { escapeRegExp } from '../util/string.util.js';
5
6
  import { kindOf, UqlUsageError } from '../util/uqlError.js';
6
7
  /**
@@ -38,6 +39,40 @@ export function namesRows(where) {
38
39
  ? groupClauses(key, where[key]).some((clause) => clause instanceof QuerySql || namesRows(clause))
39
40
  : !(isWhereMap(where[key]) && !hasKeys(where[key]))));
40
41
  }
42
+ /**
43
+ * The fields of `meta` a `$where` reads, through every group: each key, a JSON path by its column, and each ref to
44
+ * one of `meta`'s own. `undefined` where it reads what the query does not show: raw SQL, a field computed by it, a
45
+ * relation or its aggregate, a `$` key.
46
+ */
47
+ export function fieldsRead(meta, where) {
48
+ const read = new Set();
49
+ const readsOperand = (value) => {
50
+ if (value instanceof ColumnRef) {
51
+ if ((value[REF_ENTITY] ?? meta.entity) === meta.entity) {
52
+ read.add(value[REF_KEY]);
53
+ }
54
+ return true;
55
+ }
56
+ if (value instanceof QuerySql) {
57
+ return false;
58
+ }
59
+ return !(isRecord(value) || Array.isArray(value)) || Object.values(value).every(readsOperand);
60
+ };
61
+ const readsClause = (clause) => !(clause instanceof QuerySql) &&
62
+ getKeys(clause).every((key) => {
63
+ if (isGroupOp(key)) {
64
+ return groupClauses(key, clause[key]).every(readsClause);
65
+ }
66
+ const [root] = key.split('.');
67
+ const field = meta.fields[root];
68
+ if (isOperatorKey(key) || meta.relations[root] || aggregateOf(field) || (field && isInlinedExpression(field))) {
69
+ return false;
70
+ }
71
+ read.add(root);
72
+ return readsOperand(clause[key]);
73
+ });
74
+ return readsClause(where) ? read : undefined;
75
+ }
41
76
  /**
42
77
  * A WHERE value as the operators it applies: an array is `$in`, an operator map its own entries, and
43
78
  * anything else `$eq`. Each key is checked here, once, refused as `refusal` where it is no operator.
@@ -48,8 +48,8 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
48
48
  vector: (expr: string) => string;
49
49
  blob: (expr: string) => string;
50
50
  };
51
- /** `$N` placeholders carry their own index, so the upsert's assignments need no scratch context. */
52
- protected readonly upsertUpdateBindsInPlace = true;
51
+ /** A typed column as text, which a JSON path's text compares with: Postgres converts neither side of `text = uuid`. */
52
+ protected textOperand(column: string): string;
53
53
  readonly maxBindValues: number;
54
54
  readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
55
55
  /**
@@ -110,8 +110,8 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
110
110
  /** A single key's list binds as one array, whatever its length. */
111
111
  keyListCapacity(keyCount: number): number;
112
112
  /**
113
- * One array parameter, which a context that inlines values has none of: it lists them instead. The
114
- * array takes its type from `operand`, so it needs none of the casts `bind` would give each value.
113
+ * One array parameter, which a context that inlines values has none of, nor a list holding SQL: those list them
114
+ * instead. The array takes its type from `operand`, so it needs none of the casts `bind` gives each value.
115
115
  */
116
116
  protected formatIn(ctx: QueryContext, operand: string, values: unknown[], negate: boolean, bind: (value: unknown) => string): string;
117
117
  escape(value: unknown): string;
@@ -33,11 +33,10 @@ export const PG_FEATURES = {
33
33
  serverSideCursors: true,
34
34
  correlatedWrites: true,
35
35
  rowLocks: { of: true, withWindow: false, placement: 'suffix' },
36
- writeReturning: true,
36
+ reportsWrites: ['insert', 'update', 'delete', 'upsert'],
37
37
  nullsSortLowest: false,
38
38
  nullsOrdering: 'clause',
39
39
  textScoreIndexes: false,
40
- orderedUpsertReturning: true,
41
40
  orderedJsonAggregates: true,
42
41
  narrowVectorTypes: false,
43
42
  vectorTuningNeedsTransaction: true,
@@ -108,8 +107,10 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
108
107
  vector: (expr) => `${expr}::text`,
109
108
  blob: (expr) => `${this.escape(BYTES_PREFIX)} || ENCODE(${expr}, 'hex')`,
110
109
  };
111
- /** `$N` placeholders carry their own index, so the upsert's assignments need no scratch context. */
112
- upsertUpdateBindsInPlace = true;
110
+ /** A typed column as text, which a JSON path's text compares with: Postgres converts neither side of `text = uuid`. */
111
+ textOperand(column) {
112
+ return `${column}::text`;
113
+ }
113
114
  maxBindValues = 65535;
114
115
  vectorMetrics = PG_VECTOR_METRICS;
115
116
  /**
@@ -250,11 +251,11 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
250
251
  return keyCount > 1 ? super.keyListCapacity(keyCount) : Infinity;
251
252
  }
252
253
  /**
253
- * One array parameter, which a context that inlines values has none of: it lists them instead. The
254
- * array takes its type from `operand`, so it needs none of the casts `bind` would give each value.
254
+ * One array parameter, which a context that inlines values has none of, nor a list holding SQL: those list them
255
+ * instead. The array takes its type from `operand`, so it needs none of the casts `bind` gives each value.
255
256
  */
256
257
  formatIn(ctx, operand, values, negate, bind) {
257
- if (!values.length || ctx.inlineValues) {
258
+ if (!values.length || ctx.inlineValues || values.some((value) => value instanceof QuerySql)) {
258
259
  return super.formatIn(ctx, operand, values, negate, bind);
259
260
  }
260
261
  const ph = this.addValue(ctx, values);
@@ -1,4 +1,4 @@
1
1
  export * from './column.js';
2
2
  export * from './decorator/entity.js';
3
3
  export * from './decorator/members.js';
4
- export { defineEntity, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, keyOf, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';
4
+ export { defineEntity, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, keyOf, namesEvery, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';
@@ -1,4 +1,4 @@
1
1
  export * from './column.js';
2
2
  export * from './decorator/entity.js';
3
3
  export * from './decorator/members.js';
4
- export { defineEntity, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, keyOf, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';
4
+ export { defineEntity, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, keyOf, namesEvery, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';
@@ -84,7 +84,7 @@ export declare const Author: import("../../../index.js").RelatedEntity<object &
84
84
  } & {
85
85
  readonly defaultValue: unknown;
86
86
  }, Date>;
87
- }, object> & import("../../../index.js").RelationRow</*elided*/ any> & import("../../../index.js").DerivedRow<{
87
+ }, object> & import("../../../index.js").RelationRow</*elided*/ any> & import("../../../index.js").AggregateRow<{
88
88
  readonly bookCount: () => import("../../../index.js").RelationAggregate<number>;
89
89
  readonly topStock: () => import("../../../index.js").RelationAggregate<number | null>;
90
90
  }>, "m1", object & {
@@ -112,11 +112,11 @@ export declare const Author: import("../../../index.js").RelatedEntity<object &
112
112
  } & {
113
113
  readonly defaultValue: unknown;
114
114
  }, Date>;
115
- }, object> & import("../../../index.js").RelationRow</*elided*/ any> & import("../../../index.js").DerivedRow<{
115
+ }, object> & import("../../../index.js").RelationRow</*elided*/ any> & import("../../../index.js").AggregateRow<{
116
116
  readonly bookCount: () => import("../../../index.js").RelationAggregate<number>;
117
117
  readonly topStock: () => import("../../../index.js").RelationAggregate<number | null>;
118
118
  }>>;
119
- }> & import("../../../index.js").DerivedRow<{}>, "1m", {
119
+ }> & import("../../../index.js").AggregateRow<{}>, "1m", {
120
120
  id: number;
121
121
  title: string;
122
122
  stock: number;
@@ -126,7 +126,7 @@ export declare const Author: import("../../../index.js").RelatedEntity<object &
126
126
  } & {} & {
127
127
  readonly shout: string | null;
128
128
  } & {}>;
129
- }> & import("../../../index.js").DerivedRow<{
129
+ }> & import("../../../index.js").AggregateRow<{
130
130
  readonly bookCount: () => import("../../../index.js").RelationAggregate<number>;
131
131
  readonly topStock: () => import("../../../index.js").RelationAggregate<number | null>;
132
132
  }>, number, {
@@ -93,7 +93,7 @@ export declare const Book: import("../../../index.js").DefinedClass<object & {
93
93
  }, number>;
94
94
  }, object> & {
95
95
  readonly shout: string | null;
96
- } & {} & import("../../../index.js").RelationRow</*elided*/ any> & import("../../../index.js").DerivedRow<{}>, "1m", {
96
+ } & {} & import("../../../index.js").RelationRow</*elided*/ any> & import("../../../index.js").AggregateRow<{}>, "1m", {
97
97
  id: number;
98
98
  title: string;
99
99
  stock: number;
@@ -103,7 +103,7 @@ export declare const Book: import("../../../index.js").DefinedClass<object & {
103
103
  } & {} & {
104
104
  readonly shout: string | null;
105
105
  } & {}>;
106
- }> & import("../../../index.js").DerivedRow<{
106
+ }> & import("../../../index.js").AggregateRow<{
107
107
  readonly bookCount: () => import("../../../index.js").RelationAggregate<number>;
108
108
  readonly topStock: () => import("../../../index.js").RelationAggregate<number | null>;
109
109
  }>, "m1", object & {
@@ -166,7 +166,7 @@ export declare const Book: import("../../../index.js").DefinedClass<object & {
166
166
  }, number>;
167
167
  }, object> & {
168
168
  readonly shout: string | null;
169
- } & {} & import("../../../index.js").RelationRow<any> & import("../../../index.js").DerivedRow<{}>, "1m", {
169
+ } & {} & import("../../../index.js").RelationRow<any> & import("../../../index.js").AggregateRow<{}>, "1m", {
170
170
  id: number;
171
171
  title: string;
172
172
  stock: number;
@@ -176,11 +176,11 @@ export declare const Book: import("../../../index.js").DefinedClass<object & {
176
176
  } & {} & {
177
177
  readonly shout: string | null;
178
178
  } & {}>;
179
- }> & import("../../../index.js").DerivedRow<{
179
+ }> & import("../../../index.js").AggregateRow<{
180
180
  readonly bookCount: () => import("../../../index.js").RelationAggregate<number>;
181
181
  readonly topStock: () => import("../../../index.js").RelationAggregate<number | null>;
182
182
  }>>;
183
- }> & import("../../../index.js").DerivedRow<{}>, number, {
183
+ }> & import("../../../index.js").AggregateRow<{}>, number, {
184
184
  id: number;
185
185
  title: string;
186
186
  stock: number;
@@ -55,6 +55,8 @@ export type KeyedRow<E> = {
55
55
  };
56
56
  /** Whether the row names every column of its primary key, `0` and `''` included. */
57
57
  export declare function namesKey<E>(meta: EntityMeta<E>, row: KeyedRow<E>): boolean;
58
+ /** Whether the row holds a value in each of `keys`, `0` and `''` included: a null one names no row, nor conflicts. */
59
+ export declare function namesEvery<E>(row: KeyedRow<E>, keys: readonly (keyof E)[]): boolean;
58
60
  /** A row's primary key: its value, or a map of every column on a composite, checked at run time. */
59
61
  export declare function idOf<E>(meta: EntityMeta<E>, row: KeyedRow<E>): WrittenId<E>;
60
62
  /**