Repository

The @talosjs/repository component is a thin data access layer. You register a repository class with a decorator, implement the IRepository contract, and resolve it from the container. The contract standardizes how repositories open and close their data source and return paginated, searchable results, so every repository in your app reads and writes the same way no matter what database sits underneath.

What the contract standardizes

IRepository<T, TCriteria> defines open, close, and find, and you implement it the same way for any data source. find is paginated: it returns a FilterResultType<T> carrying resources, total, totalPages, page, and limit, and it accepts an optional q query string alongside your own criteria fields for search. Generics thread your entity type T and criteria type TCriteria through the whole API. Register a repository with a decorator and you can resolve or inject it anywhere, at whichever scope you choose.

How it works

A repository implements the IRepository interface and is registered with @decorator.repository(). The decorator adds the class to the @talosjs/container, so you resolve it instead of constructing it by hand. The contract is intentionally small:

Method	Purpose
`open()`	Open or initialize the data source connection; returns the underlying connection.
`close()`	Close the data source connection.
`find(criteria)`	Return entities matching `criteria` as a paginated `FilterResultType<T>`.

find always merges your own filter fields with three reserved keys:

Field	Default	Purpose
`page`	`1`	Page number for pagination.
`limit`	`10`	Items per page.
`q`	—	Free-text search query.

The result is always shaped the same way:

type FilterResultType<T> = {
  resources: T[];
  total: number;
  totalPages: number;
  page: number;
  limit: number;
};

Decorator and usage

`@decorator.repository(scope?)`

Registers a repository class with the container. It accepts an optional scope (defaults to EContainerScope.Singleton).

Scope	Behavior
`Singleton`	One instance shared across all resolutions (default).
`Transient`	A new instance is created on every resolution.
`Request`	A new instance per request context.

Implement the IRepository<T, TCriteria> contract on your class:

import { decorator, type IRepository } from "@talosjs/repository";
import type { FilterResultType } from "@talosjs/types";

interface User {
  id: string;
  email: string;
  name: string;
}

interface UserCriteria {
  email?: string;
  name?: string;
  isActive?: boolean;
}

@decorator.repository()
class UserRepository implements IRepository<User, UserCriteria> {
  private connection: unknown = null;

  public async open(): Promise<unknown> {
    this.connection = await this.createConnection();
    return this.connection;
  }

  public async close(): Promise<void> {
    this.connection = null;
  }

  public async find(
    criteria: UserCriteria & { page?: number; limit?: number; q?: string },
  ): Promise<FilterResultType<User>> {
    const { page = 1, limit = 10, q, ...filters } = criteria;

    const users = await this.queryUsers(filters, q);
    const total = await this.countUsers(filters, q);

    return {
      resources: users,
      total,
      totalPages: Math.ceil(total / limit),
      page,
      limit,
    };
  }
}

Resolve it from the container and run a paginated, filtered query:

import { container } from "@talosjs/container";

const userRepository = container.get(UserRepository);

await userRepository.open();

const result = await userRepository.find({
  isActive: true,
  page: 1,
  limit: 20,
  q: "john",
});

result.resources; // User[]
result.total; // total matching rows
result.totalPages; // number of pages

await userRepository.close();

Pass a scope when you need a fresh instance per resolution:

import { decorator, type IRepository } from "@talosjs/repository";
import { EContainerScope } from "@talosjs/container";

@decorator.repository(EContainerScope.Transient)
class TransientRepository implements IRepository {
  // each container.get(...) returns a new instance
}

Building dependable repositories

Provide open, close, and find on every repository so callers can treat them all identically. Default page to 1 and limit to a bounded value, and never return an unbounded result set. Compute totalPages with Math.ceil(total / limit) so callers can paginate reliably. Destructure page, limit, and q out of the criteria before building the query, then apply the rest as filter fields. Honor q consistently by applying the same search predicate to both the result query and the count, so the total matches the page. Pull repositories from the container, or inject them, rather than using new, so scope and dependencies wire up correctly. Choose the scope to fit the repository: Singleton for shared, stateless ones, and Transient or Request when each consumer needs isolated state.

CLI command

Scaffold a repository class and its test file with the generator. It writes the class under modules/<module>/src/repositories/<Name>Repository.ts, a spec under modules/<module>/tests/repositories/, and installs @talosjs/repository if it is missing.

# Interactive: prompts for the name
talos repository:create

# Provide the name
talos repository:create --name=User

# Target a module and overwrite
talos repository:create --name=User --module=auth --override

Option	Description	Default
`--name`	Repository class name. The `Repository` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated class is a TypeORM-backed repository with open, close, find (paginated + searchable), and full CRUD methods, ready for you to wire up to your entity:

import { inject } from "@talosjs/container";
import type { ITypeormDatabase } from "@talosjs/database";
import { decorator } from "@talosjs/repository";
import type { FilterResultType } from "@talosjs/types";
import type { FindManyOptions, FindOptionsWhere, Repository, SaveOptions, UpdateResult } from "typeorm";
import { UserEntity } from "../entities/UserEntity";

@decorator.repository()
export class UserRepository {
  constructor(
    @inject("database")
    private readonly database: ITypeormDatabase,
  ) {}

  public async open(): Promise<Repository<UserEntity>> {
    return await this.database.open(UserEntity);
  }

  public async close(): Promise<void> {
    await this.database.close();
  }

  public async find(
    criteria: FindManyOptions<UserEntity> & { page?: number; limit?: number; q?: string },
  ): Promise<FilterResultType<UserEntity>> {
    const repository = await this.open();

    const { page = 1, limit = 100, q, ...rest } = criteria;

    let skip: number | undefined;
    const take = limit === 0 ? 100 : limit;

    if (page && page > 0 && limit && limit > 0) {
      skip = (page - 1) * take;
    }

    let findOptions = { ...rest, take, ...(skip !== undefined && { skip }) };
    if (q) {
      findOptions = {
        ...findOptions,
        where: {
          ...rest.where,
          // name: ILike(`%${q}%`),
        },
      };
    }

    const result = await repository.find(findOptions);

    let countWhere = rest.where;
    if (q) {
      countWhere = {
        ...rest.where,
        // name: ILike(`%${q}%`),
      };
    }

    const total = await this.count(countWhere);
    const totalPages = Math.ceil(total / limit);

    return { resources: result, total, totalPages, page, limit };
  }

  public async findOne(id: string): Promise<UserEntity | null> {
    const repository = await this.open();
    return await repository.findOne({ where: { id } });
  }

  public async findOneBy(criteria: FindOptionsWhere<UserEntity>): Promise<UserEntity | null> {
    const repository = await this.open();
    return await repository.findOne({ where: criteria });
  }

  public async create(entity: UserEntity, options?: SaveOptions): Promise<UserEntity> {
    const repository = await this.open();
    return await repository.save(entity, options);
  }

  public async createMany(entities: UserEntity[], options?: SaveOptions): Promise<UserEntity[]> {
    const repository = await this.open();
    return await repository.save(entities, options);
  }

  public async update(entity: Partial<UserEntity> & { id: string }): Promise<UpdateResult> {
    const repository = await this.open();
    return await repository.update(entity.id, entity);
  }

  public async updateMany(entities: (Partial<UserEntity> & { id: string })[]): Promise<UpdateResult[]> {
    const repository = await this.open();
    return await Promise.all(entities.map((entity) => repository.update(entity.id, entity)));
  }

  public async delete(
    criteria: FindOptionsWhere<UserEntity> | FindOptionsWhere<UserEntity>[],
  ): Promise<UpdateResult> {
    const repository = await this.open();
    return await repository.softDelete(criteria);
  }

  public async count(criteria?: FindOptionsWhere<UserEntity> | FindOptionsWhere<UserEntity>[]): Promise<number> {
    const repository = await this.open();
    return await repository.count(criteria ? { where: criteria } : {});
  }
}

See repository:create for the full command reference.

Use with Claude and Codex

The generator ships a matching repository:create skill. It runs the scaffold, then guides your AI agent through completing the repository: verifying the entity import path, adjusting the find search fields, and trimming or adding CRUD methods to fit the entity. Initialize the skills once for your agent.

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a repository for the User entity.

talos agent:skills:create

Then ask Codex in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a repository for the User entity.

For example, the prompt above maps to repository:create --name=User, then completes the CRUD methods against the User entity.

Getting Started

AI

Framework

Command Line

What the contract standardizes

How it works

Decorator and usage

`@decorator.repository(scope?)`

Building dependable repositories

CLI command

Use with Claude and Codex

​What the contract standardizes

​How it works

​Decorator and usage

​@decorator.repository(scope?)

​Building dependable repositories

​CLI command

​Use with Claude and Codex

What the contract standardizes

How it works

Decorator and usage

`@decorator.repository(scope?)`

Building dependable repositories

CLI command

Use with Claude and Codex