# @qvac/error

This library provides standardized error handling capabilities for all QVAC libraries. It ensures consistency in error reporting, serialization, and handling across the entire QVAC ecosystem.

## Installation

```bash
npm i @qvac/error
```

## Features

- Base error class extending native Error
- Standardized error codes and messages
- Support for dynamic error messages with parameters
- Error serialization for logging and API responses
- Registry system for error code management
- Mechanisms to prevent error code conflicts

## Usage

### Basic Usage

```javascript
import { QvacErrorBase, addCodes } from '@qvac/error'

// Create your own error class extending the base
class QvacErrorCustom extends QvacErrorBase {}

// Define your error codes (reserve at least 1000 codes per library)
const ERR_CODES = Object.freeze({
  VALIDATION_ERROR: 1000,
  CONNECTION_ERROR: 1001,
  TIMEOUT_ERROR: 1002
})

// Register your error codes and their messages
addCodes({
  [ERR_CODES.VALIDATION_ERROR]: {
    name: 'VALIDATION_ERROR',
    message: (...field) => `Validation failed for field: ${field}`
  },
  [ERR_CODES.CONNECTION_ERROR]: {
    name: 'CONNECTION_ERROR',
    message: 'Failed to establish connection'
  },
  [ERR_CODES.TIMEOUT_ERROR]: {
    name: 'TIMEOUT_ERROR',
    message: (timeout) => `Operation timed out after ${timeout}ms`
  }
})

// Using your custom errors
try {
  // Some operation that fails
  throw new QvacErrorCustom({ code: ERR_CODES.VALIDATION_ERROR, adds: 'username' })
} catch (error) {
  console.error(error.message) // "Validation failed for field: username"
  console.error(error.code) // 1000
  console.error(error.name) // "VALIDATION_ERROR"
}
```

### Error Code Conventions

- Each library should reserve a range of at least 1000 codes
- Keep codes in ascending order based on abstraction level
- Base libraries should have lower code ranges
- Document your code range to avoid conflicts with other libraries

### API Reference

#### `QvacErrorBase`

Base error class that extends the native Error.

```javascript
new QvacErrorBase(options)
```

- `options.code` (Number): The error code
- `options.adds` (Array|String): Additional parameters to format the error message
- `options.cause` (Error): The underlying error that caused this one

#### `addCodes(codes)`

Register new error codes.

- `codes` (Object): Map of error codes to their definitions

#### `getRegisteredCodes()`

Get all registered error codes and their definitions.

#### `isCodeRegistered(code)`

Check if a code is already registered.

- `code` (Number): The error code to check

#### `INTERNAL_ERROR_CODES`

Reserved internal error codes:

- `UNKNOWN_ERROR_CODE`: 0
- `INVALID_CODE_DEFINITION`: 1
- `ERROR_CODE_ALREADY_EXISTS`: 2
- `MISSING_ERROR_DEFINITION`: 3
- `PACKAGE_VERSION_CONFLICT`: 4
- `INVALID_PACKAGE_INFO`: 5

## Development

The package is written in TypeScript under `src/` and compiled to `dist/` with `tsc`.
After cloning, run `npm install` (its `prepare` script builds `dist/`); run `npm run build`
to recompile, `npm run typecheck` to type-check, and `npm run test:unit` for the tests.

## Best Practices

1. Create a dedicated errors file/module in each library
2. Extend `QvacErrorBase` with a library-specific class name (e.g., `QvacErrorAgent`)
3. Keep all error codes in a separate, well-documented module
4. Use descriptive error names and clear messages
5. Avoid relying on error messages for logic (use codes instead)
6. Consider generating documentation from your error codes