uql-orm 0.69.0 → 0.71.0

package/dist/dialect/queryJoins.js

@@ -1,5 +1,5 @@
 import { getMeta, relationOf } from '../entity/index.js';
-import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey } from '../util/index.js';
+import { getKeys, getRelationRequestSummary, isRecord, isToManyRelation, parseRelationAtKey, parseRelationSize, } from '../util/index.js';
 export const NO_JOINS = new Map();
 /**
  * What the statement joins, from `$populate` and from a `$sort` by a to-one relation's field, so the
@@ -11,9 +11,48 @@ export function resolveQueryJoins(meta, q, claimAlias = (path) => path) {
     }
     const joins = new Map();
     addPopulateJoins(joins, claimAlias, meta, q.$populate);
-    addSortJoins(joins, claimAlias, meta, q.$sort);
+    addPathJoins(joins, claimAlias, meta, q.$sort, false);
     return joins;
 }
+/**
+ * What an aggregate joins, and the `$where` left to it. Each to-one relation a `$group` path passes through
+ * is an `INNER` join, since a group of a path names a related row; a filter on one of them, keyed at the top
+ * of the `$where` where an `AND` joins it, moves into that join rather than reading its table again. Under a
+ * `$not` it could not: the join would drop the rows the negation keeps.
+ */
+export function resolveGroupJoins(meta, q, claimAlias = (path) => path) {
+    const joins = new Map();
+    for (const ref of Object.values(q.$group ?? {})) {
+        if (isRecord(ref)) {
+            addPathJoins(joins, claimAlias, meta, ref, true);
+        }
+    }
+    if (!q.$where) {
+        return { joins, where: q.$where };
+    }
+    const where = { ...q.$where };
+    for (const key of getKeys(q.$where)) {
+        const join = joins.get(key);
+        const filter = q.$where[key];
+        if (join && isRecord(filter) && parseRelationSize(filter) === undefined) {
+            joins.set(key, { ...join, query: { $where: filter } });
+            delete where[key];
+        }
+    }
+    return { joins, where };
+}
+/** The field a grouped `path` reads, and the join it reads it through: none for the entity's own. */
+export function groupPathField(joins, path) {
+    const key = path[path.length - 1];
+    if (path.length === 1) {
+        return { key, join: undefined };
+    }
+    const join = joins.get(path.slice(0, -1).join('.'));
+    if (!join) {
+        throw new TypeError(`cannot $group by '${path.join('.')}': only a to-one relation's field groups, since a to-many multiplies the rows it joins`);
+    }
+    return { key, join };
+}
 /**
  * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
  * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or
@@ -71,21 +110,25 @@ function addPopulateJoins(joins, claimAlias, meta, populate, parent) {
         addPopulateJoins(joins, claimAlias, join.meta, query.$populate, join);
     }
 }
-function addSortJoins(joins, claimAlias, meta, sort, parent) {
-    if (!sort) {
+/**
+ * The to-one relations a nested map of fields passes through, a `$sort` or a `$group` path, as joins adding
+ * no columns: `required` where the path names a related row, as a group's does, and a sort's does not.
+ */
+function addPathJoins(joins, claimAlias, meta, map, required, parent) {
+    if (!map) {
         return;
     }
-    for (const key of getKeys(sort)) {
+    for (const key of getKeys(map)) {
         const relation = meta.relations[key];
-        const value = sort[key];
+        const value = map[key];
         // A to-many, or a value that is not a map of the relation's own fields, cannot be joined and is
-        // reported where the `ORDER BY` is rendered - the one place that knows how to name it.
+        // reported where the statement names it - the one place that knows how to.
         if (!relation || isToManyRelation(relation) || !isSortMap(value)) {
             continue;
         }
-        const join = addJoin(joins, claimAlias, parent, key, relation, {}, false, false);
-        // `E` stated: inferred from a `QuerySortMap<object>`, it lands on the nested relation's target.
-        addSortJoins(joins, claimAlias, join.meta, value, join);
+        const join = addJoin(joins, claimAlias, parent, key, relation, {}, required, false);
+        // `E` stated: inferred from the nested map, it lands on the nested relation's target.
+        addPathJoins(joins, claimAlias, join.meta, value, required, join);
     }
 }
 /** The join a sort may address at `path` with the relation's own sort map, or why it may not; `unjoinable` is the dialect's remedy. */
@@ -102,7 +145,7 @@ export function resolveSortableJoin(relation, path, value, joins, unjoinable) {
     }
     return { join, sort: value };
 }
-/** A nested `$sort` map, as opposed to a direction or a vector search. */
+/** A nested map of fields, as opposed to a `$sort` direction or vector search, or a `$group` field's `true`. */
 function isSortMap(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) && !('$vector' in value);
 }

package/dist/dialect/vectorCast.d.ts

@@ -20,5 +20,7 @@ export declare function toSparsevecLiteral(values: readonly unknown[]): string;
  * as it was written, `{1:1,3:2}/3` or `[1,2,3]`; `undefined` where the text matches neither.
  */
 export declare function parseVectorLiteral(raw: string, cast: VectorCast): number[] | undefined;
+/** The packed little-endian float32s a blob vector column holds, and {@link decodeFloat32s} reads back. */
+export declare function encodeFloat32s(values: readonly unknown[]): Uint8Array;
 /** Packed little-endian float32s, each read as {@link shortestFloat32}. */
 export declare function decodeFloat32s(bytes: Uint8Array): number[];

package/dist/dialect/vectorCast.js

@@ -62,6 +62,13 @@ function parseDense(text) {
         return undefined;
     }
 }
+/** The packed little-endian float32s a blob vector column holds, and {@link decodeFloat32s} reads back. */
+export function encodeFloat32s(values) {
+    const bytes = new Uint8Array(values.length * 4);
+    const view = new DataView(bytes.buffer);
+    values.forEach((value, at) => view.setFloat32(at * 4, Number(value), true));
+    return bytes;
+}
 /** Packed little-endian float32s, each read as {@link shortestFloat32}. */
 export function decodeFloat32s(bytes) {
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);

package/dist/dialect/vectorSqlDialect.d.ts

@@ -1,6 +1,6 @@
-import type { EntityIndexMeta, EntityMeta, FieldOptions, Query, QueryContext, QueryVectorSearch, SqlDialectFeatures, VectorDistance, VectorMetric } from '../type/index.js';
+import type { EntityIndexMeta, EntityMeta, FieldOptions, Query, QueryContext, QueryVectorSearch, QueryWhere, SqlDialectFeatures, VectorDistance, VectorMetric } from '../type/index.js';
 import { AbstractDialect } from './abstractDialect.js';
-import type { VectorCast } from './vectorCast.js';
+import { type VectorCast } from './vectorCast.js';
 /**
  * Vector search for the SQL dialects: the distance a `$sort` ranks by and projects, and the ANN tuning.
  * Each dialect lists its metrics in {@link vectorMetrics}, an operator or a function; empty means no search.
@@ -20,12 +20,16 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      * spelled into a `SET` rather than bound, and `/http` input is untyped.
      */
     protected tunedVectorIndex<E>(meta: EntityMeta<E>, q: Query<E>): EntityIndexMeta | undefined;
+    /** The `$where` a read runs: the query's own, which an engine reading its vector index as a table narrows. */
+    protected rankedWhere<E>(_meta: EntityMeta<E>, q: Query<E>, _prefix: string | undefined): QueryWhere<E> | undefined;
     /**
      * Every distance metric this dialect has, and how a search and an index spell each. Empty means no
      * vector search at all, which is what MySQL and D1 are. The key set is the single answer to "is this
      * metric supported here", for a query and an index alike.
      */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
+    /** Whether this engine has a vector index: the one a metric's `index` names. */
+    hasVectorIndex(): boolean;
     /** Quotes an identifier; supplied by the SQL dialect built on top of this layer. */
     abstract escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /**
@@ -39,7 +43,7 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
     };
     /**
      * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
-     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     * dialect needing a conversion around it (`$1::vector`, `CAST(? AS VECTOR(n))`) declares it once.
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], _field?: FieldOptions): void;
     /**

package/dist/dialect/vectorSqlDialect.js

@@ -1,7 +1,8 @@
-import { unsupportedVectorMetric } from '../type/vector.js';
-import { findVectorIndex, findVectorSort } from '../util/dialect.util.js';
+import { DEFAULT_VECTOR_DISTANCE, unsupportedVectorMetric } from '../type/vector.js';
+import { findVectorIndex, findVectorSort, vectorCandidates } from '../util/dialect.util.js';
 import { entityName } from '../util/object.util.js';
 import { AbstractDialect } from './abstractDialect.js';
+import { encodeFloat32s } from './vectorCast.js';
 /**
  * Vector search for the SQL dialects: the distance a `$sort` ranks by and projects, and the ANN tuning.
  * Each dialect lists its metrics in {@link vectorMetrics}, an operator or a function; empty means no search.
@@ -24,22 +25,26 @@ export class VectorSqlDialect extends AbstractDialect {
      * spelled into a `SET` rather than bound, and `/http` input is untyped.
      */
     tunedVectorIndex(meta, q) {
-        const candidates = q.$candidates;
-        if (candidates === undefined) {
+        if (vectorCandidates(q) === undefined) {
             return undefined;
         }
-        if (!Number.isInteger(candidates) || candidates < 1) {
-            throw new TypeError(`$candidates must be a positive integer, got ${JSON.stringify(candidates)}`);
-        }
         const key = this.vectorSortKey(q);
         return key ? findVectorIndex(meta, key) : undefined;
     }
+    /** The `$where` a read runs: the query's own, which an engine reading its vector index as a table narrows. */
+    rankedWhere(_meta, q, _prefix) {
+        return q.$where;
+    }
     /**
      * Every distance metric this dialect has, and how a search and an index spell each. Empty means no
      * vector search at all, which is what MySQL and D1 are. The key set is the single answer to "is this
      * metric supported here", for a query and an index alike.
      */
     vectorMetrics = new Map();
+    /** Whether this engine has a vector index: the one a metric's `index` names. */
+    hasVectorIndex() {
+        return [...this.vectorMetrics.values()].some((metric) => metric.index);
+    }
     /**
      * What a distance expression reads, for a `$sort` and a `$near` alike. The metric falls back to the
      * field's, then its index's, which serves no other, then cosine.
@@ -47,15 +52,15 @@ export class VectorSqlDialect extends AbstractDialect {
     resolveVectorDistance(meta, key, search) {
         const field = meta.fields[key];
         const colName = this.resolveColumnName(key, field);
-        const distance = search.$distance ?? field?.distance ?? findVectorIndex(meta, key)?.distance ?? 'cosine';
+        const distance = search.$distance ?? field?.distance ?? findVectorIndex(meta, key)?.distance ?? DEFAULT_VECTOR_DISTANCE;
         return { colName, distance, field };
     }
     /**
      * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
-     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     * dialect needing a conversion around it (`$1::vector`, `CAST(? AS VECTOR(n))`) declares it once.
      */
     appendVectorValue(ctx, value, _field) {
-        ctx.addValue(`[${value.join(',')}]`);
+        ctx.addValue(this.features.vectorBytes ? encodeFloat32s(value) : `[${value.join(',')}]`);
     }
     /**
      * The vector type this dialect actually has for a declared one, so the cast follows the column

package/dist/entity/decorator/members.d.ts

@@ -1,7 +1,19 @@
-import type { AggregateValue, ComputedRefs, EntityAggregate, EntityGetter, Except, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, RejectKeys, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, RelationAggregate, TsTypeOf } from '../../type/index.js';
+import type { AggregateValue, ComputedRefs, EntityAggregate, EntityGetter, Except, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, RejectKeys, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, RelationAggregate, TsTypeOf, Writable } from '../../type/index.js';
 import type { RejectIncompatible } from '../../util/index.js';
 /** A member decorator that also constrains the property it may be applied to, on a class `O`. */
 type MemberDecorator<V, O = unknown> = (value: undefined, context: ClassFieldDecoratorContext<O, V>) => void;
+/**
+ * A {@link MemberDecorator} whose property has to admit `M` as well as hold `V`. A decorator context is
+ * covariant in its value, so on its own it takes a property narrower than the field reads: a `string`
+ * where a nullable column reads `string | null`, a `number` where `max()` reads `number | null`.
+ *
+ * `M` is what each arm insists on rather than the whole of `V`, because a column type that names a
+ * family - `jsonb`, whose document the property shapes, or `numeric`, either number kind - is meant to
+ * be narrowed. A column insists on its `null`; an aggregate, whose value is exact, insists on all of it.
+ */
+type AdmittingDecorator<V, M, O> = <P extends V | undefined>(value: undefined, context: ClassFieldDecoratorContext<O, P> & ([Writable<M>] extends [Writable<P>] ? unknown : {
+    readonly __propertyMustAdmit: M;
+})) => void;
 /**
  * The property type a set of field options describes: the declared `type`, narrowed by `enum` to the
  * values that type admits (so `enum: [2]` stays off a `String`), or else the referenced key's own type,
@@ -16,6 +28,16 @@ type DeclaredValue<O> = O extends {
 } ? HasCompositeKey<E> extends true ? {
     readonly __compositeKeyNeedsAColumnPerKey: true;
 } : IdValue<E> : never;
+/**
+ * The `null` a column reads back: every one holds it unless `nullable: false` says otherwise, so the
+ * property admits it too. A key holds none, whether `@Id` or `@Field({ isId: true })` declares it, since
+ * it is NOT NULL on every engine.
+ */
+type NullOf<O> = O extends {
+    readonly nullable: false;
+} | {
+    readonly isId: true;
+} ? never : null;
 /** The enum's members, or a named complaint where they widened for lack of `as const`, which would check nothing. */
 type EnumValue<Members, Declared> = Declared extends Members ? {
     readonly __enumNeedsAsConst: true;
@@ -29,14 +51,14 @@ export declare function Field<This, O extends FieldOptions<DeclaredValue<O>, Thi
     type: FieldType;
 } | {
     references: EntityGetter;
-}) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined, This>;
+}) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O): AdmittingDecorator<DeclaredValue<O> | NullOf<O>, NullOf<O>, This>;
 /**
  * Declares a field a relation aggregate computes, `@Field({ computed: (user) => user.resources.count() })`.
  * The aggregate says what the field holds, so it takes no `type`, and only `count` and `sum` - the two a
  * row change turns into a delta - may be `stored`.
  * @example `@Field({ computed: (user) => user.resources.count() }) readonly resourceCount?: number;`
  */
-export declare function Field<This, O extends AggregateOptions<This> & RejectKeys<Exclude<keyof O, keyof FieldOptions>>>(opts: O): AggregateDecorator<AggregateValue<O>, This>;
+export declare function Field<This, O extends AggregateOptions<This> & RejectKeys<Exclude<keyof O, keyof FieldOptions>>>(opts: O): AdmittingDecorator<AggregateValue<O>, AggregateValue<O>, This>;
 /**
  * A field the aggregate itself types: `stored: true` only where a trigger could keep it, and every other
  * option as a column takes it.
@@ -50,14 +72,6 @@ type AggregateOptions<E> = (Except<FieldOptions<never, E>, 'computed' | 'stored'
     }['agg'];
     readonly stored: true;
 });
-/**
- * {@link MemberDecorator} for a field an aggregate types, which the property has to hold *exactly*: a
- * decorator context takes a property narrower than its value, so nothing else would stop a `number`
- * from holding what `max()` reads, which is `number | null` on a parent with no rows.
- */
-type AggregateDecorator<V, O> = <P extends V | undefined>(value: undefined, context: ClassFieldDecoratorContext<O, P> & ([V] extends [P] ? unknown : {
-    readonly __propertyMustAdmit: V;
-})) => void;
 /**
  * A key the type level cannot name, reported on each `@Id` that leaves it unnamed. Where no `idKey`
  * brand and no conventional name applies, `IdKey` falls back to every field, and `IdValue`,

package/dist/entity/metadata/definition.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldMeta, FieldOptions, FilterName, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, RelationRegistration, Type, WrittenId } from '../../type/index.js';
+import type { EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldMeta, FieldOptions, FilterName, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, RelationRegistration, Type, WrittenId } from '../../type/index.js';
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
 /** `T` is the relation's target, independent of the owner `E`. */
@@ -39,10 +39,14 @@ export declare function soleIdOf<E>(meta: EntityMeta<E>, what: string): IdKey<E>
 export declare function fieldOf<E>(meta: EntityMeta<E>, key: string): FieldMeta;
 /** The relation `key` names, for a caller that took `key` from the metadata itself. */
 export declare function relationOf<E>(meta: EntityMeta<E>, key: RelationKey<E>): RelationMeta;
+/** A row of `E` as far as reading its key goes: a record or a write, whatever its values. */
+type KeyedRow<E> = {
+    readonly [K in keyof E]?: unknown;
+};
 /** Whether the row names every column of its primary key, `0` and `''` included. */
-export declare function namesKey<E>(meta: EntityMeta<E>, row: EntityData<E>): boolean;
+export declare function namesKey<E>(meta: EntityMeta<E>, row: KeyedRow<E>): boolean;
 /** A row's primary key: its value, or a map of every column on a composite, checked at run time. */
-export declare function idOf<E>(meta: EntityMeta<E>, row: EntityData<E>): WrittenId<E>;
+export declare function idOf<E>(meta: EntityMeta<E>, row: KeyedRow<E>): WrittenId<E>;
 /**
  * Forgets an entity, and reports whether there was one - for a registry that grows at runtime, where a
  * deleted content type would otherwise keep its metadata for the life of the process. Nothing rewrites
@@ -58,3 +62,4 @@ export declare function getMeta<E>(entity: Type<E>): EntityMeta<E>;
  * schema build constrains and a junction joins by, settling the relations holding them first.
  */
 export declare function foreignKeysOf<E>(meta: EntityMeta<E>): RelationMeta[];
+export {};

package/dist/libsql/libsqlDialect.d.ts

@@ -7,6 +7,6 @@ import type { VectorDistance, VectorMetric } from '../type/index.js';
  * functions, which `TursoDialect` inherits.
  */
 export declare class LibsqlDialect extends SqliteDialect {
-    /** libSQL's built-in vector functions; no `inner` (only the Rust engine has it) and no `l1`. */
+    /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
 }

package/dist/libsql/libsqlDialect.js

@@ -6,9 +6,9 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
  * functions, which `TursoDialect` inherits.
  */
 export class LibsqlDialect extends SqliteDialect {
-    /** libSQL's built-in vector functions; no `inner` (only the Rust engine has it) and no `l1`. */
+    /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
     vectorMetrics = new Map([
-        ['cosine', { fn: 'vector_distance_cos' }],
-        ['l2', { fn: 'vector_distance_l2' }],
+        ['cosine', { fn: 'vector_distance_cos', index: 'cosine' }],
+        ['l2', { fn: 'vector_distance_l2', index: 'l2' }],
     ]);
 }

package/dist/maria/mariaDialect.d.ts

@@ -6,8 +6,9 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
     /**
-     * Unlike MySQL: `VECTOR(n)` takes its dimension, every column of a vector index has to be NOT NULL,
-     * `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed to one table of a join.
+     * Unlike MySQL: `VECTOR(n)` takes its dimension and binds as packed float32 bytes, every column of a
+     * vector index has to be NOT NULL, `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed
+     * to one table of a join.
      */
     readonly features: SqlDialectFeatures;
     /**
@@ -34,13 +35,6 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     protected jsonDiffers(elem: string, operand: string): string;
     /** `VEC_DISTANCE_COSINE`/`VEC_DISTANCE_EUCLIDEAN`, 11.7+, which the index's `DISTANCE=` names alike. */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
-    /**
-     * A `VECTOR` column holds a packed little-endian float32 blob, and MariaDB refuses text where one
-     * belongs: inserting `'[1,2,3]'` fails with `Incorrect vector value`, and passing it to
-     * `VEC_DISTANCE_COSINE` with `Illegal parameter data type varchar`. `VEC_FromText` is the
-     * conversion, needed on both paths.
-     */
-    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /**
      * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
      * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,

package/dist/maria/mariaDialect.js

@@ -8,12 +8,14 @@ export class MariaDialect extends MysqlLikeSqlDialect {
     // MariaDB 10.5+ has `INSERT ... RETURNING`, so ids come back exact per row - the upsert's too.
     insertIdSource = 'returning';
     /**
-     * Unlike MySQL: `VECTOR(n)` takes its dimension, every column of a vector index has to be NOT NULL,
-     * `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed to one table of a join.
+     * Unlike MySQL: `VECTOR(n)` takes its dimension and binds as packed float32 bytes, every column of a
+     * vector index has to be NOT NULL, `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed
+     * to one table of a join.
      */
     features = {
         ...MYSQL_FEATURES,
         vectorSupportsLength: true,
+        vectorBytes: true,
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
         rowLockOf: false,
@@ -69,17 +71,6 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         ['cosine', { fn: 'VEC_DISTANCE_COSINE', index: 'cosine' }],
         ['l2', { fn: 'VEC_DISTANCE_EUCLIDEAN', index: 'euclidean' }],
     ]);
-    /**
-     * A `VECTOR` column holds a packed little-endian float32 blob, and MariaDB refuses text where one
-     * belongs: inserting `'[1,2,3]'` fails with `Incorrect vector value`, and passing it to
-     * `VEC_DISTANCE_COSINE` with `Illegal parameter data type varchar`. `VEC_FromText` is the
-     * conversion, needed on both paths.
-     */
-    appendVectorValue(ctx, value) {
-        ctx.append('VEC_FromText(');
-        super.appendVectorValue(ctx, value);
-        ctx.append(')');
-    }
     /**
      * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
      * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,

package/dist/maria/mariadbQuerier.js

@@ -1,19 +1,25 @@
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import { decodeBigInts } from '../util/wideNumber.js';
+/** This driver binds only a `Buffer` as bytes: any other `Uint8Array` goes as the JSON of its indices. */
+function toBindValues(values) {
+    return values?.map((value) => value instanceof Uint8Array && !Buffer.isBuffer(value)
+        ? Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+        : value);
+}
 export class MariadbQuerier extends AbstractPoolQuerier {
     async internalAll(query, values) {
-        const rows = await this.getConn().query(query, values);
+        const rows = await this.getConn().query(query, toBindValues(values));
         return Array.from(rows, decodeBigInts);
     }
     async internalRun(query, values) {
-        const res = await this.getConn().query(query, values);
+        const res = await this.getConn().query(query, toBindValues(values));
         // An OK packet reports `affectedRows`; a `RETURNING` statement answers rows instead, and counts by them.
         const changes = res.affectedRows ?? res.length;
         const rows = res.length ? Array.from(res, decodeBigInts) : [];
         return this.buildUpdateResult({ rows, changes, upsertStatus: res.affectedRows });
     }
     async *internalStream(query, values) {
-        const stream = this.getConn().queryStream(query, values);
+        const stream = this.getConn().queryStream(query, toBindValues(values));
         try {
             for await (const row of stream) {
                 yield decodeBigInts(row);

package/dist/migrate/codegen/entityCodeGenerator.js

@@ -156,9 +156,11 @@ export class EntityCodeGenerator {
             const fieldOptions = this.buildFieldOptions(col, propertyName);
             lines.push(`  @Field(${fieldOptions})`);
         }
-        // Property
+        // Property. A generated column is the database's to write, so it is `readonly`: a write payload
+        // leaves those out, and one naming it would be dropped rather than persisted.
         const nullable = col.nullable ? '?' : '';
-        lines.push(`  ${propertyName}${nullable}: ${tsType};`);
+        const written = col.generatedAs === undefined ? '' : 'readonly ';
+        lines.push(`  ${written}${propertyName}${nullable}: ${tsType};`);
         return lines.join('\n');
     }
     /**

package/dist/migrate/ddl/index.d.ts

@@ -6,6 +6,7 @@ export { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+export { SqliteIndexDdl } from './sqliteIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
 export declare function indexDdlFor(dialect: AbstractSqlDialect): IndexDdl;
 /**

package/dist/migrate/ddl/index.js

@@ -3,16 +3,18 @@ import { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 import { MsSqlTableDdl } from './mssqlTableDdl.js';
 import { MariaIndexDdl, MySqlIndexDdl } from './mysqlIndexDdl.js';
 import { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+import { SqliteIndexDdl } from './sqliteIndexDdl.js';
 import { TableDdl } from './tableDdl.js';
 export { IndexDdl } from './indexDdl.js';
 export { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+export { SqliteIndexDdl } from './sqliteIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
 /**
  * Each engine's index DDL, by the `dialectName` a subclass inherits: by name, so this entry carries no
- * dialect, and exhaustive, so a new engine has to name its own. SQLite's is the portable form.
+ * dialect, and exhaustive, so a new engine has to name its own.
  */
 const INDEX_DDL = {
     postgres: PgIndexDdl,
@@ -20,7 +22,7 @@ const INDEX_DDL = {
     mysql: MySqlIndexDdl,
     mariadb: MariaIndexDdl,
     mssql: MsSqlIndexDdl,
-    sqlite: IndexDdl,
+    sqlite: SqliteIndexDdl,
 };
 export function indexDdlFor(dialect) {
     return new INDEX_DDL[dialect.dialectName](dialect);

package/dist/migrate/ddl/indexDdl.d.ts

@@ -37,6 +37,8 @@ export declare class IndexDdl<D extends AbstractSqlDialect = AbstractSqlDialect>
     protected readonly indexTypeKeywords: ReadonlyMap<IndexType, string>;
     /** The keyword an index type replaces `INDEX` with, or `INDEX` for the types that do not. */
     protected indexKeyword(index: IndexSchema): string;
+    /** What the index is over, between the parentheses: a fulltext one's columns as a search matches them, else its entries. */
+    protected indexTarget(index: IndexSchema): string;
     /** One index entry: what is indexed, its operator class if any, then its stored order. */
     protected indexColumn(entry: IndexColumnSchema, index: IndexSchema): string;
     /**

package/dist/migrate/ddl/indexDdl.js

@@ -1,7 +1,7 @@
 import { jsonTypeMode } from '../../dialect/jsonSql.js';
 import { INDEX_TYPES } from '../../schema/types.js';
 import { INDEX_FEATURE_LABELS, } from '../../type/index.js';
-import { getKeys } from '../../util/index.js';
+import { fulltextConfig, getKeys } from '../../util/index.js';
 /**
  * What in an index asks for each feature. A `Record` over the feature union rather than a list, so a
  * feature added to {@link INDEX_FEATURE_LABELS} cannot reach a dialect without the test that decides
@@ -45,7 +45,7 @@ export class IndexDdl {
         assertIndexFeatures(index, this.indexFeatures, this.dialect.dialectName);
         const unique = index.unique ? 'UNIQUE ' : '';
         const ifNotExists = (opts.ifNotExists ?? this.dialect.features.indexIfNotExists) ? 'IF NOT EXISTS ' : '';
-        const columns = index.entries.map((entry) => this.indexColumn(entry, index)).join(', ');
+        const columns = this.indexTarget(index);
         return (`CREATE ${unique}${this.indexKeyword(index)} ${ifNotExists}${this.dialect.escapeId(index.name)} ` +
             `ON ${this.dialect.escapeId(tableName)}${this.indexAccessMethod(index)} (${columns})` +
             `${this.indexInclude(index)}${this.indexTuning(index)}${this.indexPredicate(index)};`);
@@ -78,6 +78,14 @@ export class IndexDdl {
     indexKeyword(index) {
         return (index.type && this.indexTypeKeywords.get(index.type)) || 'INDEX';
     }
+    /** What the index is over, between the parentheses: a fulltext one's columns as a search matches them, else its entries. */
+    indexTarget(index) {
+        if (index.type === 'fulltext' && !index.entries.some((entry) => entry.expression)) {
+            const columns = index.entries.map((entry) => this.dialect.escapeId(entry.column));
+            return this.dialect.textSearchTarget(columns, fulltextConfig(index));
+        }
+        return index.entries.map((entry) => this.indexColumn(entry, index)).join(', ');
+    }
     /** One index entry: what is indexed, its operator class if any, then its stored order. */
     indexColumn(entry, index) {
         return `${this.indexColumnTarget(entry)}${this.indexColumnOpsClass(entry, index)}${this.indexColumnOrder(entry)}`;

package/dist/migrate/ddl/pgIndexDdl.d.ts

@@ -2,9 +2,8 @@ import type { IndexColumnSchema, IndexSchema } from '../../type/index.js';
 import { IndexDdl } from './indexDdl.js';
 /** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
 export declare class PgIndexDdl extends IndexDdl {
-    /** Postgres 18's `pg_am`, with pgvector's two. */
+    /** Postgres 18's `pg_am`, with pgvector's two, and `fulltext`, which builds a `gin` one. */
     protected readonly indexTypes: Set<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch">;
-    protected readonly indexTypeHints: ReadonlyMap<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch", string>;
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
     /** pgvector's own index types; CockroachDB's native one widens this. */
     protected isVectorIndex(index: IndexSchema): boolean;
@@ -27,6 +26,6 @@ export declare class CockroachIndexDdl extends PgIndexDdl {
     protected isVectorIndex(index: IndexSchema): boolean;
     protected indexKeyword(index: IndexSchema): string;
     protected indexAccessMethod(index: IndexSchema): string;
-    /** None of pgvector's knobs: `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
-    protected indexTuning(): string;
+    /** Its build-time candidate list alone: pgvector's `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
+    protected indexTuning(index: IndexSchema): string;
 }

package/dist/migrate/ddl/pgIndexDdl.js

@@ -1,12 +1,8 @@
 import { unsupportedVectorMetric } from '../../type/vector.js';
 import { IndexDdl } from './indexDdl.js';
-/** `$text` computes its `TO_TSVECTOR` per row, which no index over the raw columns serves. */
-const PG_INDEX_TYPE_HINTS = new Map([
-    ['fulltext', '. $text needs none there; name the columns it searches with $fields.'],
-]);
 /** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
 export class PgIndexDdl extends IndexDdl {
-    /** Postgres 18's `pg_am`, with pgvector's two. */
+    /** Postgres 18's `pg_am`, with pgvector's two, and `fulltext`, which builds a `gin` one. */
     indexTypes = new Set([
         'btree',
         'hash',
@@ -15,8 +11,8 @@ export class PgIndexDdl extends IndexDdl {
         'brin',
         'hnsw',
         'ivfflat',
+        'fulltext',
     ]);
-    indexTypeHints = PG_INDEX_TYPE_HINTS;
     indexFeatures = new Set([
         'expression',
         'partial',
@@ -30,6 +26,9 @@ export class PgIndexDdl extends IndexDdl {
         return index.type === 'hnsw' || index.type === 'ivfflat';
     }
     indexAccessMethod(index) {
+        if (index.type === 'fulltext') {
+            return ' USING gin';
+        }
         return index.type ? ` USING ${index.type}` : '';
     }
     /**
@@ -75,9 +74,8 @@ export class PgIndexDdl extends IndexDdl {
 export class CockroachIndexDdl extends PgIndexDdl {
     indexFeatures = new Set(['expression', 'partial', 'include', 'jsonPath']);
     /** v26.3 answers `hash` and `brin` "unimplemented", `ivfflat` "unrecognized"; `hnsw` builds its vector index. */
-    indexTypes = new Set(['btree', 'gin', 'gist', 'hnsw', 'vector']);
+    indexTypes = new Set(['btree', 'gin', 'gist', 'hnsw', 'vector', 'fulltext']);
     indexTypeHints = new Map([
-        ...PG_INDEX_TYPE_HINTS,
         ['ivfflat', "; declare type: 'vector' instead"],
     ]);
     isNativeVectorIndex(index) {
@@ -92,8 +90,10 @@ export class CockroachIndexDdl extends PgIndexDdl {
     indexAccessMethod(index) {
         return this.isNativeVectorIndex(index) ? '' : super.indexAccessMethod(index);
     }
-    /** None of pgvector's knobs: `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
-    indexTuning() {
-        return '';
+    /** Its build-time candidate list alone: pgvector's `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
+    indexTuning(index) {
+        return this.isVectorIndex(index) && index.efConstruction !== undefined
+            ? ` WITH (build_beam_size = ${index.efConstruction})`
+            : '';
     }
 }

package/dist/migrate/ddl/sqliteIndexDdl.d.ts

@@ -0,0 +1,11 @@
+import type { IndexColumnSchema, IndexSchema } from '../../type/index.js';
+import { IndexDdl } from './indexDdl.js';
+/**
+ * SQLite's `CREATE INDEX`, which names no index type. A vector index is libSQL's DiskANN where the dialect
+ * can index its metric, and a plain index on an engine with none, so an entity written for Postgres migrates.
+ */
+export declare class SqliteIndexDdl extends IndexDdl {
+    protected indexColumn(entry: IndexColumnSchema, index: IndexSchema): string;
+    /** The metric libSQL's index names, or `undefined` where the index is no vector index or the engine has none. */
+    private vectorIndexMetric;
+}