BLISS FRAMEWORK - CLAUDE CODE COMMON SOLUTIONS
Version: 1.0.0
Last Modified: 2025-01-19T00:00:00Z
Category: Implementation Guidelines
Priority: High

Reusable solutions and patterns for frequently encountered problems across projects.

=== ERROR HANDLING PATTERNS ===

Result Pattern Implementation:
```typescript
// Base Result type
export interface Result<T> {
    success: boolean;
    data?: T;
    error?: string;
}

// Helper functions
export class ResultHelper {
    static success<T>(data: T): Result<T> {
        return { success: true, data };
    }

    static failure<T>(error: string): Result<T> {
        return { success: false, error };
    }

    static async fromPromise<T>(
        promise: Promise<T>,
        errorMessage?: string
    ): Promise<Result<T>> {
        try {
            const data = await promise;
            return ResultHelper.success(data);
        } catch (error) {
            return ResultHelper.failure(
                errorMessage || (error as Error).message
            );
        }
    }
}
```

Custom Error Classes:
```typescript
export class AppError extends Error {
    constructor(
        message: string,
        public code: string,
        public statusCode: number = 500
    ) {
        super(message);
        this.name = this.constructor.name;
    }
}

export class ValidationError extends AppError {
    constructor(message: string) {
        super(message, 'VALIDATION_ERROR', 400);
    }
}

export class NotFoundError extends AppError {
    constructor(resource: string) {
        super(`${resource} not found`, 'NOT_FOUND', 404);
    }
}
```

=== VALIDATION PATTERNS ===

Input Validation with Zod:
```typescript
import { z } from 'zod';

// Schema definitions
export const CreateUserSchema = z.object({
    email: z.string().email('Invalid email format'),
    name: z.string().min(1, 'Name is required').max(100, 'Name too long'),
    age: z.number().int().min(18, 'Must be at least 18')
});

// Validation helper
export class ValidationHelper {
    static validate<T>(schema: z.ZodSchema<T>, data: unknown): Result<T> {
        try {
            const validData = schema.parse(data);
            return ResultHelper.success(validData);
        } catch (error) {
            if (error instanceof z.ZodError) {
                const messages = error.errors.map(e => e.message).join(', ');
                return ResultHelper.failure(`Validation failed: ${messages}`);
            }
            return ResultHelper.failure('Validation failed');
        }
    }
}
```

Business Rule Validation:
```typescript
export class UserBusinessRules {
    static async validateUserCreation(
        userData: CreateUserData,
        userProvider: UserProvider
    ): Promise<Result<void>> {
        // Check if email already exists
        const existingUser = await userProvider.getUserByEmail(userData.email);
        if (existingUser) {
            return ResultHelper.failure('Email already registered');
        }

        // Check age requirement
        if (userData.age < 18) {
            return ResultHelper.failure('User must be at least 18 years old');
        }

        return ResultHelper.success(undefined);
    }
}
```

=== DATABASE PATTERNS ===

Connection Management:
```typescript
export interface Database {
    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
    queryOne<T>(sql: string, params?: unknown[]): Promise<T | null>;
    transaction<T>(callback: (tx: Database) => Promise<T>): Promise<T>;
}

export class PostgresDatabase implements Database {
    constructor(private pool: Pool) {}

    async query<T>(sql: string, params: unknown[] = []): Promise<T[]> {
        try {
            const result = await this.pool.query(sql, params);
            return result.rows;
        } catch (error) {
            throw new DatabaseError('Query failed', error as Error);
        }
    }

    async transaction<T>(callback: (tx: Database) => Promise<T>): Promise<T> {
        const client = await this.pool.connect();
        try {
            await client.query('BEGIN');
            const tx = new PostgresTransaction(client);
            const result = await callback(tx);
            await client.query('COMMIT');
            return result;
        } catch (error) {
            await client.query('ROLLBACK');
            throw error;
        } finally {
            client.release();
        }
    }
}
```

Query Builder Pattern:
```typescript
export class QueryBuilder {
    private selectClause = '';
    private fromClause = '';
    private whereConditions: string[] = [];
    private params: unknown[] = [];

    select(columns: string): QueryBuilder {
        this.selectClause = `SELECT ${columns}`;
        return this;
    }

    from(table: string): QueryBuilder {
        this.fromClause = `FROM ${table}`;
        return this;
    }

    where(condition: string, value: unknown): QueryBuilder {
        this.whereConditions.push(`${condition} = $${this.params.length + 1}`);
        this.params.push(value);
        return this;
    }

    build(): { sql: string; params: unknown[] } {
        const whereClause = this.whereConditions.length > 0
            ? `WHERE ${this.whereConditions.join(' AND ')}`
            : '';

        const sql = [this.selectClause, this.fromClause, whereClause]
            .filter(clause => clause)
            .join(' ');

        return { sql, params: this.params };
    }
}
```

=== CACHING PATTERNS ===

In-Memory Cache:
```typescript
export interface CacheProvider {
    get<T>(key: string): Promise<T | null>;
    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
    delete(key: string): Promise<void>;
    clear(): Promise<void>;
}

export class MemoryCacheProvider implements CacheProvider {
    private cache = new Map<string, { value: unknown; expires: number }>();

    async get<T>(key: string): Promise<T | null> {
        const item = this.cache.get(key);

        if (!item || Date.now() > item.expires) {
            this.cache.delete(key);
            return null;
        }

        return item.value as T;
    }

    async set<T>(key: string, value: T, ttlSeconds = 300): Promise<void> {
        const expires = Date.now() + (ttlSeconds * 1000);
        this.cache.set(key, { value, expires });
    }
}

// Cached provider wrapper
export class CachedUserProvider implements UserProvider {
    constructor(
        private userProvider: UserProvider,
        private cache: CacheProvider
    ) {}

    async getUserById(id: string): Promise<User | null> {
        const cacheKey = `user:${id}`;
        const cached = await this.cache.get<User>(cacheKey);

        if (cached) {
            return cached;
        }

        const user = await this.userProvider.getUserById(id);

        if (user) {
            await this.cache.set(cacheKey, user, 300); // 5 minutes
        }

        return user;
    }
}
```

=== AUTHENTICATION PATTERNS ===

JWT Token Handling:
```typescript
import jwt from 'jsonwebtoken';

export interface TokenPayload {
    userId: string;
    email: string;
    role: string;
}

export class TokenService {
    constructor(private secretKey: string) {}

    generateToken(payload: TokenPayload): string {
        return jwt.sign(payload, this.secretKey, { expiresIn: '24h' });
    }

    verifyToken(token: string): Result<TokenPayload> {
        try {
            const payload = jwt.verify(token, this.secretKey) as TokenPayload;
            return ResultHelper.success(payload);
        } catch (error) {
            return ResultHelper.failure('Invalid token');
        }
    }
}
```

Role-Based Access Control:
```typescript
export enum UserRole {
    Admin = 'admin',
    User = 'user',
    Guest = 'guest'
}

export class AuthorizationService {
    private static roleHierarchy = {
        [UserRole.Admin]: [UserRole.Admin, UserRole.User, UserRole.Guest],
        [UserRole.User]: [UserRole.User, UserRole.Guest],
        [UserRole.Guest]: [UserRole.Guest]
    };

    static hasRole(userRole: UserRole, requiredRole: UserRole): boolean {
        return this.roleHierarchy[userRole].includes(requiredRole);
    }
}
```

=== API RESPONSE PATTERNS ===

Standardized API Responses:
```typescript
export interface ApiResponse<T> {
    success: boolean;
    data?: T;
    error?: string;
    meta?: {
        timestamp: string;
        requestId: string;
    };
}

export class ResponseBuilder {
    static success<T>(data: T, requestId: string): ApiResponse<T> {
        return {
            success: true,
            data,
            meta: {
                timestamp: new Date().toISOString(),
                requestId
            }
        };
    }

    static error(error: string, requestId: string): ApiResponse<never> {
        return {
            success: false,
            error,
            meta: {
                timestamp: new Date().toISOString(),
                requestId
            }
        };
    }
}
```

=== LOGGING PATTERNS ===

Structured Logging:
```typescript
export enum LogLevel {
    Debug = 'debug',
    Info = 'info',
    Warn = 'warn',
    Error = 'error'
}

export interface Logger {
    debug(message: string, context?: Record<string, unknown>): void;
    info(message: string, context?: Record<string, unknown>): void;
    warn(message: string, context?: Record<string, unknown>): void;
    error(message: string, error?: Error, context?: Record<string, unknown>): void;
}

export class ConsoleLogger implements Logger {
    constructor(private minLevel: LogLevel = LogLevel.Info) {}

    debug(message: string, context?: Record<string, unknown>): void {
        this.log(LogLevel.Debug, message, context);
    }

    info(message: string, context?: Record<string, unknown>): void {
        this.log(LogLevel.Info, message, context);
    }

    private log(
        level: LogLevel,
        message: string,
        context?: Record<string, unknown>,
        error?: Error
    ): void {
        const entry = {
            level,
            message,
            timestamp: new Date().toISOString(),
            context,
            error
        };

        console.log(JSON.stringify(entry));
    }
}
```

=== CONFIGURATION PATTERNS ===

Environment Configuration:
```typescript
export interface AppConfig {
    port: number;
    database: {
        url: string;
        maxConnections: number;
    };
    jwt: {
        secret: string;
        expiresIn: string;
    };
}

export class ConfigService {
    static load(): AppConfig {
        return {
            port: parseInt(process.env.PORT || '3000'),
            database: {
                url: this.requireEnv('DATABASE_URL'),
                maxConnections: parseInt(process.env.DB_MAX_CONNECTIONS || '10')
            },
            jwt: {
                secret: this.requireEnv('JWT_SECRET'),
                expiresIn: process.env.JWT_EXPIRES_IN || '24h'
            }
        };
    }

    private static requireEnv(key: string): string {
        const value = process.env[key];
        if (!value) {
            throw new Error(`Required environment variable ${key} is not set`);
        }
        return value;
    }
}
```

=== TESTING PATTERNS ===

Mock Factories:
```typescript
export class UserFactory {
    static create(overrides: Partial<User> = {}): User {
        return {
            id: '1',
            email: 'test@example.com',
            name: 'Test User',
            createdAt: new Date(),
            ...overrides
        };
    }

    static createMany(count: number, overrides: Partial<User> = {}): User[] {
        return Array.from({ length: count }, (_, i) =>
            this.create({ id: (i + 1).toString(), ...overrides })
        );
    }
}

export class MockUserProvider implements UserProvider {
    private users: User[] = [];

    async getUserById(id: string): Promise<User | null> {
        return this.users.find(user => user.id === id) || null;
    }

    async createUser(userData: CreateUserData): Promise<User> {
        const user = UserFactory.create({
            id: (this.users.length + 1).toString(),
            ...userData
        });
        this.users.push(user);
        return user;
    }

    // Test helpers
    addUser(user: User): void {
        this.users.push(user);
    }

    clear(): void {
        this.users = [];
    }
}
```