Repository navigation
Core Concepts
-
Layer A — the core.
@dusrel/image-coreis a tiny, zero-dependency engine built oncreateImageBitmap+OffscreenCanvas/Canvas 2D. It decodes (EXIF-aware), crops, rotates, flips, resizes and encodes JPEG/PNG/WebP — and it is all the flagship@dusrel/imageneeds for the common case. -
Layer B — the codec and feature packages. Real codecs (MozJPEG,
libwebp, libavif, libjxl, the Rust
pngcrate, …) 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.
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.
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.
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 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 |
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.
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
-
@dusrel/image-coreexportsinstallWorkerHandler()— the RPC half of the engine, ready to drop into your own worker. -
@dusrel/image-batchexportscreateWorkerPool(url, { size })andrunBatch/BatchQueuefor pool-based batch work with retries, per-item timeouts and memory caps.
Next: Cookbook · Package Guide
Released under the MIT License · © 2026 Dus Mamud · A Dusrel project · The HEIC engine (libheif/libde265) is LGPL-3.0, fenced to @dusrel/image-heic · Docs · Playground
Start here
Reference
Project
Elsewhere