uql-orm 0.106.0 → 0.106.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.
@@ -1,5 +1,5 @@
1
1
  import type { ColumnNode, EnumValues, ForeignKeyAction } from '../../schema/types.js';
2
- import type { IndexEntry, Except, FieldOptions, IndexColumnInput, IndexOptions, IndexSchema, QuerySql } from '../../type/index.js';
2
+ import type { IndexEntry, Except, FieldOptions, IndexColumnInput, IndexOptions } from '../../type/index.js';
3
3
  import type { ForeignKeySchema } from '../../type/migration.js';
4
4
  export type ColumnDefinition = Except<ColumnNode, 'table'>;
5
5
  /**
@@ -20,14 +20,12 @@ export interface FullColumnDefinition extends ColumnDefinition {
20
20
  index?: string | boolean;
21
21
  }
22
22
  /**
23
- * An index as the builder records it, with the entries and options an entity's `indexes` entry takes: its SQL kept as `raw`
24
- * until a generator renders it for the engine the migration runs on.
23
+ * An index as the builder records it: its options as declared, its SQL kept as `raw` until a generator renders it for
24
+ * the engine the migration runs on, and an unnamed one named then, from its predicate as written.
25
25
  */
26
- export type IndexDefinition = Except<IndexSchema, 'name' | 'entries' | 'where'> & {
27
- /** As declared; an unnamed index is named when it is rendered, from its predicate as written. */
28
- readonly name?: string;
26
+ export type IndexDefinition = IndexOptions & {
29
27
  readonly entries: readonly IndexEntry[];
30
- readonly where?: QuerySql;
28
+ readonly unique: boolean;
31
29
  /** Whether an unnamed index takes the `_uk` kind. Only `table.unique` sets it: earlier migrations installed `_uk` there, so `index` keeps `_idx`. */
32
30
  readonly uniqueName?: boolean;
33
31
  };
@@ -34,6 +34,6 @@ export declare function indexDefinition(columns: readonly IndexColumnInput[], {
34
34
  * An index the builder recorded, its SQL rendered by `render` into the text the schema holds, and named
35
35
  * from that text the way an entity's is.
36
36
  */
37
- export declare function renderIndexDefinition(table: string, { uniqueName, ...index }: IndexDefinition, render: (sql: QuerySql) => string): IndexSchema;
37
+ export declare function renderIndexDefinition(table: string, { uniqueName, where, ...index }: IndexDefinition, render: (sql: QuerySql) => string): IndexSchema;
38
38
  /** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
39
39
  export declare function columnForeignKey(col: FullColumnDefinition): ForeignKeySchema | undefined;
@@ -1,6 +1,6 @@
1
1
  import { createTableNode, keyOfColumns } from '../../schema/schemaAST.js';
2
- import { namedIndex, enumCheck } from '../../util/ddlExpression.util.js';
3
- import { normalizeIndexColumn, renderIndexColumn } from '../../util/indexEntry.util.js';
2
+ import { enumCheck, renderIndex } from '../../util/ddlExpression.util.js';
3
+ import { normalizeIndexColumn } from '../../util/indexEntry.util.js';
4
4
  import { derivedIndexName, splitQualifiedName } from '../../util/sql.util.js';
5
5
  /**
6
6
  * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
@@ -61,12 +61,8 @@ export function indexDefinition(columns, { name, unique = false, ...options } =
61
61
  * An index the builder recorded, its SQL rendered by `render` into the text the schema holds, and named
62
62
  * from that text the way an entity's is.
63
63
  */
64
- export function renderIndexDefinition(table, { uniqueName, ...index }, render) {
65
- return {
66
- ...index,
67
- ...namedIndex(index.name, table, index.entries, () => index.where && render(index.where), uniqueName),
68
- entries: index.entries.map((entry) => renderIndexColumn(entry, render)),
69
- };
64
+ export function renderIndexDefinition(table, { uniqueName, where, ...index }, render) {
65
+ return renderIndex(table, index, render, () => where && render(where), uniqueName);
70
66
  }
71
67
  /** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
72
68
  export function columnForeignKey(col) {
@@ -15,4 +15,4 @@ export declare class MongoSchemaIntrospector implements SchemaIntrospector {
15
15
  private withDb;
16
16
  }
17
17
  /** A key as the entity declares it: the field, then the path inside it, so the two compare and name alike. */
18
- export declare function documentEntry(key: string): IndexEntry<string>;
18
+ export declare function documentEntry(key: string): IndexEntry<never>;
@@ -8,7 +8,7 @@ import { sides } from '../migrate/schemaChange.js';
8
8
  import { indexChanges } from '../schema/indexDifferences.js';
9
9
  import { QuerySql, } from '../type/index.js';
10
10
  import { indexDistance, unsupportedVectorMetric } from '../type/vector.js';
11
- import { declaredIndexes, namedIndex } from '../util/ddlExpression.util.js';
11
+ import { declaredIndexes, renderIndex } from '../util/ddlExpression.util.js';
12
12
  import { findVectorIndex, fulltextConfig, fulltextWeights, indexedDistance } from '../util/dialect.util.js';
13
13
  import { entryKeys, entryModifiers, renamedEntry } from '../util/indexEntry.util.js';
14
14
  import { definedEntries, hasKeys } from '../util/object.util.js';
@@ -67,13 +67,10 @@ export class MongoSchemaGenerator extends MongoDialect {
67
67
  const [first] = declared;
68
68
  const vectorKey = options.type === 'vectorSearch' && typeof first?.column === 'string' ? first.column : undefined;
69
69
  const vector = vectorKey === undefined ? undefined : meta.fields[vectorKey];
70
- const named = namedIndex(options.name, collectionName, entries, (label) => where && this.indexFilter(where, meta.entity, label));
70
+ const index = renderIndex(collectionName, { ...options, entries }, refuseSql, (label) => where && this.indexFilter(where, meta.entity, label));
71
71
  return {
72
- ...options,
73
- ...named,
74
- name: vector ? this.vectorSearchIndexName(options.name, documentPath(entries[0])) : named.name,
75
- entries,
76
- unique: options.unique ?? false,
72
+ ...index,
73
+ name: vector ? this.vectorSearchIndexName(options.name, documentPath(entries[0])) : index.name,
77
74
  distance: vectorKey === undefined
78
75
  ? options.distance
79
76
  : indexedDistance(meta, vectorKey, findVectorIndex(meta, vectorKey)),
@@ -1,8 +1,8 @@
1
1
  import { fieldOf, foreignKeysOf, getMeta } from '../entity/metadata/definition.js';
2
- import { declaredIndexes, namedIndex, enumCheck, ownedCheck } from '../util/ddlExpression.util.js';
2
+ import { declaredIndexes, enumCheck, ownedCheck, renderIndex } from '../util/ddlExpression.util.js';
3
3
  import { fulltextWeights, textWeightSteps } from '../util/dialect.util.js';
4
4
  import { isInlinedExpression, isSoleIdField } from '../util/field.util.js';
5
- import { entryColumn, entryColumns, renamedEntry, renderIndexColumn } from '../util/indexEntry.util.js';
5
+ import { entryColumn, entryColumns, renamedEntry } from '../util/indexEntry.util.js';
6
6
  import { definedEntries, entityName } from '../util/object.util.js';
7
7
  import { derivedForeignKeyName, derivedIndexName } from '../util/sql.util.js';
8
8
  import { UqlUsageError } from '../util/uqlError.js';
@@ -176,16 +176,10 @@ function addCompositeIndex(ctx, table, meta, { entries, include, where, ...optio
176
176
  });
177
177
  if (!resolved.length)
178
178
  return;
179
- const named = namedIndex(options.name, table.name, resolved, (label) => where && ctx.compileIndexPredicate(where, meta.entity, label));
180
- ctx.ast.addIndex({
181
- ...options,
182
- ...named,
183
- table,
184
- entries: resolved.map((entry) => renderIndexColumn(entry, (sql) => ctx.compileDdl(sql, meta.entity))),
185
- // An `include` column is named like any other, so a custom naming has to reach it too.
186
- include: include?.map((column) => fieldColumn(ctx, meta, column) ?? column),
187
- unique: options.unique ?? false,
188
- });
179
+ const index = renderIndex(table.name,
180
+ // An `include` column is named like any other, so a custom naming has to reach it too.
181
+ { ...options, entries: resolved, include: include?.map((column) => fieldColumn(ctx, meta, column) ?? column) }, (sql) => ctx.compileDdl(sql, meta.entity), (label) => where && ctx.compileIndexPredicate(where, meta.entity, label));
182
+ ctx.ast.addIndex({ ...index, table });
189
183
  if (ctx.textScoreIndexes) {
190
184
  addTextScoreIndexes(ctx, table, options.type, resolved);
191
185
  }
@@ -5,7 +5,7 @@ import type { FilterOptions, RelationQuery } from './query.js';
5
5
  import type { ColumnRef, JsonPathRef, QuerySql, SqlFor, RelationAggregate } from './querySql.js';
6
6
  import type { QueryWhere } from './queryWhere.js';
7
7
  import type { StandardSchemaV1 } from './standardSchema.js';
8
- import type { AtLeastOne, Except, ExactlyOne, IsEqual, Merge, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, AbstractType, Unpacked, Writable } from './utility.js';
8
+ import type { AtLeastOne, ExactlyOne, IsEqual, Merge, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, AbstractType, Unpacked, Writable } from './utility.js';
9
9
  import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
10
10
  /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
11
11
  export declare const idKey: unique symbol;
@@ -577,21 +577,21 @@ export type HookFunction = {
577
577
  * cosine; a `fulltext` one may name the text-search `config` it parses with; and any other index neither.
578
578
  */
579
579
  export type IndexTypeOptions = {
580
- type: VectorIndexType;
581
- distance: VectorDistance;
582
- config?: never;
580
+ readonly type: VectorIndexType;
581
+ readonly distance: VectorDistance;
582
+ readonly config?: never;
583
583
  } | {
584
- type: 'vectorSearch';
585
- distance?: VectorDistance;
586
- config?: never;
584
+ readonly type: 'vectorSearch';
585
+ readonly distance?: VectorDistance;
586
+ readonly config?: never;
587
587
  } | {
588
- type: 'fulltext';
589
- distance?: never;
590
- config?: string;
588
+ readonly type: 'fulltext';
589
+ readonly distance?: never;
590
+ readonly config?: string;
591
591
  } | {
592
- type?: Exclude<IndexType, VectorIndexType | 'vectorSearch' | 'fulltext'>;
593
- distance?: never;
594
- config?: never;
592
+ readonly type?: Exclude<IndexType, VectorIndexType | 'vectorSearch' | 'fulltext'>;
593
+ readonly distance?: never;
594
+ readonly config?: never;
595
595
  };
596
596
  /** What an index entry carries besides what it indexes, at every layer. */
597
597
  export type IndexEntryModifiers = {
@@ -709,19 +709,25 @@ type IndexEntryTarget = (ColumnLengths & {
709
709
  * @example `{ columns: (user) => [user.settings.theme, { column: user.settings.rating, type: Number }] }`
710
710
  */
711
711
  export type EntityIndexColumnInput = QuerySql | JsonPathRef<string> | JsonPathRef<UntypedJson> | (IndexEntryModifiers & IndexEntryTarget);
712
+ /**
713
+ * What an index states the same at every layer. Each layer adds its own `include` and `where` beside it, so nothing
714
+ * maps over `IndexTypeOptions`' arms: `type` and `distance` stay a discriminated pair at no instantiation cost.
715
+ */
716
+ export type IndexKnobs = {
717
+ /** Custom index name */
718
+ readonly name?: string;
719
+ /** Whether index is unique; omit or `false` for a non-unique index (default). */
720
+ readonly unique?: boolean;
721
+ } & VectorIndexOptions & IndexTypeOptions;
712
722
  /** An index as metadata keeps it. */
713
723
  export type EntityIndexMeta<E = object> = {
714
724
  /** The indexed entries, in order. */
715
- entries: readonly IndexEntry[];
716
- /** Custom index name */
717
- name?: string;
718
- /** Whether index is unique; omit or `false` for a non-unique index (default). */
719
- unique?: boolean;
720
- /** Partial index predicate, compiled when the schema is built. */
721
- where?: EntityWhereMeta<E>;
725
+ readonly entries: readonly IndexEntry[];
722
726
  /** Columns stored in the index beyond its key, so a query reading only these needs no row. Postgres-wire only. */
723
- include?: readonly string[];
724
- } & VectorIndexOptions & IndexTypeOptions;
727
+ readonly include?: readonly string[];
728
+ /** Partial index predicate, compiled when the schema is built. */
729
+ readonly where?: EntityWhereMeta<E>;
730
+ } & IndexKnobs;
725
731
  export type EntityMeta<E> = {
726
732
  readonly entity: AbstractType<E>;
727
733
  /** The table, which is the class's own name where the entity named none - see {@link derivedName}. */
@@ -912,24 +918,22 @@ export type EntityOptions<E = unknown> = {
912
918
  /** Triggers the database runs, in the order written. See {@link TriggerOptions}. */
913
919
  readonly triggers?: TriggerSection<E>;
914
920
  };
915
- /**
916
- * Everything an index carries beyond its columns, as the migration builder's `table.index(...)` takes it,
917
- * and through {@link EntityIndexOptions} an entity's `indexes`. `Except` (not plain `Omit`) keeps
918
- * `type`/`distance` a discriminated pair: omitting `distance` on a vector index type is a compile error.
919
- */
920
- export type IndexOptions = Except<EntityIndexMeta, 'entries' | 'where'> & {
921
+ /** Everything an index carries beyond its columns, as the migration builder's `table.index(...)` takes it. */
922
+ export type IndexOptions = IndexKnobs & {
923
+ /** Columns stored in the index beyond its key, so a query reading only these needs no row. Postgres-wire only. */
924
+ readonly include?: readonly string[];
921
925
  /** Partial-index predicate, as `sql` with no interpolation: the migration builder has no entity to compile one against. */
922
926
  readonly where?: QuerySql;
923
927
  };
924
928
  /** {@link IndexOptions} on an entity, `include` and `where` read off the section's refs as its columns are. */
925
- export type EntityIndexOptions<E> = Merge<IndexOptions, {
929
+ export type EntityIndexOptions<E> = IndexKnobs & {
926
930
  readonly include?: readonly ColumnRef<FieldKey<E>>[];
927
931
  /**
928
932
  * Partial-index predicate, written as the predicate the query passes: a planner matches the two by
929
933
  * shape, so a hand-written `sql` that means the same thing leaves the index unused.
930
934
  */
931
935
  readonly where?: EntityPredicate<E> | QuerySql;
932
- }>;
936
+ };
933
937
  /** An index as registration reads it: its columns, read off the refs, and its options. */
934
938
  export type EntityIndexInput<E> = EntityIndexOptions<E> & {
935
939
  readonly columns: readonly EntityIndexColumnInput[];
@@ -45,13 +45,13 @@ export declare function unsupportedVectorMetric(engine: EngineName, distance: Ve
45
45
  */
46
46
  export type VectorIndexOptions = {
47
47
  /** Distance metric for vector indexes - maps to operator class. */
48
- distance?: VectorDistance;
48
+ readonly distance?: VectorDistance;
49
49
  /** HNSW: max connections per node. */
50
- m?: number;
50
+ readonly m?: number;
51
51
  /** HNSW: construction search depth. */
52
- efConstruction?: number;
52
+ readonly efConstruction?: number;
53
53
  /** IVFFlat: number of inverted lists. */
54
- lists?: number;
54
+ readonly lists?: number;
55
55
  };
56
56
  /** The metric a search or an index measures by where nothing names one: every engine with vectors has it. */
57
57
  export declare const DEFAULT_VECTOR_DISTANCE: VectorDistance;
@@ -1,5 +1,5 @@
1
1
  import type { CheckSchema, EnumValues } from '../schema/types.js';
2
- import type { EntityIndexMeta, EntityMeta, IndexEntry, QuerySql } from '../type/index.js';
2
+ import type { EntityIndexMeta, EntityMeta, IndexEntry, IndexKnobs, IndexSchema, QuerySql } from '../type/index.js';
3
3
  /**
4
4
  * Every index an entity declares: each `index()` or `unique()` column as the one-column
5
5
  * index it is, then its `indexes`. A unique column is a unique index, the one spelling of uniqueness
@@ -7,13 +7,13 @@ import type { EntityIndexMeta, EntityMeta, IndexEntry, QuerySql } from '../type/
7
7
  */
8
8
  export declare function declaredIndexes<E>(meta: EntityMeta<E>): EntityIndexMeta<E>[];
9
9
  /**
10
- * An index's rendered predicate and the name it is created by, settled together: `render` gets the name without the
10
+ * An index as the schema holds it, its entries' SQL rendered by `renderSql`. `renderWhere` gets the name without the
11
11
  * predicate's hash to label its errors, then the name takes the hash of what it rendered.
12
12
  */
13
- export declare function namedIndex(name: string | undefined, table: string, entries: readonly IndexEntry<unknown>[], render: (label: string) => string | undefined, unique?: boolean): {
14
- readonly name: string;
15
- readonly where: string | undefined;
16
- };
13
+ export declare function renderIndex(table: string, { entries, unique, ...index }: IndexKnobs & {
14
+ readonly entries: readonly IndexEntry[];
15
+ readonly include?: readonly string[];
16
+ }, renderSql: (sql: QuerySql) => string, renderWhere: (label: string) => string | undefined, uniqueName?: boolean): IndexSchema;
17
17
  /**
18
18
  * The name an index is created and read by: its own, else one derived from its table, entries, uniqueness and
19
19
  * rendered predicate. A caller renders the predicate first, since an unnamed partial index's name carries its hash.
@@ -1,4 +1,4 @@
1
- import { indexEntryNamePart } from './indexEntry.util.js';
1
+ import { indexEntryNamePart, renderIndexColumn } from './indexEntry.util.js';
2
2
  import { definedEntries } from './object.util.js';
3
3
  import { sql } from './sql.js';
4
4
  import { derivedIndexName, ownedName } from './sql.util.js';
@@ -20,12 +20,18 @@ export function declaredIndexes(meta) {
20
20
  return [...fieldIndexes, ...(meta.indexes ?? [])];
21
21
  }
22
22
  /**
23
- * An index's rendered predicate and the name it is created by, settled together: `render` gets the name without the
23
+ * An index as the schema holds it, its entries' SQL rendered by `renderSql`. `renderWhere` gets the name without the
24
24
  * predicate's hash to label its errors, then the name takes the hash of what it rendered.
25
25
  */
26
- export function namedIndex(name, table, entries, render, unique) {
27
- const where = render(declaredIndexName(name, table, entries, { unique }));
28
- return { name: declaredIndexName(name, table, entries, { unique, where }), where };
26
+ export function renderIndex(table, { entries, unique = false, ...index }, renderSql, renderWhere, uniqueName) {
27
+ const where = renderWhere(declaredIndexName(index.name, table, entries, { unique: uniqueName }));
28
+ return {
29
+ ...index,
30
+ name: declaredIndexName(index.name, table, entries, { unique: uniqueName, where }),
31
+ where,
32
+ entries: entries.map((entry) => renderIndexColumn(entry, renderSql)),
33
+ unique,
34
+ };
29
35
  }
30
36
  /**
31
37
  * The name an index is created and read by: its own, else one derived from its table, entries, uniqueness and
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "homepage": "https://uql-orm.dev",
4
4
  "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
5
5
  "license": "MIT",
6
- "version": "0.106.0",
6
+ "version": "0.106.1",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"