@tstdl/base 0.93.27 → 0.93.29

package/orm/server/query-converter.js

@@ -1,10 +1,11 @@
 import { and, Column, eq, gt, gte, inArray, isNotNull, isNull, isSQLWrapper, lt, lte, ne, not, notInArray, or, SQL, sql } from 'drizzle-orm';
+import { PgColumn } from 'drizzle-orm/pg-core';
 import { match } from 'ts-pattern';
 import { NotSupportedError } from '../../errors/not-supported.error.js';
-import { toArray } from '../../utils/array/index.js';
-import { hasOwnProperty, objectEntries } from '../../utils/object/object.js';
+import { hasOwnProperty, mapObject, mapObjectKeysToSnakeCase, objectEntries } from '../../utils/object/object.js';
+import { toSnakeCase } from '../../utils/string/index.js';
 import { assert, assertDefinedPass, isArray, isDefined, isPrimitive, isRegExp, isString, isUndefined } from '../../utils/type-guards.js';
-import { isSimilar, isStrictWordSimilar, isWordSimilar, phraseToTsQuery, plainToTsQuery, setweight, similarity, strictWordSimilarity, toTsQuery, toTsVector, websearchToTsQuery, wordSimilarity } from '../sqls.js';
+import { array, isSimilar, isStrictWordSimilar, isWordSimilar, jsonbBuildObject, phraseToTsQuery, plainToTsQuery, setweight, similarity, strictWordSimilarity, toTsQuery, toTsVector, websearchToTsQuery, wordSimilarity } from '../sqls.js';
 const sqlTrue = sql `true`;
 /**
  * Resolves a target to a Drizzle PgColumn or SQLWrapper.
@@ -82,7 +83,7 @@ export function convertQuery(query, table, columnDefinitionsMap) {
                 break;
             }
             case '$tsvector': {
-                const tsvectorQuery = value.$tsvector;
+                const tsvectorQuery = value;
                 const fields = assertDefinedPass(tsvectorQuery.fields, '`fields` is required for tsvector search.');
                 const convertedFields = fields.map((target) => {
                     const [field, weight] = isArray(target) ? target : [target, undefined];
@@ -98,7 +99,7 @@ export function convertQuery(query, table, columnDefinitionsMap) {
                 break;
             }
             case '$trigram': {
-                const trigramQuery = value.$trigram;
+                const trigramQuery = value;
                 const fields = isArray(trigramQuery.fields) ? trigramQuery.fields : [trigramQuery.fields];
                 const convertedFields = fields.map((target) => resolveTargetColumn(target, table, columnDefinitionsMap));
                 const searchExpression = sql `(${sql.join(convertedFields, sql ` || ' ' || `)})`;
@@ -113,9 +114,29 @@ export function convertQuery(query, table, columnDefinitionsMap) {
                 break;
             }
             case '$parade': {
-                const paradeQuery = value.$parade;
-                const convertedParadeQuery = convertParadeDbQuery(paradeQuery, table, columnDefinitionsMap);
-                conditions.push(sql `${table.id} @@@ ${convertedParadeQuery}`);
+                const paradeQuery = value;
+                if (hasOwnProperty(paradeQuery, 'fields')) {
+                    const { fields, query: searchQuery, conjunction, distance, prefix, transpositionCostOne } = paradeQuery;
+                    const operator = (conjunction == true) ? sql `&&&` : sql `|||`;
+                    const convertedFields = fields.map((target) => resolveTargetColumn(target, table, columnDefinitionsMap));
+                    const searchExpression = sql `(${sql.join(convertedFields, sql ` || ' ' || `)})`;
+                    const casts = [];
+                    if (isDefined(distance) && (distance > 0)) {
+                        const parameters = [
+                            sql.raw(String(distance)),
+                            sql.raw((prefix == true) ? 't' : 'f'),
+                            sql.raw((transpositionCostOne != false) ? 't' : 'f'),
+                        ];
+                        casts.push(sql `::pdb.fuzzy(${sql.join(parameters, sql `, `)})`);
+                    }
+                    const castsSql = sql.join(casts);
+                    const condition = sql `${searchExpression} ${operator} ${searchQuery}${castsSql}`;
+                    conditions.push(condition);
+                }
+                else {
+                    const convertedParadeQuery = convertParadeSpecialQuery(paradeQuery, table, columnDefinitionsMap);
+                    conditions.push(sql `${table.id} @@@ ${convertedParadeQuery}::pdb.query`);
+                }
                 break;
             }
             default: {
@@ -230,34 +251,63 @@ function getCondition(property, value, column, table, columnDefinitionsMap) {
         }
         return isSimilar(column, query);
     }
-    if (hasOwnProperty(value, '$match')) {
-        const queryValue = value.$match;
-        const { query, distance, prefix, conjunctionMode } = isString(queryValue) ? { query: queryValue } : queryValue;
-        const parts = [sql `field => ${column.name}`, sql `value => ${query}`];
-        if (isDefined(distance)) {
-            parts.push(sql `distance => ${distance}`);
+    if (hasOwnProperty(value, '$parade')) {
+        const queryValue = value.$parade;
+        if (isDefined(queryValue.match)) {
+            const { value: matchValue, conjunctionMode, ...options } = queryValue.match;
+            const operator = (conjunctionMode == true) ? sql `&&&` : sql `|||`;
+            const casts = buildParadeCasts(options);
+            return sql `${column} ${operator} ${matchValue}${casts}`;
         }
-        if (isDefined(prefix)) {
-            parts.push(sql `prefix => ${prefix}`);
+        if (isDefined(queryValue.fuzzyTerm)) {
+            const { value: termValue, ...options } = queryValue.fuzzyTerm;
+            const casts = buildParadeCasts(options);
+            return sql `${column} === ${termValue}${casts}`;
         }
-        if (isDefined(conjunctionMode)) {
-            parts.push(sql `conjunction_mode => ${conjunctionMode}`);
+        if (isDefined(queryValue.term)) {
+            const { value: termValue, ...options } = queryValue.term;
+            const casts = buildParadeCasts(options);
+            return sql `${column} === ${termValue}${casts}`;
         }
-        const searchFn = sql `paradedb.match(${sql.join(parts, sql.raw(', '))})`;
-        return sql `${table.id} @@@ ${searchFn}`;
-    }
-    if (hasOwnProperty(value, '$tantivy')) {
-        const queryValue = value.$tantivy;
-        const { query, lenient, conjunctionMode } = isString(queryValue) ? { query: queryValue } : queryValue;
-        const parts = [sql `${query}`];
-        if (isDefined(lenient)) {
-            parts.push(sql `lenient => ${lenient}`);
+        if (isDefined(queryValue.phrase)) {
+            const { phrases, ...options } = queryValue.phrase;
+            const phraseValue = array(phrases.map((phrase) => sql `${phrase}`));
+            const casts = buildParadeCasts(options);
+            return sql `${column} ### ${phraseValue}${casts}`;
+        }
+        if (isDefined(queryValue.proximity)) {
+            const { ordered = false, distance, terms } = queryValue.proximity;
+            const operator = ordered ? sql `##>` : sql `##`;
+            const buildTerm = (term) => {
+                if (isString(term)) {
+                    return sql `${term}`;
+                }
+                if (hasOwnProperty(term, 'regex')) {
+                    const { regex, maxExpansions } = term;
+                    const args = [sql `'${sql.raw(regex)}'`];
+                    if (isDefined(maxExpansions)) {
+                        args.push(sql `${maxExpansions}`);
+                    }
+                    return sql `pdb.prox_regex(${sql.join(args, sql `, `)})`;
+                }
+                if (hasOwnProperty(term, 'array')) {
+                    const args = term.array.map(buildTerm);
+                    return sql `pdb.prox_array(${sql.join(args, sql `, `)})`;
+                }
+                throw new NotSupportedError('Unsupported proximity term type.');
+            };
+            const sqlTerms = terms.map(buildTerm);
+            const proximitySql = sql.join(sqlTerms, sql ` ${operator} ${distance} ${operator} `);
+            return sql `${column} @@@ (${proximitySql})`;
         }
-        if (isDefined(conjunctionMode)) {
-            parts.push(sql `conjunction_mode => ${conjunctionMode}`);
+        if (isDefined(queryValue.termSet)) {
+            const { terms, conjunctionMode } = queryValue.termSet;
+            const operator = (conjunctionMode == true) ? sql `&&&` : sql `===`;
+            const term_set_value = array(terms.map((term) => sql `${term}`));
+            return sql `${column} ${operator} ${term_set_value}`;
         }
-        const searchFn = sql `paradedb.parse(${sql.join(parts, sql.raw(', '))})`;
-        return sql `${table.id} @@@ ${searchFn}`;
+        const convertedParadeQuery = convertParadeComparisonQuery(queryValue);
+        return sql `${column} @@@ ${convertedParadeQuery}::pdb.query`;
     }
     if (hasOwnProperty(value, '$geoShape')) {
         throw new NotSupportedError('$geoShape is not supported.');
@@ -282,74 +332,71 @@ function getTrigramIsSimilarOperator(type = 'phrase') {
         .exhaustive();
 }
 /**
- * Recursively converts a ParadeDbQueryObject into a Drizzle SQL object representing the JSONB structure.
+ * Converts a ParadeComparisonQueryObject into a Drizzle SQL object representing the JSONB structure.
  */
-function convertParadeDbQuery(query, table, columnDefinitionsMap) {
+function convertParadeComparisonQuery(query) {
     const entries = objectEntries(query);
-    assert(entries.length == 1, 'ParadeDB query object must have exactly one key.');
+    assert(entries.length == 1, 'ParadeDB comparison query object must have exactly one key.');
     const [key, queryValue] = entries[0];
-    const buildObject = (properties) => {
-        const chunks = [];
-        for (const [propKey, propValue] of properties) {
-            chunks.push(sql `'${sql.raw(propKey)}', ${propValue}`);
-        }
-        return sql `jsonb_build_object(${sql.join(chunks, sql `, `)})`;
-    };
-    const convertRecursive = (subQuery) => {
-        return convertParadeDbQuery(subQuery, table, columnDefinitionsMap);
-    };
+    const snakeKey = toSnakeCase(key);
     const innerSql = match(key)
-        .with('all', 'empty', () => sql `null`)
-        .with('term', 'fuzzy_term', 'regex', 'phrase', 'match', 'parse_with_field', 'exists', 'range', 'phrase_prefix', 'regex_phrase', 'range_term', 'range_intersects', 'range_contains', 'range_within', (_) => {
-        const properties = [];
-        for (const [propKey, propValue] of objectEntries(queryValue)) {
-            if (propKey == 'field') {
-                const column = resolveTargetColumn(propValue, table, columnDefinitionsMap);
-                properties.push([propKey, column.name]);
-            }
-            else {
-                properties.push([propKey, propValue]);
-            }
-        }
-        return buildObject(properties);
-    })
-        .with('parse', 'more_like_this', () => buildObject(objectEntries(queryValue)))
-        .with('boolean', () => {
-        const properties = [];
-        for (const [propKey, propValue] of objectEntries(queryValue)) {
-            const subQueries = toArray(propValue ?? []).map(convertRecursive);
-            properties.push([propKey, sql `jsonb_build_array(${sql.join(subQueries, sql `, `)})`]);
-        }
-        return buildObject(properties);
+        .with('exists', () => sql `null`)
+        .with('term', 'fuzzyTerm', 'regex', 'phrase', 'match', 'range', 'phrasePrefix', 'regexPhrase', 'termSet', 'rangeTerm', (_) => {
+        const properties = mapObjectKeysToSnakeCase(queryValue);
+        return jsonbBuildObject(properties);
     })
-        .with('boost', 'const_score', () => {
-        const properties = [];
-        for (const [propKey, propValue] of objectEntries(queryValue)) {
-            if (propKey == 'query') {
-                properties.push([propKey, convertRecursive(propValue)]);
-            }
-            else {
-                properties.push([propKey, propValue]);
-            }
-        }
-        return buildObject(properties);
+        .with('proximity', () => {
+        // Proximity is handled directly in getCondition and should not fall back to JSON conversion
+        throw new NotSupportedError('Proximity query should be handled directly and not converted to JSON.');
     })
-        .with('disjunction_max', 'term_set', (_k) => {
-        const properties = [];
-        const subqueryArrayKey = (key == 'disjunction_max') ? 'disjuncts' : 'terms';
-        for (const [propKey, propValue] of objectEntries(queryValue)) {
-            if (propKey == subqueryArrayKey) {
-                const subQueries = propValue.map(convertRecursive);
-                properties.push([propKey, sql `jsonb_build_array(${sql.join(subQueries, sql `, `)})`]);
-            }
-            else {
-                properties.push([propKey, propValue]);
-            }
-        }
-        return buildObject(properties);
+        .exhaustive();
+    return jsonbBuildObject([[snakeKey, innerSql]]);
+}
+/**
+ * Converts a ParadeSpecialQueryObject into a Drizzle SQL object representing the JSONB structure.
+ */
+function convertParadeSpecialQuery(query, table, columnDefinitionsMap) {
+    const entries = objectEntries(query);
+    assert(entries.length == 1, 'ParadeDB special query object must have exactly one key.');
+    const [key, queryValue] = entries[0];
+    const snakeKey = toSnakeCase(key);
+    const innerSql = match(key)
+        .with('all', 'empty', () => sql `null`)
+        .with('moreLikeThis', () => {
+        const { fields, document, ...properties } = mapObjectKeysToSnakeCase(queryValue);
+        const resolvedFields = fields.map((field) => resolveTargetColumn(field, table, columnDefinitionsMap));
+        const columnNames = resolvedFields.map((field) => (field instanceof Column) ? sql `${field.name}` : field);
+        const fieldsArraySql = (columnNames.length > 0) ? array(columnNames) : undefined;
+        const documentJson = isDefined(document) ? JSON.stringify(mapObject(document, (key, value) => [resolveTargetColumn(key, table, columnDefinitionsMap).name, value])) : undefined;
+        return jsonbBuildObject({
+            ...properties,
+            fields: fieldsArraySql,
+            document: documentJson
+        });
     })
         .exhaustive();
-    return buildObject([[key, innerSql]]);
+    return jsonbBuildObject([[snakeKey, innerSql]]);
+}
+function buildParadeCasts(options) {
+    const casts = [];
+    if (isDefined(options.distance) && (options.distance > 0)) {
+        const parameters = [
+            sql.raw(String(options.distance)),
+            sql.raw((options.prefix == true) ? 't' : 'f'),
+            sql.raw((options.transpositionCostOne != false) ? 't' : 'f'),
+        ];
+        casts.push(sql `::pdb.fuzzy(${sql.join(parameters, sql `, `)})`);
+    }
+    if (isDefined(options.slop) && options.slop > 0) {
+        casts.push(sql `::pdb.slop(${sql.raw(String(options.slop))})`);
+    }
+    if (isDefined(options.boost)) {
+        casts.push(sql `::pdb.boost(${sql.raw(String(options.boost))})`);
+    }
+    if (isDefined(options.const)) {
+        casts.push(sql `::pdb.const(${sql.raw(String(options.const))})`);
+    }
+    return sql.join(casts);
 }
 export function getTsQuery(text, language, parser) {
     switch (parser) {

package/orm/server/repository.d.ts

@@ -1,9 +1,9 @@
 import { SQL, type SQLWrapper } from 'drizzle-orm';
 import type { PgColumn, PgInsertValue, PgSelectBuilder, PgUpdateSetSource, SelectedFields } from 'drizzle-orm/pg-core';
 import { afterResolve, resolveArgumentType, type Resolvable } from '../../injector/interfaces.js';
-import type { DeepPartial, Function, OneOrMany, Record, Type } from '../../types/index.js';
+import type { DeepPartial, Function, OneOrMany, Record, SimplifyObject, Type, TypedOmit } from '../../types/index.js';
 import { Entity, type BaseEntity, type EntityMetadataAttributes, type EntityType } from '../entity.js';
-import type { ParadeDbSearchQuery, Query, TrigramSearchQuery, TsVectorSearchQuery } from '../query.js';
+import type { ParadeSearchQuery, Query, TrigramSearchQuery, TsVectorSearchQuery } from '../query/index.js';
 import type { EntityMetadataUpdate, EntityUpdate, LoadManyOptions, LoadOptions, NewEntity, Order, SearchOptions, SearchResult, TargetColumn, TargetColumnPath } from '../repository.types.js';
 import type { Database } from './database.js';
 import type { PgTransaction } from './transaction.js';
@@ -46,9 +46,9 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
     protected trigramSearch(options: SearchOptions<T> & {
         query: TrigramSearchQuery<T>;
     }): Promise<SearchResult<T>[]>;
-    protected paradeDbSearch(options: SearchOptions<T> & {
-        query: ParadeDbSearchQuery<T>;
-    }): Promise<SearchResult<T>[]>;
+    protected paradeDbSearch(options: SimplifyObject<TypedOmit<SearchOptions<T>, 'query'> & {
+        query: ParadeSearchQuery<T>;
+    }>): Promise<SearchResult<T>[]>;
     /**
      * Performs a full-text search and returns entities ranked by relevance.
      * This method dispatches to the appropriate search implementation based on the `method` option.
@@ -475,7 +475,7 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
     protected _mapUpdate(update: EntityUpdate<T>, transformContext: TransformContext): Promise<PgUpdateSetSource<PgTableFromType>>;
     protected _getMetadataUpdate(update?: EntityUpdate<T>): PgUpdateSetSource<PgTableFromType<EntityType<Entity>>> | undefined;
     protected getTransformContext(): Promise<TransformContext>;
-    protected _mapSearchResults(rowsPromise: Promise<Record[]>, scoreColumnName: string, highlightColumnName: string, scoreTransformer?: (rawScore: any) => number | undefined): Promise<SearchResult<T>[]>;
+    protected _mapSearchResults(rows: Record[], scoreTransformer?: (rawScore: any) => number | undefined): Promise<SearchResult<T>[]>;
 }
 /**
  * Injects an EntityRepository instance for the specified entity type.

package/orm/server/repository.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { and, asc, count, desc, eq, inArray, isNull, isSQLWrapper, lte, or, SQL, sql } from 'drizzle-orm';
+import { and, asc, count, desc, eq, inArray, isNull as isSqlNull, isSQLWrapper, lte, or, SQL, sql } from 'drizzle-orm';
 import { match, P } from 'ts-pattern';
 import { CancellationSignal } from '../../cancellation/token.js';
 import { NotFoundError } from '../../errors/not-found.error.js';
@@ -16,8 +16,8 @@ import { distinct, toArray } from '../../utils/array/array.js';
 import { mapAsync } from '../../utils/async-iterable-helpers/map.js';
 import { toArrayAsync } from '../../utils/async-iterable-helpers/to-array.js';
 import { importSymmetricKey } from '../../utils/cryptography.js';
-import { filterUndefinedObjectProperties, fromDeepObjectEntries, fromEntries, objectEntries } from '../../utils/object/object.js';
-import { toSnakeCase } from '../../utils/string/snake-case.js';
+import { fromDeepObjectEntries, fromEntries, objectEntries } from '../../utils/object/object.js';
+import { toSnakeCase } from '../../utils/string/index.js';
 import { cancelableTimeout } from '../../utils/timing.js';
 import { tryIgnoreAsync } from '../../utils/try-ignore.js';
 import { assertDefined, assertDefinedPass, isArray, isBoolean, isDefined, isFunction, isInstanceOf, isString, isUndefined } from '../../utils/type-guards.js';
@@ -32,7 +32,7 @@ import { getTransactionalContextData, injectTransactional, injectTransactionalAs
 const searchScoreColumn = '__tsl_score';
 const searchDistanceColumn = '__tsl_distance';
 const searchHighlightColumn = '__tsl_highlight';
-const bm25ScoreColumn = '__parade_bm25_score';
+const searchHighlightPositionsColumn = '__tsl_highlight_positions';
 export const repositoryType = Symbol('repositoryType');
 /**
  * Configuration class for EntityRepository.
@@ -157,7 +157,8 @@ let EntityRepository = class EntityRepository extends Transactional {
             orderByExpressions.push(desc(score));
         }
         dbQuery = dbQuery.orderBy(...orderByExpressions);
-        return await this._mapSearchResults(dbQuery, searchScoreColumn, searchHighlightColumn);
+        const rows = await dbQuery;
+        return await this._mapSearchResults(rows);
     }
     async trigramSearch(options) {
         const { query: { $trigram: trigramOptions }, rank, filter } = options;
@@ -200,27 +201,36 @@ let EntityRepository = class EntityRepository extends Transactional {
             orderByExpressions.push(distanceColumn); // order by distance ascending
         }
         dbQuery = dbQuery.orderBy(...orderByExpressions);
-        return await this._mapSearchResults(dbQuery, searchDistanceColumn, searchHighlightColumn, (rawDistance) => 1 - rawDistance);
+        const rows = await dbQuery;
+        return await this._mapSearchResults(rows, (rawDistance) => 1 - rawDistance);
     }
     async paradeDbSearch(options) {
-        const { query: { $parade: paradeQuery }, score: scoreOption = true, highlight, filter } = options;
+        const { query, score: scoreOption = true, highlight, filter } = options;
         const keyField = this.#table.id;
-        const paradeNativeQuery = convertQuery({ $parade: paradeQuery }, this.#table, this.#columnDefinitionsMap);
+        const paradeNativeQuery = this.convertQuery(query);
         const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.resolveTargetColumn(column)]));
         let score;
         if (scoreOption) {
             const rawScore = sql `pdb.score(${keyField})`;
-            score = (isFunction(scoreOption) ? scoreOption(rawScore) : rawScore).as(bm25ScoreColumn);
-            selection[bm25ScoreColumn] = score;
+            score = (isFunction(scoreOption) ? scoreOption(rawScore) : rawScore).as(searchScoreColumn);
+            selection[searchScoreColumn] = score;
         }
         if (isDefined(highlight)) {
-            const { source, ...highlightOptions } = (isString(highlight) || isInstanceOf(highlight, SQL))
+            const { source, includePositions, ...highlightOptionsAny } = (isString(highlight) || isInstanceOf(highlight, SQL))
                 ? { source: highlight }
                 : highlight;
+            const highlightOptions = highlightOptionsAny;
             const sourceSql = isInstanceOf(source, SQL) ? source : sql `${this.resolveTargetColumn(source)}`;
-            const highlightParts = objectEntries(filterUndefinedObjectProperties(highlightOptions)).map(([key, value]) => sql `${sql.raw(toSnakeCase(key))} => ${sql `${value}`}`);
-            const snippet = sql `pdb.snippet(${sql.join([sourceSql, ...highlightParts], sql.raw(', '))})`;
-            selection[searchHighlightColumn] = snippet.as(searchHighlightColumn);
+            const functionName = (highlightOptions.multiple == true) ? 'snippets' : 'snippet';
+            const highlightParts = objectEntries(highlightOptions)
+                .filter(([key, value]) => (key != 'multiple') && isDefined(value))
+                .map(([key, value]) => sql `${sql.raw(toSnakeCase(key))} => ${sql `${value}`}`);
+            const snippetParameters = sql.join([sourceSql, ...highlightParts], sql.raw(', '));
+            const highlightSql = sql `pdb.${sql.raw(functionName)}(${snippetParameters})`;
+            selection[searchHighlightColumn] = highlightSql.as(searchHighlightColumn);
+            if (includePositions == true) {
+                selection[searchHighlightPositionsColumn] = sql `array_to_json(pdb.snippet_positions(${sourceSql}))`.as(searchHighlightPositionsColumn);
+            }
         }
         const whereClause = isDefined(filter)
             ? and(this.convertQuery(filter), paradeNativeQuery)
@@ -241,7 +251,7 @@ let EntityRepository = class EntityRepository extends Transactional {
             const order = isFunction(options.order)
                 ? options.order({
                     get score() {
-                        return assertDefinedPass(score, 'Score is disabled.');
+                        return assertDefinedPass(score, 'Score is not enabled.');
                     },
                 })
                 : options.order;
@@ -251,7 +261,8 @@ let EntityRepository = class EntityRepository extends Transactional {
             orderByExpressions.push(desc(score));
         }
         dbQuery = dbQuery.orderBy(...orderByExpressions);
-        return await this._mapSearchResults(dbQuery, bm25ScoreColumn, searchHighlightColumn);
+        const rows = await dbQuery;
+        return await this._mapSearchResults(rows);
     }
     /**
      * Performs a full-text search and returns entities ranked by relevance.
@@ -719,7 +730,7 @@ let EntityRepository = class EntityRepository extends Transactional {
         if (!this.hasMetadata) {
             return await this.tryHardDelete(id);
         }
-        const sqlQuery = and(isNull(this.#tableWithMetadata.deleteTimestamp), this.convertQuery(eq(this.#table.id, id)));
+        const sqlQuery = and(isSqlNull(this.#tableWithMetadata.deleteTimestamp), this.convertQuery(eq(this.#table.id, id)));
         const [row] = await this.session
             .update(this.#tableWithMetadata)
             .set({
@@ -760,7 +771,7 @@ let EntityRepository = class EntityRepository extends Transactional {
             return await this.tryHardDeleteByQuery(query);
         }
         const idQuery = this.getIdLimitQuery(query).for('update');
-        const sqlQuery = and(isNull(this.#tableWithMetadata.deleteTimestamp), inArray(this.#table.id, idQuery));
+        const sqlQuery = and(isSqlNull(this.#tableWithMetadata.deleteTimestamp), inArray(this.#table.id, idQuery));
         const [row] = await this.session
             .update(this.#tableWithMetadata)
             .set({
@@ -796,7 +807,7 @@ let EntityRepository = class EntityRepository extends Transactional {
         if (!this.hasMetadata) {
             return await this.hardDeleteManyByQuery(query);
         }
-        const sqlQuery = and(isNull(this.#tableWithMetadata.deleteTimestamp), this.convertQuery(query));
+        const sqlQuery = and(isSqlNull(this.#tableWithMetadata.deleteTimestamp), this.convertQuery(query));
         const rows = await this.session
             .update(this.#tableWithMetadata)
             .set({
@@ -956,7 +967,7 @@ let EntityRepository = class EntityRepository extends Transactional {
         if (!this.hasMetadata || (options?.withDeleted == true)) {
             return sql;
         }
-        return and(isNull(this.#tableWithMetadata.deleteTimestamp), sql);
+        return and(isSqlNull(this.#tableWithMetadata.deleteTimestamp), sql);
     }
     /**
      * Maps multiple database rows to an array of entities.
@@ -1131,15 +1142,15 @@ let EntityRepository = class EntityRepository extends Transactional {
         }
         return await this.#transformContext;
     }
-    async _mapSearchResults(rowsPromise, scoreColumnName, highlightColumnName, scoreTransformer = (s) => s) {
-        const rows = await rowsPromise;
+    async _mapSearchResults(rows, scoreTransformer = (s) => s) {
         const transformContext = await this.getTransformContext();
         return await toArrayAsync(mapAsync(rows, async (row) => {
-            const { [scoreColumnName]: rawScore, [highlightColumnName]: highlight, ...entityRow } = row;
+            const { [searchScoreColumn]: rawScore, [searchHighlightColumn]: highlight, [searchHighlightPositionsColumn]: highlightPositions, ...entityRow } = row;
             return {
                 entity: await this._mapToEntity(entityRow, transformContext),
                 score: scoreTransformer(rawScore),
                 highlight: highlight,
+                highlightPositions,
             };
         }));
     }

package/orm/sqls.d.ts

@@ -1,6 +1,6 @@
 import { type AnyColumn, type Column, type SQL, type SQLChunk } from 'drizzle-orm';
 import type { GetSelectTableSelection, SelectResultField, TableLike } from 'drizzle-orm/query-builders/select.types';
-import type { TsVectorWeight } from './query.js';
+import type { TsVectorWeight } from './query/index.js';
 import type { Uuid } from './types.js';
 /** Drizzle SQL helper for getting the current transaction's timestamp. Returns a Date object. */
 export declare const TRANSACTION_TIMESTAMP: SQL<Date>;
@@ -50,6 +50,8 @@ export type TsHeadlineOptions = {
      */
     fragmentDelimiter?: string;
 };
+export declare function array<T>(values: SQL<T>[]): SQL<T[]>;
+export declare function array<T = unknown>(values: SQLChunk[]): SQL<T[]>;
 export declare function autoAlias<T>(column: AnyColumn<{
     data: T;
 }>): SQL.Aliased<T>;
@@ -118,7 +120,7 @@ export declare function greatest<T extends (Column | SQL | number)[]>(...values:
 }[number]>>;
 export declare function greatest<T>(...values: T[]): SQL<SelectResultField<T>>;
 export declare function unnest<T>(array: SQL<readonly T[]>): SQL<T>;
-export declare function toTsVector(language: string | SQL, text: string | Column | SQLChunk): SQL<string>;
+export declare function toTsVector(language: string | SQLChunk, text: string | SQLChunk): SQL<string>;
 export declare function tsvectorToArray(tsvector: SQL): SQL<string[]>;
 /**
  * Creates a PostgreSQL `to_tsquery` function call.
@@ -127,7 +129,7 @@ export declare function tsvectorToArray(tsvector: SQL): SQL<string[]>;
  * @param text The search query text with operators.
  * @returns A Drizzle SQL object representing the tsquery.
  */
-export declare function toTsQuery(language: string | SQL, text: string | SQLChunk): SQL;
+export declare function toTsQuery(language: string | SQLChunk, text: string | SQLChunk): SQL;
 /**
  * Creates a PostgreSQL `plainto_tsquery` function call.
  * This function parses text into tokens and normalizes them, creating a tsquery
@@ -136,7 +138,7 @@ export declare function toTsQuery(language: string | SQL, text: string | SQLChun
  * @param text The search query text.
  * @returns A Drizzle SQL object representing the tsquery.
  */
-export declare function plainToTsQuery(language: string | SQL, text: string | SQLChunk): SQL;
+export declare function plainToTsQuery(language: string | SQLChunk, text: string | SQLChunk): SQL;
 /**
  * Creates a PostgreSQL `phraseto_tsquery` function call.
  * This function is similar to `plainto_tsquery` but creates a tsquery that searches for a phrase.
@@ -144,7 +146,7 @@ export declare function plainToTsQuery(language: string | SQL, text: string | SQ
  * @param text The phrase to search for.
  * @returns A Drizzle SQL object representing the tsquery.
  */
-export declare function phraseToTsQuery(language: string | SQL, text: string | SQLChunk): SQL;
+export declare function phraseToTsQuery(language: string | SQLChunk, text: string | SQLChunk): SQL;
 /**
  * Creates a PostgreSQL `websearch_to_tsquery` function call.
  * This function is similar to `plainto_tsquery` but also handles "quoted phrases"
@@ -153,7 +155,7 @@ export declare function phraseToTsQuery(language: string | SQL, text: string | S
  * @param text The search query text.
  * @returns A Drizzle SQL object representing the tsquery.
  */
-export declare function websearchToTsQuery(language: string | SQL, text: string | SQLChunk): SQL;
+export declare function websearchToTsQuery(language: string | SQLChunk, text: string | SQLChunk): SQL;
 /**
  * Creates a PostgreSQL `setweight` function call.
  * Assigns a weight ('A', 'B', 'C', 'D') to a tsvector.
@@ -186,7 +188,7 @@ export declare function tsRankCd(tsvector: SQL, tsquery: SQL, options?: {
  * Cross-Site Scripting (XSS) vulnerabilities. Ensure the `document` content is
  * properly sanitized before rendering it in a browser if it comes from an untrusted source.
  */
-export declare function tsHeadline(language: string | SQL, document: string | SQL | SQL.Aliased | AnyColumn, tsquery: SQL, options?: TsHeadlineOptions): SQL<string>;
+export declare function tsHeadline(language: string | SQLChunk, document: string | SQLChunk, tsquery: SQL, options?: TsHeadlineOptions): SQL<string>;
 /**
  * Creates a PostgreSQL `similarity` function call (from pg_trgm extension).
  * Calculates the similarity between two strings based on trigram matching.
@@ -194,7 +196,7 @@ export declare function tsHeadline(language: string | SQL, document: string | SQ
  * @param right The second text value or expression to compare against.
  * @returns A Drizzle SQL object representing the similarity score (0 to 1).
  */
-export declare function similarity(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<number>;
+export declare function similarity(left: string | SQLChunk, right: string | SQLChunk): SQL<number>;
 /**
  * Creates a PostgreSQL `word_similarity` function call (from pg_trgm extension).
  * Calculates the greatest similarity between the set of trigrams in the first string and any continuous extent of an ordered set of trigrams in the second string.
@@ -202,7 +204,7 @@ export declare function similarity(left: string | SQL | SQL.Aliased | AnyColumn,
  * @param right The second text value or expression to compare against.
  * @returns A Drizzle SQL object representing the similarity score (0 to 1).
  */
-export declare function wordSimilarity(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<number>;
+export declare function wordSimilarity(left: string | SQLChunk, right: string | SQLChunk): SQL<number>;
 /**
  * Creates a PostgreSQL `strict_word_similarity` function call (from pg_trgm extension).
  * Same as `word_similarity`, but forces extent boundaries to match word boundaries.
@@ -210,10 +212,11 @@ export declare function wordSimilarity(left: string | SQL | SQL.Aliased | AnyCol
  * @param right The second text value or expression to compare against.
  * @returns A Drizzle SQL object representing the similarity score (0 to 1).
  */
-export declare function strictWordSimilarity(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<number>;
-export declare function isSimilar(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<boolean>;
-export declare function isWordSimilar(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<boolean>;
-export declare function isStrictWordSimilar(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<boolean>;
-export declare function distance(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<number>;
-export declare function wordDistance(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<number>;
-export declare function strictWordDistance(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<number>;
+export declare function strictWordSimilarity(left: string | SQLChunk, right: string | SQLChunk): SQL<number>;
+export declare function isSimilar(left: string | SQLChunk, right: string | SQLChunk): SQL<boolean>;
+export declare function isWordSimilar(left: string | SQLChunk, right: string | SQLChunk): SQL<boolean>;
+export declare function isStrictWordSimilar(left: string | SQLChunk, right: string | SQLChunk): SQL<boolean>;
+export declare function distance(left: string | SQLChunk, right: string | SQLChunk): SQL<number>;
+export declare function wordDistance(left: string | SQLChunk, right: string | SQLChunk): SQL<number>;
+export declare function strictWordDistance(left: string | SQLChunk, right: string | SQLChunk): SQL<number>;
+export declare function jsonbBuildObject(properties: Record<string, any> | [string, any][]): SQL;