# qrcode-error

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

`QRCodeError` is the typed error class for the entire `@suaveplan/qrcode` package. It extends the native `Error` class with a stable `code` property drawn from `QRCODE_CODES`, allowing callers to discriminate failure modes programmatically without string parsing. The class intentionally avoids the `@suaveplan/error` dependency so this leaf package remains dependency-minimal: only `zod`, `tslib`, and `@opentelemetry/api` are required at runtime.

The three error codes cover every failure surface of the QR code generation pipeline: invalid input data, insufficient version capacity for the payload, and unexpected encoding pipeline failures. All three are stable across patch releases.

## Features

- `QRCODE_CODES` frozen registry with three stable error codes
- `QRCodeCode` union type derived from the registry
- `QRCodeError` extends `Error` with a narrow `code: QRCodeCode` property
- `instanceof` discrimination for structured error handling
- `name` property set to `"QRCodeError"` for logging and stack trace clarity

## Usage: Basic Example

```ts
import { QRCodeError, QRCODE_CODES } from "@suaveplan/qrcode/errors";

try {
  throw new QRCodeError("Input is empty", QRCODE_CODES.INVALID_DATA);
} catch (err) {
  if (err instanceof QRCodeError) {
    console.error(err.code); // "QRCODE.INVALID_DATA"
  }
}
```

## Usage: Advanced Example

```ts
import { QRCodeError, QRCODE_CODES } from "@suaveplan/qrcode/errors";

function assertVersionCapacity(version: number, byteCount: number): void {
  // Version 1 byte-mode M capacity = 14 bytes
  const cap = version === 1 ? 14 : byteCount + 1;
  if (byteCount > cap) {
    throw new QRCodeError(
      `Version ${version} cannot hold ${byteCount} bytes`,
      QRCODE_CODES.VERSION_TOO_SMALL
    );
  }
}

try {
  assertVersionCapacity(1, 20);
} catch (err) {
  if (err instanceof QRCodeError && err.code === QRCODE_CODES.VERSION_TOO_SMALL) {
    console.warn("Increase version or reduce data size");
  }
}
```

## API Reference

### `QRCODE_CODES`

`{ readonly INVALID_DATA: "QRCODE.INVALID_DATA"; readonly VERSION_TOO_SMALL: "QRCODE.VERSION_TOO_SMALL"; readonly ENCODE_FAILED: "QRCODE.ENCODE_FAILED" }`

Frozen object mapping error-code names to their canonical string values. Consumers should always reference codes via this object rather than inline strings to benefit from rename refactoring and exhaustive switch checking.

### `QRCodeCode`

`type QRCodeCode = (typeof QRCODE_CODES)[keyof typeof QRCODE_CODES]`

Union of all valid error code strings. Narrowed automatically when branching on `err.code`.

### `class QRCodeError extends Error`

**Constructor:** `new QRCodeError(message: string, code: QRCodeCode)`

- `message` — human-readable description of the failure
- `code` — one of the values in `QRCODE_CODES`

**Properties:**

- `name: "QRCodeError"` — set by the constructor for identification in logs and stack traces
- `code: QRCodeCode` — readonly, stable error code
- All standard `Error` properties: `message`, `stack`

## Implementation Notes

The class deliberately does not extend `SuaveplanError` from `@suaveplan/error`. This keeps the dependency graph lean: the qrcode package is a leaf in the media domain and should not pull in the full error substrate (Zod wire format, OTel span events, cause-chain traversal) unless a future version explicitly requires them. If the package graduates to depending on `@suaveplan/error`, the migration is straightforward since the `code` property convention is identical.

The `as const` assertion on `QRCODE_CODES` ensures TypeScript infers string literal types rather than `string`, enabling exhaustive union checks.