Repository API

Creating a Repository

Using Factory Function

import { createRepository } from '@esengine/database'

const playerRepo = createRepository<Player>(mongo, 'players')

// Enable soft delete
const playerRepo = createRepository<Player>(mongo, 'players', true)

Extending Repository

import { Repository, BaseEntity } from '@esengine/database'

interface Player extends BaseEntity {
    name: string
    score: number
}

class PlayerRepository extends Repository<Player> {
    constructor(connection: IMongoConnection) {
        super(connection, 'players', false)  // Third param: enable soft delete
    }

    // Add custom methods
    async findTopPlayers(limit: number): Promise<Player[]> {
        return this.findMany({
            sort: { score: 'desc' },
            limit
        })
    }
}

BaseEntity Interface

All entities must extend BaseEntity:

interface BaseEntity {
    id: string
    createdAt: Date
    updatedAt: Date
    deletedAt?: Date  // Used for soft delete
}

Query Methods

findById

const player = await repo.findById('player-123')

findOne

const player = await repo.findOne({
    where: { name: 'John' }
})

const topPlayer = await repo.findOne({
    sort: { score: 'desc' }
})

findMany

// Simple query
const players = await repo.findMany({
    where: { rank: 'gold' }
})

// Complex query
const players = await repo.findMany({
    where: {
        score: { $gte: 100 },
        rank: { $in: ['gold', 'platinum'] }
    },
    sort: { score: 'desc', name: 'asc' },
    limit: 10,
    offset: 0
})

findPaginated

const result = await repo.findPaginated(
    { page: 1, pageSize: 20 },
    {
        where: { rank: 'gold' },
        sort: { score: 'desc' }
    }
)

console.log(result.data)        // Player[]
console.log(result.total)       // Total count
console.log(result.totalPages)  // Total pages
console.log(result.hasNext)     // Has next page
console.log(result.hasPrev)     // Has previous page

count

const count = await repo.count({
    where: { rank: 'gold' }
})

exists

const exists = await repo.exists({
    where: { email: 'john@example.com' }
})

Create Methods

create

const player = await repo.create({
    name: 'John',
    score: 0
})
// Automatically generates id, createdAt, updatedAt

createMany

const players = await repo.createMany([
    { name: 'Alice', score: 100 },
    { name: 'Bob', score: 200 },
    { name: 'Carol', score: 150 }
])

Update Methods

update

const updated = await repo.update('player-123', {
    score: 200,
    rank: 'gold'
})
// Automatically updates updatedAt

Delete Methods

delete

// Hard delete
await repo.delete('player-123')

// Soft delete (if enabled)
// Actually sets the deletedAt field

deleteMany

const count = await repo.deleteMany({
    where: { score: { $lt: 10 } }
})

Soft Delete

Enabling Soft Delete

const repo = createRepository<Player>(mongo, 'players', true)

Query Behavior

// Excludes soft-deleted records by default
const players = await repo.findMany()

// Include soft-deleted records
const allPlayers = await repo.findMany({
    includeSoftDeleted: true
})

Restore Records

await repo.restore('player-123')

QueryOptions

interface QueryOptions<T> {
    /** Query conditions */
    where?: WhereCondition<T>

    /** Sorting */
    sort?: Partial<Record<keyof T, 'asc' | 'desc'>>

    /** Limit count */
    limit?: number

    /** Offset */
    offset?: number

    /** Include soft-deleted records (only when soft delete is enabled) */
    includeSoftDeleted?: boolean
}

PaginatedResult

interface PaginatedResult<T> {
    data: T[]
    total: number
    page: number
    pageSize: number
    totalPages: number
    hasNext: boolean
    hasPrev: boolean
}