# DedupError

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

`DedupError` is the error substrate for the `@suaveplan/dedup` package. It extends the built-in `Error` class with a stable `code` field so callers can branch on specific failure modes without parsing message strings. Every error thrown by the dedup engine or merge strategies uses this class.

## Features

- Typed `code` field for reliable programmatic error handling
- Two stable error codes: `DEDUP.INVALID_CONFIG` and `DEDUP.STRATEGY_ERROR`
- Lightweight — no external dependencies; usable in any runtime environment
- `name` set to `'DedupError'` for readable stack traces and `instanceof` checks

## Usage: Basic Example

```ts
import { DedupError, DEDUP_CODES } from '@suaveplan/dedup/errors';

try {
  engine.detect(entities);
} catch (err) {
  if (err instanceof DedupError && err.code === DEDUP_CODES.INVALID_CONFIG) {
    console.error('Configuration is invalid:', err.message);
  }
}
```

## Usage: Advanced Example

```ts
import { DedupError, DEDUP_CODES } from '@suaveplan/dedup/errors';

function safeMerge(engine: DedupEngine, group: DuplicateGroup, strategy: MergeStrategy) {
  try {
    return engine.merge(group, strategy);
  } catch (err) {
    if (err instanceof DedupError) {
      if (err.code === DEDUP_CODES.STRATEGY_ERROR) {
        // Fall back to manual strategy
        return engine.merge(group, manualStrategy);
      }
    }
    throw err;
  }
}
```

## API Reference

### `DEDUP_CODES`

```ts
const DEDUP_CODES: {
  INVALID_CONFIG: 'DEDUP.INVALID_CONFIG';
  STRATEGY_ERROR: 'DEDUP.STRATEGY_ERROR';
}
```

- `INVALID_CONFIG` — thrown when `DedupConfig` fails Zod validation (missing required fields, invalid weights, etc.)
- `STRATEGY_ERROR` — thrown when a merge strategy throws an unexpected error

### `DedupError`

```ts
class DedupError extends Error {
  readonly code: string;
  constructor(message: string, code: string);
}
```

- `message` — human-readable description of the failure
- `code` — one of the `DEDUP_CODES` constants
- `name` — always `'DedupError'`

## Implementation Notes

This package is a leaf (no `@suaveplan/*` runtime dependencies), so it cannot depend on `@suaveplan/error`. The local `DedupError` class provides the same `code`-based discriminator pattern used throughout the project without introducing a circular dependency. If `@suaveplan/error` is added as a dependency in the future, this class should be migrated to extend `SuaveplanError`.

All errors thrown by the engine and merge strategies include a `code` value drawn from `DEDUP_CODES`. Callers should always `instanceof DedupError` before reading `.code` to avoid narrowing mistakes when third-party errors propagate through the dedup boundary. The code constants are exported as a plain `const` object rather than an enum to keep the module tree-shakeable and to avoid TypeScript enum pitfalls in strict ESM environments.