first commit

docs/foundation/barcode/qrcode/src/errors/qrcode-error.md

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