@tstdl/base 0.93.21 → 0.93.23

package/orm/server/query-converter.js

@@ -1,10 +1,35 @@
-import { and, eq, gt, gte, inArray, isNotNull, isNull, isSQLWrapper, lt, lte, ne, not, notInArray, or, SQL, sql } from 'drizzle-orm';
+import { and, Column, 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 { toArray } from '../../utils/array/index.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';
+import { assert, assertDefinedPass, isArray, isDefined, isPrimitive, isRegExp, isString, isUndefined } from '../../utils/type-guards.js';
+import { isSimilar, isStrictWordSimilar, isWordSimilar, phraseToTsQuery, plainToTsQuery, setweight, similarity, strictWordSimilarity, toTsQuery, toTsVector, websearchToTsQuery, wordSimilarity } from '../sqls.js';
 const sqlTrue = sql `true`;
+/**
+ * Resolves a target to a Drizzle PgColumn or SQLWrapper.
+ * @param target The target to resolve.
+ * @param table The Drizzle table object.
+ * @param columnDefinitionsMap A map from property names to column definitions.
+ */
+export function resolveTargetColumn(target, table, columnDefinitionsMap) {
+    if ((target instanceof SQL) || (target instanceof SQL.Aliased) || (target instanceof Column)) {
+        return target;
+    }
+    const columnDef = isString(target)
+        ? assertDefinedPass(columnDefinitionsMap.get(target), `Could not map property ${target} to column.`)
+        : target; // eslint-disable-line @typescript-eslint/no-unnecessary-type-assertion
+    return table[columnDef.name];
+}
+/**
+ * Resolves multiple targets to a Drizzle PgColumn or SQLWrapper.
+ * @param targets The targets to resolve.
+ * @param table The Drizzle table object.
+ * @param columnDefinitionsMap A map from property names to column definitions.
+ */
+export function resolveTargetColumns(targets, table, columnDefinitionsMap) {
+    return targets.map((target) => resolveTargetColumn(target, table, columnDefinitionsMap));
+}
 /**
  * Converts a query object into a Drizzle SQL condition.
  * Recursively handles nested logical operators and maps property names to database columns.
@@ -56,21 +81,41 @@ export function convertQuery(query, table, columnDefinitionsMap) {
                 }
                 break;
             }
-            case '$fts': {
-                const ftsQuery = value;
-                const method = ftsQuery.method ?? 'vector';
-                const sqlValue = match(method)
-                    .with('vector', () => {
-                    const tsquery = getTsQuery(ftsQuery.text, ftsQuery.vector?.language ?? 'simple', ftsQuery.vector?.parser ?? 'raw');
-                    const tsvector = getTsVector(ftsQuery.fields, ftsQuery.vector?.language ?? 'simple', table, columnDefinitionsMap, ftsQuery.vector?.weights);
-                    return sql `${tsvector} @@ ${tsquery}`;
-                })
-                    .with('trigram', () => {
-                    const searchExpression = getColumnConcatenation(ftsQuery.fields, table, columnDefinitionsMap);
-                    return isSimilar(searchExpression, ftsQuery.text);
-                })
-                    .exhaustive();
-                conditions.push(sqlValue);
+            case '$tsvector': {
+                const tsvectorQuery = value.$tsvector;
+                const fields = assertDefinedPass(tsvectorQuery.fields, '`fields` is required for tsvector search.');
+                const convertedFields = fields.map((target) => {
+                    const [field, weight] = isArray(target) ? target : [target, undefined];
+                    const sqlField = resolveTargetColumn(field, table, columnDefinitionsMap);
+                    if (isDefined(weight)) {
+                        return [sqlField, weight];
+                    }
+                    return sqlField;
+                });
+                const tsquery = getTsQuery(tsvectorQuery.query, tsvectorQuery.language ?? 'simple', tsvectorQuery.parser ?? 'raw');
+                const tsvector = getTsVector(convertedFields, tsvectorQuery.language ?? 'simple');
+                conditions.push(sql `${tsvector} @@ ${tsquery}`);
+                break;
+            }
+            case '$trigram': {
+                const trigramQuery = value.$trigram;
+                const fields = isArray(trigramQuery.fields) ? trigramQuery.fields : [trigramQuery.fields];
+                const convertedFields = fields.map((target) => resolveTargetColumn(target, table, columnDefinitionsMap));
+                const searchExpression = sql `(${sql.join(convertedFields, sql ` || ' ' || `)})`;
+                if (isDefined(trigramQuery.threshold)) {
+                    const similarityFn = getTrigramSimilarityFunction(trigramQuery.type);
+                    conditions.push(sql `${similarityFn(trigramQuery.query, searchExpression)} > ${trigramQuery.threshold}`);
+                }
+                else {
+                    const isSimilarOperator = getTrigramIsSimilarOperator(trigramQuery.type);
+                    conditions.push(isSimilarOperator(trigramQuery.query, searchExpression));
+                }
+                break;
+            }
+            case '$parade': {
+                const paradeQuery = value.$parade;
+                const convertedParadeQuery = convertParadeDbQuery(paradeQuery, table, columnDefinitionsMap);
+                conditions.push(sql `${table.id} @@@ ${convertedParadeQuery}`);
                 break;
             }
             default: {
@@ -167,18 +212,53 @@ function getCondition(property, value, column, table, columnDefinitionsMap) {
         const operator = (regexp.flags?.includes('i') ?? false) ? sql.raw('~*') : sql.raw('~');
         return sql `${column} ${operator} ${regexp.value}`;
     }
-    if (hasOwnProperty(value, '$fts')) {
-        const queryValue = value.$fts;
-        const { query, method = 'vector', language = 'simple', parser = 'plain' } = isString(queryValue)
+    if (hasOwnProperty(value, '$tsvector')) {
+        const queryValue = value.$tsvector;
+        const { query, 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, '$trigram')) {
+        const queryValue = value.$trigram;
+        const { query, type, threshold } = isString(queryValue) ? { query: queryValue } : queryValue;
+        if (isDefined(threshold)) {
+            const similarityFn = getTrigramSimilarityFunction(type);
+            return sql `${similarityFn(column, query)} > ${threshold}`;
+        }
+        return isSimilar(column, query);
+    }
+    if (hasOwnProperty(value, '$match')) {
+        const queryValue = value.$match;
+        const { query, distance, prefix, conjunctionMode } = isString(queryValue) ? { query: queryValue } : queryValue;
+        const parts = [sql `field => ${column.name}`, sql `value => ${query}`];
+        if (isDefined(distance)) {
+            parts.push(sql `distance => ${distance}`);
+        }
+        if (isDefined(prefix)) {
+            parts.push(sql `prefix => ${prefix}`);
+        }
+        if (isDefined(conjunctionMode)) {
+            parts.push(sql `conjunction_mode => ${conjunctionMode}`);
+        }
+        const searchFn = sql `paradedb.match(${sql.join(parts, sql.raw(', '))})`;
+        return sql `${table.id} @@@ ${searchFn}`;
+    }
+    if (hasOwnProperty(value, '$tantivy')) {
+        const queryValue = value.$tantivy;
+        const { query, lenient, conjunctionMode } = isString(queryValue) ? { query: queryValue } : queryValue;
+        const parts = [sql `${query}`];
+        if (isDefined(lenient)) {
+            parts.push(sql `lenient => ${lenient}`);
+        }
+        if (isDefined(conjunctionMode)) {
+            parts.push(sql `conjunction_mode => ${conjunctionMode}`);
+        }
+        const searchFn = sql `paradedb.parse(${sql.join(parts, sql.raw(', '))})`;
+        return sql `${table.id} @@@ ${searchFn}`;
+    }
     if (hasOwnProperty(value, '$geoShape')) {
         throw new NotSupportedError('$geoShape is not supported.');
     }
@@ -187,6 +267,90 @@ function getCondition(property, value, column, table, columnDefinitionsMap) {
     }
     throw new Error(`Unsupported query type "${property}".`);
 }
+function getTrigramSimilarityFunction(type = 'phrase') {
+    return match(type)
+        .with('phrase', () => similarity)
+        .with('word', () => wordSimilarity)
+        .with('strict-word', () => strictWordSimilarity)
+        .exhaustive();
+}
+function getTrigramIsSimilarOperator(type = 'phrase') {
+    return match(type)
+        .with('phrase', () => isSimilar)
+        .with('word', () => isWordSimilar)
+        .with('strict-word', () => isStrictWordSimilar)
+        .exhaustive();
+}
+/**
+ * Recursively converts a ParadeDbQueryObject into a Drizzle SQL object representing the JSONB structure.
+ */
+function convertParadeDbQuery(query, table, columnDefinitionsMap) {
+    const entries = objectEntries(query);
+    assert(entries.length == 1, 'ParadeDB query object must have exactly one key.');
+    const [key, queryValue] = entries[0];
+    const buildObject = (properties) => {
+        const chunks = [];
+        for (const [propKey, propValue] of properties) {
+            chunks.push(sql `'${sql.raw(propKey)}', ${propValue}`);
+        }
+        return sql `jsonb_build_object(${sql.join(chunks, sql `, `)})`;
+    };
+    const convertRecursive = (subQuery) => {
+        return convertParadeDbQuery(subQuery, table, columnDefinitionsMap);
+    };
+    const innerSql = match(key)
+        .with('all', 'empty', () => sql `null`)
+        .with('term', 'fuzzy_term', 'regex', 'phrase', 'match', 'parse_with_field', 'exists', 'range', 'phrase_prefix', 'regex_phrase', 'range_term', 'range_intersects', 'range_contains', 'range_within', (_) => {
+        const properties = [];
+        for (const [propKey, propValue] of objectEntries(queryValue)) {
+            if (propKey == 'field') {
+                const column = resolveTargetColumn(propValue, table, columnDefinitionsMap);
+                properties.push([propKey, column.name]);
+            }
+            else {
+                properties.push([propKey, propValue]);
+            }
+        }
+        return buildObject(properties);
+    })
+        .with('parse', 'more_like_this', () => buildObject(objectEntries(queryValue)))
+        .with('boolean', () => {
+        const properties = [];
+        for (const [propKey, propValue] of objectEntries(queryValue)) {
+            const subQueries = toArray(propValue ?? []).map(convertRecursive);
+            properties.push([propKey, sql `jsonb_build_array(${sql.join(subQueries, sql `, `)})`]);
+        }
+        return buildObject(properties);
+    })
+        .with('boost', 'const_score', () => {
+        const properties = [];
+        for (const [propKey, propValue] of objectEntries(queryValue)) {
+            if (propKey == 'query') {
+                properties.push([propKey, convertRecursive(propValue)]);
+            }
+            else {
+                properties.push([propKey, propValue]);
+            }
+        }
+        return buildObject(properties);
+    })
+        .with('disjunction_max', 'term_set', (_k) => {
+        const properties = [];
+        const subqueryArrayKey = (key == 'disjunction_max') ? 'disjuncts' : 'terms';
+        for (const [propKey, propValue] of objectEntries(queryValue)) {
+            if (propKey == subqueryArrayKey) {
+                const subQueries = propValue.map(convertRecursive);
+                properties.push([propKey, sql `jsonb_build_array(${sql.join(subQueries, sql `, `)})`]);
+            }
+            else {
+                properties.push([propKey, propValue]);
+            }
+        }
+        return buildObject(properties);
+    })
+        .exhaustive();
+    return buildObject([[key, innerSql]]);
+}
 export function getTsQuery(text, language, parser) {
     switch (parser) {
         case 'raw':
@@ -201,23 +365,15 @@ export function getTsQuery(text, language, parser) {
             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];
+export function getTsVector(fields, language) {
+    const sqlFields = fields.map((fieldWithWeight) => {
+        const [field, weight] = isArray(fieldWithWeight) ? fieldWithWeight : [fieldWithWeight, undefined];
+        const vector = toTsVector(language, field);
         if (isDefined(weight)) {
             return setweight(vector, weight);
         }
         return vector;
-    }), sql ` || `);
-    return tsvector;
-}
-export function getColumnConcatenation(fields, table, columnDefinitionsMap) {
-    const columns = fields.map((field) => {
-        const columnDef = assertDefinedPass(columnDefinitionsMap.get(field), `Could not map property ${field} to column.`);
-        return table[columnDef.name];
     });
-    return sql `(${sql.join(columns, sql ` || ' ' || `)})`;
+    const mergedTsVector = sql.join(sqlFields, sql ` || `);
+    return mergedTsVector;
 }

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