# @suaveplan/streams-metadata - Universal stream transforms that detect MIME type and extract EXIF/IPTC/XMP image metadata via @suaveplan/streams BaseTransform

Universal stream transforms that detect MIME type and extract
EXIF/IPTC/XMP image metadata from buffered `Uint8Array` payloads. Three
composable transforms (`MimeTransform`, `ExifTransform`, and the wrapping
`MetadataTransform`) each extend `BaseTransform` from `@suaveplan/streams`
and expose a typed event surface through the inherited `on`/`off` API.

<!-- begin:auto-docs -->
## Documentation tree

- [errors](./src/errors/errors.md) — Stable error registry for the `@suaveplan/streams-metadata` package. Every failure surface produced by `MimeTransform`,…
  - [errors](./src/errors/errors.md) — Stable error registry for the `@suaveplan/streams-metadata` package. Every failure surface produced by `MimeTransform`,…
- [events](./src/events/events.md) — Declares the typed `StreamsMetadataEvents` map consumed by every transform in this package. `BaseTransform` fro…
  - [events](./src/events/events.md) — Declares the typed `StreamsMetadataEvents` map consumed by every transform in this package. `BaseTransform` fro…
- [exif](./src/exif/exif.md) — `ExifTransform` is a universal stream transform that extracts `ImageMetadata` via `@suaveplan/exif::readMetadata`…
  - [exif](./src/exif/exif.md) — `ExifTransform` is a universal stream transform that extracts `ImageMetadata` via `@suaveplan/exif::readMetadata`…
- [metadata](./src/metadata/metadata.md) — `MetadataTransform` is the high-level composing wrapper around `MimeTransform` and `ExifTransform`. A single instance r…
  - [metadata](./src/metadata/metadata.md) — `MetadataTransform` is the high-level composing wrapper around `MimeTransform` and `ExifTransform`. A single instance r…
- [mime](./src/mime/mime.md) — `MimeTransform` is a universal stream transform that decides the MIME type of a buffered binary payload and (in `e…
  - [mime](./src/mime/mime.md) — `MimeTransform` is a universal stream transform that decides the MIME type of a buffered binary payload and (in `e…
- [payload](./src/types/payload.md) — Public type contract shared by every `@suaveplan/streams-metadata` transform. Callers and library code agree on the sha…
- [process-options](./src/types/process-options.md) — Defines the `ProcessOptions` shape accepted by every `@suaveplan/streams-metadata` transform's `process(input, options?…
<!-- end:auto-docs -->

## Install

```bash
bun add @suaveplan/streams-metadata
```

## Quick start

```ts
import { MetadataTransform } from "@suaveplan/streams-metadata";

const transform = new MetadataTransform();
const result = await transform.process({ bytes: imageBytes, name: "photo.jpg" });

console.log(result.mime?.mimeType); // "image/jpeg"
console.log(result.exif?.width);    // 1920
```

## Manual composition

Use `MimeTransform` and `ExifTransform` separately when you need
fine-grained control over each stage or want to run only one of them:

```ts
import { ExifTransform, MimeTransform } from "@suaveplan/streams-metadata";

const mime = new MimeTransform();
const exif = new ExifTransform({ read: { skipXmp: true } });

mime.on("mime:detected", (r) => console.log("MIME:", r.mimeType, "(source:", r.source, ")"));
exif.on("exif:detected", (m) => console.log("Dimensions:", m.width, "x", m.height));

const afterMime = await mime.process({ bytes: imageBytes, name: "photo.jpg" });
const afterExif = await exif.process(afterMime);
```

## Error handling

`MetadataTransform` catches errors from either child transform, emits
`metadata:error` with the thrown value, and returns the original input
reference so the pipeline continues. `MimeTransform` never throws for
unknown bytes — the fallback is `application/octet-stream`. `ExifTransform`
wraps every reader exception as `ExifFailedError`
(`STREAMS_METADATA.EXIF_FAILED`) preserving the original `cause`.

## Modules

- [`src/mime/mime.md`](src/mime/mime.md) — MIME detection from magic bytes
  and file extension.
- [`src/exif/exif.md`](src/exif/exif.md) — EXIF / IPTC / XMP image metadata
  extraction via `@suaveplan/exif`.
- [`src/metadata/metadata.md`](src/metadata/metadata.md) — composing
  wrapper around both transforms with event forwarding.
- [`src/events/events.md`](src/events/events.md) — full
  `StreamsMetadataEvents` reference.
- [`src/errors/errors.md`](src/errors/errors.md) — `StreamsMetadataError`,
  factory subclasses, and the `STREAMS_METADATA_CODES` registry.
- [`src/types/payload.md`](src/types/payload.md) — `MetadataPayload`,
  `EnrichedPayload`, `MimeDetectionResult`, `MetadataMode`.
- [`src/types/process-options.md`](src/types/process-options.md) — runtime
  `ProcessOptions` shape (signal / clock / logger) accepted by every
  transform.