uql-orm 0.19.0 → 0.20.1

package/dist/sqlite/sqliteDialect.js

@@ -1,8 +1,6 @@
 import { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
-import { buildElemMatchConditions } from '../dialect/jsonArrayElemMatchUtils.js';
+import { JSON_ELEM_ALIAS_PREFIX, JSON_PULL_ALIAS, jsonAssignCall, jsonElemExists, jsonPath, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
 import { getMeta } from '../entity/index.js';
-import { escapeAnsiSqlLiteral } from '../util/ansiSqlLiteral.js';
-import { hasKeys } from '../util/index.js';
 export class SqliteDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for SQLite and SQLite-derived dialects. */
     featureDefaults = {
@@ -76,54 +74,39 @@ export class SqliteDialect extends AbstractSqlDialect {
         }
         super.compare(ctx, entity, key, val, opts);
     }
-    compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
-        switch (op) {
-            case '$elemMatch':
-                this.buildElemMatchCondition(ctx, entity, key, val, opts);
-                break;
-            case '$all': {
-                // SQLite: Check JSON array contains all values using multiple json_each subqueries
-                const values = val;
-                const conditions = values
-                    .map((v) => {
-                    ctx.pushValue(JSON.stringify(v));
-                    return `EXISTS (SELECT 1 FROM json_each(${this.escapeId(key)}) WHERE value = json(?))`;
-                })
-                    .join(' AND ');
-                ctx.append(`(${conditions})`);
-                break;
-            }
-            case '$size':
-                // SQLite: Check JSON array length
-                // e.g., json_array_length(roles) = 3, or json_array_length(roles) >= 2
-                this.buildSizeComparison(ctx, () => {
-                    ctx.append('json_array_length(');
-                    this.getComparisonKey(ctx, entity, key, opts);
-                    ctx.append(')');
-                }, val);
-                break;
-            default:
-                super.compareFieldOperator(ctx, entity, key, op, val, opts);
-        }
-    }
     /**
-     * Build $elemMatch condition for SQLite JSON arrays.
-     * Uses EXISTS with json_each and supports nested operators.
+     * SQLite compares an exploded element as whole JSON text, so containment cannot express "this
+     * element includes these keys" - `$elemMatch` always expands to per-field conditions.
      */
-    buildElemMatchCondition(ctx, _entity, key, match, opts) {
-        ctx.append('EXISTS (SELECT 1 FROM json_each(');
-        this.getComparisonKey(ctx, _entity, key, opts);
-        ctx.append(') WHERE ');
-        const conditions = buildElemMatchConditions(match, (field, op, opVal) => this.buildJsonFieldCondition(ctx, (f) => `json_extract(value, '$.${this.escapeJsonKey(f)}')`, field, op, opVal), (field, value) => {
-            // Keep SQLite's placeholder behavior consistent with prior implementation.
-            ctx.pushValue(value);
-            return `json_extract(value, '$.${this.escapeJsonKey(field)}') = ?`;
-        });
-        ctx.append(conditions.join(' AND '));
-        ctx.append(')');
-    }
-    getJsonPathScalarExpr(escapedColumn, jsonPath) {
-        return `json_extract(${escapedColumn}, '$.${this.escapeJsonKey(jsonPath)}')`;
+    jsonContainmentIsPartial = false;
+    /** `json_each` exposes a JSON boolean as `0`/`1` and a number as a number - already comparable. */
+    jsonScalarElemKeepsType = true;
+    /**
+     * Each element is read back as JSON text through `->` at its own `fullkey`, so it compares
+     * correctly whatever its type. `json_each`'s `value` column would not: it unquotes strings (`a`
+     * vs `"a"`), flattens booleans to 0/1, and stringifies objects.
+     */
+    jsonAll(ctx, jsonField, value) {
+        const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+        const from = this.jsonElemFrom(jsonField, [], alias);
+        const conditions = value.map((val) => jsonElemExists(from, [`${jsonField} -> ${alias}.fullkey = ${this.jsonScalarParam(ctx, val)}`]));
+        return `(${conditions.join(' AND ')})`;
+    }
+    jsonSize(ctx, jsonField, value) {
+        return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`json_array_length(${jsonField})`), value));
+    }
+    /** `json_each` yields both scalar and object elements, so one form covers each case. */
+    jsonElemFrom(jsonField, _fields, alias) {
+        return `json_each(${jsonField}) ${alias}`;
+    }
+    jsonElemRef(alias, field, asJson = false) {
+        if (field === undefined) {
+            return `${alias}.value`;
+        }
+        return asJson ? `${alias}.value -> ${jsonPath(field)}` : `json_extract(${alias}.value, ${jsonPath(field)})`;
+    }
+    getJsonPathScalarExpr(escapedColumn, jsonPathStr) {
+        return `json_extract(${escapedColumn}, ${jsonPath(jsonPathStr)})`;
     }
     numericCast(expr) {
         return `CAST(${expr} AS REAL)`;
@@ -133,38 +116,40 @@ export class SqliteDialect extends AbstractSqlDialect {
         ctx.append(' ' + this.returningId(entity));
     }
     upsert(ctx, entity, conflictPaths, payload) {
-        // Use the base (non-RETURNING) insert here: `onConflictUpsert` appends its own RETURNING
-        // after the ON CONFLICT clause, so calling `this.insert` would append it twice.
-        this.onConflictUpsert(ctx, entity, conflictPaths, payload, (c, e, p) => super.insert(c, e, p));
-    }
-    formatJsonUpdate(ctx, escapedCol, value) {
-        let expr = escapedCol;
-        if (hasKeys(value.$merge)) {
-            const merge = value.$merge;
-            expr = `json_set(COALESCE(${escapedCol}, '{}')`;
-            for (const [key, v] of Object.entries(merge)) {
-                expr += `, '$.${this.escapeJsonKey(key)}', json(?)`;
-                ctx.pushValue(JSON.stringify(v));
-            }
-            expr += ')';
-        }
-        if (hasKeys(value.$push)) {
-            const push = value.$push;
-            expr = `json_insert(${expr}`;
-            for (const [key, v] of Object.entries(push)) {
-                expr += `, '$.${this.escapeJsonKey(key)}[#]', json(?)`;
-                ctx.pushValue(JSON.stringify(v));
-            }
-            expr += ')';
-        }
-        if (value.$unset?.length) {
-            const paths = value.$unset.map((k) => `'$.${this.escapeJsonKey(k)}'`).join(', ');
-            expr = `json_remove(${expr}, ${paths})`;
-        }
-        ctx.append(`${escapedCol} = ${expr}`);
+        const meta = getMeta(entity);
+        const updateCtx = this.createContext();
+        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `EXCLUDED.${name}`);
+        const keysStr = this.getUpsertConflictPathsStr(meta, conflictPaths);
+        const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
+        // Use the base (non-RETURNING) insert here: the appended RETURNING below would otherwise
+        // be doubled by `this.insert`'s own.
+        super.insert(ctx, entity, payload);
+        ctx.append(` ON CONFLICT (${keysStr}) ${onConflict} ${this.returningId(entity)}`);
+        ctx.pushValue(...updateCtx.values);
+    }
+    jsonCast(operand) {
+        return `json(${operand})`;
+    }
+    /**
+     * `json_replace` leaves an absent key (and a NULL column) untouched. Elements are read back
+     * through `->` at their own `fullkey` so each keeps its JSON type - `json_each`'s `value` would
+     * flatten booleans to 0/1 and stringify objects.
+     */
+    jsonPullKey(ctx, expr, escapedCol, key, value) {
+        const path = jsonPath(key);
+        const elem = `${escapedCol} -> ${JSON_PULL_ALIAS}.fullkey`;
+        const kept = `SELECT json_group_array(json(${elem})) FROM json_each(${escapedCol}, ${path}) ${JSON_PULL_ALIAS} WHERE ${elem} <> ${this.jsonScalarParam(ctx, value)}`;
+        return `json_replace(${expr}, ${path}, (${kept}))`;
+    }
+    jsonSet(ctx, expr, set, field) {
+        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'json_set', jsonSetTarget(expr, field, `'{}'`), set);
+    }
+    /** `[#]` appends, creating the array when the key is absent. */
+    jsonPush(ctx, expr, push) {
+        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'json_insert', expr, push, '[#]');
     }
-    escape(value) {
-        return escapeAnsiSqlLiteral(value);
+    jsonUnset(_ctx, expr, unset) {
+        return jsonRemoveCall('json_remove', expr, unset);
     }
 }
 //# sourceMappingURL=sqliteDialect.js.map

package/dist/sqlite/sqliteDialect.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqliteDialect.js","sourceRoot":"","sources":["../../src/sqlite/sqliteDialect.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqliteDialect.js","sourceRoot":"","sources":["../../src/sqlite/sqliteDialect.ts"],"names":[],"mappings":"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"}

package/dist/type/dialect.d.ts

@@ -0,0 +1,199 @@
+import type { UpdatePayload } from './entity.js';
+import type { Query, QueryConflictPaths, QueryOptions, QuerySearch } from './query.js';
+import type { QueryAggMap, QueryAggregate, QueryGroupMap } from './queryAggregate.js';
+import type { Type } from './utility.js';
+/**
+ * comparison options.
+ */
+export type QueryComparisonOptions = QueryOptions & {
+    /**
+     * use precedence for the comparison or not.
+     */
+    usePrecedence?: boolean;
+};
+/**
+ * query filter options.
+ */
+export type QueryWhereOptions = QueryComparisonOptions & {
+    /**
+     * clause to be used in the filter.
+     */
+    clause?: 'WHERE' | 'AND' | false;
+};
+export interface QueryContext {
+    append(sql: string): this;
+    addValue(value: unknown): this;
+    pushValue(...values: unknown[]): this;
+    /**
+     * A fresh derived-table/subquery alias, unique within this query: `nextAlias('_uql_elem')` returns
+     * `'_uql_elem_1'`, then `'_uql_elem_2'`, etc. Needed wherever a hook (e.g. exploding a JSON array)
+     * might recurse into itself at a deeper nesting level within the same query - a fixed, reused
+     * alias would let the inner occurrence shadow the outer one it needs to correlate against.
+     */
+    nextAlias(prefix: string): string;
+    readonly sql: string;
+    readonly values: unknown[];
+}
+/**
+ * Capabilities of the database driver (transport layer).
+ */
+export interface DriverCapabilities {
+    /**
+     * Whether JSON bind parameters are cast via text first (`($n::text)::jsonb`).
+     * Bun SQL PostgreSQL uses this for reliable jsonb merge/push; `pg` does not.
+     */
+    readonly explicitJsonCast: boolean;
+    /**
+     * Whether the driver natively supports JS arrays for the underlying database type.
+     * `PgDialect` keeps this `true` for node-postgres; Bun SQL PostgreSQL uses `false` and
+     * `toPgArray` string literals instead.
+     */
+    readonly nativeArrays: boolean;
+    /** Whether the dialect natively supports the JSONB binary JSON type (Postgres/CockroachDB). */
+    readonly supportsJsonb: boolean;
+}
+/**
+ * How a dialect surfaces the IDs generated by an INSERT statement:
+ * - `'returning'`: the statement itself returns one row per inserted record (`RETURNING`,
+ *   or MongoDB's `insertedIds`), so IDs are exact for every row.
+ * - `'firstId'`: the driver header only exposes the first generated ID (MySQL `insertId`);
+ *   the remaining IDs are inferred by incrementing it.
+ * - `'lastId'`: the driver header only exposes the last generated ID (SQLite `lastInsertRowid`);
+ *   the remaining IDs are inferred backwards from it.
+ */
+export type InsertIdSource = 'returning' | 'firstId' | 'lastId';
+/**
+ * Features of the database engine (SQL syntax layer).
+ */
+export interface EngineFeatures {
+    readonly ifNotExists: boolean;
+    readonly indexIfNotExists: boolean;
+    readonly dropTableCascade: boolean;
+    readonly renameColumn: boolean;
+    readonly foreignKeyAlter: boolean;
+    /** Whether the dialect supports inline COMMENT on columns (MySQL/MariaDB). */
+    readonly columnComment: boolean;
+    /**
+     * How vector indexes are emitted: inline in CREATE TABLE (MySQL/MariaDB), a standalone
+     * `CREATE INDEX ... USING <type> (col opclass)` (Postgres/SQLite), or a standalone
+     * `CREATE VECTOR INDEX (col opclass)` with no access-method keyword (CockroachDB's native type).
+     */
+    readonly vectorIndexStyle: 'inline' | 'create' | 'native';
+    /** Whether the dialect requires/allows (n) length constraints on vector types. */
+    readonly vectorSupportsLength: boolean;
+    /** Whether the dialect natively supports the TIMESTAMPTZ alias/type. */
+    readonly supportsTimestamptz: boolean;
+    /** Whether the dialect defaults to TEXT for strings when no length is specified (e.g. Postgres). */
+    readonly defaultStringAsText: boolean;
+}
+export interface DialectFeatures extends EngineFeatures, DriverCapabilities {
+}
+export interface QueryDialect {
+    /**
+     * The dialect features.
+     */
+    readonly features: DialectFeatures;
+    /**
+     * obtains the records matching the given search parameters.
+     * @param ctx the query context
+     * @param entity the target entity
+     * @param q the criteria options
+     * @param opts the query options
+     */
+    find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions): void;
+    /**
+     * counts the number of records matching the given search parameters.
+     * @param ctx the query context
+     * @param entity the target entity
+     * @param q the criteria options
+     * @param opts the query options
+     */
+    count<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
+    /**
+     * insert records.
+     * @param ctx the query context
+     * @param entity the target entity
+     * @param payload the payload
+     * @param opts the query options
+     */
+    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    /**
+     * update records.
+     * @param ctx the query context
+     * @param entity the target entity
+     * @param q the criteria options
+     * @param payload
+     * @param opts the query options
+     */
+    update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): void;
+    /**
+     * upsert records.
+     * @param ctx the query context
+     * @param entity the target entity
+     * @param conflictPaths the conflict paths
+     * @param payload
+     */
+    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
+    /**
+     * delete records.
+     * @param ctx the query context
+     * @param entity the target entity
+     * @param q the criteria options
+     * @param opts the query options
+     */
+    delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
+    /**
+     * escape an identifier.
+     * @param val the value to be escaped
+     * @param forbidQualified don't escape dots
+     * @param addDot use a dot as suffix
+     */
+    escapeId(val: string, forbidQualified?: boolean, addDot?: boolean): string;
+    /**
+     * escape a value.
+     * @param val the value to escape
+     */
+    escape(val: unknown): string;
+    /**
+     * add a value to the query.
+     * @param values the values array
+     * @param value the value to add
+     */
+    addValue(values: unknown[], value: unknown): string;
+    /**
+     * normalizes a value according to the dialect.
+     * @param value the value to normalize
+     */
+    normalizeValue(value: unknown): unknown;
+    /**
+     * create a new query context.
+     */
+    createContext(): QueryContext;
+}
+/**
+ * Supported SQL dialect identifiers.
+ */
+export type SqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb' | 'sqlite';
+/**
+ * Minimal dialect interface exposing escapeIdChar for SQL operations
+ */
+export interface SqlQueryDialect extends QueryDialect {
+    /**
+     * The SQL dialect name (postgres, mysql, mariadb, sqlite).
+     */
+    readonly dialectName: SqlDialectName;
+    /**
+     * the escape character for identifiers.
+     */
+    readonly escapeIdChar: '"' | '`';
+    /**
+     * Build an aggregate query.
+     */
+    aggregate<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(ctx: QueryContext, entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): void;
+    /**
+     * Get the placeholder for a parameter at the given index (1-based).
+     * Default: '?' for MySQL/MariaDB/SQLite, '$n' for PostgreSQL.
+     */
+    placeholder(index: number): string;
+}
+//# sourceMappingURL=dialect.d.ts.map

package/dist/type/dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect.d.ts","sourceRoot":"","sources":["../../src/type/dialect.ts"],"names":[],"mappings":"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"}

package/dist/type/dialect.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dialect.js.map

package/dist/type/dialect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect.js","sourceRoot":"","sources":["../../src/type/dialect.ts"],"names":[],"mappings":""}

package/dist/type/entity.d.ts

@@ -1,6 +1,8 @@
 import type { IndexType } from '../schema/types.js';
-import type { FilterMeta, FilterOptions, QueryRaw, VectorDistance } from './query.js';
-import type { Json, Scalar, Type } from './utility.js';
+import type { FilterOptions } from './query.js';
+import type { QueryRaw } from './queryRaw.js';
+import type { Json, Scalar, Type, Unpacked } from './utility.js';
+import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /**
  * Allow to customize the name of the property that identifies an entity
  */
@@ -33,10 +35,10 @@ type IsJson<T> = '__json' extends keyof T ? true : false;
 /** The payload `P` of a branded `Json<P>`, or `never` for any non-JSON type. */
 type UnwrapJson<T> = IsJson<T> extends true ? (T extends Json<infer P> ? P : never) : never;
 /**
- * The `Json` payload of a field value `V`: both `Json<T>` and `Json<T>[]` yield `T`;
- * `never` when `V` is not a JSON field. Exactly one arm is ever non-`never`.
+ * The `Json` payload of a field value `V`: both `Json<T>` and `Json<T>[]` yield `T` (via
+ * `Unpacked`, a no-op for the non-array case); `never` when `V` is not a JSON field.
  */
-type JsonPayload<V> = UnwrapJson<NonNullable<V>> | (NonNullable<V> extends readonly (infer U)[] ? UnwrapJson<NonNullable<U>> : never);
+type JsonPayload<V> = UnwrapJson<NonNullable<Unpacked<NonNullable<V>>>>;
 /**
  * Recursively derives dot-notation key paths from a JSON payload type. Handles every shape at
  * entry: an untyped (`unknown`) payload accepts any suffix via a `string` pattern, scalars are
@@ -69,46 +71,60 @@ type PathValue<T, P extends string> = unknown extends T ? unknown : NonNullable<
  */
 export type JsonFieldPathValue<E, P extends string> = P extends `${infer F}.${infer Rest}` ? F extends FieldKey<E> ? [JsonPayload<E[F]>] extends [never] ? unknown : PathValue<JsonPayload<E[F]>, Rest> : unknown : unknown;
 /**
- * Extracts only the array-typed keys from `T`, mapping each to its element type.
- * Used by `$push` to provide type-safe append targets. Uses `readonly (infer U)[]` to match the
- * rest of the JSON machinery, so a `readonly` array payload keeps its `$push` target.
+ * Extracts only the array-typed keys from `T`, mapping each to its element type via `Unpacked`.
+ * Used by `$push` and `$pull` to provide type-safe element targets.
  */
-export type JsonPushFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends readonly unknown[] ? K & string : never]?: NonNullable<T[K]> extends readonly (infer U)[] ? U : never;
+export type JsonArrayFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends readonly unknown[] ? K & string : never]?: Unpacked<NonNullable<T[K]>>;
 };
 /**
- * Operator shape accepted by JSON/JSONB fields in update payloads.
- * Provides type-safe `$merge`, `$unset`, and `$push` operations with IDE autocomplete.
+ * Operator shape accepted by JSON/JSONB fields in update payloads: `$set`/`$unset` target object
+ * keys, `$push`/`$pull` target array elements. All four are type-safe with IDE autocomplete.
+ *
+ * `$set` is shallow: it assigns the given top-level keys and leaves the rest untouched (it is not
+ * an RFC 7396 recursive merge). `$pull` removes *every* element equal to the given value.
+ *
+ * Operators are applied `$pull` -> `$set` -> `$push` -> `$unset`, so any combination - including
+ * `$pull` and `$push` on the same key - yields the same result on every dialect.
  *
  * @example
  * ```ts
- * // merge only - autocompletes keys from the JSON field's inner type
- * querier.updateOneById(Company, id, { kind: { $merge: { public: 1 } } });
+ * // set only - autocompletes keys from the JSON field's inner type
+ * querier.updateOneById(Company, id, { kind: { $set: { public: 1 } } });
  * // unset only - autocompletes keys from the JSON field's inner type
  * querier.updateOneById(Company, id, { kind: { $unset: ['private'] } });
- * // push to array - autocompletes array keys, value matches element type
- * querier.updateOneById(Company, id, { data: { $push: { tags: 'new-tag' } } });
- * // combine all three
- * querier.updateOneById(Company, id, { kind: { $merge: { public: 1 }, $push: { tags: 'x' }, $unset: ['private'] } });
+ * // append to / remove from an array - autocompletes array keys, value matches element type
+ * querier.updateOneById(Company, id, { kind: { $push: { tags: 'new-tag' } } });
+ * querier.updateOneById(Company, id, { kind: { $pull: { tags: 'stale-tag' } } });
+ * // combine
+ * querier.updateOneById(Company, id, { kind: { $set: { public: 1 }, $push: { tags: 'x' }, $unset: ['private'] } });
  * ```
  */
 export type JsonUpdateOp<T = unknown> = {
-    readonly $merge?: Partial<T>;
-    readonly $unset?: (keyof T & string)[];
-    readonly $push?: JsonPushFields<T>;
+    readonly $set?: Partial<T>;
+    readonly $unset?: unknown extends T ? string[] : (keyof T & string)[];
+    readonly $push?: JsonArrayFields<T>;
+    readonly $pull?: JsonArrayFields<T>;
 };
 /**
- * Accepted value for a single field in an update payload.
- * - JSON/JSONB fields (detected via {@link UnwrapJson}, whose {@link IsJson} guard avoids the
- *   non-discriminating bare `Json<infer T>` match that would offer `$merge`/`$unset` on plain
- *   scalar fields) additionally accept `JsonUpdateOp<T>` for `$merge`/`$unset`/`$push` operations.
- * - All fields accept `QueryRaw` for raw SQL expressions (e.g. `raw('NOW()')`).
+ * The {@link JsonUpdateOp} a field accepts, or `never` where the operators do not apply:
+ * - Non-JSON fields. {@link UnwrapJson}'s {@link IsJson} guard avoids the non-discriminating bare
+ *   `Json<infer T>` match that would otherwise offer `$set`/`$unset` on plain scalar fields.
+ * - `Json<T[]>` payloads. All four operators address object keys of the JSON document, so on an
+ *   array column none is meaningful: PostgreSQL's `||` would concatenate arrays while
+ *   `JSON_SET(arr, '$.k', v)` is a no-op on MySQL and SQLite. Replace the whole value instead.
+ *   `Json<unknown>` stays permissive, since `unknown` is not an array.
  */
-type UpdateFieldValue<V> = [UnwrapJson<NonNullable<V>>] extends [never] ? V | QueryRaw : V | JsonUpdateOp<UnwrapJson<NonNullable<V>>> | QueryRaw;
+type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? never : T extends readonly unknown[] ? never : JsonUpdateOp<T>;
+/**
+ * Accepted value for a single field in an update payload: the value itself, `QueryRaw` for a raw SQL
+ * expression (e.g. `raw('NOW()')`), and - for JSON object fields - the JSON operators.
+ */
+type UpdateFieldValue<V> = V | QueryRaw | JsonUpdateOpFor<V>;
 /**
  * Payload type for update operations.
  * Widens each field to additionally accept `QueryRaw` or `JsonUpdateOp` (for JSON fields),
- * providing IDE autocomplete for `$merge`/`$push` keys via `Json<infer T>`.
+ * providing IDE autocomplete for `$set`/`$push`/`$pull` keys via `Json<infer T>`.
  */
 export type UpdatePayload<E> = {
     [K in FieldKey<E>]?: UpdateFieldValue<E[K]>;
@@ -308,17 +324,24 @@ export type HookRegistration = {
     readonly methodName: string;
 };
 /**
- * Vector-specific tuning options shared by `@Index` decorator, entity metadata, and migration schema.
- */
-export type VectorIndexOptions = {
-    /** Distance metric for vector indexes - maps to operator class. */
-    distance?: VectorDistance;
-    /** HNSW: max connections per node. */
-    m?: number;
-    /** HNSW: construction search depth. */
-    efConstruction?: number;
-    /** IVFFlat: number of inverted lists. */
-    lists?: number;
+ * Index type paired with the metric it needs. `distance` is required for {@link VectorIndexType}
+ * because omitting it changes the DDL semantics silently: MariaDB's `DISTANCE=` defaults to
+ * euclidean (so a cosine query full-scans instead of using the index) and pgvector has no default
+ * operator class. MongoDB's `vectorSearch` is excluded - its generator emits no metric at all, so
+ * requiring one would demand a value that is dropped.
+ *
+ * The non-vector arm forbids `distance` (rather than just omitting it) because `VectorIndexOptions`
+ * - intersected in below by {@link EntityIndexMeta} - already declares `distance` as optional, for
+ * the sake of the migration/introspection schema types that reuse it without this discriminated
+ * `type`/`distance` pairing. Without the explicit `never` here, that optional `distance` would
+ * survive the intersection and silently typecheck `{ type: 'btree', distance: 'cosine' }`.
+ */
+export type IndexTypeOptions = {
+    type: VectorIndexType;
+    distance: VectorDistance;
+} | {
+    type?: Exclude<IndexType, VectorIndexType>;
+    distance?: never;
 };
 /**
  * Index metadata from @Index decorator.
@@ -330,18 +353,16 @@ export type EntityIndexMeta = {
     name?: string;
     /** Whether index is unique; omit or `false` for a non-unique index (default). */
     unique?: boolean;
-    /** Index type */
-    type?: IndexType;
     /** Partial index condition (WHERE clause) */
     where?: string;
-} & VectorIndexOptions;
+} & VectorIndexOptions & IndexTypeOptions;
 export type EntityMeta<E> = {
     readonly entity: Type<E>;
     name?: string;
     id: IdKey<E>;
     softDelete?: FieldKey<E>;
     /** Named, default-on `$where` filters applied to every query unless bypassed. */
-    filters?: Record<string, FilterMeta<E>>;
+    filters?: Record<string, FilterOptions<E>>;
     fields: {
         [K in FieldKey<E>]?: FieldOptions;
     } & {