# data-masking-error

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

Provides a stable error-code registry and a typed `DataMaskingError` class for
all failures that originate inside `@suaveplan/data-masking`. Keeping errors
isolated to a single file makes it easy for callers to perform narrow
`instanceof` checks and to discriminate specific failure modes via the `code`
property without resorting to fragile message-string matching.

The package is intentionally a leaf node — it carries zero `@suaveplan/*`
runtime dependencies — so `DataMaskingError` extends the native `Error` class
directly rather than `SuaveplanError`.

## Features

- `DATA_MASKING_CODES` constant object: two stable string codes exported as
  `as const` for full TypeScript narrowing.
- `DataMaskingCode` union type derived from `DATA_MASKING_CODES`.
- `DataMaskingError` class: extends `Error`, sets `name = "DataMaskingError"`,
  exposes a readonly `code: DataMaskingCode` property.
- Tree-shakeable — no side-effects, compatible with `"sideEffects": false`.

## Usage: Basic Example

```ts
import {
  DataMaskingError,
  DATA_MASKING_CODES,
} from '@suaveplan/data-masking/errors';

try {
  throw new DataMaskingError(
    'Strategy "unknown" is not recognised',
    DATA_MASKING_CODES.INVALID_RULE,
  );
} catch (err) {
  if (err instanceof DataMaskingError) {
    console.error(err.code);   // 'DATA_MASKING.INVALID_RULE'
    console.error(err.name);   // 'DataMaskingError'
    console.error(err.message);
  }
}
```

## Usage: Advanced Example

```ts
import {
  DataMaskingError,
  DATA_MASKING_CODES,
  type DataMaskingCode,
} from '@suaveplan/data-masking/errors';

function handleMaskingError(err: unknown): void {
  if (!(err instanceof DataMaskingError)) throw err;

  const actions: Record<DataMaskingCode, () => void> = {
    [DATA_MASKING_CODES.INVALID_RULE]: () =>
      console.warn('Rule validation failed — check your MaskRule definitions'),
    [DATA_MASKING_CODES.MASK_FAILED]: () =>
      console.error('Masking strategy threw during execution'),
  };

  actions[err.code]?.();
}
```

## API Reference

### `DATA_MASKING_CODES`

```ts
const DATA_MASKING_CODES: {
  readonly INVALID_RULE: 'DATA_MASKING.INVALID_RULE';
  readonly MASK_FAILED:  'DATA_MASKING.MASK_FAILED';
};
```

Stable string constants that identify each error category.  Values are
intentionally namespaced with `DATA_MASKING.` to avoid collisions in shared
error-monitoring pipelines.

### `DataMaskingCode`

```ts
type DataMaskingCode = 'DATA_MASKING.INVALID_RULE' | 'DATA_MASKING.MASK_FAILED';
```

Union type derived from `DATA_MASKING_CODES`.  Use this for exhaustive `switch`
statements or discriminated-union narrowing.

### `DataMaskingError`

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

| Property | Type              | Description                            |
|----------|-------------------|----------------------------------------|
| `name`   | `string`          | Always `"DataMaskingError"`.           |
| `code`   | `DataMaskingCode` | The stable machine-readable error code.|
| `message`| `string`          | Human-readable description of failure. |

## Implementation Notes

- The `name` property is set in the constructor body (not via a static field)
  to ensure correct behaviour after `Object.setPrototypeOf` in transpiled ES5
  environments, though suaveplan targets ES2022+ natively.
- No stack-trace manipulation is performed — the default `Error` constructor
  captures a stack trace automatically in V8 and Bun runtimes.
- `DATA_MASKING_CODES` is declared `as const` so TypeScript infers the narrow
  string-literal type for each member; this enables exhaustive checks on
  `DataMaskingCode` without a separate enum.