uql-orm 0.21.0 → 0.22.0

package/README.md

@@ -9,7 +9,7 @@
 
 <h3>The smartest TypeScript ORM</h3>
 
-<p>Type-safe to the leaf, serializable queries, no codegen, <a href="https://uql-orm.dev/benchmark">extremely fast</a>, and a unified API across Postgres, CockroachDB, MySQL, SQLite, MongoDB, MariaDB, and the edge.</p>
+<p>Type-safe to the leaf, serializable queries, no codegen, <a href="https://uql-orm.dev/benchmark">extremely fast</a>, and unified API across Postgres, CockroachDB, MySQL, SQLite, MongoDB, MariaDB, and the edge.</p>
 
 <p>
   <a href="https://uql-orm.dev"><b>Website</b></a> ·
@@ -29,7 +29,7 @@
 ---
 
 ```sh
-npm install uql-orm pg   # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/client
+npm install uql-orm pg   # or mysql2, mariadb, better-sqlite3, mongodb, @tursodatabase/serverless, @libsql/client
 ```
 
 Decorators also need `reflect-metadata` ([setup](https://uql-orm.dev/getting-started)); the
@@ -49,12 +49,13 @@ from the browser to the server. The same object runs on every supported database
 
 ## Why UQL?
 
-- **The fastest.** Wins [all 8 categories](https://uql-orm.dev/benchmark) of our [open benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), beating even query builders like Knex and Kysely: ~2.4× faster than the runner-up on average, over 4.1M ops/s on simple SELECTs.
+- **The fastest.** Wins [all 8 categories](https://uql-orm.dev/benchmark) of our [open benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), beating even query builders like Knex and Kysely: ~2.3× faster than the runner-up on average, close to 4M ops/s on simple SELECTs.
 - **Light.** Zero dependencies, under 1 MB installed, every dialect included.
 - **Queries are data, not method chains.** Plain JSON in, typed rows out. There's no DSL to learn and nothing to compile.
 - **Type-safe to the leaf.** Operators are gated per field type, and JSON/JSONB dot-paths resolve each path's value type, so `{ age: { $like: 'x' } }` or a typo'd path is a compile error instead of a runtime surprise.
 - **No codegen.** Entities are TypeScript classes, so your code *is* the schema. No `.prisma` file to regenerate, no generated client to keep in sync.
-- **One API everywhere.** PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, LibSQL/Turso, Neon, Cloudflare D1, Bun SQL, and MongoDB.
+- **One API everywhere.** PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, Turso, LibSQL, Neon, Cloudflare D1, Bun SQL, and MongoDB.
+- **First ORM with a native Turso driver.** Turso Cloud over pure `fetch()` with zero native dependencies, so it runs on Cloudflare Workers and Vercel Edge, plus the embedded Rust engine for local-first apps.
 - **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [non-bypassable multi-tenant filters](https://uql-orm.dev/multi-tenancy), [entity-first migrations](https://uql-orm.dev/migrations), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [a REST API from your entities](https://uql-orm.dev/extensions-http).
 
 ## Get started

package/dist/bunSql/bunSqlCockroachDialect.d.ts

@@ -1,5 +1,5 @@
 import { CockroachDialect } from '../cockroachdb/cockroachDialect.js';
-import type { DialectOptions } from '../dialect/abstractDialect.js';
+import type { DialectFeatures } from '../type/index.js';
 /**
  * CockroachDB Dialect specialization for the `bun:sql` driver, which routes CockroachDB
  * connections through its own Postgres wire-protocol implementation (see
@@ -8,5 +8,5 @@ import type { DialectOptions } from '../dialect/abstractDialect.js';
  * (verified directly against a live CockroachDB instance via `bun:sql`).
  */
 export declare class BunSqlCockroachDialect extends CockroachDialect {
-    constructor(options?: DialectOptions);
+    protected readonly featureOverrides: Partial<DialectFeatures>;
 }

package/dist/bunSql/bunSqlCockroachDialect.js

@@ -8,14 +8,8 @@ import { POSTGRES_WIRE_DRIVER_CAPABILITIES } from '../postgres/postgresWireDrive
  * (verified directly against a live CockroachDB instance via `bun:sql`).
  */
 export class BunSqlCockroachDialect extends CockroachDialect {
-    constructor(options = {}) {
-        super({
-            ...options,
-            driverCapabilities: {
-                ...POSTGRES_WIRE_DRIVER_CAPABILITIES,
-                explicitJsonCast: true,
-                ...options.driverCapabilities,
-            },
-        });
-    }
+    featureOverrides = {
+        ...POSTGRES_WIRE_DRIVER_CAPABILITIES,
+        explicitJsonCast: true,
+    };
 }

package/dist/bunSql/bunSqlPostgresDialect.d.ts

@@ -1,5 +1,5 @@
-import type { DialectOptions } from '../dialect/abstractDialect.js';
 import { PostgresDialect } from '../postgres/postgresDialect.js';
+import type { DialectFeatures } from '../type/index.js';
 /**
  * Postgres Dialect specialization for the `bun:sql` driver.
  *
@@ -7,5 +7,5 @@ import { PostgresDialect } from '../postgres/postgresDialect.js';
  * reliably; `PgDialect` omits the text re-cast.
  */
 export declare class BunSqlPostgresDialect extends PostgresDialect {
-    constructor(options?: DialectOptions);
+    protected readonly featureOverrides: Partial<DialectFeatures>;
 }

package/dist/bunSql/bunSqlPostgresDialect.js

@@ -7,14 +7,8 @@ import { POSTGRES_WIRE_DRIVER_CAPABILITIES } from '../postgres/postgresWireDrive
  * reliably; `PgDialect` omits the text re-cast.
  */
 export class BunSqlPostgresDialect extends PostgresDialect {
-    constructor(options = {}) {
-        super({
-            ...options,
-            driverCapabilities: {
-                ...POSTGRES_WIRE_DRIVER_CAPABILITIES,
-                explicitJsonCast: true,
-                ...options.driverCapabilities,
-            },
-        });
-    }
+    featureOverrides = {
+        ...POSTGRES_WIRE_DRIVER_CAPABILITIES,
+        explicitJsonCast: true,
+    };
 }

package/dist/cockroachdb/cockroachDialect.d.ts

@@ -1,6 +1,5 @@
-import type { DialectOptions } from '../dialect/abstractDialect.js';
 import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
-import type { VectorDistance } from '../type/index.js';
+import type { IndexFeature, IndexSchema, VectorDistance } from '../type/index.js';
 /**
  * CockroachDB Dialect.
  * Shares AST/quoting/JSONB/full-text-search/vector-search/upsert logic with Postgres via
@@ -14,6 +13,23 @@ import type { VectorDistance } from '../type/index.js';
  */
 export declare class CockroachDialect extends PgLikeSqlDialect {
     readonly dialectName = "cockroachdb";
-    readonly vectorOpsClass: ReadonlyMap<VectorDistance, string> | undefined;
-    constructor(options?: DialectOptions);
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, {
+        op: string;
+        opsSuffix: string;
+    }>;
+    /**
+     * `NULLS FIRST/LAST` answers "unimplemented: this syntax" and `jsonb_path_ops` "operator class is
+     * not supported" (both verified on v26.2), so neither is offered here.
+     */
+    protected readonly indexFeatures: Set<IndexFeature>;
+    /**
+     * CockroachDB's vector index is native and has its own syntax: `CREATE VECTOR INDEX ... ("col"
+     * vector_cosine_ops)`, with no access-method keyword, and tuning knobs of its own names that UQL
+     * does not map. `type: 'vector'` is its trigger, the same generic value MariaDB's inline index uses.
+     */
+    private isNativeVectorIndex;
+    protected isVectorIndex(index: IndexSchema): boolean;
+    protected indexKeyword(index: IndexSchema): string;
+    protected indexAccessMethod(index: IndexSchema): string;
+    protected indexTuning(index: IndexSchema): string;
 }

package/dist/cockroachdb/cockroachDialect.js

@@ -12,24 +12,39 @@ import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
  */
 export class CockroachDialect extends PgLikeSqlDialect {
     dialectName = 'cockroachdb';
-    // CockroachDB only implements 3 of pgvector's 5 distance metrics. Verified live (both `<+>`/`<~>`
-    // query operators and `vector_l1_ops`/`bit_hamming_ops` index opclasses throw "unimplemented:
-    // operator class ... is not supported") and confirmed in CockroachDB's own docs, "Known
-    // limitations": https://www.cockroachlabs.com/docs/stable/vector-indexes - tracked upstream at
-    // https://github.com/cockroachdb/cockroach/issues/147839. Re-check that issue before adding
-    // `l1`/`hamming` here; they're omitted on purpose, not an oversight.
-    vectorOpsClass = new Map([
-        ['cosine', 'vector_cosine_ops'],
-        ['l2', 'vector_l2_ops'],
-        ['inner', 'vector_ip_ops'],
+    // CockroachDB implements 3 of pgvector's 4 metrics: `<+>` and `vector_l1_ops` throw
+    // "unimplemented: operator class ... is not supported" (verified live on v26.2), which its own docs
+    // list under "Known limitations": https://www.cockroachlabs.com/docs/stable/vector-indexes -
+    // tracked upstream at https://github.com/cockroachdb/cockroach/issues/147839. Re-check that issue
+    // before adding `l1` here; it is omitted on purpose, not an oversight.
+    vectorMetrics = new Map([
+        ['cosine', { op: '<=>', opsSuffix: 'cosine' }],
+        ['l2', { op: '<->', opsSuffix: 'l2' }],
+        ['inner', { op: '<#>', opsSuffix: 'ip' }],
     ]);
-    constructor(options = {}) {
-        super({
-            ...options,
-            driverCapabilities: {
-                vectorIndexStyle: 'native',
-                ...options.driverCapabilities,
-            },
-        });
+    /**
+     * `NULLS FIRST/LAST` answers "unimplemented: this syntax" and `jsonb_path_ops` "operator class is
+     * not supported" (both verified on v26.2), so neither is offered here.
+     */
+    indexFeatures = new Set(['expression', 'include']);
+    /**
+     * CockroachDB's vector index is native and has its own syntax: `CREATE VECTOR INDEX ... ("col"
+     * vector_cosine_ops)`, with no access-method keyword, and tuning knobs of its own names that UQL
+     * does not map. `type: 'vector'` is its trigger, the same generic value MariaDB's inline index uses.
+     */
+    isNativeVectorIndex(index) {
+        return index.type === 'vector';
+    }
+    isVectorIndex(index) {
+        return this.isNativeVectorIndex(index) || super.isVectorIndex(index);
+    }
+    indexKeyword(index) {
+        return this.isNativeVectorIndex(index) ? 'VECTOR INDEX' : super.indexKeyword(index);
+    }
+    indexAccessMethod(index) {
+        return this.isNativeVectorIndex(index) ? '' : super.indexAccessMethod(index);
+    }
+    indexTuning(index) {
+        return this.isNativeVectorIndex(index) ? '' : super.indexTuning(index);
     }
 }

package/dist/d1/d1Querier.d.ts

@@ -35,11 +35,12 @@ export interface D1Database {
     batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
     exec(query: string): Promise<D1ExecResult>;
 }
+/** The only part of a D1 binding the querier uses; a full {@link D1Database} satisfies it. */
+export type D1Preparer = Pick<D1Database, 'prepare'>;
 export declare class D1Querier extends AbstractSqliteQuerier {
-    readonly db: D1Database;
+    readonly db: D1Preparer;
     readonly extra?: ExtraOptions | undefined;
-    constructor(db: D1Database, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
+    constructor(db: D1Preparer, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
-    internalRelease(): Promise<void>;
 }

package/dist/d1/d1Querier.js

@@ -21,7 +21,4 @@ export class D1Querier extends AbstractSqliteQuerier {
         const changes = rows.length || res.meta?.changes || 0;
         return this.buildUpdateResult({ rows, changes, id: res.meta?.last_row_id });
     }
-    async internalRelease() {
-        // no-op
-    }
 }

package/dist/d1/d1SqliteDialect.d.ts

@@ -6,4 +6,11 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
  */
 export declare class D1SqliteDialect extends SqliteDialect {
     readonly maxBindValues: number;
+    /**
+     * D1 loads no extensions (its allowlist is FTS5, JSON and the math functions) and has no vector
+     * functions of its own, so the sqlite-vec names inherited from {@link SqliteDialect} would compile
+     * to SQL that only fails once it reaches the edge. `raw()` is no escape hatch either, hence a
+     * message that names the product that does the job.
+     */
+    protected appendVectorSort(): never;
 }

package/dist/d1/d1SqliteDialect.js

@@ -7,4 +7,13 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export class D1SqliteDialect extends SqliteDialect {
     // Cloudflare D1 caps bound parameters at 100 per query.
     maxBindValues = 100;
+    /**
+     * D1 loads no extensions (its allowlist is FTS5, JSON and the math functions) and has no vector
+     * functions of its own, so the sqlite-vec names inherited from {@link SqliteDialect} would compile
+     * to SQL that only fails once it reaches the edge. `raw()` is no escape hatch either, hence a
+     * message that names the product that does the job.
+     */
+    appendVectorSort() {
+        throw new TypeError('Cloudflare D1 has no vector functions and cannot load sqlite-vec. Use Cloudflare Vectorize for vector search.');
+    }
 }

package/dist/dialect/abstractDialect.d.ts

@@ -20,12 +20,17 @@ export declare abstract class AbstractDialect {
      * {@link DialectOptions.driverCapabilities} overrides. Each concrete dialect declares its own.
      */
     protected abstract readonly featureDefaults: DialectFeatures;
+    /**
+     * How this dialect differs from the family it extends, so a subclass states only its deltas rather
+     * than repeating {@link featureDefaults} in full or injecting them through its constructor.
+     */
+    protected readonly featureOverrides: Partial<DialectFeatures>;
     readonly namingStrategy: NamingStrategy | undefined;
     constructor(options?: DialectOptions);
     /**
-     * Effective features: {@link featureDefaults} merged with any {@link DialectOptions.driverCapabilities}.
-     * Computed lazily (and memoized) because `featureDefaults` is a subclass field, initialized only
-     * after `super()` returns.
+     * Effective features: {@link featureDefaults}, then this dialect's {@link featureOverrides}, then
+     * any per-instance {@link DialectOptions.driverCapabilities}. Computed lazily (and memoized)
+     * because both are subclass fields, initialized only after `super()` returns.
      */
     get features(): DialectFeatures;
     /**

package/dist/dialect/abstractDialect.js

@@ -4,6 +4,11 @@ import { applyFilters, buildQueryWhereAsMap } from '../util/dialect.util.js';
  */
 export class AbstractDialect {
     options;
+    /**
+     * How this dialect differs from the family it extends, so a subclass states only its deltas rather
+     * than repeating {@link featureDefaults} in full or injecting them through its constructor.
+     */
+    featureOverrides = {};
     namingStrategy;
     #features;
     constructor(options = {}) {
@@ -11,12 +16,12 @@ export class AbstractDialect {
         this.namingStrategy = options.namingStrategy;
     }
     /**
-     * Effective features: {@link featureDefaults} merged with any {@link DialectOptions.driverCapabilities}.
-     * Computed lazily (and memoized) because `featureDefaults` is a subclass field, initialized only
-     * after `super()` returns.
+     * Effective features: {@link featureDefaults}, then this dialect's {@link featureOverrides}, then
+     * any per-instance {@link DialectOptions.driverCapabilities}. Computed lazily (and memoized)
+     * because both are subclass fields, initialized only after `super()` returns.
      */
     get features() {
-        this.#features ??= { ...this.featureDefaults, ...this.options.driverCapabilities };
+        this.#features ??= { ...this.featureDefaults, ...this.featureOverrides, ...this.options.driverCapabilities };
         return this.#features;
     }
     /**

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,6 +1,8 @@
-import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationOptions, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
-import { VectorSqlDialect } from './vectorSqlDialect.js';
-export declare abstract class AbstractSqlDialect extends VectorSqlDialect implements QueryDialect, SqlQueryDialect {
+import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationOptions, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { IndexSqlDialect } from './indexSqlDialect.js';
+/** How a column's values are bound: see {@link AbstractSqlDialect.persistKind}. */
+type PersistKind = 'plain' | 'json' | 'vector';
+export declare abstract class AbstractSqlDialect extends IndexSqlDialect implements QueryDialect, SqlQueryDialect {
     abstract readonly dialectName: SqlDialectName;
     abstract readonly escapeIdChar: '"' | '`';
     abstract readonly serialPrimaryKey: string;
@@ -47,6 +49,18 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     returningId<E>(entity: Type<E>): string;
     search<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions): void;
     selectFields<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelectValue<E> | undefined, opts?: QuerySelectOptions, exclude?: QueryExclude<E>): void;
+    /**
+     * The expression a scalar field is read through, the plain column by default. MariaDB reads a
+     * vector column back with `VEC_ToText`, since selecting it raw yields its binary form.
+     */
+    protected selectFieldExpr(escapedColumn: string, _field: FieldOptions): string;
+    /**
+     * The `$text` full-text predicate, which every engine spells differently: `MATCH ... AGAINST`
+     * (MySQL family), `to_tsvector @@ websearch_to_tsquery` (Postgres-wire), an FTS5 `MATCH` against
+     * the table itself (SQLite). No portable form exists, so a dialect without one says so here rather
+     * than inheriting another engine's syntax.
+     */
+    protected appendTextSearch<E>(_ctx: QueryContext, _entity: Type<E>, _meta: EntityMeta<E>, _search: QueryTextSearchOptions<E>): void;
     select<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelectValue<E> | undefined, exclude?: QueryExclude<E>, populate?: QueryPopulate<E>, opts?: QueryOptions, distinct?: boolean, sort?: QuerySortMap<E>): void;
     private resolveRelationAwarePrefix;
     protected selectRelationFields<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelect<E> | undefined, populate: QueryPopulate<E> | undefined, opts?: {
@@ -195,6 +209,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected havingCondition(ctx: QueryContext, expr: string, condition: QueryHavingMap[string]): void;
     find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions): void;
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    /**
+     * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
+     * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
+     */
+    protected appendInsertValues<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
     /**
      * Emit the value for a column a payload record does not provide (the column list is the union
      * across all records). `DEFAULT` delegates to the database default; SQLite overrides this since
@@ -208,13 +227,21 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
     escapeId(val: string, forbidQualified?: boolean, addDot?: boolean): string;
     /**
-     * The single type dispatch for a persisted value. Dialects override {@link appendJsonValue} and
-     * {@link appendVectorValue} rather than this, so the chain runs once per value - overriding this
-     * and delegating back to `super` ran every check twice, measurably slowing every INSERT/UPDATE.
+     * Bind one persisted value, classifying its column on the spot. Dialects override
+     * {@link appendJsonValue} and {@link appendVectorValue} rather than this, so the chain runs once per
+     * value - overriding this and delegating back to `super` ran every check twice, measurably slowing
+     * every INSERT/UPDATE.
      */
     protected formatPersistableValue(ctx: QueryContext, field: FieldOptions | undefined, value: unknown): void;
+    /**
+     * How a column's values are written. A function of the column, not of the value, so a bulk insert
+     * classifies each column once instead of re-deciding per row: a 20-row, 6-column insert asked
+     * `isJsonType` and `isVectorFieldType` 120 times to get the same six answers.
+     */
+    protected persistKind(field: FieldOptions | undefined): PersistKind;
+    /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
+    private writePersistableValue;
     protected appendJsonValue(ctx: QueryContext, value: unknown, _type: JsonColumnType): void;
-    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /**
      * Reads `operand` as a JSON value. Passing the `?` placeholder yields the cast for a bound
      * parameter, and passing an expression re-reads text as JSON - the same SQL either way, which is
@@ -332,3 +359,4 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected numericCast(expr: string): string;
     toString(): string;
 }
+export {};

package/dist/dialect/abstractSqlDialect.js

@@ -1,12 +1,13 @@
 import { getMeta } from '../entity/index.js';
 import { QueryRaw, RAW_ALIAS, RAW_VALUE, } from '../type/index.js';
-import { asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isJsonType, isJsonUpdateOp, isOperatorObject, isOperatorOnlyObject, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isJsonType, isJsonUpdateOp, isOperatorObject, isOperatorOnlyObject, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
+import { IndexSqlDialect } from './indexSqlDialect.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
 import { JSON_ELEM_ALIAS_PREFIX, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
-import { VectorSqlDialect } from './vectorSqlDialect.js';
-export class AbstractSqlDialect extends VectorSqlDialect {
+import { isVectorFieldType } from './vectorCast.js';
+export class AbstractSqlDialect extends IndexSqlDialect {
     isolationLevelStrategy = 'inline';
     alterColumnStrategy = 'single-statement';
     alterColumnSyntax = 'ALTER COLUMN';
@@ -135,7 +136,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 const field = meta.fields[key];
                 if (!field)
                     return;
-                const columnName = this.resolveColumnName(key, field);
                 if (field.virtual) {
                     this.getRawValue(ctx, {
                         value: raw(field.virtual[RAW_VALUE], key),
@@ -143,17 +143,35 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                         escapedPrefix,
                         autoPrefixAlias: opts.autoPrefixAlias,
                     });
+                    return;
                 }
-                else {
-                    ctx.append(escapedPrefix + this.escapeId(columnName));
-                }
-                if (!field.virtual && (columnName !== key || opts.autoPrefixAlias)) {
-                    const aliasStr = prefix + key;
-                    ctx.append(' ' + this.escapeId(aliasStr, true));
+                const columnName = this.resolveColumnName(key, field);
+                const column = escapedPrefix + this.escapeId(columnName);
+                const expr = this.selectFieldExpr(column, field);
+                ctx.append(expr);
+                // An expression needs the alias too, or the row comes back keyed by the expression text.
+                if (expr !== column || columnName !== key || opts.autoPrefixAlias) {
+                    ctx.append(' ' + this.escapeId(prefix + key, true));
                 }
             }
         });
     }
+    /**
+     * The expression a scalar field is read through, the plain column by default. MariaDB reads a
+     * vector column back with `VEC_ToText`, since selecting it raw yields its binary form.
+     */
+    selectFieldExpr(escapedColumn, _field) {
+        return escapedColumn;
+    }
+    /**
+     * The `$text` full-text predicate, which every engine spells differently: `MATCH ... AGAINST`
+     * (MySQL family), `to_tsvector @@ websearch_to_tsquery` (Postgres-wire), an FTS5 `MATCH` against
+     * the table itself (SQLite). No portable form exists, so a dialect without one says so here rather
+     * than inheriting another engine's syntax.
+     */
+    appendTextSearch(_ctx, _entity, _meta, _search) {
+        throw new TypeError(`${this.dialectName} does not support $text full-text search`);
+    }
     select(ctx, entity, select, exclude, populate, opts = {}, distinct, sort) {
         const meta = getMeta(entity);
         const tableName = this.resolveTableName(entity, meta);
@@ -296,16 +314,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             return;
         }
         if (key === '$text') {
-            const search = val;
-            const searchFields = search.$fields ?? getFieldKeys(meta.fields);
-            const fields = searchFields.map((fKey) => {
-                const field = meta.fields[fKey];
-                const columnName = this.resolveColumnName(fKey, field);
-                return this.escapeId(columnName);
-            });
-            ctx.append(`MATCH(${fields.join(', ')}) AGAINST(`);
-            ctx.addValue(search.$value);
-            ctx.append(')');
+            this.appendTextSearch(ctx, entity, meta, val);
             return;
         }
         if (key === '$and' || key === '$or' || key === '$not' || key === '$nor') {
@@ -911,6 +920,18 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         this.search(ctx, entity, q, opts);
     }
     insert(ctx, entity, payload, opts) {
+        this.appendInsertValues(ctx, entity, payload, opts);
+        // Every engine whose ids come back from the statement itself wants the same clause, so it is
+        // appended once here instead of in an identical `insert` override per dialect.
+        if (this.insertIdSource === 'returning') {
+            ctx.append(` ${this.returningId(entity)}`);
+        }
+    }
+    /**
+     * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
+     * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
+     */
+    appendInsertValues(ctx, entity, payload, opts) {
         const meta = getMeta(entity);
         const payloads = fillOnFields(meta, payload, 'onInsert');
         const keys = getInsertFieldKeys(meta, payloads);
@@ -919,10 +940,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const width = keys.length;
         const fields = new Array(width);
         const columns = new Array(width);
+        const kinds = new Array(width);
         for (let i = 0; i < width; i++) {
             const key = keys[i];
-            fields[i] = meta.fields[key];
+            const field = meta.fields[key];
+            fields[i] = field;
             columns[i] = this.escapedColumnName(meta, key);
+            kinds[i] = this.persistKind(field);
         }
         const tableName = this.resolveTableName(entity, meta);
         ctx.append(`INSERT INTO ${this.escapeId(tableName)} (${columns.join(', ')}) VALUES (`);
@@ -939,8 +963,12 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 if (value === undefined) {
                     this.appendDefaultInsertValue(ctx, fields[i]);
                 }
+                else if (kinds[i] === 'plain' && !(value instanceof QueryRaw)) {
+                    // The overwhelmingly common case in a bulk insert, so it binds without a dispatch.
+                    ctx.addValue(value);
+                }
                 else {
-                    this.formatPersistableValue(ctx, fields[i], value);
+                    this.writePersistableValue(ctx, kinds[i], fields[i], value);
                 }
             }
         }
@@ -983,13 +1011,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const updateCtx = this.createContext();
         const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `VALUES(${name})`);
         if (update) {
-            this.insert(ctx, entity, payload);
+            this.appendInsertValues(ctx, entity, payload);
             ctx.append(` ON DUPLICATE KEY UPDATE ${update}`);
             ctx.pushValue(...updateCtx.values);
         }
         else {
             const insertCtx = this.createContext();
-            this.insert(insertCtx, entity, payload);
+            this.appendInsertValues(insertCtx, entity, payload);
             ctx.append(insertCtx.sql.replace(/^INSERT/, 'INSERT IGNORE'));
             ctx.pushValue(...insertCtx.values);
         }
@@ -1045,22 +1073,38 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return escapeSqlId(val, this.escapeIdChar, forbidQualified, addDot);
     }
     /**
-     * The single type dispatch for a persisted value. Dialects override {@link appendJsonValue} and
-     * {@link appendVectorValue} rather than this, so the chain runs once per value - overriding this
-     * and delegating back to `super` ran every check twice, measurably slowing every INSERT/UPDATE.
+     * Bind one persisted value, classifying its column on the spot. Dialects override
+     * {@link appendJsonValue} and {@link appendVectorValue} rather than this, so the chain runs once per
+     * value - overriding this and delegating back to `super` ran every check twice, measurably slowing
+     * every INSERT/UPDATE.
      */
     formatPersistableValue(ctx, field, value) {
+        this.writePersistableValue(ctx, this.persistKind(field), field, value);
+    }
+    /**
+     * How a column's values are written. A function of the column, not of the value, so a bulk insert
+     * classifies each column once instead of re-deciding per row: a 20-row, 6-column insert asked
+     * `isJsonType` and `isVectorFieldType` 120 times to get the same six answers.
+     */
+    persistKind(field) {
+        const type = field?.type;
+        if (isJsonType(type)) {
+            return 'json';
+        }
+        return isVectorFieldType(type) ? 'vector' : 'plain';
+    }
+    /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
+    writePersistableValue(ctx, kind, field, value) {
         if (value instanceof QueryRaw) {
             this.getRawValue(ctx, { value });
             return;
         }
-        const type = field?.type;
-        if (isJsonType(type)) {
-            this.appendJsonValue(ctx, value, type);
+        if (kind === 'json') {
+            this.appendJsonValue(ctx, value, field?.type);
             return;
         }
-        if (type === 'vector' && Array.isArray(value)) {
-            this.appendVectorValue(ctx, value);
+        if (kind === 'vector' && Array.isArray(value)) {
+            this.appendVectorValue(ctx, value, field);
             return;
         }
         ctx.addValue(value);
@@ -1068,9 +1112,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     appendJsonValue(ctx, value, _type) {
         ctx.addValue(value == null ? null : JSON.stringify(value));
     }
-    appendVectorValue(ctx, value) {
-        ctx.addValue(`[${value.join(',')}]`);
-    }
     /**
      * Reads `operand` as a JSON value. Passing the `?` placeholder yields the cast for a bound
      * parameter, and passing an expression re-reads text as JSON - the same SQL either way, which is

package/dist/dialect/index.d.ts

@@ -4,5 +4,6 @@ export { PostgresDialect } from '../postgres/postgresDialect.js';
 export { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
+export * from './indexSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';

package/dist/dialect/index.js

@@ -4,5 +4,6 @@ export { PostgresDialect } from '../postgres/postgresDialect.js';
 export { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
+export * from './indexSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';