utilful 3.3.0 → 3.4.0

package/README.md

@@ -11,6 +11,7 @@ A collection of TypeScript utilities that I use across my projects.
   - [CSV](#csv)
   - [Defu](#defu)
   - [Emitter](#emitter)
+  - [Image](#image)
   - [JSON](#json)
   - [Module](#module)
   - [Object](#object)
@@ -38,7 +39,7 @@ import { defu } from 'utilful' // Everything
 import { joinURL } from 'utilful/path' // Just the path helpers
 ```
 
-The `cli` module is the exception: it is Node-only (22.13 or later) and lives on its subpaths `utilful/cli` and `utilful/cli/testing` alone.
+Two modules are the exception and live on their subpaths alone. `cli` is Node-only (22.13 or later) and ships as `utilful/cli` and `utilful/cli/testing`. `image` is browser-only and ships as `utilful/image`.
 
 ## API
 
@@ -428,6 +429,55 @@ emitter.on('foo', onFoo) // Listen
 emitter.off('foo', onFoo) // Unlisten
 ```
 
+### Image
+
+#### `toReducedBlob`
+
+Downscales an image blob so its longer side fits `maxDimension` and re-encodes it. Resizing happens in `createImageBitmap` with `resizeQuality: 'high'`, so the canvas only ever holds the reduced image.
+
+```ts
+type ReducedBlobType = 'image/jpeg' | 'image/png' | 'image/webp'
+
+interface ReducedBlobOptions {
+  /**
+   * Maximum width or height in pixels. Smaller images are never upscaled.
+   */
+  maxDimension?: number
+  /**
+   * MIME type of the output. Defaults to the source type if it is one of these, otherwise `image/jpeg`.
+   */
+  type?: ReducedBlobType
+  /**
+   * Encoder quality between 0 and 1, applied to JPEG and WebP.
+   * @default 0.85
+   */
+  quality?: number
+  /**
+   * Whether to re-encode an image that already has the right size and type, which drops EXIF data such as the location.
+   * @default false
+   */
+  stripMetadata?: boolean
+}
+
+declare function toReducedBlob(blob: Blob, options?: ReducedBlobOptions): Promise<Blob>
+```
+
+The original blob comes back untouched when the image already fits and the output type matches the source type. Anything else is re-encoded:
+
+- Re-encoding drops EXIF data such as the location. Set `stripMetadata` to re-encode an image that would otherwise be returned as it is.
+- Any other source type, like HEIC or GIF, becomes JPEG. Animation is lost and transparent pixels turn black – pass `type: 'image/png'` to keep transparency.
+- The function throws if the browser cannot encode the output type, rather than silently returning PNG. Safari cannot encode WebP, which includes a WebP source without an explicit `type`.
+- Re-encoding an image that is not resized draws it at full size. Safari on iOS 17 and earlier limits a canvas to 16.7 megapixels and throws beyond that, so pass `maxDimension` along for camera photos.
+
+**Example:**
+
+```ts
+import { toReducedBlob } from 'utilful/image'
+
+const reduced = await toReducedBlob(file, { maxDimension: 2048 })
+const webp = await toReducedBlob(file, { maxDimension: 1024, type: 'image/webp', quality: 0.8 })
+```
+
 ### JSON
 
 #### `tryParseJSON`

package/dist/image/index.d.mts

@@ -0,0 +1,32 @@
+//#region src/image/index.d.ts
+type ReducedBlobType = typeof REDUCED_BLOB_TYPES[number];
+interface ReducedBlobOptions {
+  /**
+   * Maximum width or height in pixels. Smaller images are never upscaled.
+   */
+  maxDimension?: number;
+  /**
+   * MIME type of the output. Defaults to the source type if it is one of these, otherwise `image/jpeg`.
+   */
+  type?: ReducedBlobType;
+  /**
+   * Encoder quality between 0 and 1, applied to JPEG and WebP.
+   * @default 0.85
+   */
+  quality?: number;
+  /**
+   * Whether to re-encode an image that already has the right size and type, which drops EXIF data such as the location.
+   * @default false
+   */
+  stripMetadata?: boolean;
+}
+declare const REDUCED_BLOB_TYPES: readonly ["image/jpeg", "image/png", "image/webp"];
+/**
+ * Downscales an image blob to fit the maximum dimension and re-encodes it, preserving the aspect ratio.
+ *
+ * @remarks
+ * Returns the original blob if nothing needs to change. Browser-only.
+ */
+declare function toReducedBlob(blob: Blob, options?: ReducedBlobOptions): Promise<Blob>;
+//#endregion
+export { ReducedBlobOptions, ReducedBlobType, toReducedBlob };

package/dist/image/index.mjs

@@ -0,0 +1,69 @@
+import { getReducedSize } from "./size.mjs";
+//#region src/image/index.ts
+const REDUCED_BLOB_TYPES = [
+	"image/jpeg",
+	"image/png",
+	"image/webp"
+];
+const DEFAULT_QUALITY = .85;
+/**
+* Downscales an image blob to fit the maximum dimension and re-encodes it, preserving the aspect ratio.
+*
+* @remarks
+* Returns the original blob if nothing needs to change. Browser-only.
+*/
+async function toReducedBlob(blob, options = {}) {
+	const { maxDimension, type, quality = DEFAULT_QUALITY, stripMetadata = false } = options;
+	if (!maxDimension && !type && !stripMetadata) return blob;
+	const outputType = type ?? (isReducedBlobType(blob.type) ? blob.type : "image/jpeg");
+	const source = await createImageBitmap(blob);
+	let resized;
+	try {
+		const size = getReducedSize(source, maxDimension);
+		const isResized = size.width !== source.width || size.height !== source.height;
+		if (!isResized && outputType === blob.type && !stripMetadata) return blob;
+		if (isResized) resized = await createImageBitmap(source, {
+			resizeWidth: size.width,
+			resizeHeight: size.height,
+			resizeQuality: "high"
+		});
+		return await encodeBitmap(resized ?? source, outputType, quality);
+	} finally {
+		source.close();
+		resized?.close();
+	}
+}
+function isReducedBlobType(type) {
+	return REDUCED_BLOB_TYPES.includes(type);
+}
+async function encodeBitmap(bitmap, type, quality) {
+	let blob;
+	if (typeof OffscreenCanvas !== "undefined") {
+		const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+		drawBitmap(canvas.getContext("2d"), bitmap);
+		blob = await canvas.convertToBlob({
+			type,
+			quality
+		});
+	} else {
+		const canvas = document.createElement("canvas");
+		canvas.width = bitmap.width;
+		canvas.height = bitmap.height;
+		try {
+			drawBitmap(canvas.getContext("2d"), bitmap);
+			blob = await new Promise((resolve) => canvas.toBlob(resolve, type, quality));
+		} finally {
+			canvas.width = 0;
+			canvas.height = 0;
+		}
+	}
+	if (!blob) throw new Error("Failed to encode the image");
+	if (blob.type !== type) throw new Error(`This browser cannot encode ${type}`);
+	return blob;
+}
+function drawBitmap(context, bitmap) {
+	if (!context) throw new Error("Failed to get a 2D canvas context");
+	context.drawImage(bitmap, 0, 0);
+}
+//#endregion
+export { toReducedBlob };

package/dist/image/size.mjs

@@ -0,0 +1,11 @@
+//#region src/image/size.ts
+function getReducedSize(size, maxDimension) {
+	if (!maxDimension || Math.max(size.width, size.height) <= maxDimension) return size;
+	const ratio = maxDimension / Math.max(size.width, size.height);
+	return {
+		width: Math.max(1, Math.round(size.width * ratio)),
+		height: Math.max(1, Math.round(size.height * ratio))
+	};
+}
+//#endregion
+export { getReducedSize };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "packageManager": "pnpm@11.25.0",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
@@ -19,6 +19,7 @@
     "csv",
     "defu",
     "emitter",
+    "image",
     "result",
     "typescript",
     "url",
@@ -54,6 +55,10 @@
       "types": "./dist/emitter.d.mts",
       "default": "./dist/emitter.mjs"
     },
+    "./image": {
+      "types": "./dist/image/index.d.mts",
+      "default": "./dist/image/index.mjs"
+    },
     "./json": {
       "types": "./dist/json.d.mts",
       "default": "./dist/json.mjs"