metadata-error

(no submodules)

Purpose

Provides the stable error code registry (METADATA_CODES) and the MetadataError class used by every module in @suaveplan/audio-metadata. Centralising error identifiers in one place guarantees that callers can branch on a well-known string constant rather than pattern-matching on human-readable messages, which are subject to change.

The package intentionally does not extend @suaveplan/error's SuaveplanError — @suaveplan/audio-metadata is a leaf package that carries no @suaveplan/* runtime dependencies, keeping its install footprint minimal for both Node.js and browser environments.

Features

Three stable error codes: UNSUPPORTED_FORMAT, PARSE_ERROR, FETCH_FAILED
MetadataError extends Error and exposes a typed code property
name is always "MetadataError" for easy instanceof / error.name branching
Exported MetadataCode union type for use in catch-block type narrowing

Usage: Basic Example

import { MetadataError, METADATA_CODES } from "@suaveplan/audio-metadata/errors";

try {
  // ... parse audio buffer
} catch (err) {
  if (err instanceof MetadataError && err.code === METADATA_CODES.PARSE_ERROR) {
    console.error("Malformed audio data:", err.message);
  }
}

Usage: Advanced Example

import { MetadataError, METADATA_CODES, type MetadataCode } from "@suaveplan/audio-metadata/errors";

function handleMetadataError(err: MetadataError): never {
  const actions: Record<MetadataCode, () => never> = {
    [METADATA_CODES.UNSUPPORTED_FORMAT]: () => { throw new Error("Format not supported by this build"); },
    [METADATA_CODES.PARSE_ERROR]:        () => { throw new Error("Audio data is corrupt"); },
    [METADATA_CODES.FETCH_FAILED]:       () => { throw new Error("Network failure — retry later"); },
  };
  return actions[err.code]();
}

API Reference

`METADATA_CODES`

const METADATA_CODES: {
  UNSUPPORTED_FORMAT: "METADATA.UNSUPPORTED_FORMAT";
  PARSE_ERROR:        "METADATA.PARSE_ERROR";
  FETCH_FAILED:       "METADATA.FETCH_FAILED";
}

Immutable as const object containing every stable error code string.

`MetadataCode`

type MetadataCode = "METADATA.UNSUPPORTED_FORMAT" | "METADATA.PARSE_ERROR" | "METADATA.FETCH_FAILED";

Union of all code values for use in type narrowing.

`MetadataError`

class MetadataError extends Error {
  readonly code: MetadataCode;
  constructor(message: string, code: MetadataCode);
}

Member	Type	Description
`message`	`string`	Human-readable description of the failure
`code`	`MetadataCode`	Stable machine-readable identifier
`name`	`"MetadataError"`	Always set for `instanceof`-free discrimination

Implementation Notes

The name property is assigned in the constructor body (not via a class-level initialiser) to ensure it survives TypeScript's super() call ordering and remains correct when the class is extended. The code field is readonly to prevent accidental mutation after construction. No external dependencies are used — this file is intentionally dependency-free so it can be imported by any part of the package without creating cycles.

3.2 KiB Raw Blame History