API Design: dusrel-image
These rules are locked. Any exception needs an ADR.
1. One shape everywhere
Every processing entry point in every sub-package follows the same contract:
- Input: File | Blob | ArrayBuffer | ImageData | ImageBitmap | canvas/image source
- Options object: a single typed options object (never long positional argument lists). All fields optional unless the operation is meaningless without them; defaults are documented per package.
- Controls: every async operation accepts
signal(AbortSignal) andonProgresswhere meaningful. - Result: the processed output plus, from the main pipeline, a report (sizes, dimensions, format, time, fallbacks).
- Errors: typed errors with stable string
codes. No raw DOMExceptions or codec exceptions cross the public API.
2. Two modes, one API
- Easy mode: the main
@dusrel/imagepackage exposes a single-call entry with defaults (sensible quality, target format preserved, metadata stripped, EXIF orientation applied). - Pro mode: the fluent pipeline and the individual sub-packages expose every option: step order, engine selection (native vs WASM per format), quality curves, target-size strategy and iteration caps, worker behaviour, timeouts, fallback policy (
return-original | throw | downgrade-format), and event hooks (onStepStart,onStepComplete,onFallback).
Easy mode is implemented on top of pro mode with default options — there is exactly one engine, never two divergent code paths.
3. Naming
- Packages:
@dusrel/image-<thing>(see README package table). - Functions: verbs (
compress,resize,crop,rotate,convert...). - Options: camelCase, units in the name where ambiguous (
maxSizeBytes,maxWidthOrHeight,qualityis 0..1 everywhere). - Encode and decode are separate exports in codec packages (jSquash model), so decode code is never shipped to encode-only users.
4. Stability & versioning
- Semantic versioning. All
@dusrel/image-*packages release in lockstep (same version) to eliminate inter-package version mismatch. - Public API = everything exported from a package's documented entry points. Anything else is internal and may change in any release.
- Deprecations: marked in types and docs for at least one minor release before removal in the next major.
- Breaking changes only in major versions, with a migration guide (
docs/MIGRATION.md, created when the first major bump is planned).
5. TypeScript
- Strict mode; hand-reviewed public
.d.tssurface generated by tsdown. - Options and results are exported as named types from every package.
attwandpublintmust pass in CI for every package (packaging or types regressions block release).
6. Plugins
The main package accepts registered plugins of two kinds; plugins run only when the developer registers them, and the core ships no plugin code. This surface was stabilised in Phase 5 (ADR-0007) and is covered by a conformance suite (packages/image/test/plugins.test.ts, tests/browser/plugins.spec.ts).
Step plugins (ImagePlugin: { name, format?, apply(blob, ctx) }) transform a Blob into a Blob. ctx is { previous?, signal? }: previous is the last stage's result (format widened to any MIME type), signal the run's AbortSignal. On the fluent pipeline a step runs at its registered position and splits canvas segments there. In easy mode (processImage) steps run in order after the core pass and before any codec encode. Report steps record plugin:<name>. When a step changes the output MIME type it declares it via format (codecPlugin sets the codec's type; imageDataPlugin sets image/png), and the result/report format follows the last such declaration. Factories: codecPlugin(def), imageDataPlugin(def), and the pipeline builder's .codec(def) sugar.
Codec registrations make a non-canvas format selectable: processImage(input, { format: "image/avif", codecs: [avifDef] }), where a definition is { name?, mimeType, encode, options? } — a codec package's encode plus the MIME type it produces. The core pass runs losslessly (PNG) and the codec encodes the pixels; the report records codec:<format> and the result/report format is the codec's MIME type (which is why both are typed string, not the canvas union). A non-canvas format with NO registered codec throws the typed unsupported-format error before any processing — never a silent fallback.
Errors. Plugin failures surface in the family's typed shape (DusrelImageError): a typed error passes through untouched, an abort becomes code aborted, and anything else becomes code plugin-failed with the plugin named in the message and the original error preserved as cause (wrapPluginError). Fallback policies apply to the whole easy-mode call, as documented in section 2.