@tstdl/base 0.93.21 → 0.93.23

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>;

package/orm/sqls.js

@@ -213,7 +213,7 @@ export function similarity(left, right) {
 }
 /**
  * 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).
@@ -224,27 +224,44 @@ export function wordSimilarity(left, right) {
     return sql `word_similarity(${leftSql}, ${rightSql})`;
 }
 /**
- * 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 function strictWordSimilarity(left, right) {
+    const leftSql = isString(left) ? sql `${left}` : left;
+    const rightSql = isString(right) ? sql `${right}` : right;
+    return sql `strict_word_similarity(${leftSql}, ${rightSql})`;
+}
 export function isSimilar(left, right) {
     const leftSql = isString(left) ? sql `${left}` : left;
     const rightSql = isString(right) ? sql `${right}` : right;
-    return sql `(${leftSql}) % (${rightSql})`;
+    return sql `(${leftSql} % ${rightSql})`;
 }
-/**
- * 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 function similarityDistance(left, right) {
+export function isWordSimilar(left, right) {
+    const leftSql = isString(left) ? sql `${left}` : left;
+    const rightSql = isString(right) ? sql `${right}` : right;
+    return sql `(${leftSql} <% ${rightSql})`;
+}
+export function isStrictWordSimilar(left, right) {
+    const leftSql = isString(left) ? sql `${left}` : left;
+    const rightSql = isString(right) ? sql `${right}` : right;
+    return sql `(${leftSql} <<% ${rightSql})`;
+}
+export function distance(left, right) {
+    const leftSql = isString(left) ? sql `${left}` : left;
+    const rightSql = isString(right) ? sql `${right}` : right;
+    return sql `(${leftSql} <-> ${rightSql})`;
+}
+export function wordDistance(left, right) {
+    const leftSql = isString(left) ? sql `${left}` : left;
+    const rightSql = isString(right) ? sql `${right}` : right;
+    return sql `(${leftSql} <<-> ${rightSql})`;
+}
+export function strictWordDistance(left, right) {
     const leftSql = isString(left) ? sql `${left}` : left;
     const rightSql = isString(right) ? sql `${right}` : right;
-    return sql `(${leftSql}) <-> (${rightSql})`;
+    return sql `(${leftSql} <<<-> ${rightSql})`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.21",
+  "version": "0.93.23",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -136,7 +136,7 @@
   },
   "peerDependencies": {
     "@google-cloud/storage": "^7.17",
-    "@google/genai": "^1.27",
+    "@google/genai": "^1.28",
     "@tstdl/angular": "^0.93",
     "@zxcvbn-ts/core": "^3.0",
     "@zxcvbn-ts/language-common": "^3.0",

package/test/drizzle/0000_nervous_iron_monger.sql

@@ -0,0 +1,9 @@
+CREATE TABLE "test"."test" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"title" text NOT NULL,
+	"content" text NOT NULL,
+	"tags" text NOT NULL,
+	"language" text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX "test_id_title_content_tags_idx" ON "test"."test" USING bm25 ("id","title","content","tags") WITH (key_field='id');

package/test/drizzle/meta/0000_snapshot.json

@@ -1,5 +1,5 @@
 {
-  "id": "5c221821-4273-489d-b533-2f49653ab8d1",
+  "id": "e703ecc5-9f40-4ecb-848d-c1f3663d484c",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "version": "7",
   "dialect": "postgresql",
@@ -41,20 +41,40 @@
         }
       },
       "indexes": {
-        "test_title_content_tags_idx": {
-          "name": "test_title_content_tags_idx",
+        "test_id_title_content_tags_idx": {
+          "name": "test_id_title_content_tags_idx",
           "columns": [
             {
-              "expression": "(setweight(to_tsvector(\"language\"::regconfig, \"title\"), 'A') || setweight(to_tsvector(\"language\"::regconfig, \"content\"), 'B') || setweight(to_tsvector(\"language\"::regconfig, \"tags\"), 'C'))",
+              "expression": "id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "title",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "content",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "tags",
+              "isExpression": false,
               "asc": true,
-              "isExpression": true,
               "nulls": "last"
             }
           ],
           "isUnique": false,
           "concurrently": false,
-          "method": "gin",
-          "with": {}
+          "method": "bm25",
+          "with": {
+            "key_field": "'id'"
+          }
         }
       },
       "foreignKeys": {},

package/test/drizzle/meta/_journal.json

@@ -5,50 +5,8 @@
     {
       "idx": 0,
       "version": "7",
-      "when": 1760697525756,
-      "tag": "0000_sudden_sphinx",
-      "breakpoints": true
-    },
-    {
-      "idx": 1,
-      "version": "7",
-      "when": 1760974454017,
-      "tag": "0001_organic_rhodey",
-      "breakpoints": true
-    },
-    {
-      "idx": 2,
-      "version": "7",
-      "when": 1761138612314,
-      "tag": "0002_nice_squadron_supreme",
-      "breakpoints": true
-    },
-    {
-      "idx": 3,
-      "version": "7",
-      "when": 1761142229231,
-      "tag": "0003_serious_mockingbird",
-      "breakpoints": true
-    },
-    {
-      "idx": 4,
-      "version": "7",
-      "when": 1761143426736,
-      "tag": "0004_complete_pixie",
-      "breakpoints": true
-    },
-    {
-      "idx": 5,
-      "version": "7",
-      "when": 1761153443342,
-      "tag": "0005_bumpy_sabra",
-      "breakpoints": true
-    },
-    {
-      "idx": 6,
-      "version": "7",
-      "when": 1761153500086,
-      "tag": "0006_overrated_post",
+      "when": 1761843226770,
+      "tag": "0000_nervous_iron_monger",
       "breakpoints": true
     }
   ]