utilful 3.2.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/cli/testing.mjs

@@ -69,7 +69,7 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 			return new Promise((resolve, reject) => {
 				execFile(process.execPath, [entry, ...argv], {
 					cwd: options.cwd,
-					maxBuffer: 64 * 1024 * 1024
+					maxBuffer: 67108864
 				}, (spawnError, stdout, stderr) => {
 					if (spawnError && typeof spawnError.code !== "number") reject(spawnError);
 					else resolve({

package/dist/cli/usage.mjs

@@ -4,7 +4,7 @@ import process from "node:process";
 //#region src/cli/usage.ts
 function renderUsage(command, { parent, stream = process.stdout } = {}) {
 	const color = (style, text) => paint(style, text, stream);
-	const heading = (title) => color(["bold", "underline"], title);
+	const heading = (title) => color("bold", title);
 	const meta = command.meta ?? {};
 	const parentMeta = parent?.meta ?? {};
 	const commandName = [parentMeta.name, meta.name].filter((name) => name !== void 0).join(" ");
@@ -29,7 +29,7 @@ function renderUsage(command, { parent, stream = process.stdout } = {}) {
 		}
 		const spellings = [definition.alias === void 0 ? void 0 : `-${definition.alias}`, `--${name}`].filter((spelling) => spelling !== void 0).join(", ");
 		const value = definition.type === "string" ? `<${definition.valueHint ?? name}>` : void 0;
-		optionLines.push([color("cyan", value === void 0 ? spellings : `${spellings}=${value}`), hints]);
+		optionLines.push([color("cyan", spellings) + (value === void 0 ? "" : color("dim", `=${value}`)), hints]);
 		if (definition.type === "boolean" && definition.default === true) optionLines.push([color("cyan", `--no-${name}`), ""]);
 		if (isRequired) usageLine.push(`--${name}=${value}`);
 	}
@@ -37,9 +37,10 @@ function renderUsage(command, { parent, stream = process.stdout } = {}) {
 	const hasArguments = positionalLines.length > 0 || optionLines.length > 0;
 	if (commandLines.length > 0 && !hasArguments) usageLine.push(Object.keys(command.subCommands).join("|"));
 	const lines = [
-		color("gray", `${meta.description ?? ""} (${commandName}${version === void 0 ? "" : ` v${version}`})`),
+		color("bold", version === void 0 ? commandName : `${commandName} v${version}`),
+		...meta.description === void 0 ? [] : [meta.description],
 		"",
-		`${heading("USAGE")} ${color("cyan", [
+		`${heading("USAGE")}  ${color("cyan", [
 			commandName,
 			hasArguments ? "[OPTIONS]" : void 0,
 			...usageLine

package/dist/csv.mjs

@@ -154,15 +154,16 @@ var CSVParserCore = class {
 			const character = text[i];
 			const nextCharacter = i + 1 < text.length ? text[i + 1] : "";
 			if (this.isFieldQuoted && !this.inQuotes && character !== this.delimiter && (character === SPACE || character === TAB)) continue;
-			if (character === DOUBLE_QUOTE) if (this.currentField.length === 0 && !this.inQuotes) {
-				this.inQuotes = true;
-				this.isFieldQuoted = true;
-			} else if (this.inQuotes && nextCharacter === DOUBLE_QUOTE) {
-				this.currentField += DOUBLE_QUOTE;
-				i++;
-			} else if (this.inQuotes) this.inQuotes = false;
-			else this.currentField += character;
-			else if (character === this.delimiter && !this.inQuotes) this.appendField();
+			if (character === DOUBLE_QUOTE) {
+				if (this.currentField.length === 0 && !this.inQuotes) {
+					this.inQuotes = true;
+					this.isFieldQuoted = true;
+				} else if (this.inQuotes && nextCharacter === DOUBLE_QUOTE) {
+					this.currentField += DOUBLE_QUOTE;
+					i++;
+				} else if (this.inQuotes) this.inQuotes = false;
+				else this.currentField += character;
+			} else if (character === this.delimiter && !this.inQuotes) this.appendField();
 			else if ((character === NEWLINE || character === CARRIAGE_RETURN) && !this.inQuotes) {
 				if (character === CARRIAGE_RETURN && nextCharacter === NEWLINE) i++;
 				this.appendRow();

package/dist/emitter.mjs

@@ -28,8 +28,10 @@ function createEmitter(events) {
 		*/
 		off(type, handler) {
 			const handlers = events.get(type);
-			if (handlers) if (handler) handlers.splice(handlers.indexOf(handler) >>> 0, 1);
-			else events.set(type, []);
+			if (handlers) {
+				if (handler) handlers.splice(handlers.indexOf(handler) >>> 0, 1);
+				else events.set(type, []);
+			}
 		},
 		/**
 		* Invokes all handlers for the given type.

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,8 +1,8 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "3.2.0",
-  "packageManager": "pnpm@11.15.1",
+  "version": "3.4.0",
+  "packageManager": "pnpm@11.25.0",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
   "license": "MIT",
@@ -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"
@@ -104,13 +109,13 @@
     }
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.1.0",
-    "@types/node": "^26.1.1",
-    "bumpp": "^12.0.0",
-    "eslint": "^10.7.0",
+    "@antfu/eslint-config": "^9.5.0",
+    "@types/node": "^26.4.1",
+    "bumpp": "^12.2.2",
+    "eslint": "^10.9.1",
     "eslint-flat-config-utils": "^3.2.0",
-    "tsdown": "^0.22.13",
+    "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   }
 }