Error Handling

import { CodedError } from '@cosmneo/onion-lasagna/backend/core/global';

abstract class CodedError extends Error {
  public readonly code: string;

  constructor(options: {
    message: string;
    code: string;
    cause?: unknown;
  });

  static fromError(cause: unknown): CodedError;
}

CodedError (base)
├── DomainError
│   ├── InvariantViolationError
│   └── PartialLoadError
├── UseCaseError
│   ├── NotFoundError
│   ├── ConflictError
│   └── UnprocessableError
├── InfraError
│   ├── DbError
│   ├── NetworkError
│   ├── TimeoutError
│   └── ExternalServiceError
├── ControllerError
├── AccessDeniedError
├── InvalidRequestError
└── ObjectValidationError

import { ErrorCodes } from '@cosmneo/onion-lasagna/backend/core/global';

// Domain errors
ErrorCodes.Domain.DOMAIN_ERROR           // 'DOMAIN_ERROR'
ErrorCodes.Domain.INVARIANT_VIOLATION    // 'INVARIANT_VIOLATION'
ErrorCodes.Domain.PARTIAL_LOAD           // 'PARTIAL_LOAD'

// Use case errors
ErrorCodes.App.USE_CASE_ERROR            // 'USE_CASE_ERROR'
ErrorCodes.App.NOT_FOUND                 // 'NOT_FOUND'
ErrorCodes.App.CONFLICT                  // 'CONFLICT'
ErrorCodes.App.UNPROCESSABLE             // 'UNPROCESSABLE'

// Infrastructure errors
ErrorCodes.Infra.INFRA_ERROR             // 'INFRA_ERROR'
ErrorCodes.Infra.DB_ERROR                // 'DB_ERROR'
ErrorCodes.Infra.NETWORK_ERROR           // 'NETWORK_ERROR'
ErrorCodes.Infra.TIMEOUT_ERROR           // 'TIMEOUT_ERROR'
ErrorCodes.Infra.EXTERNAL_SERVICE_ERROR  // 'EXTERNAL_SERVICE_ERROR'

// Presentation errors
ErrorCodes.Presentation.CONTROLLER_ERROR // 'CONTROLLER_ERROR'
ErrorCodes.Presentation.ACCESS_DENIED    // 'ACCESS_DENIED'
ErrorCodes.Presentation.INVALID_REQUEST  // 'INVALID_REQUEST'

// Global errors
ErrorCodes.Global.OBJECT_VALIDATION_ERROR // 'OBJECT_VALIDATION_ERROR'

import { InvariantViolationError } from '@cosmneo/onion-lasagna/backend/core/onion-layers';

class Order {
  addItem(item: OrderItem): void {
    if (this.status !== 'draft') {
      throw new InvariantViolationError({
        message: 'Cannot add items to a submitted order',
        code: 'ORDER_NOT_DRAFT', // Custom code
      });
    }
    // ...
  }
}

import { PartialLoadError } from '@cosmneo/onion-lasagna/backend/core/onion-layers';

class OrderAggregate extends BaseAggregateRoot<OrderId, OrderProps> {
  get items(): readonly OrderItem[] {
    // Throws PartialLoadError if 'items' wasn't marked as loaded
    return this.requireLoaded('items');
  }
}

// In use case - handle partial load errors
class GetOrderItemsQuery extends BaseInboundAdapter<...> {
  protected async handle(input: GetOrderItemsInput): Promise<OrderItemsOutput> {
    const order = await this.orderRepo.findById(input.orderId);
    if (!order) {
      throw new NotFoundError({ message: 'Order not found' });
    }

    try {
      return { items: order.items };
    } catch (error) {
      if (error instanceof PartialLoadError) {
        // Re-fetch with items included
        const orderWithItems = await this.orderRepo.findById(
          input.orderId,
          { includeItems: true },
        );
        return { items: orderWithItems!.items };
      }
      throw error;
    }
  }
}

import {
  NotFoundError,
  ConflictError,
  UnprocessableError,
} from '@cosmneo/onion-lasagna/backend/core/onion-layers';

class CreateUserCommand {
  async execute(input: CreateUserInput): Promise<void> {
    const existing = await this.userRepo.findByEmail(input.email);
    if (existing) {
      throw new ConflictError({
        message: `User with email ${input.email} already exists`,
        code: 'USER_EMAIL_EXISTS', // Custom code
      });
    }
    // ...
  }
}

class GetUserQuery {
  async execute(input: GetUserInput): Promise<UserOutput> {
    const user = await this.userRepo.findById(input.userId);
    if (!user) {
      throw new NotFoundError({
        message: `User ${input.userId} not found`,
        code: 'USER_NOT_FOUND', // Custom code
      });
    }
    return this.toOutput(user);
  }
}

import { DbError, NetworkError } from '@cosmneo/onion-lasagna/backend/core/onion-layers';
import { BaseOutboundAdapter } from '@cosmneo/onion-lasagna/backend/core/onion-layers';

class UserRepository extends BaseOutboundAdapter {
  constructor(private readonly db: Database) {
    super();
  }

  // Override to customize error type
  protected createInfraError(error: unknown, methodName: string): InfraError {
    return new DbError({
      message: `Database error in ${methodName}`,
      cause: error,
    });
  }

  async findById(id: string): Promise<User | null> {
    // If this throws, it's automatically wrapped in DbError
    return this.db.query('SELECT * FROM users WHERE id = ?', [id]);
  }
}

import {
  AccessDeniedError,
  InvalidRequestError,
} from '@cosmneo/onion-lasagna/backend/core/onion-layers';

// Access guard
class CanEditResourceGuard {
  async guard(request: Request): Promise<AccessGuardResult> {
    const canEdit = await this.checkPermission(request);
    if (!canEdit) {
      throw new AccessDeniedError({
        message: 'You do not have permission to edit this resource',
      });
    }
    return { isAllowed: true };
  }
}

import { ObjectValidationError } from '@cosmneo/onion-lasagna/backend/core/global';

// Thrown by validators when validation fails
throw new ObjectValidationError({
  message: 'Validation failed',
  validationErrors: [
    { field: 'email', message: 'Invalid email format' },
    { field: 'password', message: 'Password must be at least 8 characters' },
  ],
});

import { DomainError, NotFoundError, ConflictError, UnprocessableError } from '@cosmneo/onion-lasagna/backend/core/onion-layers';

class DeleteStatusUseCase extends BaseInboundAdapter<...> {
  protected async handle(input: DeleteStatusInputDto): Promise<void> {
    const project = await this.projectRepository.findById(input.data.projectId);
    if (!project) {
      throw new NotFoundError({ message: 'Project not found' });
    }

    try {
      project.deleteStatus(input.data.statusId);
    } catch (error) {
      // Translate domain errors to use-case errors
      if (error instanceof StatusNotFoundError) {
        throw new NotFoundError({
          message: error.message,
          code: 'STATUS_NOT_FOUND'
        });
      }
      if (error instanceof StatusInUseError) {
        throw new ConflictError({
          message: error.message,
          code: 'STATUS_IN_USE'
        });
      }
      if (error instanceof LastStatusError) {
        throw new UnprocessableError({
          message: error.message,
          code: 'LAST_STATUS'
        });
      }
      throw error; // Re-throw unknown errors
    }

    await this.projectRepository.save(project);
  }
}

import { serverRoutes } from '@cosmneo/onion-lasagna/http/server';

const routes = serverRoutes(router)
  .handle('users.create', {
    // If validation fails, ObjectValidationError is thrown automatically
    requestMapper: (req) => ({
      email: req.body.email,
      name: req.body.name,
    }),
    useCase: createUserUseCase,
    responseMapper: (output) => ({
      status: 201 as const,
      body: { userId: output.userId },
    }),
  })
  .build();

// Hono
import { onionErrorHandler } from '@cosmneo/onion-lasagna/http/frameworks/hono';
app.onError((err, c) => onionErrorHandler(err, c));

// Elysia
import { onionErrorHandler } from '@cosmneo/onion-lasagna/http/frameworks/elysia';
app.onError(({ error }) => onionErrorHandler({ error }));

// Fastify
import { onionErrorHandler } from '@cosmneo/onion-lasagna/http/frameworks/fastify';
app.setErrorHandler(onionErrorHandler);

// NestJS
import { OnionExceptionFilter } from '@cosmneo/onion-lasagna/http/frameworks/nestjs';
@UseFilters(OnionExceptionFilter)
export class AppController {}