qrcode-error

(no submodules)

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

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

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.

3.7 KiB Raw Blame History