@tstdl/base 0.93.9 → 0.93.11

package/orm/repository.types.d.ts

@@ -3,11 +3,13 @@
  * Defines types used by ORM repositories for operations like loading, updating, and creating entities.
  * Includes types for ordering, loading options, and entity data structures for create/update operations.
  */
-import type { Paths, Record, TypedOmit } from '../types/index.js';
+import type { Paths, Record, SimplifyObject, TypedOmit } from '../types/index.js';
 import type { UntaggedDeep } from '../types/tagged.js';
 import type { SQL, SQLWrapper } from 'drizzle-orm';
 import type { PartialDeep } from 'type-fest';
 import type { Entity, EntityMetadata, EntityWithoutMetadata } from './entity.js';
+import type { FullTextSearchQuery, Query } from './query.js';
+import type { TsHeadlineOptions } from './sqls.js';
 type WithSql<T> = {
     [P in keyof T]: T[P] extends Record ? WithSql<T[P]> : (T[P] | SQL);
 };
@@ -53,6 +55,75 @@ export type LoadManyOptions<T extends EntityWithoutMetadata> = LoadOptions<T> &
     limit?: number;
     distinct?: boolean | TargetColumn<T>[];
 };
+/**
+ * Options for ranking search results.
+ */
+export type RankOptions = {
+    /**
+     * Array of four numbers to weight D, C, B, and A labels respectively.
+     * Defaults to PostgreSQL's default {0.1, 0.2, 0.4, 1.0}.
+     */
+    weights?: [number, number, number, number];
+    /**
+     * Specifies how a document's length should impact its rank.
+     * It's a bitmask, e.g., 0 (default) ignores length, 2 divides by document length.
+     * See PostgreSQL documentation for `ts_rank_cd` for more details.
+     */
+    normalization?: number;
+};
+/**
+ * Options for highlighting search results.
+ */
+export type HighlightOptions<T extends EntityWithoutMetadata> = {
+    /**
+     * The source to generate the highlight from. Can be one or more property paths or a raw SQL expression.
+     */
+    source: TargetColumnPaths<T> | SQL<string>;
+} & TsHeadlineOptions;
+/**
+ * Options for the `search` method.
+ * @template T - The entity type.
+ */
+export type SearchOptions<T extends EntityWithoutMetadata> = SimplifyObject<FullTextSearchQuery<T>['$fts'] & TypedOmit<LoadManyOptions<T>, 'order'> & {
+    /**
+     * An additional filter to apply to the search query.
+     */
+    filter?: Query<T>;
+    /**
+     * How to order the search results.
+     */
+    order?: Order<T> | ((columns: {
+        score: SQL | SQL.Aliased<number>;
+    }) => Order<T>);
+    /**
+     * Whether to include a relevance score with each result. Only applicable for vector searches.
+     * - If `true`, the default score is included.
+     * - If a function is provided, it customizes the score calculation using the original score.
+     * - If no order is specified, results are ordered by score descending, when score is enabled.
+     * @default true
+     */
+    score?: boolean | ((originalScore: SQL<number>) => SQL<number>);
+    /**
+     * Enable and configure ranking of search results.
+     * - If `true` (default), results are ordered by score descending using default ranking options.
+     * - If an `RankOptions` object is provided, ranking is customized.
+     * @default true
+     */
+    rank?: boolean | RankOptions;
+    /**
+     * Enable and configure highlighting of search results.
+     */
+    highlight?: TargetColumnPaths<T> | SQL<string> | HighlightOptions<T>;
+}>;
+/**
+ * Represents a single result from a full-text search operation.
+ * @template T - The entity type.
+ */
+export type SearchResult<T extends EntityWithoutMetadata> = {
+    entity: T;
+    score?: number;
+    highlight?: string;
+};
 /**
  * Options for update operations (currently inherits from LoadOptions, primarily for ordering).
  * @template T - The entity type.

package/orm/server/drizzle/schema-converter.js

@@ -1,9 +1,11 @@
+import { sql, SQL } from 'drizzle-orm';
 import { toCamelCase, toSnakeCase } from 'drizzle-orm/casing';
 import { boolean, check, doublePrecision, foreignKey, index, integer, jsonb, pgSchema, primaryKey, text, unique, uniqueIndex, uuid } from 'drizzle-orm/pg-core';
 import { MultiKeyMap } from '../../../data-structures/multi-key-map.js';
 import { tryGetEnumName } from '../../../enumeration/enumeration.js';
 import { NotSupportedError } from '../../../errors/not-supported.error.js';
 import { JsonPath } from '../../../json-path/json-path.js';
+import { setweight, toTsVector } from '../../../orm/sqls.js';
 import { reflectionRegistry } from '../../../reflection/registry.js';
 import { ArraySchema, BooleanSchema, DefaultSchema, EnumerationSchema, getObjectSchema, NullableSchema, NumberSchema, ObjectSchema, OptionalSchema, StringSchema, Uint8ArraySchema } from '../../../schema/index.js';
 import { compareByValueSelectionToOrder, orderRest } from '../../../utils/comparison.js';
@@ -53,9 +55,12 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
     function buildIndex(table, data, columnName) {
         const columns = (data.columns ?? [columnName]).map((columnValue) => {
             assertDefined(columnValue, 'Missing column name for index.');
+            if (columnValue instanceof SQL) {
+                return columnValue;
+            }
             const [columnName, columnOrder] = isString(columnValue) ? [columnValue] : columnValue;
-            const order = columnOrder ?? data.order ?? 'asc';
             let column = getColumn(table, columnName);
+            const order = columnOrder ?? data.order ?? 'asc';
             column = column[order]();
             if (data.options?.nulls == 'first') {
                 column = column.nullsFirst();
@@ -66,13 +71,37 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
             return column;
         });
         const indexFn = (data.options?.unique == true) ? uniqueIndex : index;
-        let builder = indexFn(data.options?.name ?? getIndexName(tableName, columns, { naming: data.options?.naming })).using(data.options?.using ?? 'btree', ...columns);
+        const containsSql = columns.some((column) => column instanceof SQL);
+        const indexName = data.options?.name ?? (containsSql
+            ? assertDefinedPass(data.options?.name, 'Index with SQL expressions must have a name.')
+            : getIndexName(tableName, columns, { naming: data.options?.naming }));
+        const indexColumns = (data.options?.using == 'gin'
+            ? buildGinIndexColumns(columns, data.options)
+            : columns);
+        let builder = indexFn(indexName).using(data.options?.using ?? 'btree', ...indexColumns);
         if (isDefined(data.options?.where)) {
             const query = convertQuery(data.options.where(table), table, columnDefinitionsMap);
             builder = builder.where(query.inlineParams());
         }
         return builder;
     }
+    function buildGinIndexColumns(columns, options) {
+        const vectors = columns.map((column) => {
+            if (column instanceof SQL) {
+                return column;
+            }
+            const tsVector = toTsVector(options.language ?? 'simple', column);
+            const weight = options.weights?.[column.name];
+            if (isDefined(weight)) {
+                return setweight(tsVector, weight);
+            }
+            return tsVector;
+        });
+        if (options.vectors == 'separate') {
+            return vectors;
+        }
+        return [sql `(${sql.join(vectors, sql ` || `)})`];
+    }
     function buildPrimaryKey(table) {
         const columns = primaryKeyColumnDefinitions.map((columnDefinition) => getColumn(table, columnDefinition.name));
         return primaryKey({

package/orm/server/query-converter.d.ts

@@ -1,11 +1,6 @@
-/**
- * @module
- * Converts a generic query object structure into a Drizzle ORM SQL condition.
- * Supports logical operators ($and, $or, $nor) and various comparison operators
- * ($eq, $neq, $in, $nin, $lt, $lte, $gt, $gte, $regex).
- */
 import { SQL } from 'drizzle-orm';
-import type { Query } from '../query.js';
+import type { Record } from '../../types/index.js';
+import type { FtsParser, Query } from '../query.js';
 import type { ColumnDefinition, PgTableFromType } from './types.js';
 /**
  * Converts a query object into a Drizzle SQL condition.
@@ -20,3 +15,6 @@ import type { ColumnDefinition, PgTableFromType } from './types.js';
  * @throws {Error} If an unsupported query type is encountered.
  */
 export declare function convertQuery(query: Query, table: PgTableFromType, columnDefinitionsMap: Map<string, ColumnDefinition>): SQL;
+export declare function getTsQuery(text: string | SQL, language: string | SQL, parser: FtsParser): SQL;
+export declare function getTsVector(fields: readonly string[], language: string | SQL, table: PgTableFromType, columnDefinitionsMap: Map<string, ColumnDefinition>, weights?: Partial<Record<string, 'A' | 'B' | 'C' | 'D'>>): SQL;
+export declare function getColumnConcatenation(fields: readonly string[], table: PgTableFromType, columnDefinitionsMap: Map<string, ColumnDefinition>): SQL;

package/orm/server/query-converter.js

@@ -1,13 +1,9 @@
-/**
- * @module
- * Converts a generic query object structure into a Drizzle ORM SQL condition.
- * Supports logical operators ($and, $or, $nor) and various comparison operators
- * ($eq, $neq, $in, $nin, $lt, $lte, $gt, $gte, $regex).
- */
 import { and, eq, gt, gte, inArray, isNotNull, isNull, isSQLWrapper, lt, lte, ne, not, notInArray, or, SQL, sql } from 'drizzle-orm';
+import { match } from 'ts-pattern';
 import { NotSupportedError } from '../../errors/not-supported.error.js';
 import { hasOwnProperty, objectEntries } from '../../utils/object/object.js';
 import { assertDefinedPass, isDefined, isPrimitive, isRegExp, isString, isUndefined } from '../../utils/type-guards.js';
+import { isSimilar, phraseToTsQuery, plainToTsQuery, setweight, toTsQuery, toTsVector, websearchToTsQuery } from '../sqls.js';
 const sqlTrue = sql `true`;
 /**
  * Converts a query object into a Drizzle SQL condition.
@@ -60,10 +56,27 @@ export function convertQuery(query, table, columnDefinitionsMap) {
                 }
                 break;
             }
+            case '$fts': {
+                const ftsQuery = value;
+                const method = ftsQuery.method ?? 'vector';
+                const sqlValue = match(method)
+                    .with('vector', () => {
+                    const tsquery = getTsQuery(ftsQuery.text, ftsQuery.vector?.language ?? 'simple', ftsQuery.vector?.parser ?? 'raw');
+                    const tsvector = getTsVector(ftsQuery.fields, ftsQuery.vector?.language ?? 'simple', table, columnDefinitionsMap, ftsQuery.vector?.weights);
+                    return sql `${tsvector} @@ ${tsquery}`;
+                })
+                    .with('trigram', () => {
+                    const searchExpression = getColumnConcatenation(ftsQuery.fields, table, columnDefinitionsMap);
+                    return isSimilar(searchExpression, ftsQuery.text);
+                })
+                    .exhaustive();
+                conditions.push(sqlValue);
+                break;
+            }
             default: {
                 const columnDef = assertDefinedPass(columnDefinitionsMap.get(property), `Could not map property ${property} to column.`);
                 const column = table[columnDef.name];
-                const condition = getCondition(property, value, column);
+                const condition = getCondition(property, value, column, table, columnDefinitionsMap);
                 conditions.push(condition);
                 break;
             }
@@ -79,10 +92,8 @@ export function convertQuery(query, table, columnDefinitionsMap) {
  * @param value The value or comparison object for the property.
  * @param column The Drizzle column object.
  * @returns A Drizzle SQL condition.
- * @throws {NotSupportedError} If an unsupported operator like $exists, $text, $geoShape, or $geoDistance is used.
- * @throws {Error} If the value structure is not a recognized comparison operator.
  */
-function getCondition(property, value, column) {
+function getCondition(property, value, column, table, columnDefinitionsMap) {
     const isPrimitiveValue = isPrimitive(value);
     if (isPrimitiveValue || hasOwnProperty(value, '$eq')) {
         const queryValue = isPrimitiveValue ? value : value.$eq;
@@ -92,7 +103,7 @@ function getCondition(property, value, column) {
         return eq(column, queryValue);
     }
     if (hasOwnProperty(value, '$and')) {
-        const innerQueries = value.$and.map((query) => getCondition(property, query, column)); // eslint-disable-line @typescript-eslint/no-unsafe-argument
+        const innerQueries = value.$and.map((query) => getCondition(property, query, column, table, columnDefinitionsMap)); // eslint-disable-line @typescript-eslint/no-unsafe-argument
         const andQuery = and(...innerQueries);
         if (isUndefined(andQuery)) {
             throw new Error(`No valid conditions in $and for property "${property}".`);
@@ -100,7 +111,7 @@ function getCondition(property, value, column) {
         return andQuery;
     }
     if (hasOwnProperty(value, '$or')) {
-        const innerQueries = value.$or.map((query) => getCondition(property, query, column)); // eslint-disable-line @typescript-eslint/no-unsafe-argument
+        const innerQueries = value.$or.map((query) => getCondition(property, query, column, table, columnDefinitionsMap)); // eslint-disable-line @typescript-eslint/no-unsafe-argument
         const orQuery = or(...innerQueries);
         if (isUndefined(orQuery)) {
             throw new Error(`No valid conditions in $or for property "${property}".`);
@@ -108,7 +119,7 @@ function getCondition(property, value, column) {
         return orQuery;
     }
     if (hasOwnProperty(value, '$not')) {
-        const innerQuery = getCondition(property, value.$not, column); // eslint-disable-line @typescript-eslint/no-unsafe-argument
+        const innerQuery = getCondition(property, value.$not, column, table, columnDefinitionsMap); // eslint-disable-line @typescript-eslint/no-unsafe-argument
         return not(innerQuery);
     }
     if (hasOwnProperty(value, '$neq')) {
@@ -156,8 +167,17 @@ function getCondition(property, value, column) {
         const operator = (regexp.flags?.includes('i') ?? false) ? sql.raw('~*') : sql.raw('~');
         return sql `${column} ${operator} ${regexp.value}`;
     }
-    if (hasOwnProperty(value, '$text')) {
-        throw new NotSupportedError('$text is not supported.');
+    if (hasOwnProperty(value, '$fts')) {
+        const queryValue = value.$fts;
+        const { query, method = 'vector', language = 'simple', parser = 'plain' } = isString(queryValue)
+            ? { query: queryValue }
+            : queryValue;
+        if (method == 'similarity') {
+            return isSimilar(column, query);
+        }
+        const tsquery = getTsQuery(query, language, parser);
+        const tsvector = toTsVector(language, column);
+        return sql `${tsvector} @@ ${tsquery}`;
     }
     if (hasOwnProperty(value, '$geoShape')) {
         throw new NotSupportedError('$geoShape is not supported.');
@@ -167,3 +187,37 @@ function getCondition(property, value, column) {
     }
     throw new Error(`Unsupported query type "${property}".`);
 }
+export function getTsQuery(text, language, parser) {
+    switch (parser) {
+        case 'raw':
+            return toTsQuery(language, text);
+        case 'plain':
+            return plainToTsQuery(language, text);
+        case 'phrase':
+            return phraseToTsQuery(language, text);
+        case 'websearch':
+            return websearchToTsQuery(language, text);
+        default:
+            throw new NotSupportedError(`Unsupported text search parser: ${parser}`);
+    }
+}
+export function getTsVector(fields, language, table, columnDefinitionsMap, weights) {
+    const tsvector = sql.join(fields.map((field) => {
+        const columnDef = assertDefinedPass(columnDefinitionsMap.get(field), `Could not map property ${field} to column.`);
+        const column = table[columnDef.name];
+        const vector = toTsVector(language, column);
+        const weight = weights?.[field];
+        if (isDefined(weight)) {
+            return setweight(vector, weight);
+        }
+        return vector;
+    }), sql ` || `);
+    return tsvector;
+}
+export function getColumnConcatenation(fields, table, columnDefinitionsMap) {
+    const columns = fields.map((field) => {
+        const columnDef = assertDefinedPass(columnDefinitionsMap.get(field), `Could not map property ${field} to column.`);
+        return table[columnDef.name];
+    });
+    return sql `(${sql.join(columns, sql ` || ' ' || `)})`;
+}

package/orm/server/repository.d.ts

@@ -1,10 +1,10 @@
 import { SQL } from 'drizzle-orm';
-import type { PgColumn, PgInsertValue, PgUpdateSetSource } from 'drizzle-orm/pg-core';
-import { afterResolve, type Resolvable, resolveArgumentType } from '../../injector/interfaces.js';
-import type { DeepPartial, OneOrMany, Paths, Type, UntaggedDeep } from '../../types/index.js';
+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, Paths, Record, Type, UntaggedDeep } from '../../types/index.js';
 import { Entity, type EntityMetadataAttributes, type EntityType, type EntityWithoutMetadata } from '../entity.js';
-import type { Query } from '../query.js';
-import type { EntityMetadataUpdate, EntityUpdate, LoadManyOptions, LoadOptions, NewEntity, Order, TargetColumnPaths } from '../repository.types.js';
+import type { FullTextSearchQuery, Query } from '../query.js';
+import type { EntityMetadataUpdate, EntityUpdate, LoadManyOptions, LoadOptions, NewEntity, Order, SearchOptions, SearchResult, TargetColumn, TargetColumnPaths } from '../repository.types.js';
 import type { Database } from './database.js';
 import type { PgTransaction } from './transaction.js';
 import { Transactional } from './transactional.js';
@@ -40,6 +40,16 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
     [afterResolve](): void;
     private expirationLoop;
     protected getTransactionalContextData(): EntityRepositoryContext;
+    vectorSearch(options: SearchOptions<T>): Promise<SearchResult<T>[]>;
+    trigramSearch(options: SearchOptions<T>): Promise<SearchResult<T>[]>;
+    /**
+     * Performs a full-text search and returns entities ranked by relevance.
+     * This method is a convenience wrapper around `loadManyByQuery` with the `$fts` operator.
+     * @param query The search query using the `$fts` operator.
+     * @param options Search options including ranking, and highlighting configuration.
+     * @returns A promise that resolves to an array of search results, including the entity, score, and optional highlight.
+     */
+    search(_query: FullTextSearchQuery<T>['$fts'], _options?: SearchOptions<T>): Promise<SearchResult<T>[]>;
     /**
      * Loads a single entity by its ID.
      * Throws `NotFoundError` if the entity is not found.
@@ -416,7 +426,7 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-    }, "partial", globalThis.Record<string, "not-null">, false, "where" | "limit", {
+    }, "partial", globalThis.Record<string, "not-null">, false, "limit" | "where", {
         id: string;
     }[], {
         id: PgColumn<{
@@ -436,7 +446,9 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-    }>, "where" | "limit">;
+    }>, "limit" | "where">;
+    applySelect<TApplyTo extends Record<'select' | 'selectDistinct' | 'selectDistinctOn', Function<any[], PgSelectBuilder<any, any>>>>(applyTo: TApplyTo, distinct?: boolean | TargetColumn<T>[]): PgSelectBuilder<undefined, ReturnType<TApplyTo['selectDistinct']> extends PgSelectBuilder<any, infer TResult> ? TResult : never>;
+    applySelect<TApplyTo extends Record<'select' | 'selectDistinct' | 'selectDistinctOn', Function<any[], PgSelectBuilder<any, any>>>, TSelection extends SelectedFields>(applyTo: TApplyTo, selection: TSelection, distinct?: boolean | TargetColumn<T>[]): PgSelectBuilder<TSelection, ReturnType<TApplyTo['selectDistinct']> extends PgSelectBuilder<any, infer TResult> ? TResult : never>;
     protected getAttributesUpdate(attributes: SQL | EntityMetadataAttributes | undefined): SQL<unknown> | undefined;
     protected _mapManyToEntity(columns: InferSelect[], transformContext: TransformContext): Promise<T[]>;
     protected _mapToEntity(columns: InferSelect, transformContext: TransformContext): Promise<T>;

package/orm/server/repository.js

@@ -5,9 +5,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { match } from 'ts-pattern';
+import { match, P } from 'ts-pattern';
 import { CancellationSignal } from '../../cancellation/token.js';
 import { NotFoundError } from '../../errors/not-found.error.js';
+import { NotImplementedError } from '../../errors/not-implemented.error.js';
 import { Singleton } from '../../injector/decorators.js';
 import { inject, injectArgument } from '../../injector/inject.js';
 import { afterResolve, resolveArgumentType } from '../../injector/interfaces.js';
@@ -19,15 +20,18 @@ import { importSymmetricKey } from '../../utils/cryptography.js';
 import { fromDeepObjectEntries, fromEntries, objectEntries } from '../../utils/object/object.js';
 import { cancelableTimeout } from '../../utils/timing.js';
 import { tryIgnoreAsync } from '../../utils/try-ignore.js';
-import { assertDefined, assertDefinedPass, isArray, isDefined, isString, isUndefined } from '../../utils/type-guards.js';
+import { assertDefined, assertDefinedPass, isArray, isBoolean, isDefined, isFunction, isInstanceOf, isString, isUndefined } from '../../utils/type-guards.js';
 import { typeExtends } from '../../utils/type/index.js';
 import { millisecondsPerSecond } from '../../utils/units.js';
 import { Entity } from '../entity.js';
-import { TRANSACTION_TIMESTAMP } from '../sqls.js';
+import { TRANSACTION_TIMESTAMP, tsHeadline, tsRankCd } from '../sqls.js';
 import { getColumnDefinitions, getColumnDefinitionsMap, getDrizzleTableFromType } from './drizzle/schema-converter.js';
-import { convertQuery } from './query-converter.js';
+import { convertQuery, getColumnConcatenation, getTsQuery, getTsVector } from './query-converter.js';
 import { ENCRYPTION_SECRET } from './tokens.js';
 import { getTransactionalContextData, injectTransactional, injectTransactionalAsync, isInTransactionalContext, Transactional } from './transactional.js';
+const searchScoreColumn = '__tsl_score';
+const searchDistanceColumn = '__tsl_distance';
+const searchHighlightColumn = '__tsl_highlight';
 export const repositoryType = Symbol('repositoryType');
 /**
  * Configuration class for EntityRepository.
@@ -92,6 +96,128 @@ let EntityRepository = class EntityRepository extends Transactional {
         };
         return context;
     }
+    async vectorSearch(options) {
+        const { vector: { language = 'simple' } = {} } = options;
+        const languageSql = isString(language) ? language : sql `${language}`;
+        const tsquery = getTsQuery(options.text, languageSql, options.vector?.parser ?? 'raw');
+        const tsvector = getTsVector(options.fields, languageSql, this.table, this.#columnDefinitionsMap, options.vector?.weights);
+        const rawScore = (options.score != false) ? tsRankCd(tsvector, tsquery, isBoolean(options.rank) ? undefined : options.rank) : undefined;
+        const score = (isFunction(options.score) ? options.score(rawScore) : rawScore)?.as(searchScoreColumn);
+        const vectorClause = sql `${tsvector} @@ ${tsquery}`;
+        const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.getColumn(column)]));
+        if (isDefined(score)) {
+            selection[searchScoreColumn] = score;
+        }
+        if (isDefined(options.highlight)) {
+            const { source, ...headlineOptions } = (isString(options.highlight) || isInstanceOf(options.highlight, SQL))
+                ? { source: options.highlight }
+                : options.highlight;
+            const document = match(source)
+                .with(P.instanceOf(SQL), (s) => s)
+                .otherwise((paths) => {
+                const columns = this.getColumns(paths);
+                return sql.join(columns, sql ` || ' ' || `);
+            });
+            selection[searchHighlightColumn] = tsHeadline(languageSql, document, tsquery, headlineOptions).as(searchHighlightColumn);
+        }
+        const whereClause = isDefined(options.filter)
+            ? and(this.convertQuery(options.filter), vectorClause)
+            : vectorClause;
+        let dbQuery = this
+            .applySelect(this.session, selection, options.distinct)
+            .from(this.#table)
+            .where(whereClause)
+            .$dynamic();
+        if (isDefined(options.offset)) {
+            dbQuery = dbQuery.offset(options.offset);
+        }
+        if (isDefined(options.limit)) {
+            dbQuery = dbQuery.limit(options.limit);
+        }
+        const orderByExpressions = [];
+        if (isDefined(options.order)) {
+            const order = isFunction(options.order)
+                ? options.order({
+                    get score() {
+                        return assertDefinedPass(score, 'Score is disabled.');
+                    },
+                })
+                : options.order;
+            orderByExpressions.push(...this.convertOrderBy(order));
+        }
+        else if (isDefined(score)) {
+            orderByExpressions.push(desc(score));
+        }
+        dbQuery = dbQuery.orderBy(...orderByExpressions);
+        const transformContext = await this.getTransformContext();
+        const rows = await dbQuery;
+        return await toArrayAsync(mapAsync(rows, async ({ [searchScoreColumn]: score, [searchHighlightColumn]: highlight, ...row }) => ({
+            entity: await this._mapToEntity(row, transformContext),
+            score: score,
+            highlight: highlight,
+        })));
+    }
+    async trigramSearch(options) {
+        const distanceOperator = match(options.trigram?.type ?? 'phrase')
+            .with('phrase', () => '<->')
+            .with('word', () => '<<->')
+            .with('strict-word', () => '<<<->')
+            .exhaustive();
+        const distanceThresholdOperator = match(options.trigram?.type ?? 'phrase')
+            .with('phrase', () => '%')
+            .with('word', () => '<%')
+            .with('strict-word', () => '<<%')
+            .exhaustive();
+        // TODO: set similarity_threshold, word_similarity_threshold, strict_word_similarity_threshold
+        const searchExpression = getColumnConcatenation(options.fields, this.table, this.#columnDefinitionsMap);
+        const distance = sql `(${options.text} ${sql.raw(distanceOperator)} ${searchExpression})`.as(searchDistanceColumn);
+        const trigramClause = sql `(${options.text} ${sql.raw(distanceThresholdOperator)} ${searchExpression})`;
+        const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.getColumn(column)]));
+        selection[searchDistanceColumn] = distance;
+        const whereClause = isDefined(options.filter)
+            ? and(this.convertQuery(options.filter), trigramClause)
+            : trigramClause;
+        let dbQuery = this
+            .applySelect(this.session, selection, options.distinct)
+            .from(this.#table)
+            .where(whereClause)
+            .$dynamic();
+        if (isDefined(options.offset)) {
+            dbQuery = dbQuery.offset(options.offset);
+        }
+        if (isDefined(options.limit)) {
+            dbQuery = dbQuery.limit(options.limit);
+        }
+        const orderByExpressions = [];
+        if (isDefined(options.order)) {
+            const order = isFunction(options.order)
+                ? options.order({ score: sql `1 - ${distance}` })
+                : options.order;
+            orderByExpressions.push(...this.convertOrderBy(order));
+        }
+        else if (options.rank != false) {
+            orderByExpressions.push(distance);
+        }
+        dbQuery = dbQuery.orderBy(...orderByExpressions);
+        console.log(dbQuery.toSQL());
+        const transformContext = await this.getTransformContext();
+        const rows = await dbQuery;
+        return await toArrayAsync(mapAsync(rows, async ({ [searchDistanceColumn]: distance, [searchHighlightColumn]: highlight, ...row }) => ({
+            entity: await this._mapToEntity(row, transformContext),
+            score: (1 - distance),
+            highlight: highlight,
+        })));
+    }
+    /**
+     * Performs a full-text search and returns entities ranked by relevance.
+     * This method is a convenience wrapper around `loadManyByQuery` with the `$fts` operator.
+     * @param query The search query using the `$fts` operator.
+     * @param options Search options including ranking, and highlighting configuration.
+     * @returns A promise that resolves to an array of search results, including the entity, score, and optional highlight.
+     */
+    async search(_query, _options) {
+        throw new NotImplementedError('EntityRepository.search is not implemented yet.');
+    }
     /**
      * Loads a single entity by its ID.
      * Throws `NotFoundError` if the entity is not found.
@@ -186,13 +312,7 @@ let EntityRepository = class EntityRepository extends Transactional {
      */
     async loadManyByQuery(query, options) {
         const sqlQuery = this.convertQuery(query);
-        let dbQuery = match(options?.distinct ?? false)
-            .with(false, () => this.session.select())
-            .with(true, () => this.session.selectDistinct())
-            .otherwise((targets) => {
-            const ons = targets.map((target) => isString(target) ? this.getColumn(target) : target);
-            return this.session.selectDistinctOn(ons);
-        })
+        let dbQuery = this.applySelect(this.session, options?.distinct)
             .from(this.#table)
             .where(sqlQuery)
             .$dynamic();
@@ -855,6 +975,19 @@ let EntityRepository = class EntityRepository extends Transactional {
             .where(sqlQuery)
             .limit(1);
     }
+    applySelect(applyTo, selectionOrDistinct, distinctOrNothing) {
+        const firstParameterIsDistinct = isBoolean(selectionOrDistinct) || isArray(selectionOrDistinct);
+        const selection = firstParameterIsDistinct ? undefined : selectionOrDistinct;
+        const distinct = firstParameterIsDistinct ? selectionOrDistinct : distinctOrNothing;
+        const selectBuilder = match(distinct ?? false)
+            .with(false, () => applyTo.select(selection))
+            .with(true, () => applyTo.selectDistinct(selection))
+            .otherwise((targets) => {
+            const ons = targets.map((target) => isString(target) ? this.getColumn(target) : target);
+            return applyTo.selectDistinctOn(ons, selection);
+        });
+        return selectBuilder;
+    }
     getAttributesUpdate(attributes) {
         if (isUndefined(attributes)) {
             return undefined;