repository-implementation-and-testing-pattern

Implement a standardized repository with soft delete functionality and comprehensive tests to ensure maintainable code and reliable data access patterns in the Packmind codebase.

When to Use

• When creating a new repository for an entity
• When you need to implement data access layer following Packmind patterns
• When writing comprehensive tests for repositories
• When implementing soft delete functionality

Context Validation Checkpoints

• Have you defined the entity and its TypeORM schema?
• Do you know which domain-specific finder methods are needed?
• Have you created a test factory for the entity?
• Is the AbstractRepository base class available in @packmind/shared?

Recipe Steps

Step 1: Define Repository Interface

Create the repository interface extending IRepository from @packmind/shared. Add domain-specific finder methods that will be needed by use cases.

import { Entity } from '../entities/Entity';
import { IRepository, QueryOption } from '@packmind/shared';
import { OrganizationId } from '@packmind/accounts';

export interface IEntityRepository extends IRepository<Entity> {
  findBySlug(slug: string, opts?: QueryOption): Promise<Entity | null>;
  findByOrganizationId(organizationId: OrganizationId): Promise<Entity[]>;
  // Add other domain-specific finder methods
}

Step 2: Implement Repository Class

Create the repository class extending AbstractRepository. Implement the interface with proper logging for all operations. Override loggableEntity to specify which fields should be logged.

import { Entity } from '../../domain/entities/Entity';
import { IEntityRepository } from '../../domain/repositories/IEntityRepository';
import { EntitySchema } from '../schemas/EntitySchema';
import { Repository } from 'typeorm';
import {
  PackmindLogger,
  localDataSource,
  AbstractRepository,
  QueryOption,
} from '@packmind/shared';
import { OrganizationId } from '@packmind/accounts';

const origin = 'EntityRepository';

export class EntityRepository
  extends AbstractRepository<Entity>
  implements IEntityRepository
{
  constructor(
    repository: Repository<Entity> = localDataSource.getRepository<Entity>(EntitySchema),
    logger: PackmindLogger = new PackmindLogger(origin),
  ) {
    super('entity', repository, logger, EntitySchema);
    this.logger.info('EntityRepository initialized');
  }

  protected override loggableEntity(entity: Entity): Partial<Entity> {
    return {
      id: entity.id,
      name: entity.name, // Include key identifying fields only
    };
  }

  async findBySlug(slug: string, opts?: QueryOption): Promise<Entity | null> {
    this.logger.info('Finding entity by slug', { slug });

    try {
      const entity = await this.repository.findOne({
        where: { slug },
        withDeleted: opts?.includeDeleted ?? false,
      });
      
      if (entity) {
        this.logger.info('Entity found by slug', { slug, entityId: entity.id });
      } else {
        this.logger.warn('Entity not found by slug', { slug });
      }
      return entity;
    } catch (error) {
      this.logger.error('Failed to find entity by slug', {
        slug,
        error: error instanceof Error ? error.message : String(error),
      });
      throw error;
    }
  }
}