@tstdl/base 0.93.9 → 0.93.10

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.query, ftsQuery.language ?? 'simple', ftsQuery.parser ?? 'raw');
+                    const tsvector = getTsVector(ftsQuery.fields, ftsQuery.language ?? 'simple', table, columnDefinitionsMap, ftsQuery.weights);
+                    return sql `${tsvector} @@ ${tsquery}`;
+                })
+                    .with('similarity', () => {
+                    const searchExpression = getSimilaritySearchExpression(ftsQuery.fields, table, columnDefinitionsMap);
+                    return isSimilar(searchExpression, ftsQuery.query);
+                })
+                    .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 getSimilaritySearchExpression(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.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 { afterResolve, resolveArgumentType, type Resolvable } from '../../injector/interfaces.js';
 import type { DeepPartial, OneOrMany, Paths, 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, 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,14 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
     [afterResolve](): void;
     private expirationLoop;
     protected getTransactionalContextData(): EntityRepositoryContext;
+    /**
+     * 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 +424,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 +444,7 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-    }>, "where" | "limit">;
+    }>, "limit" | "where">;
     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 { NotSupportedError } from '../../errors/not-supported.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,17 @@ 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, 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 { isSimilar, similarity, TRANSACTION_TIMESTAMP, tsHeadline, tsRankCd } from '../sqls.js';
 import { getColumnDefinitions, getColumnDefinitionsMap, getDrizzleTableFromType } from './drizzle/schema-converter.js';
-import { convertQuery } from './query-converter.js';
+import { convertQuery, getSimilaritySearchExpression, 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 searchHighlightColumn = '__tsl_highlight';
 export const repositoryType = Symbol('repositoryType');
 /**
  * Configuration class for EntityRepository.
@@ -92,6 +95,105 @@ let EntityRepository = class EntityRepository extends Transactional {
         };
         return context;
     }
+    /**
+     * 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) {
+        const { method = 'vector' } = query;
+        let whereClause;
+        let rankExpression;
+        let highlightExpression;
+        const rankEnabled = options?.rank ?? true;
+        match(method)
+            .with('similarity', () => {
+            if (isDefined(query.weights) || isDefined(query.parser) || isDefined(options?.highlight)) {
+                throw new NotSupportedError('`weights`, `parser`, and `highlight` are not applicable to similarity search.');
+            }
+            const searchExpression = getSimilaritySearchExpression(query.fields, this.table, this.#columnDefinitionsMap);
+            whereClause = isSimilar(searchExpression, query.query);
+            if (rankEnabled) {
+                rankExpression = isInstanceOf(options?.rank, SQL)
+                    ? options.rank
+                    : similarity(searchExpression, query.query);
+            }
+        })
+            .with('vector', () => {
+            const { language = 'simple' } = query;
+            const languageSql = isString(language) ? language : sql `${language}`;
+            const tsquery = getTsQuery(query.query, languageSql, query.parser ?? 'raw');
+            const tsvector = getTsVector(query.fields, languageSql, this.table, this.#columnDefinitionsMap, query.weights);
+            whereClause = sql `${tsvector} @@ ${tsquery}`;
+            if (rankEnabled) {
+                if (isInstanceOf(options?.rank, SQL)) {
+                    rankExpression = options.rank;
+                }
+                else {
+                    const rankOptions = isBoolean(options?.rank) ? undefined : options?.rank;
+                    rankExpression = tsRankCd(tsvector, tsquery, rankOptions);
+                }
+            }
+            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 ` || ' ' || `);
+                });
+                highlightExpression = tsHeadline(languageSql, document, tsquery, headlineOptions);
+            }
+        })
+            .exhaustive();
+        if (isDefined(options?.filter)) {
+            const filter = this.convertQuery(options.filter);
+            whereClause = and(whereClause, filter);
+        }
+        const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.getColumn(column)]));
+        if (isDefined(rankExpression)) {
+            selection[searchScoreColumn] = rankExpression.as(searchScoreColumn);
+        }
+        if (isDefined(highlightExpression)) {
+            selection[searchHighlightColumn] = highlightExpression.as(searchHighlightColumn);
+        }
+        let dbQuery = match(options?.distinct ?? false)
+            .with(false, () => this.session.select(selection))
+            .with(true, () => this.session.selectDistinct(selection))
+            .otherwise((targets) => {
+            const ons = targets.map((target) => isString(target) ? this.getColumn(target) : target);
+            return this.session.selectDistinctOn(ons, selection);
+        })
+            .from(this.#table)
+            .where(whereClause)
+            .$dynamic();
+        if (isDefined(options?.offset)) {
+            dbQuery = dbQuery.offset(options.offset);
+        }
+        if (isDefined(options?.limit)) {
+            dbQuery = dbQuery.limit(options.limit);
+        }
+        if (rankEnabled) {
+            const orderByExpressions = [];
+            if (isArray(options?.distinct)) {
+                const ons = options.distinct.map((target) => isString(target) ? this.getColumn(target) : target.getSQL());
+                orderByExpressions.push(...ons);
+            }
+            orderByExpressions.push(desc(sql.identifier(searchScoreColumn)));
+            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,
+        })));
+    }
     /**
      * Loads a single entity by its ID.
      * Throws `NotFoundError` if the entity is not found.

package/orm/sqls.d.ts

@@ -1,4 +1,4 @@
-import { type AnyColumn, type Column, type SQL } from 'drizzle-orm';
+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 { Uuid } from './types.js';
 /** Drizzle SQL helper for getting the current transaction's timestamp. Returns a Date object. */
@@ -7,18 +7,60 @@ export declare const TRANSACTION_TIMESTAMP: SQL<Date>;
 export declare const RANDOM_UUID_V4: SQL<Uuid>;
 /** Represents valid units for PostgreSQL interval values. */
 export type IntervalUnit = 'millennium' | 'millenniums' | 'millennia' | 'century' | 'centuries' | 'decade' | 'decades' | 'year' | 'years' | 'day' | 'days' | 'hour' | 'hours' | 'minute' | 'minutes' | 'second' | 'seconds' | 'millisecond' | 'milliseconds' | 'microsecond' | 'microseconds';
+export type TsHeadlineOptions = {
+    /**
+     * The longest headline to output.
+     * @default 35
+     */
+    maxWords?: number;
+    /**
+     * The shortest headline to output.
+     * @default 15
+     */
+    minWords?: number;
+    /**
+     * Words of this length or less will be dropped at the start and end of a headline, unless they are query terms.
+     * @default 3
+     */
+    shortWord?: number;
+    /**
+     * If true the whole document will be used as the headline, ignoring the preceding three parameters.
+     * @default false
+     */
+    highlightAll?: boolean;
+    /**
+     * Maximum number of text fragments to display. Default is 0, which selects a non-fragment-based headline generation method. A value greater than zero selects fragment-based headline generation.
+     * @default 0
+     */
+    maxFragments?: number;
+    /**
+     * The strings with which to delimit query words appearing in the document, to distinguish them from other excerpted words.
+     * @default '<b>'
+     */
+    startSel?: string;
+    /**
+     * The strings with which to delimit query words appearing in the document, to distinguish them from other excerpted words.
+     * @default '</b>'
+     */
+    stopSel?: string;
+    /**
+     * When more than one fragment is displayed, the fragments will be separated by this string.
+     * @default ' ... '
+     */
+    fragmentDelimiter?: string;
+};
 export declare function autoAlias<T>(column: AnyColumn<{
     data: T;
 }>): SQL.Aliased<T>;
 /**
- * Creates a Drizzle SQL interval expression.
+ * Creates a PostgreSQL interval expression.
  * @param value - The numeric value of the interval.
  * @param unit - The unit of the interval (e.g., 'day', 'hour').
  * @returns A Drizzle SQL object representing the interval.
  */
 export declare function interval(value: number, unit: IntervalUnit): SQL;
 /**
- * Creates a Drizzle SQL `array_agg` aggregate function call.
+ * Creates a PostgreSQL `array_agg` aggregate function call.
  * Aggregates values from a column into a PostgreSQL array.
  * @template T - The Drizzle column type.
  * @param column - The column to aggregate.
@@ -26,7 +68,7 @@ export declare function interval(value: number, unit: IntervalUnit): SQL;
  */
 export declare function arrayAgg<T extends Column>(column: T): SQL<SelectResultField<T>[]>;
 /**
- * Creates a Drizzle SQL `json_agg` aggregate function call.
+ * Creates a PostgreSQL `json_agg` aggregate function call.
  * Aggregates rows or column values into a JSON array.
  * @template T - The Drizzle table or column type.
  * @param tableOrColumn - The table or column to aggregate into JSON.
@@ -37,7 +79,7 @@ export declare namespace jsonAgg {
     var withNull: <T extends TableLike>(tableOrColumn: T) => SQL<(SelectResultField<GetSelectTableSelection<T>> | null)[]>;
 }
 /**
- * Creates a Drizzle SQL `coalesce` function call.
+ * Creates a PostgreSQL `coalesce` function call.
  * Returns the first non-null value from the provided list of columns or SQL expressions.
  * @template T - An array type of Drizzle Columns or SQL expressions.
  * @param columns - The columns or SQL expressions to check.
@@ -45,7 +87,7 @@ export declare namespace jsonAgg {
  */
 export declare function coalesce<T extends (Column | SQL)[]>(...columns: T): SQL<SelectResultField<T>[number]>;
 /**
- * Creates a Drizzle SQL `to_jsonb` function call.
+ * Creates a PostgreSQL `to_jsonb` function call.
  * Converts the input column or SQL expression to a JSONB value.
  * @template T - The Drizzle column or SQL expression type.
  * @param column - The column or SQL expression to convert.
@@ -53,14 +95,14 @@ export declare function coalesce<T extends (Column | SQL)[]>(...columns: T): SQL
  */
 export declare function toJsonb<T extends (Column | SQL)>(column: T): SQL<SelectResultField<T>>;
 /**
- * Creates a Drizzle SQL `num_nulls` function call.
+ * Creates a PostgreSQL `num_nulls` function call.
  * Counts the number of null arguments.
  * @param columns - The columns to check for nulls.
  * @returns A Drizzle SQL object representing the count of nulls.
  */
 export declare function numNulls(...columns: Column[]): SQL<number>;
 /**
- * Creates a Drizzle SQL `num_nonnulls` function call.
+ * Creates a PostgreSQL `num_nonnulls` function call.
  * Counts the number of non-null arguments.
  * @param columns - The columns to check for non-nulls.
  * @returns A Drizzle SQL object representing the count of non-nulls.
@@ -74,3 +116,96 @@ export declare function greatest<T extends (Column | SQL | number)[]>(...values:
     [P in keyof T]: T[P] extends number ? Exclude<T[P], number> | SQL<number> : T[P];
 }[number]>>;
 export declare function greatest<T>(...values: T[]): SQL<SelectResultField<T>>;
+export declare function toTsVector(language: string | SQL, column: Column | SQLChunk): SQL<string>;
+/**
+ * Creates a PostgreSQL `to_tsquery` function call.
+ * This function parses text into a tsquery, respecting operators like & (AND), | (OR), and ! (NOT).
+ * @param language The text search configuration (e.g., 'english').
+ * @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;
+/**
+ * Creates a PostgreSQL `plainto_tsquery` function call.
+ * This function parses text into tokens and normalizes them, creating a tsquery
+ * where tokens are joined by the AND operator. It's useful for raw user input.
+ * @param language The text search configuration (e.g., 'english').
+ * @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;
+/**
+ * Creates a PostgreSQL `phraseto_tsquery` function call.
+ * This function is similar to `plainto_tsquery` but creates a tsquery that searches for a phrase.
+ * @param language The text search configuration (e.g., 'english').
+ * @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;
+/**
+ * Creates a PostgreSQL `websearch_to_tsquery` function call.
+ * This function is similar to `plainto_tsquery` but also handles "quoted phrases"
+ * and prefixes terms with `-` or `!` for negation. It's suitable for web search style inputs.
+ * @param language The text search configuration (e.g., 'english').
+ * @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;
+/**
+ * Creates a PostgreSQL `setweight` function call.
+ * Assigns a weight ('A', 'B', 'C', 'D') to a tsvector.
+ * @param tsvector The tsvector to weight.
+ * @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;
+/**
+ * Creates a PostgreSQL `ts_rank_cd` function call for relevance ranking.
+ * @param tsvector The document's tsvector.
+ * @param tsquery The search query's tsquery.
+ * @param options Optional configuration for ranking, including weights and normalization.
+ * @returns A Drizzle SQL object representing the relevance score.
+ */
+export declare function tsRankCd(tsvector: SQL, tsquery: SQL, options?: {
+    weights?: number[];
+    normalization?: number;
+}): SQL<number>;
+/**
+ * Creates a PostgreSQL `ts_headline` function call for highlighting search results.
+ *
+ * @param language The text search configuration.
+ * @param document The original text column.
+ * @param tsquery The search query's tsquery.
+ * @param options Optional configuration object for ts_headline (e.g., { MaxWords: 10 }).
+ * @returns A Drizzle SQL object representing the highlighted text snippet.
+ *
+ * @warning If using HTML tags for `startSel` and `stopSel` (the default), be aware of
+ * 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 | AnyColumn, 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.
+ * @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 similarity(left: string | SQL | AnyColumn, right: string | SQL | 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.
+ */
+export declare function isSimilar(left: string | SQL | AnyColumn, right: string | SQL | 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 | AnyColumn, right: string | SQL | AnyColumn): SQL<number>;