@portable/image-size

Functions

`ImageSize.parse`

Returns the type and dimensions of the image in bytes. The bytes need only cover the header: a few dozen bytes for most formats, up to the first frame header for JPEG.

function parse(bytes: Uint8Array): Size;

Throws

UnsupportedError The bytes don't match a supported format.
TruncatedError The bytes end before the dimensions.
InvalidInputError The header is malformed.

import * as ImageSize from '@portable/image-size';
 
const bytes = new Uint8Array(
  await (await fetch('https://example.com/photo.jpg')).arrayBuffer(),
);
ImageSize.parse(bytes); // { width: 1600, height: 1200, type: 'jpg' }

`ImageSize.parseStream`

Reads stream only until the image's dimensions are known, then cancels it.

async function parseStream(
  stream: ReadableStream<Uint8Array>,
  options: parseStream.Options = {},
): Promise<Size>;

Option	Type	Default	Description
`maxBytes`	`number`	`524288`	The most bytes to buffer. If the dimensions aren't in the first `maxBytes` bytes, `parseStream` cancels the stream and rejects with `MaxBytesError`.
`signal`	`AbortSignal`		Rejects with `signal.reason` when aborted, and cancels the stream.

Throws

UnsupportedError The bytes don't match a supported format.
TruncatedError The stream ends before the dimensions.
MaxBytesError maxBytes is reached before the dimensions.
signal.reason when signal is aborted.
InvalidInputError The header is malformed.

import * as ImageSize from '@portable/image-size';
 
const response = await fetch('https://example.com/photo.jpg');
const { width, height } = await ImageSize.parseStream(response.body!);

Errors

`ImageSize.InvalidInputError`

Thrown when the input starts like a supported format but its header is malformed.

class InvalidInputError extends Errors.InvalidInputError {
  readonly kind: string;
}

import * as ImageSize from '@portable/image-size';
 
try {
  ImageSize.parse(new TextEncoder().encode('<svg width="10"></svg>'));
} catch (error) {
  if (error instanceof ImageSize.InvalidInputError) {
    console.log(error.message); // 'Invalid SVG'
  }
}

`ImageSize.MaxBytesError`

Thrown by parseStream when it has read maxBytes and the dimensions still aren't in them. Raise maxBytes, or treat the image as too large to measure.

class MaxBytesError extends Errors.MaxBytesError {
  constructor(options: Errors.MaxBytesError.Options);
  readonly kind: string;
}

import * as ImageSize from '@portable/image-size';
 
try {
  await ImageSize.parseStream(response.body!, { maxBytes: 64 * 1024 });
} catch (error) {
  if (error instanceof ImageSize.MaxBytesError) {
    console.log(`no size in ${error.maxBytes} bytes`);
  }
}

`ImageSize.TruncatedError`

Thrown when the input ends before the bytes that hold the dimensions.

class TruncatedError extends Errors.TruncatedError {
  constructor(
    message: string = 'Image data ended before its dimensions.',
    options?: ErrorOptions,
  );
  readonly kind: string;
}

import * as ImageSize from '@portable/image-size';
 
const png = new Uint8Array([
  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
]);
try {
  ImageSize.parse(png);
} catch (error) {
  if (error instanceof ImageSize.TruncatedError) {
    console.log('need more bytes');
  }
}

`ImageSize.UnsupportedError`

Thrown when the bytes don't match any supported image format.

class UnsupportedError extends Errors.UnsupportedError {
  constructor(
    message: string = 'Unsupported image type.',
    options?: ErrorOptions,
  );
  readonly kind: string;
}

import * as ImageSize from '@portable/image-size';
 
try {
  ImageSize.parse(new TextEncoder().encode('hello world'));
} catch (error) {
  if (error instanceof ImageSize.UnsupportedError) {
    console.log('not an image');
  }
}

Types

`ImageSize.Image`

One image of a multi-image file. ICNS entries include their icon type, such as ic08.

type Image = {
  width: number;
  height: number;
  type?: string | undefined;
};

`ImageSize.Size`

The type and dimensions of an image, in the shape image-size returns.

type Size = {
  width: number;
  height: number;
  type: Type;
  orientation?: number | undefined;
  images?: readonly Image[] | undefined;
};

`ImageSize.Type`

The detected format. HEIF files report their brand (avif, heic, mif1 and so on), KTX 2 reports ktx2, and BigTIFF reports bigtiff.

type Type =  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | ;