utilful 3.0.2 → 3.2.0

package/dist/cli/errors.mjs

@@ -0,0 +1,43 @@
+import { error } from "./log.mjs";
+import process from "node:process";
+//#region src/cli/errors.ts
+/**
+* A condition the CLI recognized and phrased for a human. Anything else
+* reaching the boundary is a defect in the tool and prints its stack unasked.
+*/
+var CliError = class extends Error {};
+/** Gets usage printed alongside its message. */
+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);
+	}
+	error(sections.join("\n\n"));
+	process.exitCode = 1;
+}
+/**
+* Reports whether the CLI raised this error deliberately rather than tripping
+* over it. A system error such as `ENOENT` reaches the boundary as the honest
+* answer to what the user asked for, so it reads as deliberate too, while an
+* `ERR_*` error from a Node API is a wrong call and stays a defect.
+*/
+function isExpected(error, expectedErrors) {
+	if (error instanceof CliError) return true;
+	if (expectedErrors.some((expectedError) => error instanceof expectedError)) return true;
+	return error instanceof Error && /^E[A-Z0-9]+$/.test(String(error.code));
+}
+function formatCauseChain(error) {
+	const causeLines = [];
+	let current = error instanceof Error ? error.cause : void 0;
+	while (current instanceof Error) {
+		causeLines.push(`Caused by: ${current.name || "Error"}: ${current.message}`);
+		current = current.cause;
+	}
+	return causeLines.join("\n");
+}
+//#endregion
+export { ArgumentError, CliError, reportFailure };

package/dist/cli/index.d.mts

@@ -0,0 +1,5 @@
+import { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, 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 };

package/dist/cli/index.mjs

@@ -0,0 +1,5 @@
+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 };

package/dist/cli/log.d.mts

@@ -0,0 +1,10 @@
+declare namespace log_d_exports {
+  export { blankLine, error, info, success, warn };
+}
+declare function error(message: string): void;
+declare function warn(message: string): void;
+declare function info(message: string): void;
+declare function success(message: string): void;
+declare function blankLine(): void;
+//#endregion
+export { blankLine, error, info, log_d_exports, success, warn };

package/dist/cli/log.mjs

@@ -0,0 +1,28 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { paint } from "./style.mjs";
+import process from "node:process";
+//#region src/cli/log.ts
+var log_exports = /* @__PURE__ */ __exportAll({
+	blankLine: () => blankLine,
+	error: () => error,
+	info: () => info,
+	success: () => success,
+	warn: () => warn
+});
+function error(message) {
+	console.error(`${paint("red", "✖", process.stderr)} ${message}`);
+}
+function warn(message) {
+	console.error(`${paint("yellow", "⚠", process.stderr)} ${message}`);
+}
+function info(message) {
+	console.error(`${paint("cyan", "●", process.stderr)} ${message}`);
+}
+function success(message) {
+	console.error(`${paint("green", "✔", process.stderr)} ${message}`);
+}
+function blankLine() {
+	console.error("");
+}
+//#endregion
+export { blankLine, error, info, log_exports, success, warn };

package/dist/cli/style.mjs

@@ -0,0 +1,7 @@
+import { styleText } from "node:util";
+//#region src/cli/style.ts
+function paint(style, text, stream) {
+	return styleText(style, text, { stream });
+}
+//#endregion
+export { paint };

package/dist/cli/testing.d.mts

@@ -0,0 +1,29 @@
+import { ArgsDef } from "./args.mjs";
+import { CommandDef, RunMainOptions } from "./command.mjs";
+//#region src/cli/testing.d.ts
+interface FileMap {
+  [relativePath: string]: string;
+}
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+interface RunOptions {
+  cwd?: string;
+}
+interface CliHarnessOptions extends Omit<RunMainOptions, "argv"> {
+  /** Only `runCliProcess` needs it. */
+  entry?: string;
+}
+interface CliHarness {
+  runCli: (argv: readonly string[], options?: RunOptions) => Promise<CliResult>;
+  /** Runs the entry file as a child process, where the exit code is real and stdout can be cut short by exiting. */
+  runCliProcess: (argv: readonly string[], options?: RunOptions) => Promise<CliResult>;
+}
+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;
+declare function mockStdin(input: string): () => void;
+//#endregion
+export { CliHarness, CliHarnessOptions, CliResult, FileMap, RunOptions, createCliHarness, mockStdin, useTemporaryDirectories };

package/dist/cli/testing.mjs

@@ -0,0 +1,120 @@
+import { runMain } from "./command.mjs";
+import process from "node:process";
+import { execFile } from "node:child_process";
+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";
+//#region src/cli/testing.ts
+var ProcessExitError = class extends Error {
+	constructor(exitCode) {
+		super(`process.exit(${exitCode})`);
+		this.exitCode = exitCode;
+	}
+};
+function createCliHarness(command, { entry, ...runOptions } = {}) {
+	return {
+		async runCli(argv, options = {}) {
+			const stdout = [];
+			const stderr = [];
+			const previousExitCode = process.exitCode;
+			const previousCwd = process.cwd();
+			process.exitCode = void 0;
+			const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+				stdout.push(String(chunk));
+				return true;
+			});
+			const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+				stderr.push(String(chunk));
+				return true;
+			});
+			const consoleLogSpy = vi.spyOn(console, "log").mockImplementation((...parts) => {
+				stdout.push(`${parts.map(String).join(" ")}\n`);
+			});
+			const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation((...parts) => {
+				stderr.push(`${parts.map(String).join(" ")}\n`);
+			});
+			const exitSpy = vi.spyOn(process, "exit").mockImplementation((code) => {
+				throw new ProcessExitError(typeof code === "number" ? code : 0);
+			});
+			let exitCode;
+			try {
+				if (options.cwd !== void 0) process.chdir(options.cwd);
+				await runMain(command, {
+					...runOptions,
+					argv
+				});
+				exitCode = process.exitCode ?? 0;
+			} catch (error) {
+				if (!(error instanceof ProcessExitError)) throw error;
+				exitCode = error.exitCode;
+			} finally {
+				process.chdir(previousCwd);
+				process.exitCode = previousExitCode;
+				exitSpy.mockRestore();
+				consoleErrorSpy.mockRestore();
+				consoleLogSpy.mockRestore();
+				stderrSpy.mockRestore();
+				stdoutSpy.mockRestore();
+			}
+			return {
+				stdout: stdout.join(""),
+				stderr: stderr.join(""),
+				exitCode
+			};
+		},
+		runCliProcess(argv, options = {}) {
+			if (entry === void 0) return Promise.reject(/* @__PURE__ */ new Error("runCliProcess needs the entry file of the CLI"));
+			return new Promise((resolve, reject) => {
+				execFile(process.execPath, [entry, ...argv], {
+					cwd: options.cwd,
+					maxBuffer: 64 * 1024 * 1024
+				}, (spawnError, stdout, stderr) => {
+					if (spawnError && typeof spawnError.code !== "number") reject(spawnError);
+					else resolve({
+						stdout,
+						stderr,
+						exitCode: spawnError ? spawnError.code : 0
+					});
+				});
+			});
+		}
+	};
+}
+/** Registers an `afterEach` cleanup, so call it at the top level of a test file. */
+function useTemporaryDirectories(prefix = "cli-test-") {
+	const directories = [];
+	afterEach(() => {
+		while (directories.length > 0) rmSync(directories.pop(), {
+			recursive: true,
+			force: true
+		});
+	});
+	return (files = {}) => {
+		const directory = mkdtempSync(path.join(os.tmpdir(), prefix));
+		directories.push(directory);
+		for (const [relativePath, contents] of Object.entries(files)) {
+			const filePath = path.join(directory, relativePath);
+			mkdirSync(path.dirname(filePath), { recursive: true });
+			writeFileSync(filePath, contents, "utf-8");
+		}
+		return directory;
+	};
+}
+function mockStdin(input) {
+	const stream = Readable.from([new TextEncoder().encode(input)]);
+	const originalStdin = process.stdin;
+	Object.defineProperty(process, "stdin", {
+		value: stream,
+		writable: true
+	});
+	return () => {
+		Object.defineProperty(process, "stdin", {
+			value: originalStdin,
+			writable: true
+		});
+	};
+}
+//#endregion
+export { createCliHarness, mockStdin, useTemporaryDirectories };

package/dist/cli/usage.mjs

@@ -0,0 +1,65 @@
+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 } = {}) {
+	const color = (style, text) => paint(style, text, stream);
+	const heading = (title) => color(["bold", "underline"], 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 = [];
+	const usageLine = [];
+	for (const [name, definition] of Object.entries(command.args ?? {})) {
+		const isRequired = definition.type !== "boolean" && definition.required === true;
+		const hasDefault = definition.type !== "positional" && definition.default !== void 0 && definition.default !== false;
+		const hints = [
+			definition.description,
+			isRequired ? color("gray", "(Required)") : void 0,
+			hasDefault ? color("gray", `(Default: ${definition.default})`) : void 0
+		].filter((hint) => hint !== void 0).join(" ");
+		if (definition.type === "positional") {
+			const label = name.toUpperCase();
+			positionalLines.push([color("cyan", label), hints]);
+			usageLine.push(isRequired ? `<${label}>` : `[${label}]`);
+			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;
+		optionLines.push([color("cyan", value === void 0 ? spellings : `${spellings}=${value}`), hints]);
+		if (definition.type === "boolean" && definition.default === true) optionLines.push([color("cyan", `--no-${name}`), ""]);
+		if (isRequired) usageLine.push(`--${name}=${value}`);
+	}
+	for (const [name, subCommand] of Object.entries(command.subCommands ?? {})) commandLines.push([color("cyan", name), subCommand.meta?.description ?? ""]);
+	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}`})`),
+		"",
+		`${heading("USAGE")} ${color("cyan", [
+			commandName,
+			hasArguments ? "[OPTIONS]" : void 0,
+			...usageLine
+		].filter((part) => part !== void 0).join(" "))}`,
+		""
+	];
+	for (const [title, rows] of [
+		["ARGUMENTS", positionalLines],
+		["OPTIONS", optionLines],
+		["COMMANDS", commandLines]
+	]) if (rows.length > 0) lines.push(heading(title), "", formatColumns(rows), "");
+	if (commandLines.length > 0) lines.push(`Use ${color("cyan", `${commandName} <command> --help`)} for more information about a command.`);
+	return lines.join("\n").trimEnd();
+}
+function formatColumns(rows) {
+	const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => visibleLength(row[column]))));
+	return rows.map((row) => row.map((cell, column) => `  ${cell}${" ".repeat(widths[column] - visibleLength(cell))}`).join("").trimEnd()).join("\n");
+}
+function visibleLength(text) {
+	return stripVTControlCharacters(text).length;
+}
+//#endregion
+export { renderUsage };

package/dist/csv.d.mts

@@ -106,8 +106,8 @@ declare function createCSVAsync<T extends Record<string, unknown>>(data: AsyncIt
  * Within quoted values, double quotes are escaped by doubling them.
  *
  * @example
- * escapeCSVValue('hello, world') // "hello, world"
- * escapeCSVValue('contains "quotes"') // "contains ""quotes"""
+ * escapeCSVValue('hello, world') // '"hello, world"'
+ * escapeCSVValue('contains "quotes"') // '"contains ""quotes"""'
  */
 declare function escapeCSVValue(value: unknown, options?: {
   /** @default ',' */

package/dist/csv.mjs

@@ -17,9 +17,9 @@ function createCSV(data, columnsOrOptions, maybeOptions = {}) {
 		columns = inferColumns(data);
 		options = columnsOrOptions ?? {};
 	}
-	if (columns.length === 0 && data.length === 0) return "";
 	const { delimiter = COMMA, addHeader = true, quoteAll = false, lineEnding = NEWLINE } = options;
 	assertValidCSVDelimiter(delimiter);
+	if (columns.length === 0) return "";
 	if (addHeader) {
 		const header = encodeCSVHeader(columns.map(String), delimiter, quoteAll);
 		if (data.length === 0) return header;
@@ -97,8 +97,8 @@ function encodeCSVRow(row, columns, delimiter, quoteAll) {
 * Within quoted values, double quotes are escaped by doubling them.
 *
 * @example
-* escapeCSVValue('hello, world') // "hello, world"
-* escapeCSVValue('contains "quotes"') // "contains ""quotes"""
+* escapeCSVValue('hello, world') // '"hello, world"'
+* escapeCSVValue('contains "quotes"') // '"contains ""quotes"""'
 */
 function escapeCSVValue(value, options = {}) {
 	const { delimiter = COMMA, quoteAll = false } = options;

package/dist/emitter.d.mts

@@ -4,8 +4,8 @@ type Handler<T = unknown> = (event: T) => void;
 type WildcardHandler<T = Record<string, unknown>> = (type: keyof T, event: T[keyof T]) => void;
 type EventHandlerList<T = unknown> = Handler<T>[];
 type WildCardEventHandlerList<T = Record<string, unknown>> = WildcardHandler<T>[];
-type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<keyof Events | "*", EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>>;
-interface Emitter<Events extends Record<EventType, unknown>> {
+type EventHandlerMap<Events extends Record<EventType, any>> = Map<keyof Events | "*", EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>>;
+interface Emitter<Events extends Record<EventType, any>> {
   events: EventHandlerMap<Events>;
   on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): void;
   on(type: "*", handler: WildcardHandler<Events>): void;
@@ -20,6 +20,6 @@ interface Emitter<Events extends Record<EventType, unknown>> {
  * @remarks Ported from `mitt`.
  * @see https://github.com/developit/mitt
  */
-declare function createEmitter<Events extends Record<EventType, unknown>>(events?: EventHandlerMap<Events>): Emitter<Events>;
+declare function createEmitter<Events extends Record<EventType, any>>(events?: EventHandlerMap<Events>): Emitter<Events>;
 //#endregion
 export { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter };

package/dist/emitter.mjs

@@ -14,8 +14,6 @@ function createEmitter(events) {
 		events,
 		/**
 		* Registers an event handler for the given type.
-		*
-		* @memberOf createEmitter
 		*/
 		on(type, handler) {
 			const handlers = events.get(type);
@@ -27,8 +25,6 @@ function createEmitter(events) {
 		*
 		* @remarks
 		* If `handler` is omitted, all handlers of the given type are removed.
-		*
-		* @memberOf createEmitter
 		*/
 		off(type, handler) {
 			const handlers = events.get(type);
@@ -41,8 +37,6 @@ function createEmitter(events) {
 		* @remarks
 		* If present, `'*'` handlers are invoked after type-matched handlers.
 		* Manually firing `'*'` handlers is not supported.
-		*
-		* @memberOf createEmitter
 		*/
 		emit(type, evt) {
 			let handlers = events.get(type);

package/dist/index.d.mts

@@ -5,8 +5,8 @@ import { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCar
 import { tryParseJSON } from "./json.mjs";
 import { interopDefault } from "./module.mjs";
 import { deepApply, isObject, memoize, objectEntries, objectKeys } from "./object.mjs";
-import { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.mjs";
+import { ParsedQuery, QueryObject, QueryValue, getPathname, getQuery, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.mjs";
 import { Err, ErrData, Ok, OkData, Result, ResultData, err, isErr, isOk, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
 import { TEMPLATE_PLACEHOLDER_RE, generateRandomId, template } from "./string.mjs";
-import { AutocompletableString, BrandedType, LooseAutocomplete, UnifyIntersection } from "./types.mjs";
-export { AutocompletableString, BrandedType, CSVCreateOptions, CSVParseOptions, CSVRow, Defu, DefuFn, DefuMerger, Emitter, Err, ErrData, EventHandlerList, EventHandlerMap, EventType, Handler, LooseAutocomplete, MaybeArray, Ok, OkData, QueryObject, QueryValue, Result, ResultData, TEMPLATE_PLACEHOLDER_RE, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, isErr, isObject, isOk, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+import { BrandedType, UnifyIntersection } from "./types.mjs";
+export { BrandedType, CSVCreateOptions, CSVParseOptions, CSVRow, Defu, DefuFn, DefuMerger, Emitter, Err, ErrData, EventHandlerList, EventHandlerMap, EventType, Handler, MaybeArray, Ok, OkData, ParsedQuery, QueryObject, QueryValue, Result, ResultData, TEMPLATE_PLACEHOLDER_RE, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, getQuery, interopDefault, isErr, isObject, isOk, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/index.mjs

@@ -5,7 +5,7 @@ import { createEmitter } from "./emitter.mjs";
 import { tryParseJSON } from "./json.mjs";
 import { interopDefault } from "./module.mjs";
 import { deepApply, isObject, memoize, objectEntries, objectKeys } from "./object.mjs";
-import { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.mjs";
+import { getPathname, getQuery, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.mjs";
 import { Err, Ok, err, isErr, isOk, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
 import { TEMPLATE_PLACEHOLDER_RE, generateRandomId, template } from "./string.mjs";
-export { Err, Ok, TEMPLATE_PLACEHOLDER_RE, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, isErr, isObject, isOk, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+export { Err, Ok, TEMPLATE_PLACEHOLDER_RE, createCSV, createCSVAsync, createCSVStream, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, getQuery, interopDefault, isErr, isObject, isOk, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, parseCSVStream, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/object.d.mts

@@ -23,9 +23,14 @@ declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${Extrac
  */
 declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof T, T[keyof T]]>;
 /**
- * Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays (including arrays nested inside arrays).
+ * Applies a callback to every key-value pair of the given object, and to every pair
+ * inside nested objects and arrays (including arrays nested inside arrays).
+ *
+ * @remarks
+ * The callback also fires for nested objects, so `item` is whichever object the pair
+ * belongs to rather than the one that was passed in.
  */
-declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void;
+declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: Record<string, any>, key: string, value: any) => void): void;
 /**
  * Checks if a value is an object with the plain `[object Object]` tag.
  *

package/dist/object.mjs

@@ -31,7 +31,12 @@ function objectEntries(obj) {
 	return Object.entries(obj);
 }
 /**
-* Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays (including arrays nested inside arrays).
+* Applies a callback to every key-value pair of the given object, and to every pair
+* inside nested objects and arrays (including arrays nested inside arrays).
+*
+* @remarks
+* The callback also fires for nested objects, so `item` is whichever object the pair
+* belongs to rather than the one that was passed in.
 */
 function deepApply(data, callback) {
 	for (const [key, value] of Object.entries(data)) {

package/dist/path.d.mts

@@ -1,6 +1,8 @@
 //#region src/path.d.ts
 type QueryValue = string | number | boolean | QueryValue[] | Record<string, any> | null | undefined;
 type QueryObject = Record<string, QueryValue | QueryValue[]>;
+/** Query parameters as read back from a URL, where a repeated key holds all its values. */
+type ParsedQuery = Record<string, string | string[]>;
 /**
  * Removes the leading slash from the given path if it has one.
  */
@@ -25,6 +27,11 @@ declare function withTrailingSlash(path?: string): string;
 declare function joinURL(...paths: (string | undefined)[]): string;
 /**
  * Adds the base path to the input path, if it is not already present.
+ *
+ * @remarks
+ * An absolute URL is returned as it is, since a base path cannot prefix one –
+ * whether it carries a scheme (`https://example.com/foo`) or is protocol-relative
+ * (`//example.com/foo`).
  */
 declare function withBase(input?: string, base?: string): string;
 /**
@@ -35,13 +42,23 @@ declare function withoutBase(input?: string, base?: string): string;
  * Returns the pathname of the given path, which is the path without the query string or hash.
  *
  * @remarks
- * Absolute URLs (with a scheme, e.g. `https://example.com/foo`) return the URL's pathname.
- * All other inputs are returned unchanged with the query string and hash removed.
+ * Absolute URLs return the segment after the authority, whether they carry a
+ * scheme (`https://example.com/foo`) or are protocol-relative (`//example.com/foo`).
+ * The result is sliced out verbatim, never normalized, so percent-encoding and
+ * `..` segments survive as written.
  */
 declare function getPathname(path?: string): string;
 /**
  * Returns the URL with the given query parameters. If a query parameter is `undefined`, it is omitted.
  */
 declare function withQuery(input: string, query?: QueryObject): string;
+/**
+ * Reads the query parameters of the given URL, ignoring the fragment.
+ *
+ * @remarks
+ * A parameter that appears more than once becomes an array of its values,
+ * in the order they appear. Values are percent-decoded.
+ */
+declare function getQuery(input: string): ParsedQuery;
 //#endregion
-export { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+export { ParsedQuery, QueryObject, QueryValue, getPathname, getQuery, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/path.mjs

@@ -1,4 +1,14 @@
 //#region src/path.ts
+const URL_SCHEME_RE = /^[a-z][\w+.-]*:\/\//i;
+/**
+* Returns the index at which the authority of an absolute URL starts, or `-1`
+* for a path that carries none. A protocol-relative input such as
+* `//example.com/foo` counts as absolute: its authority follows the leading `//`.
+*/
+function getAuthorityStart(path) {
+	if (path.startsWith("//")) return 2;
+	return URL_SCHEME_RE.test(path) ? path.indexOf("://") + 3 : -1;
+}
 /**
 * Removes the leading slash from the given path if it has one.
 */
@@ -66,9 +76,14 @@ function joinURL(...paths) {
 }
 /**
 * Adds the base path to the input path, if it is not already present.
+*
+* @remarks
+* An absolute URL is returned as it is, since a base path cannot prefix one –
+* whether it carries a scheme (`https://example.com/foo`) or is protocol-relative
+* (`//example.com/foo`).
 */
 function withBase(input = "", base = "") {
-	if (!base || base === "/") return input;
+	if (!base || base === "/" || getAuthorityStart(input) !== -1) return input;
 	const _base = withoutTrailingSlash(base);
 	if (input.startsWith(_base) && (input.length === _base.length || input[_base.length] === "/" || input[_base.length] === "?" || input[_base.length] === "#")) return input;
 	return joinURL(_base, input);
@@ -83,32 +98,47 @@ function withoutBase(input = "", base = "") {
 	const trimmed = input.slice(_base.length);
 	return trimmed[0] === "/" ? trimmed : `/${trimmed}`;
 }
-const URL_SCHEME_RE = /^[a-z][\w+.-]*:\/\//i;
 /**
 * Returns the pathname of the given path, which is the path without the query string or hash.
 *
 * @remarks
-* Absolute URLs (with a scheme, e.g. `https://example.com/foo`) return the URL's pathname.
-* All other inputs are returned unchanged with the query string and hash removed.
+* Absolute URLs return the segment after the authority, whether they carry a
+* scheme (`https://example.com/foo`) or are protocol-relative (`//example.com/foo`).
+* The result is sliced out verbatim, never normalized, so percent-encoding and
+* `..` segments survive as written.
 */
 function getPathname(path = "/") {
-	if (URL_SCHEME_RE.test(path)) return new URL(path).pathname;
+	let pathStart = 0;
+	const authorityStart = getAuthorityStart(path);
+	if (authorityStart !== -1) {
+		let authorityEnd = path.length;
+		for (let i = authorityStart; i < path.length; i++) {
+			const character = path[i];
+			if (character === "/" || character === "?" || character === "#") {
+				authorityEnd = i;
+				break;
+			}
+		}
+		if (path[authorityEnd] !== "/") return "/";
+		pathStart = authorityEnd;
+	}
 	let pathEnd = path.length;
-	const queryIndex = path.indexOf("?");
-	const hashIndex = path.indexOf("#");
+	const queryIndex = path.indexOf("?", pathStart);
+	const hashIndex = path.indexOf("#", pathStart);
 	if (queryIndex !== -1) pathEnd = queryIndex;
 	if (hashIndex !== -1 && hashIndex < pathEnd) pathEnd = hashIndex;
-	return path.slice(0, pathEnd) || "/";
+	return path.slice(pathStart, pathEnd) || "/";
 }
 /**
 * Returns the URL with the given query parameters. If a query parameter is `undefined`, it is omitted.
 */
 function withQuery(input, query) {
 	if (!query || Object.keys(query).length === 0) return input;
-	const searchIndex = input.indexOf("?");
+	const { beforeHash, hash } = splitFragment(input);
+	const searchIndex = beforeHash.indexOf("?");
 	const hasExistingParams = searchIndex !== -1;
-	const base = hasExistingParams ? input.slice(0, searchIndex) : input;
-	const searchParams = new URLSearchParams(hasExistingParams ? input.slice(searchIndex + 1) : void 0);
+	const base = hasExistingParams ? beforeHash.slice(0, searchIndex) : beforeHash;
+	const searchParams = new URLSearchParams(hasExistingParams ? beforeHash.slice(searchIndex + 1) : void 0);
 	for (const [key, value] of Object.entries(query)) {
 		if (value === void 0) {
 			searchParams.delete(key);
@@ -120,7 +150,37 @@ function withQuery(input, query) {
 		} else searchParams.set(key, normalizeQueryValue(value));
 	}
 	const queryString = searchParams.toString();
-	return queryString ? `${base}?${queryString}` : base;
+	return queryString ? `${base}?${queryString}${hash}` : base + hash;
+}
+/**
+* Reads the query parameters of the given URL, ignoring the fragment.
+*
+* @remarks
+* A parameter that appears more than once becomes an array of its values,
+* in the order they appear. Values are percent-decoded.
+*/
+function getQuery(input) {
+	const { beforeHash } = splitFragment(input);
+	const searchIndex = beforeHash.indexOf("?");
+	if (searchIndex === -1) return {};
+	const query = Object.create(null);
+	for (const [key, value] of new URLSearchParams(beforeHash.slice(searchIndex + 1))) {
+		const existingValue = query[key];
+		if (existingValue === void 0) query[key] = value;
+		else if (Array.isArray(existingValue)) existingValue.push(value);
+		else query[key] = [existingValue, value];
+	}
+	return { ...query };
+}
+function splitFragment(input) {
+	const hashIndex = input.indexOf("#");
+	return hashIndex === -1 ? {
+		beforeHash: input,
+		hash: ""
+	} : {
+		beforeHash: input.slice(0, hashIndex),
+		hash: input.slice(hashIndex)
+	};
 }
 function normalizeQueryValue(value) {
 	if (value === null) return "";
@@ -129,4 +189,4 @@ function normalizeQueryValue(value) {
 	return String(value);
 }
 //#endregion
-export { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+export { getPathname, getQuery, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };