Services

Services in Orionjs encapsulate business logic, following the dependency injection pattern to make your code more modular, testable, and maintainable. They separate business logic from data access and controllers.

Structure and Naming

Use @Service() decorator from @orion-js/services
Each service should focus on a single business operation
Follow verb-noun naming convention: {Action}{Entity}Service (e.g., SendEmailService, CreatePostService, CallWebhookService)
Service should typically have one main public method named like the action (e.g., execute, send, create)
Put services in app/{component}/services/{Action}{Entity}/index.ts

Best Practices

Single Responsibility: One service should do only one thing
Meaningful Business Logic: Services should contain meaningful business logic, not just pass-through to repositories
Don’t Over-Abstract: Don’t create services for simple repository interactions - call repositories directly from controllers or other services
Keep Methods Short: Divide logic into private methods within the same service
Use repositories for database operations
Use dependency injection with @Inject(() => ServiceName)
Add proper typing for all parameters and return values
Handle validation and error cases appropriately
Prefer throwing ValidationError when validation of data fails
Prefer throwing UserError when the error is not a system error

Basic Example

Here’s an example of a service that implements a single business operation with meaningful business logic:

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

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

  @Inject(() => NotificationsRepo)
  private notificationsRepo: NotificationsRepo

  async execute(data: Omit<Card, '_id'>, userId: string) {
    // Business logic validation
    if (data.name.toLowerCase().includes('invalid')) {
      throw new BadRequestError('invalidCardName')
    }

    // Apply business rules
    const enrichedData = {
      ...data,
      createdBy: userId,
      status: this.determineInitialStatus(data),
      priority: this.calculatePriority(data),
      createdAt: new Date()
    }

    // Use repository for data access
    const card = await this.cardsRepo.createCard(enrichedData)

    // Additional business logic after creation
    await this.notificationsRepo.createNotification({
      type: 'card_created',
      entityId: card._id,
      userId,
      message: `Card "${card.name}" was created`
    })

    return {
      ...card,
      isNew: true,
      canEdit: true
    }
  }

  private determineInitialStatus(data: Omit<Card, '_id'>) {
    if (data.dueDate && new Date(data.dueDate) < new Date()) {
      return 'urgent'
    }
    return 'draft'
  }

  private calculatePriority(data: Omit<Card, '_id'>) {
    let priority = 0

    if (data.tags?.includes('important')) {
      priority += 10
    }

    if (data.dueDate) {
      const daysUntilDue = Math.floor(
        (new Date(data.dueDate).getTime() - new Date().getTime()) / (1000 * 60 * 60 * 24)
      )
      if (daysUntilDue < 3) {
        priority += 20
      } else if (daysUntilDue < 7) {
        priority += 10
      }
    }

    return priority
  }
}

Complex Service Example

A more complex example showing a service that orchestrates multiple operations:

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

  @Inject(() => PaymentGatewayService)
  private paymentGatewayService: PaymentGatewayService

  @Inject(() => EmailService)
  private emailService: EmailService

  async execute(cardId: CardId, paymentDetails: PaymentDetails) {
    // Get data directly from repository - no need for a dedicated service
    const card = await this.cardsRepo.getCardById(cardId)

    if (!card) {
      throw new BadRequestError('cardNotFound')
    }

    if (card.status === 'paid') {
      throw new BadRequestError('cardAlreadyPaid')
    }

    // Process payment through payment gateway
    const paymentResult = await this.paymentGatewayService.processPayment({
      amount: card.amount,
      currency: card.currency,
      ...paymentDetails
    })

    if (paymentResult.status === 'success') {
      await this.handleSuccessfulPayment(card, paymentResult, paymentDetails)

      return {
        success: true,
        paymentId: paymentResult.paymentId,
        receiptUrl: paymentResult.receiptUrl
      }
    } else {
      throw new BadRequestError('paymentFailed', {
        reason: paymentResult.reason
      })
    }
  }

  private async handleSuccessfulPayment(card: Card, paymentResult: PaymentResult, paymentDetails: PaymentDetails) {
    await this.cardsRepo.updateCard(card._id, {
      status: 'paid',
      paymentId: paymentResult.paymentId,
      paidAt: new Date()
    })

    await this.emailService.sendEmail({
      to: paymentDetails.email,
      subject: 'Payment Confirmation',
      template: 'payment-confirmation',
      data: {
        cardName: card.name,
        amount: card.amount,
        currency: card.currency,
        paymentId: paymentResult.paymentId
      }
    })
  }
}

Dependency Injection

Services can be injected into other services or controllers. Always use the factory function pattern:

import {Service, Inject} from '@orion-js/services'

@Service()
export class AuthenticateUserService {
  @Inject(() => UsersRepo)
  private usersRepo: UsersRepo

  @Inject(() => GenerateAuthTokenService)
  private tokenService: GenerateAuthTokenService

  @Inject(() => SecurityService)
  private securityService: SecurityService

  async execute(email: string, password: string) {
    const user = await this.usersRepo.findByEmail(email)

    if (!user) {
      throw new BadRequestError('userNotFound')
    }

    const isPasswordValid = await this.securityService.verifyPassword({
      inputPassword: password,
      storedHash: user.password,
      salt: user.salt
    })

    if (!isPasswordValid) {
      await this.usersRepo.incrementFailedLoginAttempts(user._id)
      throw new BadRequestError('invalidPassword')
    }

    if (user.failedLoginAttempts > 0) {
      await this.usersRepo.resetFailedLoginAttempts(user._id)
    }

    return this.tokenService.execute({
      userId: user._id,
      roles: user.roles,
      permissions: await this.securityService.calculateEffectivePermissions(user)
    })
  }
}

The factory function pattern @Inject(() => ServiceName) automatically handles circular dependencies.

Getting Service Instances

You can get service instances from anywhere in your application:

import {getInstance} from '@orion-js/services'
import {CreateCardService} from './CreateCardService'

const createCardService = getInstance(CreateCardService)
await createCardService.execute(cardData, userId)

Testing

Services are designed to be easily testable with mocks:

import {mockService} from '@orion-js/services'
import {AuthenticateUserService} from './AuthenticateUserService'
import {GenerateAuthTokenService} from './GenerateAuthTokenService'
import {SecurityService} from './SecurityService'
import {UsersRepo} from '../repos/UsersRepo'

describe('AuthenticateUserService', () => {
  it('should authenticate valid users', async () => {
    // Mock the repository directly
    mockService(UsersRepo, {
      findByEmail: async () => ({
        _id: 'usr-123',
        email: 'test@example.com',
        password: 'hashed_password',
        salt: 'salt123',
        failedLoginAttempts: 0,
        roles: ['user']
      }),
      resetFailedLoginAttempts: async () => true
    })

    // Mock services with complex business logic
    mockService(SecurityService, {
      verifyPassword: async () => true,
      calculateEffectivePermissions: async () => ['read:profile', 'edit:profile']
    })

    mockService(GenerateAuthTokenService, {
      execute: async () => ({
        token: 'test-token',
        expiresAt: new Date()
      })
    })

    const authService = new AuthenticateUserService()
    const result = await authService.execute('test@example.com', 'password')

    expect(result.token).toBeDefined()
  })
})

When NOT to Create a Service

Don’t create a service if you’re just:

Calling a single repository method without additional business logic
Passing through data without transformation or validation
Creating a thin wrapper around an external API without business rules

In these cases, call the repository or external service directly from your controller or another service.

Get Started

Essentials

Controllers

Other Modules

Structure and Naming

Best Practices

Basic Example

Complex Service Example

Dependency Injection

Getting Service Instances

Testing

When NOT to Create a Service

​Structure and Naming

​Best Practices

​Basic Example

​Complex Service Example

​Dependency Injection

​Getting Service Instances

​Testing

​When NOT to Create a Service

Structure and Naming

Best Practices

Basic Example

Complex Service Example

Dependency Injection

Getting Service Instances

Testing

When NOT to Create a Service