@thalorlabs/errors/PUBLISHING.md

Enhanced exception handling system for TypeScript applications with comprehensive error classes and debugging capabilities

# Publishing Guide

This guide is for developers who want to publish updates to the `@thalorlabs/errors` package.

## Prerequisites

1. Ensure you have an npm account and are logged in:

   ```bash
   npm login
   ```

2. Make sure you have the necessary permissions to publish to the `@thalorlabs` scope.

## Build and Validation

Before publishing, ensure the package builds, tests pass, and TypeScript compiles without errors:

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Check test coverage
npm run test:coverage
```

## Publishing

1. **Version the package** (choose one):

   ```bash
   # Patch version (1.0.0 -> 1.0.1)
   npm version patch

   # Minor version (1.0.0 -> 1.1.0)
   npm version minor

   # Major version (1.0.0 -> 2.0.0)
   npm version major
   ```

   **Semantic Versioning Guide:**

   - **PATCH**: Bug fixes that don't add features or break existing functionality
     - Examples: Fixing error class implementations, documentation updates, minor error property adjustments
   - **MINOR**: Adding new features that are backward compatible
     - Examples: New error classes, new error enums, optional error properties, new exports
   - **MAJOR**: Breaking changes that could break existing code
     - Examples: Removing error classes, changing required error properties, changing error status codes, breaking error constructor changes

2. **Publish to npm**:

   ```bash
   npm publish
   ```

   **Note**: The `prepublishOnly` script automatically runs:

   - `npm run build` - Builds the package and generates type definitions

   Publishing will fail if the build fails or TypeScript compilation errors exist.

## Package Structure

The package is configured as an ES module with the following structure:

- **Main entry**: `./dist/index.js`
- **Types**: `./dist/index.d.ts`
- **Individual exports**: Available at `@thalorlabs/errors/ValidationError`, `@thalorlabs/errors/DatabaseError`, etc.

## Development

### Scripts

- `npm run build` - Build the package and generate type definitions
- `npm run clean` - Clean build artifacts
- `npm test` - Run the test suite
- `npm run test:coverage` - Run tests with coverage reporting

### Configuration

- **TypeScript**: Configured in `tsconfig.json`
- **Build output**: `dist/` directory
- **Package files**: Defined in `.npmignore`

### Error Safety

This package focuses on providing comprehensive error handling:

- **Error inheritance**: All errors extend CustomError base class
- **TypeScript definitions**: Compile-time type checking for error properties
- **HTTP status codes**: Proper HTTP status code mapping
- **Error context**: Rich context and request tracking support
- **Test coverage**: Comprehensive test suite with high coverage

### Third-Party Error Policy

**This package only contains ThalorLabs error classes** - never publish third-party library error types.

- ✅ Publish: `ValidationError`, `DatabaseError`, `RateLimitError` (our error contracts)
- ❌ Never publish: Express.js error types, Mongoose error types, Axios error types
- Keep third-party error types local to the service that uses the library
- This ensures stable error handling contracts and prevents third-party library changes from breaking our ecosystem

## Breaking Changes

When making breaking changes to error classes:

1. **Document the change** in the changelog
2. **Update major version** using `npm version major`
3. **Consider migration guide** for complex changes
4. **Test with dependent packages** before publishing
5. **Ensure backward compatibility** where possible

## Dependencies

This package depends on:

- `@thalorlabs/types` - HTTP status code enums and type definitions
- No other runtime dependencies (lightweight error handling)

Ensure these dependencies are compatible with your target environment.