skills/docs/foundation/data/dedup/src/errors/dedup-error.md

DedupError

(no submodules)

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

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

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

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

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.