first commit

docs/media/audio/audio-metadata/src/errors/metadata-error.md

@@ -0,0 +1,87 @@
+# metadata-error
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## 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
+
+```ts
+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
+
+```ts
+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`
+
+```ts
+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`
+
+```ts
+type MetadataCode = "METADATA.UNSUPPORTED_FORMAT" | "METADATA.PARSE_ERROR" | "METADATA.FETCH_FAILED";
+```
+
+Union of all code values for use in type narrowing.
+
+### `MetadataError`
+
+```ts
+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.