@aicgen/aicgen 1.0.0-beta.1

package/data/language/typescript/error-handling.md

@@ -0,0 +1,98 @@
+# TypeScript Error Handling
+
+## Custom Error Classes
+
+```typescript
+// ✅ Create structured error hierarchy
+class AppError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number = 500,
+    public code: string = 'INTERNAL_ERROR',
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} with id ${id} not found`, 404, 'NOT_FOUND', { resource, id });
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message: string, details: unknown) {
+    super(message, 400, 'VALIDATION_ERROR', details);
+  }
+}
+```
+
+## Async Error Handling
+
+```typescript
+// ✅ Always handle promise rejections
+async function fetchUser(id: string): Promise<User> {
+  try {
+    const response = await api.get(`/users/${id}`);
+    return response.data;
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) {
+      throw new NotFoundError('User', id);
+    }
+    throw new AppError('Failed to fetch user', 500, 'FETCH_ERROR', { userId: id });
+  }
+}
+
+// ✅ Use wrapper for Express async handlers
+const asyncHandler = (fn: RequestHandler) => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+};
+```
+
+## Result Type Pattern
+
+```typescript
+// ✅ Explicit success/failure without exceptions
+type Result<T, E = Error> =
+  | { success: true; value: T }
+  | { success: false; error: E };
+
+function parseJSON<T>(json: string): Result<T, string> {
+  try {
+    return { success: true, value: JSON.parse(json) };
+  } catch {
+    return { success: false, error: 'Invalid JSON' };
+  }
+}
+
+// Usage
+const result = parseJSON<User>(data);
+if (result.success) {
+  console.log(result.value.name);
+} else {
+  console.error(result.error);
+}
+```
+
+## Centralized Error Handler
+
+```typescript
+// ✅ Express error middleware
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      error: { message: err.message, code: err.code, details: err.details }
+    });
+  }
+
+  console.error('Unexpected error:', err);
+  res.status(500).json({
+    error: { message: 'Internal server error', code: 'INTERNAL_ERROR' }
+  });
+});
+```

package/data/language/typescript/generics.md

@@ -0,0 +1,85 @@
+# TypeScript Generics
+
+## Basic Generic Functions
+
+```typescript
+// ✅ Generic function for type-safe operations
+function first<T>(array: T[]): T | undefined {
+  return array[0];
+}
+
+const numbers = [1, 2, 3];
+const firstNumber = first(numbers); // Type: number | undefined
+
+const users = [{ name: 'John' }];
+const firstUser = first(users); // Type: { name: string } | undefined
+```
+
+## Generic Interfaces
+
+```typescript
+// ✅ Generic repository pattern
+interface Repository<T> {
+  findById(id: string): Promise<T | null>;
+  findAll(): Promise<T[]>;
+  create(entity: Omit<T, 'id'>): Promise<T>;
+  update(id: string, data: Partial<T>): Promise<T>;
+  delete(id: string): Promise<void>;
+}
+
+class UserRepository implements Repository<User> {
+  async findById(id: string): Promise<User | null> {
+    return this.db.users.findUnique({ where: { id } });
+  }
+  // ... other methods
+}
+```
+
+## Generic Constraints
+
+```typescript
+// ✅ Constrain generic types
+interface HasId {
+  id: string;
+}
+
+function getById<T extends HasId>(items: T[], id: string): T | undefined {
+  return items.find(item => item.id === id);
+}
+
+// Works with any type that has an id
+getById(users, '123');
+getById(products, '456');
+```
+
+## Mapped Types
+
+```typescript
+// ✅ Create transformed types
+type Nullable<T> = {
+  [K in keyof T]: T[K] | null;
+};
+
+type NullableUser = Nullable<User>;
+// { id: string | null; name: string | null; ... }
+
+// ✅ Conditional types
+type ExtractArrayType<T> = T extends Array<infer U> ? U : never;
+
+type StringArrayElement = ExtractArrayType<string[]>; // string
+```
+
+## Default Generic Parameters
+
+```typescript
+// ✅ Provide defaults for flexibility
+interface ApiResponse<T = unknown, E = Error> {
+  data?: T;
+  error?: E;
+  status: number;
+}
+
+// Can use with or without type parameters
+const response1: ApiResponse<User> = { data: user, status: 200 };
+const response2: ApiResponse = { status: 500, error: new Error('Failed') };
+```

package/data/language/typescript/index.md

@@ -0,0 +1,14 @@
+# TypeScript Guidelines
+
+TypeScript-specific best practices for Claude Code.
+
+## Chunks
+
+- `basics.md` - Type system fundamentals and strict mode
+- `interfaces-types.md` - Interfaces vs types, when to use each
+- `generics.md` - Generic programming patterns
+- `async.md` - Async/await and Promise patterns
+- `error-handling.md` - Type-safe error handling
+- `testing.md` - Testing TypeScript code
+- `config.md` - tsconfig.json best practices
+- `performance.md` - Performance optimization

package/data/language/typescript/interfaces-types.md

@@ -0,0 +1,83 @@
+# TypeScript Types & Interfaces
+
+## Prefer Interfaces for Public APIs
+
+```typescript
+// ✅ Use interfaces for object shapes
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: Date;
+}
+
+// ✅ Use type aliases for unions and complex types
+type UserRole = 'admin' | 'editor' | 'viewer';
+type ResponseHandler = (response: Response) => void;
+```
+
+## Discriminated Unions
+
+```typescript
+// ✅ Use discriminated unions for variant types
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+function handleResult(result: Result<User>) {
+  if (result.success) {
+    console.log(result.data.name); // TypeScript knows data exists
+  } else {
+    console.error(result.error); // TypeScript knows error exists
+  }
+}
+```
+
+## Utility Types
+
+```typescript
+// Use built-in utility types
+type PartialUser = Partial<User>;           // All fields optional
+type RequiredUser = Required<User>;         // All fields required
+type ReadonlyUser = Readonly<User>;         // All fields readonly
+type UserKeys = keyof User;                 // 'id' | 'name' | 'email' | 'createdAt'
+type PickedUser = Pick<User, 'id' | 'name'>; // Only id and name
+type OmittedUser = Omit<User, 'createdAt'>; // Everything except createdAt
+```
+
+## Type Guards
+
+```typescript
+// ✅ Use type guards for runtime checking
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    'email' in value
+  );
+}
+
+// Usage
+const data: unknown = fetchData();
+if (isUser(data)) {
+  console.log(data.email); // TypeScript knows it's a User
+}
+```
+
+## Avoid `any`
+
+```typescript
+// ❌ Never use any
+function process(data: any) {
+  return data.name; // No type safety
+}
+
+// ✅ Use unknown with type guards
+function process(data: unknown) {
+  if (isUser(data)) {
+    return data.name; // Type-safe
+  }
+  throw new Error('Invalid data');
+}
+```

package/data/language/typescript/performance.md

@@ -0,0 +1,103 @@
+# TypeScript Performance
+
+## Choose Right Data Structures
+
+```typescript
+// ❌ Array for lookups (O(n))
+const users: User[] = [];
+const findUser = (id: string) => users.find(u => u.id === id);
+
+// ✅ Map for O(1) lookups
+const users = new Map<string, User>();
+const findUser = (id: string) => users.get(id);
+
+// ❌ Array for membership checks
+const hasPermission = (perms: string[], perm: string) => perms.includes(perm);
+
+// ✅ Set for O(1) membership
+const hasPermission = (perms: Set<string>, perm: string) => perms.has(perm);
+```
+
+## Avoid N+1 Queries
+
+```typescript
+// ❌ N+1 queries
+const getOrdersWithCustomers = async () => {
+  const orders = await db.query('SELECT * FROM orders');
+  for (const order of orders) {
+    order.customer = await db.query('SELECT * FROM customers WHERE id = ?', [order.customerId]);
+  }
+  return orders;
+};
+
+// ✅ Single JOIN query
+const getOrdersWithCustomers = async () => {
+  return db.query(`
+    SELECT orders.*, customers.name as customer_name
+    FROM orders
+    JOIN customers ON orders.customer_id = customers.id
+  `);
+};
+
+// ✅ Using ORM with eager loading
+const getOrdersWithCustomers = async () => {
+  return orderRepository.find({ relations: ['customer'] });
+};
+```
+
+## Parallel Execution
+
+```typescript
+// ❌ Sequential (slow)
+const getUserData = async (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)
+const getUserData = async (userId: string) => {
+  const [user, posts, comments] = await Promise.all([
+    fetchUser(userId),
+    fetchPosts(userId),
+    fetchComments(userId)
+  ]);
+  return { user, posts, comments }; // Total: 150ms
+};
+```
+
+## Memoization
+
+```typescript
+const memoize = <T extends (...args: any[]) => any>(fn: T): T => {
+  const cache = new Map<string, ReturnType<T>>();
+
+  return ((...args: any[]) => {
+    const key = JSON.stringify(args);
+    if (cache.has(key)) return cache.get(key);
+    const result = fn(...args);
+    cache.set(key, result);
+    return result;
+  }) as T;
+};
+
+const expensiveCalc = memoize((n: number) => {
+  // Expensive computation
+  return result;
+});
+```
+
+## Batch Processing
+
+```typescript
+// ✅ Process in batches
+const processUsers = async (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)));
+  }
+};
+```

package/data/language/typescript/testing.md

@@ -0,0 +1,98 @@
+# TypeScript Testing
+
+## Test Structure: Arrange-Act-Assert
+
+```typescript
+describe('UserService', () => {
+  describe('createUser', () => {
+    it('should create user with hashed password', async () => {
+      // Arrange
+      const userData = { email: 'test@example.com', password: 'password123' };
+      const mockRepo = { save: jest.fn().mockResolvedValue({ id: '1', ...userData }) };
+      const service = new UserService(mockRepo);
+
+      // Act
+      const result = await service.createUser(userData);
+
+      // Assert
+      expect(result.id).toBe('1');
+      expect(mockRepo.save).toHaveBeenCalledWith(
+        expect.objectContaining({ email: 'test@example.com' })
+      );
+    });
+  });
+});
+```
+
+## Test Observable Behavior, Not Implementation
+
+```typescript
+// ❌ Testing implementation details
+it('should call validateEmail method', () => {
+  const spy = jest.spyOn(service, 'validateEmail');
+  service.createUser({ email: 'test@example.com' });
+  expect(spy).toHaveBeenCalled(); // Brittle - breaks if refactored
+});
+
+// ✅ Testing observable behavior
+it('should reject invalid email', async () => {
+  await expect(
+    service.createUser({ email: 'invalid' })
+  ).rejects.toThrow('Invalid email');
+});
+```
+
+## Test Doubles
+
+```typescript
+// Stub: Returns canned responses
+const stubDatabase = {
+  findUser: () => ({ id: '1', name: 'Test User' })
+};
+
+// Mock: Pre-programmed with expectations
+const mockPayment = {
+  charge: jest.fn()
+    .mockResolvedValueOnce({ success: true })
+    .mockResolvedValueOnce({ success: false })
+};
+
+// Fake: Working implementation (not for production)
+class FakeDatabase implements Database {
+  private data = new Map<string, any>();
+
+  async save(id: string, data: any) { this.data.set(id, data); }
+  async find(id: string) { return this.data.get(id); }
+}
+```
+
+## One Test Per Condition
+
+```typescript
+// ❌ Multiple assertions for different scenarios
+it('should validate user input', () => {
+  expect(() => validate({ age: -1 })).toThrow();
+  expect(() => validate({ age: 200 })).toThrow();
+  expect(() => validate({ name: '' })).toThrow();
+});
+
+// ✅ One test per condition
+it('should reject negative age', () => {
+  expect(() => validate({ age: -1 })).toThrow('Age must be positive');
+});
+
+it('should reject age over 150', () => {
+  expect(() => validate({ age: 200 })).toThrow('Age must be under 150');
+});
+```
+
+## Keep Tests Independent
+
+```typescript
+// ✅ Each test is self-contained
+it('should update user', async () => {
+  const user = await service.createUser({ name: 'Test' });
+  const updated = await service.updateUser(user.id, { name: 'Updated' });
+  expect(updated.name).toBe('Updated');
+});
+```

package/data/patterns/base-patterns.md

@@ -0,0 +1,105 @@
+# Base Patterns
+
+## Value Object
+
+Immutable object defined by its value, not identity.
+
+```typescript
+class Email {
+  private readonly value: string;
+
+  constructor(email: string) {
+    if (!this.isValid(email)) throw new Error('Invalid email');
+    this.value = email.toLowerCase();
+  }
+
+  equals(other: Email): boolean {
+    return this.value === other.value;
+  }
+}
+
+class Money {
+  constructor(
+    public readonly amount: number,
+    public readonly currency: Currency
+  ) {
+    Object.freeze(this);
+  }
+
+  add(other: Money): Money {
+    this.assertSameCurrency(other);
+    return new Money(this.amount + other.amount, this.currency);
+  }
+}
+```
+
+## Special Case (Null Object)
+
+Replace null checks with polymorphism.
+
+```typescript
+abstract class Customer {
+  abstract getDiscount(): number;
+}
+
+class RealCustomer extends Customer {
+  getDiscount(): number { return 0.1; }
+}
+
+class GuestCustomer extends Customer {
+  getDiscount(): number { return 0; } // No discount
+}
+
+// No null checks needed
+const customer = repo.findById(id) || new GuestCustomer();
+const discount = customer.getDiscount();
+```
+
+## Registry
+
+Global access point for services.
+
+```typescript
+class ServiceRegistry {
+  private static services = new Map<string, any>();
+
+  static register<T>(key: string, service: T): void {
+    this.services.set(key, service);
+  }
+
+  static get<T>(key: string): T {
+    return this.services.get(key);
+  }
+}
+
+// Prefer dependency injection over registry
+```
+
+## Plugin
+
+Extend behavior without modifying core code.
+
+```typescript
+interface ValidationPlugin {
+  validate(user: User): ValidationResult;
+}
+
+class UserValidator {
+  private plugins: ValidationPlugin[] = [];
+
+  registerPlugin(plugin: ValidationPlugin): void {
+    this.plugins.push(plugin);
+  }
+
+  validate(user: User): ValidationResult[] {
+    return this.plugins.map(p => p.validate(user));
+  }
+}
+```
+
+## Best Practices
+
+- Use Value Objects to avoid primitive obsession
+- Make Value Objects immutable
+- Use Special Case instead of null checks
+- Prefer dependency injection over Registry

package/data/patterns/concurrency.md

@@ -0,0 +1,87 @@
+# Concurrency Patterns
+
+## Optimistic Locking
+
+Detect conflicts on commit using version numbers.
+
+```typescript
+class Product {
+  constructor(
+    public id: string,
+    public name: string,
+    public version: number = 1
+  ) {}
+}
+
+class ProductRepository {
+  async save(product: Product): Promise<void> {
+    const result = await this.db.execute(
+      `UPDATE products SET name = $1, version = version + 1
+       WHERE id = $2 AND version = $3`,
+      [product.name, product.id, product.version]
+    );
+
+    if (result.rowCount === 0) {
+      throw new OptimisticLockException('Product was modified');
+    }
+    product.version++;
+  }
+}
+```
+
+## Pessimistic Locking
+
+Lock resources before editing.
+
+```typescript
+class LockManager {
+  async acquireLock(resourceId: string, ownerId: string): Promise<boolean> {
+    const existing = await this.db.queryOne(
+      'SELECT * FROM locks WHERE resource_id = $1 AND expires_at > NOW()',
+      [resourceId]
+    );
+
+    if (existing) return false;
+
+    await this.db.execute(
+      'INSERT INTO locks (resource_id, owner_id, expires_at) VALUES ($1, $2, $3)',
+      [resourceId, ownerId, new Date(Date.now() + 30000)]
+    );
+    return true;
+  }
+
+  async releaseLock(resourceId: string, ownerId: string): Promise<void> {
+    await this.db.execute(
+      'DELETE FROM locks WHERE resource_id = $1 AND owner_id = $2',
+      [resourceId, ownerId]
+    );
+  }
+}
+```
+
+## Coarse-Grained Lock
+
+Lock entire aggregate rather than individual entities.
+
+```typescript
+class OrderRepository {
+  async save(order: Order): Promise<void> {
+    // Lock aggregate root, all children implicitly locked
+    await this.db.execute(
+      'SELECT * FROM orders WHERE id = $1 FOR UPDATE',
+      [order.id]
+    );
+
+    // Update order and all items in single transaction
+    await this.updateOrder(order);
+    await this.updateOrderItems(order.items);
+  }
+}
+```
+
+## Best Practices
+
+- Use optimistic locking for low-contention scenarios
+- Use pessimistic locking for high-contention or critical data
+- Always set lock timeouts
+- Implement retry logic with exponential backoff