@codyswann/lisa 1.48.0 → 1.50.0

package/plugins/src/nestjs/skills/typeorm-patterns/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: typeorm-patterns
+description: Enforces TypeORM implementation patterns for this NestJS backend project. This skill should be used when creating or modifying TypeORM entities, repositories, database configuration, migrations, or any database-related code. It covers configuration patterns (TypeOrmModule.forRootAsync, replication, naming strategy), entity patterns (base entity, comments, indexes), and observability (X-Ray logging).
+---
+
+# TypeORM Patterns
+
+## Overview
+
+This skill enforces TypeORM implementation patterns for the NestJS backend project. It ensures consistent database configuration, entity design, repository patterns, and observability across the codebase.
+
+## Core Requirements
+
+### Configuration Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| **Module Pattern** | `TypeOrmModule.forRootAsync()` with `dataSourceFactory` |
+| **Naming Strategy** | `SnakeNamingStrategy` from `typeorm-naming-strategies` |
+| **Synchronize** | Always `false` - migrations only, no auto-sync |
+| **Entity Loading** | Explicit entity exports via index.ts (esbuild compatibility) |
+| **Database** | PostgreSQL (local Docker, AWS Aurora Serverless v2 production) |
+
+### Environment-Based Configuration
+
+| Environment | Connection Type | Authentication |
+|-------------|-----------------|----------------|
+| **Local** | Direct connection | Environment variables |
+| **Production** | Read-write replication | AWS RDS Signer (IAM) |
+
+### Entity Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| **Abstract Base** | All entities extend `TimestampedEntity` (NOT TypeORM's `BaseEntity`) |
+| **Primary Key** | UUID via `@PrimaryGeneratedColumn("uuid")` |
+| **Column Comments** | Required on all columns via `@Column({ comment: "..." })` |
+| **Foreign Keys** | Must be indexed via `@Index()` decorator |
+| **Cascade Deletes** | Use `orphanedRowAction: "delete"` on OneToMany relations |
+
+**Note**: We use `TimestampedEntity` to avoid confusion with TypeORM's built-in `BaseEntity` class which provides Active Record pattern methods. Our abstract class only provides column inheritance.
+
+### Observability Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| **Logger** | Custom `TypeOrmXRayLogger` for distributed tracing |
+| **Graceful Degradation** | Logger must work locally without X-Ray SDK |
+| **Query Tracking** | Extract query type and table name for metrics |
+
+## Quick Reference
+
+### Database Module Setup
+
+Use the standard NestJS `TypeOrmModule.forRootAsync()` with `dataSourceFactory` for full control:
+
+```typescript
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { DataSource } from "typeorm";
+import { createTypeOrmOptions } from "./database.config";
+
+/**
+ * Database module using official NestJS TypeORM integration.
+ *
+ * @remarks
+ * Uses forRootAsync with dataSourceFactory for:
+ * - Async configuration (environment-based)
+ * - Custom DataSource initialization
+ * - Replication support with dynamic passwords
+ */
+@Module({
+  imports: [
+    TypeOrmModule.forRootAsync({
+      useFactory: createTypeOrmOptions,
+      dataSourceFactory: async (options) => {
+        const dataSource = new DataSource(options);
+        return dataSource.initialize();
+      },
+    }),
+  ],
+})
+export class DatabaseModule {}
+```
+
+### Creating a New Entity
+
+```typescript
+import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from "typeorm";
+import { TimestampedEntity } from "./timestamped.entity";
+
+/**
+ * Represents a user in the system.
+ *
+ * @remarks
+ * Users belong to organizations and can have multiple watchlists.
+ */
+@Entity({ comment: "Application users with organization membership" })
+export class User extends TimestampedEntity {
+  @Column({ comment: "User email address for authentication" })
+  @Index()
+  email: string;
+
+  @Column({ comment: "User display name", nullable: true })
+  name: string | null;
+
+  @Column({ comment: "Foreign key to organization", type: "uuid" })
+  @Index()
+  organizationId: string;
+
+  @ManyToOne(() => Organization, { onDelete: "SET NULL", nullable: true })
+  @JoinColumn()
+  organization: Organization;
+
+  @OneToMany(() => Watchlist, w => w.user, { orphanedRowAction: "delete" })
+  watchlists: Watchlist[];
+}
+```
+
+**Important**: The abstract `TimestampedEntity` does NOT have an `@Entity()` decorator - only concrete child entities get this decorator.
+
+### Adding Entity to Exports
+
+After creating any entity, add it to `src/database/entities/index.ts`:
+
+```typescript
+export { User } from "./user.entity";
+export { Organization } from "./organization.entity";
+// Add new entity here
+```
+
+### Using Repository Injection
+
+With `TypeOrmModule`, use `@InjectRepository()` for standard repository access:
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { User } from "../entities/user.entity";
+
+@Injectable()
+export class UserService {
+  constructor(
+    @InjectRepository(User)
+    private readonly userRepository: Repository<User>
+  ) {}
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.userRepository.findOne({ where: { email } });
+  }
+}
+```
+
+### Creating a Custom Repository (When Needed)
+
+Only create custom repositories when you need reusable query methods:
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { DataSource, Repository } from "typeorm";
+import { User } from "../entities/user.entity";
+
+/**
+ * Custom repository for complex User queries.
+ */
+@Injectable()
+export class UserRepository extends Repository<User> {
+  constructor(private readonly dataSource: DataSource) {
+    super(User, dataSource.createEntityManager());
+  }
+
+  /**
+   * Find users with full-text search.
+   */
+  async searchByName(query: string): Promise<User[]> {
+    return this.createQueryBuilder("user")
+      .where("user.name ILIKE :query", { query: `%${query}%` })
+      .getMany();
+  }
+}
+```
+
+### Custom Repositories in Transactions
+
+**Critical**: Class-based repositories extending `Repository<T>` do NOT work correctly inside transactions. Per [TypeORM documentation](https://typeorm.io/docs/working-with-entity-manager/custom-repository/), you must use `withRepository()`:
+
+```typescript
+// WRONG - repository uses wrong EntityManager, won't be transactional
+async transferFunds(fromId: string, toId: string, amount: number): Promise<void> {
+  await this.dataSource.transaction(async manager => {
+    const from = await this.accountRepository.findOne({ where: { id: fromId } });
+    // This query runs OUTSIDE the transaction!
+  });
+}
+
+// CORRECT - use withRepository() for transactional operations
+async transferFunds(fromId: string, toId: string, amount: number): Promise<void> {
+  await this.dataSource.transaction(async manager => {
+    const accountRepo = manager.withRepository(this.accountRepository);
+    const from = await accountRepo.findOne({ where: { id: fromId } });
+    // This query runs INSIDE the transaction
+  });
+}
+```
+
+## Read-Write Routing
+
+TypeORM automatically routes queries based on operation type when replication is configured:
+
+| Operation | Endpoint | Method Examples |
+|-----------|----------|-----------------|
+| **Read** | Slave (read replica) | `find()`, `findOne()`, `query()` with SELECT |
+| **Write** | Master | `save()`, `insert()`, `update()`, `delete()` |
+
+To force a specific connection:
+
+```typescript
+// Force master for reads (when consistency required)
+await this.userRepository.manager.transaction(async manager => {
+  const user = await manager.findOne(User, { where: { id } });
+  // This read uses master connection
+});
+
+// QueryRunner for explicit control
+const queryRunner = dataSource.createQueryRunner("master");
+try {
+  await queryRunner.query("SELECT * FROM users WHERE id = $1", [id]);
+} finally {
+  await queryRunner.release();
+}
+```
+
+## Migration Workflow
+
+Always use the migration scripts - never modify migration files directly:
+
+```bash
+# Generate migration from entity changes
+bun migration:generate --name=AddUserEmailIndex
+
+# Run pending migrations
+bun migration:run
+
+# Revert last migration
+bun migration:revert
+```
+
+## File Structure
+
+```
+src/database/
+├── database.module.ts          # NestJS module with TypeOrmModule.forRootAsync
+├── database.config.ts          # Configuration factory
+├── typeorm-xray-logger.ts      # Custom X-Ray logger
+├── entities/
+│   ├── index.ts                # Explicit entity exports
+│   ├── timestamped.entity.ts   # Abstract base entity (no @Entity decorator)
+│   ├── user.entity.ts
+│   └── ...
+├── repositories/               # Only if custom repositories needed
+│   ├── index.ts
+│   ├── user.repository.ts
+│   └── ...
+└── migrations/
+    └── {timestamp}-{name}.ts
+```
+
+## Detailed References
+
+For comprehensive implementation details, see:
+
+- **[references/configuration-patterns.md](references/configuration-patterns.md)** - TypeOrmModule setup, replication, environment configuration
+- **[references/entity-patterns.md](references/entity-patterns.md)** - Base entity, relationships, indexes, enums, views
+- **[references/observability-patterns.md](references/observability-patterns.md)** - X-Ray logger implementation with graceful degradation