# API Reference

This guide covers the main API in 1.15.0. The package ships complete TypeScript declarations, including advanced quantization and compositing options. Everything is exported from the package root:

import {
  Transformer,
  losslessCompressPng,
  pngQuantize,
  compressJpeg,
  ChromaSubsampling,
  ResizeFilterType,
  ResizeFit,
  // …enums and option types
} from '@napi-rs/image'

Every async method also accepts a trailing AbortSignal to cancel in-flight work (omitted from signatures below for brevity).

# Transformer

Decode an image, optionally transform it, then encode to any supported format.

# Construction

new Transformer(input: Uint8Array)

// CSS3 colors are accepted for the SVG background, e.g. 'rgba(255,255,255,.8)'
Transformer.fromSvg(input: string | Uint8Array, background?: string | null): Transformer

Transformer.fromRgbaPixels(input: Uint8Array | Uint8ClampedArray, width: number, height: number): Transformer

# Metadata

metadata(withExif?: boolean | null): Promise<Metadata>
metadataSync(withExif?: boolean | null): Metadata

Metadata:

# Encoders

All encoders return a Promise<Buffer> (async) or Buffer (sync). The async variants run on a background thread pool.

webp(qualityFactor?: number | null): Promise<Buffer>   // 0–100; lower = smaller
webpSync(qualityFactor?: number | null): Buffer
webpLossless(): Promise<Buffer>
webpLosslessSync(): Buffer

avif(options?: AvifConfig | null): Promise<Buffer>
avifSync(options?: AvifConfig | null): Buffer

heic(options?: HeicConfig | null): Promise<Buffer>     // macOS / Windows with an OS codec
heicSync(options?: HeicConfig | null): Buffer

png(options?: PngEncodeOptions | null): Promise<Buffer>
pngSync(options?: PngEncodeOptions | null): Buffer

jpeg(quality?: number | null): Promise<Buffer>         // default 90
jpegSync(quality?: number | null): Buffer

// also: bmp, ico, tiff, pnm, tga — each with a *Sync variant, no options

// raw pixels, native-endian byte slice
rawPixels(): Promise<Buffer>
rawPixelsSync(): Buffer

The declared farbfeld() / farbfeldSync() methods reject in the published build because that codec is not enabled. See format support and HEIC restrictions.

# Transforms

Transforms configure the pipeline and return this. Work is applied when reading pixels, metadata or encoded output. The pipeline has a defined transform order; chaining is not a general-purpose sequence of arbitrary operations. Use a fresh Transformer for independent outputs.

resize signature:

resize(
  widthOrOptions: number | ResizeOptions,
  height?: number | null,
  filter?: ResizeFilterType | null,
  fit?: ResizeFit | null,
): this

# Standalone optimizers

Optimize encoded bytes and return new bytes of the same format. Output size depends on the image and options. Async variants take any Uint8Array; some sync variants are typed for Buffer.

losslessCompressPng(input: Uint8Array, options?: PNGLosslessOptions | null): Promise<Buffer>
losslessCompressPngSync(input: Buffer, options?: PNGLosslessOptions | null): Buffer

pngQuantize(input: Uint8Array, options?: PngQuantOptions | null): Promise<Buffer>
pngQuantizeSync(input: Uint8Array, options?: PngQuantOptions | null): Buffer

compressJpeg(input: Uint8Array, options?: JpegCompressOptions | null): Promise<Buffer>
compressJpegSync(input: Uint8Array, options?: JpegCompressOptions | null): Buffer

# Option types

# AvifConfig

The implementation uses speed: 5 in 1.15.0; older declaration comments say 4. Set the value explicitly when comparing outputs.

# HeicConfig

Requires macOS or Windows with the OS codec. See the HEIC guide for alpha, color and precision restrictions.

# JpegCompressOptions

# PngEncodeOptions

# PNGLosslessOptions

# PngQuantOptions

# ResizeOptions / FastResizeOptions

interface ResizeOptions {
  width: number
  height?: number
  filter?: ResizeFilterType
  fit?: ResizeFit
}
interface FastResizeOptions {
  width: number
  height?: number
  filter?: FastResizeFilter
  fit?: ResizeFit
}

# Enums

# ChromaSubsampling

Yuv444 (0, no subsampling) · Yuv422 (1) · Yuv420 (2, common for the web) · Yuv400 (3, grayscale).

# ResizeFilterType

Nearest (0) · Triangle (1) · CatmullRom (2) · Gaussian (3) · Lanczos3 (4).

# FastResizeFilter

Box (0) · Bilinear (1) · Hamming (2) · CatmullRom (3) · Mitchell (4) · Lanczos3 (5).

# ResizeFit

Cover (0, default — preserve aspect, crop to fill) · Fill (1, stretch) · Inside (2, preserve aspect, fit within).

# Orientation

EXIF orientation values 1–8: Horizontal (1) · MirrorHorizontal (2) · Rotate180 (3) · MirrorVertical (4) · MirrorHorizontalAndRotate270Cw (5) · Rotate90Cw (6) · MirrorHorizontalAndRotate90Cw (7) · Rotate270Cw (8).

# CompressionType

Default (0) · Fast (1) · Best (2).

# FilterType

NoFilter (0) · Sub (1) · Up (2) · Avg (3) · Paeth (4) · Adaptive (5).

# PngRowFilter

None (0) · Sub (1) · Up (2) · Average (3) · Paeth (4).

# JsColorType

L8 (0) · La8 (1) · Rgb8 (2) · Rgba8 (3) · L16 (4) · La16 (5) · Rgb16 (6) · Rgba16 (7) · Rgb32F (8) · Rgba32F (9).