Skip to content

Core Concepts

Dus Mamud edited this page Nov 9, 2026 · 1 revision

Core Concepts

Two layers

  • Layer A — the core. @dusrel/image-core is a tiny, zero-dependency engine built on createImageBitmap + OffscreenCanvas/Canvas 2D. It decodes (EXIF-aware), crops, rotates, flips, resizes and encodes JPEG/PNG/WebP — and it is all the flagship @dusrel/image needs for the common case.
  • Layer B — the codec and feature packages. Real codecs (MozJPEG, libwebp, libavif, libjxl, the Rust png crate, …) compiled to WASM, each its own @dusrel/ sub-package: separately installable, separately lazy-loaded, ESM-only, worker-ready. No codec WASM is ever bundled into the core.

One options object

Every operation takes a single options object. Every async operation accepts an AbortSignal (signal) and, where progress is meaningful, an onProgress callback. Core quality is 0..1; codec packages use their native scales, documented per package.

Step order

Processing always runs in this order, no matter how the options were written:

crop → transform → resize → adjust → watermark → encode

Consecutive canvas operations are merged into a single pass by the pipeline builder — you describe steps, the engine avoids re-decoding between them.

Plugins and codec registration

Two extension points, both first-class:

  • imageDataPlugin({ name, transform }) — transform decoded pixels (this is how adjust, watermark and your own pixel code plug in).
  • codecPlugin({ mimeType, encode }) — register a WASM encoder as an output format.

processImage() honours options.plugins, and any format registered via options.codecs becomes selectable as format. Asking for an unregistered format fails fast with a typed unsupported-format error — before any processing happens. Plugin failures surface as typed plugin-failed errors; an abort stays an abort (aborted).

Fallback policies

fallback decides what happens when the requested format or codec is unavailable:

Policy Behaviour
throw (default) Fail with a typed error
return-original Hand back the untouched input
downgrade-format Encode with the best available fallback format

The process report

Every run returns a ProcessReport next to the blob:

Field Meaning
engine Which engine ran ("canvas" for the core path)
originalBytes / finalBytes Input and output sizes
savingsRatio How much smaller (or larger) the result is
width / height Output dimensions
format The format actually produced
stepsApplied The steps that ran, in order (e.g. ["resize", "codec:avif"])
durationMs Wall-clock time
fallbacks Any fallbacks that were taken

Byte budgets are honest: when maxSizeBytes can't be met, the result says so (targetSizeMet) instead of silently returning a bigger file.

Typed errors

All failures are DusrelImageErrors with a stable string code (narrow with isDusrelImageError):

aborted · decode-failed · encode-failed · invalid-input · invalid-options · platform-unsupported · plugin-failed · unsupported-format

Workers

  • @dusrel/image-core exports installWorkerHandler() — the RPC half of the engine, ready to drop into your own worker.
  • @dusrel/image-batch exports createWorkerPool(url, { size }) and runBatch / BatchQueue for pool-based batch work with retries, per-item timeouts and memory caps.

Next: Cookbook · Package Guide

Clone this wiki locally