Repository API

创建仓库

使用工厂函数

import { createRepository } from '@esengine/database'

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

// 启用软删除
const playerRepo = createRepository<Player>(mongo, 'players', true)

继承 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)  // 第三个参数：启用软删除
    }

    // 添加自定义方法
    async findTopPlayers(limit: number): Promise<Player[]> {
        return this.findMany({
            sort: { score: 'desc' },
            limit
        })
    }
}

BaseEntity 接口

所有实体必须继承 BaseEntity：

interface BaseEntity {
    id: string
    createdAt: Date
    updatedAt: Date
    deletedAt?: Date  // 软删除时使用
}

查询方法

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

// 简单查询
const players = await repo.findMany({
    where: { rank: 'gold' }
})

// 复杂查询
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)       // 总数量
console.log(result.totalPages)  // 总页数
console.log(result.hasNext)     // 是否有下一页
console.log(result.hasPrev)     // 是否有上一页

count

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

exists

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

创建方法

create

const player = await repo.create({
    name: 'John',
    score: 0
})
// 自动生成 id, createdAt, updatedAt

createMany

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

更新方法

update

const updated = await repo.update('player-123', {
    score: 200,
    rank: 'gold'
})
// 自动更新 updatedAt

删除方法

delete

// 普通删除
await repo.delete('player-123')

// 软删除（如果启用）
// 实际是设置 deletedAt 字段

deleteMany

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

软删除

启用软删除

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

查询行为

// 默认排除软删除记录
const players = await repo.findMany()

// 包含软删除记录
const allPlayers = await repo.findMany({
    includeSoftDeleted: true
})

恢复记录

await repo.restore('player-123')

QueryOptions

interface QueryOptions<T> {
    /** 查询条件 */
    where?: WhereCondition<T>

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

    /** 限制数量 */
    limit?: number

    /** 偏移量 */
    offset?: number

    /** 包含软删除记录（仅在启用软删除时有效） */
    includeSoftDeleted?: boolean
}

PaginatedResult

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