// Instead of this performance trap:
const users = await userRepo.findAll();
for (const user of users) {
  console.log(user.posts); // Hidden N+1 query
}

// You get explicit, predictable queries:
const users = await userRepo.findAll({
  include: { posts: true }
});

// Raw ORM classes never escape your data layer:
interface UserDTO {
  id: string;
  email: string;
  lastLoginAt: Date | null;
}

// Your services work with clean, domain-focused types
async function getUserProfile(id: string): Promise<UserDTO> {
  return userRepo.findById(id);
}

// Transform cryptic ORM errors into actionable domain errors:
try {
  await userRepo.create(userData);
} catch (error) {
  if (isPrismaError(error, 'P2002')) {
    throw new UniqueConstraintError('Email already exists');
  }
  throw new DataLayerError('Failed to create user', { cause: error });
}

// This innocent-looking code creates a performance disaster:
app.get('/api/users', async (req, res) => {
  const users = await db.user.findMany();
  const enriched = await Promise.all(
    users.map(async (user) => ({
      ...user,
      postCount: await db.post.count({ where: { userId: user.id } }),
      lastPost: await db.post.findFirst({ 
        where: { userId: user.id },
        orderBy: { createdAt: 'desc' }
      })
    }))
  );
  res.json(enriched);
});

// Clean, predictable, and fast:
app.get('/api/users', async (req, res) => {
  const users = await userRepo.findAllWithStats();
  res.json(users);
});

// In your repository:
async findAllWithStats(): Promise<UserWithStatsDTO[]> {
  return this.db.user.findMany({
    select: {
      id: true,
      email: true,
      name: true,
      _count: { select: { posts: true } },
      posts: {
        take: 1,
        orderBy: { createdAt: 'desc' },
        select: { id: true, title: true, createdAt: true }
      }
    }
  });
}

// Strict forward-only migrations with semantic versioning:
// V2_3_0__JIRA-1234_add_user_status.sql

// Every migration includes:
// 1. Semantic version prefix
// 2. Ticket reference
// 3. Descriptive name
// 4. SQL linting in CI
// 5. Rollback strategy documentation

// Fast unit tests with mocked ORM:
describe('UserService', () => {
  it('should create user with valid email', async () => {
    const mockRepo = {
      create: jest.fn().mockResolvedValue(mockUser),
      findByEmail: jest.fn().mockResolvedValue(null)
    };
    
    const service = new UserService(mockRepo);
    const result = await service.createUser(validUserData);
    
    expect(result.email).toBe(validUserData.email);
  });
});

// Rock-solid integration tests:
describe('UserRepo Integration', () => {
  beforeEach(async () => {
    await testDb.migrate.latest();
    await testDb.raw('TRUNCATE users CASCADE');
  });
  
  it('should enforce unique email constraint', async () => {
    await userRepo.create({ email: '[email protected]' });
    
    await expect(
      userRepo.create({ email: '[email protected]' })
    ).rejects.toThrow(UniqueConstraintError);
  });
});

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "skipLibCheck": true
  }
}

// src/modules/user/user.entity.ts
export interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

// src/modules/user/user.repo.ts
export class UserRepo {
  constructor(private readonly db: PrismaClient) {}
  
  async findByEmail(email: string): Promise<User | null> {
    if (!email) throw new InvalidInputError('Email is required');
    
    return this.db.user.findUnique({
      where: { email },
      select: userSelect
    });
  }
  
  async create(userData: CreateUserData): Promise<User> {
    try {
      return await this.db.user.create({
        data: userData,
        select: userSelect
      });
    } catch (error) {
      if (isPrismaError(error, 'P2002')) {
        throw new UniqueConstraintError('Email already exists');
      }
      throw new DataLayerError('Failed to create user', { cause: error });
    }
  }
}

const userSelect = {
  id: true,
  email: true,
  name: true,
  createdAt: true
} as const;

// src/errors/data-layer.error.ts
export class DataLayerError extends Error {
  constructor(
    message: string,
    public readonly context: Record<string, unknown> = {}
  ) {
    super(message);
    this.name = 'DataLayerError';
  }
}

export class UniqueConstraintError extends DataLayerError {
  constructor(message: string) {
    super(message);
    this.name = 'UniqueConstraintError';
  }
}

// src/utils/prisma-errors.ts
export function isPrismaError(error: unknown, code: string): boolean {
  return error instanceof Error && 
         'code' in error && 
         error.code === code;
}

// src/middleware/query-logger.ts
export function createQueryLogger(db: PrismaClient) {
  db.$use(async (params, next) => {
    const start = Date.now();
    const result = await next(params);
    const duration = Date.now() - start;
    
    if (duration > 200) {
      logger.warn('Slow query detected', {
        model: params.model,
        action: params.action,
        duration,
        // Never log actual parameters in production
        paramCount: Object.keys(params.args || {}).length
      });
    }
    
    return result;
  });
}

// tests/setup.ts
import { PrismaClient } from '@prisma/client';

export let testDb: PrismaClient;

beforeAll(async () => {
  testDb = new PrismaClient({
    datasources: {
      db: { url: process.env.TEST_DATABASE_URL }
    }
  });
  
  await testDb.$connect();
  await testDb.$executeRawUnsafe('TRUNCATE TABLE users CASCADE');
});

afterAll(async () => {
  await testDb.$disconnect();
});