`error-codes.ts`

(no submodules)

Purpose

Defines the stable error-code registry for @suaveplan/api-plugin-file-upload. Each failure path in the plugin throws a FileUploadError carrying one of 11 UPLOAD.* codes; consumers branch on error.code to render localised messages, decide on retry behaviour, or surface user-facing copy. The registry is the single source of truth for every observable failure mode the plugin exposes — the spec, the integration tests, and downstream consumer code all reference it by name.

Features

11 codes registered via defineCodes("UPLOAD", [...]) so the cause chain, OTel span events, and i18n keys all share the same string prefix.
FileUploadError extends SuaveplanError<UploadErrorCode> for typed instanceof narrowing.
Public constructor so call sites in routes, the assembler, and the storage adapters can throw directly without a factory helper.
Documented per-code semantics so reviewers can confirm every ### Requirement in the spec maps to exactly one production call site.

Usage: Basic

import {
    FileUploadError,
    UPLOAD_CODES,
} from "@suaveplan/api-plugin-file-upload/error-codes/error-codes";

if (size > limit) {
    throw new FileUploadError(
        UPLOAD_CODES.TOO_LARGE,
        `Upload exceeds singleShotLimitBytes`,
        { context: { statusCode: 413, size, limit } }
    );
}

Usage: Advanced

import { FileUploadError } from "@suaveplan/api-plugin-file-upload";

try {
    await uploadService.complete(id, declaredHash, principalId);
} catch (err) {
    if (err instanceof FileUploadError) {
        switch (err.uploadCode) {
            case "UPLOAD.HASH_MISMATCH":
                return c.json({ retry: true, reason: "hash-mismatch" }, 422);
            case "UPLOAD.INCOMPLETE":
                return c.json({ retry: true, reason: "missing-chunks" }, 409);
            default:
                throw err;
        }
    }
    throw err;
}

API Reference

UPLOAD_CODES — readonly registry of 11 string constants prefixed UPLOAD..
UploadErrorCode — union type derived from UPLOAD_CODES values.
FileUploadError extends SuaveplanError<UploadErrorCode> — concrete error class. Constructor signature (code: UploadErrorCode, message: string, options?: SuaveplanErrorOptions). Carries an uploadCode field mirroring code for ergonomic narrowing.

Implementation Notes

The registry is intentionally closed at 11 codes; adding a new code requires bumping the spec delta and threading the new code through a real production path. This is enforced by error-codes.spec-conformance.test.ts.
cause carries the original ZodError for INVALID_INPUT and the underlying Error for STORAGE_FAILURE. Consumers may walk the cause chain via SuaveplanError.traverseCauses() from @suaveplan/error.
context.statusCode is set by every throw site so the @suaveplan/api error-handler translates it to the right HTTP status without per-code mapping at the handler layer.

3.0 KiB Raw Blame History

error-codes.ts