inspect()

Format, dimensions, and metadata facts, with no decode and no codec load.

import { inspect } from "@imagekbreducer/image-core"

const info = inspect(bytes) // Uint8Array

inspect() is the entire Image Info tool, and it’s what every recipe in Run a job needs as its source argument. It reads magic bytes and container headers only — no decode, no canvas, no codec load — which is what makes it cheap even against a HEIC file the engine can’t compress without libheif, and why the CLI’s own info command never loads a single codec (see imagekbreducer info).

Return shape

interface SourceInfo {
  format: "jpeg" | "png" | "webp" | "avif" | "heic"
  width: number      // BEFORE EXIF orientation is applied
  height: number
  bytes: number       // size of the original, undecoded file
  orientation?: number  // EXIF tag 1-8; absent or 1 means no reorientation needed
  hasAlpha?: boolean
  isAnimated?: boolean
  hasExif?: boolean
  hasGps?: boolean
  hasIptc?: boolean
  hasXmp?: boolean
}

width/height are the RAW decoded dimensions, before EXIF orientation — the space the bytes are actually stored in, not necessarily the space a viewer displays them in. A portrait phone photo stored sideways with an orientation tag reports its stored (sideways) dimensions here; if you need the dimensions a person would actually see, use orientedSize — the same helper the CLI’s own target-unreachable suggestion sentences use internally to avoid reporting a portrait photo’s size sideways — also available from the root import:

import { orientedSize } from "@imagekbreducer/image-core"

const { width, height } = orientedSize({ width: info.width, height: info.height }, info.orientation)

hasExif/hasGps/hasIptc/hasXmp never affect the pipeline — no job conditions on them — they exist purely to be surfaced, the way the CLI’s info --json and human table both do.

What it refuses, and why

inspect() throws ImageCoreError rather than returning a “sort of valid” result for input it can’t honestly describe:

`ErrorCode`	When
`decode-failed`	the file is empty (0 bytes) — not a format problem, so it gets its own message rather than “unrecognized format”
`unsupported-format`	the bytes are an SVG (a script-capable document, never accepted, regardless of what a raster-only tool would do with one), a GIF, a BMP, or anything else that doesn’t sniff as jpeg/png/webp/avif/heic
`input-too-large`	the byte count exceeds the configured ceiling — checked before the format/dimension checks below, so an oversized file is refused as cheaply as possible
`dimension-exceeded`	decoded dimensions exceed the configured pixel ceiling

A renamed SVG (photo.svg saved as photo.png) is refused by its real, sniffed content, not its extension — inspect() never trusts a filename.

import { inspect } from "@imagekbreducer/image-core"

try {
  const info = inspect(bytes)
} catch (error) {
  // error.code is one of the four above; error.message is written to be
  // shown to a user directly, not just logged.
}