@martinffx/atelier 2.0.0 → 3.0.0

package/skills/typescript-drizzle-orm/references/entity-pattern.md

@@ -1,412 +0,0 @@
-# Entity Pattern
-
-Domain entities encapsulate business logic and data transformations between API, domain, and database layers.
-
-## Core Concept
-
-Entities have **four transformation methods**:
-
-1. `fromRequest(rq)` - API request → Entity
-2. `fromRecord(record)` - Database record → Entity
-3. `toRecord()` - Entity → Database insert/update
-4. `toResponse()` - Entity → API response
-
-This creates clear boundaries between layers and centralizes data transformation logic.
-
-## Basic Entity
-
-```typescript
-import type { InferInsertModel, InferSelectModel } from 'drizzle-orm'
-import type { users } from '../schema'
-
-// Infer types from schema
-type UserRecord = InferSelectModel<typeof users>
-type UserInsert = InferInsertModel<typeof users>
-
-interface UserEntityData {
-  id: string
-  name: string
-  email: string
-  createdAt: Date
-  updatedAt: Date
-}
-
-export class UserEntity {
-  public readonly id: string
-  public readonly name: string
-  public readonly email: string
-  public readonly createdAt: Date
-  public readonly updatedAt: Date
-
-  // Private constructor enforces factory methods
-  private constructor(data: UserEntityData) {
-    this.id = data.id
-    this.name = data.name
-    this.email = data.email
-    this.createdAt = data.createdAt
-    this.updatedAt = data.updatedAt
-  }
-
-  // 1. API request → Entity
-  static fromRequest(rq: CreateUserRequest, id?: string): UserEntity {
-    const now = new Date()
-    return new UserEntity({
-      id: id ?? crypto.randomUUID(),
-      name: rq.name,
-      email: rq.email,
-      createdAt: now,
-      updatedAt: now,
-    })
-  }
-
-  // 2. DB record → Entity
-  static fromRecord(record: UserRecord): UserEntity {
-    return new UserEntity({
-      id: record.id,
-      name: record.name,
-      email: record.email,
-      createdAt: record.createdAt,
-      updatedAt: record.updatedAt,
-    })
-  }
-
-  // 3. Entity → DB record
-  toRecord(): UserInsert {
-    return {
-      id: this.id,
-      name: this.name,
-      email: this.email,
-      createdAt: this.createdAt,
-      updatedAt: this.updatedAt,
-    }
-  }
-
-  // 4. Entity → API response
-  toResponse(): UserResponse {
-    return {
-      id: this.id,
-      name: this.name,
-      email: this.email,
-      createdAt: this.createdAt.toISOString(),
-      updatedAt: this.updatedAt.toISOString(),
-    }
-  }
-}
-```
-
-## Entity with TypeID
-
-Using TypeID for type-safe prefixed identifiers:
-
-```typescript
-import { TypeID } from 'typeid-js'
-import type { InferInsertModel, InferSelectModel } from 'drizzle-orm'
-import type { users } from '../schema'
-
-type UserID = TypeID<'usr'>
-type UserRecord = InferSelectModel<typeof users>
-type UserInsert = InferInsertModel<typeof users>
-
-export class UserEntity {
-  public readonly id: UserID
-  public readonly name: string
-  public readonly email: string
-
-  private constructor(data: {
-    id: UserID
-    name: string
-    email: string
-  }) {
-    this.id = data.id
-    this.name = data.name
-    this.email = data.email
-  }
-
-  static fromRequest(rq: CreateUserRequest, id?: string): UserEntity {
-    return new UserEntity({
-      id: id ? TypeID.fromString<'usr'>(id) : new TypeID('usr'),
-      name: rq.name,
-      email: rq.email,
-    })
-  }
-
-  static fromRecord(record: UserRecord): UserEntity {
-    return new UserEntity({
-      id: TypeID.fromString<'usr'>(record.id),
-      name: record.name,
-      email: record.email,
-    })
-  }
-
-  toRecord(): UserInsert {
-    return {
-      id: this.id.toString(),  // TypeID → string for DB
-      name: this.name,
-      email: this.email,
-    }
-  }
-
-  toResponse(): UserResponse {
-    return {
-      id: this.id.toString(),  // TypeID → string for API
-      name: this.name,
-      email: this.email,
-    }
-  }
-}
-```
-
-## Entity with JSON Fields
-
-Handle JSON serialization/deserialization:
-
-```typescript
-import type { InferInsertModel, InferSelectModel } from 'drizzle-orm'
-import type { users } from '../schema'
-
-type UserMetadata = {
-  theme: 'light' | 'dark'
-  notifications: boolean
-}
-
-type UserRecord = InferSelectModel<typeof users>
-type UserInsert = InferInsertModel<typeof users>
-
-export class UserEntity {
-  public readonly id: string
-  public readonly name: string
-  public readonly metadata?: UserMetadata
-
-  private constructor(data: {
-    id: string
-    name: string
-    metadata?: UserMetadata
-  }) {
-    this.id = data.id
-    this.name = data.name
-    this.metadata = data.metadata
-  }
-
-  static fromRequest(rq: CreateUserRequest, id?: string): UserEntity {
-    return new UserEntity({
-      id: id ?? crypto.randomUUID(),
-      name: rq.name,
-      metadata: rq.metadata,  // Already typed from API schema
-    })
-  }
-
-  static fromRecord(record: UserRecord): UserEntity {
-    // Parse JSON string from TEXT column
-    let metadata: UserMetadata | undefined
-    if (record.metadata) {
-      metadata = JSON.parse(record.metadata)
-    }
-
-    return new UserEntity({
-      id: record.id,
-      name: record.name,
-      metadata,
-    })
-  }
-
-  toRecord(): UserInsert {
-    return {
-      id: this.id,
-      name: this.name,
-      // Serialize to JSON string for TEXT column
-      metadata: this.metadata ? JSON.stringify(this.metadata) : undefined,
-    }
-  }
-
-  toResponse(): UserResponse {
-    return {
-      id: this.id,
-      name: this.name,
-      metadata: this.metadata,  // Send as object
-    }
-  }
-}
-```
-
-## Entity with Business Logic
-
-Entities can contain domain logic that operates on their data:
-
-```typescript
-import { TypeID } from 'typeid-js'
-import type { InferInsertModel, InferSelectModel } from 'drizzle-orm'
-import type { ledgerAccounts } from '../schema'
-
-type LedgerAccountID = TypeID<'lat'>
-type LedgerAccountRecord = InferSelectModel<typeof ledgerAccounts>
-type LedgerAccountInsert = InferInsertModel<typeof ledgerAccounts>
-
-export class LedgerAccountEntity {
-  public readonly id: LedgerAccountID
-  public readonly name: string
-  public readonly normalBalance: 'debit' | 'credit'
-  public readonly postedAmount: number
-  public readonly lockVersion: number
-  public readonly updated: Date
-
-  private constructor(data: {
-    id: LedgerAccountID
-    name: string
-    normalBalance: 'debit' | 'credit'
-    postedAmount: number
-    lockVersion: number
-    updated: Date
-  }) {
-    Object.assign(this, data)
-  }
-
-  static fromRecord(record: LedgerAccountRecord): LedgerAccountEntity {
-    return new LedgerAccountEntity({
-      id: TypeID.fromString<'lat'>(record.id),
-      name: record.name,
-      normalBalance: record.normalBalance as 'debit' | 'credit',
-      postedAmount: record.postedAmount,
-      lockVersion: record.lockVersion,
-      updated: record.updated,
-    })
-  }
-
-  /**
-   * Apply a transaction entry and return a new immutable entity.
-   * Uses double-entry accounting rules based on the account's normal balance.
-   */
-  applyEntry(entry: {
-    direction: 'debit' | 'credit'
-    amount: number
-  }): LedgerAccountEntity {
-    let newPostedAmount = this.postedAmount
-
-    if (this.normalBalance === 'debit') {
-      if (entry.direction === 'debit') {
-        newPostedAmount += entry.amount  // Debit increases debit accounts
-      } else {
-        newPostedAmount -= entry.amount  // Credit decreases debit accounts
-      }
-    } else {
-      // credit normal balance
-      if (entry.direction === 'credit') {
-        newPostedAmount += entry.amount  // Credit increases credit accounts
-      } else {
-        newPostedAmount -= entry.amount  // Debit decreases credit accounts
-      }
-    }
-
-    // Return new immutable instance
-    return new LedgerAccountEntity({
-      ...this,
-      postedAmount: newPostedAmount,
-      updated: new Date(),
-    })
-  }
-
-  toRecord(): LedgerAccountInsert {
-    return {
-      id: this.id.toString(),
-      name: this.name,
-      normalBalance: this.normalBalance,
-      postedAmount: this.postedAmount,
-      lockVersion: this.lockVersion,
-      updated: this.updated,
-    }
-  }
-
-  toResponse(): LedgerAccountResponse {
-    return {
-      id: this.id.toString(),
-      name: this.name,
-      normalBalance: this.normalBalance,
-      postedAmount: this.postedAmount,
-      updated: this.updated.toISOString(),
-    }
-  }
-}
-```
-
-## Entity with Defaults
-
-Handle default values consistently:
-
-```typescript
-export class LedgerEntity {
-  public readonly id: LedgerID
-  public readonly organizationId: OrgID
-  public readonly name: string
-  public readonly currency: string
-  public readonly currencyExponent: number
-  public readonly metadata?: Record<string, unknown>
-
-  private constructor(data: LedgerEntityData) {
-    Object.assign(this, data)
-  }
-
-  static fromRequest(
-    rq: LedgerRequest,
-    organizationId: OrgID,
-    id?: string
-  ): LedgerEntity {
-    return new LedgerEntity({
-      id: id ? TypeID.fromString<'lgr'>(id) : new TypeID('lgr'),
-      organizationId,
-      name: rq.name,
-      currency: rq.currency ?? 'USD',  // Apply default
-      currencyExponent: rq.currencyExponent ?? 2,  // Apply default
-      metadata: rq.metadata,
-    })
-  }
-
-  static fromRecord(record: LedgerRecord): LedgerEntity {
-    let metadata: Record<string, unknown> | undefined
-    if (record.metadata) {
-      metadata = JSON.parse(record.metadata)
-    }
-
-    return new LedgerEntity({
-      id: TypeID.fromString<'lgr'>(record.id),
-      organizationId: TypeID.fromString<'org'>(record.organizationId),
-      name: record.name,
-      currency: record.currency,
-      currencyExponent: record.currencyExponent,
-      metadata,
-    })
-  }
-
-  toRecord(): LedgerInsert {
-    return {
-      id: this.id.toString(),
-      organizationId: this.organizationId.toString(),
-      name: this.name,
-      currency: this.currency,
-      currencyExponent: this.currencyExponent,
-      metadata: this.metadata ? JSON.stringify(this.metadata) : undefined,
-    }
-  }
-
-  toResponse(): LedgerResponse {
-    return {
-      id: this.id.toString(),
-      name: this.name,
-      currency: this.currency,
-      currencyExponent: this.currencyExponent,
-      metadata: this.metadata,
-    }
-  }
-}
-```
-
-## Guidelines
-
-1. **Use immutable readonly properties** - Prevents accidental mutation
-2. **Private constructor** - Forces use of factory methods (fromRequest, fromRecord)
-3. **Four transformation methods** - Clear contracts for each layer boundary
-4. **Business logic in entities** - Domain rules belong in entities, not repos or services
-5. **Return new instances** - When applying changes, return new entity (immutability)
-6. **Parse JSON in fromRecord** - Handle TEXT → object deserialization
-7. **Stringify JSON in toRecord** - Handle object → TEXT serialization
-8. **Format dates in toResponse** - Convert Date → ISO string for API
-9. **Apply defaults in fromRequest** - Ensure defaults are set when creating from API
-10. **Use TypeID for type safety** - Prevents ID mixups across entity types

package/skills/typescript-drizzle-orm/references/postgresql.md

@@ -1,191 +0,0 @@
-# PostgreSQL Patterns with Drizzle ORM
-
-PostgreSQL-specific patterns, connection setup, and error handling.
-
-## Schema Definition
-
-```typescript
-import {
-  pgTable,
-  serial,
-  text,
-  integer,
-  timestamp,
-  boolean,
-  varchar,
-  uuid,
-  primaryKey,
-  unique,
-  index
-} from 'drizzle-orm/pg-core'
-
-export const users = pgTable('users', {
-  id: serial('id').primaryKey(),
-  name: text('name').notNull(),
-  email: varchar('email', { length: 255 }).notNull().unique(),
-  age: integer('age'),
-  isActive: boolean('is_active').default(true),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-  updatedAt: timestamp('updated_at').$onUpdate(() => new Date()),
-})
-
-export const posts = pgTable('posts', {
-  id: serial('id').primaryKey(),
-  title: text('title').notNull(),
-  content: text('content'),
-  authorId: integer('author_id')
-    .notNull()
-    .references(() => users.id, { onDelete: 'cascade' }),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-})
-```
-
-## Database Connection
-
-```typescript
-import { drizzle } from 'drizzle-orm/node-postgres'
-import { Pool } from 'pg'
-import * as schema from './schema'
-
-const pool = new Pool({ connectionString: process.env.DATABASE_URL })
-export const db = drizzle(pool, { schema })
-```
-
-## Migrations (drizzle-kit)
-
-```typescript
-// drizzle.config.ts
-import { defineConfig } from 'drizzle-kit'
-
-export default defineConfig({
-  schema: './src/db/schema.ts',
-  out: './drizzle',
-  dialect: 'postgresql',
-  dbCredentials: {
-    url: process.env.DATABASE_URL!,
-  },
-})
-```
-
-```bash
-# Generate migration
-npx drizzle-kit generate
-
-# Apply migrations
-npx drizzle-kit migrate
-
-# Open Drizzle Studio
-npx drizzle-kit studio
-
-# Pull schema from existing DB
-npx drizzle-kit pull
-```
-
-## Column Helpers
-
-```typescript
-// UUID with auto-generation
-id: uuid('id').defaultRandom().primaryKey()
-
-// Timestamps
-createdAt: timestamp('created_at').defaultNow().notNull()
-updatedAt: timestamp('updated_at').$onUpdate(() => new Date())
-
-// Enum
-import { pgEnum } from 'drizzle-orm/pg-core'
-export const statusEnum = pgEnum('status', ['pending', 'active', 'archived'])
-// usage: status: statusEnum('status').default('pending')
-
-// JSON
-metadata: jsonb('metadata').$type<{ key: string }>()
-```
-
-## Composite Keys & Indexes
-
-```typescript
-export const postTags = pgTable('post_tags', {
-  postId: integer('post_id').references(() => posts.id),
-  tagId: integer('tag_id').references(() => tags.id),
-}, (t) => [
-  primaryKey({ columns: [t.postId, t.tagId] }),
-])
-
-export const users = pgTable('users', {
-  // columns...
-}, (t) => [
-  unique('unique_email').on(t.email),
-  index('name_idx').on(t.name),
-])
-```
-
-## PostgreSQL Error Codes
-
-Map database error codes to domain errors:
-
-```typescript
-type ErrorContext = {
-  userId?: string
-  resourceId?: string
-  [key: string]: unknown
-}
-
-function handleDBError(error: unknown, context: ErrorContext = {}): never {
-  const code = (error as { code?: string }).code
-
-  switch (code) {
-    case '23505': // unique_violation
-      throw new ConflictError('Resource already exists', context)
-    case '23503': // foreign_key_violation
-      throw new NotFoundError('Referenced resource not found', context)
-    case '40001': // serialization_failure
-      throw new ServiceUnavailableError('Transaction conflict - please retry', {
-        retryable: true,
-        ...context,
-      })
-    case 'OC000': // AWS DSQL occ_conflict
-      throw new ServiceUnavailableError('Optimistic concurrency conflict', {
-        retryable: true,
-        ...context,
-      })
-    default:
-      throw error
-  }
-}
-```
-
-## Optimistic Locking
-
-Prevent concurrent modification issues with version-based locking:
-
-```typescript
-// Add lockVersion column to schema
-export const users = pgTable('users', {
-  id: uuid('id').defaultRandom().primaryKey(),
-  name: text('name').notNull(),
-  lockVersion: integer('lock_version').default(0).notNull(),
-  updatedAt: timestamp('updated_at').$onUpdate(() => new Date()),
-})
-
-// Update with version check
-async update(entity: UserEntity): Promise<UserEntity> {
-  const result = await this.db
-    .update(users)
-    .set({
-      ...entity.toRecord(),
-      lockVersion: sql`${users.lockVersion} + 1`,
-    })
-    .where(and(
-      eq(users.id, entity.id),
-      eq(users.lockVersion, entity.lockVersion)
-    ))
-    .returning()
-
-  if (result.length === 0) {
-    throw new ConflictError({
-      message: 'Resource was modified by another transaction',
-      retryable: true,
-    })
-  }
-  return UserEntity.fromRecord(result[0])
-}
-```