@ciphercross/nestjs-errors

Standardized error handling for NestJS applications. Automatically converts all exceptions to a consistent ErrorResponse format that integrates seamlessly with @ciphercross/nestjs-contracts.

Installation

npm install @ciphercross/nestjs-errors

Testing

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:cov

Test Structure

Tests are located alongside source files with .spec.ts extension:

• src/domain/domain-error.spec.ts - DomainError class tests
• src/domain/error.factory.spec.ts - Error factory tests
• src/utils/sanitize-error.util.spec.ts - Sanitization utility tests
• src/utils/type-guards.util.spec.ts - Type guard tests
• src/mappers/*.spec.ts - Mapper tests
• src/filters/all-exceptions.filter.spec.ts - Exception filter tests

Coverage

The project aims for 80% code coverage. Run coverage report:

npm run test:cov

Coverage report will be generated in coverage/ directory.

Test Configuration

Jest configuration is in jest.config.js:

• Uses ts-jest preset for TypeScript support
• Mocks @ciphercross/nestjs-contracts to avoid peer dependency issues
• Excludes type files and interfaces from coverage
• Sets up test environment in src/__tests__/setup.ts

Development

Quality Checks

# Run all quality checks (lint, format, type-check)
npm run quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

# Type check without building
npm run type-check

Building

# Build the library
npm run build

# Clean build artifacts
npm run clean

Publishing

Automatic Publishing via GitHub Actions

The library is automatically published to npm when a version tag is pushed.

Method 1: Using Version Bump Workflow (Recommended)

1. Go to GitHub Actions → "Bump Version" workflow
2. Click "Run workflow"
3. Select version type (patch/minor/major)
4. Review and merge the created PR
5. Create a tag v<new-version> (e.g., v1.0.1) to trigger publish

Method 2: Manual Tag Creation

1. Update version in package.json manually
2. Commit and push changes
3. Create and push a tag:

   git tag v1.0.0
   git push origin v1.0.0

4. The publish workflow will automatically:
   • Extract version from tag
   • Run tests and linting
   • Build the package
   • Publish to npm
   • Create GitHub release

Method 3: Manual Workflow Dispatch

1. Go to GitHub Actions → "Publish to NPM" workflow
2. Click "Run workflow"
3. Enter version number (e.g., 1.0.0)
4. Workflow will publish to npm

Setup Required

Before publishing, configure the following GitHub secrets:

1. NPM_TOKEN - npm access token with publish permissions
   • Create at: https://www.npmjs.com/settings/YOUR_USERNAME/tokens
   • Required permissions: Automation or Publish

Workflows

• CI - Runs on every push/PR: tests, linting, type checking
• Publish to NPM - Publishes package when tag is created
• Bump Version - Automatically creates PR with version bump

Usage

See the main documentation for usage examples and API reference.