@tstdl/base 0.93.139 → 0.93.141

package/orm/README.md

@@ -0,0 +1,423 @@
+# ORM Module
+
+A robust, code-first Object-Relational Mapping (ORM) library for PostgreSQL, built on top of [Drizzle ORM](https://orm.drizzle.team/). It simplifies data access through a repository pattern, provides advanced type-safe querying (including full-text search and ParadeDB integration), and integrates seamlessly with the dependency injection system.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Entities](#entities)
+  - [Repositories](#repositories)
+  - [Decorators](#decorators)
+  - [Querying](#querying)
+  - [Transactions](#transactions)
+- [🚀 Basic Usage](#-basic-usage)
+  - [1. Configuration](#1-configuration)
+  - [2. Defining Entities](#2-defining-entities)
+  - [3. Using Repositories](#3-using-repositories)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Full-Text Search](#full-text-search)
+  - [ParadeDB Integration](#paradedb-integration)
+  - [Transparent Encryption](#transparent-encryption)
+  - [Automatic Expiration (TTL)](#automatic-expiration-ttl)
+  - [Embedded Properties](#embedded-properties)
+  - [Transactions](#transaction-management)
+  - [Soft Deletes](#soft-deletes)
+  - [SQL Helper Functions](#sql-helper-functions)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Code-First Schema**: Define database tables, columns, and relationships using TypeScript classes and decorators.
+- **Repository Pattern**: Standardized API for CRUD operations, bulk actions, and complex querying.
+- **Type-Safe Querying**: MongoDB-like query syntax (`$eq`, `$gt`, `$in`, `$or`) fully typed to your entities.
+- **Advanced Search**: Built-in support for PostgreSQL `tsvector`, `pg_trgm`, and ParadeDB (`bm25`) full-text search.
+- **Transparent Encryption**: Encrypt sensitive columns automatically at the application level using AES-GCM.
+- **Automatic Expiration**: Built-in Time-To-Live (TTL) support for auto-deleting old records.
+- **Transaction Management**: Robust transaction handling with automatic commit/rollback and context propagation.
+- **Soft Deletes**: Built-in support for soft deletion when using the standard `Entity` base class.
+- **Dependency Injection**: Seamless integration with `@tstdl/base/injector`.
+
+## Core Concepts
+
+### Entities
+
+Entities are classes that map directly to database tables. The module provides base classes to standardize common fields:
+
+- **`Entity`**: The standard base class. Includes an `id` (UUIDv7 primary key) and metadata fields: `revision`, `createTimestamp`, `deleteTimestamp` (for soft deletes), and `attributes` (JSONB).
+- **`BaseEntity`**: A minimal base class providing only the `id` primary key. Useful for join tables or simple configuration data.
+- **`TenantEntity`**: Extends `Entity` with a `tenantId` column for multi-tenant applications.
+
+### Repositories
+
+Repositories provide the interface to the database.
+
+- **`EntityRepository<T>`**: The generic class providing methods like `load`, `insert`, `update`, `search`, etc.
+- **`injectRepository(Entity)`**: Helper to inject the default repository for an entity.
+- **`getRepository(Entity)`**: Helper to create a custom repository class extending the base functionality.
+
+### Decorators
+
+Decorators configure the mapping between TypeScript properties and database columns/constraints.
+
+- **Class**: `@Table`, `@Index`, `@Unique`, `@Check`, `@ParadeIndex`, `@TimeToLive`.
+- **Property**: `@StringProperty`, `@Integer`, `@UuidProperty`, `@TimestampProperty`, `@EncryptedProperty`, `@References`, `@EmbeddedProperty`, `@GeneratedTsVector`, `@TrigramIndex`.
+
+### Querying
+
+The ORM uses a structured query object syntax instead of raw SQL builders for most operations.
+
+- **Comparison**: `$eq`, `$neq`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$regex`.
+- **Logical**: `$and`, `$or`, `$nor`, `$not`.
+- **Search**: `$tsvector`, `$trigram`, `$parade`.
+
+### Transactions
+
+The `Transactional` base class allows services to manage transactions easily.
+
+- **`this.transaction(async (tx) => { ... })`**: Starts a transaction scope.
+- **`repository.withTransaction(tx)`**: Binds a repository to an active transaction.
+
+## 🚀 Basic Usage
+
+### 1. Configuration
+
+Configure the ORM in your application bootstrap.
+
+```typescript
+import { configureOrm } from '@tstdl/base/orm/server';
+
+configureOrm({
+  connection: {
+    host: 'localhost',
+    port: 5432,
+    user: 'postgres',
+    password: 'password',
+    database: 'my_app',
+  },
+  // Optional: Secret for column encryption (32 bytes)
+  encryptionSecret: new Uint8Array([
+    /* ... 32 bytes ... */
+  ]),
+});
+```
+
+### 2. Defining Entities
+
+Define your data model using classes and decorators. Note that standard schema decorators (like `@StringProperty`) are combined with ORM-specific decorators.
+
+```typescript
+import { Entity, Table, Unique, References } from '@tstdl/base/orm';
+import { UuidProperty } from '@tstdl/base/orm/schemas';
+import { StringProperty } from '@tstdl/base/schema';
+
+@Table({ name: 'users' })
+export class User extends Entity {
+  @StringProperty()
+  name: string;
+
+  @StringProperty()
+  @Unique()
+  email: string;
+}
+
+@Table({ name: 'posts' })
+export class Post extends Entity {
+  @StringProperty()
+  title: string;
+
+  @UuidProperty()
+  @References(() => User)
+  authorId: string;
+}
+```
+
+### 3. Using Repositories
+
+Inject repositories into your services to interact with the database.
+
+```typescript
+import { Singleton } from '@tstdl/base/injector';
+import { injectRepository, Transactional } from '@tstdl/base/orm/server';
+import { User } from './user.model.js';
+
+@Singleton()
+export class UserService extends Transactional {
+  // Inject the default repository for User
+  readonly #userRepository = injectRepository(User);
+
+  async createUser(name: string, email: string): Promise<User> {
+    // Insert a new entity
+    return await this.#userRepository.insert({
+      name,
+      email,
+    });
+  }
+
+  async findByEmail(email: string): Promise<User | undefined> {
+    // Query using the object syntax
+    return await this.#userRepository.tryLoadByQuery({
+      email: { $eq: email },
+    });
+  }
+
+  async updateName(id: string, newName: string): Promise<void> {
+    // Update specific fields
+    await this.#userRepository.update(id, {
+      name: newName,
+    });
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Full-Text Search
+
+The ORM supports PostgreSQL's native full-text search (`tsvector`) and trigram similarity (`pg_trgm`).
+
+```typescript
+import { Entity, Table, GeneratedTsVector } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+@Table({ name: 'articles' })
+export class Article extends Entity {
+  @StringProperty()
+  title: string;
+
+  @StringProperty()
+  content: string;
+
+  // Automatically generated tsvector column combining title (weight A) and content (weight B)
+  @GeneratedTsVector({
+    sources: ['title', 'content'],
+    weights: { title: 'A', content: 'B' },
+    language: 'english',
+  })
+  searchVector: string;
+}
+
+// In your service:
+const results = await articleRepository.search({
+  query: {
+    $tsvector: {
+      fields: ['searchVector'],
+      query: 'typescript & orm',
+      language: 'english',
+    },
+  },
+  highlight: 'content', // Optional: highlight matches in content
+});
+```
+
+### ParadeDB Integration
+
+If you are using [ParadeDB](https://www.paradedb.com/), you can use the `@ParadeIndex` decorator for BM25 relevance scoring and advanced search capabilities.
+
+```typescript
+import { Entity, Table, ParadeIndex } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+@Table({ name: 'products' })
+@ParadeIndex({
+  // Define a BM25 index on these columns
+  columns: ['name', 'description'],
+})
+export class Product extends Entity {
+  @StringProperty()
+  name: string;
+
+  @StringProperty()
+  description: string;
+}
+
+// Searching with ParadeDB
+const results = await productRepository.search({
+  query: {
+    $parade: {
+      fields: ['name', 'description'],
+      query: 'shoes OR boots',
+      distance: 1, // Fuzzy matching
+    },
+  },
+});
+```
+
+### Transparent Encryption
+
+Encrypt sensitive data at rest using the `@EncryptedProperty` decorator. The data is automatically encrypted on insert/update and decrypted on load. The underlying database column type will be `bytea`.
+
+```typescript
+import { Entity, EncryptedProperty } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+export class UserSecret extends Entity {
+  @StringProperty()
+  @EncryptedProperty()
+  apiKey: string;
+}
+```
+
+### Automatic Expiration (TTL)
+
+Automatically delete records after a specified duration. This relies on the `createTimestamp` field of `Entity` or a specific property marked with `@Expires`.
+
+```typescript
+import { Entity, TimeToLive, Expires } from '@tstdl/base/orm';
+import { TimestampProperty } from '@tstdl/base/orm/schemas';
+
+// Soft delete records 24 hours after creation
+@TimeToLive(24 * 60 * 60 * 1000, 'soft')
+export class Session extends Entity {
+  // ...
+}
+
+// Or expire based on a specific column
+export class ApiKey extends Entity {
+  @TimestampProperty()
+  @Expires({ after: 0, mode: 'hard' }) // Hard delete immediately when validUntil is reached
+  validUntil: number;
+}
+```
+
+### Embedded Properties
+
+Group related columns into a reusable class and embed them into entities. This flattens the structure in the database table but keeps it structured in your code.
+
+```typescript
+import { Entity, EmbeddedProperty } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+class Address {
+  @StringProperty()
+  street: string;
+
+  @StringProperty()
+  city: string;
+}
+
+export class User extends Entity {
+  @EmbeddedProperty(Address, { prefix: 'billing_' })
+  billingAddress: Address; // DB Columns: billing_street, billing_city
+
+  @EmbeddedProperty(Address, { prefix: 'shipping_' })
+  shippingAddress: Address; // DB Columns: shipping_street, shipping_city
+}
+```
+
+### Transaction Management
+
+Services extending `Transactional` can manage transactions. The repository automatically participates in the active transaction context.
+
+```typescript
+@Singleton()
+export class OrderService extends Transactional {
+  readonly #orderRepository = injectRepository(Order);
+  readonly #itemRepository = injectRepository(OrderItem);
+
+  async createOrder(data: OrderData): Promise<void> {
+    // Start a transaction scope
+    await this.transaction(async (tx) => {
+      // Repositories automatically use the transaction 'tx'
+      // because they are accessed within the scope of 'this.transaction'
+      // and injected via injectRepository which handles context propagation.
+
+      // Alternatively, explicitly bind:
+      // const txRepo = this.#orderRepository.withTransaction(tx);
+
+      const order = await this.#orderRepository.insert({ ... });
+      await this.#itemRepository.insertMany(data.items.map(i => ({ ...i, orderId: order.id })));
+
+      // If an error is thrown here, everything is rolled back.
+    });
+  }
+}
+```
+
+### Soft Deletes
+
+When using the `Entity` base class, the `delete` and `deleteByQuery` methods perform a soft delete by setting the `deleteTimestamp`. The `load` and `loadByQuery` methods automatically filter out soft-deleted records.
+
+To permanently remove records, use `hardDelete` or `hardDeleteByQuery`.
+
+### SQL Helper Functions
+
+The module exports SQL helpers in `@tstdl/base/orm/sqls` for complex queries.
+
+```typescript
+import { sql } from 'drizzle-orm';
+import { interval, TRANSACTION_TIMESTAMP } from '@tstdl/base/orm/sqls';
+
+// Find records created in the last 7 days
+const recent = await repository.loadManyByQuery({
+  createTimestamp: { $gt: sql`${TRANSACTION_TIMESTAMP} - ${interval(7, 'days')}` },
+});
+```
+
+## 📚 API
+
+### Decorators
+
+| Decorator                            | Target     | Description                                             |
+| :----------------------------------- | :--------- | :------------------------------------------------------ |
+| `@Table({ name?, schema? })`         | Class      | Configures table name and schema.                       |
+| `@Unique(columns?, options?)`        | Class/Prop | Defines unique constraints.                             |
+| `@Index(columns?, options?)`         | Class/Prop | Defines database indexes.                               |
+| `@Check(name, builder)`              | Class      | Defines a SQL CHECK constraint.                         |
+| `@ForeignKey(...)`                   | Class      | Defines a foreign key constraint.                       |
+| `@ParadeIndex(options)`              | Class/Prop | Configures a ParadeDB BM25 index.                       |
+| `@TimeToLive(ttl, mode)`             | Class      | Sets TTL for automatic deletion based on creation time. |
+| `@PrimaryKeyProperty()`              | Prop       | Marks the primary key column.                           |
+| `@References(target)`                | Prop       | Defines a foreign key relationship.                     |
+| `@EncryptedProperty()`               | Prop       | Marks column for encryption (`bytea`).                  |
+| `@EmbeddedProperty(type)`            | Prop       | Embeds another class's properties.                      |
+| `@GeneratedTsVector(opts)`           | Prop       | Creates a generated `tsvector` column.                  |
+| `@TrigramIndex(opts)`                | Prop       | Creates a GIN/GIST trigram index.                       |
+| `@Expires(opts)`                     | Prop       | Sets expiration based on the property value.            |
+| `@UuidProperty()`                    | Prop       | Maps to `uuid` column.                                  |
+| `@TimestampProperty()`               | Prop       | Maps to `timestamp with time zone` (number).            |
+| `@NumericDateProperty()`             | Prop       | Maps to `date` (number YYYYMMDD).                       |
+| `@JsonProperty()`                    | Prop       | Maps to `jsonb` column.                                 |
+| `@NumericProperty(precision, scale)` | Prop       | Maps to `numeric` column.                               |
+| `@TsVectorProperty()`                | Prop       | Maps to `tsvector` column.                              |
+
+### Repository Methods
+
+| Method                              | Description                                              |
+| :---------------------------------- | :------------------------------------------------------- |
+| `load(id)`                          | Loads an entity by ID. Throws if not found.              |
+| `tryLoad(id)`                       | Loads an entity by ID. Returns `undefined` if not found. |
+| `loadByQuery(query)`                | Loads first match. Throws if not found.                  |
+| `tryLoadByQuery(query)`             | Loads first match. Returns `undefined` if not found.     |
+| `loadMany(ids)`                     | Loads multiple entities by ID.                           |
+| `loadManyByQuery(query)`            | Loads all matches.                                       |
+| `loadAll()`                         | Loads all entities in the table.                         |
+| `insert(entity)`                    | Inserts a new entity.                                    |
+| `insertMany(entities)`              | Inserts multiple entities.                               |
+| `insertIfNotExists(target, entity)` | Inserts if no conflict on target columns.                |
+| `update(id, update)`                | Updates an entity by ID.                                 |
+| `updateByQuery(query, update)`      | Updates entities matching query.                         |
+| `upsert(target, entity)`            | Inserts or updates on conflict.                          |
+| `delete(id)`                        | Soft deletes (if supported) or hard deletes by ID.       |
+| `deleteByQuery(query)`              | Soft deletes matching entity.                            |
+| `hardDelete(id)`                    | Permanently removes the record.                          |
+| `search(options)`                   | Performs full-text search (TsVector, Trigram, Parade).   |
+| `count()`                           | Returns total count of entities.                         |
+| `countByQuery(query)`               | Returns the count of matching records.                   |
+| `has(id)`                           | Checks if an ID exists.                                  |
+| `transaction(handler)`              | Executes handler in a transaction.                       |
+
+### Query Operators
+
+| Operator                | Description                          |
+| :---------------------- | :----------------------------------- |
+| `$eq` / `$neq`          | Equal / Not Equal                    |
+| `$gt` / `$gte`          | Greater Than / Greater Than or Equal |
+| `$lt` / `$lte`          | Less Than / Less Than or Equal       |
+| `$in` / `$nin`          | In Array / Not In Array              |
+| `$regex`                | Regular Expression match             |
+| `$and` / `$or` / `$nor` | Logical operators                    |
+| `$not`                  | Negation                             |
+| `$tsvector`             | PostgreSQL Text Search               |
+| `$trigram`              | Trigram Similarity Search            |
+| `$parade`               | ParadeDB Search                      |

package/orm/decorators.d.ts

@@ -3,7 +3,7 @@
  * Defines decorators for ORM entities and columns, used to configure database schema mapping.
  */
 import type { SQL } from 'drizzle-orm';
-import type { ExtraConfigColumn } from 'drizzle-orm/pg-core';
+import type { ExtraConfigColumn, UpdateDeleteAction } from 'drizzle-orm/pg-core';
 import type { LiteralUnion, SetRequired } from 'type-fest';
 import { type SpecificCreateDecoratorOptions } from '../reflection/index.js';
 import type { AbstractConstructor, Record, TypedOmit } from '../types/index.js';
@@ -87,6 +87,8 @@ type ReferenceReflectionData<T extends AnyEntity = AnyEntity> = {
     target: () => EntityType<T>;
     targetColumn?: TargetColumnPath<T>;
     excludeTenant?: boolean;
+    onDelete?: UpdateDeleteAction;
+    onUpdate?: UpdateDeleteAction;
 };
 /**
  * Reflection data for unique constraints.
@@ -122,6 +124,8 @@ export type ForeignKeyReflectionData = {
     options?: {
         name?: string;
         naming?: NamingStrategy;
+        onDelete?: UpdateDeleteAction;
+        onUpdate?: UpdateDeleteAction;
     };
 };
 export type IndexOptions<T extends BaseEntity> = {

package/orm/decorators.js

@@ -71,7 +71,7 @@ export function PrimaryKeyProperty() {
 export function Reference(target, targetColumnOrOptions) {
     const targetColumn = (isString(targetColumnOrOptions) ? targetColumnOrOptions : targetColumnOrOptions?.targetColumn);
     const options = isString(targetColumnOrOptions) ? undefined : targetColumnOrOptions;
-    return createColumnDecorator({ references: [{ target, targetColumn, excludeTenant: options?.excludeTenant }] });
+    return createColumnDecorator({ references: [{ target, targetColumn, excludeTenant: options?.excludeTenant, onDelete: options?.onDelete, onUpdate: options?.onUpdate }] });
 }
 export { 
 /** @deprecated use {@link Reference} instead. */

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

@@ -15,13 +15,13 @@ import { typeExtends } from '../../../utils/index.js';
 import { merge } from '../../../utils/merge.js';
 import { compileDereferencer } from '../../../utils/object/dereference.js';
 import { fromEntries, mapObjectKeysToSnakeCase, objectEntries } from '../../../utils/object/object.js';
-import { assertDefined, assertDefinedPass, isArray, isDefined, isNotNull, isNotNullOrUndefined, isNull, isString, isUndefined } from '../../../utils/type-guards.js';
+import { assertDefined, isArray, isDefined, isNotNull, 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 { TenantBaseEntity, TenantEntity } from '../../entity.js';
 import { getEnumName } from '../../enums.js';
 import { JsonSchema, NumericDateSchema, NumericSchema, TimestampSchema, TsVectorSchema, UuidSchema } from '../../schemas/index.js';
-import { getInheritanceMetadata, isChildEntity } from '../../utils.js';
+import { getEntitySchema, getEntityTableName, getInheritanceMetadata, getTableReflectionDatas, isChildEntity } from '../../utils.js';
 import { decryptBytes, encryptBytes } from '../encryption.js';
 import { convertQuery, resolveTargetColumn, resolveTargetColumns } from '../query-converter.js';
 const getDbSchema = memoizeSingle(pgSchema);
@@ -42,8 +42,8 @@ export function getColumnDefinitionsMap(table) {
 export function _getDrizzleTableFromType(type, fallbackSchemaName) {
     const tableReflectionDatas = getTableReflectionDatas(type);
     const mergedTableReflectionData = tableReflectionDatas.reduceRight((merged, data) => ({ ...merged, ...data }), {});
-    const schema = assertDefinedPass(mergedTableReflectionData.schema ?? fallbackSchemaName, 'Table schema not provided');
-    const tableName = getTableName(type);
+    const schema = getEntitySchema(type, fallbackSchemaName);
+    const tableName = getEntityTableName(type);
     const dbSchema = getDbSchema(schema);
     const inheritanceMetadata = getInheritanceMetadata(type);
     const allColumnDefinitions = getPostgresColumnEntries(type, dbSchema, tableName, undefined, '', { filterInherited: false }, type);
@@ -130,7 +130,7 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
         if (isDefined(inheritanceMetadata) && isDefined(childEntityMetadata)) {
             const hasTenantId = isDefined(table['tenantId']);
             constraints.push(check(getIdentifier(tableName, discriminatorColumn, 'check'), eq(table[discriminatorColumn], sql.raw(`'${childEntityMetadata.discriminatorValue}'`))), foreignKey({
-                name: getForeignKeyName(tableName, getTableName(reflectionRegistry.getMetadata(type).parent), [...(hasTenantId ? ['tenantId'] : []), discriminatorColumn, 'id']),
+                name: getForeignKeyName(tableName, getEntityTableName(reflectionRegistry.getMetadata(type).parent), [...(hasTenantId ? ['tenantId'] : []), discriminatorColumn, 'id']),
                 columns: [
                     ...(hasTenantId ? [table['tenantId']] : []),
                     table[discriminatorColumn],
@@ -247,7 +247,7 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
                     const foreignTable = getDrizzleTableFromType(tenantReferenceData.target(), dbSchema.schemaName);
                     const nonTenantColumn = tenantReferenceData.targetColumn ?? 'id';
                     return foreignKey({
-                        name: getForeignKeyName(tableName, getTableName(tenantReferenceData.target()), [nonTenantColumn]),
+                        name: getForeignKeyName(tableName, getEntityTableName(tenantReferenceData.target()), [nonTenantColumn]),
                         columns: [getColumn(table, 'tenantId'), getColumn(table, columnDefinition.name)],
                         foreignColumns: [getColumn(foreignTable, 'tenantId'), getColumn(foreignTable, nonTenantColumn)],
                     });
@@ -257,11 +257,18 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
                 return tableReflectionData.foreignKeys?.map((foreignKeyData) => {
                     const foreignKeyTarget = foreignKeyData.target();
                     const foreignTable = getDrizzleTableFromType(foreignKeyTarget, dbSchema.schemaName);
-                    return foreignKey({
-                        name: foreignKeyData.options?.name ?? getForeignKeyName(tableName, getTableName(foreignKeyData.target()), foreignKeyData.columns, { naming: foreignKeyData.options?.naming }),
+                    let builder = foreignKey({
+                        name: foreignKeyData.options?.name ?? getForeignKeyName(tableName, getEntityTableName(foreignKeyData.target()), foreignKeyData.columns, { naming: foreignKeyData.options?.naming }),
                         columns: foreignKeyData.columns.map((column) => getColumn(table, column)),
                         foreignColumns: foreignKeyData.foreignColumns.map((column) => getColumn(foreignTable, column)),
                     });
+                    if (isDefined(foreignKeyData.options?.onDelete)) {
+                        builder = builder.onDelete(foreignKeyData.options.onDelete);
+                    }
+                    if (isDefined(foreignKeyData.options?.onUpdate)) {
+                        builder = builder.onUpdate(foreignKeyData.options.onUpdate);
+                    }
+                    return builder;
                 }) ?? [];
             }),
             ...tableReflectionDatas.flatMap((tableReflectionData) => tableReflectionData.unique).filter(isDefined).map((data) => {
@@ -398,7 +405,7 @@ function getPostgresColumn(tableName, columnName, dbSchema, propertySchema, refl
     if (((reflectionData.primaryKey == true) || (context.property == 'id' && reflectionData.primaryKey != false)) && (options.skipPrimaryKey != true)) {
         column = column.primaryKey();
     }
-    for (const { target, targetColumn, excludeTenant } of reflectionData.references ?? []) {
+    for (const { target, targetColumn, excludeTenant, onDelete, onUpdate } of reflectionData.references ?? []) {
         column = column.references(() => {
             const targetType = target();
             if ((excludeTenant != true) && (typeExtends(context.type, TenantBaseEntity) || typeExtends(context.type, TenantEntity)) && (typeExtends(targetType, TenantBaseEntity) || typeExtends(targetType, TenantEntity))) {
@@ -406,7 +413,7 @@ function getPostgresColumn(tableName, columnName, dbSchema, propertySchema, refl
             }
             const targetTable = getDrizzleTableFromType(targetType, dbSchema.schemaName);
             return targetTable[(targetColumn ?? 'id')];
-        });
+        }, { onDelete, onUpdate });
     }
     return column;
 }
@@ -462,9 +469,6 @@ export function getPgEnum(schema, enumeration, context) {
     }
     return dbEnum;
 }
-function getDefaultTableName(type) {
-    return toSnakeCase(isString(type.entityName) ? type.entityName : type.name.replace(/\d+$/u, ''));
-}
 function getPrimaryKeyName(tableName, columnsOrBaseName, options) {
     return getIdentifier(tableName, columnsOrBaseName, 'pk', options);
 }
@@ -486,23 +490,6 @@ function getForeignKeyName(tableName, foreignTableName, columnsOrBaseName, optio
     }
     return identifier;
 }
-function getTableName(type) {
-    const tableReflectionDatas = getTableReflectionDatas(type);
-    const tableReflectionData = tableReflectionDatas[0];
-    return tableReflectionData?.name ?? getDefaultTableName(type);
-}
-function getTableReflectionDatas(type) {
-    const metadata = reflectionRegistry.getMetadata(type);
-    assertDefined(metadata, `Type ${type.name} does not have reflection metadata.`);
-    const tableReflectionDatas = [];
-    for (let currentMetadata = metadata; isNotNullOrUndefined(currentMetadata?.parent); currentMetadata = reflectionRegistry.getMetadata(currentMetadata.parent)) {
-        const tableReflectionData = currentMetadata.data.tryGet('orm');
-        if (isDefined(tableReflectionData)) {
-            tableReflectionDatas.push(tableReflectionData);
-        }
-    }
-    return tableReflectionDatas;
-}
 function getIdentifier(tableName, columnsOrBaseName, suffix, options) {
     const middle = isString(columnsOrBaseName) ? columnsOrBaseName : getColumnNames(columnsOrBaseName).join('_');
     const identifier = `${getTablePrefix(tableName, options?.naming)}_${middle}_${suffix}`;

package/orm/server/encryption.d.ts

@@ -12,7 +12,6 @@ export declare function encryptBytes(bytes: Uint8Array<ArrayBuffer>, key: Crypto
  * @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<ArrayBuffer>>;

package/orm/server/encryption.js

@@ -3,7 +3,6 @@
  * 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';
@@ -36,7 +35,6 @@ export async function encryptBytes(bytes, key) {
  * @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) {
@@ -49,7 +47,6 @@ export async function decryptBytes(bytes, key) {
         return new Uint8Array(decrypted);
     }
     catch (error) {
-        // Wrap decryption errors for better context
-        throw new DetailsError('Decrypt error', error);
+        throw new Error('Decryption failed.', { cause: error });
     }
 }

package/orm/server/index.d.ts

@@ -1,11 +1,6 @@
-/**
- * @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 './migration.js';
 export * from './module.js';
 export * from './query-converter.js';
 export * from './repository-config.js';

package/orm/server/index.js

@@ -1,11 +1,6 @@
-/**
- * @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 './migration.js';
 export * from './module.js';
 export * from './query-converter.js';
 export * from './repository-config.js';

package/orm/server/migration.d.ts

@@ -0,0 +1,19 @@
+import { Injector, type ProvidersItem } from '../../injector/index.js';
+export type DatabaseMigration = {
+    name: string;
+    migrate: () => void | Promise<void>;
+    dependencies?: string[];
+};
+export declare const DATABASE_MIGRATION: import("../../injector/index.js").InjectionToken<DatabaseMigration, never>;
+/**
+ * Registers a database migration in the provided injector.
+ * @param name - The unique name of the migration.
+ * @param migrate - The migration function.
+ * @param options - Optional injector and dependencies.
+ */
+export declare function registerDatabaseMigration(name: string, migrate: () => void | Promise<void>, { injector, dependencies }?: {
+    injector?: Injector;
+    dependencies?: string[];
+}): void;
+export declare function provideDatabaseMigrator(): ProvidersItem;
+export declare function runDatabaseMigrations(): Promise<void>;