uql-orm 0.104.1 → 0.105.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 (143) hide show
  1. package/README.md +24 -10
  2. package/dist/browser/uql-browser.min.js +2 -2
  3. package/dist/browser/uql-browser.min.js.map +7 -7
  4. package/dist/dialect/abstractSqlDialect.d.ts +6 -4
  5. package/dist/dialect/abstractSqlDialect.js +35 -32
  6. package/dist/dialect/aliases.d.ts +2 -0
  7. package/dist/dialect/aliases.js +2 -0
  8. package/dist/dialect/jsonSql.js +2 -2
  9. package/dist/dialect/mysqlLikeSqlDialect.d.ts +1 -1
  10. package/dist/dialect/mysqlLikeSqlDialect.js +1 -1
  11. package/dist/dialect/operators.js +2 -4
  12. package/dist/dialect/queryJoins.d.ts +2 -0
  13. package/dist/dialect/vectorSqlDialect.d.ts +1 -1
  14. package/dist/dialect/vectorSqlDialect.js +1 -1
  15. package/dist/entity/column.d.ts +3 -0
  16. package/dist/entity/column.js +3 -0
  17. package/dist/entity/columnOptionsBuilder.d.ts +54 -0
  18. package/dist/entity/columnOptionsBuilder.js +108 -0
  19. package/dist/entity/decorator/bag.d.ts +4 -4
  20. package/dist/entity/decorator/entity.d.ts +2 -19
  21. package/dist/entity/decorator/entity.js +3 -37
  22. package/dist/entity/decorator/members.d.ts +46 -76
  23. package/dist/entity/decorator/members.js +18 -7
  24. package/dist/entity/index.d.ts +2 -1
  25. package/dist/entity/index.js +2 -1
  26. package/dist/entity/metadata/definition.d.ts +10 -24
  27. package/dist/entity/metadata/definition.js +329 -147
  28. package/dist/entity/metadata/schemaFixture/animal.d.ts +54 -0
  29. package/dist/entity/metadata/schemaFixture/animal.js +7 -0
  30. package/dist/entity/metadata/schemaFixture/author.d.ts +140 -0
  31. package/dist/entity/metadata/schemaFixture/author.js +25 -0
  32. package/dist/entity/metadata/schemaFixture/book.d.ts +192 -0
  33. package/dist/entity/metadata/schemaFixture/book.js +22 -0
  34. package/dist/http/query.js +12 -13
  35. package/dist/index.d.ts +2 -2
  36. package/dist/index.js +2 -1
  37. package/dist/mariadb/mariaDialect.js +1 -1
  38. package/dist/mariadb/mariadbQuerier.js +1 -3
  39. package/dist/migrate/builder/columnBuilder.d.ts +20 -68
  40. package/dist/migrate/builder/columnBuilder.js +104 -110
  41. package/dist/migrate/builder/migrationBuilder.d.ts +3 -3
  42. package/dist/migrate/builder/migrationBuilder.js +7 -6
  43. package/dist/migrate/builder/tableBuilder.d.ts +3 -55
  44. package/dist/migrate/builder/tableBuilder.js +88 -204
  45. package/dist/migrate/builder/types.d.ts +52 -151
  46. package/dist/migrate/builder/types.js +0 -6
  47. package/dist/migrate/codegen/entityCodeGenerator.d.ts +2 -2
  48. package/dist/migrate/codegen/entityCodeGenerator.js +24 -24
  49. package/dist/migrate/codegen/fieldOptionsSource.d.ts +3 -1
  50. package/dist/migrate/codegen/fieldOptionsSource.js +35 -34
  51. package/dist/migrate/codegen/indexEntrySource.d.ts +16 -0
  52. package/dist/migrate/codegen/{indexDecoratorSource.js → indexEntrySource.js} +54 -27
  53. package/dist/migrate/ddl/defaultSql.js +7 -6
  54. package/dist/migrate/ddl/indexCapabilities.d.ts +8 -7
  55. package/dist/migrate/ddl/indexCapabilities.js +26 -13
  56. package/dist/migrate/ddl/indexDdl.d.ts +13 -13
  57. package/dist/migrate/ddl/indexDdl.js +33 -30
  58. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +6 -11
  59. package/dist/migrate/ddl/mysqlIndexDdl.js +17 -28
  60. package/dist/migrate/ddl/pgIndexDdl.d.ts +2 -2
  61. package/dist/migrate/ddl/sqliteIndexDdl.d.ts +2 -2
  62. package/dist/migrate/drift/driftDetector.js +2 -2
  63. package/dist/migrate/generator/definitionToNode.d.ts +8 -2
  64. package/dist/migrate/generator/definitionToNode.js +4 -5
  65. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +11 -2
  66. package/dist/migrate/introspection/jsonIndexEntry.d.ts +6 -0
  67. package/dist/migrate/introspection/jsonIndexEntry.js +120 -0
  68. package/dist/migrate/introspection/mysqlIntrospector.d.ts +4 -4
  69. package/dist/migrate/introspection/mysqlIntrospector.js +25 -21
  70. package/dist/migrate/introspection/postgresIntrospector.d.ts +1 -1
  71. package/dist/migrate/introspection/postgresIntrospector.js +3 -4
  72. package/dist/migrate/introspection/sqliteIntrospector.js +24 -9
  73. package/dist/migrate/introspection/tableSchemaAST.js +5 -1
  74. package/dist/migrate/schemaChange.d.ts +3 -3
  75. package/dist/migrate/schemaChange.js +3 -2
  76. package/dist/migrate/schemaGenerator.js +1 -1
  77. package/dist/migrate/storage/databaseStorage.js +4 -4
  78. package/dist/mongodb/mongoDialect.d.ts +33 -36
  79. package/dist/mongodb/mongoDialect.js +118 -32
  80. package/dist/mongodb/mongoIntrospector.d.ts +3 -1
  81. package/dist/mongodb/mongoIntrospector.js +11 -5
  82. package/dist/mongodb/mongoSchemaGenerator.js +35 -27
  83. package/dist/mongodb/mongodbQuerier.d.ts +1 -11
  84. package/dist/mongodb/mongodbQuerier.js +9 -43
  85. package/dist/querier/abstractQuerier.d.ts +0 -1
  86. package/dist/querier/abstractQuerier.js +1 -20
  87. package/dist/querier/keyset.js +3 -3
  88. package/dist/schema/declaredColumn.d.ts +11 -0
  89. package/dist/schema/declaredColumn.js +21 -0
  90. package/dist/schema/indexColumns.d.ts +0 -3
  91. package/dist/schema/indexColumns.js +11 -7
  92. package/dist/schema/indexDifferences.d.ts +10 -5
  93. package/dist/schema/indexDifferences.js +42 -28
  94. package/dist/schema/schemaASTBuilder.js +28 -36
  95. package/dist/schema/schemaASTDiffer.js +8 -4
  96. package/dist/schema/sqlExpression.d.ts +21 -17
  97. package/dist/schema/sqlExpression.js +11 -23
  98. package/dist/type/column.d.ts +328 -0
  99. package/dist/type/column.js +2 -0
  100. package/dist/type/config.d.ts +1 -1
  101. package/dist/type/dialect.d.ts +2 -1
  102. package/dist/type/dialect.js +1 -0
  103. package/dist/type/entity.d.ts +290 -279
  104. package/dist/type/entity.js +6 -1
  105. package/dist/type/index.d.ts +2 -0
  106. package/dist/type/index.js +2 -0
  107. package/dist/type/migration.d.ts +5 -5
  108. package/dist/type/query.d.ts +44 -40
  109. package/dist/type/query.js +2 -3
  110. package/dist/type/queryAggregate.d.ts +22 -12
  111. package/dist/type/querySql.d.ts +20 -4
  112. package/dist/type/querySql.js +27 -9
  113. package/dist/type/schemaEntity.d.ts +190 -0
  114. package/dist/type/schemaEntity.js +1 -0
  115. package/dist/type/utility.d.ts +0 -6
  116. package/dist/type/vector.d.ts +1 -1
  117. package/dist/util/ddlExpression.util.d.ts +12 -13
  118. package/dist/util/ddlExpression.util.js +12 -21
  119. package/dist/util/dialect.util.d.ts +11 -5
  120. package/dist/util/dialect.util.js +31 -37
  121. package/dist/util/field.util.d.ts +10 -9
  122. package/dist/util/field.util.js +14 -10
  123. package/dist/util/fieldOption.util.d.ts +11 -95
  124. package/dist/util/fieldOption.util.js +49 -16
  125. package/dist/util/hook.util.d.ts +2 -14
  126. package/dist/util/hook.util.js +3 -16
  127. package/dist/util/index.d.ts +1 -0
  128. package/dist/util/index.js +1 -0
  129. package/dist/util/indexEntry.util.d.ts +45 -0
  130. package/dist/util/indexEntry.util.js +138 -0
  131. package/dist/util/relationQuery.util.d.ts +0 -1
  132. package/dist/util/relationQuery.util.js +0 -5
  133. package/dist/util/sql.d.ts +10 -7
  134. package/dist/util/sql.js +34 -16
  135. package/dist/util/sql.util.d.ts +4 -5
  136. package/dist/util/sql.util.js +7 -16
  137. package/dist/util/string.util.d.ts +2 -0
  138. package/dist/util/string.util.js +4 -0
  139. package/dist/util/uqlError.d.ts +1 -1
  140. package/dist/util/uqlError.js +1 -1
  141. package/package.json +1 -1
  142. package/skills/uql-orm/SKILL.md +76 -25
  143. package/dist/migrate/codegen/indexDecoratorSource.d.ts +0 -16
@@ -1,6 +1,6 @@
1
1
  import { canonicalToSql } from '../../schema/canonicalType.js';
2
2
  import { diffSchemas, referentialActions } from '../../schema/schemaASTDiffer.js';
3
- import { SqlExpression, writtenDefault } from '../../schema/sqlExpression.js';
3
+ import { SqlExpression, sqlExpressionText, writtenDefault } from '../../schema/sqlExpression.js';
4
4
  /**
5
5
  * Compare an expected schema (from entities) with an actual one (from the database) and report every
6
6
  * way they have drifted apart.
@@ -219,7 +219,7 @@ function relationshipDrift(change) {
219
219
  }
220
220
  /** A default as a report shows it: SQL as its SQL, a JSON document as JSON rather than `[object Object]`. */
221
221
  function shownDefault(value) {
222
- return value == null ? 'NULL' : SqlExpression.isExpression(value) ? String(value) : writtenDefault(value);
222
+ return value == null ? 'NULL' : SqlExpression.isExpression(value) ? sqlExpressionText(value) : writtenDefault(value);
223
223
  }
224
224
  /** Both actions spelled out, so a side that left one unstated reads the same as one that stated the default. */
225
225
  function formatActions(rel) {
@@ -14,10 +14,16 @@ export declare function bareColumn({ index: _index, foreignKey: _foreignKey, enu
14
14
  /**
15
15
  * The index a column-level `index` or `unique` declares, or nothing: a unique column is a unique index.
16
16
  *
17
- * Shared with `TableDefinitionBuilder.build`, which lifts these into the table it is creating: written twice,
17
+ * Shared with `tableBuilder`'s `build`, which lifts these into the table it is creating: written twice,
18
18
  * `addColumn` had no lift at all and silently emitted a column with no index.
19
19
  */
20
- export declare function columnIndex(tableName: string, col: FullColumnDefinition): Pick<IndexSchema, 'name' | 'entries' | 'unique'> | undefined;
20
+ export declare function columnIndex(tableName: string, col: FullColumnDefinition): {
21
+ readonly name: string;
22
+ readonly entries: readonly [{
23
+ readonly column: string;
24
+ }];
25
+ readonly unique: boolean;
26
+ } | undefined;
21
27
  /**
22
28
  * The index that `table.index`, `table.unique` and `createIndex` record. Its entries are normalized, since
23
29
  * an entry left as written reaches the generator as a column named `[object Object]`. An unnamed index is
@@ -1,5 +1,6 @@
1
1
  import { createTableNode, keyOfColumns } from '../../schema/schemaAST.js';
2
- import { declaredIndexName, enumCheck, normalizeIndexColumn, renderIndexColumn, } from '../../util/ddlExpression.util.js';
2
+ import { namedIndex, enumCheck } from '../../util/ddlExpression.util.js';
3
+ import { normalizeIndexColumn, renderIndexColumn } from '../../util/indexEntry.util.js';
3
4
  import { derivedIndexName, splitQualifiedName } from '../../util/sql.util.js';
4
5
  /**
5
6
  * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
@@ -35,7 +36,7 @@ export function bareColumn({ index: _index, foreignKey: _foreignKey, enum: _enum
35
36
  /**
36
37
  * The index a column-level `index` or `unique` declares, or nothing: a unique column is a unique index.
37
38
  *
38
- * Shared with `TableDefinitionBuilder.build`, which lifts these into the table it is creating: written twice,
39
+ * Shared with `tableBuilder`'s `build`, which lifts these into the table it is creating: written twice,
39
40
  * `addColumn` had no lift at all and silently emitted a column with no index.
40
41
  */
41
42
  export function columnIndex(tableName, col) {
@@ -61,11 +62,9 @@ export function indexDefinition(columns, { name, unique = false, ...options } =
61
62
  * from that text the way an entity's is.
62
63
  */
63
64
  export function renderIndexDefinition(table, { uniqueName, ...index }, render) {
64
- const where = index.where && render(index.where);
65
65
  return {
66
66
  ...index,
67
- name: declaredIndexName(index.name, table, index.entries, { unique: uniqueName, where }),
68
- where,
67
+ ...namedIndex(index.name, table, index.entries, () => index.where && render(index.where), uniqueName),
69
68
  entries: index.entries.map((entry) => renderIndexColumn(entry, render)),
70
69
  };
71
70
  }
@@ -1,10 +1,12 @@
1
1
  import { SqlExpression } from '../../schema/sqlExpression.js';
2
2
  import { FOREIGN_KEY_ACTIONS } from '../../schema/types.js';
3
+ import { entryModifiers } from '../../util/indexEntry.util.js';
3
4
  import { cachedIn } from '../../util/object.util.js';
4
5
  import { sql } from '../../util/sql.js';
5
6
  import { isOwnedName } from '../../util/sql.util.js';
6
7
  import { withSqlQuerierForMigrations } from '../acquireQuerierForMigrations.js';
7
8
  import { knownDefault } from '../ddl/defaultSql.js';
9
+ import { readIndexEntry } from './jsonIndexEntry.js';
8
10
  import { renamedTable, tableSchemasToAST } from './tableSchemaAST.js';
9
11
  /** A SQL introspector: an engine reads each part of a table from its catalogue (`get*`), on a {@link TableRowReader}. */
10
12
  export class AbstractSqlSchemaIntrospector {
@@ -76,7 +78,7 @@ export class AbstractSqlSchemaIntrospector {
76
78
  isUnique: unique.has(column.name),
77
79
  })),
78
80
  primaryKey,
79
- indexes,
81
+ indexes: indexes.map((index) => ({ ...index, entries: index.entries.map(readEntry) })),
80
82
  foreignKeys,
81
83
  checks,
82
84
  triggers,
@@ -153,9 +155,16 @@ export class AbstractSqlSchemaIntrospector {
153
155
  return knownDefault(SqlExpression.parenthesized(sql), this.dialect);
154
156
  }
155
157
  }
158
+ /** An entry the engine reports as an expression, read back as the JSON path uql compiled it from where it is one. */
159
+ function readEntry(entry) {
160
+ return entry.expression === undefined ? entry : { ...entryModifiers(entry), ...readIndexEntry(entry.expression) };
161
+ }
156
162
  /** The columns a unique index makes unique alone: over that one plain column, unfiltered. The key's is not among them. */
157
163
  function uniqueColumns(indexes) {
158
- return new Set(indexes.flatMap(({ unique, where, entries }) => unique && !where && entries.length === 1 && !entries[0].expression ? [entries[0].column] : []));
164
+ return new Set(indexes.flatMap(({ unique, where, entries }) => {
165
+ const column = entries.length === 1 ? entries[0].column : undefined;
166
+ return unique && !where && column !== undefined ? [column] : [];
167
+ }));
159
168
  }
160
169
  /** A {@link TableRowReader} over one querier: the same statement is only ever sent once. */
161
170
  function createTableRowReader(querier) {
@@ -0,0 +1,6 @@
1
+ import type { IndexEntry } from '../../type/index.js';
2
+ /**
3
+ * An index entry an engine reports as an expression, read back as the JSON path entry uql compiled it from where it is
4
+ * one (`{ json, path, type, charLength }`), as MongoDB reports a path; the expression where it is anything else.
5
+ */
6
+ export declare function readIndexEntry(expression: string): IndexEntry<string>;
@@ -0,0 +1,120 @@
1
+ import { JSON_KEY_PATTERN } from '../../util/field.util.js';
2
+ /** One token of an index expression as an engine reprints it; anything else leaves the expression unread. */
3
+ const TOKEN = /\s+|'(?:[^']|'')*'|"(?:[^"]|"")+"|`(?:[^`]|``)+`|->>|->|::|[(),=]|\d+|[A-Za-z_][\w$]*/y;
4
+ /** The words uql's JSON path reads reprint as on every engine; any other word is the column, or something uql never wrote. */
5
+ const READ_WORDS = new Set([
6
+ 'array',
7
+ 'as',
8
+ 'case',
9
+ 'cast',
10
+ 'char',
11
+ 'charset',
12
+ 'collate',
13
+ 'datetime',
14
+ 'double',
15
+ 'else',
16
+ 'end',
17
+ 'json_extract',
18
+ 'json_unquote',
19
+ 'jsonb_typeof',
20
+ 'null',
21
+ 'numeric',
22
+ 'real',
23
+ 'signed',
24
+ 'text',
25
+ 'then',
26
+ 'utf8mb4',
27
+ 'utf8mb4_bin',
28
+ 'when',
29
+ ]);
30
+ /** The element types MySQL's `CAST(... AS <type> ARRAY)` reprints, as uql declares them. */
31
+ const ARRAY_TYPES = new Map([
32
+ ['char', String],
33
+ ['signed', Number],
34
+ ['datetime', Date],
35
+ ]);
36
+ const PATH_LITERAL = new RegExp(`^'\\$((?:\\.${JSON_KEY_PATTERN})*)'$`, 'u');
37
+ const KEY_LITERAL = new RegExp(`^'(${JSON_KEY_PATTERN})'$`, 'u');
38
+ /**
39
+ * An index entry an engine reports as an expression, read back as the JSON path entry uql compiled it from where it is
40
+ * one (`{ json, path, type, charLength }`), as MongoDB reports a path; the expression where it is anything else.
41
+ */
42
+ export function readIndexEntry(expression) {
43
+ return jsonIndexEntry(expression) ?? { expression };
44
+ }
45
+ function jsonIndexEntry(expression) {
46
+ const tokens = tokenize(expression);
47
+ if (!tokens) {
48
+ return undefined;
49
+ }
50
+ const then = tokens.findIndex((token) => token.word === 'then');
51
+ const read = then < 0 ? tokens : tokens.slice(then + 1);
52
+ const columns = new Set(tokens.flatMap(identifier));
53
+ const path = pathOf(tokens, read);
54
+ const [json] = columns;
55
+ if (columns.size !== 1 || json === undefined || path === undefined) {
56
+ return undefined;
57
+ }
58
+ const typed = typeOf(read);
59
+ if (!typed) {
60
+ return undefined;
61
+ }
62
+ return { json, ...(path && { path }), ...typed };
63
+ }
64
+ /** The tokens of `expression`, `undefined` where one is no token uql's reads reprint as. */
65
+ function tokenize(expression) {
66
+ const tokens = [];
67
+ TOKEN.lastIndex = 0;
68
+ while (TOKEN.lastIndex < expression.length) {
69
+ const match = TOKEN.exec(expression);
70
+ if (!match) {
71
+ return undefined;
72
+ }
73
+ if (match[0].trim()) {
74
+ tokens.push({ text: match[0], word: /^[A-Za-z_]/.test(match[0]) ? match[0].toLowerCase() : '' });
75
+ }
76
+ }
77
+ return tokens;
78
+ }
79
+ /** The column a token names: a quoted identifier, or a word no read reprints as. */
80
+ function identifier({ text, word }) {
81
+ const quoted = /^(["`])(.*)\1$/s.exec(text);
82
+ if (quoted) {
83
+ return [quoted[2].replaceAll(quoted[1] + quoted[1], quoted[1])];
84
+ }
85
+ return word && !READ_WORDS.has(word) ? [text] : [];
86
+ }
87
+ /**
88
+ * The dotted path the read reaches: a `'$.a.b'` literal (MySQL, SQLite), or Postgres's chain of `-> 'a'` keys, read
89
+ * past a `CASE`'s type test. `undefined` where a literal is anything else, which no read of uql's holds.
90
+ */
91
+ function pathOf(tokens, read) {
92
+ const typeTest = tokens.some((token) => token.word === 'case');
93
+ const keyOf = (all, at) => at > 0 && all[at - 1].text.startsWith('->') ? KEY_LITERAL.exec(all[at].text)?.[1] : undefined;
94
+ const known = tokens.every(({ text }, at) => !text.startsWith("'") ||
95
+ PATH_LITERAL.test(text) ||
96
+ keyOf(tokens, at) !== undefined ||
97
+ (typeTest && text === "'number'"));
98
+ const paths = tokens.flatMap((token) => PATH_LITERAL.exec(token.text)?.[1] ?? []);
99
+ if (!known || paths.length > 1) {
100
+ return undefined;
101
+ }
102
+ return paths.length ? paths[0].slice(1) : read.flatMap((_, at) => keyOf(read, at) ?? []).join('.');
103
+ }
104
+ /** The type and key length a read casts its value to: none for text, a number, a JSON value (a boolean) or each element. */
105
+ function typeOf(read) {
106
+ const words = read.map((token) => token.word);
107
+ const charLength = words.includes('char') ? Number(read[words.indexOf('char') + 2]?.text) : undefined;
108
+ const sized = charLength === undefined ? {} : { charLength };
109
+ const elements = words.indexOf('array');
110
+ if (elements >= 0) {
111
+ const cast = words.slice(0, elements).findLast((word) => ARRAY_TYPES.has(word));
112
+ const type = cast === undefined ? undefined : ARRAY_TYPES.get(cast);
113
+ return type && { type: [type], ...sized };
114
+ }
115
+ if (words.some((word) => word === 'double' || word === 'real' || word === 'numeric')) {
116
+ return { type: Number };
117
+ }
118
+ const asJson = !words.some((word) => word === 'json_extract') && !read.some((token) => token.text === '->>');
119
+ return asJson ? { type: Boolean } : sized;
120
+ }
@@ -18,6 +18,8 @@ export declare class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospect
18
18
  protected tableExistsQuery(tableName: string): QuerySql;
19
19
  protected getColumns(read: TableRowReader, tableName: string): Promise<ReadColumn[]>;
20
20
  protected getIndexes(read: TableRowReader, tableName: string): Promise<IndexSchema[]>;
21
+ /** A functional key part's text, which MariaDB, having none, does not report. */
22
+ protected readonly indexExpressionSql: QuerySql;
21
23
  protected getForeignKeys(read: TableRowReader, tableName: string): Promise<ForeignKeySchema[]>;
22
24
  /** Unnamed: MySQL calls every key `PRIMARY`, and drops one by no name. */
23
25
  protected getPrimaryKey(read: TableRowReader, tableName: string): Promise<PrimaryKeySchema | undefined>;
@@ -27,10 +29,7 @@ export declare class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospect
27
29
  * `_utf8mb4\'x\'`.
28
30
  */
29
31
  protected parseDefaultValue(defaultValue: string | null, extra?: string): unknown;
30
- /**
31
- * A default's SQL, or `undefined` for a literal. MySQL flags a SQL default `DEFAULT_GENERATED` and prints
32
- * it escaped like a literal, with charset introducers on its strings: `lower(_utf8mb4\'A\')`.
33
- */
32
+ /** A default's SQL, or `undefined` for a literal: MySQL flags a SQL default `DEFAULT_GENERATED`. */
34
33
  protected sqlText(defaultValue: string, extra: string): string | undefined;
35
34
  }
36
35
  /**
@@ -51,6 +50,7 @@ export declare class MariadbSchemaIntrospector extends MysqlSchemaIntrospector {
51
50
  protected sqlText(defaultValue: string): string | undefined;
52
51
  /** Whether an index is MariaDB's vector index, and the distance it was built for. */
53
52
  protected readonly indexFacets: ReadonlySet<IndexFacet>;
53
+ protected readonly indexExpressionSql: QuerySql;
54
54
  /**
55
55
  * A vector index's distance is kept only in the table's own definition, ``VECTOR KEY `ix` (`vec`)
56
56
  * `DISTANCE`='cosine'``, and left out there for MariaDB's default, euclidean.
@@ -86,26 +86,30 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
86
86
  const rows = await read(sql `
87
87
  SELECT
88
88
  INDEX_NAME as index_name,
89
- GROUP_CONCAT(COALESCE(COLUMN_NAME, '') ORDER BY SEQ_IN_INDEX) as columns,
89
+ COLUMN_NAME as column_name,
90
+ ${this.indexExpressionSql} as expression,
90
91
  NOT NON_UNIQUE as is_unique,
91
- MAX(INDEX_TYPE) as method
92
+ INDEX_TYPE as method
92
93
  FROM information_schema.STATISTICS
93
94
  WHERE TABLE_SCHEMA = ${this.schemaExpr}
94
95
  AND TABLE_NAME = ${tableName}
95
96
  AND INDEX_NAME != 'PRIMARY'
96
- GROUP BY INDEX_NAME, NON_UNIQUE
97
- ORDER BY INDEX_NAME
97
+ ORDER BY INDEX_NAME, SEQ_IN_INDEX
98
98
  `);
99
- return rows.map((row) => ({
100
- name: row.index_name,
101
- ...(row.method === 'VECTOR' && { type: 'vector' }),
102
- // A functional or multi-valued key part has no `COLUMN_NAME` - the `COALESCE` above keeps its
103
- // place in the list, and it is reported as the expression it is, which is what stops diffing
104
- // from comparing an entry list the server cannot state against the entity's own.
105
- entries: row.columns.split(',').map((column) => (column ? { column } : { column, expression: true })),
106
- unique: Boolean(row.is_unique),
99
+ // One row per key part, ordered by position, so the rows of an index are its entries in order.
100
+ return [...Map.groupBy(rows, (row) => row.index_name)].map(([name, parts]) => ({
101
+ name,
102
+ ...(parts[0].method === 'VECTOR' && { type: 'vector' }),
103
+ // A functional or multi-valued key part has no `COLUMN_NAME`: it is reported as the expression it is, which is
104
+ // what stops diffing from comparing an entry list the server cannot state against the entity's own.
105
+ entries: parts.map(({ column_name, expression }) => column_name === null
106
+ ? { expression: expression === null ? '' : mysqlSqlText(expression) }
107
+ : { column: column_name }),
108
+ unique: Boolean(parts[0].is_unique),
107
109
  }));
108
110
  }
111
+ /** A functional key part's text, which MariaDB, having none, does not report. */
112
+ indexExpressionSql = sql `EXPRESSION`;
109
113
  async getForeignKeys(read, tableName) {
110
114
  const rows = await read(sql `
111
115
  SELECT
@@ -158,21 +162,16 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
158
162
  if (sql !== undefined) {
159
163
  // Any precision here repeats the column's own, which the column type already states.
160
164
  return /^CURRENT_TIMESTAMP(?:\(\d?\))?$/i.test(sql)
161
- ? new SqlExpression('currentTimestamp')
165
+ ? SqlExpression.named('currentTimestamp')
162
166
  : this.sqlDefault(sql);
163
167
  }
164
168
  const literal = introduced ? unescapeMysqlString(introduced[1]) : defaultValue;
165
169
  const quoted = /^'(.*)'$/s.exec(literal);
166
170
  return quoted ? unescapeMysqlString(quoted[1]) : literal;
167
171
  }
168
- /**
169
- * A default's SQL, or `undefined` for a literal. MySQL flags a SQL default `DEFAULT_GENERATED` and prints
170
- * it escaped like a literal, with charset introducers on its strings: `lower(_utf8mb4\'A\')`.
171
- */
172
+ /** A default's SQL, or `undefined` for a literal: MySQL flags a SQL default `DEFAULT_GENERATED`. */
172
173
  sqlText(defaultValue, extra) {
173
- return extra.includes('DEFAULT_GENERATED')
174
- ? unescapeMysqlString(defaultValue).replace(/(?<![\w'])_[a-z0-9]+(?=')/gi, '')
175
- : undefined;
174
+ return extra.includes('DEFAULT_GENERATED') ? mysqlSqlText(defaultValue) : undefined;
176
175
  }
177
176
  }
178
177
  const TIMESTAMP_TYPES = new Set(['datetime', 'timestamp']);
@@ -203,6 +202,7 @@ export class MariadbSchemaIntrospector extends MysqlSchemaIntrospector {
203
202
  }
204
203
  /** Whether an index is MariaDB's vector index, and the distance it was built for. */
205
204
  indexFacets = new Set(['vector', 'distance']);
205
+ indexExpressionSql = sql `NULL`;
206
206
  /**
207
207
  * A vector index's distance is kept only in the table's own definition, ``VECTOR KEY `ix` (`vec`)
208
208
  * `DISTANCE`='cosine'``, and left out there for MariaDB's default, euclidean.
@@ -223,7 +223,7 @@ export class MariadbSchemaIntrospector extends MysqlSchemaIntrospector {
223
223
  }
224
224
  const line = lines.find((it) => it.includes(`VECTOR KEY \`${index.name}\``));
225
225
  const metric = line?.match(/`DISTANCE`='(\w+)'/)?.[1] ?? 'euclidean';
226
- return { ...index, distance: this.dialect.indexedDistance(metric) };
226
+ return { ...index, distance: this.dialect.distanceOfMetric(metric) };
227
227
  });
228
228
  }
229
229
  async getColumns(read, tableName) {
@@ -240,3 +240,7 @@ export class MariadbSchemaIntrospector extends MysqlSchemaIntrospector {
240
240
  return columns.map((column) => jsonColumns.has(column.name) ? { ...column, type: 'JSON', length: undefined } : column);
241
241
  }
242
242
  }
243
+ /** SQL as MySQL's catalogue prints it, escaped like a literal, with charset introducers on its strings: `lower(_utf8mb4\'A\')`. */
244
+ function mysqlSqlText(text) {
245
+ return unescapeMysqlString(text).replace(/(?<![\w'])_[a-z0-9]+(?=')/gi, '');
246
+ }
@@ -40,7 +40,7 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
40
40
  *
41
41
  * The key's index and an `EXCLUDE`'s are left out. A `UNIQUE` constraint's index stays, as SQL Server
42
42
  * and the MySQL family report theirs: the diff reads one over a single column as that column's
43
- * uniqueness, and one over several as the unique `@Index` it is.
43
+ * uniqueness, and one over several as the unique index it is.
44
44
  */
45
45
  protected getIndexes(read: TableRowReader, tableName: string): Promise<IndexSchema[]>;
46
46
  /** Whether an entry sorts nulls first, which Postgres states on every entry. */
@@ -118,7 +118,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
118
118
  *
119
119
  * The key's index and an `EXCLUDE`'s are left out. A `UNIQUE` constraint's index stays, as SQL Server
120
120
  * and the MySQL family report theirs: the diff reads one over a single column as that column's
121
- * uniqueness, and one over several as the unique `@Index` it is.
121
+ * uniqueness, and one over several as the unique index it is.
122
122
  */
123
123
  async getIndexes(read, tableName) {
124
124
  const rows = await read(sql `
@@ -230,7 +230,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
230
230
  return index;
231
231
  }
232
232
  const opsClass = index.entries.find((entry) => entry.opsClass)?.opsClass;
233
- const distance = this.dialect.indexedDistance(opsClass ? /_([a-z0-9]+)_ops$/.exec(opsClass)?.[1] : 'l2');
233
+ const distance = this.dialect.distanceOfMetric(opsClass ? /_([a-z0-9]+)_ops$/.exec(opsClass)?.[1] : 'l2');
234
234
  const entries = index.entries.map(({ opsClass: _opsClass, ...entry }) => entry);
235
235
  return distance ? { ...index, distance, entries } : index;
236
236
  }
@@ -315,8 +315,7 @@ const TEXT_INDEX_METHODS = new Set(['gin', 'inverted']);
315
315
  */
316
316
  function mapIndexEntry(row) {
317
317
  return {
318
- column: row.entry,
319
- ...(row.is_expression && { expression: true }),
318
+ ...(row.is_expression ? { expression: row.entry } : { column: row.entry }),
320
319
  order: row.descending ? 'desc' : 'asc',
321
320
  ...(row.nulls_first !== null && { nulls: row.nulls_first ? 'first' : 'last' }),
322
321
  ...(row.ops_class && { opsClass: row.ops_class }),
@@ -61,9 +61,10 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
61
61
  // The key's own index ('pk') is left out; a unique constraint's ('u') is reported as every engine reports one.
62
62
  for (const index of list.filter((it) => it.origin !== 'pk')) {
63
63
  const sql = statements.get(index.name) ?? '';
64
- // `PRAGMA index_info` names an expression entry `null`, its text kept only in `sqlite_master.sql`: it is
65
- // reported as the expression it is, as MySQL reports one, and libSQL's vector index is read off that text.
66
- const entries = (await this.getIndexColumns(read, index.name)).map(({ name }) => name === null ? { column: '', expression: true } : { column: name });
64
+ // `PRAGMA index_info` names an expression entry `null`, its text kept only in `sqlite_master.sql`, which is
65
+ // where it is read from, as libSQL's vector index is.
66
+ const written = indexEntries(sql);
67
+ const entries = (await this.getIndexColumns(read, index.name)).map(({ name }, at) => name === null ? { expression: written[at] ?? '' } : { column: name });
67
68
  indexes.push(this.vectorIndex(index.name, sql) ?? {
68
69
  name: index.name,
69
70
  entries,
@@ -110,7 +111,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
110
111
  entries: [{ column }],
111
112
  unique: false,
112
113
  type: 'vector',
113
- distance: this.dialect.indexedDistance(metric),
114
+ distance: this.dialect.distanceOfMetric(metric),
114
115
  };
115
116
  }
116
117
  getIndexColumns(read, indexName) {
@@ -170,16 +171,30 @@ export function generatedExpression(ddl, column) {
170
171
  }
171
172
  /** A `CREATE TABLE` body split at each comma outside any parentheses or quotes: one entry per column or constraint. */
172
173
  function tableEntries(ddl) {
173
- const body = ddl.slice(ddl.indexOf('(') + 1, ddl.lastIndexOf(')'));
174
- const entries = [];
174
+ return topLevelParts(ddl.slice(ddl.indexOf('(') + 1, ddl.lastIndexOf(')')));
175
+ }
176
+ /** A `CREATE INDEX` statement's entries as written, each without its order. */
177
+ function indexEntries(ddl) {
178
+ let open = -1;
179
+ scan(ddl, (char, index) => {
180
+ open = char === '(' ? index : open;
181
+ return open >= 0;
182
+ });
183
+ return open < 0
184
+ ? []
185
+ : topLevelParts(parenthesized(ddl.slice(open))).map((entry) => entry.replace(/\s+(?:ASC|DESC)$/i, ''));
186
+ }
187
+ /** `text` split at each comma outside any parentheses or quotes, each part trimmed. */
188
+ function topLevelParts(text) {
189
+ const parts = [];
175
190
  let start = 0;
176
- scan(body, (char, index, depth) => {
191
+ scan(text, (char, index, depth) => {
177
192
  if (char === ',' && depth === 0) {
178
- entries.push(body.slice(start, index));
193
+ parts.push(text.slice(start, index));
179
194
  start = index + 1;
180
195
  }
181
196
  });
182
- return [...entries, body.slice(start)];
197
+ return [...parts, text.slice(start)].map((part) => part.trim());
183
198
  }
184
199
  /** A partial index's predicate: what follows `WHERE` after its column list, as the statement gave it. */
185
200
  function indexPredicate(sql) {
@@ -1,6 +1,7 @@
1
1
  import { storedType } from '../../schema/canonicalType.js';
2
2
  import { createTableNode, SchemaAST } from '../../schema/schemaAST.js';
3
3
  import { DEFAULT_FOREIGN_KEY_ACTION, } from '../../schema/types.js';
4
+ import { entryColumn } from '../../util/indexEntry.util.js';
4
5
  import { derivedForeignKeyName, qualifyName } from '../../util/sql.util.js';
5
6
  import { renameIndexEntries } from '../schemaChange.js';
6
7
  /** The tables an introspector read, as a {@link SchemaAST}: every table first, so a foreign key reaches one read after it. */
@@ -77,7 +78,10 @@ function addRelationships(ast, nodes, schema, fromTable) {
77
78
  /** An expression has no column to resolve; an entry naming a column the table lacks is dropped, as the entity side does. */
78
79
  function addIndexes(ast, schema, table) {
79
80
  for (const index of schema.indexes ?? []) {
80
- const entries = index.entries.filter((entry) => entry.expression || table.columns.has(entry.column));
81
+ const entries = index.entries.filter((entry) => {
82
+ const column = entryColumn(entry);
83
+ return column === undefined || table.columns.has(column);
84
+ });
81
85
  if (entries.length > 0) {
82
86
  ast.addIndex({ ...index, table, entries });
83
87
  }
@@ -1,4 +1,4 @@
1
- import type { Alteration, Change, ColumnSchema, IndexColumnSchema, SchemaDiff } from '../type/index.js';
1
+ import type { Alteration, Change, ColumnSchema, IndexEntry, SchemaDiff } from '../type/index.js';
2
2
  /** Each change's end on `side`, where it has one: what a drop half removes (`from`), or an add half creates (`to`). */
3
3
  export declare function sides<T>(changes: readonly Change<T>[] | undefined, side: 'from' | 'to'): T[];
4
4
  /** What the changes add: each `to` with no `from`. */
@@ -35,5 +35,5 @@ export declare function nonEmpty<T>(items: readonly T[]): readonly T[] | undefin
35
35
  * either way, so a key, index or foreign key put back names a renamed column as the rename back leaves it.
36
36
  */
37
37
  export declare function reverseDiff(diff: SchemaDiff): SchemaDiff;
38
- /** Each column entry named by `nameOf`; an expression entry is SQL, left as written. */
39
- export declare function renameIndexEntries(entries: readonly IndexColumnSchema[], nameOf: (column: string) => string): IndexColumnSchema[];
38
+ /** Each entry's column named by `nameOf`; an expression entry is SQL, left as written. */
39
+ export declare function renameIndexEntries(entries: readonly IndexEntry<string>[], nameOf: (column: string) => string): IndexEntry<string>[];
@@ -1,3 +1,4 @@
1
+ import { renamedEntry } from '../util/indexEntry.util.js';
1
2
  /** Each change's end on `side`, where it has one: what a drop half removes (`from`), or an add half creates (`to`). */
2
3
  export function sides(changes, side) {
3
4
  return (changes ?? []).flatMap((change) => {
@@ -93,7 +94,7 @@ export function reverseDiff(diff) {
93
94
  function putBack({ from, to }, restore) {
94
95
  return { from: to, to: from && restore(from) };
95
96
  }
96
- /** Each column entry named by `nameOf`; an expression entry is SQL, left as written. */
97
+ /** Each entry's column named by `nameOf`; an expression entry is SQL, left as written. */
97
98
  export function renameIndexEntries(entries, nameOf) {
98
- return entries.map((entry) => (entry.expression ? entry : { ...entry, column: nameOf(entry.column) }));
99
+ return entries.map((entry) => renamedEntry(entry, nameOf));
99
100
  }
@@ -246,7 +246,7 @@ export class SqlSchemaGenerator {
246
246
  return undefined;
247
247
  }
248
248
  const tableDiff = diffTable(desired, currentTable, this.diffOptions());
249
- const indexes = indexChanges(currentTable.name, desired.indexes, currentTable.indexes, currentTable.indexFacets);
249
+ const indexes = indexChanges(desired.indexes, currentTable);
250
250
  const columns = (tableDiff?.columns ?? []).map(({ from, to, isBreaking }) => ({
251
251
  from: from && this.columnNodeToSchema(from),
252
252
  to: to && this.columnNodeToSchema(to),
@@ -1,5 +1,5 @@
1
1
  import { currentTimestamp, sql } from '../../util/sql.js';
2
- import { TableDefinitionBuilder } from '../builder/tableBuilder.js';
2
+ import { tableBuilder } from '../builder/tableBuilder.js';
3
3
  import { SqlSchemaGenerator } from '../schemaGenerator.js';
4
4
  /** Where executed migrations are recorded when the config does not name a table. */
5
5
  export const DEFAULT_MIGRATIONS_TABLE = 'uql_migrations';
@@ -14,9 +14,9 @@ export const LOCK_RECORD = 'uql/lock';
14
14
  * default. Run under the migration lock, so two runs never race to create it.
15
15
  */
16
16
  export async function createMigrationsTable(querier, tableName) {
17
- const table = new TableDefinitionBuilder(tableName);
18
- table.string('name', { length: 255, primaryKey: true });
19
- table.timestamptz('executed_at', { defaultValue: currentTimestamp });
17
+ const table = tableBuilder(tableName);
18
+ table.string('name').id();
19
+ table.timestamptz('executed_at').default(currentTimestamp);
20
20
  const generator = new SqlSchemaGenerator(querier.dialect);
21
21
  for (const statement of generator.generateCreateTableFromDefinition(table.build(), { ifNotExists: true })) {
22
22
  await querier.run(sql.text(statement));