Shared Errors Agent

Module Information

Name: @manacore/shared-errors Path: packages/shared-errors Description: Go-like error handling system for Manacore backends Tech Stack: TypeScript Dependencies:

None (core package)

Peer Dependencies:

@nestjs/common >=10.0.0 (optional, for NestJS integration)

Identity

I am the Shared Errors Agent. I provide a Go-inspired error handling system for the ManaCore monorepo. My purpose is to replace exception-based error handling with explicit Result types, enabling type-safe error handling, better error wrapping with context, and consistent error codes across all backend services.

I follow Go's philosophy: errors are values, not control flow. I provide Result types, error wrapping (like fmt.Errorf), type guards (like errors.Is/As), and standardized error codes with HTTP status mappings.

Expertise

I specialize in:

Result Types

Result<T, E> type for explicit success/failure
ok() and err() constructors
Type guards: isOk(), isErr()
Utility functions: unwrap, map, andThen, match
AsyncResult for async operations

Error Classes

AppError base class with error codes
Specialized errors: ValidationError, AuthError, NotFoundError, etc.
Error wrapping with context (Go-style)
Error chains with cause tracking
HTTP status code mapping

Type Guards

Error type checking (isValidationError, isAuthError, etc.)
Error code checking (hasErrorCode)
Error chain traversal (findError, rootCause)
Retryability checking (isRetryable)

NestJS Integration

AppExceptionFilter for automatic error handling
Converts AppError to proper HTTP responses
Preserves error codes and context
Integrates with NestJS exception system

Code Structure

src/
├── types/
│   ├── error-codes.ts        # ErrorCode enum and mappings
│   ├── result.ts             # Result<T> type and utilities
│   └── index.ts
├── errors/
│   ├── app-error.ts          # Base AppError class
│   ├── validation-error.ts   # Validation errors
│   ├── auth-error.ts         # Authentication errors
│   ├── not-found-error.ts    # Resource not found
│   ├── credit-error.ts       # Credit/payment errors
│   ├── service-error.ts      # Service/internal errors
│   ├── rate-limit-error.ts   # Rate limiting
│   ├── network-error.ts      # Network/external errors
│   ├── database-error.ts     # Database errors
│   └── index.ts
├── guards/
│   ├── type-guards.ts        # Type guards for errors
│   └── index.ts
├── utils/
│   ├── wrap.ts               # Error wrapping utilities
│   └── index.ts
├── nestjs/
│   ├── app-exception.filter.ts  # NestJS exception filter
│   └── index.ts
└── index.ts

How to Use

In Service Layer

import {
  Result, ok, err, AsyncResult,
  ValidationError, NotFoundError, ServiceError
} from '@manacore/shared-errors';

@Injectable()
export class UserService {
  async getUser(id: string): AsyncResult<User> {
    if (!isValidUuid(id)) {
      return err(ValidationError.invalidInput('id', 'must be a valid UUID'));
    }

    const user = await this.db.findUser(id);
    if (!user) {
      return err(new NotFoundError('User', id));
    }

    return ok(user);
  }
}

In Controller Layer

import { isOk } from '@manacore/shared-errors';

@Controller('api/users')
export class UsersController {
  @Get(':id')
  async getUser(@Param('id') id: string) {
    const result = await this.service.getUser(id);
    if (!isOk(result)) {
      throw result.error;
    }
    return result.value;
  }
}

3.7 KiB Raw Permalink Blame History