`error-codes`

Purpose

Defines the frozen STORAGE_FILE_CODES registry and the StorageFileError class used by every public path in @suaveplan/storage-file. The registry is the contract: every code is intentionally thrown from at least one production path, and downstream consumers assert on error.code rather than parsing message text. The class extends @suaveplan/error.SuaveplanError so it integrates with the OTel span-event adapter and the error-envelope wire format.

Features

8 frozen codes covering missing keys, permissions, IO failures, invalid input, atomic-write rollback, option validation, abort, and key length overrun.
StorageFileErrorCode union type derived from the registry — exhaustive switch statements get compile-time enforcement.
StorageFileError carries an optional key discriminant so callers can correlate a failure with the offending key without parsing strings.
All codes are namespaced STORAGE_FILE.* for unambiguous registry filtering in centralised error reporters.

Usage: Basic Example

import { StorageFileError, STORAGE_FILE_CODES } from "@suaveplan/storage-file";

try {
 await storage.get("../../etc/passwd");
} catch (err) {
 if (err instanceof StorageFileError && err.code === STORAGE_FILE_CODES.INVALID_KEY) {
  // caller-friendly message
 }
}

Usage: Advanced Example

import { StorageFileError, STORAGE_FILE_CODES, type StorageFileErrorCode } from "@suaveplan/storage-file";

function classify(code: StorageFileErrorCode): "client" | "server" {
 switch (code) {
  case STORAGE_FILE_CODES.INVALID_KEY:
  case STORAGE_FILE_CODES.KEY_TOO_LONG:
  case STORAGE_FILE_CODES.INVALID_OPTIONS:
   return "client";
  case STORAGE_FILE_CODES.NOT_FOUND:
  case STORAGE_FILE_CODES.PERMISSION_DENIED:
  case STORAGE_FILE_CODES.IO_FAILED:
  case STORAGE_FILE_CODES.ATOMIC_WRITE_FAILED:
  case STORAGE_FILE_CODES.ABORTED:
   return "server";
 }
}

throw new StorageFileError(STORAGE_FILE_CODES.NOT_FOUND, "no such key", {
 key: "/orders/42.json",
 cause: undefined,
});

API Reference

STORAGE_FILE_CODES — frozen object map of code names to fully-qualified strings (STORAGE_FILE.NOT_FOUND, etc.). Exhaustive: 8 codes.
StorageFileErrorCode — union derived from (typeof STORAGE_FILE_CODES)[keyof typeof STORAGE_FILE_CODES].
StorageFileError — class extending SuaveplanError<StorageFileErrorCode>. Constructor: (code, message, options?). Properties: inherited code, inherited cause, additional key?: string.
StorageFileErrorOptions — extends SuaveplanErrorOptions with optional key.

Implementation Notes

Codes are registered by defineCodes("STORAGE_FILE", [...]). The registration is idempotent: importing this module multiple times does not re-register or throw.
The list is closed by design — adding a new failure mode requires an spec change so consumers can update their handlers in lockstep.
name is set to "StorageFileError" so instanceof and error.name checks both work.

3.0 KiB Raw Blame History

error-codes