@tstdl/base 0.92.123 → 0.92.125

package/orm/entity.js

@@ -7,15 +7,26 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+/**
+ * @module
+ * Defines base entity classes and related types for the ORM.
+ */
 import { Defaulted, Integer } from '../schema/index.js';
 import { PrimaryKey } from './decorators.js';
 import { Embedded, Json, Timestamp, Uuid } from './types.js';
+/**
+ * Base class for extensible metadata attributes associated with an entity.
+ * Allows storing arbitrary key-value pairs.
+ */
 let EntityMetadataAttributes = class EntityMetadataAttributes {
 };
 EntityMetadataAttributes = __decorate([
     Json()
 ], EntityMetadataAttributes);
 export { EntityMetadataAttributes };
+/**
+ * Base class defining common metadata fields for entities, such as revision tracking and timestamps.
+ */
 export class EntityMetadata {
     revision;
     revisionTimestamp;
@@ -43,6 +54,10 @@ __decorate([
     Defaulted(EntityMetadataAttributes, {}),
     __metadata("design:type", Object)
 ], EntityMetadata.prototype, "attributes", void 0);
+/**
+ * Abstract base class for entities that include standard metadata.
+ * Provides a default `id` (UUID primary key) and an `metadata` field.
+ */
 export class Entity {
     id;
     metadata;
@@ -56,6 +71,10 @@ __decorate([
     Embedded(EntityMetadata, { prefix: null }),
     __metadata("design:type", Object)
 ], Entity.prototype, "metadata", void 0);
+/**
+ * Abstract base class for entities that do *not* include the standard metadata fields.
+ * Provides only a default `id` (UUID primary key). Useful for simpler tables or join tables.
+ */
 export class EntityWithoutMetadata {
     id;
 }

package/orm/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @module
+ * Barrel file exporting core ORM functionalities including data types,
+ * base entities, query types, repository types, SQL helpers, and utility types.
+ */
 export * from './data-types/index.js';
 export * from './entity.js';
 export * from './query.js';

package/orm/index.js

@@ -1,3 +1,8 @@
+/**
+ * @module
+ * Barrel file exporting core ORM functionalities including data types,
+ * base entities, query types, repository types, SQL helpers, and utility types.
+ */
 export * from './data-types/index.js';
 export * from './entity.js';
 export * from './query.js';

package/orm/query.d.ts

@@ -1,92 +1,140 @@
+/**
+ * @module
+ * Defines types for constructing database queries using a MongoDB-like syntax.
+ * Supports logical operators, comparison operators, and specialized queries like text search and geospatial queries.
+ */
 import type { SQLWrapper } from 'drizzle-orm';
 import type { Flatten, Record } from '../types.js';
 import type { Geometry } from '../types/geo-json.js';
 import type { UntaggedDeep } from '../types/tagged.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'). */
 export type LogicalQueryTypes = keyof (LogicalAndQuery & LogicalOrQuery & LogicalNorQuery);
+/** Array containing all valid logical query operator keys. */
 export declare const allLogicalQueryTypes: LogicalQueryTypes[];
+/** Represents the body of a comparison query, mapping field paths to comparison operators or values. Allows nested structures. */
 export type ComparisonQueryBody<T = any> = {
     [P in keyof T]?: T[P] extends Record ? ComparisonQueryBody<T[P]> : ComparisonQueryOrValue<T[P]>;
 } & Record<ComparisonQueryOrValue>;
+/** 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<ComparisonNotQuery<T> & ComparisonEqualsQuery<T> & ComparisonNotEqualsQuery<T> & ComparisonExistsQuery & ComparisonItemQuery<T> & ComparisonInQuery<T> & ComparisonNotInQuery<T> & ComparisonAllQuery<T> & ComparisonGreaterThanQuery<T> & ComparisonGreaterThanOrEqualsQuery<T> & ComparisonLessThanQuery<T> & ComparisonLessThanOrEqualsQuery<T> & ComparisonRegexQuery & ComparisonTextQuery & ComparisonGeoShapeQuery & ComparisonGeoDistanceQuery>;
+/** 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 (e.g., $textSpan). */
 export type SpecialQuery<T = any> = Partial<TextSpanQuery<T>>;
+/** Union of keys representing special query operators. */
 export type SpecialQueryTypes = keyof SpecialQuery;
+/** Array containing all valid special query operator keys. */
 export declare const allSpecialQueryTypes: SpecialQueryTypes[];
+/**
+ * Represents a complete query, which can be either a raw Drizzle SQLWrapper
+ * 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>>;
+/** Represents a structured query object, combining logical, comparison, and special queries. */
 export type QueryObject<T> = LogicalQuery<T> | (ComparisonQueryBody<T> & 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" | "$text" | "$geoShape" | "$geoDistance" | "$textSpan")[];
+/** Logical operators used within certain query types like $text. */
 export type Operator = 'and' | 'or';
+/** Array containing all valid logical operators ('and', 'or'). */
 export declare const allOperators: Operator[];
+/** Represents an AND logical query. All sub-queries must be true. */
 export type LogicalAndQuery<T = any> = {
     $and: readonly Query<T>[];
 };
+/** Represents an OR logical query. At least one sub-query must be true. */
 export type LogicalOrQuery<T = any> = {
     $or: readonly Query<T>[];
 };
+/** Represents a NOR logical query. All sub-queries must be false. */
 export type LogicalNorQuery<T = any> = {
     $nor: readonly Query<T>[];
 };
+/** Represents a value used in comparisons, can be a direct value, a flattened value, or a Drizzle SQLWrapper. */
 export type ComparisonValue<T> = T | Flatten<T> | SQLWrapper;
+/** Represents a comparison value that can also include a RegExp for string comparisons. */
 export type ComparisonValueWithRegex<T> = T extends string ? ComparisonValue<T | RegExp> : T extends readonly string[] ? ComparisonValue<readonly (Flatten<T> | RegExp)[]> : (T | Flatten<T>);
+/** Represents a NOT comparison query. Inverts the result of the nested comparison. */
 export type ComparisonNotQuery<T = any> = {
     $not: ComparisonQuery<T>;
 };
+/** Represents an equality comparison query ($eq). */
 export type ComparisonEqualsQuery<T = any> = {
     $eq: ComparisonValueWithRegex<T>;
 };
+/** Represents a non-equality comparison query ($neq). */
 export type ComparisonNotEqualsQuery<T = any> = {
     $neq: ComparisonValueWithRegex<T>;
 };
+/** Represents an existence check query ($exists). Checks if a field exists (or not). */
 export type ComparisonExistsQuery = {
     $exists: ComparisonValue<boolean>;
 };
+/** Represents a query targeting elements within an array field ($item). */
 export type ComparisonItemQuery<T = any> = {
     $item: T extends readonly (infer U)[] ? U extends Record ? Query<U> : ComparisonQuery<U> : never;
 };
+/** Represents an "in list" comparison query ($in). Checks if a field value is within a specified array. */
 export type ComparisonInQuery<T = any> = {
     $in: readonly ComparisonValueWithRegex<T>[];
 };
+/** Represents a "not in list" comparison query ($nin). Checks if a field value is not within a specified array. */
 export type ComparisonNotInQuery<T = any> = {
     $nin: readonly ComparisonValueWithRegex<T>[];
 };
+/** Represents an "all elements match" query ($all). Checks if an array field contains all specified values. */
 export type ComparisonAllQuery<T = any> = {
     $all: readonly ComparisonValueWithRegex<T>[];
 };
+/** Represents a "greater than" comparison query ($gt). */
 export type ComparisonGreaterThanQuery<T = any> = {
     $gt: ComparisonValue<T>;
 };
+/** Represents a "greater than or equals" comparison query ($gte). */
 export type ComparisonGreaterThanOrEqualsQuery<T = any> = {
     $gte: ComparisonValue<T>;
 };
+/** Represents a "less than" comparison query ($lt). */
 export type ComparisonLessThanQuery<T = any> = {
     $lt: ComparisonValue<T>;
 };
+/** Represents a "less than or equals" comparison query ($lte). */
 export type ComparisonLessThanOrEqualsQuery<T = any> = {
     $lte: ComparisonValue<T>;
 };
+/** Represents a regular expression comparison query ($regex). */
 export type ComparisonRegexQuery = {
     $regex: string | RegExp | {
         pattern: string;
         flags: string;
     };
 };
+/** Represents a full-text search query ($text). */
 export type ComparisonTextQuery = {
     $text: string | {
         text: string;
         operator?: Operator;
     };
 };
+/** Defines the possible spatial relationships for geospatial shape queries. */
 export type GeoShapeRelation = 'intersects' | 'within' | 'disjoint' | 'contains';
+/** Represents a geospatial query based on shape relationships ($geoShape). */
 export type ComparisonGeoShapeQuery = {
     $geoShape: {
         geometry: Geometry;
         relation: GeoShapeRelation;
     };
 };
+/** Represents a geospatial query based on distance from a point ($geoDistance). */
 export type ComparisonGeoDistanceQuery = {
     $geoDistance: {
         longitude: number;
@@ -101,8 +149,11 @@ export type ComparisonGeoDistanceQuery = {
         minDistance?: number;
     };
 };
+/** Defines the modes for text span queries, affecting how multiple field matches are handled. */
 export type TextSpanQueryMode = 'best' | 'most' | 'cross';
+/** Array containing all valid text span query modes. */
 export declare const allTextSpanQueryModes: TextSpanQueryMode[];
+/** Represents a text span query ($textSpan), searching for text across multiple fields. */
 export type TextSpanQuery<T = any> = {
     $textSpan: {
         fields: readonly (Extract<keyof T, string>)[];

package/orm/query.js

@@ -1,6 +1,12 @@
+/** 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', '$text', '$geoDistance', '$geoShape'];
+/** Array containing all valid special query operator keys. */
 export const allSpecialQueryTypes = ['$textSpan'];
+/** Array containing all valid query operator keys. */
 export const allQueryTypes = [...allLogicalQueryTypes, ...allComparisonQueryTypes, ...allSpecialQueryTypes];
+/** Array containing all valid logical operators ('and', 'or'). */
 export const allOperators = ['and', 'or'];
+/** Array containing all valid text span query modes. */
 export const allTextSpanQueryModes = ['best', 'most', 'cross'];

package/orm/repository.types.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @module
+ * 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, TypedOmit } from '../types.js';
 import type { UntaggedDeep } from '../types/tagged.js';
 import type { SQL, SQLWrapper } from 'drizzle-orm';
@@ -6,26 +11,73 @@ import type { Entity, EntityMetadata, EntityWithoutMetadata } from './entity.js'
 type WithSql<T> = {
     [P in keyof T]: T[P] extends Record ? WithSql<T[P]> : (T[P] | SQL);
 };
+/**
+ * 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 TargetColumnPaths<T extends EntityWithoutMetadata> = Paths<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 EntityWithoutMetadata> = TargetColumnPaths<T> | SQLWrapper;
+/** Specifies the direction for ordering results ('asc' or 'desc'). */
 export type OrderDirection = 'asc' | 'desc';
-export type OrderTarget<T extends EntityWithoutMetadata> = Paths<UntaggedDeep<T>> | SQLWrapper;
-export type Order<T extends EntityWithoutMetadata> = OrderTarget<T> | (OrderTarget<T> | [OrderTarget<T>, OrderDirection])[] | Partial<Record<Exclude<OrderTarget<T>, SQLWrapper>, OrderDirection>>;
+/**
+ * Defines how results should be ordered. Can be a single target, an array of targets
+ * (optionally with direction), or an object mapping property paths to directions.
+ * @template T - The entity type.
+ */
+export type Order<T extends EntityWithoutMetadata> = TargetColumn<T> | (TargetColumn<T> | [TargetColumn<T>, OrderDirection])[] | Partial<Record<Exclude<TargetColumn<T>, SQLWrapper>, OrderDirection>>;
+/**
+ * Options object containing ordering configuration.
+ * @template T - The entity type.
+ */
 export type OrderOptions<T extends EntityWithoutMetadata> = {
     order?: Order<T>;
 };
+/**
+ * Options for loading a single entity, including ordering and offset.
+ * @template T - The entity type.
+ */
 export type LoadOptions<T extends EntityWithoutMetadata> = OrderOptions<T> & {
     offset?: number;
 };
+/**
+ * Options for loading multiple entities, including ordering, offset, and limit.
+ * @template T - The entity type.
+ */
 export type LoadManyOptions<T extends EntityWithoutMetadata> = LoadOptions<T> & {
     limit?: number;
+    distinct?: boolean | TargetColumn<T>[];
 };
+/**
+ * Options for update operations (currently inherits from LoadOptions, primarily for ordering).
+ * @template T - The entity type.
+ */
 export type UpdateOptions<T extends EntityWithoutMetadata> = LoadOptions<T>;
+/** Type definition for updating entity metadata attributes, allowing partial updates and SQL expressions. */
 export type EntityMetadataUpdate = WithSql<Partial<UntaggedDeep<Pick<EntityMetadata, 'attributes'>>>>;
+/**
+ * Represents the data structure for creating a new entity.
+ * Excludes 'id' and 'metadata' by default, but allows providing an optional 'id' and partial 'metadata.attributes'.
+ * Allows SQL expressions for values.
+ * @template T - The entity type.
+ */
 export type NewEntity<T extends Entity | EntityWithoutMetadata> = T extends Entity ? WithSql<UntaggedDeep<TypedOmit<T, 'id' | 'metadata'> & {
     id?: string;
     metadata?: Partial<Pick<EntityMetadata, 'attributes'>>;
 }>> : WithSql<UntaggedDeep<TypedOmit<T, 'id'> & {
     id?: string;
 }>>;
+/**
+ * Represents the data structure for updating an existing entity.
+ * Allows partial updates for all properties (using PartialDeep) and specific updates for 'metadata.attributes'.
+ * Allows SQL expressions for values.
+ * @template T - The entity type.
+ */
 export type EntityUpdate<T extends EntityWithoutMetadata> = T extends Entity ? WithSql<PartialDeep<UntaggedDeep<TypedOmit<T, 'metadata'>>>> & {
     metadata?: EntityMetadataUpdate;
 } : WithSql<PartialDeep<UntaggedDeep<T>>>;

package/orm/server/database-schema.d.ts

@@ -1,11 +1,45 @@
+/**
+ * @module
+ * Provides utilities for defining and accessing database schemas, tables, and enums
+ * within a specific PostgreSQL schema.
+ */
 import type { PgEnum } from 'drizzle-orm/pg-core';
 import type { Enumeration, EnumerationValue, UnionToTuple } from '../../types.js';
 import type { EntityType } from '../entity.js';
 import type { PgTableFromType } from './types.js';
+/**
+ * Represents a database schema, providing methods to access tables and enums within that schema.
+ * @template SchemaName The name of the PostgreSQL schema.
+ */
 export declare class DatabaseSchema<SchemaName extends string> {
+    /** The name of the PostgreSQL schema. */
     readonly name: SchemaName;
+    /**
+     * Creates an instance of DatabaseSchema.
+     * @param name The name of the PostgreSQL schema.
+     */
     constructor(name: SchemaName);
+    /**
+     * Gets the Drizzle table object corresponding to the given entity type within this schema.
+     * @template T The entity type.
+     * @param type The entity class.
+     * @returns The Drizzle table object.
+     */
     getTable<T extends EntityType>(type: T): PgTableFromType<T, SchemaName>;
+    /**
+     * Gets the Drizzle enum object corresponding to the given enumeration within this schema.
+     * If a name is provided, it registers the enum with that name first.
+     * @template T The enumeration type.
+     * @param enumeration The enumeration object.
+     * @param name Optional name to register the enum with.
+     * @returns The Drizzle enum object.
+     */
     getEnum<T extends Enumeration>(enumeration: T, name?: string): PgEnum<UnionToTuple<`${EnumerationValue<T>}`> extends [string, ...string[]] ? UnionToTuple<`${EnumerationValue<T>}`> : never>;
 }
+/**
+ * Factory function to create a DatabaseSchema instance.
+ * @template Name The name of the PostgreSQL schema.
+ * @param name The name of the PostgreSQL schema.
+ * @returns A new DatabaseSchema instance.
+ */
 export declare function databaseSchema<Name extends string>(name: Name): DatabaseSchema<Name>;

package/orm/server/database-schema.js

@@ -1,13 +1,36 @@
 import { isDefined } from '../../utils/type-guards.js';
 import { getDrizzleTableFromType, getPgEnum, registerEnum } from './drizzle/schema-converter.js';
+/**
+ * Represents a database schema, providing methods to access tables and enums within that schema.
+ * @template SchemaName The name of the PostgreSQL schema.
+ */
 export class DatabaseSchema {
+    /** The name of the PostgreSQL schema. */
     name;
+    /**
+     * Creates an instance of DatabaseSchema.
+     * @param name The name of the PostgreSQL schema.
+     */
     constructor(name) {
         this.name = name;
     }
+    /**
+     * Gets the Drizzle table object corresponding to the given entity type within this schema.
+     * @template T The entity type.
+     * @param type The entity class.
+     * @returns The Drizzle table object.
+     */
     getTable(type) {
         return getDrizzleTableFromType(type, this.name);
     }
+    /**
+     * Gets the Drizzle enum object corresponding to the given enumeration within this schema.
+     * If a name is provided, it registers the enum with that name first.
+     * @template T The enumeration type.
+     * @param enumeration The enumeration object.
+     * @param name Optional name to register the enum with.
+     * @returns The Drizzle enum object.
+     */
     getEnum(enumeration, name) {
         if (isDefined(name)) {
             registerEnum(enumeration, name);
@@ -15,6 +38,12 @@ export class DatabaseSchema {
         return getPgEnum(this.name, enumeration); // eslint-disable-line @typescript-eslint/no-unsafe-return
     }
 }
+/**
+ * Factory function to create a DatabaseSchema instance.
+ * @template Name The name of the PostgreSQL schema.
+ * @param name The name of the PostgreSQL schema.
+ * @returns A new DatabaseSchema instance.
+ */
 export function databaseSchema(name) {
     return new DatabaseSchema(name);
 }

package/orm/server/database.d.ts

@@ -1,9 +1,27 @@
+/**
+ * @module
+ * Provides the core database connection and migration functionality using Drizzle ORM and node-postgres.
+ * It sets up the dependency injection for the database instance.
+ */
 import { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
-import type { PoolConfig } from 'pg';
+import { type PoolConfig } from 'pg';
 import type { Resolvable, resolveArgumentType } from '../../injector/interfaces.js';
+/**
+ * Type alias for the argument required to resolve a Database instance via the injector.
+ * Represents the PostgreSQL pool configuration.
+ */
 export type DatabaseArgument = PoolConfig;
+/**
+ * Represents the application's database connection.
+ * Extends Drizzle's `NodePgDatabase` and integrates with the dependency injection system.
+ * Can be resolved using a `PoolConfig` argument.
+ */
 export declare class Database extends NodePgDatabase<any> implements Resolvable<DatabaseArgument> {
     readonly [resolveArgumentType]?: DatabaseArgument;
 }
+/**
+ * Re-exports the `migrate` function from `drizzle-orm/node-postgres/migrator`
+ * for running database migrations.
+ */
 export { migrate };

package/orm/server/database.js

@@ -4,12 +4,22 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+/**
+ * @module
+ * Provides the core database connection and migration functionality using Drizzle ORM and node-postgres.
+ * It sets up the dependency injection for the database instance.
+ */
 import { drizzle, NodePgDatabase } from 'drizzle-orm/node-postgres';
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
-import pg from 'pg';
+import { Pool } from 'pg';
 import { inject, Injector, ReplaceClass } from '../../injector/index.js';
 import { isUndefined } from '../../utils/type-guards.js';
 import { DatabaseConfig } from './module.js';
+/**
+ * Represents the application's database connection.
+ * Extends Drizzle's `NodePgDatabase` and integrates with the dependency injection system.
+ * Can be resolved using a `PoolConfig` argument.
+ */
 let Database = class Database extends NodePgDatabase {
 };
 Database = __decorate([
@@ -22,9 +32,13 @@ Injector.registerSingleton(Database, {
         if (isUndefined(connection)) {
             throw new Error('Missing postgres connection. Provide it either via injection argument or a provider for DatabaseConfig.');
         }
-        const pool = new pg.Pool(connection);
+        const pool = new Pool(connection);
         context.addDisposeHandler(async () => pool.end());
         return drizzle(pool);
-    }
+    },
 });
+/**
+ * Re-exports the `migrate` function from `drizzle-orm/node-postgres/migrator`
+ * for running database migrations.
+ */
 export { migrate };

package/orm/server/drizzle/schema-converter.d.ts

@@ -1,13 +1,14 @@
 import { type PgEnum, type PgSchema, type PgTableWithColumns } from 'drizzle-orm/pg-core';
 import type { AbstractConstructor, Enumeration } from '../../../types.js';
 import type { EntityType } from '../../entity.js';
-import type { ColumnDefinition, PgTableFromType } from '../types.js';
+import type { ColumnDefinition, ColumnDefinitionsMap, PgTableFromType } from '../types.js';
 type ConverterContext = {
     type: AbstractConstructor;
     property: string;
 };
 export declare const getDrizzleTableFromType: typeof _getDrizzleTableFromType;
 export declare function getColumnDefinitions(table: PgTableWithColumns<any>): ColumnDefinition[];
+export declare function getColumnDefinitionsMap(table: PgTableWithColumns<any>): ColumnDefinitionsMap;
 export declare function _getDrizzleTableFromType<T extends EntityType, S extends string>(type: T, fallbackSchemaName?: S): PgTableFromType<T, S>;
 export declare function registerEnum(enumeration: Enumeration, name: string): void;
 export declare function getPgEnum(schema: string | PgSchema, enumeration: Enumeration, context?: ConverterContext): PgEnum<[string, ...string[]]>;

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

@@ -19,12 +19,17 @@ 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';
 const getDbSchema = memoizeSingle(pgSchema);
 export const getDrizzleTableFromType = memoize(_getDrizzleTableFromType);
 const columnDefinitionsSymbol = Symbol('columnDefinitions');
+const columnDefinitionsMapSymbol = Symbol('columnDefinitionsMap');
 export function getColumnDefinitions(table) {
     return table[columnDefinitionsSymbol];
 }
+export function getColumnDefinitionsMap(table) {
+    return table[columnDefinitionsMapSymbol];
+}
 export function _getDrizzleTableFromType(type, fallbackSchemaName) {
     const metadata = reflectionRegistry.getMetadata(type);
     assertDefined(metadata, `Type ${type.name} does not have reflection metadata.`);
@@ -41,6 +46,7 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
     const tableName = tableReflectionData?.name ?? getDefaultTableName(type);
     const dbSchema = getDbSchema(schema);
     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}`);
     }
@@ -60,7 +66,11 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
             return column;
         });
         const indexFn = (data.options?.unique == true) ? uniqueIndex : index;
-        return indexFn(data.name ?? getIndexName(tableName, columns, { naming: data.options?.naming })).using(data.options?.using ?? 'btree', ...columns);
+        let builder = indexFn(data.name ?? getIndexName(tableName, columns, { naming: data.options?.naming })).using(data.options?.using ?? 'btree', ...columns);
+        if (isDefined(data.options?.where)) {
+            builder = builder.where(convertQuery(data.options.where(table), table, columnDefinitionsMap));
+        }
+        return builder;
     }
     function buildPrimaryKey(table) {
         const columns = primaryKeyColumnDefinitions.map((columnDefinition) => getColumn(table, columnDefinition.name));
@@ -95,6 +105,7 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
         ...tableReflectionDatas.flatMap((tableReflectionData) => tableReflectionData.checks).filter(isDefined).map((data) => check(data.name, data.builder(table)))
     ]);
     drizzleSchema[columnDefinitionsSymbol] = columnDefinitions;
+    drizzleSchema[columnDefinitionsMapSymbol] = columnDefinitionsMap;
     return drizzleSchema;
 }
 function getPostgresColumnEntries(type, dbSchema, tableName, path = new JsonPath({ dollar: false }), prefix = '') {

package/orm/server/encryption.d.ts

@@ -1,2 +1,18 @@
+/**
+ * Encrypts a byte array using AES-GCM with the provided key.
+ * Prepends the encryption version and IV to the resulting ciphertext.
+ * @param bytes The byte array to encrypt.
+ * @param key The CryptoKey to use for encryption.
+ * @returns A promise that resolves to the encrypted byte array (version + IV + ciphertext).
+ */
 export declare function encryptBytes(bytes: Uint8Array, key: CryptoKey): Promise<Uint8Array>;
+/**
+ * Decrypts a byte array encrypted with `encryptBytes`.
+ * Reads the version and IV from the beginning of the array.
+ * @param bytes The byte array to decrypt (must include version and IV).
+ * @param key The CryptoKey to use for decryption.
+ * @returns A promise that resolves to the original decrypted byte array.
+ * @throws {DetailsError} If decryption fails (e.g., wrong key, corrupted data).
+ * @throws {Error} If the encryption version is invalid.
+ */
 export declare function decryptBytes(bytes: Uint8Array, key: CryptoKey): Promise<Uint8Array>;

package/orm/server/encryption.js

@@ -1,30 +1,55 @@
+/**
+ * @module
+ * Provides utility functions for encrypting and decrypting byte arrays using AES-GCM.
+ * It includes versioning to handle potential future changes in the encryption format.
+ */
 import { DetailsError } from '../../errors/index.js';
 import { decrypt, encrypt } from '../../utils/cryptography.js';
 import { getRandomBytes } from '../../utils/random.js';
 import { assert } from '../../utils/type-guards.js';
+/** Current version of the encryption format. */
 const encryptionVersion = 1;
+/** Number of bytes used to store the encryption version. */
 const encryptionVersionBytes = 2;
+/** Number of bytes used for the Initialization Vector (IV). */
 const ivBytes = 12;
+/**
+ * Encrypts a byte array using AES-GCM with the provided key.
+ * Prepends the encryption version and IV to the resulting ciphertext.
+ * @param bytes The byte array to encrypt.
+ * @param key The CryptoKey to use for encryption.
+ * @returns A promise that resolves to the encrypted byte array (version + IV + ciphertext).
+ */
 export async function encryptBytes(bytes, key) {
     const iv = getRandomBytes(ivBytes);
     const encrypted = await encrypt({ name: 'AES-GCM', iv }, key, bytes).toBuffer();
     const result = new Uint8Array(encryptionVersionBytes + ivBytes + encrypted.byteLength);
     const resultView = new DataView(result.buffer);
-    resultView.setUint16(0, encryptionVersion);
-    result.set(iv, encryptionVersionBytes);
-    result.set(new Uint8Array(encrypted), encryptionVersionBytes + ivBytes);
+    resultView.setUint16(0, encryptionVersion); // Prepend version
+    result.set(iv, encryptionVersionBytes); // Prepend IV
+    result.set(new Uint8Array(encrypted), encryptionVersionBytes + ivBytes); // Append ciphertext
     return result;
 }
+/**
+ * Decrypts a byte array encrypted with `encryptBytes`.
+ * Reads the version and IV from the beginning of the array.
+ * @param bytes The byte array to decrypt (must include version and IV).
+ * @param key The CryptoKey to use for decryption.
+ * @returns A promise that resolves to the original decrypted byte array.
+ * @throws {DetailsError} If decryption fails (e.g., wrong key, corrupted data).
+ * @throws {Error} If the encryption version is invalid.
+ */
 export async function decryptBytes(bytes, key) {
     const bytesView = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
     const version = bytesView.getUint16(0);
     const iv = bytes.slice(encryptionVersionBytes, encryptionVersionBytes + ivBytes);
-    assert(version == encryptionVersion, 'Invalid encryption version.');
+    assert(version == encryptionVersion, 'Invalid encryption version.'); // Check version
     try {
         const decrypted = await decrypt({ name: 'AES-GCM', iv }, key, bytes.slice(encryptionVersionBytes + ivBytes)).toBuffer();
         return new Uint8Array(decrypted);
     }
     catch (error) {
+        // Wrap decryption errors for better context
         throw new DetailsError('Decrypt error', error);
     }
 }

package/orm/server/index.d.ts

@@ -1,6 +1,13 @@
+/**
+ * @module
+ * Barrel file exporting core server-side ORM functionalities.
+ * Includes database connection, schema management, repositories, transactions,
+ * and query conversion utilities.
+ */
 export * from './database-schema.js';
 export * from './database.js';
 export * from './module.js';
 export * from './query-converter.js';
 export * from './repository.js';
 export * from './transaction.js';
+export * from './transactional.js';