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

data-masking-error

(no submodules)

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

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

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

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

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

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.