uql-orm 0.104.0 → 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 +45 -41
  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,28 +1,39 @@
1
1
  import { isVectorIndexType } from '../../type/index.js';
2
2
  import { fulltextConfig } from '../../util/dialect.util.js';
3
+ import { jsonPathKeys } from '../../util/field.util.js';
4
+ import { isElementsType } from '../../util/indexEntry.util.js';
3
5
  import { memberSource, quoted, sqlTag } from './sourceLiteral.js';
4
6
  /**
5
- * The options each field of an index entry writes into `@Index`, in emit order; `satisfies` forces every new
7
+ * The options each field of an index entry writes, in emit order; `satisfies` forces every new
6
8
  * field to be listed. Defaults are skipped: Postgres reports each entry in full (`order: 'asc', nulls: 'last'`
7
9
  * on a plain column), and writing that out would bake its defaults into every entity.
8
10
  */
9
11
  const ENTRY_MODIFIER_SOURCE = {
12
+ type: (entry) => (entry.type === undefined ? [] : [`type: ${valueTypeSource(entry.type)}`]),
10
13
  order: (entry) => (entry.order === 'desc' ? [`order: 'desc'`] : []),
11
14
  opsClass: (entry) => (entry.opsClass ? [`opsClass: ${quoted(entry.opsClass)}`] : []),
12
- length: (entry) => (entry.length === undefined ? [] : [`length: ${entry.length}`]),
15
+ prefixLength: (entry) => (entry.prefixLength === undefined ? [] : [`prefixLength: ${entry.prefixLength}`]),
16
+ charLength: (entry) => (entry.charLength === undefined ? [] : [`charLength: ${entry.charLength}`]),
13
17
  weight: (entry) => ((entry.weight ?? 1) === 1 ? [] : [`weight: ${entry.weight}`]),
14
18
  // Never written: only Postgres reports it, and on every entry.
15
19
  nulls: null,
16
- // Written by `indexEntrySource` as the entry itself, ahead of its modifiers.
20
+ // Written by `entryTargetSource` as the entry itself, ahead of its modifiers.
17
21
  column: null,
22
+ json: null,
23
+ path: null,
18
24
  expression: null,
19
- // Never written: introspection reads a JSON entry back as the expression the engine prints for it.
20
- jsonPath: null,
21
- jsonArray: null,
22
25
  };
23
- /** Each {@link IndexNode} field's `@Index` options, in emit order; `satisfies` forces a new field to be listed. */
26
+ /** A JSON path's value type as source: `Number`, `'decimal'`, or `[String]` for each element. */
27
+ function valueTypeSource(type) {
28
+ if (isElementsType(type)) {
29
+ return `[${valueTypeSource(type[0])}]`;
30
+ }
31
+ return typeof type === 'string' ? quoted(type) : type.name;
32
+ }
33
+ /** Each {@link IndexNode} field's index options, in emit order; `satisfies` forces a new field to be listed. */
24
34
  const INDEX_OPTION_SOURCE = {
25
- name: (index) => (index.name ? [`name: ${quoted(index.name)}`] : []),
35
+ // Written by `buildIndexEntrySource` ahead of the rest, as the bare string when it is alone.
36
+ name: null,
26
37
  unique: (index) => (index.unique ? ['unique: true'] : []),
27
38
  type: (index) => (writesType(index) ? [`type: '${index.type}'`] : []),
28
39
  distance: (index) => (isVectorIndexType(index.type) && index.distance ? [`distance: '${index.distance}'`] : []),
@@ -37,9 +48,9 @@ const INDEX_OPTION_SOURCE = {
37
48
  where: (index) => (index.where ? [`where: ${sqlTag(index.where)}`] : []),
38
49
  include: (index, { param, propertyName }) => {
39
50
  const included = index.include?.map((column) => memberSource(param, propertyName(column))) ?? [];
40
- return included.length ? [`include: (${param}) => [${included.join(', ')}]`] : [];
51
+ return included.length ? [`include: [${included.join(', ')}]`] : [];
41
52
  },
42
- // Written as the decorator's first argument, not as an option.
53
+ // Written as the entry's `columns`, not as an option.
43
54
  entries: null,
44
55
  // Taken from the indexed field, never declared on the index.
45
56
  vectorType: null,
@@ -49,7 +60,7 @@ const INDEX_OPTION_SOURCE = {
49
60
  };
50
61
  /**
51
62
  * Whether to write the index's type. `btree` is skipped: it is every engine's default and reported on every
52
- * index. So is a vector type whose distance introspection could not recover, since `@Index` requires a
63
+ * index. So is a vector type whose distance introspection could not recover, since an index entry requires a
53
64
  * `distance` beside a vector type and would not compile without one.
54
65
  */
55
66
  function writesType(index) {
@@ -57,44 +68,60 @@ function writesType(index) {
57
68
  index.type !== 'btree' &&
58
69
  (!isVectorIndexType(index.type) || index.distance !== undefined));
59
70
  }
60
- function entryModifiers(entry) {
71
+ function entryModifierSources(entry) {
61
72
  return Object.values(ENTRY_MODIFIER_SOURCE).flatMap((source) => source?.(entry) ?? []);
62
73
  }
63
74
  /**
64
- * Whether `@Field({ index })` can carry the whole index. It says only "this column is indexed under
75
+ * Whether `.index()` can carry the whole index. It says only "this column is indexed under
65
76
  * this name", and `unique` beside it that the index is unique, so anything else the index declares - an
66
77
  * expression, a predicate, an access method, stored columns, a stored order - has to be written out as
67
- * an `@Index` instead.
78
+ * an `indexes` entry instead.
68
79
  */
69
80
  export function isPlainFieldIndex(index) {
70
81
  const entries = index.entries;
71
82
  const [entry] = entries;
72
83
  return (entries.length === 1 &&
73
84
  entry !== undefined &&
74
- !entry.expression &&
85
+ entry.column !== undefined &&
75
86
  index.where === undefined &&
76
87
  // Postgres names an access method on every index, so the default one still counts as plain.
77
88
  (index.type === undefined || index.type === 'btree') &&
78
89
  !index.include?.length &&
79
- entryModifiers(entry).length === 0);
90
+ entryModifierSources(entry).length === 0);
80
91
  }
81
92
  /**
82
- * One `@Index((user) => [...])` as source, for an index no `@Field` can express, its columns read off the
83
- * refs `param` names. Emits `sql` for an expression entry, so callers import `sql` when
84
- * {@link indexNeedsRaw} holds.
93
+ * One `@Entity` `indexes` entry as source, `index([user.email], { unique: true })`, for an index no column's
94
+ * `index()` can express, its columns read off the refs `param` names and a lone name written as the bare string.
95
+ * Emits `sql` for an expression entry, so callers import `sql` when {@link indexNeedsRaw} holds.
85
96
  */
86
- export function buildIndexDecoratorSource(index, propertyName, param) {
97
+ export function buildIndexEntrySource(index, propertyName, param) {
87
98
  const context = { param, propertyName };
88
99
  const entries = index.entries.map((entry) => indexEntrySource(entry, context)).join(', ');
89
100
  const options = Object.values(INDEX_OPTION_SOURCE).flatMap((source) => source?.(index, context) ?? []);
90
- return `@Index((${param}) => [${entries}]${options.length > 0 ? `, { ${options.join(', ')} }` : ''})`;
101
+ const name = index.name ? quoted(index.name) : undefined;
102
+ if (name !== undefined && options.length === 0) {
103
+ return `index([${entries}], ${name})`;
104
+ }
105
+ const written = name === undefined ? options : [`name: ${name}`, ...options];
106
+ return written.length ? `index([${entries}], { ${written.join(', ')} })` : `index([${entries}])`;
91
107
  }
92
- /** Whether emitting this index needs `sql` imported alongside `Index`. */
108
+ /** Whether emitting this index needs `sql` imported. */
93
109
  export function indexNeedsRaw(index) {
94
- return Boolean(index.where) || index.entries.some((entry) => entry.expression);
110
+ return Boolean(index.where) || index.entries.some((entry) => entry.expression !== undefined);
111
+ }
112
+ function indexEntrySource(entry, context) {
113
+ const target = entryTargetSource(entry, context);
114
+ const modifiers = entryModifierSources(entry);
115
+ return modifiers.length === 0 ? target : `{ column: ${target}, ${modifiers.join(', ')} }`;
95
116
  }
96
- function indexEntrySource(entry, { param, propertyName }) {
97
- const column = entry.expression ? sqlTag(entry.column) : memberSource(param, propertyName(entry.column));
98
- const modifiers = entryModifiers(entry);
99
- return modifiers.length === 0 ? column : `{ column: ${column}, ${modifiers.join(', ')} }`;
117
+ /** What an entry indexes as source: a member, a JSON path read along one, or `sql`. */
118
+ function entryTargetSource(entry, { param, propertyName }) {
119
+ if (entry.expression !== undefined) {
120
+ return sqlTag(entry.expression);
121
+ }
122
+ if (entry.column !== undefined) {
123
+ return memberSource(param, propertyName(entry.column));
124
+ }
125
+ const keys = entry.path ? jsonPathKeys(entry.path) : [];
126
+ return keys.reduce((source, key) => memberSource(source, key), memberSource(param, propertyName(entry.json)));
100
127
  }
@@ -54,8 +54,8 @@ const storedLiteral = (value, dialect) => typeof value === 'boolean' && dialect.
54
54
  * compares equal and `generate:from-db` writes it by name; any other SQL is kept as it is.
55
55
  */
56
56
  export function knownDefault(expression, dialect) {
57
- const name = SQL_VALUE_NAMES.find((kind) => dialect.sqlValues[kind] !== undefined && sameDefault(new SqlExpression(kind), expression, dialect));
58
- return name ? new SqlExpression(name) : expression;
57
+ const name = SQL_VALUE_NAMES.find((kind) => dialect.sqlValues[kind] !== undefined && sameDefault(SqlExpression.named(kind), expression, dialect));
58
+ return name ? SqlExpression.named(name) : expression;
59
59
  }
60
60
  /**
61
61
  * Normalizes what engines reprint differently in SQL: it lowercases, collapses spacing, and strips wrapping
@@ -92,16 +92,17 @@ function defaultLiteral(value, dialect, columnType) {
92
92
  return dialect.escape(typeof value === 'object' && !(value instanceof Date) ? JSON.stringify(value) : value);
93
93
  }
94
94
  /** A raw expression's own SQL, else the engine's spelling of the value it names. */
95
- function expressionSql({ kind, sql }, dialect, columnType) {
96
- if (sql !== undefined) {
97
- return sql;
95
+ function expressionSql(expression, dialect, columnType) {
96
+ if (expression.kind === 'sql') {
97
+ return expression.sql;
98
98
  }
99
+ const { kind } = expression;
99
100
  const { preciseTypes } = DIALECT_DEFAULTS[dialect.dialectName];
100
101
  if (kind === 'currentTimestamp' && preciseTypes) {
101
102
  const precision = columnType === undefined ? undefined : preciseTypes.exec(columnType)?.[1];
102
103
  return precision ? `CURRENT_TIMESTAMP(${precision})` : 'CURRENT_TIMESTAMP';
103
104
  }
104
- const spelled = kind === 'sql' ? undefined : dialect.sqlValues[kind];
105
+ const spelled = dialect.sqlValues[kind];
105
106
  if (spelled === undefined) {
106
107
  throw new UqlUsageError(`${dialect.engineName} has no ${kind}; write it as raw SQL this engine accepts`);
107
108
  }
@@ -1,11 +1,12 @@
1
1
  import { type IndexType } from '../../schema/types.js';
2
- import type { IndexFeature, SqlDialectName } from '../../type/index.js';
2
+ import type { DialectName, IndexFeature } from '../../type/index.js';
3
3
  /** What an engine's `CREATE INDEX` can say; an index asking for anything else is refused rather than emitted. */
4
4
  export type IndexCapabilities = {
5
- /** The types its `CREATE INDEX` takes. SQLite's has no `USING`, so every type builds its plain index there. */
6
- readonly types: ReadonlySet<IndexType>;
7
- /** The features it can express, each supported by one engine and a hard error at the server on another. */
8
- readonly features: ReadonlySet<IndexFeature>;
5
+ /**
6
+ * Each type its `CREATE INDEX` takes, with the features it can express on one, each a hard error at the server
7
+ * where it is missing. An untyped index is its `btree`. SQLite's has no `USING`, so every type builds its plain one.
8
+ */
9
+ readonly types: ReadonlyMap<IndexType, ReadonlySet<IndexFeature>>;
9
10
  /**
10
11
  * The types it spells as a keyword of their own (`FULLTEXT INDEX`, `VECTOR INDEX`) rather than as an access
11
12
  * method: one table drives both, so a keyword never also leaks out as a ` USING` the engine has no word for.
@@ -16,5 +17,5 @@ export type IndexCapabilities = {
16
17
  /** Whether `CREATE TABLE` takes a plain index among its definitions, built with the table. */
17
18
  readonly inline: boolean;
18
19
  };
19
- /** Each engine's {@link IndexCapabilities}, total over the SQL engines. */
20
- export declare const INDEX_CAPABILITIES: Readonly<Record<SqlDialectName, IndexCapabilities>>;
20
+ /** Each engine's {@link IndexCapabilities}, total over the engines. */
21
+ export declare const INDEX_CAPABILITIES: Readonly<Record<DialectName, IndexCapabilities>>;
@@ -3,29 +3,31 @@ import { VECTOR_INDEX_TYPES } from '../../type/vector.js';
3
3
  const NONE = new Map();
4
4
  /** A full-text index is its own keyword in the MySQL family: `USING fulltext` is a syntax error there. */
5
5
  const MYSQL_LIKE_KEYWORDS = new Map([['fulltext', 'FULLTEXT INDEX']]);
6
+ /** Each of `types`, expressing the same `features`. */
7
+ function typesWith(types, features) {
8
+ const expressed = new Set(features);
9
+ return new Map(types.map((type) => [type, expressed]));
10
+ }
6
11
  const DECLARE_VECTOR = "; declare type: 'vector' instead";
7
- /** Each engine's {@link IndexCapabilities}, total over the SQL engines. */
12
+ /** Each engine's {@link IndexCapabilities}, total over the engines. */
8
13
  export const INDEX_CAPABILITIES = {
9
14
  /** Postgres 18's `pg_am`, with pgvector's two, and `fulltext`, which builds a `gin` one. */
10
15
  postgres: {
11
- types: new Set(['btree', 'hash', 'gin', 'gist', 'brin', 'hnsw', 'ivfflat', 'fulltext']),
12
- features: new Set(['expression', 'partial', 'nullsOrder', 'opsClass', 'include', 'jsonPath']),
16
+ types: typesWith(['btree', 'hash', 'gin', 'gist', 'brin', 'hnsw', 'ivfflat', 'fulltext'], ['expression', 'partial', 'nullsOrder', 'opsClass', 'include', 'jsonPath']),
13
17
  keywords: NONE,
14
18
  hints: NONE,
15
19
  inline: false,
16
20
  },
17
21
  /** v26.3 answers `hash` and `brin` "unimplemented", `ivfflat` "unrecognized"; no nulls order nor operator class. */
18
22
  cockroachdb: {
19
- types: new Set(['btree', 'gin', 'gist', 'hnsw', 'vector', 'fulltext']),
20
- features: new Set(['expression', 'partial', 'include', 'jsonPath']),
23
+ types: typesWith(['btree', 'gin', 'gist', 'hnsw', 'vector', 'fulltext'], ['expression', 'partial', 'include', 'jsonPath']),
21
24
  keywords: new Map([['vector', 'VECTOR INDEX']]),
22
25
  hints: new Map([['ivfflat', DECLARE_VECTOR]]),
23
26
  inline: true,
24
27
  },
25
28
  /** No vector index: MySQL 26.7 has no distance function outside HeatWave, and `VECTOR INDEX` is MariaDB's. */
26
29
  mysql: {
27
- types: new Set(['btree', 'hash', 'fulltext']),
28
- features: new Set(['expression', 'prefixLength', 'jsonPath', 'jsonArray']),
30
+ types: typesWith(['btree', 'hash', 'fulltext'], ['expression', 'prefixLength', 'jsonPath', 'jsonArray']),
29
31
  keywords: MYSQL_LIKE_KEYWORDS,
30
32
  hints: new Map(VECTOR_INDEX_TYPES.map((type) => [type, '. Vector search on MySQL needs HeatWave'])),
31
33
  inline: true,
@@ -35,8 +37,7 @@ export const INDEX_CAPABILITIES = {
35
37
  * either. A vector index of its own, `CREATE VECTOR INDEX`, 11.7+.
36
38
  */
37
39
  mariadb: {
38
- types: new Set(['btree', 'hash', 'fulltext', 'vector']),
39
- features: new Set(['prefixLength']),
40
+ types: typesWith(['btree', 'hash', 'fulltext', 'vector'], ['prefixLength']),
40
41
  keywords: new Map([...MYSQL_LIKE_KEYWORDS, ['vector', 'VECTOR INDEX']]),
41
42
  hints: new Map([
42
43
  ['hnsw', DECLARE_VECTOR],
@@ -49,16 +50,28 @@ export const INDEX_CAPABILITIES = {
49
50
  * the rowstore B-tree, since the index built in its place fails on a `VECTOR` or `nvarchar(max)` (Msg 1978).
50
51
  */
51
52
  mssql: {
52
- types: new Set(['btree']),
53
- features: new Set(['partial']),
53
+ types: typesWith(['btree'], ['partial']),
54
54
  keywords: NONE,
55
55
  hints: NONE,
56
56
  inline: false,
57
57
  },
58
58
  /** Every type builds a plain index, so an entity written for Postgres migrates; libSQL's vector is DiskANN. */
59
59
  sqlite: {
60
- types: new Set(INDEX_TYPES),
61
- features: new Set(['expression', 'partial', 'jsonPath']),
60
+ types: typesWith(INDEX_TYPES, ['expression', 'partial', 'jsonPath']),
61
+ keywords: NONE,
62
+ hints: NONE,
63
+ inline: false,
64
+ },
65
+ /**
66
+ * A key spec says a plain key or `'text'`, and Atlas adds its vector search index, which pre-filters on fields
67
+ * instead of a predicate. A path inside a document, or each element of an array there, is a key like any other:
68
+ * a multikey index on an array.
69
+ */
70
+ mongodb: {
71
+ types: new Map([
72
+ ...typesWith(['btree', 'fulltext'], ['partial', 'jsonPath', 'jsonArray', 'fulltextPath']),
73
+ ['vectorSearch', new Set()],
74
+ ]),
62
75
  keywords: NONE,
63
76
  hints: NONE,
64
77
  inline: false,
@@ -1,11 +1,12 @@
1
1
  import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
2
- import type { IndexType } from '../../schema/types.js';
3
- import { type EngineName, type IndexColumnSchema, type IndexFeature, type IndexJsonPath, type IndexSchema } from '../../type/index.js';
2
+ import { type EngineName, type IndexEntry, type IndexSchema } from '../../type/index.js';
3
+ import { type JsonIndexRead } from '../../util/indexEntry.util.js';
4
4
  import { type IndexCapabilities } from './indexCapabilities.js';
5
- /** Refuses an index of a type `types` lacks, `hints` naming what to declare instead. */
6
- export declare function assertIndexType(index: IndexSchema, types: ReadonlySet<IndexType>, engine: EngineName, hints?: ReadonlyMap<IndexType, string>): void;
7
- /** Refuses an index asking for a feature `features` lacks. */
8
- export declare function assertIndexFeatures(index: IndexSchema, features: ReadonlySet<IndexFeature>, engine: EngineName): void;
5
+ /**
6
+ * Refuses an index `capabilities` cannot express: a type it lacks, its hint naming what to declare instead, or a
7
+ * feature that type cannot take, naming the type where another of the engine's can.
8
+ */
9
+ export declare function assertExpressible(index: IndexSchema, capabilities: IndexCapabilities, engine: EngineName): void;
9
10
  /**
10
11
  * `CREATE INDEX` in its portable form, which the SQLite family takes as is; the engines with more override
11
12
  * the fragments. The migrator's own, so no runtime entry carries it.
@@ -23,7 +24,6 @@ export declare class IndexDdl {
23
24
  * `CREATE INDEX`. Never a unique one: CockroachDB makes that a constraint, which `DROP INDEX` refuses.
24
25
  */
25
26
  inlineDefinition(index: IndexSchema): string | undefined;
26
- private assertExpressible;
27
27
  /** What follows the name and access method, in either form: the columns, then what qualifies them. */
28
28
  private indexBody;
29
29
  /** What an index added to a table that has rows needs run after it to serve queries; nothing, mostly. */
@@ -35,20 +35,20 @@ export declare class IndexDdl {
35
35
  /** What the index is over, between the parentheses: a fulltext one's columns as a search matches them, else its entries. */
36
36
  protected indexTarget(index: IndexSchema): string;
37
37
  /** One index entry: what is indexed, its operator class if any, then its stored order. */
38
- protected indexColumn(entry: IndexColumnSchema, index: IndexSchema): string;
38
+ protected indexColumn(entry: IndexEntry<string>, index: IndexSchema): string;
39
39
  /**
40
40
  * A quoted column, optionally prefix-limited, or an expression in its own parentheses - the form
41
41
  * `((lower("email")))` that MySQL requires and Postgres, CockroachDB and SQLite all accept, so one
42
42
  * rendering serves every engine that has expression indexes. A JSON entry is one of those too, its
43
43
  * expression compiled from the path rather than written out by the caller.
44
44
  */
45
- protected indexColumnTarget(entry: IndexColumnSchema): string;
45
+ protected indexColumnTarget(entry: IndexEntry<string>): string;
46
46
  /** The path read the way a query comparing it reads it, which is how the planner matches the two. */
47
- protected jsonPathIndexExpr(escapedColumn: string, json: IndexJsonPath): string;
47
+ protected jsonIndexExpr(escapedColumn: string, json: JsonIndexRead): string;
48
48
  /** Postgres-wire dialects put a vector or user-declared operator class here. */
49
- protected indexColumnOpsClass(_entry: IndexColumnSchema, _index: IndexSchema): string;
49
+ protected indexColumnOpsClass(_entry: IndexEntry<string>, _index: IndexSchema): string;
50
50
  /** `ASC` is every engine's default, so only `DESC` is worth emitting. */
51
- protected indexColumnOrder(entry: IndexColumnSchema): string;
51
+ protected indexColumnOrder(entry: IndexEntry<string>): string;
52
52
  /** ` INCLUDE (...)`: non-key columns stored for index-only scans. Postgres-wire only. */
53
53
  protected indexInclude(_index: IndexSchema): string;
54
54
  /** The metric this engine's vector index names for the index's distance, refusing a distance it has none for. */
@@ -58,7 +58,7 @@ export declare class IndexDdl {
58
58
  /** What trails the columns: pgvector's ` WITH (m = ...)`, MySQL's ` USING btree`, MariaDB's ` M=8`. */
59
59
  protected indexTuning(_index: IndexSchema): string;
60
60
  /**
61
- * The partial-index predicate. Engines without one reject the index in {@link assertIndexFeatures}
61
+ * The partial-index predicate. Engines without one reject the index in {@link assertExpressible}
62
62
  * rather than reaching here: silently widening a partial unique index changes which rows the
63
63
  * database accepts.
64
64
  */
@@ -2,6 +2,7 @@ import { jsonTypeMode } from '../../dialect/jsonSql.js';
2
2
  import { INDEX_FEATURE_LABELS, } from '../../type/index.js';
3
3
  import { indexDistance, unsupportedVectorMetric } from '../../type/vector.js';
4
4
  import { fulltextConfig, getKeys } from '../../util/index.js';
5
+ import { jsonIndexRead, storedColumns } from '../../util/indexEntry.util.js';
5
6
  import { UqlUsageError } from '../../util/uqlError.js';
6
7
  import { INDEX_CAPABILITIES } from './indexCapabilities.js';
7
8
  /**
@@ -10,26 +11,32 @@ import { INDEX_CAPABILITIES } from './indexCapabilities.js';
10
11
  * whether an index wants it - which is how a JSON path once slipped past the entry comparison.
11
12
  */
12
13
  const INDEX_FEATURE_PROBES = {
13
- expression: (index) => index.entries.some((entry) => entry.expression),
14
- jsonPath: (index) => index.entries.some((entry) => entry.jsonPath),
15
- jsonArray: (index) => index.entries.some((entry) => entry.jsonArray),
14
+ expression: (index) => index.entries.some((entry) => entry.expression !== undefined),
15
+ jsonPath: (index) => index.entries.some((entry) => jsonIndexRead(entry)?.elements === false),
16
+ jsonArray: (index) => index.entries.some((entry) => jsonIndexRead(entry)?.elements === true),
16
17
  partial: (index) => index.where !== undefined,
17
- prefixLength: (index) => index.entries.some((entry) => entry.length !== undefined),
18
+ prefixLength: (index) => index.entries.some((entry) => entry.prefixLength !== undefined),
19
+ fulltextPath: (index) => index.type === 'fulltext' && index.entries.some((entry) => jsonIndexRead(entry) !== undefined),
18
20
  nullsOrder: (index) => index.entries.some((entry) => entry.nulls !== undefined),
19
21
  opsClass: (index) => index.entries.some((entry) => entry.opsClass !== undefined),
20
22
  include: (index) => Boolean(index.include?.length),
21
23
  };
22
- /** Refuses an index of a type `types` lacks, `hints` naming what to declare instead. */
23
- export function assertIndexType(index, types, engine, hints = new Map()) {
24
- if (index.type && !types.has(index.type)) {
25
- throw new UqlUsageError(`${engine} has no ${index.type} index (index "${index.name}")` + (hints.get(index.type) ?? ''));
24
+ /**
25
+ * Refuses an index `capabilities` cannot express: a type it lacks, its hint naming what to declare instead, or a
26
+ * feature that type cannot take, naming the type where another of the engine's can.
27
+ */
28
+ export function assertExpressible(index, capabilities, engine) {
29
+ const { types, hints } = capabilities;
30
+ const type = index.type ?? 'btree';
31
+ const features = types.get(type);
32
+ if (!features) {
33
+ throw new UqlUsageError(`${engine} has no ${type} index (index "${index.name}")` + (hints.get(type) ?? ''));
26
34
  }
27
- }
28
- /** Refuses an index asking for a feature `features` lacks. */
29
- export function assertIndexFeatures(index, features, engine) {
30
35
  for (const feature of getKeys(INDEX_FEATURE_PROBES)) {
31
36
  if (INDEX_FEATURE_PROBES[feature](index) && !features.has(feature)) {
32
- throw new UqlUsageError(`${engine} does not support ${INDEX_FEATURE_LABELS[feature]} (index "${index.name}")`);
37
+ const elsewhere = [...types.values()].some((expressed) => expressed.has(feature));
38
+ throw new UqlUsageError(`${engine} does not support ${INDEX_FEATURE_LABELS[feature]}${elsewhere ? ` on a ${type} index` : ''} ` +
39
+ `(index "${index.name}")`);
33
40
  }
34
41
  }
35
42
  }
@@ -46,7 +53,7 @@ export class IndexDdl {
46
53
  this.capabilities = INDEX_CAPABILITIES[dialect.dialectName];
47
54
  }
48
55
  getCreateIndexStatement(tableName, index, opts = {}) {
49
- this.assertExpressible(index);
56
+ assertExpressible(index, this.capabilities, this.dialect.engineName);
50
57
  const unique = index.unique ? 'UNIQUE ' : '';
51
58
  const ifNotExists = (opts.ifNotExists ?? this.dialect.features.indexIfNotExists) ? 'IF NOT EXISTS ' : '';
52
59
  return (`CREATE ${unique}${this.indexKeyword(index)} ${ifNotExists}${this.dialect.escapeId(index.name)} ` +
@@ -60,14 +67,9 @@ export class IndexDdl {
60
67
  if (!this.capabilities.inline || index.type || index.unique) {
61
68
  return undefined;
62
69
  }
63
- this.assertExpressible(index);
70
+ assertExpressible(index, this.capabilities, this.dialect.engineName);
64
71
  return `INDEX ${this.dialect.escapeId(index.name)} ${this.indexBody(index)}`;
65
72
  }
66
- assertExpressible(index) {
67
- const { types, features, hints } = this.capabilities;
68
- assertIndexType(index, types, this.dialect.engineName, hints);
69
- assertIndexFeatures(index, features, this.dialect.engineName);
70
- }
71
73
  /** What follows the name and access method, in either form: the columns, then what qualifies them. */
72
74
  indexBody(index) {
73
75
  return `(${this.indexTarget(index)})${this.indexInclude(index)}${this.indexTuning(index)}${this.indexPredicate(index)}`;
@@ -86,9 +88,9 @@ export class IndexDdl {
86
88
  }
87
89
  /** What the index is over, between the parentheses: a fulltext one's columns as a search matches them, else its entries. */
88
90
  indexTarget(index) {
89
- if (index.type === 'fulltext' && !index.entries.some((entry) => entry.expression)) {
90
- const columns = index.entries.map((entry) => this.dialect.escapeId(entry.column));
91
- return this.dialect.textSearchTarget(columns, fulltextConfig(index));
91
+ const columns = index.type === 'fulltext' ? storedColumns(index.entries) : undefined;
92
+ if (columns) {
93
+ return this.dialect.textSearchTarget(columns.map((column) => this.dialect.escapeId(column)), fulltextConfig(index));
92
94
  }
93
95
  return index.entries.map((entry) => this.indexColumn(entry, index)).join(', ');
94
96
  }
@@ -103,17 +105,18 @@ export class IndexDdl {
103
105
  * expression compiled from the path rather than written out by the caller.
104
106
  */
105
107
  indexColumnTarget(entry) {
106
- if (entry.expression) {
107
- return `(${entry.column})`;
108
+ if (entry.expression !== undefined) {
109
+ return `(${entry.expression})`;
108
110
  }
109
- const column = this.dialect.escapeId(entry.column);
110
- if (entry.jsonPath) {
111
- return `(${this.jsonPathIndexExpr(column, entry.jsonPath)})`;
111
+ const json = jsonIndexRead(entry);
112
+ if (json) {
113
+ return `(${this.jsonIndexExpr(this.dialect.escapeId(json.column), json)})`;
112
114
  }
113
- return entry.length === undefined ? column : `${column}(${entry.length})`;
115
+ const column = this.dialect.escapeId(entry.column);
116
+ return entry.prefixLength === undefined ? column : `${column}(${entry.prefixLength})`;
114
117
  }
115
118
  /** The path read the way a query comparing it reads it, which is how the planner matches the two. */
116
- jsonPathIndexExpr(escapedColumn, json) {
119
+ jsonIndexExpr(escapedColumn, json) {
117
120
  return this.dialect.jsonPathExpr(escapedColumn, json.path, jsonTypeMode(json.type));
118
121
  }
119
122
  /** Postgres-wire dialects put a vector or user-declared operator class here. */
@@ -147,7 +150,7 @@ export class IndexDdl {
147
150
  return '';
148
151
  }
149
152
  /**
150
- * The partial-index predicate. Engines without one reject the index in {@link assertIndexFeatures}
153
+ * The partial-index predicate. Engines without one reject the index in {@link assertExpressible}
151
154
  * rather than reaching here: silently widening a partial unique index changes which rows the
152
155
  * database accepts.
153
156
  */
@@ -1,4 +1,5 @@
1
- import type { IndexColumnSchema, IndexJsonPath, IndexSchema } from '../../type/index.js';
1
+ import type { IndexSchema } from '../../type/index.js';
2
+ import type { JsonIndexRead } from '../../util/indexEntry.util.js';
2
3
  import { IndexDdl } from './indexDdl.js';
3
4
  /** `CREATE INDEX ... (cols) USING btree`, plus the types this family spells as a keyword instead. */
4
5
  export declare class MysqlLikeIndexDdl extends IndexDdl {
@@ -12,17 +13,11 @@ export declare class MysqlLikeIndexDdl extends IndexDdl {
12
13
  }
13
14
  export declare class MySqlIndexDdl extends MysqlLikeIndexDdl {
14
15
  /**
15
- * A number as the query reads it. A string as `CHAR(n)` in the collation `->>` returns, which the
16
- * planner strips back to the bare `->>` a query compares; any other collation leaves it unused. A
17
- * boolean compares as JSON, which no key part can hold.
16
+ * A string as `CHAR(n)` in the collation `->>` returns, which the planner strips back to the `->>` a query
17
+ * compares. A boolean compares as JSON, which no key part holds. An array's elements are a multi-valued index,
18
+ * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the document, as `$all` reads it.
18
19
  */
19
- protected jsonPathIndexExpr(escapedColumn: string, json: IndexJsonPath): string;
20
- /**
21
- * A JSON array entry is MySQL's multi-valued index, one key per element: `CAST(col AS CHAR(64) ARRAY)`,
22
- * over the column itself where the array is the whole document, which is what `$all`'s
23
- * `JSON_CONTAINS(col, ?)` is matched against. A `path` indexes the array at that path instead.
24
- */
25
- protected indexColumnTarget(entry: IndexColumnSchema): string;
20
+ protected jsonIndexExpr(escapedColumn: string, json: JsonIndexRead): string;
26
21
  }
27
22
  export declare class MariaIndexDdl extends MysqlLikeIndexDdl {
28
23
  /**
@@ -18,37 +18,27 @@ export class MysqlLikeIndexDdl extends IndexDdl {
18
18
  }
19
19
  export class MySqlIndexDdl extends MysqlLikeIndexDdl {
20
20
  /**
21
- * A number as the query reads it. A string as `CHAR(n)` in the collation `->>` returns, which the
22
- * planner strips back to the bare `->>` a query compares; any other collation leaves it unused. A
23
- * boolean compares as JSON, which no key part can hold.
21
+ * A string as `CHAR(n)` in the collation `->>` returns, which the planner strips back to the `->>` a query
22
+ * compares. A boolean compares as JSON, which no key part holds. An array's elements are a multi-valued index,
23
+ * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the document, as `$all` reads it.
24
24
  */
25
- jsonPathIndexExpr(escapedColumn, json) {
25
+ jsonIndexExpr(escapedColumn, json) {
26
+ if (json.elements) {
27
+ const source = json.path ? this.dialect.jsonPathExpr(escapedColumn, json.path, 'json') : escapedColumn;
28
+ return `CAST(${source} AS ${arrayCastType(json.type, json.charLength)} ARRAY)`;
29
+ }
26
30
  const mode = jsonTypeMode(json.type);
27
31
  if (mode === 'json') {
28
32
  throw new UqlUsageError(`MySQL cannot index the boolean JSON path '${json.path}', which compares as JSON`);
29
33
  }
30
- const expr = super.jsonPathIndexExpr(escapedColumn, json);
34
+ const expr = super.jsonIndexExpr(escapedColumn, json);
31
35
  if (mode === 'numeric') {
32
36
  return expr;
33
37
  }
34
- if (!json.length) {
35
- throw new UqlUsageError(`a MySQL index over the string JSON path '${json.path}' needs a length`);
36
- }
37
- return `CAST(${expr} AS CHAR(${json.length}) CHARACTER SET utf8mb4) COLLATE utf8mb4_bin`;
38
- }
39
- /**
40
- * A JSON array entry is MySQL's multi-valued index, one key per element: `CAST(col AS CHAR(64) ARRAY)`,
41
- * over the column itself where the array is the whole document, which is what `$all`'s
42
- * `JSON_CONTAINS(col, ?)` is matched against. A `path` indexes the array at that path instead.
43
- */
44
- indexColumnTarget(entry) {
45
- const json = entry.jsonArray;
46
- if (!json) {
47
- return super.indexColumnTarget(entry);
38
+ if (!json.charLength) {
39
+ throw new UqlUsageError(`a MySQL index over the string JSON path '${json.path}' needs a charLength`);
48
40
  }
49
- const column = this.dialect.escapeId(entry.column);
50
- const source = json.path ? this.dialect.jsonPathExpr(column, json.path, 'json') : column;
51
- return `(CAST(${source} AS ${arrayCastType(json)} ARRAY))`;
41
+ return `CAST(${expr} AS CHAR(${json.charLength}) CHARACTER SET utf8mb4) COLLATE utf8mb4_bin`;
52
42
  }
53
43
  }
54
44
  export class MariaIndexDdl extends MysqlLikeIndexDdl {
@@ -89,9 +79,8 @@ const ARRAY_CASTS = new Map([
89
79
  ['blob', 'BINARY'],
90
80
  ['bytea', 'BINARY'],
91
81
  ]);
92
- /** The cast an element type compiles to; the sized ones need their length, since it sizes the key. */
93
- function arrayCastType(json) {
94
- const type = json.type;
82
+ /** The cast an element type compiles to; the sized ones need their charLength, since it sizes the key. */
83
+ function arrayCastType(type, charLength) {
95
84
  const cast = ARRAY_CASTS.get(typeof type === 'string' ? type.toLowerCase() : type);
96
85
  if (!cast) {
97
86
  throw new UqlUsageError(`MySQL has no array cast for ${typeof type === 'string' ? type : type.name} elements`);
@@ -99,8 +88,8 @@ function arrayCastType(json) {
99
88
  if (cast !== 'CHAR' && cast !== 'BINARY') {
100
89
  return cast;
101
90
  }
102
- if (!json.length) {
103
- throw new UqlUsageError(`a multi-valued index over ${cast === 'CHAR' ? 'string' : 'binary'} elements needs a length`);
91
+ if (!charLength) {
92
+ throw new UqlUsageError(`a multi-valued index over ${cast === 'CHAR' ? 'string' : 'binary'} elements needs a charLength`);
104
93
  }
105
- return `${cast}(${json.length})`;
94
+ return `${cast}(${charLength})`;
106
95
  }
@@ -1,4 +1,4 @@
1
- import type { IndexColumnSchema, IndexSchema } from '../../type/index.js';
1
+ import type { IndexEntry, IndexSchema } from '../../type/index.js';
2
2
  import { IndexDdl } from './indexDdl.js';
3
3
  /** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
4
4
  export declare class PgIndexDdl extends IndexDdl {
@@ -10,7 +10,7 @@ export declare class PgIndexDdl extends IndexDdl {
10
10
  * lacks rather than build with the default; any other entry takes the class it declares. Stated even
11
11
  * for the default distance: pgvector's own default class is L2, which a cosine search never uses.
12
12
  */
13
- protected indexColumnOpsClass(entry: IndexColumnSchema, index: IndexSchema): string;
13
+ protected indexColumnOpsClass(entry: IndexEntry<string>, index: IndexSchema): string;
14
14
  protected indexInclude(index: IndexSchema): string;
15
15
  protected indexTuning(index: IndexSchema): string;
16
16
  }
@@ -1,11 +1,11 @@
1
- import type { IndexColumnSchema, IndexSchema } from '../../type/index.js';
1
+ import type { IndexEntry, IndexSchema } from '../../type/index.js';
2
2
  import { IndexDdl } from './indexDdl.js';
3
3
  /**
4
4
  * SQLite's `CREATE INDEX`, which names no index type. A vector index is libSQL's DiskANN where the dialect
5
5
  * can index its metric, and a plain index on an engine with none, so an entity written for Postgres migrates.
6
6
  */
7
7
  export declare class SqliteIndexDdl extends IndexDdl {
8
- protected indexColumn(entry: IndexColumnSchema, index: IndexSchema): string;
8
+ protected indexColumn(entry: IndexEntry<string>, index: IndexSchema): string;
9
9
  /** The metric libSQL's index names, or `undefined` where the index is no vector index or the engine has none. */
10
10
  private vectorIndexMetric;
11
11
  }