@tstdl/base 0.93.36 → 0.93.38

package/source/orm/README.md

@@ -1,385 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-/**
- * @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

@@ -1,28 +0,0 @@
-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

@@ -1,9 +0,0 @@
-/**
- * @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

@@ -1,29 +0,0 @@
-/**
- * @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

@@ -1,22 +0,0 @@
-/**
- * @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

@@ -1,16 +0,0 @@
-/**
- * @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';
-  },
-});