`errors` — `VideoError` and the 16 factories

(no submodules)

Purpose

This module exposes the typed VideoError class and the 16 factory functions every consumer of @suaveplan/video uses to construct errors. VideoError extends SuaveplanError<VideoCode> from @suaveplan/error so it inherits the foundation contract: cause chains, stable code discriminants, i18n-friendly message resolution, span-event compatibility, and a typed context field carrying structured hints. Every factory in the upstream package is preserved with its original signature and message phrasing so consumers porting from the legacy @suaveplan/video continue to compile without code changes.

The factories form the canonical surface for the rest of the package — VideoProcessor, VideoPipelineBuilder, and helper functions all raise through these factories rather than constructing VideoError instances directly. This keeps the codes, messages, and context fields consistent and makes it trivial to grep for "where does code X come from" across the codebase.

Features

VideoError extends SuaveplanError<VideoCode> — full base-class surface including code, message, cause, context, timestamp.
15 upstream factory functions with identical signatures.
One factory: videoConfigInvalid(message) raising VIDEO.CONFIG_INVALID.
VideoErrorContext type with the structured hint fields the upstream package threaded through context.

Usage: Basic

import { unknownVideoFormat } from "@suaveplan/video/errors/errors";

try {
    // some pipeline step
} catch {
    throw unknownVideoFormat();
}

Usage: Advanced

import {
    VideoError,
    videoMetadataParseFailed,
    videoTooLarge,
} from "@suaveplan/video/errors/errors";

function ensureSize(size: number, max: number) {
    if (size > max) throw videoTooLarge(size, max);
}

function safeParse(data: Uint8Array, parser: (b: Uint8Array) => unknown) {
    try {
        return parser(data);
    } catch (err) {
        throw videoMetadataParseFailed(err instanceof Error ? err : undefined);
    }
}

function handle(err: unknown) {
    if (err instanceof VideoError) {
        // err.code is the discriminant; err.context carries typed hints.
        console.error(err.code, err.context, err.cause);
    }
}

API Reference

class VideoError extends SuaveplanError<VideoCode> — constructor (code, message, options?).
interface VideoErrorContext extends Record<string, unknown> — optional hints: format, codec, duration, width, height, fileSize, maxSize, operationMs.
interface VideoErrorOptions extends SuaveplanErrorOptions — adds the typed context.
Factories: unknownVideoFormat(), invalidVideoDimensions(w, h), invalidTrimRange(start, end), videoMetadataParseFailed(cause?), invalidVideoTransform(message), durationExceeded(d, max), unsupportedCodec(c), videoNotFound(format?), videoDecodeFailed(cause?), videoEncodeFailed(cause?), videoFormatUnsupported(format), videoTooLarge(fileSize, maxSize), videoProcessingFailed(message, cause?), videoCodecUnsupported(c), videoTimeout(operationMs), videoConfigInvalid(message).

Implementation Notes

VideoError does NOT redeclare a local context field — it relies on the one already declared on SuaveplanError, which is typed as Readonly<Record<string, unknown>> and to which VideoErrorContext is assignable. This avoids the field-shadowing footgun seen in early implementations of similar packages.

The videoConfigInvalid factory is the only entry; it replaces the upstream pattern of conflating constructor-time validation failures with generic VIDEO_PROCESSING_FAILED errors by giving them a discrete VIDEO.CONFIG_INVALID code so retry policies and HTTP mappers can distinguish "your config is wrong" (500, non-retryable) from "the pipeline failed at runtime" (422). All other factories preserve the upstream message phrasing verbatim so log-scrapers and i18n catalogs keep matching.

4.0 KiB Raw Blame History

errors — VideoError and the 16 factories