@zerotal/media 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -4,10 +4,90 @@ All notable changes to this package are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/); this package
 follows the Zerotal monorepo's unified versioning.
 
-**Maturity: `experimental`**
+**Maturity: `stable`** — the public API follows SemVer strictly: anything
+importable without an `@internal` marker keeps its shape for the rest of the 1.x
+line, and `api-surface.md` is diffed by CI on every change.
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-08-15
+
+### Changed
+
+- **`@zerotal/media` is `stable`.** The blocker was never the feature set — it was
+  that the default driver could not centre-crop, so freezing `ImageDriver` would
+  have frozen the workaround with it. `fit: "cover"` on `BunImageDriver` removed
+  that, and nothing reopened the promotion afterwards, which is the only reason
+  this package was still beta.
+
+  Two things had to happen first, and both are the promotion rather than
+  paperwork around it:
+
+  - **The surface was triaged.** It listed 79 exports and carried exactly one
+    `@internal` marker — plumbing that had leaked out of a module because
+    something else in the package needed it. Collection resolution, retention,
+    conversion dispatch, source resolvers, disk resolution, schema provisioning
+    and the config defaults are now marked `@internal`. Narrowing a surface after
+    `stable` is itself a breaking change, so an export that shipped stable by
+    accident would have been stuck for the rest of 1.x.
+  - **What survived is documented.** All 47 promised exports appear in
+    `docs/media.md`, and `bun run docs:coverage` now fails CI if that stops being
+    true. A SemVer promise over a surface nobody wrote down is not a promise
+    anyone can use.
+
+  Nothing is removed and nothing is renamed: an `@internal` export still imports
+  and still works. It is a statement about what the guarantee covers.
+
+- **`ImageDriver` is frozen, and its growth rule is written down.** It is the one
+  type in this package a third party implements, so a new _required_ member would
+  break code this repository cannot see. New members arrive optional, with the
+  package supplying the fallback; `ImageManipulation` may gain optional fields;
+  `ImageResult` and `ImageMetadata` may not gain required ones, because drivers
+  produce them. Buffers rather than streams stays: media is read from and written
+  to a storage disk, and both hand over whole objects.
+
+### Added
+
+- **`fit: "cover"` works on the default driver.** No `sharp`, no native module. `Bun.Image`
+  still exposes no crop primitive, so the centre window is taken through a lossless PNG
+  round-trip on the already-downscaled image — scaling stays native, and the extra cost is
+  roughly 40 ms on an 8 MB photo, off the request path via the queue. This removes the one
+  blocker that sat outside the repo: `sharp` is now a throughput and codec-coverage choice
+  rather than a feature one.
+- **`allowEnlargement` on a conversion.** Off by default, as before. Worth setting when the
+  exact box matters more than fidelity — a `cover` thumbnail for a fixed-size grid slot
+  would otherwise come back undersized for small sources.
+- **`@zerotal/media/testing`** — the state-swapping and disk-resolver seams, moved out of the
+  main entry point so it can be frozen while these stay free to change.
+
+### Fixed
+
+- **`fit: "inside"` returned dimensions that were off, sometimes short of the box asked
+  for.** `Bun.Image` floors internally, so a 400×300 source asked for `width: 150` came back
+  **149** px wide, and derived heights sat a pixel below what `sharp` produced. Both drivers
+  now resolve exact dimensions in shared code before touching their backend. Affects the
+  responsive ladder, which records these widths into `srcset`.
+
+### Changed
+
+- **Both shipped drivers are held to one parity suite**, over a sweep of sizes, fits and
+  enlargement settings. `BunImageDriver.supportsCrop` is now `true`; the flag stays on
+  `ImageDriver` for third-party drivers that genuinely cannot crop.
+- **`fit: "fill"` with a single dimension now behaves as `inside`** in both drivers. `sharp`
+  would stretch that one axis and leave the other at source size, which is almost never
+  what a caller meant.
+- `FORMAT_MIME`, `FORMAT_EXTENSION` and `CONVERTIBLE_MIME_TYPES` are frozen — they are
+  shared module state, and mutating one changed conversion behaviour process-wide.
+- `UnsupportedManipulationError` is no longer thrown for `cover`. It remains exported as
+  the way any driver reports a manipulation it cannot express.
+
+### Removed
+
+- Test seams from the package root: `mediaState`, `setMediaState`, `resetMediaState`,
+  `setDiskResolver`, `setDefaultDiskName`, `diskNameFor`, `setConversionDispatcher`,
+  `performConversions`, `ownerClassFor`, `partitionConversions`. All still available from
+  `@zerotal/media/testing`; update the import path.
+
 ## [1.3.0] — 2026-08-09
 
 ### Added

package/README.md

@@ -3,11 +3,13 @@
 > Attach files to models — collections, image conversions, responsive images, and ordering.
 
 Associate uploads with any model, store them on any disk, and generate derived
-images without installing a native module. Zerotal's answer to
-`spatie/laravel-medialibrary`.
+images without installing a native module.
 
 Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
 
+**Maturity: `stable`** — anything importable without an `@internal` marker keeps
+its shape for the rest of the 1.x line.
+
 ## Installation
 
 ```bash
@@ -65,10 +67,12 @@ await product.clearMediaCollection("images");
 - **Types come from bytes.** `accepts` is checked against the type sniffed from
   the file's own contents, never the filename or the upload's `Content-Type`.
 - **No native dependency.** Conversions run on `Bun.Image`, built into the
-  runtime. JPEG, PNG and WebP work on every host.
-- **`Bun.Image` cannot crop.** `fit: "cover"` throws rather than silently
-  returning a stretched image. Install `sharp` and set `driver: "sharp"` if you
-  need centre-cropped thumbnails.
+  runtime. JPEG, PNG and WebP work on every host — including `fit: "cover"`,
+  the centre-crop behind square thumbnails. `sharp` is optional, and a shared
+  parity suite holds both drivers to the same output dimensions.
+- **Nothing is upscaled by default.** A source too small to fill the box comes
+  back at the largest size it can supply, rather than blurred up to fit. Set
+  `allowEnlargement: true` on a conversion to opt in.
 - **Deleting a model deletes its files** — unless it soft-deletes, in which case
   they wait for `forceDelete()`.
 - **Paths are keyed on uuid,** not the numeric id, so a public URL discloses

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@zerotal/media",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "license": "MIT",
-  "maturity": "experimental",
+  "maturity": "stable",
   "private": false,
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./commands": "./src/commands/index.ts"
+    "./commands": "./src/commands/index.ts",
+    "./testing": "./src/testing.ts"
   },
   "files": [
     "CHANGELOG.md",
@@ -30,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.3.0",
-    "@zerotal/orm": "1.3.0"
+    "@zerotal/core": "1.5.0",
+    "@zerotal/orm": "1.5.0"
   },
   "peerDependencies": {
     "@zerotal/queue": "^1.0.0",
@@ -46,7 +47,8 @@
     }
   },
   "devDependencies": {
-    "@zerotal/queue": "1.3.0",
+    "@zerotal/queue": "1.5.0",
+    "sharp": "^0.34.0",
     "typescript": "^5.8.0"
   },
   "description": "Attach files to models: media collections, image conversions, responsive images, and ordering — on any Zerotal storage disk.",

package/src/Media.ts

@@ -34,9 +34,8 @@ function ownedQuery(self: MediaHost): ModelQueryBuilder<MediaItem> {
  * Adds media handling to a model.
  *
  * Compose it with `Model.using(...)` and declare the collections the model
- * owns in a static `mediaCollections` field. Zerotal's equivalent of Laravel's
- * `HasMedia` interface plus `InteractsWithMedia` trait, in one piece — named for
- * how it reads at the call site: `Model.using(Media)`.
+ * owns in a static `mediaCollections` field. The interface and the behaviour are
+ * one piece here, named for how it reads at the call site: `Model.using(Media)`.
  *
  * ## Deleting
  *

package/src/MediaItem.ts

@@ -14,6 +14,7 @@ export function setPathGenerator(generator: PathGenerator): void {
 }
 
 /** The path generator currently in force. */
+/** @internal — reads the active generator; `setPathGenerator` is the public seam. */
 export function pathGenerator(): PathGenerator {
   return _pathGenerator;
 }

package/src/collections/resolve.ts

@@ -2,6 +2,7 @@ import { UnknownCollectionError } from "../errors.ts";
 import type { CollectionDefinition, MediaCollections } from "../types.ts";
 
 /** A model class that may declare media collections. */
+/** @internal — the structural shape `resolveCollection` reads off a model. */
 export interface CollectionHost {
   name: string;
   mediaCollections?: MediaCollections;
@@ -16,6 +17,8 @@ export interface CollectionHost {
  *
  * @throws {UnknownCollectionError} when the model declares no such collection —
  *   listing the ones it does declare, because the mistake is nearly always a typo.
+ *
+ * @internal — collection lookup; apps declare `mediaCollections` and never call this.
  */
 export function resolveCollection(host: CollectionHost, name: string): CollectionDefinition {
   const declared = host.mediaCollections ?? {};
@@ -29,11 +32,13 @@ export function resolveCollection(host: CollectionHost, name: string): Collectio
 }
 
 /** Whether a model declares a collection under `name`. */
+/** @internal — collection lookup; apps declare `mediaCollections` and never call this. */
 export function hasCollection(host: CollectionHost, name: string): boolean {
   return (host.mediaCollections ?? {})[name] !== undefined;
 }
 
 /** Every collection name the model declares. */
+/** @internal — collection lookup; apps declare `mediaCollections` and never call this. */
 export function collectionNames(host: CollectionHost): string[] {
   return Object.keys(host.mediaCollections ?? {});
 }

package/src/collections/retention.ts

@@ -13,6 +13,8 @@ import type { CollectionDefinition } from "../types.ts";
  *
  * @param justAdded - The item that triggered the trim; never removed, even if
  *   its sort position would otherwise put it outside the window.
+ *
+ * @internal — `single` / `onlyKeepLatest` enforcement, run by MediaAdder.
  */
 export async function applyRetentionRules(
   modelType: string,

package/src/config.ts

@@ -77,6 +77,7 @@ export function MediaConfig(options: Partial<MediaConfigShape> = {}): MediaConfi
 }
 
 /** The defaults, for tests and for resolving config in DB-less runtimes. */
+/** @internal — the defaults `MediaConfig()` merges onto. */
 export function mediaDefaults(): MediaConfigShape {
   return { ...defaults, responsiveWidths: [...defaults.responsiveWidths] };
 }

package/src/conversions/BunImageDriver.ts

@@ -5,21 +5,28 @@ import {
   type ImageMetadata,
   type ImageResult,
 } from "./ImageDriver.ts";
-import { UnsupportedFormatError, UnsupportedManipulationError } from "../errors.ts";
+import { RasterFormatError, UnsupportedFormatError } from "../errors.ts";
+import { cropCentre, decodePng, encodePng, readPngHeader, resolveGeometry } from "./raster.ts";
+import type { ResolvedGeometry } from "./raster.ts";
 import type { ConversionFormat } from "../types.ts";
 
 /**
  * Image processing on `Bun.Image` — no native modules, no `sharp`, nothing to
  * install. JPEG, PNG and WebP are statically linked into Bun itself.
  *
- * ## What it cannot do
+ * ## How cropping works
  *
- * `Bun.Image.resize()` takes `fit: "fill" | "inside"` and the class exposes no
- * crop, extract or composite primitive. A centre-cropped thumbnail — a square
- * from a 3:2 photo — is therefore not expressible, and `fit: "cover"` throws
- * {@link UnsupportedManipulationError} naming the fix rather than silently
- * returning a stretched image. Apps that need crop install `sharp` and switch to
- * `SharpImageDriver` via `media.driver`.
+ * `Bun.Image.resize()` takes only `fit: "fill" | "inside"` and the class exposes
+ * no crop, extract or composite primitive, so `fit: "cover"` is not expressible
+ * through its API alone. It is instead assembled here: scale so the image
+ * overflows the target box in at most one axis, then take the centre window out
+ * of the result through a lossless PNG round-trip (see `raster.ts`). Scaling
+ * stays native; only the window copy is ours, and it runs on the already-scaled
+ * image rather than the original.
+ *
+ * The upshot is that this driver crops, and `sharp` is no longer required for a
+ * cover-fit thumbnail. `SharpImageDriver` remains worth choosing for throughput
+ * on large batches and for formats Bun's `system` backend lacks.
  *
  * ## Host-dependent formats
  *
@@ -29,7 +36,7 @@ import type { ConversionFormat } from "../types.ts";
  */
 export class BunImageDriver implements ImageDriver {
   readonly name = "BunImageDriver";
-  readonly supportsCrop = false;
+  readonly supportsCrop = true;
 
   /** Memoised results of {@link canEncode}, which costs a real encode. */
   readonly #encodable = new Map<ConversionFormat, boolean>();
@@ -41,6 +48,16 @@ export class BunImageDriver implements ImageDriver {
      * against the header before any pixel buffer is allocated.
      */
     private readonly maxPixels: number = 0x3fff * 0x3fff,
+    /**
+     * Cap on the intermediate buffer the crop path decodes, in pixels.
+     *
+     * Separate from {@link maxPixels}, and much lower, because this one bounds an
+     * allocation *we* make rather than one Bun makes: the intermediate is
+     * uncompressed RGBA, so the default 40 MP is already ~160 MB. Conversions
+     * are thumbnail-sized in practice, so this only ever catches a conversion
+     * defined with implausible dimensions.
+     */
+    private readonly maxCropPixels: number = 40_000_000,
   ) {}
 
   async metadata(bytes: Uint8Array): Promise<ImageMetadata | null> {
@@ -55,54 +72,145 @@ export class BunImageDriver implements ImageDriver {
   }
 
   async convert(bytes: Uint8Array, manipulation: ImageManipulation): Promise<ImageResult> {
-    const { width, height, fit = "inside", format, quality, rotate } = manipulation;
-
-    if (fit === "cover") {
-      throw new UnsupportedManipulationError(
-        this.name,
-        'centre-crop (fit: "cover") — Bun.Image supports only fit: "fill" | "inside" ' +
-          "and exposes no crop primitive",
-        'either use fit: "inside" (scale to fit, preserves aspect ratio) or ' +
-          'install sharp and set `driver: "sharp"` in config/media.ts.',
-      );
+    const { format, quality, rotate } = manipulation;
+
+    // Rotation changes which dimension is which, so the geometry has to be
+    // computed against the post-rotation shape. Rotating first — into a PNG, so
+    // nothing is lost — lets the dimensions simply be read back, rather than
+    // re-deriving Bun's canvas expansion for non-right angles.
+    const rotated = rotate !== undefined && rotate !== 0;
+    let source = bytes;
+    let sourceWidth: number;
+    let sourceHeight: number;
+
+    if (rotated) {
+      source = await new Bun.Image(bytes, { maxPixels: this.maxPixels })
+        .rotate(rotate)
+        .png()
+        .bytes();
+      const header = readPngHeader(source);
+      if (header === null) throw new RasterFormatError("Bun.Image.rotate() did not return a PNG");
+      sourceWidth = header.width;
+      sourceHeight = header.height;
+    } else {
+      const meta = await this.metadata(bytes);
+      if (meta === null) throw new RasterFormatError("the source image could not be read");
+      sourceWidth = meta.width;
+      sourceHeight = meta.height;
     }
 
-    let pipeline = new Bun.Image(bytes, { maxPixels: this.maxPixels });
+    const geometry = resolveGeometry({
+      sourceWidth,
+      sourceHeight,
+      targetWidth: manipulation.width,
+      targetHeight: manipulation.height,
+      fit: manipulation.fit ?? "inside",
+      // Upscaling a 200px source to fill a 1920px slot produces a blurry file
+      // larger than the original. Never worth it by default.
+      withoutEnlargement: manipulation.withoutEnlargement ?? true,
+    });
+
+    const needsCrop =
+      geometry.cropWidth !== undefined &&
+      geometry.cropHeight !== undefined &&
+      (geometry.cropWidth !== geometry.resizeWidth ||
+        geometry.cropHeight !== geometry.resizeHeight);
 
-    if (rotate !== undefined && rotate !== 0) pipeline = pipeline.rotate(rotate);
+    // Without a crop the whole thing stays inside Bun: one pipeline, no
+    // round-trip. This is the overwhelmingly common path.
+    if (!needsCrop) {
+      let pipeline = new Bun.Image(source, { maxPixels: this.maxPixels });
+      if (!geometry.resizeIsNoop) {
+        pipeline = pipeline.resize(geometry.resizeWidth, geometry.resizeHeight, {
+          // Exact dimensions are already resolved, so `fill` is what we want:
+          // it asks Bun for precisely these numbers instead of letting it
+          // re-derive (and re-round) them from the caller's box.
+          fit: "fill",
+          withoutEnlargement: false,
+        });
+      }
+      pipeline = _applyFormat(pipeline, format, quality);
 
-    if (width !== undefined || height !== undefined) {
-      // Bun.Image needs a width; when only a height is given, pass the height
-      // through as the bound and let `inside` preserve the aspect ratio.
-      const targetWidth = width ?? height!;
-      pipeline = pipeline.resize(targetWidth, height, {
-        fit,
-        // Upscaling a 200px source to fill a 1920px slot produces a blurry file
-        // larger than the original. Never worth it by default.
-        withoutEnlargement: manipulation.withoutEnlargement ?? true,
-      });
+      return {
+        bytes: await this.#encode(pipeline, format),
+        width: geometry.resizeWidth,
+        height: geometry.resizeHeight,
+        format,
+        mimeType: FORMAT_MIME[format],
+      };
     }
 
-    pipeline = _applyFormat(pipeline, format, quality);
+    return await this.#convertCropped(source, geometry, rotated, format, quality);
+  }
+
+  /**
+   * The `fit: "cover"` path: scale so the image overflows the box in at most one
+   * axis, then keep the centre.
+   *
+   * `Bun.Image` has no crop primitive, so the centre window is taken here —
+   * through a lossless PNG round-trip, on the already-scaled image. The scaling
+   * itself never leaves Bun.
+   */
+  async #convertCropped(
+    source: Uint8Array,
+    geometry: ResolvedGeometry,
+    sourceIsPng: boolean,
+    format: ConversionFormat,
+    quality: number | undefined,
+  ): Promise<ImageResult> {
+    // A no-op resize on a source that is already PNG has nothing to do.
+    const scaled =
+      geometry.resizeIsNoop && sourceIsPng
+        ? source
+        : await this.#toPng(source, geometry.resizeIsNoop ? null : geometry);
+
+    const cropped = cropCentre(
+      decodePng(scaled, this.maxCropPixels),
+      geometry.cropWidth!,
+      geometry.cropHeight!,
+    );
 
-    let out: Uint8Array;
+    const pipeline = _applyFormat(
+      new Bun.Image(encodePng(cropped), { maxPixels: this.maxPixels }),
+      format,
+      quality,
+    );
+
+    return {
+      bytes: await this.#encode(pipeline, format),
+      // Known exactly from the crop — no need to ask the pipeline.
+      width: cropped.width,
+      height: cropped.height,
+      format,
+      mimeType: FORMAT_MIME[format],
+    };
+  }
+
+  /** Re-encode as PNG, optionally resizing on the way through. */
+  async #toPng(bytes: Uint8Array, geometry: ResolvedGeometry | null): Promise<Uint8Array> {
+    const image = new Bun.Image(bytes, { maxPixels: this.maxPixels });
+    const pipeline =
+      geometry === null
+        ? image
+        : image.resize(geometry.resizeWidth, geometry.resizeHeight, {
+            // Safe despite the name: both dimensions were scaled by one factor,
+            // so this fills a box that already has the source's aspect ratio.
+            fit: "fill",
+            withoutEnlargement: false,
+          });
+    return await pipeline.png().bytes();
+  }
+
+  /** Await a pipeline, translating a missing codec into a named error. */
+  async #encode(pipeline: Bun.Image, format: ConversionFormat): Promise<Uint8Array> {
     try {
-      out = await pipeline.bytes();
+      return await pipeline.bytes();
     } catch (error) {
       if (_codeOf(error) === "ERR_IMAGE_FORMAT_UNSUPPORTED") {
         throw new UnsupportedFormatError(format, await this.encodableFormats());
       }
       throw error;
     }
-
-    return {
-      bytes: out,
-      // Populated once a terminal has been awaited; -1 before that.
-      width: pipeline.width,
-      height: pipeline.height,
-      format,
-      mimeType: FORMAT_MIME[format],
-    };
   }
 
   async placeholder(bytes: Uint8Array): Promise<string | null> {

package/src/conversions/ConversionRunner.ts

@@ -47,6 +47,8 @@ export function partitionConversions(
  * and its row already exists, so a codec that chokes on one file should cost
  * that file its thumbnail, not the upload. Failures are collected and returned
  * rather than thrown.
+ *
+ * @internal — the conversion engine, constructed by MediaProvider.
  */
 export class ConversionRunner {
   constructor(
@@ -214,6 +216,9 @@ export class ConversionRunner {
       fit: definition.fit ?? "inside",
       format,
       quality: definition.quality ?? this.config.quality,
+      // Inverted at the boundary: the collection API reads better as an opt-in
+      // ("allow this"), the driver contract as a constraint ("do not do this").
+      withoutEnlargement: definition.allowEnlargement !== true,
     };
   }
 }

package/src/conversions/ImageDriver.ts

@@ -37,15 +37,46 @@ export interface ImageMetadata {
 /**
  * The seam between this package and whatever actually manipulates pixels.
  *
- * Two implementations ship: {@link BunImageDriver} (the default — no
- * dependencies, no crop) and `SharpImageDriver` (opt-in, adds crop). Keeping
- * both behind one interface is also what makes `Bun.Image` — which is a few
- * weeks old — a safe thing to depend on: if its API moves, one file changes.
+ * Two implementations ship: `BunImageDriver` (the default — no dependencies)
+ * and `SharpImageDriver` (opt-in, a native module). Both support every
+ * manipulation in {@link ImageManipulation}, and a shared parity suite holds
+ * them to the same output dimensions, so `media.driver` is a throughput and
+ * codec-coverage choice rather than a feature one.
+ *
+ * Keeping both behind one interface is also what makes `Bun.Image` — which is
+ * young — a safe thing to depend on: if its API moves, one file changes.
+ *
+ * ## How this interface may grow
+ *
+ * This is the one type in the package a third-party implements, so a new
+ * **required** member is a breaking change for code this repository cannot see.
+ * The policy, decided when the package was promoted to `stable`:
+ *
+ * - **New members arrive optional**, and the package supplies the fallback —
+ *   the same way `supportsCrop` lets a driver decline `fit: "cover"` instead of
+ *   failing at conversion time. A capability nobody implements must degrade to
+ *   the behaviour drivers already have.
+ * - **{@link ImageManipulation} may gain optional fields** (a background colour,
+ *   a device-pixel-ratio multiplier, EXIF stripping). Drivers ignore what they
+ *   do not understand, so this stays additive — but a field that *changes*
+ *   existing output is a new field, never a new default.
+ * - **{@link ImageResult} and {@link ImageMetadata} may not gain required
+ *   fields**, because drivers produce them. Optional only.
+ *
+ * Buffers rather than streams is deliberate and does not change: media is read
+ * from and written to a storage disk, both of which hand over whole objects, so
+ * a streaming seam here would only re-buffer at each end.
  */
 export interface ImageDriver {
   /** Name used in error messages. */
   readonly name: string;
-  /** Whether `fit: "cover"` is available. */
+  /**
+   * Whether `fit: "cover"` is available.
+   *
+   * Both shipped drivers report `true`. It stays part of the interface for
+   * third-party drivers wrapping a backend that genuinely cannot crop, which
+   * need a way to say so other than failing at conversion time.
+   */
   readonly supportsCrop: boolean;
 
   /** Read dimensions and format without decoding the whole image. */
@@ -64,26 +95,31 @@ export interface ImageDriver {
   canEncode(format: ConversionFormat): Promise<boolean>;
 }
 
+// These three are exported for reading — to label a download, or to check a type
+// before offering an upload. They are frozen because they are shared module
+// state: an app that mutated one would change how conversions behave for every
+// other caller in the process, including ones it does not own.
+
 /** MIME type for each format a driver may emit. */
-export const FORMAT_MIME: Record<ConversionFormat, string> = {
+export const FORMAT_MIME: Readonly<Record<ConversionFormat, string>> = Object.freeze({
   jpeg: "image/jpeg",
   png: "image/png",
   webp: "image/webp",
   avif: "image/avif",
   heic: "image/heic",
-};
+});
 
 /** File extension for each format. */
-export const FORMAT_EXTENSION: Record<ConversionFormat, string> = {
+export const FORMAT_EXTENSION: Readonly<Record<ConversionFormat, string>> = Object.freeze({
   jpeg: "jpg",
   png: "png",
   webp: "webp",
   avif: "avif",
   heic: "heic",
-};
+});
 
 /** MIME types this package will attempt to convert. */
-export const CONVERTIBLE_MIME_TYPES = new Set([
+export const CONVERTIBLE_MIME_TYPES: ReadonlySet<string> = new Set([
   "image/jpeg",
   "image/png",
   "image/webp",