@aicgen/aicgen 1.0.0-beta.1

package/data/patterns/data-access.md

@@ -0,0 +1,83 @@
+# Data Access Patterns
+
+## Repository
+
+Collection-like interface for domain objects.
+
+```typescript
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  save(user: User): Promise<void>;
+  delete(user: User): Promise<void>;
+}
+
+class PostgreSQLUserRepository implements UserRepository {
+  async findById(id: string): Promise<User | null> {
+    const row = await this.db.queryOne('SELECT * FROM users WHERE id = $1', [id]);
+    return row ? this.mapToUser(row) : null;
+  }
+}
+```
+
+## Data Mapper
+
+Complete separation between domain and persistence.
+
+```typescript
+class UserMapper {
+  toDomain(row: DbRow): User {
+    return new User(row.id, row.name, new Email(row.email));
+  }
+
+  toDatabase(user: User): DbRow {
+    return { id: user.id, name: user.name, email: user.email.toString() };
+  }
+}
+```
+
+## Unit of Work
+
+Track changes and commit together.
+
+```typescript
+class UnitOfWork {
+  private newObjects = new Set<any>();
+  private dirtyObjects = new Set<any>();
+
+  registerNew(obj: any): void { this.newObjects.add(obj); }
+  registerDirty(obj: any): void { this.dirtyObjects.add(obj); }
+
+  async commit(): Promise<void> {
+    await this.db.beginTransaction();
+    try {
+      for (const obj of this.newObjects) await this.insert(obj);
+      for (const obj of this.dirtyObjects) await this.update(obj);
+      await this.db.commit();
+    } catch (e) {
+      await this.db.rollback();
+      throw e;
+    }
+  }
+}
+```
+
+## Identity Map
+
+Ensure each object loaded only once per session.
+
+```typescript
+class IdentityMap {
+  private map = new Map<string, any>();
+
+  get(id: string): any | null { return this.map.get(id) || null; }
+  put(id: string, obj: any): void { this.map.set(id, obj); }
+}
+```
+
+## Best Practices
+
+- Return domain objects from repositories
+- Use one repository per aggregate root
+- Keep repositories focused on persistence
+- Don't leak database details into domain

package/data/patterns/distribution.md

@@ -0,0 +1,86 @@
+# Distribution Patterns
+
+## Remote Facade
+
+Coarse-grained interface to reduce network calls.
+
+```typescript
+// Bad: Multiple network calls
+const customer = await api.getCustomer(id);
+const orders = await api.getOrders(id);
+const addresses = await api.getAddresses(id);
+
+// Good: Single call via facade
+const details = await api.getCustomerDetails(id);
+// Returns { customer, orders, addresses }
+```
+
+## Data Transfer Object (DTO)
+
+Bundle data for transfer across boundaries.
+
+```typescript
+interface OrderDTO {
+  id: string;
+  customerId: string;
+  items: OrderItemDTO[];
+  total: number;
+  status: string;
+}
+
+class OrderDTOMapper {
+  static toDTO(order: Order): OrderDTO {
+    return {
+      id: order.id,
+      customerId: order.customer.id,
+      items: order.items.map(i => this.itemToDTO(i)),
+      total: order.total.amount,
+      status: order.status.toString()
+    };
+  }
+}
+```
+
+## Gateway
+
+Abstract external system access.
+
+```typescript
+interface PaymentGateway {
+  charge(amount: Money, method: PaymentMethod): Promise<PaymentResult>;
+}
+
+class StripeGateway implements PaymentGateway {
+  async charge(amount: Money, method: PaymentMethod): Promise<PaymentResult> {
+    const result = await this.stripe.paymentIntents.create({
+      amount: amount.cents,
+      currency: amount.currency
+    });
+    return this.mapToResult(result);
+  }
+}
+```
+
+## Service Stub
+
+Test double for external services.
+
+```typescript
+class StubPaymentGateway implements PaymentGateway {
+  private shouldSucceed = true;
+
+  async charge(amount: Money): Promise<PaymentResult> {
+    if (!this.shouldSucceed) throw new PaymentDeclinedError();
+    return { success: true, transactionId: 'stub-123' };
+  }
+
+  configureFail(): void { this.shouldSucceed = false; }
+}
+```
+
+## Best Practices
+
+- Design facades around client use cases
+- Keep DTOs simple and serializable
+- Isolate vendor code in gateways
+- Use stubs for testing, not production

package/data/patterns/domain-logic.md

@@ -0,0 +1,81 @@
+# Domain Logic Patterns
+
+## Transaction Script
+
+Procedural approach - one procedure per operation.
+
+```typescript
+async function transferMoney(fromId: string, toId: string, amount: number) {
+  const db = await Database.connect();
+  await db.beginTransaction();
+
+  try {
+    const from = await db.query('SELECT * FROM accounts WHERE id = $1', [fromId]);
+    if (from.balance < amount) throw new Error('Insufficient funds');
+
+    await db.execute('UPDATE accounts SET balance = balance - $1 WHERE id = $2', [amount, fromId]);
+    await db.execute('UPDATE accounts SET balance = balance + $1 WHERE id = $2', [amount, toId]);
+    await db.commit();
+  } catch (e) {
+    await db.rollback();
+    throw e;
+  }
+}
+```
+
+**Use for:** Simple apps, CRUD, reports.
+
+## Domain Model
+
+Rich objects with behavior.
+
+```typescript
+class Account {
+  constructor(private balance: Money, private overdraftLimit: Money) {}
+
+  withdraw(amount: Money): void {
+    if (!this.canWithdraw(amount)) throw new InsufficientFundsError();
+    this.balance = this.balance.subtract(amount);
+  }
+
+  transfer(amount: Money, recipient: Account): void {
+    this.withdraw(amount);
+    recipient.deposit(amount);
+  }
+}
+```
+
+**Use for:** Complex business rules, rich domains.
+
+## Service Layer
+
+Application boundary coordinating domain objects.
+
+```typescript
+class AccountService {
+  constructor(
+    private accountRepo: AccountRepository,
+    private unitOfWork: UnitOfWork
+  ) {}
+
+  async transfer(fromId: string, toId: string, amount: Money): Promise<void> {
+    const from = await this.accountRepo.findById(fromId);
+    const to = await this.accountRepo.findById(toId);
+
+    from.transfer(amount, to); // Domain logic
+
+    await this.accountRepo.save(from);
+    await this.accountRepo.save(to);
+    await this.unitOfWork.commit();
+  }
+}
+```
+
+**Use for:** API boundaries, multiple clients, transaction coordination.
+
+## Best Practices
+
+- Choose pattern based on complexity
+- Service layer orchestrates, domain model contains logic
+- Keep services thin, domain objects rich
+- Combine Domain Model + Service Layer for complex apps

package/data/patterns/gof.md

@@ -0,0 +1,109 @@
+# Gang of Four Patterns
+
+## Creational
+
+### Factory Method
+```typescript
+interface Logger { log(msg: string): void; }
+
+abstract class Application {
+  abstract createLogger(): Logger;
+  run(): void { this.createLogger().log('Started'); }
+}
+
+class DevApp extends Application {
+  createLogger(): Logger { return new ConsoleLogger(); }
+}
+```
+
+### Builder
+```typescript
+const query = new QueryBuilder()
+  .from('users')
+  .select('id', 'name')
+  .where('active = true')
+  .limit(10)
+  .build();
+```
+
+## Structural
+
+### Adapter
+```typescript
+class PaymentAdapter implements PaymentProcessor {
+  constructor(private legacy: OldPaymentSystem) {}
+
+  async process(amount: number): Promise<boolean> {
+    return this.legacy.makePayment(amount);
+  }
+}
+```
+
+### Decorator
+```typescript
+interface Coffee { cost(): number; }
+
+class MilkDecorator implements Coffee {
+  constructor(private coffee: Coffee) {}
+  cost(): number { return this.coffee.cost() + 2; }
+}
+
+let coffee: Coffee = new SimpleCoffee();
+coffee = new MilkDecorator(coffee);
+```
+
+### Facade
+```typescript
+class ComputerFacade {
+  start(): void {
+    this.cpu.freeze();
+    this.memory.load(0, this.hdd.read(0, 1024));
+    this.cpu.execute();
+  }
+}
+```
+
+## Behavioral
+
+### Strategy
+```typescript
+interface SortStrategy { sort(data: number[]): number[]; }
+
+class Sorter {
+  constructor(private strategy: SortStrategy) {}
+  sort(data: number[]): number[] { return this.strategy.sort(data); }
+}
+```
+
+### Observer
+```typescript
+class Stock {
+  private observers: Observer[] = [];
+
+  attach(o: Observer): void { this.observers.push(o); }
+  notify(): void { this.observers.forEach(o => o.update(this)); }
+
+  setPrice(price: number): void {
+    this.price = price;
+    this.notify();
+  }
+}
+```
+
+### Command
+```typescript
+interface Command { execute(): void; undo(): void; }
+
+class AppendCommand implements Command {
+  constructor(private editor: Editor, private text: string) {}
+  execute(): void { this.editor.append(this.text); }
+  undo(): void { this.editor.delete(this.text.length); }
+}
+```
+
+## Best Practices
+
+- Use patterns to solve specific problems, not everywhere
+- Combine patterns when appropriate
+- Favor composition over inheritance
+- Keep implementations simple

package/data/patterns/index.md

@@ -0,0 +1,12 @@
+# Enterprise Patterns
+
+This directory contains enterprise application patterns.
+
+## Available Chunks
+
+- **base-patterns.md** - Value Objects, Money, Special Case, Registry, Plugin
+- **concurrency.md** - Optimistic/Pessimistic locking, Coarse-Grained Lock
+- **data-access.md** - Repository, Data Mapper, Active Record, Unit of Work
+- **distribution.md** - Remote Facade, DTO, Gateway, Service Stub
+- **domain-logic.md** - Transaction Script, Domain Model, Service Layer
+- **gof.md** - Gang of Four: Creational, Structural, Behavioral patterns

package/data/performance/async.md

@@ -0,0 +1,148 @@
+# Async Performance Patterns
+
+## Parallel Execution
+
+```typescript
+// ❌ Sequential - slow
+async function getUserData(userId: string) {
+  const user = await fetchUser(userId);       // 100ms
+  const posts = await fetchPosts(userId);     // 150ms
+  const comments = await fetchComments(userId); // 120ms
+  return { user, posts, comments }; // Total: 370ms
+}
+
+// ✅ Parallel - fast
+async function getUserData(userId: string) {
+  const [user, posts, comments] = await Promise.all([
+    fetchUser(userId),
+    fetchPosts(userId),
+    fetchComments(userId)
+  ]);
+  return { user, posts, comments }; // Total: 150ms
+}
+
+// ✅ Partial parallel with dependencies
+async function getOrderDetails(orderId: string) {
+  const order = await fetchOrder(orderId); // Must fetch first
+
+  const [customer, items, shipping] = await Promise.all([
+    fetchCustomer(order.customerId),
+    fetchOrderItems(orderId),
+    fetchShippingInfo(orderId)
+  ]);
+
+  return { order, customer, items, shipping };
+}
+```
+
+## Promise.allSettled for Partial Failures
+
+```typescript
+// Return partial data instead of complete failure
+async function getDashboard(userId: string) {
+  const [user, orders, stats] = await Promise.allSettled([
+    getUser(userId),
+    getOrders(userId),
+    getStats(userId)
+  ]);
+
+  return {
+    user: user.status === 'fulfilled' ? user.value : null,
+    orders: orders.status === 'fulfilled' ? orders.value : [],
+    stats: stats.status === 'fulfilled' ? stats.value : null,
+    errors: {
+      user: user.status === 'rejected' ? user.reason.message : null,
+      orders: orders.status === 'rejected' ? orders.reason.message : null,
+      stats: stats.status === 'rejected' ? stats.reason.message : null
+    }
+  };
+}
+```
+
+## Batch Processing
+
+```typescript
+// ❌ One at a time - slow
+async function processUsers(userIds: string[]) {
+  for (const id of userIds) {
+    await updateUser(id);
+  }
+}
+
+// ✅ Batch processing
+async function processUsers(userIds: string[]) {
+  const BATCH_SIZE = 50;
+
+  for (let i = 0; i < userIds.length; i += BATCH_SIZE) {
+    const batch = userIds.slice(i, i + BATCH_SIZE);
+    await Promise.all(batch.map(id => updateUser(id)));
+  }
+}
+
+// ✅ Bulk database operations
+async function createUsers(users: User[]) {
+  await db.query(`
+    INSERT INTO users (name, email)
+    VALUES ${users.map(() => '(?, ?)').join(', ')}
+  `, users.flatMap(u => [u.name, u.email]));
+}
+```
+
+## Debouncing and Throttling
+
+```typescript
+// Debounce: Wait until user stops typing
+const debounce = <T extends (...args: any[]) => any>(
+  fn: T,
+  delay: number
+): ((...args: Parameters<T>) => void) => {
+  let timeoutId: NodeJS.Timeout;
+
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => fn(...args), delay);
+  };
+};
+
+// Throttle: Execute at most once per interval
+const throttle = <T extends (...args: any[]) => any>(
+  fn: T,
+  limit: number
+): ((...args: Parameters<T>) => void) => {
+  let inThrottle: boolean;
+
+  return (...args: Parameters<T>) => {
+    if (!inThrottle) {
+      fn(...args);
+      inThrottle = true;
+      setTimeout(() => (inThrottle = false), limit);
+    }
+  };
+};
+
+// Usage
+const searchUsers = debounce(query => api.search(query), 300);
+const handleScroll = throttle(() => console.log('scroll'), 100);
+```
+
+## Rate Limiting Concurrent Operations
+
+```typescript
+async function processWithLimit<T>(
+  items: T[],
+  fn: (item: T) => Promise<void>,
+  concurrency: number
+): Promise<void> {
+  const chunks = [];
+  for (let i = 0; i < items.length; i += concurrency) {
+    chunks.push(items.slice(i, i + concurrency));
+  }
+
+  for (const chunk of chunks) {
+    await Promise.all(chunk.map(fn));
+  }
+}
+
+// Usage: Process 100 items, max 10 at a time
+await processWithLimit(users, updateUser, 10);
+```