error-handling-api

Files (19)

• README.md
• SKILL.md
• VALIDATION.md
• advanced-patterns.ts · examples/
• basic-usage.ts · examples/
• custom-logger.ts · examples/
• nextjs-api-route.ts · examples/
• manifest.yaml
• package-lock.json
• package.json
• error-codes.ts · src/
• error-handler.ts · src/
• index.ts · src/
• types.ts · src/
• utils.ts · src/
• error-handler.test.ts · tests/
• index.test.ts · tests/
• tsconfig.json
• vitest.config.ts

SKILL.md (first lines)

# Error Handling API

Centralized error handling system for Next.js API routes with consistent responses, request tracking, and separation between user-facing messages and technical logs.

## When to Use

Use this skill when building Next.js APIs that need:
- Consistent error response format across all endpoints
- User-friendly error messages (never expose internal details)
- Request ID tracking for debugging
- Automatic error catching and logging
- Type-safe error codes and responses
- Separation between client errors (4xx) and server errors (5xx)

**Don't use this skill if:**
- You're building a simple static site without APIs
- You need GraphQL error handling (this is REST-focused)
- You're using Next.js Pages Router (this uses App Router Route Handlers)

## Stack

- Next.js 14+ (App Router Route Handlers)
- TypeScript (strict mode)
- Optional: Logging library integration (Pino, Winston, etc.)

## Quick Start

### 1. Install Skill

```bash
npm install -D @project-forge/error-handling-api
```

### 2. Create Error Codes Dictionary

```typescript
// lib/api/errors.ts
import { API_ERROR } from '@project-forge/error-handling-api'

// Use predefined errors or extend with your own
export const AppErrors = {
  ...API_ERROR,
  CUSTOM_ERROR: {
    code: 'CUSTOM_ERROR',
    message: 'Your custom error message',
    status: 400,
  },
} as const
```

### 3. Use in API Routes

```typescript
// app/api/users/route.ts
import { apiError, apiSuccess } from '@project-forge/error-handling-api'
import { NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  const userId = request.nextUrl.searchParams.get('id')

  if (!userId) {
    return apiError('MISSING_PARAMS')
  }

  const user = await db.users.findUnique({ where: { id: userId } })

  if (!user) {
    return apiError('NOT_FOUND')
  }

  return apiSuccess(user)
}
```

### 4. Wrap Routes with Error Handler

```typescript
import { withErrorHandler } from '@project-forge/error-handling-api'

export const POST = withErrorHandler(async (request) => {
  // Any unhandled errors are caught and returned as 500
  const data = await processData()
  return apiSuccess(data)
})
```

## Key Features

### Standard Error Codes

Pre-defined error codes for common scenarios:

**Authentication (401)**
- `UNAUTHORIZED` - Authentication required
- `SESSION_EXPIRED` - Session expired, please reconnect

**Authorization (403)**
- `FORBIDDEN` - Access denied
- `RESOURCE_FORBIDDEN` - No access to this resource

**Not Found (404)**
- `NOT_FOUND` - Resource not found
- `PROFILE_NOT_FOUND`, `EMAIL_NOT_FOUND`, etc.

**Validation (400)**
- `VALIDATION_ERROR` - Invalid data
- `INVALID_PARAMS` - Invalid parameters
- `MISSING_PARAMS` - Required parameters missing

**Rate Limiting (429)**
- `RATE_LIMITED` - Too many requests

**Server Errors (500)**
- `INTERNAL_ERROR` - Internal server error
- `DATABASE_ERROR` - Database operation failed
- `SERVICE_UNAVAILABLE` - Service temporarily unavailable

### Request ID Tracking

From JimmyBlanquet/project-forge, MIT.

More from JimmyBlanquet/project-forge