Repository API

Complete reference for the Repository class methods

find()

find(): QueryBuilder<T>

Creates a new QueryBuilder instance for the repository's table. Automatically excludes soft-deleted records.

const users = await userRepository
  .find()
  .where("isActive = ?", true)
  .orderBy("createdAt DESC")
  .limit(10)
  .execute(client);

findOne()

async findOne(
  id: number | string,
  options?: { relations?: string[] },
  _client?: DBClient
): Promise<T | null>

Finds a single record by its primary key.

const user = await userRepository.findOne(1);

// With relations
const userWithPosts = await userRepository.findOne(1, {
  relations: ["posts"]
});

create()

async create(
  entity: Partial<T>,
  options?: { relations?: string[] }
): Promise<T>

Creates a new record. Runs beforeCreate, beforeSave, afterCreate, and afterSave hooks. Automatically manages timestamps.

const newUser = await userRepository.create({
  email: "john@example.com",
  name: "John Doe",
});

bulkCreate()

async bulkCreate(
  entities: Partial<T>[],
  options?: { relations?: string[]; batchSize?: number }
): Promise<T[]>

Creates multiple records in batches.

const users = await userRepository.bulkCreate([
  { name: "Alice", email: "alice@example.com" },
  { name: "Bob", email: "bob@example.com" },
], { batchSize: 1000 });

update()

async update(
  id: number | string,
  entity: Partial<T>
): Promise<T>

Updates a record by ID. Runs beforeUpdate, beforeSave, afterUpdate, and afterSave hooks.

const updated = await userRepository.update(1, {
  name: "John Smith",
});

bulkUpdate()

async bulkUpdate(
  updates: {
    where: { condition: string; params: any[] };
    set: Partial<T>;
  }[],
  options?: { batchSize?: number }
): Promise<void>

Updates multiple records based on different conditions.

await userRepository.bulkUpdate([
  {
    where: { condition: "id = ?", params: [1] },
    set: { status: "inactive" }
  },
  {
    where: { condition: "id = ?", params: [2] },
    set: { status: "inactive" }
  },
]);

upsert()

async upsert(
  entity: Partial<T>,
  keys: string[]
): Promise<T>

Performs an "update or insert" operation based on unique keys.

const user = await userRepository.upsert(
  { email: "john@example.com", name: "John" },
  ["email"]
);

delete()

async delete(id: number | string): Promise<void>

Deletes a record by ID. Performs soft delete if enabled. Runs beforeDelete and afterDelete hooks.

await userRepository.delete(1);

bulkDelete()

async bulkDelete(
  ids: (number | string)[],
  options?: { batchSize?: number }
): Promise<void>

Deletes multiple records by their IDs in batches.

await userRepository.bulkDelete([1, 2, 3], { batchSize: 1000 });

recover()

async recover(id: number | string): Promise<T>

Recovers a soft-deleted record. Only works if soft delete is enabled.

const recovered = await userRepository.recover(1);

asOf()

async asOf(
  id: number | string,
  asOfDate: Date
): Promise<T | null>

Time-travel query: get record as it was at a specific point in time. Only works if versioning is enabled.

const pastUser = await userRepository.asOf(
  1,
  new Date("2025-01-01")
);

history()

async history(id: number | string): Promise<T[]>

Get all historical versions of a record. Only works if versioning is enabled.

const versions = await userRepository.history(1);
console.log(`Found ${versions.length} versions`);

rollback()

async rollback(
  id: number | string,
  version: number
): Promise<T>

Rollback a record to a previous version. Only works if versioning is enabled.

const restored = await userRepository.rollback(1, 2);

scope()

scope(name: string, ...args: any[]): QueryBuilder<T>

Applies a custom scope to the query.

const activeUsers = await userRepository
  .scope("active")
  .execute(client);

rawQuery()

async rawQuery<T>(
  query: string,
  params?: any[]
): Promise<T[]>

Executes a raw SQL query. Use with caution as it bypasses ORM abstractions.

const results = await userRepository.rawQuery(
  "SELECT * FROM users WHERE status = ?",
  ["active"]
);