`error-codes`

(no submodules)

Purpose

VIDEO_THUMBNAILS_CODES is the stable, frozen registry of every failure mode raised by @suaveplan/video-thumbnails. It is built with defineCodes from @suaveplan/error so the namespace prefix (VIDEO_THUMBNAILS.) is encoded in the literal type — meaning consumers can switch on a VideoThumbnailsCode and TypeScript will enforce exhaustiveness. The registry is the single source of truth: every throw new VideoThumbnailsError(...) references a code from this object, and the conformance test walks the registry to prove no code is dead.

Features

Frozen, namespaced registry built via defineCodes("VIDEO_THUMBNAILS", [...]).
Literal union VideoThumbnailsCode derived from the registry values.
Every code reachable from a real call site in src/, validated by error-codes.test.ts.
Compatible with the project-wide SuaveplanError wire format, OTel span events, and redaction.

Usage: Basic

import { VIDEO_THUMBNAILS_CODES } from "@suaveplan/video-thumbnails/error-codes";

console.log(VIDEO_THUMBNAILS_CODES.EXTRACT_FAILED); // "VIDEO_THUMBNAILS.EXTRACT_FAILED"

Usage: Advanced

import {
    VIDEO_THUMBNAILS_CODES,
    type VideoThumbnailsCode,
} from "@suaveplan/video-thumbnails/error-codes";

function describe(code: VideoThumbnailsCode): string {
    switch (code) {
        case VIDEO_THUMBNAILS_CODES.EXTRACT_FAILED:
            return "ffmpeg failed mid-extract";
        case VIDEO_THUMBNAILS_CODES.PROBE_FAILED:
            return "ffprobe failed";
        case VIDEO_THUMBNAILS_CODES.VIDEO_INVALID:
            return "input is not a valid video";
        case VIDEO_THUMBNAILS_CODES.INVALID_TIMESTAMP:
            return "timestamp is not HH:MM:SS(.mmm)?";
        case VIDEO_THUMBNAILS_CODES.INVALID_DIMENSIONS:
            return "width/height/count <= 0";
        case VIDEO_THUMBNAILS_CODES.INVALID_OPTIONS:
            return "Zod boundary validation failed";
        case VIDEO_THUMBNAILS_CODES.FORMAT_UNSUPPORTED:
            return "output format not in jpg|png|webp";
        case VIDEO_THUMBNAILS_CODES.RUNNER_UNAVAILABLE:
            return "ffmpeg binary not available";
        case VIDEO_THUMBNAILS_CODES.ABORTED:
            return "AbortSignal triggered";
    }
}

API Reference

VIDEO_THUMBNAILS_CODES — Readonly<Record<Reason, "VIDEO_THUMBNAILS.<Reason>">> for the nine codes EXTRACT_FAILED, PROBE_FAILED, VIDEO_INVALID, INVALID_TIMESTAMP, INVALID_DIMENSIONS, INVALID_OPTIONS, FORMAT_UNSUPPORTED, RUNNER_UNAVAILABLE, ABORTED. Frozen at construction.
VideoThumbnailsCode — literal union of every value in the registry; use as the parameter type for handlers that need to switch on failure mode.

Implementation Notes

The registry is intentionally minimal — codes are added only when there is a corresponding throw site in src/. Removing a code requires a deprecation window: keep the entry in the registry, raise the new code from the call site, then drop the entry in a follow-up change so external callers have one release to migrate case clauses. Codes never carry payload — that lives on SuaveplanError.context. The frozen object means accidental mutation throws at runtime in strict mode, which preserves the registry-as-contract invariant.

3.3 KiB Raw Blame History

error-codes