@tstdl/base 0.93.35 → 0.93.36

package/source/orm/README.md

@@ -0,0 +1,385 @@
+# ORM Module
+
+A powerful, code-first, decorator-based abstraction layer built on top of [Drizzle ORM](https://orm.drizzle.team/). It simplifies data access and management in a type-safe manner for PostgreSQL databases.
+
+## Table of Contents
+
+- [Features](#features)
+- [Core Concepts](#core-concepts)
+  - [Entities](#entities)
+  - [Repositories](#repositories)
+  - [Decorators](#decorators)
+  - [Querying](#querying)
+  - [Transactions](#transactions)
+  - [Schema Generation](#schema-generation)
+- [Usage](#usage)
+  - [1. Define Entities](#1-define-entities)
+  - [2. Access Repositories](#2-access-repositories)
+  - [3. Perform Operations (CRUD+)](#3-perform-operations-crud)
+  - [4. Handle Transactions](#4-handle-transactions)
+- [Advanced Topics](#advanced-topics)
+  - [Automatic Expiration (TTL)](#automatic-expiration-ttl)
+  - [Geospatial Queries](#geospatial-queries)
+  - [SQL Helper Functions](#sql-helper-functions)
+- [API Summary](#api-summary)
+  - [Decorators](#decorators-1)
+  - [EntityRepository Methods](#entityrepository-methods)
+
+## Features
+
+- **Code-First Approach**: Define your database schema directly in TypeScript using classes and decorators.
+- **Repository Pattern**: A clean, consistent API for all data manipulation operations.
+- **Type-Safe Querying**: A MongoDB-like query syntax that is fully typed based on your entity models.
+- **Automatic Schema Generation**: Integrates with `drizzle-kit` to generate SQL migrations from your entity classes.
+- **Built-in Transactions**: Simple and robust transaction management to ensure data integrity.
+- **Transparent Encryption**: Encrypt sensitive data at the column level with a single `@Encrypted()` decorator.
+- **Automatic Expiration**: Set a Time-to-Live (TTL) on entities for automatic cleanup.
+- **Dependency Injection**: Seamlessly integrated with the application's dependency injection container.
+
+## Core Concepts
+
+### Entities
+
+Entities are classes that represent your database tables. They are the foundation of the ORM. The module provides several base classes to build upon:
+
+- **`Entity`**: The standard base class. It provides an `id` (UUID primary key) and a `metadata` property containing `revision`, `createTimestamp`, `deleteTimestamp`, and `attributes`. This is suitable for most use cases.
+- **`EntityWithoutMetadata`**: A simpler base class that only provides an `id` primary key. Ideal for simpler tables like join tables or configuration data.
+- **`TenantEntity` / `TenantEntityWithoutMetadata`**: Variants of the above that also include a `tenantId` property, useful for multi-tenant applications.
+
+```typescript
+import { Entity, EntityWithoutMetadata, TenantEntity, Uuid } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+// Standard entity with metadata
+export class User extends Entity {
+  @StringProperty()
+  name: string;
+}
+
+// Multi-tenant entity
+export class Product extends TenantEntity {
+  @StringProperty()
+  name: string;
+}
+
+// Simple entity for a join table
+export class UserRole extends EntityWithoutMetadata {
+  @UuidProperty()
+  userId: Uuid;
+
+  @UuidProperty()
+  roleId: Uuid;
+}
+```
+
+### Repositories
+
+Data access is handled through repositories, which provide a dedicated API for each entity. There are two ways to get a repository:
+
+1.  **Default Repository (`injectRepository`)**: For basic CRUD operations, you can directly inject a default repository instance for an entity. This is the most common approach.
+
+    ```typescript
+    import { injectRepository } from '@tstdl/base/orm/server';
+    import { User } from './user.model.js';
+
+    // Directly get a repository instance
+    const userRepository = injectRepository(User);
+    const user = await userRepository.load('user-id-123');
+    ```
+
+2.  **Custom Repository Class**: To add custom data access methods, create a class that extends `getRepository(MyEntity)`.
+
+    ```typescript
+    import { Singleton, inject } from '@tstdl/base/injector';
+    import { getRepository } from '@tstdl/base/orm/server';
+    import { User } from './user.model.js';
+
+    @Singleton()
+    export class UserRepository extends getRepository(User) {
+      async findAdmins(): Promise<User[]> {
+        return this.loadManyByQuery({ isAdmin: true });
+      }
+    }
+
+    // Inject your custom repository
+    const userRepository = inject(UserRepository);
+    const admins = await userRepository.findAdmins();
+    ```
+
+### Decorators
+
+Decorators map class properties to database columns and define table constraints.
+
+-   **Class Decorators:**
+    -   `@Table({ name: '...', schema: '...' })`: Sets the table name and schema.
+    -   `@Unique(['prop1', 'prop2'])`: Creates a composite unique constraint.
+    -   `@Index(['prop1', 'prop2'])`: Creates a composite index.
+    -   `@ForeignKey(() => Target, ['thisCol'], ['targetCol'])`: Creates a composite foreign key.
+    -   `@Check('name', (table) => ...)`: Defines a custom SQL `CHECK` constraint.
+    -   `@TimeToLive(ms, 'soft' | 'hard')`: Automatically deletes records after a TTL.
+
+-   **Property Decorators:**
+    -   `@StringProperty()`, `@Integer()`, `@NumberProperty()`, `@BooleanProperty()`: Define basic data types.
+    -   `@UuidProperty()`: A native `uuid` column. Can be configured with `{ defaultRandom: true }`.
+    -   `@TimestampProperty()`: A Unix timestamp (milliseconds) stored as `timestamp with time zone`.
+    -   `@NumericDateProperty()`: A date stored as a number (`YYYYMMDD`) in a `date` column.
+    -   `@Enumeration(MyEnum)`: Maps a TypeScript enum to a PostgreSQL enum type.
+    -   `@JsonProperty()`: Maps a property to a `jsonb` column.
+    -   `@EncryptedProperty()`: Transparently encrypts the column data (underlying type is `bytea`).
+    -   `@EmbeddedProperty(MyClass)`: Inlines the properties of another class.
+    -   `@PrimaryKeyProperty()`: Marks a property as the primary key.
+    -   `@Unique()`: Creates a unique constraint on a single column.
+    -   `@Index()`: Creates an index on a single column.
+    -   `@References(() => OtherEntity)`: Creates a foreign key to the `id` of another entity.
+    -   `@Expires()`: Marks a date/timestamp column to trigger expiration (used with `@TimeToLive`).
+
+### Querying
+
+The ORM uses a type-safe, MongoDB-like query syntax. The query object is mapped to the entity's properties and converted to a SQL `WHERE` clause. Top-level properties are implicitly joined with `AND`.
+
+```typescript
+import { currentTimestamp } from '@tstdl/base/utils';
+
+// Simple equality
+const user = await userRepository.loadByQuery({ mail: 'test@example.com' });
+
+// Multiple conditions (AND)
+const activeAdmins = await userRepository.loadManyByQuery({
+  role: 'admin',
+  status: { $neq: 'inactive' }
+});
+
+// Logical OR
+const highPriorityTasks = await taskRepository.loadManyByQuery({
+  $or: [
+    { priority: 'high' },
+    { dueDate: { $lt: currentTimestamp() } }
+  ]
+});
+```
+
+**Supported Operators:** `$eq`, `$neq`, `$in`, `$nin`, `$lt`, `$lte`, `$gt`, `$gte`, `$exists`, `$and`, `$or`, `$nor`, `$not`, `$regex`, `$fts`, `$geoShape`, `$geoDistance`.
+
+### Transactions
+
+Services can extend the `Transactional` base class to get simple and robust transaction management.
+
+-   **`repository.transaction(async (tx) => { ... })`**: The primary method. It starts a transaction, executes the callback, and automatically commits on success or rolls back on error.
+-   **`repository.withTransaction(tx)`**: Creates a new repository instance bound to an existing transaction, allowing you to pass the transaction context between different services and repositories.
+
+### Schema Generation
+
+The code-first approach integrates with `drizzle-kit` to automate database migrations.
+
+1.  **Define Entities**: Write your entity classes with decorators.
+2.  **Expose Schema**: Create a central file (e.g., `schemas.ts`) that exports all Drizzle tables using `databaseSchema.getTable(MyEntity)`.
+3.  **Configure `drizzle-kit`**: Point your `drizzle.config.ts` to the schema file.
+4.  **Generate Migration**: Run `drizzle-kit generate`. It will compare your code-defined schema with the database state and create a new SQL migration file.
+5.  **Apply Migration**: Use the `migrate` function from `@tstdl/base/orm/server` to apply pending migrations, typically on application startup.
+
+## Usage
+
+This example demonstrates defining two related entities (`User` and `Pet`), accessing their repositories, and performing operations within a transaction.
+
+### 1. Define Entities
+
+```typescript
+// user.model.ts
+import { Entity, Table, Unique } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+
+@Table({ name: 'users', schema: 'public' })
+export class User extends Entity {
+  @StringProperty()
+  name: string;
+
+  @StringProperty()
+  @Unique()
+  email: string;
+}
+
+// pet.model.ts
+import { Entity, References, Table, Uuid } from '@tstdl/base/orm';
+import { StringProperty } from '@tstdl/base/schema';
+import { User } from './user.model.js';
+
+@Table({ name: 'pets', schema: 'public' })
+export class Pet extends Entity {
+  @StringProperty()
+  name: string;
+
+  @UuidProperty()
+  @References(() => User)
+  ownerId: string;
+}
+```
+
+### 2. Access Repositories
+
+In a service class, inject the repositories you need. Extend `Transactional` to get access to `this.transaction()`.
+
+```typescript
+// user.service.ts
+import { Singleton } from '@tstdl/base/injector';
+import { injectRepository, Transactional } from '@tstdl/base/orm/server';
+import { User } from './user.model.js';
+import { Pet } from './pet.model.js';
+
+@Singleton()
+export class UserService extends Transactional {
+  readonly #userRepository = injectRepository(User);
+  readonly #petRepository = injectRepository(Pet);
+
+  // ... service methods
+}
+```
+
+### 3. Perform Operations (CRUD+)
+
+Use the repository instances to interact with the database.
+
+```typescript
+// Inside a method of UserService...
+
+// Create
+const newUser = await this.#userRepository.insert({
+  name: 'Jane Doe',
+  email: 'jane.doe@example.com',
+});
+
+// Read
+const user = await this.#userRepository.load(newUser.id);
+
+// Update
+await this.#userRepository.update(newUser.id, { name: 'Jane Smith' });
+
+// Upsert (insert or update on conflict)
+await this.#userRepository.upsert(
+  ['email'], // conflict target
+  { id: 'some-id', name: 'John', email: 'john.doe@example.com' },
+);
+
+// Delete (soft, sets deleteTimestamp) - requires Entity (with metadata)
+await this.#userRepository.delete(newUser.id);
+
+// Delete (hard, removes from DB) - works with any entity type
+await this.#userRepository.hardDelete(newUser.id);
+```
+
+### 4. Handle Transactions
+
+Wrap multiple operations in a transaction to ensure they all succeed or fail together.
+
+```typescript
+// Inside UserService
+async function onboardUserWithPet(userName: string, userEmail: string, petName: string): Promise<User> {
+  // All operations inside this block are atomic.
+  return this.transaction(async (tx) => {
+    // Get repository instances bound to this transaction
+    const userRepository = this.#userRepository.withTransaction(tx);
+    const petRepository = this.#petRepository.withTransaction(tx);
+
+    const newUser = await userRepository.insert({
+      name: userName,
+      email: userEmail
+    });
+
+    await petRepository.insert({
+      name: petName,
+      ownerId: newUser.id
+    });
+
+    return newUser;
+  });
+}
+```
+
+## Advanced Topics
+
+### Automatic Expiration (TTL)
+
+You can configure entities to be automatically deleted after a certain time-to-live (TTL).
+
+- **`@TimeToLive(ttl, mode)`**: A class decorator where `ttl` is the time in milliseconds and `mode` is either `'soft'` or `'hard'`.
+- This decorator relies on the `createTimestamp` field from the base `Entity` class.
+
+```typescript
+import { Entity, Table, TimeToLive } from '@tstdl/base/orm';
+
+// This entity will be soft-deleted 30 minutes after creation.
+@TimeToLive(30 * 60 * 1000, 'soft')
+export class TemporarySession extends Entity {
+  // ...
+}
+```
+
+### SQL Helper Functions
+
+For more complex queries, you can use raw SQL helpers from `@tstdl/base/orm/sqls`. These can be used inside query conditions or for selecting computed values.
+
+| Function                | Description                                    |
+| ----------------------- | ---------------------------------------------- |
+| `RANDOM_UUID_V4`        | Generates a `gen_random_uuid()` call.          |
+| `TRANSACTION_TIMESTAMP` | Gets the current transaction's timestamp.      |
+| `interval(value, unit)` | Creates a interval (e.g., `interval '1 day'`). |
+| `arrayAgg(column)`      | Aggregates values into an array.               |
+| `jsonAgg(column)`       | Aggregates values into a JSON array.           |
+| `coalesce(...values)`   | Returns the first non-null value.              |
+| `least(...values)`      | Returns the smallest value from a list.        |
+| `greatest(...values)`   | Returns the largest value from a list.         |
+
+```typescript
+import { sql } from 'drizzle-orm';
+import { interval } from '@tstdl/base/orm/sqls';
+
+// Find users created in the last 7 days
+const recentUsers = await userRepository.loadManyByQuery({
+  createTimestamp: { $gt: sql`${TRANSACTION_TIMESTAMP} - ${interval(7, 'days')}` }
+});
+```
+
+## API Summary
+
+### Decorators
+
+| Decorator                                                | Type             | Description                                                                       |
+| -------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
+| `@Table({ name?, schema? })`                             | Class            | Specifies table name and schema.                                                  |
+| `@TimeToLive(ttl, mode)`                                 | Class            | Automatically deletes records after a TTL (soft or hard).                         |
+| `@PrimaryKeyProperty()`                                          | Property         | Marks a property as the primary key.                                              |
+| `@Unique(columns?, options?)`                            | Class / Property | Defines a unique constraint.                                                      |
+| `@Index(columns?, options?)`                             | Class / Property | Defines a database index.                                                         |
+| `@Check(name, builder)`                                  | Class            | Defines a custom SQL `CHECK` constraint.                                          |
+| `@ForeignKey(target, columns, foreignColumns, options?)` | Class            | Defines a composite foreign key relationship.                                     |
+| `@References(target, targetColumn?)`                     | Property         | Defines a foreign key relationship to another entity's column (defaults to `id`). |
+| `@EncryptedProperty()`                                           | Property         | Marks a column for transparent encryption (stored as `bytea`).                    |
+| `@EmbeddedProperty(type, { prefix? })`                           | Property         | Inlines properties from another class into the table.                             |
+| `@Expires()`                                             | Property         | Marks a date/timestamp column to trigger expiration.                              |
+| `@UuidProperty({ defaultRandom? })`                      | Property         | Defines a `uuid` column.                                                          |
+| `@TimestampProperty()`                                   | Property         | Defines a `timestamp with time zone` column, storing a number (milliseconds).     |
+| `@NumericDateProperty()`                                 | Property         | Defines a `date` column, storing a number (`YYYYMMDD`).                           |
+| `@JsonProperty({ schema? })`                             | Property / Class | Defines a `jsonb` column with optional schema validation.                         |
+
+### EntityRepository Methods
+
+| Method                             | Arguments                                                                | Returns                      | Description                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------- |
+| `load(id)`                         | `id: string`                                                             | `Promise<T>`                 | Loads a single entity by ID. Throws if not found.                                        |
+| `tryLoad(id)`                      | `id: string`                                                             | `Promise<T \| undefined>`    | Loads a single entity by ID. Returns `undefined` if not found.                           |
+| `loadByQuery(query, options?)`     | `query: Query<T>, options?: LoadOptions<T>`                              | `Promise<T>`                 | Loads the first entity matching the query. Throws if not found.                          |
+| `loadManyByQuery(query, options?)` | `query: Query<T>, options?: LoadManyOptions<T>`                          | `Promise<T[]>`               | Loads all entities matching the query.                                                   |
+| `insert(entity)`                   | `entity: NewEntity<T>`                                                   | `Promise<T>`                 | Inserts a new entity.                                                                    |
+| `insertMany(entities)`             | `entities: NewEntity<T>[]`                                               | `Promise<T[]>`               | Inserts multiple new entities.                                                           |
+| `upsert(entity, onConflict, doUpdate?)` | `entity: NewEntity<T>, onConflict: UpsertConflictTarget<T>, doUpdate?: EntityUpdate<T>` | `Promise<T>` | Inserts an entity or updates it on conflict.                                             |
+| `update(id, update)`               | `id: string, update: EntityUpdate<T>`                                    | `Promise<T>`                 | Partially updates an entity by ID by setting new values.                                 |
+| `updateByQuery(query, update)`     | `query: Query<T>, update: EntityUpdate<T>`                               | `Promise<T[]>`               | Partially updates all entities matching a query by setting new values.                   |
+| `patch(id, patch)`                 | `id: string, patch: EntityPatch<T>`                                      | `Promise<T>`                 | Partially updates an entity by ID using operators like `$inc`.                           |
+| `patchByQuery(query, patch)`       | `query: Query<T>, patch: EntityPatch<T>`                                 | `Promise<T[]>`               | Partially updates all entities matching a query using operators.                         |
+| `delete(id, metadata?)`            | `id: string, metadata?: EntityMetadataUpdate`                            | `Promise<T>`                 | Soft-deletes an entity by its ID (sets `deleteTimestamp`).                               |
+| `deleteByQuery(query, metadata?)`  | `query: Query<T>, metadata?: EntityMetadataUpdate`                       | `Promise<T[]>`               | Soft-deletes all entities matching a query.                                              |
+| `hardDelete(id)`                   | `id: string`                                                             | `Promise<T>`                 | Permanently deletes an entity by its ID.                                                 |
+| `hardDeleteByQuery(query)`         | `query: Query<T>`                                                        | `Promise<T[]>`               | Permanently deletes all entities matching a query.                                       |
+| `countByQuery(query)`              | `query: Query<T>`                                                        | `Promise<number>`            | Counts entities matching a query.                                                        |
+| `hasByQuery(query)`                | `query: Query<T>`                                                        | `Promise<boolean>`           | Checks if any entity matches a query.                                                    |
+| `withTransaction(tx)`              | `tx: Transaction`                                                        | `this`                       | Returns a new repository instance bound to a specific transaction.                       |
+| `transaction(handler)`             | `handler: (tx: Transaction) => Promise<R>`                               | `Promise<R>`                 | Executes a handler within a new, automatically managed transaction.                      |

package/source/orm/data-types/bytea.ts

@@ -0,0 +1,21 @@
+/**
+ * @module
+ * Defines a custom Drizzle type for handling PostgreSQL `bytea` columns.
+ */
+import { createCustomType } from './common.js';
+
+/**
+ * Custom Drizzle type for PostgreSQL `bytea` columns.
+ * Maps between `Uint8Array` in JavaScript and `bytea` in the database.
+ */
+export const bytea = createCustomType<{ data: Uint8Array, driverData: Uint8Array }>({
+  dataType() {
+    return 'bytea';
+  },
+  toDriver(value: Uint8Array): Uint8Array {
+    return value;
+  },
+  fromDriver(value: Uint8Array): Uint8Array {
+    return value;
+  },
+});

package/source/orm/data-types/common.ts

@@ -0,0 +1,28 @@
+import {
+  customType,
+  type ConvertCustomConfig,
+  type CustomTypeParams,
+  type CustomTypeValues,
+  type PgCustomColumnBuilder,
+} from 'drizzle-orm/pg-core';
+
+/**
+ * A generic type for a custom Drizzle column builder function.
+ * This provides the overloads for creating a column with or without a specific database name.
+ * @template TConfig The configuration object for the custom type, containing `data` and `driverData` types.
+ */
+export type CustomTypeBuilder<TConfig extends Partial<CustomTypeValues>> = {
+  (): PgCustomColumnBuilder<ConvertCustomConfig<'', TConfig>>,
+  <TName extends string>(dbName: TName): PgCustomColumnBuilder<ConvertCustomConfig<TName, TConfig>>,
+};
+
+/**
+ * Factory function to create a custom Drizzle type with the standard builder overloads.
+ * This reduces boilerplate by wrapping `drizzle-orm/pg-core#customType` and applying a common type cast.
+ * @template TConfig The configuration object for the custom type.
+ * @param params The parameters for the custom type, including `dataType`, `toDriver`, and `fromDriver`.
+ * @returns A custom type builder function.
+ */
+export function createCustomType<TConfig extends CustomTypeValues>(params: CustomTypeParams<TConfig>): CustomTypeBuilder<TConfig> {
+  return customType<TConfig>(params) as CustomTypeBuilder<TConfig>;
+}

package/source/orm/data-types/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @module
+ * Exports custom Drizzle data types for PostgreSQL.
+ */
+export * from './bytea.js';
+export * from './common.js';
+export * from './numeric-date.js';
+export * from './timestamp.js';
+export * from './tsvector.js';

package/source/orm/data-types/numeric-date.ts

@@ -0,0 +1,29 @@
+/**
+ * @module
+ * Defines a custom Drizzle type for handling PostgreSQL `date` columns
+ * using numeric representation (YYYYMMDD).
+ */
+import { dateToNumericDate, numericDateToDateObject } from '#/utils/date-time.js';
+import { createCustomType } from './common.js';
+
+/**
+ * Custom Drizzle type for PostgreSQL `date` columns, storing dates as numeric values (YYYYMMDD).
+ * Converts between JavaScript `number` (YYYYMMDD) and database `date` (ISO string).
+ */
+export const numericDate = createCustomType<{ data: number, driverData: string }>({
+  dataType() {
+    return 'date';
+  },
+  toDriver(value: number): string {
+    const { year, month, day } = numericDateToDateObject(value);
+    const yearString = year.toString().padStart(4, '0');
+    const monthString = month.toString().padStart(2, '0');
+    const dayString = day.toString().padStart(2, '0');
+
+    return `${yearString}-${monthString}-${dayString}`;
+  },
+  fromDriver(value: string): number {
+    const date = new Date(value);
+    return dateToNumericDate(date);
+  },
+});

package/source/orm/data-types/timestamp.ts

@@ -0,0 +1,22 @@
+/**
+ * @module
+ * Defines a custom Drizzle type for handling PostgreSQL `timestamp with time zone` columns
+ * using numeric representation (Unix timestamp in milliseconds).
+ */
+import { createCustomType } from './common.js';
+
+/**
+ * Custom Drizzle type for PostgreSQL `timestamp with time zone` columns, storing timestamps as numeric values (Unix timestamp in milliseconds).
+ * Converts between JavaScript `number` (milliseconds since epoch) and database `timestamp with time zone` (ISO string).
+ */
+export const timestamp = createCustomType<{ data: number, driverData: string }>({
+  dataType() {
+    return 'timestamp with time zone';
+  },
+  toDriver(value: number): string {
+    return new Date(value).toISOString();
+  },
+  fromDriver(value: string): number {
+    return new Date(value).getTime();
+  },
+});

package/source/orm/data-types/tsvector.ts

@@ -0,0 +1,16 @@
+/**
+ * @module
+ * Defines a custom Drizzle type for handling PostgreSQL `tsvector` columns.
+ */
+import { createCustomType } from './common.js';
+
+/**
+ * Custom Drizzle type for PostgreSQL `tsvector` columns.
+ * This type is a placeholder for the column type and does not perform
+ * any data transformation, as `tsvector` columns are typically not directly mapped to application data.
+ */
+export const tsvector = createCustomType<{ data: string }>({
+  dataType() {
+    return 'tsvector';
+  },
+});