`VideoThumbnailsError`

(no submodules)

Purpose

VideoThumbnailsError is the single error class raised by every public surface of @suaveplan/video-thumbnails. It extends SuaveplanError<VideoThumbnailsCode> so it inherits the project-wide wire format (toJSON / fromJSON), the OTel span-event adapter, the redaction pipeline, the cause-chain walker, and the i18n resolver hook. Every constructor call must reference a code from VIDEO_THUMBNAILS_CODES, which keeps the registry and the call sites in lock-step.

Features

Single class for the entire failure surface — no parallel hierarchies to keep in sync.
Code is parameterised, so TypeScript narrows on error.code at catch sites.
Carries context (Zod issues, ffmpeg stderr, abort reason) without bloating the message.
Compatible with walkCauses, toSpanEvent, and the JSON / binary serializers exported by @suaveplan/error.

Usage: Basic

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

throw new VideoThumbnailsError(
    VIDEO_THUMBNAILS_CODES.EXTRACT_FAILED,
    "videoThumbnails.errors.extractFailed",
);

Usage: Advanced

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

try {
    await generator.generate("/missing.mp4");
} catch (error) {
    if (error instanceof VideoThumbnailsError) {
        if (error.code === VIDEO_THUMBNAILS_CODES.PROBE_FAILED) {
            await reportMetric("probe-failed", error.context);
            return;
        }
        if (error.code === VIDEO_THUMBNAILS_CODES.ABORTED) {
            return;
        }
    }
    throw error;
}

API Reference

class VideoThumbnailsError extends SuaveplanError<VideoThumbnailsCode>
- constructor(code, messageKey, options?)
  - code — one of VIDEO_THUMBNAILS_CODES.*
  - messageKey — i18n key (caller resolves the human-readable string)
  - options — SuaveplanErrorOptions ({ cause?, context?, severity?, retryable?, httpStatus? })
- Inherited members: code, messageKey, context, cause, severity, retryable, httpStatus, toJSON(), toSpanEvent().

Implementation Notes

The class sets this.name = "VideoThumbnailsError" so structured logs identify the class even when prototypes are stripped (some test runners walk name rather than the prototype chain). It does not override toJSON — the base SuaveplanError serializer already covers the wire format. When a Zod validation fails the schema layer attaches the ZodError.issues array under context.issues, which the redactor passes through unmodified because Zod issues do not contain sensitive material in this package's option space.

2.9 KiB Raw Blame History

VideoThumbnailsError