@tstdl/base 0.93.20 → 0.93.22

package/orm/server/repository.d.ts

@@ -1,10 +1,10 @@
-import { SQL } from 'drizzle-orm';
+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, Paths, Record, Type, UntaggedDeep } from '../../types/index.js';
-import { Entity, type EntityMetadataAttributes, type EntityType, type EntityWithoutMetadata } from '../entity.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 { DeepPartial, Function, OneOrMany, Record, Type } 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 { 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';
 import { Transactional } from './transactional.js';
@@ -26,8 +26,8 @@ type EntityRepositoryContext = {
     encryptionSecret: Uint8Array<ArrayBuffer> | undefined;
     transformContext: TransformContext | Promise<TransformContext> | undefined;
 };
-type InferSelect<T extends Entity | EntityWithoutMetadata = Entity | EntityWithoutMetadata> = PgTableFromType<EntityType<T>>['$inferSelect'];
-export declare class EntityRepository<T extends Entity | EntityWithoutMetadata = EntityWithoutMetadata> extends Transactional<EntityRepositoryContext> implements Resolvable<EntityType<T>> {
+type InferSelect<T extends BaseEntity = BaseEntity> = PgTableFromType<EntityType<T>>['$inferSelect'];
+export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends Transactional<EntityRepositoryContext> implements Resolvable<EntityType<T>> {
     #private;
     readonly type: EntityType<T>;
     readonly typeName: string;
@@ -40,16 +40,22 @@ 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>[]>;
+    protected tsVectorSearch(options: SearchOptions<T> & {
+        query: TsVectorSearchQuery<T>;
+    }): Promise<SearchResult<T>[]>;
+    protected trigramSearch(options: SearchOptions<T> & {
+        query: TrigramSearchQuery<T>;
+    }): Promise<SearchResult<T>[]>;
+    protected paradeDbSearch(options: SearchOptions<T> & {
+        query: ParadeDbSearchQuery<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.
+     * This method dispatches to the appropriate search implementation based on the `method` option.
+     * @param options Search options including method, query text, 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>[]>;
+    search(options: SearchOptions<T>): Promise<SearchResult<T>[]>;
     /**
      * Loads a single entity by its ID.
      * Throws `NotFoundError` if the entity is not found.
@@ -175,14 +181,14 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
      * @param entity The entity to insert.
      * @returns A promise that resolves to the inserted or existing entity.
      */
-    insertIfNotExists(target: OneOrMany<Paths<UntaggedDeep<T>>>, entity: NewEntity<T>): Promise<T | undefined>;
+    insertIfNotExists(target: OneOrMany<TargetColumnPath<T>>, entity: NewEntity<T>): Promise<T | undefined>;
     /**
      * Inserts many entities if they do not already exist based on the target columns.
      * @param target The column(s) to use for conflict detection.
      * @param entities The entities to insert.
      * @returns A promise that resolves to the inserted or existing entities.
      */
-    insertManyIfNotExists(target: OneOrMany<Paths<UntaggedDeep<T>>>, entities: NewEntity<T>[]): Promise<T[]>;
+    insertManyIfNotExists(target: OneOrMany<TargetColumnPath<T>>, entities: NewEntity<T>[]): Promise<T[]>;
     /**
      * Inserts an entity or updates it if a conflict occurs based on the target columns.
      * @param target The column(s) to use for conflict detection.
@@ -190,7 +196,7 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
      * @param update Optional update to apply if a conflict occurs. Defaults to the inserted entity's values.
      * @returns A promise that resolves to the inserted or updated entity.
      */
-    upsert(target: OneOrMany<Paths<UntaggedDeep<T>>>, entity: NewEntity<T>, update?: EntityUpdate<T>): Promise<T>;
+    upsert(target: OneOrMany<TargetColumnPath<T>>, entity: NewEntity<T>, update?: EntityUpdate<T>): Promise<T>;
     /**
      * Inserts multiple entities or updates them if a conflict occurs based on the target columns.
      * @param target The column(s) to use for conflict detection.
@@ -198,7 +204,7 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
      * @param update Optional update to apply if a conflict occurs. Defaults to the inserted entity's values.
      * @returns A promise that resolves to an array of the inserted or updated entities.
      */
-    upsertMany(target: OneOrMany<Paths<UntaggedDeep<T>>>, entities: NewEntity<T>[], update?: EntityUpdate<T>): Promise<T[]>;
+    upsertMany(target: OneOrMany<TargetColumnPath<T>>, entities: NewEntity<T>[], update?: EntityUpdate<T>): Promise<T[]>;
     /**
      * Updates an entity by its ID.
      * Throws `NotFoundError` if the entity is not found.
@@ -337,13 +343,23 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
      * @returns A promise that resolves to an array of the hard deleted entities.
      */
     hardDeleteManyByQuery(query: Query<T>): Promise<T[]>;
+    /**
+     * Resolves a target column from an object path or column definition to a Drizzle SQL wrapper.
+     * @param target The object path or column definition.
+     */
+    resolveTargetColumn(target: TargetColumn<T> | ColumnDefinition): SQLWrapper;
+    /**
+     * Resolves multiple target columns from object paths or column definitions to Drizzle SQL wrappers.
+     * @param targets The object paths or column definitions.
+     */
+    resolveTargetColumns(targets: readonly (TargetColumn<T> | ColumnDefinition)[]): SQLWrapper[];
     /**
      * Retrieves the Drizzle PgColumn for a given object path or column definition.
      * @param pathOrColumn The object path or column definition.
      * @returns The corresponding PgColumn.
      */
-    getColumn(pathOrColumn: TargetColumnPaths<T> | ColumnDefinition): PgColumn;
-    getColumns(pathOrColumns: (TargetColumnPaths<T> | ColumnDefinition)[]): PgColumn[];
+    getColumn(pathOrColumn: TargetColumnPath<T> | ColumnDefinition): PgColumn;
+    getColumns(pathOrColumns: readonly (TargetColumnPath<T> | ColumnDefinition)[]): PgColumn[];
     /**
      * Converts an Order object to an array of Drizzle SQL order expressions.
      * @param order The order object.
@@ -459,6 +475,7 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
     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>[]>;
 }
 /**
  * Injects an EntityRepository instance for the specified entity type.
@@ -466,19 +483,19 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
  * @param type The entity type.
  * @returns An EntityRepository instance for the specified type.
  */
-export declare function injectRepository<T extends Entity | EntityWithoutMetadata>(type: EntityType<T>, session?: Database | PgTransaction | null): EntityRepository<T>;
+export declare function injectRepository<T extends BaseEntity>(type: EntityType<T>, session?: Database | PgTransaction | null): EntityRepository<T>;
 /**
  * Injects an EntityRepository instance for the specified entity type.
  * @template T The entity type.
  * @param type The entity type.
  * @returns An EntityRepository instance for the specified type.
  */
-export declare function injectRepositoryAsync<T extends Entity | EntityWithoutMetadata>(type: EntityType<T>, session?: Database | PgTransaction | null): Promise<EntityRepository<T>>;
+export declare function injectRepositoryAsync<T extends BaseEntity>(type: EntityType<T>, session?: Database | PgTransaction | null): Promise<EntityRepository<T>>;
 /**
  * Gets or creates a singleton EntityRepository class for the specified entity type.
  * @template T The entity type.
  * @param type The entity type.
  * @returns A singleton EntityRepository class for the specified type.
  */
-export declare function getRepository<T extends Entity | EntityWithoutMetadata>(type: EntityType<T>): Type<EntityRepository<T>>;
+export declare function getRepository<T extends BaseEntity>(type: EntityType<T>): Type<EntityRepository<T>>;
 export {};

package/orm/server/repository.js

@@ -8,7 +8,6 @@ import { and, asc, count, desc, eq, inArray, isNull, isSQLWrapper, lte, or, SQL,
 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';
@@ -17,21 +16,23 @@ 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 { fromDeepObjectEntries, fromEntries, objectEntries } from '../../utils/object/object.js';
+import { filterUndefinedObjectProperties, fromDeepObjectEntries, fromEntries, objectEntries } from '../../utils/object/object.js';
+import { toSnakeCase } from '../../utils/string/snake-case.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';
 import { typeExtends } from '../../utils/type/index.js';
 import { millisecondsPerSecond } from '../../utils/units.js';
 import { Entity } from '../entity.js';
-import { TRANSACTION_TIMESTAMP, tsHeadline, tsRankCd } from '../sqls.js';
+import { distance, isSimilar, isStrictWordSimilar, isWordSimilar, TRANSACTION_TIMESTAMP, tsHeadline, tsRankCd } from '../sqls.js';
 import { getColumnDefinitions, getColumnDefinitionsMap, getDrizzleTableFromType } from './drizzle/schema-converter.js';
-import { convertQuery, getColumnConcatenation, getTsQuery, getTsVector } from './query-converter.js';
+import { convertQuery, getTsQuery, getTsVector, resolveTargetColumn } 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';
+const bm25ScoreColumn = '__parade_bm25_score';
 export const repositoryType = Symbol('repositoryType');
 /**
  * Configuration class for EntityRepository.
@@ -72,8 +73,8 @@ let EntityRepository = class EntityRepository extends Transactional {
         if ((softExpirationColumns.length + hardExpirationColumns.length) == 0) {
             return;
         }
-        const softDeletionQuery = or(...softExpirationColumns.map((column) => lte(sql `${this.getColumn(column)} + INTERVAL '${sql.raw(String(column.reflectionData.expirationField.after))} ms'`, TRANSACTION_TIMESTAMP)));
-        const hardDeletionQuery = or(...hardExpirationColumns.map((column) => lte(sql `${this.getColumn(column)} + INTERVAL '${sql.raw(String(column.reflectionData.expirationField.after))} ms'`, TRANSACTION_TIMESTAMP)));
+        const softDeletionQuery = or(...softExpirationColumns.map((column) => lte(sql `${this.resolveTargetColumn(column)} + INTERVAL '${sql.raw(String(column.reflectionData.expirationField.after))} ms'`, TRANSACTION_TIMESTAMP)));
+        const hardDeletionQuery = or(...hardExpirationColumns.map((column) => lte(sql `${this.resolveTargetColumn(column)} + INTERVAL '${sql.raw(String(column.reflectionData.expirationField.after))} ms'`, TRANSACTION_TIMESTAMP)));
         assertDefined(this.#cancellationSignal);
         while (this.#cancellationSignal.isUnset) {
             if (isDefined(softDeletionQuery)) {
@@ -96,22 +97,29 @@ let EntityRepository = class EntityRepository extends Transactional {
         };
         return context;
     }
-    async vectorSearch(options) {
-        const { vector: { language = 'simple' } = {} } = options;
+    async tsVectorSearch(options) {
+        const { query: { $tsvector: tsvectorOptions }, score: scoreOption = true, rank, highlight, filter } = options;
+        const { fields, query, language = 'simple', parser = 'raw' } = tsvectorOptions;
+        const fieldsArray = isArray(fields) ? fields : [fields];
+        const convertedFields = fieldsArray.map((target) => {
+            const [field, weight] = isArray(target) ? target : [target, undefined];
+            const sqlField = resolveTargetColumn(field, this.#table, this.#columnDefinitionsMap);
+            return isDefined(weight) ? [sqlField, weight] : sqlField;
+        });
         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 tsquery = getTsQuery(query, languageSql, parser);
+        const tsvector = getTsVector(convertedFields, languageSql);
+        const rawScore = (scoreOption != false) ? tsRankCd(tsvector, tsquery, isBoolean(rank) ? undefined : rank) : undefined;
+        const score = (isFunction(scoreOption) ? scoreOption(rawScore) : rawScore)?.as(searchScoreColumn);
         const vectorClause = sql `${tsvector} @@ ${tsquery}`;
-        const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.getColumn(column)]));
+        const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.resolveTargetColumn(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;
+        if (isDefined(highlight)) {
+            const { source, ...headlineOptions } = (isString(highlight) || isInstanceOf(highlight, SQL))
+                ? { source: highlight }
+                : highlight;
             const document = match(source)
                 .with(P.instanceOf(SQL), (s) => s)
                 .otherwise((paths) => {
@@ -120,8 +128,8 @@ let EntityRepository = class EntityRepository extends Transactional {
             });
             selection[searchHighlightColumn] = tsHeadline(languageSql, document, tsquery, headlineOptions).as(searchHighlightColumn);
         }
-        const whereClause = isDefined(options.filter)
-            ? and(this.convertQuery(options.filter), vectorClause)
+        const whereClause = isDefined(filter)
+            ? and(this.convertQuery(filter), vectorClause)
             : vectorClause;
         let dbQuery = this
             .applySelect(this.session, selection, options.distinct)
@@ -149,33 +157,26 @@ let EntityRepository = class EntityRepository extends Transactional {
             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,
-        })));
+        return await this._mapSearchResults(dbQuery, searchScoreColumn, searchHighlightColumn);
     }
     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();
+        const { query: { $trigram: trigramOptions }, rank, filter } = options;
+        const { fields, query, type = 'phrase', threshold } = trigramOptions;
+        const convertedFields = toArray(fields).map((target) => resolveTargetColumn(target, this.#table, this.#columnDefinitionsMap));
+        const searchExpression = sql `(${sql.join(convertedFields, sql ` || ' ' || `)})`;
         // 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)
+        const trigramClause = isDefined(threshold)
+            ? match(type)
+                .with('phrase', () => isSimilar(query, searchExpression))
+                .with('word', () => isWordSimilar(query, searchExpression))
+                .with('strict-word', () => isStrictWordSimilar(query, searchExpression))
+                .exhaustive()
+            : isSimilar(query, searchExpression);
+        const distanceColumn = distance(query, searchExpression).as(searchDistanceColumn);
+        const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.resolveTargetColumn(column)]));
+        selection[searchDistanceColumn] = distanceColumn;
+        const whereClause = isDefined(filter)
+            ? and(this.convertQuery(filter), trigramClause)
             : trigramClause;
         let dbQuery = this
             .applySelect(this.session, selection, options.distinct)
@@ -189,34 +190,80 @@ let EntityRepository = class EntityRepository extends Transactional {
             dbQuery = dbQuery.limit(options.limit);
         }
         const orderByExpressions = [];
+        const score = sql `1 - ${distanceColumn}`;
+        if (isDefined(options.order)) {
+            const order = isFunction(options.order) ? options.order({ score }) : options.order;
+            orderByExpressions.push(...this.convertOrderBy(order));
+        }
+        else if (rank != false) {
+            orderByExpressions.push(distanceColumn); // order by distance ascending
+        }
+        dbQuery = dbQuery.orderBy(...orderByExpressions);
+        return await this._mapSearchResults(dbQuery, searchDistanceColumn, searchHighlightColumn, (rawDistance) => 1 - rawDistance);
+    }
+    async paradeDbSearch(options) {
+        const { query: { $parade: paradeQuery }, score: scoreOption = true, highlight, filter } = options;
+        const keyField = this.#table.id;
+        const paradeNativeQuery = convertQuery({ $parade: paradeQuery }, this.#table, this.#columnDefinitionsMap);
+        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;
+        }
+        if (isDefined(highlight)) {
+            const { source, ...highlightOptions } = (isString(highlight) || isInstanceOf(highlight, SQL))
+                ? { source: highlight }
+                : highlight;
+            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 whereClause = isDefined(filter)
+            ? and(this.convertQuery(filter), paradeNativeQuery)
+            : paradeNativeQuery;
+        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({
+                    get score() {
+                        return assertDefinedPass(score, 'Score is disabled.');
+                    },
+                })
                 : options.order;
             orderByExpressions.push(...this.convertOrderBy(order));
         }
-        else if (options.rank != false) {
-            orderByExpressions.push(distance);
+        else if (isDefined(score)) {
+            orderByExpressions.push(desc(score));
         }
         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,
-        })));
+        return await this._mapSearchResults(dbQuery, bm25ScoreColumn, searchHighlightColumn);
     }
     /**
      * 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.
+     * This method dispatches to the appropriate search implementation based on the `method` option.
+     * @param options Search options including method, query text, 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.');
+    async search(options) {
+        return await match(options.query)
+            .with({ $tsvector: P.any }, async () => await this.tsVectorSearch(options))
+            .with({ $trigram: P.any }, async () => await this.trigramSearch(options))
+            .with({ $parade: P.any }, async () => await this.paradeDbSearch(options))
+            .exhaustive();
     }
     /**
      * Loads a single entity by its ID.
@@ -846,17 +893,27 @@ let EntityRepository = class EntityRepository extends Transactional {
             .returning();
         return await this.mapManyToEntity(rows);
     }
+    /**
+     * Resolves a target column from an object path or column definition to a Drizzle SQL wrapper.
+     * @param target The object path or column definition.
+     */
+    resolveTargetColumn(target) {
+        return resolveTargetColumn(target, this.#table, this.#columnDefinitionsMap);
+    }
+    /**
+     * Resolves multiple target columns from object paths or column definitions to Drizzle SQL wrappers.
+     * @param targets The object paths or column definitions.
+     */
+    resolveTargetColumns(targets) {
+        return targets.map((target) => this.resolveTargetColumn(target));
+    }
     /**
      * Retrieves the Drizzle PgColumn for a given object path or column definition.
      * @param pathOrColumn The object path or column definition.
      * @returns The corresponding PgColumn.
      */
     getColumn(pathOrColumn) {
-        if (isString(pathOrColumn)) {
-            const columnName = assertDefinedPass(this.#columnDefinitionsMap.get(pathOrColumn), `Could not map ${pathOrColumn} to column.`).name;
-            return this.#table[columnName];
-        }
-        return this.#table[pathOrColumn.name];
+        return this.resolveTargetColumn(pathOrColumn);
     }
     getColumns(pathOrColumns) {
         return pathOrColumns.map((column) => this.getColumn(column));
@@ -869,19 +926,20 @@ let EntityRepository = class EntityRepository extends Transactional {
     convertOrderBy(order) {
         if (isArray(order)) {
             return order.map((item) => {
-                const itemIsArray = isArray(item);
-                const target = itemIsArray ? item[0] : item;
-                const column = isSQLWrapper(target) ? target : this.getColumn(target);
-                const direction = itemIsArray ? item[1] : 'asc';
+                const [target, direction = 'asc'] = isArray(item) ? item : [item];
+                const column = this.resolveTargetColumn(target);
                 return direction == 'asc' ? asc(column) : desc(column);
             });
         }
+        if (isSQLWrapper(order) || (order instanceof SQL) || (order instanceof SQL.Aliased)) {
+            return [asc(order)];
+        }
         if (isString(order)) {
-            const column = this.getColumn(order);
+            const column = this.resolveTargetColumn(order);
             return [asc(column)];
         }
         return objectEntries(order).map(([path, direction]) => {
-            const column = this.getColumn(path);
+            const column = this.resolveTargetColumn(path);
             return direction == 'asc' ? asc(column) : desc(column);
         });
     }
@@ -983,7 +1041,7 @@ let EntityRepository = class EntityRepository extends Transactional {
             .with(false, () => applyTo.select(selection))
             .with(true, () => applyTo.selectDistinct(selection))
             .otherwise((targets) => {
-            const ons = targets.map((target) => isString(target) ? this.getColumn(target) : target);
+            const ons = targets.map((target) => resolveTargetColumn(target, this.#table, this.#columnDefinitionsMap));
             return applyTo.selectDistinctOn(ons, selection);
         });
         return selectBuilder;
@@ -1072,6 +1130,18 @@ let EntityRepository = class EntityRepository extends Transactional {
         }
         return await this.#transformContext;
     }
+    async _mapSearchResults(rowsPromise, scoreColumnName, highlightColumnName, scoreTransformer = (s) => s) {
+        const rows = await rowsPromise;
+        const transformContext = await this.getTransformContext();
+        return await toArrayAsync(mapAsync(rows, async (row) => {
+            const { [scoreColumnName]: rawScore, [highlightColumnName]: highlight, ...entityRow } = row;
+            return {
+                entity: await this._mapToEntity(entityRow, transformContext),
+                score: scoreTransformer(rawScore),
+                highlight: highlight,
+            };
+        }));
+    }
 };
 EntityRepository = __decorate([
     Singleton()

package/orm/server/types.d.ts

@@ -1,5 +1,5 @@
 import type { BuildColumns, NotNull } from 'drizzle-orm';
-import type { PgColumnBuilder, PgTableWithColumns } from 'drizzle-orm/pg-core';
+import type { ExtraConfigColumn, PgColumn, PgColumnBuilder, PgTableWithColumns } from 'drizzle-orm/pg-core';
 import type { CamelCase, ConditionalPick, SnakeCase } from 'type-fest';
 import type { JsonPath } from '../../json-path/json-path.js';
 import type { Record } from '../../schema/index.js';
@@ -27,11 +27,19 @@ type Column<Name extends string, T> = null extends T ? ColumnBuilder<Exclude<T,
 export type ColumnPrefix<T> = T extends Tagged<unknown, EmbeddedConfigTag, {
     prefix: infer Prefix;
 }> ? Prefix extends string ? Prefix : '' : '';
+export type ExtraConfigColumnsFromType<T extends EntityType = EntityType> = {
+    [P in keyof PgTableColumnsFromType<T>]: PgTableColumnsFromType<T>[P] extends PgColumn<infer U> ? ExtraConfigColumn<U> : never;
+};
+export type PgTableColumnsFromType<T extends EntityType, TableName extends string = string> = BuildColumns<TableName, {
+    [P in Exclude<keyof InstanceType<T>, keyof EmbeddedProperties<InstanceType<T>>>]: Column<CamelCase<Extract<P, string>>, InstanceType<T>[P]>;
+} & UnionToIntersection<{
+    [P in keyof EmbeddedProperties<InstanceType<T>>]: EmbeddedColumns<InstanceType<T>[P], ColumnPrefix<InstanceType<T>[P]>>;
+}[keyof EmbeddedProperties<InstanceType<T>>]>, 'pg'>;
 export type PgTableFromType<T extends EntityType = EntityType, S extends string = string, TableName extends string = T extends Required<EntityType> ? SnakeCase<T['entityName']> : string> = PgTableWithColumns<{
     name: TableName;
     schema: S;
     columns: BuildColumns<TableName, {
-        [P in Exclude<Exclude<keyof InstanceType<T>, '__entityMeta__'>, keyof EmbeddedProperties<InstanceType<T>>>]: Column<CamelCase<Extract<P, string>>, InstanceType<T>[P]>;
+        [P in Exclude<keyof InstanceType<T>, keyof EmbeddedProperties<InstanceType<T>>>]: Column<CamelCase<Extract<P, string>>, InstanceType<T>[P]>;
     } & UnionToIntersection<{
         [P in keyof EmbeddedProperties<InstanceType<T>>]: EmbeddedColumns<InstanceType<T>[P], ColumnPrefix<InstanceType<T>[P]>>;
     }[keyof EmbeddedProperties<InstanceType<T>>]>, 'pg'>;

package/orm/sqls.d.ts

@@ -1,5 +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 { 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>;
@@ -160,7 +161,7 @@ export declare function websearchToTsQuery(language: string | SQL, text: string
  * @param weight The weight to assign.
  * @returns A Drizzle SQL object representing the weighted tsvector.
  */
-export declare function setweight(tsvector: SQL, weight: 'A' | 'B' | 'C' | 'D'): SQL;
+export declare function setweight(tsvector: SQL, weight: TsVectorWeight): SQL;
 /**
  * Creates a PostgreSQL `ts_rank_cd` function call for relevance ranking.
  * @param tsvector The document's tsvector.
@@ -196,26 +197,23 @@ export declare function tsHeadline(language: string | SQL, document: string | SQ
 export declare function similarity(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<number>;
 /**
  * Creates a PostgreSQL `word_similarity` function call (from pg_trgm extension).
- * Calculates the word similarity between two strings based on trigram matching.
+ * 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.
  * @param left The first text column or expression.
  * @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>;
 /**
- * Creates a PostgreSQL `%` operator call (from pg_trgm extension) for similarity check.
- * Returns true if the similarity between the two arguments is greater than the current similarity threshold.
- * @param left The text column or expression.
- * @param right The text value or expression to compare against.
- * @returns A Drizzle SQL object representing a boolean similarity check.
+ * Creates a PostgreSQL `strict_word_similarity` function call (from pg_trgm extension).
+ * Same as `word_similarity`, but forces extent boundaries to match word boundaries.
+ * @param left The first text column or expression.
+ * @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>;
-/**
- * Creates a PostgreSQL `<->` operator call (from pg_trgm extension) for similarity distance.
- * Returns the "distance" between the arguments, that is one minus the similarity() value.
- * This is useful for ordering by similarity with an index.
- * @param left The text column or expression.
- * @param right The text value or expression to compare against.
- * @returns A Drizzle SQL object representing the similarity distance.
- */
-export declare function similarityDistance(left: string | SQL | SQL.Aliased | AnyColumn, right: string | SQL | SQL.Aliased | AnyColumn): SQL<number>;
+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>;