skills/docs/media/audio/audio-sprite-packer/src/error-codes/error-codes.md

Error Codes

(no submodules)

Purpose

This module centralises every error code, metadata description, and severity level that the @suaveplan/audio-sprite-packer package can emit. By defining codes through the @suaveplan/error registry, consumers can rely on stable string identifiers instead of brittle message matching when handling failures. The module also exports a concrete AudioSpriteError class so that all sprite-packer exceptions share a single, recognisable type.

Features

• Typed error codes — AUDIO_SPRITE_CODES provides strongly-typed constants such as UNSUPPORTED_FORMAT and CLIP_NOT_FOUND.
• Per-code metadata — AUDIO_SPRITE_ERROR_METADATA maps every code to a human-readable description and a severity of "warning" or "error".
• Dedicated exception class — AudioSpriteError extends SuaveplanError and carries the AudioSpriteErrorCode discriminator.
• Idempotent registration — registerAudioSpriteErrorCodes may be called repeatedly without side effects because the metadata record is frozen at module load time.

Usage: Basic Example

import { AudioSpriteError, AUDIO_SPRITE_CODES } from "@suaveplan/audio-sprite-packer";

function unpackClip(sprite: AudioSprite, name: string) {
  const packer = createAudioSpritePacker({ adapter: new MyAdapter() });
  try {
    return packer.unpack(sprite, name);
  } catch (err) {
    if (err instanceof AudioSpriteError && err.code === AUDIO_SPRITE_CODES.CLIP_NOT_FOUND) {
      console.warn(`Clip "${name}" missing from sprite`);
      return null;
    }
    throw err;
  }
}

Usage: Advanced Example

import {
  AudioSpriteError,
  AUDIO_SPRITE_CODES,
  AUDIO_SPRITE_ERROR_METADATA,
} from "@suaveplan/audio-sprite-packer";

function handleSpriteError(err: unknown) {
  if (err instanceof AudioSpriteError) {
    const meta = AUDIO_SPRITE_ERROR_METADATA[err.code];
    console.error(`[${meta.severity}] ${meta.description}`);

    if (err.code === AUDIO_SPRITE_CODES.ABORTED) {
      // Warning-level; safe to retry.
      return "aborted";
    }
    throw err;
  }
}

API Reference

AUDIO_SPRITE_CODES

A frozen record of error-code constants created via defineCodes("AUDIO_SPRITE", [...]).

• UNSUPPORTED_FORMAT
• DECODE_FAILED
• ENCODE_FAILED
• CLIP_NOT_FOUND
• INVALID_OPTIONS
• EMPTY_INPUT
• INVALID_MANIFEST
• ABORTED

AudioSpriteErrorCode

type AudioSpriteErrorCode = (typeof AUDIO_SPRITE_CODES)[keyof typeof AUDIO_SPRITE_CODES];

The union of all values contained in AUDIO_SPRITE_CODES.

AudioSpriteErrorMetadata

interface AudioSpriteErrorMetadata {
  readonly description: string;
  readonly severity: "warning" | "error";
}

Describes the human-readable explanation and severity for a single error code.

AUDIO_SPRITE_ERROR_METADATA

const AUDIO_SPRITE_ERROR_METADATA: Readonly<Record<AudioSpriteErrorCode, AudioSpriteErrorMetadata>>

Frozen lookup table that maps every AudioSpriteErrorCode to its metadata. Useful for localising or logging errors without parsing exception messages.

AudioSpriteError

class AudioSpriteError extends SuaveplanError<AudioSpriteErrorCode> {}

The exception type thrown by @suaveplan/audio-sprite-packer. Its code property is constrained to AudioSpriteErrorCode, allowing consumers to branch on specific failure modes. The constructor is public (widened from the protected SuaveplanError base constructor).

Throws:

• This class is thrown, not caught internally.

registerAudioSpriteErrorCodes(): void

An idempotent hook that exists for compatibility with the @suaveplan/error registration lifecycle. The metadata is already frozen and exported, so the function body is empty. It is invoked automatically at module load time.

Implementation Notes

• The module depends on @suaveplan/error for defineCodes and the base SuaveplanError class.
• AUDIO_SPRITE_ERROR_METADATA is frozen with Object.freeze so that downstream code cannot accidentally mutate severity or descriptions at runtime.
• registerAudioSpriteErrorCodes is called immediately after definition, ensuring the codes are available as soon as the module is imported.