first commit

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

@@ -0,0 +1,120 @@
+# 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.