utilful 3.3.0 → 3.5.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 (24.16 or later) and ships as `utilful/cli` and `utilful/cli/testing`. `image` is browser-only and ships as `utilful/image`.
 
 ## API
 
@@ -56,23 +57,26 @@ declare function toArray<T>(array?: MaybeArray<T> | null | undefined): T[]
 
 ### CLI
 
-A command runner on top of Node's `util.parseArgs`: strict option parsing, one level of sub-commands, `--help` and `--version`, and an error boundary that prints a recognized error as a message and anything else with its stack. `-h` and `-v` belong to the runner, so no option may take either letter as its alias.
+A command runner on top of Node's `util.parseArgs`: strict option parsing, sub-commands at any depth, `--help`, `--version` and `--verbose` on every command, and an error boundary that prints a recognized error as its message and causes, and anything else with its stack as well. `--verbose` adds the stack to every failure but a wrong argument. `-h` and `-v` belong to the runner, so no option may take either letter as its alias.
 
 #### `defineCommand`
 
-Types a command definition, so `run` receives its `args` typed by their definitions.
+Types a command definition, so `run` receives its `args` typed by their definitions. Declared `as const`, the arguments also type an exported command under `isolatedDeclarations`.
 
 ```ts
-import { CliError, commonArgs, defineCommand } from 'utilful/cli'
+import type { CommandDef } from 'utilful/cli'
+import { CliError, defineCommand } from 'utilful/cli'
 
-const build = defineCommand({
+const buildArgs = {
+  'file': { type: 'positional', description: 'Entry file', required: true }, // string
+  'out-dir': { type: 'string', alias: 'd', description: 'Output directory', valueHint: 'path' }, // string | undefined
+  'format': { type: 'enum', options: ['esm', 'iife'], default: 'esm' }, // 'esm' | 'iife'
+  'watch': { type: 'boolean', alias: 'w', description: 'Rebuild on change' }, // boolean, --no-watch turns it off
+} as const
+
+export const build: CommandDef<typeof buildArgs> = defineCommand({
   meta: { name: 'build', description: 'Compile the entry file' },
-  args: {
-    ...commonArgs, // Adds --verbose
-    'file': { type: 'positional', description: 'Entry file', required: true }, // string
-    'out-dir': { type: 'string', alias: 'd', description: 'Output directory', valueHint: 'path' }, // string | undefined
-    'watch': { type: 'boolean', alias: 'w', description: 'Rebuild on change' }, // boolean, --no-watch turns it off
-  },
+  args: buildArgs,
   run({ args }) {
     if (args.watch && args['out-dir'] === undefined)
       throw new CliError('--watch needs an --out-dir') // Printed as a message, no stack
@@ -95,11 +99,11 @@ const main = defineCommand({
 void runMain(main, { expectedErrors: [MyLibraryError] }) // Reported like a `CliError`
 ```
 
-Also exported: `runCommand` (runs the tree and throws instead of reporting), `parseArgs`, `reportFailure` (for a failure that outlives `run`, such as a watch rebuild), and `log` with `error`, `warn`, `info`, `success` and `blankLine`, all writing to stderr.
+Also exported: `runCommand` (runs the tree and throws instead of reporting), `parseArgs`, `reportFailure` (for a failure that outlives `run`, such as a watch rebuild), `readStdin` (everything piped in, as text), `paint` (`styleText` for a given stream, hex colors included), and `log` with `error`, `warn`, `info`, `success` and `blankLine`, all writing to stderr.
 
 #### `createCliHarness`
 
-From `utilful/cli/testing`, which needs `vitest`. `runCli` runs the tree in-process and captures both streams and the exit code, `runCliProcess` runs the entry file as a child process. `useTemporaryDirectories` and `mockStdin` ship alongside.
+From `utilful/cli/testing`, which needs `vitest`. `runCli` runs the tree in-process and captures both streams and the exit code, `runCliProcess` runs the entry file as a child process. Both take a `cwd` and an `env`, where `undefined` removes a variable. `useTemporaryDirectories` and `mockStdin` ship alongside and clean up after the test.
 
 ```ts
 import { createCliHarness, useTemporaryDirectories } from 'utilful/cli/testing'
@@ -428,6 +432,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/args.d.mts

@@ -15,30 +15,40 @@ interface BooleanArgDef {
   description?: string;
   default?: boolean;
 }
+interface EnumArgDef extends Omit<StringArgDef, "type"> {
+  type: "enum";
+  options: readonly string[];
+}
 interface PositionalArgDef {
   type: "positional";
   description?: string;
   required?: boolean;
 }
-type ArgDef = StringArgDef | BooleanArgDef | PositionalArgDef;
+type ArgDef = StringArgDef | BooleanArgDef | EnumArgDef | PositionalArgDef;
 type ArgsDef = Record<string, ArgDef>;
 type ParsedArgs<T extends ArgsDef = ArgsDef> = {
   /** Every positional, bound by a definition or not. */
   _: string[];
 } & { [K in keyof T]: ArgDef extends T[K] ? string | boolean | undefined : T[K] extends {
   type: "boolean";
-} ? boolean : T[K] extends {
+} ? boolean : OptionalUnless<T[K], T[K] extends {
+  type: "enum";
+  options: readonly (infer V)[];
+} ? V : string>; };
+type OptionalUnless<D, V> = D extends {
   default: string;
 } | {
   required: true;
-} ? string : string | undefined; };
+} ? V : V | undefined;
+/** @deprecated See `commonArgs`. */
 interface CommonArgs extends ArgsDef {
   verbose: BooleanArgDef;
 }
+/** @deprecated The runner accepts `--verbose` on every command, so spreading this adds nothing. */
 declare const commonArgs: CommonArgs;
 /** Parses `argv` against a definition. An absent boolean reads as `false`, and `--no-<name>` turns one off. */
-declare function parseArgs$1<T extends ArgsDef>(argv: readonly string[], argsDef: T, { allowExtraPositionals }?: {
+declare function parseArgs$1<const T extends ArgsDef>(argv: readonly string[], argsDef: T, { allowExtraPositionals }?: {
   allowExtraPositionals?: boolean;
 }): ParsedArgs<T>;
 //#endregion
-export { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, ParsedArgs, PositionalArgDef, StringArgDef, commonArgs, parseArgs$1 as parseArgs };
+export { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, EnumArgDef, ParsedArgs, PositionalArgDef, StringArgDef, commonArgs, parseArgs$1 as parseArgs };

package/dist/cli/args.mjs

@@ -1,10 +1,12 @@
 import { ArgumentError } from "./errors.mjs";
 import { parseArgs } from "node:util";
 //#region src/cli/args.ts
-const commonArgs = { verbose: {
+const verboseArg = {
 	type: "boolean",
-	description: "Print the cause chain and stack trace on failure"
-} };
+	description: "Print the stack trace on failure"
+};
+/** @deprecated The runner accepts `--verbose` on every command, so spreading this adds nothing. */
+const commonArgs = { verbose: verboseArg };
 /** Parses `argv` against a definition. An absent boolean reads as `false`, and `--no-<name>` turns one off. */
 function parseArgs$1(argv, argsDef, { allowExtraPositionals = false } = {}) {
 	let parseResult;
@@ -28,6 +30,7 @@ function parseArgs$1(argv, argsDef, { allowExtraPositionals = false } = {}) {
 			continue;
 		}
 		const value = parseResult.values[name];
+		if (definition.type === "enum") assertEnumValue(name, definition, value);
 		if (definition.type === "boolean") args[name] = value ?? false;
 		else if (value === void 0 && definition.required === true) throw new ArgumentError(`Missing required argument: --${name}`);
 		else args[name] = value;
@@ -45,7 +48,7 @@ function toNodeOptions(argsDef) {
 	const options = {};
 	for (const [name, definition] of Object.entries(argsDef)) {
 		if (definition.type === "positional") continue;
-		const option = { type: definition.type };
+		const option = { type: definition.type === "boolean" ? "boolean" : "string" };
 		if (definition.alias !== void 0) option.short = definition.alias;
 		if (definition.default !== void 0) option.default = definition.default;
 		options[name] = option;
@@ -80,7 +83,7 @@ function splitShortOptionValues(argv) {
 function joinNegativeValues(argv, argsDef) {
 	const optionNamesBySpelling = /* @__PURE__ */ new Map();
 	for (const [name, definition] of Object.entries(argsDef)) {
-		if (definition.type !== "string") continue;
+		if (definition.type !== "string" && definition.type !== "enum") continue;
 		optionNamesBySpelling.set(`--${name}`, name);
 		if (definition.alias !== void 0) optionNamesBySpelling.set(`-${definition.alias}`, name);
 	}
@@ -102,8 +105,13 @@ function joinNegativeValues(argv, argsDef) {
 	}
 	return joinedArguments;
 }
+function assertEnumValue(name, definition, value) {
+	const options = definition.options.join(", ");
+	if (definition.default !== void 0 && !definition.options.includes(definition.default)) throw new Error(`The default of --${name}, ${JSON.stringify(definition.default)}, is not one of: ${options}`);
+	if (value !== void 0 && !definition.options.includes(value)) throw new ArgumentError(`Invalid value for --${name}: ${JSON.stringify(value)}. Expected one of: ${options}`);
+}
 function isNodeArgumentError(error) {
 	return error instanceof Error && String(error.code).startsWith("ERR_PARSE_ARGS");
 }
 //#endregion
-export { commonArgs, parseArgs$1 as parseArgs, toNodeOptions };
+export { commonArgs, parseArgs$1 as parseArgs, toNodeOptions, verboseArg };

package/dist/cli/command.d.mts

@@ -1,4 +1,4 @@
-import { ArgsDef, ParsedArgs } from "./args.mjs";
+import { ArgDef, ArgsDef, ParsedArgs } from "./args.mjs";
 import { ReportOptions } from "./errors.mjs";
 //#region src/cli/command.d.ts
 interface CommandMeta {
@@ -20,7 +20,12 @@ interface RunMainOptions extends Omit<ReportOptions, "verbose"> {
   /** @default process.argv.slice(2) */
   argv?: readonly string[];
 }
-declare function defineCommand<T extends ArgsDef>(command: CommandDef<T>): CommandDef<T>;
+type ArgDefKey = ArgDef extends (infer D) ? D extends unknown ? keyof D : never : never;
+/** Maps every key no argument definition knows to `never`, so a misspelled one fails where the arguments are passed. */
+type KnownKeysOnly<T> = { [K in keyof T]: { [P in keyof T[K]]: P extends ArgDefKey ? T[K][P] : never; }; };
+declare function defineCommand<const T extends ArgsDef>(command: CommandDef<T> & {
+  args?: KnownKeysOnly<T>;
+}): CommandDef<T>;
 /**
  * Runs the command tree and reports whatever it throws. Help someone asked for
  * is the result of the run and goes to stdout; usage that follows a wrong

package/dist/cli/command.mjs

@@ -1,5 +1,5 @@
 import { ArgumentError, reportFailure } from "./errors.mjs";
-import { parseArgs as parseArgs$1, toNodeOptions } from "./args.mjs";
+import { parseArgs as parseArgs$1, toNodeOptions, verboseArg } from "./args.mjs";
 import { renderUsage } from "./usage.mjs";
 import { parseArgs } from "node:util";
 import process from "node:process";
@@ -33,19 +33,51 @@ async function runMain(command, options = {}) {
 }
 /** Runs like `runMain`, but without the error boundary. */
 async function runCommand(command, argv) {
-	const { name, firstOperand, rest } = findSubCommand(command, argv);
-	if (name !== void 0) return runCommand(command.subCommands[name], rest);
-	if (command.subCommands !== void 0 && command.run === void 0) throw new ArgumentError(firstOperand === void 0 ? "Missing command" : `Unknown command: ${firstOperand}`);
-	const args = parseArgs$1(rest, command.args ?? {}, { allowExtraPositionals: command.allowExtraPositionals });
-	await command.run?.({ args });
+	const { commands, firstOperand, rest } = resolveCommand(command, argv);
+	const leaf = withRunnerArgs(commands.at(-1));
+	if (isDispatchOnly(leaf)) throw new ArgumentError(firstOperand === void 0 ? "Missing command" : `Unknown command: ${firstOperand}`);
+	const args = parseArgs$1(rest, leaf.args ?? {}, { allowExtraPositionals: leaf.allowExtraPositionals });
+	await leaf.run?.({ args });
 }
 function usageFor(command, argv, stream) {
-	const { name } = findSubCommand(command, argv);
-	return name === void 0 ? renderUsage(command, { stream }) : renderUsage(command.subCommands[name], {
-		parent: command,
+	const { commands, keys } = resolveCommand(command, argv);
+	return renderUsage(withRunnerArgs(commands.at(-1)), {
+		commandPath: [command.meta?.name, ...keys].filter((name) => name !== void 0).join(" "),
+		version: commands.findLast((walked) => walked.meta?.version !== void 0)?.meta?.version,
 		stream
 	});
 }
+function resolveCommand(command, argv) {
+	const commands = [command];
+	const keys = [];
+	let rest = [...argv];
+	while (true) {
+		const found = findSubCommand(commands.at(-1), rest);
+		if (found.name === void 0) return {
+			commands,
+			keys,
+			firstOperand: found.firstOperand,
+			rest
+		};
+		commands.push(commands.at(-1).subCommands[found.name]);
+		keys.push(found.name);
+		rest = found.rest;
+	}
+}
+function isDispatchOnly(command) {
+	return command.subCommands !== void 0 && command.run === void 0;
+}
+/** `runMain` reads `--verbose` from argv itself, so strict parsing has to accept it on every command that parses arguments. */
+function withRunnerArgs(command) {
+	if (isDispatchOnly(command)) return command;
+	return {
+		...command,
+		args: {
+			...command.args,
+			verbose: command.args?.verbose ?? verboseArg
+		}
+	};
+}
 /**
 * Finds the sub-command the first operand names, wherever it stands among the
 * options. Telling an operand from the value of an option needs every

package/dist/cli/errors.d.mts

@@ -2,7 +2,7 @@
 type ErrorClass = abstract new (...args: never[]) => Error;
 interface ReportOptions {
   verbose?: boolean;
-  /** Treated like `CliError`: message only, no stack. */
+  /** Treated like `CliError`: no stack unless `verbose`. */
   expectedErrors?: readonly ErrorClass[];
   /** Renders an error where its message alone will not do; `undefined` falls back to the message. */
   describe?: (error: Error) => string | undefined;

package/dist/cli/errors.mjs

@@ -10,12 +10,11 @@ var CliError = class extends Error {};
 var ArgumentError = class extends CliError {};
 /** Reports a failure the way the boundary does, for one that outlives `run`, such as a watch rebuild. */
 function reportFailure(error$1, { verbose = false, expectedErrors = [], describe } = {}) {
-	const sections = [error$1 instanceof Error ? describe?.(error$1) ?? error$1.message : String(error$1)];
-	if (verbose || !isExpected(error$1, expectedErrors)) {
-		const causeChain = formatCauseChain(error$1);
-		if (causeChain) sections.push(causeChain);
-		if (error$1 instanceof Error && error$1.stack) sections.push(error$1.stack);
-	}
+	const message = error$1 instanceof Error ? describe?.(error$1) ?? error$1.message : String(error$1);
+	const sections = [message];
+	const causeChain = formatCauseChain(error$1, message);
+	if (causeChain) sections.push(causeChain);
+	if ((verbose || !isExpected(error$1, expectedErrors)) && error$1 instanceof Error && error$1.stack) sections.push(error$1.stack);
 	error(sections.join("\n\n"));
 	process.exitCode = 1;
 }
@@ -30,11 +29,13 @@ function isExpected(error, expectedErrors) {
 	if (expectedErrors.some((expectedError) => error instanceof expectedError)) return true;
 	return error instanceof Error && /^E[A-Z0-9]+$/.test(String(error.code));
 }
-function formatCauseChain(error) {
+function formatCauseChain(error, message) {
 	const causeLines = [];
+	const seen = /* @__PURE__ */ new Set([error]);
 	let current = error instanceof Error ? error.cause : void 0;
-	while (current instanceof Error) {
-		causeLines.push(`Caused by: ${current.name || "Error"}: ${current.message}`);
+	while (current instanceof Error && !seen.has(current)) {
+		seen.add(current);
+		if (current.message !== message) causeLines.push(`Caused by: ${current.name || "Error"}: ${current.message}`);
 		current = current.cause;
 	}
 	return causeLines.join("\n");

package/dist/cli/index.d.mts

@@ -1,5 +1,7 @@
-import { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, ParsedArgs, PositionalArgDef, StringArgDef, commonArgs, parseArgs } from "./args.mjs";
+import { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, EnumArgDef, ParsedArgs, PositionalArgDef, StringArgDef, commonArgs, parseArgs } from "./args.mjs";
 import { ArgumentError, CliError, ErrorClass, ReportOptions, reportFailure } from "./errors.mjs";
 import { CommandContext, CommandDef, CommandMeta, RunMainOptions, defineCommand, runCommand, runMain } from "./command.mjs";
 import { log_d_exports } from "./log.mjs";
-export { type ArgDef, type ArgsDef, ArgumentError, type BooleanArgDef, CliError, type CommandContext, type CommandDef, type CommandMeta, type CommonArgs, type ErrorClass, type ParsedArgs, type PositionalArgDef, type ReportOptions, type RunMainOptions, type StringArgDef, commonArgs, defineCommand, log_d_exports as log, parseArgs, reportFailure, runCommand, runMain };
+import { readStdin } from "./stdin.mjs";
+import { Style, paint } from "./style.mjs";
+export { type ArgDef, type ArgsDef, ArgumentError, type BooleanArgDef, CliError, type CommandContext, type CommandDef, type CommandMeta, type CommonArgs, type EnumArgDef, type ErrorClass, type ParsedArgs, type PositionalArgDef, type ReportOptions, type RunMainOptions, type StringArgDef, type Style, commonArgs, defineCommand, log_d_exports as log, paint, parseArgs, readStdin, reportFailure, runCommand, runMain };

package/dist/cli/index.mjs

@@ -1,5 +1,7 @@
+import { paint } from "./style.mjs";
 import { log_exports } from "./log.mjs";
 import { ArgumentError, CliError, reportFailure } from "./errors.mjs";
 import { commonArgs, parseArgs } from "./args.mjs";
 import { defineCommand, runCommand, runMain } from "./command.mjs";
-export { ArgumentError, CliError, commonArgs, defineCommand, log_exports as log, parseArgs, reportFailure, runCommand, runMain };
+import { readStdin } from "./stdin.mjs";
+export { ArgumentError, CliError, commonArgs, defineCommand, log_exports as log, paint, parseArgs, readStdin, reportFailure, runCommand, runMain };

package/dist/cli/stdin.d.mts

@@ -0,0 +1,4 @@
+//#region src/cli/stdin.d.ts
+declare function readStdin(): Promise<string>;
+//#endregion
+export { readStdin };

package/dist/cli/stdin.mjs

@@ -0,0 +1,8 @@
+import process from "node:process";
+import { text } from "node:stream/consumers";
+//#region src/cli/stdin.ts
+function readStdin() {
+	return text(process.stdin);
+}
+//#endregion
+export { readStdin };

package/dist/cli/style.d.mts

@@ -0,0 +1,6 @@
+import { styleText } from "node:util";
+//#region src/cli/style.d.ts
+type Style = Parameters<typeof styleText>[0];
+declare function paint(style: Style, text: string, stream: NodeJS.WriteStream): string;
+//#endregion
+export { Style, paint };

package/dist/cli/testing.d.mts

@@ -11,6 +11,7 @@ interface CliResult {
 }
 interface RunOptions {
   cwd?: string;
+  env?: Record<string, string | undefined>;
 }
 interface CliHarnessOptions extends Omit<RunMainOptions, "argv"> {
   /** Only `runCliProcess` needs it. */
@@ -24,6 +25,7 @@ interface CliHarness {
 declare function createCliHarness<T extends ArgsDef>(command: CommandDef<T>, { entry, ...runOptions }?: CliHarnessOptions): CliHarness;
 /** Registers an `afterEach` cleanup, so call it at the top level of a test file. */
 declare function useTemporaryDirectories(prefix?: string): (files?: FileMap) => string;
+/** Pipes `input` into stdin until the test finishes; the function it returns restores stdin earlier. */
 declare function mockStdin(input: string): () => void;
 //#endregion
 export { CliHarness, CliHarnessOptions, CliResult, FileMap, RunOptions, createCliHarness, mockStdin, useTemporaryDirectories };

package/dist/cli/testing.mjs

@@ -5,7 +5,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { Readable } from "node:stream";
-import { afterEach, vi } from "vitest";
+import { afterEach, onTestFinished, vi } from "vitest";
 //#region src/cli/testing.ts
 var ProcessExitError = class extends Error {
 	constructor(exitCode) {
@@ -20,6 +20,7 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 			const stderr = [];
 			const previousExitCode = process.exitCode;
 			const previousCwd = process.cwd();
+			const previousEnv = Object.fromEntries(Object.keys(options.env ?? {}).map((name) => [name, process.env[name]]));
 			process.exitCode = void 0;
 			const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
 				stdout.push(String(chunk));
@@ -41,6 +42,7 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 			let exitCode;
 			try {
 				if (options.cwd !== void 0) process.chdir(options.cwd);
+				setEnv(options.env ?? {});
 				await runMain(command, {
 					...runOptions,
 					argv
@@ -51,6 +53,7 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 				exitCode = error.exitCode;
 			} finally {
 				process.chdir(previousCwd);
+				setEnv(previousEnv);
 				process.exitCode = previousExitCode;
 				exitSpy.mockRestore();
 				consoleErrorSpy.mockRestore();
@@ -69,6 +72,10 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 			return new Promise((resolve, reject) => {
 				execFile(process.execPath, [entry, ...argv], {
 					cwd: options.cwd,
+					env: {
+						...process.env,
+						...options.env
+					},
 					maxBuffer: 67108864
 				}, (spawnError, stdout, stderr) => {
 					if (spawnError && typeof spawnError.code !== "number") reject(spawnError);
@@ -82,6 +89,10 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 		}
 	};
 }
+function setEnv(env) {
+	for (const [name, value] of Object.entries(env)) if (value === void 0) delete process.env[name];
+	else process.env[name] = value;
+}
 /** Registers an `afterEach` cleanup, so call it at the top level of a test file. */
 function useTemporaryDirectories(prefix = "cli-test-") {
 	const directories = [];
@@ -102,19 +113,22 @@ function useTemporaryDirectories(prefix = "cli-test-") {
 		return directory;
 	};
 }
+/** Pipes `input` into stdin until the test finishes; the function it returns restores stdin earlier. */
 function mockStdin(input) {
 	const stream = Readable.from([new TextEncoder().encode(input)]);
 	const originalStdin = process.stdin;
-	Object.defineProperty(process, "stdin", {
-		value: stream,
-		writable: true
-	});
-	return () => {
+	const restoreStdin = () => {
 		Object.defineProperty(process, "stdin", {
 			value: originalStdin,
 			writable: true
 		});
 	};
+	onTestFinished(restoreStdin);
+	Object.defineProperty(process, "stdin", {
+		value: stream,
+		writable: true
+	});
+	return restoreStdin;
 }
 //#endregion
 export { createCliHarness, mockStdin, useTemporaryDirectories };

package/dist/cli/usage.mjs

@@ -2,13 +2,10 @@ import { paint } from "./style.mjs";
 import { stripVTControlCharacters } from "node:util";
 import process from "node:process";
 //#region src/cli/usage.ts
-function renderUsage(command, { parent, stream = process.stdout } = {}) {
+function renderUsage(command, { commandPath: commandName = command.meta?.name ?? "", version = command.meta?.version, stream = process.stdout } = {}) {
 	const color = (style, text) => paint(style, text, stream);
 	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(" ");
-	const version = meta.version ?? parentMeta.version;
 	const positionalLines = [];
 	const optionLines = [];
 	const commandLines = [];
@@ -28,7 +25,7 @@ function renderUsage(command, { parent, stream = process.stdout } = {}) {
 			continue;
 		}
 		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;
+		const value = definition.type === "boolean" ? void 0 : `<${definition.valueHint ?? (definition.type === "enum" ? definition.options.join("|") : name)}>`;
 		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}`);

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.5.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"