BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Coconstructor
Bun

constructor

Image.constructor

constructor Image(
input: string | ArrayBuffer | TypedArray<ArrayBufferLike> | Blob,
options?: ConstructorOptions
): Image;

Referenced types

class ArrayBuffer

Represents a raw buffer of binary data, which is used to store data for the different typed arrays. ArrayBuffers cannot be read from or written to directly, but can be passed to a typed array or DataView Object to interpret the raw buffer as needed.

  • readonly [Symbol.toStringTag]: string
  • readonly byteLength: number

    Read-only. The length of the ArrayBuffer (in bytes).

  • newByteLength?: number
    ): void;

    Resizes the ArrayBuffer to the specified size (in bytes).

    MDN

    byteLength: number

    Resize an ArrayBuffer in-place.

  • begin: number,
    end?: number

    Returns a section of an ArrayBuffer.

  • newByteLength?: number

    Creates a new ArrayBuffer with the same byte content as this buffer, then detaches this buffer.

    MDN

  • newByteLength?: number

    Creates a new non-resizable ArrayBuffer with the same byte content as this buffer, then detaches this buffer.

    MDN

class Blob

A file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The File interface is based on Blob, inheriting blob functionality and expanding it to support files on the user's system.

MDN Reference

  • readonly size: number
  • readonly type: string

  • Returns a promise that resolves to the contents of the blob as an ArrayBuffer

  • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

    Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

  • formData(): Promise<FormData>;

    Read the data from the blob as a FormData object.

    This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

    The type property of the blob is used to determine the format of the body.

    This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

  • options?: ConstructorOptions
    ): Image;

    Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

    await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");
  • json(): Promise<any>;

    Read the data from the blob as a JSON object.

    This first decodes the data from UTF-8, then parses it as JSON.

  • start?: number,
    end?: number,
    contentType?: string
    ): Blob;

  • Returns a readable stream of the blob's contents

  • text(): Promise<string>;

    Returns a promise that resolves to the contents of the blob as a string

interface ConstructorOptions

  • autoOrient?: boolean

    Apply EXIF Orientation (JPEG) before any other operation.

  • maxPixels?: number

    Reject inputs whose width × height exceeds this many pixels. The check runs after the header is read but before any pixel buffer is allocated, so a tiny file claiming a huge canvas is refused cheaply.

namespace Image

  • interface ConstructorOptions

    • autoOrient?: boolean

      Apply EXIF Orientation (JPEG) before any other operation.

    • maxPixels?: number

      Reject inputs whose width × height exceeds this many pixels. The check runs after the header is read but before any pixel buffer is allocated, so a tiny file claiming a huge canvas is refused cheaply.

  • interface Metadata

  • interface ModulateOptions

    • brightness?: number

      Multiplier; 1 leaves brightness unchanged.

    • saturation?: number

      0 = greyscale, 1 = unchanged, >1 = more saturated.

  • interface ResizeOptions

    • filter?: Filter

      Resampling kernel.

    • fit?: 'fill' | 'inside'

      "fill" stretches to exactly width×height. "inside" preserves aspect ratio so the result fits within width×height.

    • withoutEnlargement?: boolean

      Never upscale — if the source is already smaller, leave it.

  • type ErrorCode = 'ERR_IMAGE_FORMAT_UNSUPPORTED' | 'ERR_IMAGE_TOO_MANY_PIXELS' | 'ERR_IMAGE_DECODE_FAILED' | 'ERR_IMAGE_ENCODE_FAILED' | 'ERR_IMAGE_UNKNOWN_FORMAT' | 'ERR_INVALID_STATE'

    Stable error.code values set on rejections from Bun.Image terminals. Branch on these instead of parsing the message.

    • ERR_IMAGE_FORMAT_UNSUPPORTED — the requested format isn't available on this machine (HEIC/AVIF without the OS codec, TIFF on Linux). Catch this to fall back to a portable format.
    • ERR_IMAGE_TOO_MANY_PIXELS — header dimensions or resize output exceed maxPixels, or a path-backed input is over the 256 MiB cap.
    • ERR_IMAGE_DECODE_FAILED / ERR_IMAGE_ENCODE_FAILED — codec error.
    • ERR_IMAGE_UNKNOWN_FORMAT — input bytes didn't match any sniffer.
    • ERR_INVALID_STATE — the input ArrayBuffer was transferred between construction and the terminal call.
    • File-backed inputs surface the underlying syscall code (ENOENT, EACCES, …) directly.
  • type Filter = 'nearest' | 'box' | 'bilinear' | 'linear' | 'cubic' | 'mitchell' | 'lanczos2' | 'lanczos3' | 'mks2013' | 'mks2021'
  • type Format = 'jpeg' | 'png' | 'webp' | 'heic' | 'avif' | 'bmp' | 'tiff' | 'gif'

    bmp/tiff/gif are decode-only — metadata().format may report them but there are no .bmp()/.tiff()/.gif() encoder methods. tiff decode rejects with error.code === "ERR_IMAGE_FORMAT_UNSUPPORTED" on Linux; gif decodes the first frame everywhere.