Public API and runtime contracts.

ImageLibrary

Create a frozen library with the codec implementations your application accepts. Registration order is preserved in formats(); duplicate format names are rejected.

function createImageLibrary(registration: Iterable<ImageCodec> | ImageLibraryConfiguration): ImageLibrary

interface ImageLibrary {
  formats(): readonly string[]
  open(input: ImageInput, options?: ImageOpenOptions): Promise<Image>
}

interface ImageOpenOptions {
  frame?: number
  resolutionLevel?: number
  tolerantDecoding?: boolean
  limits?: ImageLimitOptions
}

Codec imports

allCodecs contains the nine default codecs and intentionally excludes experimental HEIF/HEIC.

Experimental HEIC opt-in

import { createImageLibrary } from 'purejsimage'
import { allCodecs } from 'purejsimage/codecs/all'
import { experimentalHeicCodec } from 'purejsimage/codecs/experimental/heic'

const images = createImageLibrary({
  codecs: [...allCodecs, experimentalHeicCodec],
})

TIFF documents, rasters, and profiles

purejsimage/tiff exposes the validated TIFF IFD graph independently of the display-image pipeline. openTiffDocument(source, options?) returns a TiffDocument with stable top-level and SubIFD directory objects. Each TiffDirectory exposes its absolute source offset; getDirectoryByOffset(offset) resolves parsed metadata pointers. A directory reads bounded, cached public tag values and creates either an ImageDecoder for display pixels or a RasterDecoder for native-precision, arbitrary-channel samples. readBytes(offset, length, { maxBytes }) performs an exact bounded private-metadata read and returns a defensive copy without exposing the underlying ImageSource.

import { MemorySource } from 'purejsimage'
import { openOmeTiff } from 'purejsimage/scientific'
import { openTiffDocument } from 'purejsimage/tiff'

const document = await openTiffDocument(new MemorySource(bytes))
const dataset = await openOmeTiff(document)
for await (const block of dataset.readPlane({
  z: 0, c: [0, 1, 2], t: 0, resolutionLevel: 0,
  x: 0, y: 0, width: 512, height: 512,
})) {
  consume(block)
}

openOmeTiff() validates OME dimensions, sample type, channel metadata, physical pixel size, dimension order, and explicit or implicit TiffData mappings before exposing a MultidimensionalRasterDataset. readPlane() preserves native sample types and can combine separately stored channel planes without materializing a source-sized display bitmap.

purejsimage/pathology exports openAperioSvs(), aperioSvsProfile, and the generic WholeSlideImage contract. Aperio levels and label, macro, or thumbnail images decode by requested region. TIFF compression tags 33003 and 33005 use the reusable createJpeg2000CodestreamDecoder(); JPEG 2000 reconstruction remains bounded to the current TIFF tile or strip, though the current codestream decoder retains that segment's complete component state.

Third-party TIFF profile authoring

A separately shipped integration implements TiffProfile<T> using only package exports. Register profiles with createTiffProfileRegistry(). Detection runs every profile in isolation, orders matches by descending integer priority then id, reports detector failures, and rejects equal-priority matches as ambiguous. For an explicitly selected profile, registry.openWith(document, profile) preserves T and returns Promise<T>.

import { createTiffProfileRegistry } from 'purejsimage/tiff'
import type { TiffProfile } from 'purejsimage/tiff'

export const vendorProfile: TiffProfile<VendorDataset> = {
  id: 'vendor-format',
  priority: 50,
  async detect({ document }) {
    const tag = await document.topLevelDirectories[0]?.getTag(270, {
      maxBytes: 1024 * 1024,
    })
    return tag?.kind === 'ascii' && tag.value.startsWith('Vendor')
  },
  async open({ document }) {
    const pointer = await document.topLevelDirectories[0]?.getTag(65000, {
      maxBytes: 24,
    })
    if (pointer?.kind !== 'numbers') throw new Error('Vendor pointer is missing')
    const directory = document.getDirectoryByOffset(pointer.values[0] ?? -1)
    if (!directory) throw new Error('Vendor IFD is missing')
    const length = pointer.values[2] ?? -1
    const metadata = await document.readBytes(
      pointer.values[1] ?? -1, length, { maxBytes: 1024 * 1024 },
    )
    return openVendorDataset(directory, metadata)
  },
}

const registry = createTiffProfileRegistry([vendorProfile])
const dataset = await registry.openWith(document, vendorProfile)

See the dedicated TIFF guide for the complete supported-format list, scientific and whole-slide workflows, output profile, memory model, and current limitations →

Zstandard decompression

The portable purejsimage/compression/zstd subpath exports the reusable first-party decoder used by TIFF Compression=50000. It has no format-specific parameters and does not load native code, WebAssembly, or a runtime dependency.

import { decodeZstd } from 'purejsimage/compression/zstd'

const output = decodeZstd(compressed, {
  expectedOutputBytes: 8192,
  maxOutputBytes: 8192,
  maxWindowBytes: 64 * 1024 * 1024,
})

maxOutputBytes and maxWindowBytes default to 64 MiB. Supplying expectedOutputBytes preallocates the exact bounded output and rejects a different decoded size. Dictionary-dependent frames fail with UNSUPPORTED_OPERATION.

Optional WASM acceleration

JPEG and PNG provide first-party WebAssembly accelerators as explicit package entries. The root, browser, and codec imports never load them automatically. Register either provider through ImageLibraryConfiguration; ineligible or unavailable work continues through the corresponding TypeScript codec.

import { createImageLibrary } from 'purejsimage'
import { wasmJpegAccelerator } from 'purejsimage/accelerators/wasm/jpeg'
import { wasmPngAccelerator } from 'purejsimage/accelerators/wasm/png'
import { allCodecs } from 'purejsimage/codecs/all'

const images = createImageLibrary({
  codecs: allCodecs,
  accelerators: [wasmJpegAccelerator, wasmPngAccelerator],
})

Browser applications use createImageLibrary from purejsimage/browser; the two accelerator import paths are unchanged and resolve to browser-safe loaders.

Configuration

The ready-made providers use defaults chosen to avoid paying module and copy overhead on small images. Use the factory exports when an application needs different thresholds or input limits.

interface WasmJpegAcceleratorOptions {
  minimumPixels?: number
  minimumEncodePixels?: number
  maximumInputBytes?: number
  maximumEncoderRowBytes?: number
}

interface WasmPngAcceleratorOptions {
  minimumPixels?: number
  minimumEncodePixels?: number
  maximumRowBytes?: number
}

function createWasmJpegAccelerator(options?: WasmJpegAcceleratorOptions): ImageCodecAccelerator
function createWasmPngAccelerator(options?: WasmPngAcceleratorOptions): ImageCodecAccelerator

Both pixel thresholds default to 65,536. JPEG accepts at most 32 MiB of compressed input and a 16 MiB encoder row by default; PNG accepts at most a 16 MiB row. Every supplied value must be a positive integer.

Eligible workflows

Image

Every transform returns a new immutable Image sharing the same input context. No pixel work occurs until an output method is called.

Operation options

CropOptions

interface CropOptions {
  x: number
  y: number
  width: number
  height: number
}

ResizeOptions

type ResizeFit = 'contain' | 'cover' | 'fill' | 'inside' | 'outside'
type ResizeKernel = 'nearest' | 'bilinear' | 'lanczos3'
type Background = 'transparent' | `#${string}`

type ResizeOptions = {
  width?: number
  height?: number
  fit?: ResizeFit
  position?: 'center'
  background?: Background
  withoutEnlargement?: boolean
  kernel?: ResizeKernel
} // width or height is required

WindowOptions and LutOptions

interface WindowOptions {
  center: number
  width: number
}

interface LutOptions {
  table: Uint8Array // 256 × output channel count, interleaved
  format: 'gray8' | 'rgb8' | 'rgba8'
}

Windowing precedes geometric transforms and converts native numeric grayscale blocks directly to gray8. A grayscale LUT treats each table entry as an output color. An RGBA LUT maps each input channel through the corresponding interleaved channel table.

RotateOptions

interface RotateOptions {
  background?: Background // transparent by default
}

Positive degrees rotate clockwise. Arbitrary angles expand to the smallest integer canvas that contains the result and use the requested six- or eight-digit hex background, or transparency by default.

Encoder options

interface JpegEncodeOptions {
  quality?: number                // 1–100
  progressive?: boolean          // refinement-based output; false by default
  background?: Background
  chromaSubsampling?: '420' | '422' | '444'
  restartInterval?: number       // 0–65535; 0 disables restart markers
}

interface PngEncodeOptions { compressionLevel?: number } // 0–9
interface WebpEncodeOptions { lossless?: boolean; quality?: number }
interface BmpEncodeOptions { alpha?: boolean }
interface TiffEncodeOptions {
  compression?: 'deflate'
  predictor?: 'horizontal'
  layout?: 'strips'
  compressionLevel?: number       // 0–9; browser supports 6
}

EXIF and ICC preservation

Encoders strip EXIF and ICC metadata unless the pipeline calls keepExif() or keepIcc(). The two choices are independent and apply when the pipeline executes.

With keepIcc(), tagged samples remain in their source color space and the original profile is embedded in the output, avoiding a double conversion. The profile must match the output pixel model. With keepExif(), autoOrient(), rotate(), flip(), and flop() normalize a retained EXIF orientation to 1 because the pixels have already moved.

ImageMetadata

interface ImageMetadata {
  width: number
  height: number
  format: string
  mimeType: string
  hasAlpha: boolean
  orientation?: number
  colorSpace?: string
  colorProfile?:
    | { kind: 'icc'; description?: string }
    | {
        kind: 'nclx'
        primaries: number
        transferCharacteristics: number
        matrixCoefficients: number
        fullRange: boolean
      }
  bitDepth?: number
  chromaSubsampling?: '400' | '411' | '420' | '422' | '440' | '444'
  codecProfile?: number
  frames?: number
}

Optional fields depend on what the container and registered codec can determine safely. HEIF and AVIF expose validated ICC descriptions when present or the numeric nclx primaries, transfer characteristics, matrix coefficients, and range. Animated formats may report frame counts even when the current pixel decoder handles only a still subset.

Inputs & sources

type BrowserImageInput = ArrayBuffer | Blob | ImageSource | Uint8Array
type NodeImageInput = BrowserImageInput | string

interface ImageSource {
  readonly size: number
  read(offset: number, length: number, options?: { signal?: AbortSignal }): Promise<Uint8Array>
}

For an in-range read, custom read() implementations must return exactly min(length, size - offset) bytes as a Uint8Array, or reject when the backing read fails. Returned bytes may be reused or invalidated when the next read begins. Short, oversized, detached, and rejected reads surface as ImageError results. Public open, metadata, decode, raster, whole-slide, source-read, and terminal output options accept an optional AbortSignal; cancellation aborts the active sink and is rethrown as AbortError.

Safety limits

Pass a partial limits object to open(). Every provided value must be a positive safe integer.

ImageError

type ImageErrorCode =
  | 'INVALID_INPUT'
  | 'LIMIT_EXCEEDED'
  | 'TRUNCATED_INPUT'
  | 'UNSUPPORTED_FORMAT'
  | 'UNSUPPORTED_OPERATION'

Advanced contracts

The Node root and browser entry export the primitives used to author custom codecs, accelerators, and sinks: ImageCodec, ImageCodecAccelerator, ImageLibraryConfiguration, ImageDecoder, ImageEncoder, CodecRegistry, ImageSink, Uint8ArraySink, PixelBlock, PixelFormat, and BufferPool. Node additionally exports BufferSink, FileSink, and FileSource.

These interfaces support custom codecs and sinks. A decoder yields ordered pixel blocks; an encoder consumes them and writes encoded chunks to a sink. Implementations must preserve the release callback and source-buffer lifetime contracts.

View public exports on GitHub →