Repositories

Repositories in Orionjs handle data access operations, separating data access logic from business logic. They should focus exclusively on database interactions.

Structure and Naming

Use @Repository() decorator from @orion-js/mongodb
Each repository should manage a single entity type
Follow naming convention: {EntityNameInPlural}Repo (e.g., UsersRepo, CardsRepo)
Put repositories in app/{component}/repos/{EntityNameInPlural}Repo/index.ts
Collection name should be {component_name}.{plural_of_entity} (e.g., gaming.pokemon_cards)

Best Practices

Keep methods simple and focused on a single responsibility
Never access the collection directly outside the repository. All database interactions must go through repository methods. The only exception is during migrations.
Return plain objects or domain models, not database-specific structures
Use descriptive method names: findById, findByEmail, create{EntityName}, update{EntityName}, delete{EntityName}
Avoid business logic in repositories (use services instead)
Add proper typing for all parameters and return values
Always use typedId() in schema definitions for document IDs
Use InferSchemaType to derive types from schemas

Naming Convention: get vs load

Use the load prefix instead of get for methods where data freshness is not guaranteed: Use load prefix when the method:

Uses secondaryPreferred read preference (eventually consistent reads from replica secondaries)
Uses DataLoader methods like loadById, loadMany (batched/deduplicated reads within request scope)
Reads from cache (in-memory, Redis, or any caching layer)

Use get prefix when the method:

Reads directly from primary with no caching
Requires guaranteed data freshness (read-after-write scenarios)

Examples:

getCardsListCursor → loadCardsListCursor (uses secondaryPreferred)
getCardById → loadCardById (if using DataLoader or cache)
findById stays as is (direct primary read)

Read Preferences for Non-Critical Queries

For queries that don’t require strong consistency, use the readPreference: 'secondaryPreferred' option to distribute read load across MongoDB replica set secondaries. This is especially important for:

Aggregations: Heavy aggregation pipelines
List queries: Paginated lists or search results
Reports and analytics: Read-heavy operations for dashboards
Count operations: Document counts for UI display

When NOT to use secondaryPreferred:

When reading data immediately after a write (use primary for read-after-write consistency)
For critical operations where stale data could cause issues
When the query result will be used to make a write decision

Complete Example

import {createCollection, MongoFilter, Repository, OptionalId, MongoDB} from '@orion-js/mongodb'
import {InferSchemaType, schemaWithName, typedId} from '@orion-js/schema'

// Define the schema with typedId
export const typedCardId = typedId('crd')
export type CardId = typeof typedCardId.__tsFieldType

export const CardSchema = schemaWithName('Card', {
  _id: {type: typedCardId},
  name: {type: String},
  status: {type: String, optional: true},
  createdAt: {type: Date}
})

export type Card = InferSchemaType<typeof CardSchema>

// Define query params schema
export const CardsListQueryParamsSchema = schemaWithName('CardsListQueryParams', {
  filter: {type: String, optional: true},
})

export type CardsListQueryParamsType = InferSchemaType<typeof CardsListQueryParamsSchema>

@Repository()
export class CardsRepo {
  // Collection is public only to allow access during migrations.
  // Never access this collection directly outside this repository.
  collection = createCollection({
    name: 'gaming.pokemon_cards',
    schema: CardSchema,
    indexes: [],
  })

  async createCard(doc: OptionalId<Card>) {
    return await this.collection.insertAndFind(doc)
  }

  // "get" prefix: direct read from primary, guaranteed fresh data
  async getCardById(docId: CardId) {
    return await this.collection.findOne(docId)
  }

  // "load" prefix: uses DataLoader (batched/deduplicated, may return cached data within request)
  async loadCardById(docId: CardId) {
    return await this.collection.loadById(docId)
  }

  async updateCard(docId: CardId, doc: MongoDB.UpdateFilter<Card>['$set']) {
    return await this.collection.updateAndFind(docId, {$set: doc})
  }

  async deleteCard(docId: CardId) {
    await this.collection.updateOne(docId, {$set: {deletedAt: new Date()}})
  }

  private async getCardsListQuery(params: CardsListQueryParamsType) {
    const queries: MongoFilter<Card>[] = []

    if (params.filter) {
      queries.push({name: {$regex: params.filter, $options: 'i'}})
    }

    return queries.length ? {$and: queries} : {}
  }

  // "load" prefix: uses secondaryPreferred (data may be slightly stale)
  async loadCardsListCursor(params: CardsListQueryParamsType) {
    const query = await this.getCardsListQuery(params)
    return this.collection.find(query, {readPreference: 'secondaryPreferred'})
  }

  // "load" prefix: uses secondaryPreferred
  async loadCardsListCount(params: CardsListQueryParamsType) {
    const query = await this.getCardsListQuery(params)
    return this.collection.countDocuments(query, {readPreference: 'secondaryPreferred'})
  }

  // "load" prefix: aggregation on secondary
  async loadCardsStats() {
    return this.collection.aggregate([
      {$group: {_id: '$status', count: {$sum: 1}}}
    ], {readPreference: 'secondaryPreferred'})
  }
}

Integration with Services

Services should inject repositories for data access:

import {Service, Inject} from '@orion-js/services'
import {CardsRepo} from '../repos/CardsRepo'
import {CardId} from '../schemas/Card'

@Service()
export class GetCardDetailsService {
  @Inject(() => CardsRepo)
  private cardsRepo: CardsRepo

  async execute(cardId: CardId) {
    const card = await this.cardsRepo.getCardById(cardId)
    // Process card data with business logic
    return processedCardData
  }
}

Why Use Repositories?

While repositories are functionally similar to services (both use dependency injection), they serve different purposes:

Services handle business logic, orchestration, and use cases
Repositories focus exclusively on data access and persistence

This separation of concerns leads to:

Cleaner code organization
Easier testing
Better maintainability
Clearer dependencies

Get Started

Essentials

Controllers

Other Modules

Structure and Naming

Best Practices

Naming Convention: get vs load

Read Preferences for Non-Critical Queries

Complete Example

Integration with Services

Why Use Repositories?

​Structure and Naming

​Best Practices

​Naming Convention: get vs load

​Read Preferences for Non-Critical Queries

​Complete Example

​Integration with Services

​Why Use Repositories?

Structure and Naming

Best Practices

Naming Convention: get vs load

Read Preferences for Non-Critical Queries

Complete Example

Integration with Services

Why Use Repositories?