@tstdl/base 0.93.21 → 0.93.22

package/orm/entity.js

@@ -14,7 +14,6 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 import { Defaulted, Integer } from '../schema/index.js';
 import { EmbeddedProperty, PrimaryKeyProperty } from './decorators.js';
 import { JsonProperty, TimestampProperty, UuidProperty } from './schemas/index.js';
-export const entityMeta = '__entityMeta__';
 /**
  * Base class for extensible metadata attributes associated with an entity.
  * Allows storing arbitrary key-value pairs.
@@ -96,4 +95,4 @@ export {
 /**
  * @deprecated Use BaseEntity instead.
  */
-BaseEntity as EntityWithoutMetadata, };
+BaseEntity as EntityWithoutMetadata };

package/orm/query.d.ts

@@ -1,7 +1,10 @@
 import type { SQL, SQLWrapper } from 'drizzle-orm';
+import type { LiteralUnion, UnionToIntersection } from 'type-fest';
 import type { Geometry } from '../types/geo-json.js';
 import type { Flatten, Record } from '../types/index.js';
 import type { UntaggedDeep } from '../types/tagged.js';
+import type { BaseEntity } from './entity.js';
+import type { TargetColumn } from './repository.types.js';
 /** Represents a logical query combining multiple sub-queries (e.g., $and, $or, $nor). */
 export type LogicalQuery<T = any> = LogicalAndQuery<T> | LogicalOrQuery<T> | LogicalNorQuery<T>;
 /** Union of keys representing logical query operators ('$and', '$or', '$nor'). */
@@ -15,16 +18,19 @@ export type ComparisonQueryBody<T = any> = {
 /** Represents either a full comparison query object or a direct value for equality comparison. */
 export type ComparisonQueryOrValue<T = any> = ComparisonQuery<T> | ComparisonValue<T>;
 /** Represents a comparison query using various operators like $eq, $ne, $gt, $in, etc. */
-export type ComparisonQuery<T = any> = Partial<ComparisonAndQuery<T> & ComparisonOrQuery<T> & ComparisonNotQuery<T> & ComparisonEqualsQuery<T> & ComparisonNotEqualsQuery<T> & ComparisonExistsQuery & ComparisonItemQuery<T> & ComparisonInQuery<T> & ComparisonNotInQuery<T> & ComparisonAllQuery<T> & ComparisonGreaterThanQuery<T> & ComparisonGreaterThanOrEqualsQuery<T> & ComparisonLessThanQuery<T> & ComparisonLessThanOrEqualsQuery<T> & ComparisonRegexQuery & ComparisonFtsQuery & ComparisonGeoShapeQuery & ComparisonGeoDistanceQuery>;
-export type FtsParser = 'raw' | 'plain' | 'phrase' | 'websearch';
+export type ComparisonQuery<T = any> = Partial<ComparisonAndQuery<T> & ComparisonOrQuery<T> & ComparisonNotQuery<T> & ComparisonEqualsQuery<T> & ComparisonNotEqualsQuery<T> & ComparisonExistsQuery & ComparisonItemQuery<T> & ComparisonInQuery<T> & ComparisonNotInQuery<T> & ComparisonAllQuery<T> & ComparisonGreaterThanQuery<T> & ComparisonGreaterThanOrEqualsQuery<T> & ComparisonLessThanQuery<T> & ComparisonLessThanOrEqualsQuery<T> & ComparisonRegexQuery & ComparisonTsVectorQuery & ComparisonTrigramQuery & ComparisonParadeMatchQuery & ComparisonParadeTantivyQuery & ComparisonGeoShapeQuery & ComparisonGeoDistanceQuery>;
+export type TsVectorParser = 'raw' | 'plain' | 'phrase' | 'websearch';
+export type TsVectorWeight = 'A' | 'B' | 'C' | 'D';
+export type TrigramSimilarityType = 'phrase' | 'word' | 'strict-word';
 /** Union of keys representing comparison query operators. */
 export type ComparisonQueryTypes = keyof ComparisonQuery;
 /** Array containing all valid comparison query operator keys. */
 export declare const allComparisonQueryTypes: ComparisonQueryTypes[];
 /** Represents specialized query types beyond simple comparisons. */
-export type SpecialQuery<T = any> = Partial<FullTextSearchQuery<T>>;
+export type SpecialQuery<T extends BaseEntity = BaseEntity> = FullTextSearchQuery<T>;
+export type FullTextSearchQuery<T extends BaseEntity = BaseEntity> = TsVectorSearchQuery<T> | TrigramSearchQuery<T> | ParadeDbSearchQuery<T>;
 /** Union of keys representing special query operators. */
-export type SpecialQueryTypes = keyof SpecialQuery;
+export type SpecialQueryTypes = keyof UnionToIntersection<SpecialQuery>;
 /** Array containing all valid special query operator keys. */
 export declare const allSpecialQueryTypes: SpecialQueryTypes[];
 /**
@@ -32,13 +38,13 @@ export declare const allSpecialQueryTypes: SpecialQueryTypes[];
  * or a structured query object using logical and comparison operators.
  * @template T - The type of the entity being queried.
  */
-export type Query<T = any> = SQLWrapper | QueryObject<UntaggedDeep<T>>;
+export type Query<T = any> = SQLWrapper | QueryObject<Extract<UntaggedDeep<T>, BaseEntity>>;
 /** Represents a structured query object, combining logical, comparison, and special queries. */
-export type QueryObject<T> = LogicalQuery<T> | (ComparisonQueryBody<T> & SpecialQuery<T>);
+export type QueryObject<T extends BaseEntity> = LogicalQuery<T> | (ComparisonQueryBody<T> & Partial<SpecialQuery<T>>);
 /** Union of all possible query operator keys (logical, comparison, special). */
 export type QueryTypes = LogicalQueryTypes | ComparisonQueryTypes | SpecialQueryTypes;
 /** Array containing all valid query operator keys. */
-export declare const allQueryTypes: ("$and" | "$or" | "$nor" | "$not" | "$eq" | "$neq" | "$exists" | "$item" | "$in" | "$nin" | "$all" | "$gt" | "$gte" | "$lt" | "$lte" | "$regex" | "$fts" | "$geoShape" | "$geoDistance")[];
+export declare const allQueryTypes: ("$and" | "$or" | "$nor" | "$not" | "$eq" | "$neq" | "$exists" | "$item" | "$in" | "$nin" | "$all" | "$gt" | "$gte" | "$lt" | "$lte" | "$regex" | "$tsvector" | "$trigram" | "$match" | "$tantivy" | "$geoShape" | "$geoDistance" | "$parade")[];
 /** Represents an AND logical query. All sub-queries must be true. */
 export type LogicalAndQuery<T = any> = {
     $and: readonly Query<T>[];
@@ -118,24 +124,45 @@ export type ComparisonRegexQuery = {
         flags: string;
     };
 };
-/** Represents a full-text search query. */
-export type ComparisonFtsQuery = {
-    $fts: string | {
+/** Represents a single-field tsvector full-text search query. */
+export type ComparisonTsVectorQuery = {
+    $tsvector: string | {
         query: string;
+        parser?: TsVectorParser;
         /**
-         * The search method to use.
-         * - 'vector': (Default) Standard full-text search using tsvector and tsquery.
-         * - 'similarity': Trigram-based similarity search using the pg_trgm extension.
+         * The language to use for the full-text search (e.g., 'english', 'simple').
          */
-        method?: 'vector' | 'similarity';
-        /**
-         * The parser to use for the query. Only applicable for 'vector' method.
-         */
-        parser?: FtsParser;
+        language?: string | SQL;
+    };
+};
+/** Represents a single-field trigram similarity search query. */
+export type ComparisonTrigramQuery = {
+    $trigram: string | {
+        query: string;
+        type?: TrigramSimilarityType;
         /**
-         * The text search configuration (e.g., 'english', 'simple'). Can also be a SQL object for dynamic configuration. Only applicable for 'vector' method.
+         * ### **WARNING**
+         * Using a threshold here impacts performance as it switches from the `%` operator to a similarity comparison requiring functions.
+         * Use `pg_trgm.similarity_threshold(threshold)`, `pg_trgm.word_similarity_threshold(threshold)` or `pg_trgm.-_similarity_threshold(threshold)` to set a global threshold instead and omit this option, if possible.
          */
-        language?: string | SQL;
+        threshold?: number;
+    };
+};
+/** Represents a ParadeDB match query. */
+export type ComparisonParadeMatchQuery = {
+    $match: string | {
+        query: string;
+        distance?: number;
+        prefix?: boolean;
+        conjunctionMode?: boolean;
+    };
+};
+/** Represents a ParadeDB parse query (Tantivy syntax). */
+export type ComparisonParadeTantivyQuery = {
+    $tantivy: string | {
+        query: string;
+        conjunctionMode?: boolean;
+        lenient?: boolean;
     };
 };
 /** Defines the possible spatial relationships for geospatial shape queries. */
@@ -162,46 +189,157 @@ export type ComparisonGeoDistanceQuery = {
         minDistance?: number;
     };
 };
-/** Represents a full-text search query across one or more fields. Used by the `search` repository method. */
-export type FullTextSearchQuery<T = any> = {
-    $fts: {
-        fields: readonly (Extract<keyof T, string>)[];
-        text: string | SQL<string>;
-        /**
-         * The search method to use.
-         * - 'vector': (Default) Standard full-text search using tsvector and tsquery.
-         * - 'trigram': Trigram-based similarity search using the pg_trgm extension.
-         */
-        method?: 'vector' | 'trigram';
-        vector?: {
-            /**
-             * The parser to use for the query. Only applicable for 'vector' method.
-             */
-            parser?: FtsParser;
-            /**
-             * The text search configuration (e.g., 'english', 'simple'). Can also be a SQL object for dynamic configuration. Only applicable for 'vector' method.
-             */
-            language?: string | SQL<string>;
-            /**
-             * Assigns weights to fields for ranking.
-             * Keys are field names from `fields`, values are 'A', 'B', 'C', or 'D'.
-             * Fields without a specified weight will use the default. Only applicable for 'vector' method.
-             */
-            weights?: Partial<Record<Extract<keyof T, string>, 'A' | 'B' | 'C' | 'D'>>;
-        };
-        trigram?: {
-            /**
-             * Type of similarity to use for 'trigram' search.
-             * - 'normal': Standard trigram similarity (default).
-             * - 'word': Word-based similarity.
-             * - 'strict-word': Strict word-based similarity.
-             * @default 'normal'
-             */
-            type?: 'phrase' | 'word' | 'strict-word';
-            /**
-             * Threshold for similarity matching (0 to 1). Only applicable for 'trigram' method.
-             */
-            threshold?: number | SQL<number>;
-        };
+/** Represents a multi-field tsvector search. */
+export type TsVectorSearchQuery<T extends BaseEntity = BaseEntity> = {
+    $tsvector: {
+        fields: readonly (TargetColumn<T> | readonly [TargetColumn<T>, TsVectorWeight])[];
+        query: string | SQL<string>;
+        parser?: TsVectorParser;
+        language?: string | SQL<string>;
     };
 };
+/** Represents a multi-field trigram search. */
+export type TrigramSearchQuery<T extends BaseEntity = BaseEntity> = {
+    $trigram: {
+        fields: readonly TargetColumn<T>[];
+        query: string | SQL<string>;
+        type?: TrigramSimilarityType;
+        threshold?: number;
+    };
+};
+/**
+ * Represents a ParadeDB tokenizer configuration object for a `match` query.
+ */
+export type ParadeDbTokenizerObject = {
+    type: LiteralUnion<'default' | 'whitespace' | 'raw' | 'keyword' | 'regex' | 'ngram' | 'source_code' | 'chinese_compatible' | 'chinese_lindera' | 'korean_lindera' | 'japanese_lindera' | 'jieba' | 'icu', string>;
+    [key: string]: any;
+};
+/**
+ * Represents a bound for a ParadeDB range query.
+ */
+type ParadeDbRangeBound<V> = {
+    included: V;
+} | {
+    excluded: V;
+};
+/** A recursive type representing the rich ParadeDB / Tantivy query DSL. */
+export type ParadeDbQueryObject<T extends BaseEntity = BaseEntity> = {
+    all?: null;
+    empty?: null;
+    term?: {
+        field: TargetColumn<T>;
+        value: any;
+    };
+    fuzzy_term?: {
+        field: TargetColumn<T>;
+        value: string;
+        distance?: number;
+        transposition_cost_one?: boolean;
+        prefix?: boolean;
+    };
+    regex?: {
+        field: TargetColumn<T>;
+        pattern: string;
+    };
+    phrase?: {
+        field: TargetColumn<T>;
+        phrases: readonly string[];
+        slop?: number;
+    };
+    match?: {
+        field: TargetColumn<T>;
+        value: string;
+        distance?: number;
+        prefix?: boolean;
+        conjunction_mode?: boolean;
+        tokenizer?: ParadeDbTokenizerObject;
+        transposition_cost_one?: boolean;
+    };
+    boolean?: {
+        must?: ParadeDbQueryObject<T> | readonly ParadeDbQueryObject<T>[];
+        should?: ParadeDbQueryObject<T> | readonly ParadeDbQueryObject<T>[];
+        must_not?: ParadeDbQueryObject<T> | readonly ParadeDbQueryObject<T>[];
+    };
+    boost?: {
+        query: ParadeDbQueryObject<T>;
+        factor: number;
+    };
+    const_score?: {
+        query: ParadeDbQueryObject<T>;
+        score: number;
+    };
+    disjunction_max?: {
+        disjuncts: readonly ParadeDbQueryObject<T>[];
+        tie_breaker?: number;
+    };
+    parse?: {
+        query_string: string | SQL<string>;
+        lenient?: boolean;
+        conjunction_mode?: boolean;
+    };
+    parse_with_field?: {
+        field: TargetColumn<T>;
+        query_string: string | SQL<string>;
+        lenient?: boolean;
+        conjunction_mode?: boolean;
+    };
+    exists?: {
+        field: TargetColumn<T>;
+    };
+    range?: {
+        field: TargetColumn<T>;
+        lower_bound?: ParadeDbRangeBound<any> | null;
+        upper_bound?: ParadeDbRangeBound<any> | null;
+        is_datetime?: boolean;
+    };
+    term_set?: {
+        terms: readonly ParadeDbQueryObject<T>[];
+    };
+    phrase_prefix?: {
+        field: TargetColumn<T>;
+        phrases: readonly string[];
+        max_expansions?: number;
+    };
+    regex_phrase?: {
+        field: TargetColumn<T>;
+        regexes: readonly string[];
+        slop?: number;
+        max_expansions?: number;
+    };
+    more_like_this?: {
+        key_value?: any;
+        document?: readonly [string, any][];
+        min_doc_frequency?: number;
+        max_doc_frequency?: number;
+        min_term_frequency?: number;
+        max_query_terms?: number;
+        min_word_length?: number;
+        max_word_length?: number;
+        boost_factor?: number;
+        stop_words?: readonly string[];
+    };
+    range_term?: {
+        field: TargetColumn<T>;
+        value: any;
+    };
+    range_intersects?: {
+        field: TargetColumn<T>;
+        lower_bound: ParadeDbRangeBound<any>;
+        upper_bound: ParadeDbRangeBound<any>;
+    };
+    range_contains?: {
+        field: TargetColumn<T>;
+        lower_bound: ParadeDbRangeBound<any>;
+        upper_bound: ParadeDbRangeBound<any>;
+    };
+    range_within?: {
+        field: TargetColumn<T>;
+        lower_bound: ParadeDbRangeBound<any>;
+        upper_bound: ParadeDbRangeBound<any>;
+    };
+};
+/** Represents a ParadeDB search using its native JSON-based query language. */
+export type ParadeDbSearchQuery<T extends BaseEntity = BaseEntity> = {
+    $parade: ParadeDbQueryObject<T>;
+};
+export {};

package/orm/query.js

@@ -1,8 +1,8 @@
 /** Array containing all valid logical query operator keys. */
 export const allLogicalQueryTypes = ['$and', '$or', '$nor'];
 /** Array containing all valid comparison query operator keys. */
-export const allComparisonQueryTypes = ['$all', '$not', '$eq', '$exists', '$gt', '$gte', '$in', '$item', '$lt', '$lte', '$neq', '$nin', '$regex', '$fts', '$geoDistance', '$geoShape'];
+export const allComparisonQueryTypes = ['$all', '$not', '$eq', '$exists', '$gt', '$gte', '$in', '$item', '$lt', '$lte', '$neq', '$nin', '$regex', '$tsvector', '$trigram', '$match', '$tantivy', '$geoDistance', '$geoShape'];
 /** Array containing all valid special query operator keys. */
-export const allSpecialQueryTypes = ['$fts'];
+export const allSpecialQueryTypes = ['$tsvector', '$trigram', '$parade'];
 /** Array containing all valid query operator keys. */
 export const allQueryTypes = [...allLogicalQueryTypes, ...allComparisonQueryTypes, ...allSpecialQueryTypes];

package/orm/repository.types.d.ts

@@ -3,9 +3,9 @@
  * Defines types used by ORM repositories for operations like loading, updating, and creating entities.
  * Includes types for ordering, loading options, and entity data structures for create/update operations.
  */
-import type { Paths, Record, SimplifyObject, TypedOmit } from '../types/index.js';
+import type { Path, Record, SimplifyObject, TypedOmit } from '../types/index.js';
 import type { UntaggedDeep } from '../types/tagged.js';
-import type { SQL, SQLWrapper } from 'drizzle-orm';
+import type { AnyColumn, SQL, SQLWrapper } from 'drizzle-orm';
 import type { PartialDeep } from 'type-fest';
 import type { BaseEntity, Entity, EntityMetadata } from './entity.js';
 import type { FullTextSearchQuery, Query } from './query.js';
@@ -18,13 +18,13 @@ type WithSql<T> = {
  * or a raw Drizzle SQLWrapper for a complex target.
  * @template T - The entity type.
  */
-export type TargetColumnPaths<T extends BaseEntity> = Paths<UntaggedDeep<T>>;
+export type TargetColumnPath<T extends BaseEntity = BaseEntity> = Path<UntaggedDeep<T>>;
 /**
  * Specifies the target column (e.g. for ordering, distinct on), which can be a property path within the entity
  * or a raw Drizzle SQLWrapper for a complex target.
  * @template T - The entity type.
  */
-export type TargetColumn<T extends BaseEntity> = TargetColumnPaths<T> | SQLWrapper;
+export type TargetColumn<T extends BaseEntity = BaseEntity> = TargetColumnPath<T> | SQL | SQL.Aliased | AnyColumn;
 /** Specifies the direction for ordering results ('asc' or 'desc'). */
 export type OrderDirection = 'asc' | 'desc';
 /**
@@ -78,13 +78,42 @@ export type HighlightOptions<T extends BaseEntity> = {
     /**
      * The source to generate the highlight from. Can be one or more property paths or a raw SQL expression.
      */
-    source: TargetColumnPaths<T> | SQL<string>;
-} & TsHeadlineOptions;
+    source: TargetColumnPath<T> | SQL<string>;
+} & (TsHeadlineOptions | ParadeDbHighlightOptions);
+/**
+ * Options for highlighting with ParadeDB (`pdb.snippet`).
+ */
+export type ParadeDbHighlightOptions = {
+    /**
+     * Limits the number of characters in the snippet. Defaults to 150.
+     */
+    maxNumChars?: number;
+    /**
+     * The tag to use for the start of a highlighted term. Defaults to '<b>'.
+     */
+    startTag?: string;
+    /**
+     * The tag to use for the end of a highlighted term. Defaults to '</b>'.
+     */
+    endTag?: string;
+    /**
+     * Limits the number of highlighted terms returned in the snippet.
+     */
+    limit?: number;
+    /**
+     * Ignores the first N highlighted terms.
+     */
+    offset?: number;
+};
 /**
  * Options for the `search` method.
  * @template T - The entity type.
  */
-export type SearchOptions<T extends BaseEntity> = SimplifyObject<FullTextSearchQuery<T>['$fts'] & TypedOmit<LoadManyOptions<T>, 'order'> & {
+export type SearchOptions<T extends BaseEntity> = SimplifyObject<TypedOmit<LoadManyOptions<T>, 'order'> & {
+    /**
+     * The search query to execute.
+     */
+    query: FullTextSearchQuery<T>;
     /**
      * An additional filter to apply to the search query.
      */
@@ -96,7 +125,7 @@ export type SearchOptions<T extends BaseEntity> = SimplifyObject<FullTextSearchQ
         score: SQL | SQL.Aliased<number>;
     }) => Order<T>);
     /**
-     * Whether to include a relevance score with each result. Only applicable for vector searches.
+     * Whether to include a relevance score with each result.
      * - If `true`, the default score is included.
      * - If a function is provided, it customizes the score calculation using the original score.
      * - If no order is specified, results are ordered by score descending, when score is enabled.
@@ -113,7 +142,7 @@ export type SearchOptions<T extends BaseEntity> = SimplifyObject<FullTextSearchQ
     /**
      * Enable and configure highlighting of search results.
      */
-    highlight?: TargetColumnPaths<T> | SQL<string> | HighlightOptions<T>;
+    highlight?: TargetColumnPath<T> | SQL<string> | HighlightOptions<T>;
 }>;
 /**
  * Represents a single result from a full-text search operation.