@tstdl/base 0.93.21 → 0.93.23

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.

package/orm/server/drizzle/schema-converter.js

@@ -1,4 +1,4 @@
-import { SQL, sql } from 'drizzle-orm';
+import { SQL } from 'drizzle-orm';
 import { toCamelCase, toSnakeCase } from 'drizzle-orm/casing';
 import { boolean, check, doublePrecision, foreignKey, index, integer, jsonb, pgSchema, primaryKey, text, unique, uniqueIndex, uuid } from 'drizzle-orm/pg-core';
 import { match, P } from 'ts-pattern';
@@ -6,25 +6,23 @@ import { MultiKeyMap } from '../../../data-structures/multi-key-map.js';
 import { tryGetEnumName } from '../../../enumeration/enumeration.js';
 import { NotSupportedError } from '../../../errors/not-supported.error.js';
 import { JsonPath } from '../../../json-path/json-path.js';
-import { setweight, toTsVector } from '../../../orm/sqls.js';
 import { reflectionRegistry } from '../../../reflection/registry.js';
 import { ArraySchema, BooleanSchema, DefaultSchema, EnumerationSchema, getObjectSchema, NullableSchema, NumberSchema, ObjectSchema, OptionalSchema, StringSchema, Uint8ArraySchema } from '../../../schema/index.js';
 import { compareByValueSelectionToOrder, orderRest } from '../../../utils/comparison.js';
 import { decodeText, encodeUtf8 } from '../../../utils/encoding.js';
 import { enumValues } from '../../../utils/enum.js';
 import { memoize, memoizeSingle } from '../../../utils/function/memoize.js';
-import { iif } from '../../../utils/helpers.js';
 import { compileDereferencer } from '../../../utils/object/dereference.js';
 import { fromEntries, objectEntries } from '../../../utils/object/object.js';
 import { assertDefined, assertDefinedPass, isArray, isDefined, isNotNullOrUndefined, isNull, isString, isUndefined } from '../../../utils/type-guards.js';
 import { resolveValueOrProvider } from '../../../utils/value-or-provider.js';
-import { bytea, numericDate, timestamp, tsvector } from '../../data-types/index.js';
+import { bytea, numericDate, timestamp } from '../../data-types/index.js';
 import { JsonSchema } from '../../schemas/json.js';
 import { NumericDateSchema } from '../../schemas/numeric-date.js';
 import { TimestampSchema } from '../../schemas/timestamp.js';
 import { UuidSchema } from '../../schemas/uuid.js';
 import { decryptBytes, encryptBytes } from '../encryption.js';
-import { convertQuery } from '../query-converter.js';
+import { convertQuery, resolveTargetColumn } from '../query-converter.js';
 const getDbSchema = memoizeSingle(pgSchema);
 export const getDrizzleTableFromType = memoize(_getDrizzleTableFromType);
 const columnDefinitionsSymbol = Symbol('columnDefinitions');
@@ -53,14 +51,18 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
     const columnDefinitions = getPostgresColumnEntries(type, dbSchema, tableName);
     const columnDefinitionsMap = new Map(columnDefinitions.map((column) => [column.objectPath.path, column]));
     function getColumn(table, propertyName) {
-        return assertDefinedPass(table[propertyName], `Property "${propertyName}" does not exist on ${type.name}`);
+        return resolveTargetColumn(propertyName, table, columnDefinitionsMap);
     }
     function buildIndex(table, data, columnName) {
-        const columns = (data.columns ?? [columnName]).map((columnValue) => {
+        const resolvedColumns = resolveValueOrProvider(data.columns ?? [columnName], table);
+        const columns = resolvedColumns.map((columnValue) => {
+            if (columnValue instanceof SQL) {
+                return columnValue;
+            }
             assertDefined(columnValue, 'Missing column name for index.');
-            const [columnName, columnOrder] = isString(columnValue) ? [columnValue] : columnValue;
+            const [columnNameOrConfig, columnOrder] = isArray(columnValue) ? columnValue : [columnValue];
             const order = columnOrder ?? data.order ?? 'asc';
-            let column = getColumn(table, columnName);
+            let column = isString(columnNameOrConfig) ? getColumn(table, columnNameOrConfig) : columnNameOrConfig;
             column = column[order]();
             if (data.options?.nulls == 'first') {
                 column = column.nullsFirst();
@@ -71,15 +73,22 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
             return column;
         });
         const indexFn = (data.options?.unique == true) ? uniqueIndex : index;
+        console.log({ name: data.options?.name ?? getIndexName(tableName, columns, { naming: data.options?.naming }) });
         let builder = indexFn(data.options?.name ?? getIndexName(tableName, columns, { naming: data.options?.naming })).using(data.options?.using ?? 'btree', ...columns);
         if (isDefined(data.options?.where)) {
             const query = convertQuery(data.options.where(table), table, columnDefinitionsMap);
             builder = builder.where(query.inlineParams());
         }
+        if (isDefined(data.options?.with)) {
+            builder = builder.with(data.options.with);
+        }
+        if (data.options?.concurrently == true) {
+            builder = builder.concurrently();
+        }
         return builder;
     }
     function buildPrimaryKey(table) {
-        const columns = primaryKeyColumnDefinitions.map((columnDefinition) => getColumn(table, columnDefinition.name));
+        const columns = primaryKeyColumnDefinitions.map((columnDefinition) => table[columnDefinition.name]);
         return primaryKey({
             name: mergedTableReflectionData.compundPrimaryKeyName ?? getPrimaryKeyName(tableName, columns, { naming: mergedTableReflectionData.compundPrimaryKeyNaming }),
             columns,
@@ -88,40 +97,33 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
     const primaryKeyColumnDefinitions = columnDefinitions.filter((columnDefinition) => columnDefinition.reflectionData?.primaryKey == true);
     const skipPrimaryKey = primaryKeyColumnDefinitions.length > 1;
     const columnEntries = columnDefinitions.map((entry) => [entry.name, entry.buildType({ skipPrimaryKey })]);
-    const fullTextSearchColumnEntries = tableReflectionDatas
-        .flatMap((tableReflectionData) => tableReflectionData.fullTextSearch ?? [])
-        .flatMap((ftsData) => getFullTextSearchColumns(ftsData, () => drizzleSchema, (property) => getColumn(drizzleSchema, property)));
-    const drizzleSchema = dbSchema.table(tableName, fromEntries([
-        ...columnEntries,
-        ...fullTextSearchColumnEntries,
-    ]), (drizzleTable) => {
+    const drizzleSchema = dbSchema.table(tableName, fromEntries(columnEntries), (drizzleTable) => {
         const table = drizzleTable;
-        const indexes = tableReflectionDatas.flatMap((tableReflectionData) => tableReflectionData.index).filter(isDefined).map((data) => buildIndex(drizzleTable, data));
-        const fullTextIndexes = tableReflectionDatas.flatMap((tableReflectionData) => tableReflectionData.fullTextSearch ?? []).flatMap((ftsData) => getFullTextSearchIndexes(ftsData, table, (property) => getColumn(drizzleTable, property)));
+        const indexes = tableReflectionDatas.flatMap((tableReflectionData) => tableReflectionData.index).filter(isDefined).map((data) => buildIndex(table, data));
         const checks = tableReflectionDatas.flatMap((tableReflectionData) => tableReflectionData.checks).filter(isDefined).map((data) => check(data.name, data.builder(table)));
         return [
             ...((primaryKeyColumnDefinitions.length > 1)
-                ? [buildPrimaryKey(drizzleTable)]
+                ? [buildPrimaryKey(table)]
                 : []),
             ...(columnDefinitions.map((columnDefinition) => {
                 const indexData = columnDefinition.reflectionData?.index;
                 if (isUndefined(indexData)) {
                     return undefined;
                 }
-                return buildIndex(drizzleTable, indexData, columnDefinition.name);
+                return buildIndex(table, indexData, columnDefinition.name);
             }).filter(isDefined)),
             ...tableReflectionDatas.flatMap((tableReflectionData) => {
                 return tableReflectionData.foreignKeys?.map((foreignKeyData) => {
                     const foreignTable = getDrizzleTableFromType(foreignKeyData.target(), dbSchema.schemaName);
                     return foreignKey({
                         name: foreignKeyData.options?.name ?? getForeignKeyName(tableName, foreignKeyData.columns, { naming: foreignKeyData.options?.naming }),
-                        columns: foreignKeyData.columns.map((column) => getColumn(drizzleTable, column)),
+                        columns: foreignKeyData.columns.map((column) => getColumn(table, column)),
                         foreignColumns: foreignKeyData.foreignColumns.map((column) => getColumn(foreignTable, column)),
                     });
                 }) ?? [];
             }),
             ...tableReflectionDatas.flatMap((tableReflectionData) => tableReflectionData.unique).filter(isDefined).map((data) => {
-                const columns = data.columns?.map((column) => getColumn(drizzleTable, column));
+                const columns = data.columns?.map((column) => getColumn(table, column));
                 let constraint = unique(data.options?.name ?? getUniqueName(tableName, columns, { naming: data.options?.naming })).on(...columns);
                 if (data.options?.nulls == 'not distinct') {
                     constraint = constraint.nullsNotDistinct();
@@ -129,7 +131,6 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
                 return constraint;
             }),
             ...indexes,
-            ...fullTextIndexes,
             ...checks,
         ];
     });
@@ -137,69 +138,6 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
     drizzleSchema[columnDefinitionsMapSymbol] = columnDefinitionsMap;
     return drizzleSchema;
 }
-function getFullTextSearchColumns(data, tableProvider, columnProvider) {
-    if (isDefined(data.vector)) {
-        const name = `fts_v_${data.name}`;
-        const generationSource = () => {
-            const table = tableProvider();
-            const source = assertDefinedPass(resolveValueOrProvider(data.source ?? data.vector?.rawVectorSource, table), 'Either "source" or "vector.rawVectorSource" must be provided for full-text search vector generation.');
-            const language = resolveValueOrProvider(data.vector?.language ?? 'simple', table);
-            return match(source)
-                .with(P.instanceOf(SQL), (sqlExpression) => sqlExpression)
-                .otherwise((paths) => {
-                const vectors = paths.map((property) => {
-                    const column = columnProvider(property);
-                    const tsVector = toTsVector(language, column);
-                    const weight = data.vector?.weights?.[property];
-                    if (isDefined(weight)) {
-                        return setweight(tsVector, weight);
-                    }
-                    return tsVector;
-                });
-                return sql `(${sql.join(vectors, sql ` || `)})`;
-            });
-        };
-        const column = tsvector(name).generatedAlwaysAs(generationSource);
-        return [[name, column]];
-    }
-    return [];
-}
-function getFullTextSearchIndexes(data, table, columnProvider) {
-    return [
-        ...iif(isDefined(data.vector), () => {
-            const indexName = `fts_${data.name}_bm25`;
-            const textSource = assertDefinedPass(data.source, 'Either "source" or "vector.rawVectorSource" must be provided for full-text search vector generation.');
-            const source = resolveValueOrProvider(textSource, table);
-            const indexExpression = match(source)
-                .with(P.instanceOf(SQL), (sqlExpression) => sqlExpression)
-                .otherwise((paths) => {
-                const columns = paths.map((property) => columnProvider(property));
-                return sql `(${sql.join(columns, sql ` || `)})`;
-            });
-            const bm25Index = index(indexName).using('bm25', indexExpression).with({ key_field: 'id' });
-            return [bm25Index];
-        }, () => []),
-        ...iif(isDefined(data.vector), () => {
-            const columnName = `fts_v_${data.name}`;
-            const indexName = `${columnName}_gin`;
-            const ginIndex = index(indexName).using('gin', columnProvider(columnName)).with({ fastupdate: 'off' });
-            return [ginIndex];
-        }, () => []),
-        ...iif(isDefined(data.trigram), () => {
-            const indexName = `fts_t_${data.name}_gist`;
-            const textSource = assertDefinedPass(data.source, 'Either "source" or "vector.rawVectorSource" must be provided for full-text search vector generation.');
-            const source = resolveValueOrProvider(textSource, table);
-            const indexExpression = match(source)
-                .with(P.instanceOf(SQL), (sqlExpression) => sqlExpression)
-                .otherwise((paths) => {
-                const columns = paths.map((property) => columnProvider(property));
-                return sql `(${sql.join(columns, sql ` || `)})`;
-            });
-            const gistIndex = index(indexName).using('gist', indexExpression).with({ fastupdate: 'off' });
-            return [gistIndex];
-        }, () => []),
-    ];
-}
 function getPostgresColumnEntries(type, dbSchema, tableName, path = new JsonPath({ dollar: false }), prefix = '') {
     const metadata = reflectionRegistry.getMetadata(type);
     assertDefined(metadata, `Type ${type.name} does not have reflection metadata (path: ${path.toString()}).`);
@@ -289,41 +227,25 @@ function getPostgresBaseColumn(columnName, dbSchema, schema, reflectionData, con
     if (reflectionData.encrypted) {
         return bytea(columnName);
     }
-    if (schema instanceof UuidSchema) {
+    return match(schema)
+        .with(P.instanceOf(UuidSchema), (s) => {
         let column = uuid(columnName);
-        if (schema.defaultRandom) {
+        if (s.defaultRandom) {
             column = column.defaultRandom();
         }
         return column;
-    }
-    if (schema instanceof TimestampSchema) {
-        return timestamp(columnName);
-    }
-    if (schema instanceof NumericDateSchema) {
-        return numericDate(columnName);
-    }
-    if (schema instanceof NumberSchema) {
-        return schema.integer
-            ? integer(columnName)
-            : doublePrecision(columnName);
-    }
-    if (schema instanceof StringSchema) {
-        return text(columnName);
-    }
-    if (schema instanceof BooleanSchema) {
-        return boolean(columnName);
-    }
-    if (schema instanceof EnumerationSchema) {
-        const pgEnum = getPgEnum(dbSchema, schema.enumeration, context);
-        return pgEnum(columnName);
-    }
-    if (schema instanceof JsonSchema) {
-        return jsonb(columnName);
-    }
-    if (schema instanceof Uint8ArraySchema) {
-        return bytea(columnName);
-    }
-    throw new NotSupportedError(`Schema "${schema.constructor.name}" not supported on type "${context.type.name}" for property "${context.property}"`);
+    })
+        .with(P.instanceOf(TimestampSchema), () => timestamp(columnName))
+        .with(P.instanceOf(NumericDateSchema), () => numericDate(columnName))
+        .with(P.instanceOf(NumberSchema), (s) => (s.integer ? integer(columnName) : doublePrecision(columnName)))
+        .with(P.instanceOf(StringSchema), () => text(columnName))
+        .with(P.instanceOf(BooleanSchema), () => boolean(columnName))
+        .with(P.instanceOf(EnumerationSchema), (s) => getPgEnum(dbSchema, s.enumeration, context)(columnName))
+        .with(P.instanceOf(JsonSchema), () => jsonb(columnName))
+        .with(P.instanceOf(Uint8ArraySchema), () => bytea(columnName))
+        .otherwise(() => {
+        throw new NotSupportedError(`Schema "${schema.constructor.name}" not supported on type "${context.type.name}" for property "${context.property}"`);
+    });
 }
 const enumNames = new Map();
 const enums = new MultiKeyMap();

package/orm/server/query-converter.d.ts

@@ -1,7 +1,22 @@
-import { SQL } from 'drizzle-orm';
-import type { Record } from '../../types/index.js';
-import type { FtsParser, Query } from '../query.js';
-import type { ColumnDefinition, PgTableFromType } from './types.js';
+import { SQL, type SQLWrapper } from 'drizzle-orm';
+import type { BaseEntity } from '../entity.js';
+import type { Query, TsVectorParser, TsVectorWeight } from '../query.js';
+import type { TargetColumn } from '../repository.types.js';
+import type { ColumnDefinition, ExtraConfigColumnsFromType, PgTableFromType } from './types.js';
+/**
+ * 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 declare function resolveTargetColumn<T extends BaseEntity>(target: TargetColumn<T> | ColumnDefinition, table: PgTableFromType | ExtraConfigColumnsFromType, columnDefinitionsMap: Map<string, ColumnDefinition>): SQLWrapper;
+/**
+ * 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 declare function resolveTargetColumns<T extends BaseEntity>(targets: (TargetColumn<T> | ColumnDefinition)[], table: PgTableFromType, columnDefinitionsMap: Map<string, ColumnDefinition>): SQLWrapper[];
 /**
  * Converts a query object into a Drizzle SQL condition.
  * Recursively handles nested logical operators and maps property names to database columns.
@@ -15,6 +30,5 @@ import type { ColumnDefinition, PgTableFromType } from './types.js';
  * @throws {Error} If an unsupported query type is encountered.
  */
 export declare function convertQuery(query: Query, table: PgTableFromType, columnDefinitionsMap: Map<string, ColumnDefinition>): SQL;
-export declare function getTsQuery(text: string | SQL, language: string | SQL, parser: FtsParser): SQL;
-export declare function getTsVector(fields: readonly string[], language: string | SQL, table: PgTableFromType, columnDefinitionsMap: Map<string, ColumnDefinition>, weights?: Partial<Record<string, 'A' | 'B' | 'C' | 'D'>>): SQL;
-export declare function getColumnConcatenation(fields: readonly string[], table: PgTableFromType, columnDefinitionsMap: Map<string, ColumnDefinition>): SQL;
+export declare function getTsQuery(text: string | SQL, language: string | SQL, parser: TsVectorParser): SQL;
+export declare function getTsVector(fields: readonly (SQLWrapper | readonly [field: SQLWrapper, weight?: TsVectorWeight])[], language: string | SQL): SQL;