Error Handling (@wrelik/errors)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/errors/src/index.ts
• packages/errors/package.json
• README.md
• DECISIONS.md
• packages/db/src/index.ts
• packages/auth/src/index.test.ts

The @wrelik/errors package serves as the centralized error management system for the Wrelik ecosystem. It provides a set of typed application errors and integration with Sentry for centralized tracking. By standardizing error structures, the package ensures consistent error reporting across all shared packages and consumer applications.

Sources: README.md:23-24, DECISIONS.md:12

Core Architecture

The architecture is built around a base AppError class that extends the native JavaScript Error. This base class introduces specialized properties for error codes and HTTP status codes, enabling programmatic handling in API layers. The package integrates with @sentry/node to provide global error monitoring.

Error Class Hierarchy

The system uses inheritance to define specific error types used throughout the monorepo:

The diagram shows the relationship between the native Error object and the specialized typed errors provided by the package.
Sources: packages/errors/src/index.ts:3-50

Error Definitions

Class	Error Code	Default Status	Description
AppError	(Variable)	500	Base class for all application errors.
AuthRequiredError	AUTH_REQUIRED	401	Thrown when a user session is missing or invalid.
TenantRequiredError	TENANT_REQUIRED	400	Thrown when a multi-tenant operation lacks a tenant context.
PermissionDeniedError	PERMISSION_DENIED	403	Thrown when a user lacks sufficient RBAC permissions.
ValidationError	VALIDATION_ERROR	400	Thrown when input data fails validation logic.

Sources: packages/errors/src/index.ts:3-50

Reporting and Monitoring

The package provides utilities for capturing errors and managing user context in Sentry.

Error Capture Logic

The captureError function manages how errors are logged and reported based on their type and severity:

The flow shows that while all errors are logged locally, only server-side errors (500+) or unexpected errors are forwarded to Sentry.
Sources: packages/errors/src/index.ts:52-66

Monitoring Configuration

Global monitoring is configured through initialization and context-setting functions:

• initErrors(dsn: string): Initializes the Sentry SDK with a 1.0 traces sample rate.
• setUserContext(user): Associates subsequent errors with a specific user ID and optional email.
• captureError(err, context): A unified entry point for error reporting that handles both AppError instances and unknown error types.

Sources: packages/errors/src/index.ts:52-79, packages/errors/package.json:16

Cross-Package Integration

Other packages in the @wrelik scope rely on these error definitions to enforce business rules and security boundaries.

• @wrelik/auth: Uses AuthRequiredError within the requireUser helper to enforce authentication state.
• @wrelik/db: Uses TenantRequiredError and PermissionDeniedError within tenant access checkers and the withTenant wrapper to ensure data isolation.
• @wrelik/storage & @wrelik/analytics: Depend on @wrelik/errors to provide consistent failure responses during service interactions.

Sources: packages/auth/src/index.test.ts:7-10, packages/db/src/index.ts:1-25, packages/storage/package.json:14, packages/analytics/package.json:14

Summary

The @wrelik/errors package is a foundational infrastructure component that standardizes how failures are represented and monitored. By using Sentry as the backend and providing a strictly typed hierarchy of error classes, it enables reliable error tracking and predictable error handling across the entire monorepo.