89 lines
4.7 KiB
Markdown
89 lines
4.7 KiB
Markdown
# @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.
|
|
|