uql-orm 0.73.1 → 0.74.1

package/dist/mongo/vectorDistance.js

@@ -0,0 +1,26 @@
+/**
+ * A document's distance from `vector` as an aggregation expression, computed exactly as the SQL engines
+ * compute theirs: Atlas ranks only through its own index, which no related document reaches. `null` where
+ * the field holds no vector, or a cosine has a zero-length side, and `$min` skips a `null`.
+ */
+export function vectorDistanceExpr(column, vector, metric) {
+    const field = `$${column}`;
+    const sum = (term) => ({
+        $sum: { $map: { input: { $zip: { inputs: [field, { $literal: vector }] } }, as: 'pair', in: term } },
+    });
+    const own = { $arrayElemAt: ['$$pair', 0] };
+    const other = { $arrayElemAt: ['$$pair', 1] };
+    const dot = sum({ $multiply: [own, other] });
+    const distance = {
+        cosine: {
+            $let: {
+                vars: { norms: { $multiply: [{ $sqrt: sum({ $multiply: [own, own] }) }, Math.hypot(...vector)] } },
+                in: { $cond: [{ $eq: ['$$norms', 0] }, null, { $subtract: [1, { $divide: [dot, '$$norms'] }] }] },
+            },
+        },
+        l2: { $sqrt: sum({ $pow: [{ $subtract: [own, other] }, 2] }) },
+        inner: { $multiply: [-1, dot] },
+        l1: sum({ $abs: { $subtract: [own, other] } }),
+    };
+    return { $cond: [{ $isArray: field }, distance[metric], null] };
+}

package/dist/schema/indexDifferences.d.ts

@@ -5,18 +5,28 @@ import type { IndexNode } from './types.js';
  * `textIndex` is a text index's weights and language, kept by an engine that lists its fields in no declared order.
  */
 export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'textIndex';
+type ComparableIndex = Pick<IndexNode, 'name' | 'entries' | 'unique'>;
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
  * over an expression, whose text the engine reprints, falls back to its name.
  */
-export declare function indexSignature(index: Pick<IndexNode, 'name' | 'entries' | 'unique'>): string;
+export declare function indexSignature(index: ComparableIndex): string;
 /**
  * A constraint name without its kind marker, pairing an index with its older spelling
  * (`idx_User_email` with `User__email_idx`). Only one marker, the trailing one first.
  */
 export declare function indexNameStem(name: string): string;
+/**
+ * The indexes a table lacks and the ones it no longer needs, matched by `keyOf`. Only an index uql
+ * named, or whose name the entity claims, is dropped: any other may have been made outside the ORM.
+ */
+export declare function indexChanges<I extends ComparableIndex>(table: string, declared: readonly I[], current: readonly IndexNode[], keyOf?: (index: ComparableIndex) => string): {
+    toAdd: I[];
+    toDrop: IndexNode[];
+};
 /**
  * What two indexes differ by, comparing only what both sides state structurally: an expression, a JSON
  * path or a predicate is reprinted by the engine, so never compared.
  */
 export declare function describeIndexDifferences(source: IndexNode, target: IndexNode, facets: ReadonlySet<IndexFacet>): string[];
+export {};

package/dist/schema/indexDifferences.js

@@ -1,11 +1,16 @@
 import { isVectorIndexType } from '../type/vector.js';
 import { fulltextConfig } from '../util/dialect.util.js';
+import { derivedIndexName } from '../util/sql.util.js';
+/** An entry the engine reprints in its own words, so never compared as written. */
+function isReprinted(entry) {
+    return Boolean(entry.expression || entry.jsonPath || entry.jsonArray);
+}
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
  * over an expression, whose text the engine reprints, falls back to its name.
  */
 export function indexSignature(index) {
-    const comparable = !index.entries.some((entry) => entry.expression || entry.jsonPath || entry.jsonArray);
+    const comparable = !index.entries.some(isReprinted);
     const identity = comparable
         ? index.entries.map((entry) => entry.column).join(',')
         : `name:${indexNameStem(index.name)}`;
@@ -20,6 +25,33 @@ export function indexNameStem(name) {
     const bare = withoutSuffix === name ? name.replace(KIND_PREFIX, '') : withoutSuffix;
     return bare.replace(/__/g, '_');
 }
+/**
+ * The indexes a table lacks and the ones it no longer needs, matched by `keyOf`. Only an index uql
+ * named, or whose name the entity claims, is dropped: any other may have been made outside the ORM.
+ */
+export function indexChanges(table, declared, current, keyOf = indexSignature) {
+    const present = new Set(current.map(keyOf));
+    const wanted = new Set(declared.map(keyOf));
+    const claimed = new Set(declared.map((index) => index.name));
+    const owned = (index) => claimed.has(index.name) || hasDerivedName(table, index);
+    return {
+        toAdd: declared.filter((index) => !present.has(keyOf(index))),
+        toDrop: current.filter((index) => !wanted.has(keyOf(index)) && owned(index)),
+    };
+}
+/**
+ * Whether uql named the index itself, from its own columns: `Order__total_idx`, its unique `_uk`, or
+ * the `idx_Order_total` it wrote until 0.42.1.
+ */
+function hasDerivedName(table, index) {
+    const parts = index.entries.map((entry, at) => (isReprinted(entry) ? `expr${at}` : entry.column));
+    const derived = [
+        derivedIndexName(table, parts),
+        derivedIndexName(table, parts, true),
+        `idx_${table}_${parts.join('_')}`,
+    ];
+    return derived.includes(index.name);
+}
 /** What this version emits. */
 const KIND_SUFFIX = /_(?:idx|fk|ck|pk|uk|uq)$/i;
 /**
@@ -34,7 +66,7 @@ const KIND_PREFIX = /^(?:idx|fk|ck|pk|uk|uq)_/i;
  */
 export function describeIndexDifferences(source, target, facets) {
     const differences = [];
-    const comparableEntries = ![...source.entries, ...target.entries].some((entry) => entry.expression || entry.jsonPath || entry.jsonArray);
+    const comparableEntries = ![...source.entries, ...target.entries].some(isReprinted);
     if (comparableEntries) {
         const [sourceColumns, targetColumns] = [source, target].map((index) => textFieldOrder(index, facets, index.entries.map((entry) => entrySignature(entry, facets))).join(', '));
         if (sourceColumns !== targetColumns) {

package/dist/type/dialect.d.ts

@@ -3,6 +3,7 @@ import type { Query, QueryConflictPaths, QueryOptions, QueryPage, QuerySearch, R
 import type { QueryAggMap, QueryAggregate, QueryAggregateOp, QueryGroupMap } from './queryAggregate.js';
 import type { QueryWhere } from './queryWhere.js';
 import type { Type } from './utility.js';
+import type { QueryVectorQuery } from './vector.js';
 /**
  * comparison options.
  */
@@ -247,13 +248,15 @@ export type AggregateCall<E = object> = {
     readonly field?: string;
     readonly where?: QueryWhere<E>;
 };
-/** What a relation aggregate reads: how many rows, or one of the target's columns. */
+/** What a relation aggregate reads: how many rows, or one of the target's columns, or its distance to `search`. */
 export type RelationAggregateProjection = {
     readonly op: '$count';
     readonly field?: never;
+    readonly search?: never;
 } | {
     readonly op: Exclude<RelationAggregateOp, '$count'>;
     readonly field: string;
+    readonly search?: QueryVectorQuery;
 };
 /**
  * A relation aggregate as a `computed` field holds it: an {@link AggregateCall} over the rows of the

package/dist/type/migration.d.ts

@@ -203,7 +203,8 @@ export interface SchemaDiff {
     }[];
     readonly columnsToDrop?: string[];
     readonly indexesToAdd?: IndexSchema[];
-    readonly indexesToDrop?: string[];
+    /** Whole rather than by name, so the rollback can create each again. */
+    readonly indexesToDrop?: IndexSchema[];
     readonly foreignKeysToAdd?: ForeignKeySchema[];
     /** Dropped under the name the *database* reported, which is the only name a `DROP` can use. */
     readonly foreignKeysToDrop?: string[];

package/dist/type/query.d.ts

@@ -3,7 +3,7 @@ import type { QueryLock } from './queryLock.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
 import type { BooleanLike, Except, IsMany, PrimaryKey } from './utility.js';
-import type { QueryVectorSearch } from './vector.js';
+import type { QueryVectorQuery, QueryVectorSearch } from './vector.js';
 export type QueryOptions = {
     /**
      * Toggle named entity filters for this query. `false` disables all filters;
@@ -129,6 +129,18 @@ export type QuerySortValue = QuerySortDirection | QueryVectorSearch;
 export type QuerySortByCount = {
     $count: QuerySortDirection;
 };
+/** The fields of `E` a vector search can rank by. */
+type VectorFieldKey<E> = {
+    [P in FieldKey<E>]: NonNullable<E[P]> extends readonly number[] ? P : never;
+}[FieldKey<E>];
+/**
+ * Ordering parents by the row of a to-many nearest a vector, per vector field: its distance is the
+ * smallest of theirs. Nothing to `$project`, since no one row of the parent's answers under it. Never
+ * where the target has no vector, since an empty map would admit any value at all.
+ */
+export type QuerySortByNearest<E> = [VectorFieldKey<E>] extends [never] ? never : {
+    [P in VectorFieldKey<E>]?: QueryVectorQuery;
+};
 /**
  * Ordering by relevance to the `$text` at the root of `$where`, in either direction as any key sorts. The
  * object form also answers it under the name `$project` gives it, most relevant first unless `$order` says.
@@ -145,12 +157,13 @@ export type QuerySortByText = {
  */
 export type WithProjection<E, K extends string> = E & Record<K, number>;
 /**
- * A sort by fields, JSON paths, a to-one relation's fields, a to-many's `$count`, or - where `Root` says it
- * sorts the queried entity itself, not a relation's rows - a vector distance or a `$text` relevance. One
- * mapped type over the key sets: an intersection is checked once per member, which made this the costliest.
+ * A sort by fields, JSON paths, a to-one relation's fields, a to-many's `$count` or nearest row, a vector
+ * distance, or - where `Root` says it sorts the queried entity itself, not a relation's rows - a `$text`
+ * relevance or a distance it projects. One mapped type over the key sets: an intersection is checked once
+ * per member, which made this the costliest.
  */
 export type QuerySortMap<E, Root extends boolean = true, K extends keyof E = FieldKey<E> | RelationKey<E>> = {
-    [P in K]?: P extends RelationKey<E> ? IsMany<E[P]> extends true ? QuerySortByCount : QuerySortMap<RelationTarget<E[P]>, false> : Root extends true ? NonNullable<E[P]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection;
+    [P in K]?: P extends RelationKey<E> ? IsMany<E[P]> extends true ? QuerySortByCount | QuerySortByNearest<RelationTarget<E[P]>> : QuerySortMap<RelationTarget<E[P]>, false> : NonNullable<E[P]> extends readonly number[] ? Root extends true ? QuerySortValue : QuerySortDirection | QueryVectorQuery : QuerySortDirection;
 } & ([JsonFieldPaths<E>] extends [never] ? unknown : {
     [P in JsonFieldPaths<E>]?: QuerySortDirection;
 }) & (Root extends true ? QuerySortByText : unknown);

package/dist/util/dialect.util.d.ts

@@ -1,5 +1,5 @@
 import type { IndexType } from '../schema/types.js';
-import { type AggregateCall, type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
+import { type AggregateCall, type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 /** The keys of `payload` a write persists as columns. */
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -81,6 +81,11 @@ export declare function vectorCandidates(q: {
  * "which kind", which decide the name Atlas is queried by and the setting Postgres is tuned with.
  */
 export declare function findVectorIndex<E>(meta: EntityMeta<E>, key: string): EntityIndexMeta<E> | undefined;
+/**
+ * The metric a distance to `key` measures by: the search's own, else the field's, else its index's, which
+ * serves no other, else cosine. The one fallback every engine resolves, so none can rank by another.
+ */
+export declare function vectorDistanceOf<E>(meta: EntityMeta<E>, key: string, search: QueryVectorQuery): VectorDistance;
 /**
  * Whether a `$where` filters by vector distance anywhere in its tree, `$and`/`$or`/`$not` included.
  * What tells Postgres that an HNSW scan needs to iterate rather than return one candidate list.

package/dist/util/dialect.util.js

@@ -1,7 +1,7 @@
 import { getContext, UqlSecurityError } from '../context/context.js';
 import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
-import { VECTOR_INDEX_TYPES } from '../type/vector.js';
+import { DEFAULT_VECTOR_DISTANCE, VECTOR_INDEX_TYPES } from '../type/vector.js';
 import { getFieldKeys, isDatabaseWritten } from './field.util.js';
 import { entityName, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
 /** The keys of `payload` a write persists as columns. */
@@ -209,6 +209,16 @@ const VECTOR_INDEX_MATCH = new Set([...VECTOR_INDEX_TYPES, 'vectorSearch']);
 export function findVectorIndex(meta, key) {
     return meta.indexes?.find((index) => index.type !== undefined && VECTOR_INDEX_MATCH.has(index.type) && indexCoversColumn(index, key));
 }
+/**
+ * The metric a distance to `key` measures by: the search's own, else the field's, else its index's, which
+ * serves no other, else cosine. The one fallback every engine resolves, so none can rank by another.
+ */
+export function vectorDistanceOf(meta, key, search) {
+    return (search.$distance ??
+        meta.fields[key]?.distance ??
+        findVectorIndex(meta, key)?.distance ??
+        DEFAULT_VECTOR_DISTANCE);
+}
 /**
  * Whether a `$where` filters by vector distance anywhere in its tree, `$and`/`$or`/`$not` included.
  * What tells Postgres that an HNSW scan needs to iterate rather than return one candidate list.

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, 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.",
   "license": "MIT",
-  "version": "0.73.1",
+  "version": "0.74.1",
   "type": "module",
   "engines": {
     "node": ">=24"