Universal image metadata extraction, format detection, resize math, crop validation, and transform pipeline planning. Zero browser or Node dependencies — runs in Bun, Node, and browsers alike. Provides ImageProcessor for planning image transforms, PipelineBuilder for fluent composition, and header-based dimension parsers for JPEG, PNG, WebP, GIF, and AVIF.

Documentation tree

error-codes — error-codes.ts declares the canonical error-code registry for @suaveplan/image. Every failure mode that the image p…
- error-codes — error-codes.ts declares the canonical error-code registry for @suaveplan/image. Every failure mode that the image p…
errors — errors.ts provides the typed error hierarchy for @suaveplan/image. ImageError extends SuaveplanError so that ca…
- errors — errors.ts provides the typed error hierarchy for @suaveplan/image. ImageError extends SuaveplanError so that ca…
dimensions — dimensions.ts extracts width and height from raw image headers for the four supported raster formats: PNG, JPEG, GIF,…
- dimensions — dimensions.ts extracts width and height from raw image headers for the four supported raster formats: PNG, JPEG, GIF,…
instruments — instruments.ts lazily initialises the OpenTelemetry counters and histograms used by ImageProcessor. Each instrument…
- instruments — instruments.ts lazily initialises the OpenTelemetry counters and histograms used by ImageProcessor. Each instrument…
pipeline-builder — pipeline-builder.ts implements a fluent, chainable API for constructing image transform pipelines. Each method append…
- pipeline-builder — pipeline-builder.ts implements a fluent, chainable API for constructing image transform pipelines. Each method append…
processor — processor.ts is the orchestration layer of @suaveplan/image. ImageProcessor accepts a Uint8Array of image bytes…
- processor — processor.ts is the orchestration layer of @suaveplan/image. ImageProcessor accepts a Uint8Array of image bytes…
image-detect — image-detect.ts provides fast, deterministic format detection from raw binary headers. It inspects the first bytes of…
- image-detect — image-detect.ts provides fast, deterministic format detection from raw binary headers. It inspects the first bytes of…
image-types — image-types.ts is the universal type system and pure-function toolkit for image metadata. It defines Zod schemas…
- image-types — image-types.ts is the universal type system and pure-function toolkit for image metadata. It defines Zod schemas…

Installation

bun add @suaveplan/image

Quick Start

import { ImageProcessor } from "@suaveplan/image";

const proc = new ImageProcessor({ maxPixels: 50_000_000 });
const meta = proc.extractMetadata(imageBytes);
console.log(`${meta.format} ${meta.width}x${meta.height}`);

const result = proc.planTransform(meta, {
    operations: [
        { type: "resize", options: { width: 400 } },
        { type: "format", format: "webp" },
    ],
});

Modules

src/processor/processor/processor.md — ImageProcessor and PipelineBuilder
src/processor/instruments/instruments.md — OpenTelemetry instrumentation helpers
src/processor/dimensions/dimensions.md — Header dimension parsers for JPEG, PNG, WebP, GIF, AVIF
src/processor/pipeline-builder/pipeline-builder.md — Fluent transform pipeline builder
src/types/image-types/image-types.md — TypeScript interfaces and Zod schemas
src/types/image-detect/image-detect.md — Format detection types and constants
src/errors/errors.md — ImageError hierarchy and typed factories
src/error-codes/error-codes.md — Stable IMAGE.* error code registry