@nutshelllabs/image

Image parsing and resolution library for react-pdf. Handles PNG and JPEG images from various sources including local files, remote URLs, base64 data URIs, buffers, and blobs.

Installation

yarn add @nutshelllabs/image

Usage

import resolveImage from '@nutshelllabs/image';

const image = await resolveImage({ uri: './path/to/image.png' });

console.log(image.width); // Image width in pixels
console.log(image.height); // Image height in pixels
console.log(image.format); // 'png' or 'jpeg'
console.log(image.data); // Buffer containing image data

Image Sources

The library supports multiple image source types:

Local File

const image = await resolveImage({ uri: './image.png' });
// or
const image = await resolveImage({ uri: '/absolute/path/to/image.jpg' });

Note: Local file resolution is only available in Node.js environments.

Remote URL

const image = await resolveImage({ uri: 'https://example.com/image.png' });

With custom request options:

const image = await resolveImage({
  uri: 'https://example.com/image.png',
  method: 'GET',
  headers: {
    Authorization: 'Bearer token',
  },
  body: null,
  credentials: 'include',
});

Base64 Data URI

const image = await resolveImage({
  uri: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
});

Buffer

import fs from 'fs';

const buffer = fs.readFileSync('./image.png');
const image = await resolveImage(buffer);

Blob (Browser)

const response = await fetch('https://example.com/image.png');
const blob = await response.blob();
const image = await resolveImage(blob);

Data Object

const image = await resolveImage({
  data: imageBuffer,
  format: 'png', // 'png', 'jpg', or 'jpeg'
});

Caching

Images are cached by default to avoid redundant processing. You can disable caching for individual requests:

const image = await resolveImage({ uri: './image.png' }, { cache: false });

The cache has a default limit of 30 entries and uses LRU (Least Recently Used) eviction.

Types

Image

The resolved image object:

interface Image {
  width: number;
  height: number;
  data: Buffer;
  format: 'jpeg' | 'png';
  key?: string;
}

ImageSrc

All supported image source types:

type ImageSrc =
  | Blob
  | Buffer
  | DataImageSrc
  | LocalImageSrc
  | RemoteImageSrc
  | Base64ImageSrc;

type DataImageSrc = {
  data: Buffer;
  format: 'jpg' | 'jpeg' | 'png';
};

type LocalImageSrc = {
  uri: string;
  format?: 'jpg' | 'jpeg' | 'png';
};

type RemoteImageSrc = {
  uri: string;
  method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
  headers?: Record<string, string>;
  format?: 'jpg' | 'jpeg' | 'png';
  body?: any;
  credentials?: 'omit' | 'same-origin' | 'include';
};

type Base64ImageSrc = {
  uri: `data:image${string}`;
};

Supported Formats

• PNG - Portable Network Graphics
• JPEG/JPG - Joint Photographic Experts Group

JPEG images with EXIF orientation data are automatically handled, with width and height adjusted accordingly.

License

MIT