utilful 3.0.2 → 3.1.0

package/README.md

@@ -21,13 +21,20 @@ A collection of TypeScript utilities that I use across my projects.
 
 ```bash
 # npm
-npm install -D utilful
+npm install utilful
 
 # pnpm
-pnpm add -D utilful
+pnpm add utilful
 
 # yarn
-yarn add -D utilful
+yarn add utilful
+```
+
+Every module is also available on its own subpath, so you can import just the part you need:
+
+```ts
+import { defu } from 'utilful' // Everything
+import { joinURL } from 'utilful/path' // Just the path helpers
 ```
 
 ## API
@@ -130,7 +137,12 @@ declare function parseCSV<Header extends string>(
 ): CSVRow<Header>[]
 ```
 
-The parser accepts a few lenient deviations from RFC 4180: LF, CR, and CRLF line endings are all recognized, whitespace between a closing quote and the next delimiter or line break is ignored, and quotes inside unquoted fields are kept as literal characters (a field only counts as quoted if it starts with a quote).
+The parser accepts a few lenient deviations from RFC 4180:
+
+- LF, CR, and CRLF line endings are all recognized
+- whitespace between a closing quote and the next delimiter or line break is ignored
+- quotes inside unquoted fields are kept as literal characters, since a field only counts as quoted if it starts with a quote
+- text following a closing quote is appended to the field rather than rejected, so `"ab" cd` parses as `abcd`
 
 **Example:**
 
@@ -148,6 +160,9 @@ const data = parseCSV<'name' | 'age'>(csv) // [{ name: 'John', age: '30' }, { na
 
 Creates a CSV stream from an iterable or async iterable of objects. Yields complete lines (header and/or data rows) including line endings – useful for large datasets that should not be buffered in memory.
 
+> [!NOTE]
+> Unlike `createCSV`, `columns` is required here. Inferring them would mean reading every row before writing the first one, which is exactly what streaming avoids.
+
 ```ts
 declare function createCSVStream<T extends Record<string, unknown>>(
   data: AsyncIterable<T> | Iterable<T>,
@@ -228,7 +243,7 @@ escapeCSVValue('contains "quotes"') // '"contains ""quotes"""'
 
 ### Defu
 
-Recursively assign default properties. Simplified version based on [unjs/defu](https://github.com/unjs/defu).
+Fills in missing properties from a chain of defaults. A trimmed-down take on [unjs/defu](https://github.com/unjs/defu).
 
 #### `defu`
 
@@ -286,7 +301,7 @@ const result = defu(
 
 #### `createDefu`
 
-Creates a custom defu function with a custom merger.
+Creates a `defu` variant that hands every property to your own merger first. Return `true` to signal you handled it; return nothing to fall back to the default behavior.
 
 ```ts
 type DefuMerger<T extends PlainObject = PlainObject> = (
@@ -325,8 +340,7 @@ Tiny functional event emitter / pubsub, based on [mitt](https://github.com/devel
 ```ts
 import { createEmitter } from 'utilful'
 
-// eslint-disable-next-line ts/consistent-type-definitions
-type Events = {
+interface Events {
   foo: { a: string }
 }
 
@@ -388,12 +402,9 @@ async function loadModule() {
 
 #### `memoize`
 
-A simple general purpose memoizer utility.
+Defers a computation until the value is first read, then caches it.
 
-- Lazily computes a value when accessed
-- Auto-caches the result by overwriting the getter
-
-Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invocation, since the getter itself is overwritten with the memoized value.
+Useful for expensive setup you may never need. Unlike a plain getter, there is no runtime cost after the first read, because the getter replaces itself with the computed value.
 
 ```ts
 declare function memoize<T>(getter: () => T): { value: T }
@@ -426,15 +437,20 @@ declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof
 
 #### `deepApply`
 
-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).
+
+The callback also fires for nested objects, so `item` is whichever object the pair belongs to rather than the one you passed in.
 
 ```ts
-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
 ```
 
 #### `isObject`
 
-Checks if a value is an object with the plain `[object Object]` tag. Returns `true` for object literals, class instances, and `null`-prototype objects.
+Checks whether a value is an object. Object literals, class instances, and `null`-prototype objects all count; arrays, `Date`, `RegExp`, and `null` do not.
 
 ```ts
 declare function isObject(value: unknown): value is Record<any, any>
@@ -442,7 +458,7 @@ declare function isObject(value: unknown): value is Record<any, any>
 
 ### Path
 
-Utilities to build and normalize URL paths. All of them are also available from the `utilful/path` subpath export.
+Utilities to build and normalize URL paths. They slice strings instead of parsing a full `URL`, which keeps them cheap enough for hot paths. Only `withQuery` and `getQuery` reach for `URLSearchParams`, where correct percent-encoding is worth the allocation.
 
 #### `withoutLeadingSlash` / `withLeadingSlash`
 
@@ -478,7 +494,7 @@ joinURL('/api/', '/users', '42') // '/api/users/42'
 
 #### `withBase` / `withoutBase`
 
-Adds or removes a base path – each is a no-op if the base is already present (or absent).
+Adds or removes a base path – each is a no-op if the base is already present (or absent). An absolute URL is returned as it is, since no base path can prefix it.
 
 ```ts
 declare function withBase(input?: string, base?: string): string
@@ -489,20 +505,36 @@ declare function withoutBase(input?: string, base?: string): string
 
 ```ts
 withBase('/users', '/api') // '/api/users'
+withBase('https://example.com/users', '/api') // 'https://example.com/users'
 withoutBase('/api/users', '/api') // '/users'
 ```
 
 #### `getPathname`
 
-Returns the pathname of the given path – everything before the query string or hash. 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.
+Returns the pathname of the given path – everything before the query string or hash. Absolute URLs return the part after the host, whether they carry a scheme (`https://example.com/foo`) or are protocol-relative (`//example.com/foo`).
+
+The pathname is sliced out as written and never normalized, so percent-encoding and `..` segments survive:
 
 ```ts
 declare function getPathname(path?: string): string
 ```
 
+```ts
+getPathname('/foo?bar#baz') // '/foo'
+getPathname('https://example.com/foo') // '/foo'
+getPathname('//example.com/foo') // '/foo'
+getPathname('https://example.com') // '/'
+getPathname('https://example.com/a/../b') // '/a/../b' – use `new URL` if you need this resolved
+```
+
 #### `withQuery`
 
-Returns the URL with the given query parameters merged in. `undefined` values remove the parameter, array values append one entry per item, and object values are JSON-stringified.
+Returns the URL with the given query parameters merged in. A fragment stays where it belongs, at the very end.
+
+- `undefined` removes the parameter
+- `null` keeps the parameter with an empty value
+- arrays append one entry per item, and empty arrays are skipped
+- objects are JSON-stringified
 
 ```ts
 type QueryValue = string | number | boolean | QueryValue[] | Record<string, any> | null | undefined
@@ -515,6 +547,25 @@ declare function withQuery(input: string, query?: QueryObject): string
 
 ```ts
 withQuery('/api/users', { page: 2, tags: ['a', 'b'] }) // '/api/users?page=2&tags=a&tags=b'
+withQuery('/api/users#list', { page: 2 }) // '/api/users?page=2#list'
+withQuery('/api/users?page=2', { page: undefined }) // '/api/users'
+```
+
+#### `getQuery`
+
+Reads the query parameters back out of a URL, ignoring the fragment. A parameter that appears more than once becomes an array of its values.
+
+```ts
+type ParsedQuery = Record<string, string | string[]>
+
+declare function getQuery(input: string): ParsedQuery
+```
+
+**Example:**
+
+```ts
+getQuery('/api/users?page=2&tags=a&tags=b') // { page: '2', tags: ['a', 'b'] }
+getQuery('/api/users') // {}
 ```
 
 ### Result
@@ -525,7 +576,7 @@ The `Result` type represents either success (`Ok`) or failure (`Err`). It provid
 type Result<T, E> = Ok<T, E> | Err<T, E>
 ```
 
-Both `Ok` and `Err` carry phantom types for proper type inference in unions.
+Both variants carry the success *and* the error type, so the two stay in sync as you chain `map` and `mapError` calls.
 
 **Basic example:**
 
@@ -616,7 +667,7 @@ Chains a function that returns a `Result`. Useful for composing fallible operati
 
 ```ts
 ok(2).andThen(x => x > 0 ? ok(x) : err('negative')) // Ok(2)
-err('fail').andThen(x => ok(x * 2)) // Err('fail') - short-circuits
+err('fail').andThen(x => ok(x * 2)) // Err('fail') – short-circuits
 ```
 
 #### `Result.unwrap`
@@ -629,6 +680,16 @@ err('fail').unwrap() // throws Error
 err('fail').unwrap('custom message') // throws Error('custom message')
 ```
 
+#### `Result.unwrapErr`
+
+Extracts the error, or throws if the result is `Ok`. The mirror image of `unwrap`.
+
+```ts
+err('fail').unwrapErr() // 'fail'
+ok(42).unwrapErr() // throws Error
+ok(42).unwrapErr('custom message') // throws Error('custom message')
+```
+
 #### `Result.unwrapOr`
 
 Extracts the value or returns a fallback.
@@ -690,6 +751,9 @@ declare function tryCatch<T, E = unknown>(fn: () => T): { value: T, error: undef
 declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<{ value: T, error: undefined } | { value: undefined, error: E }>
 ```
 
+> [!NOTE]
+> Like `toResult`, the function overload must be synchronous, and passing a function that returns a promise throws a `TypeError` rather than returning it as an error. Pass the promise itself.
+
 **Example:**
 
 ```ts
@@ -704,7 +768,9 @@ const { value, error } = await tryCatch(fetch('https://api.example.com').then(r
 
 #### `template`
 
-Simple template engine to replace variables in a string.
+Replaces `{name}` placeholders in a string with the matching variable.
+
+A placeholder with no matching variable is left as its own key, unless you pass a `fallback` – either a fixed string or a function receiving the key. A variable that is present but `null` or `undefined` is treated the same as a missing one. Only own properties are read, so `{constructor}` cannot reach prototype members.
 
 ```ts
 declare function template(
@@ -727,7 +793,10 @@ console.log(template(str, variables)) // Hello, world!
 
 #### `generateRandomId`
 
-Generates a random string. The function is ported from [`nanoid`](https://github.com/ai/nanoid). You can specify the size of the string and the dictionary of characters to use.
+Generates a random string. Ported from [`nanoid`](https://github.com/ai/nanoid). You can specify the length and the dictionary of characters to draw from.
+
+> [!WARNING]
+> Backed by `Math.random()` and therefore not cryptographically secure. Use `crypto.randomUUID()` or `crypto.getRandomValues()` for session tokens, password resets, and anything else an attacker would like to guess.
 
 ```ts
 declare function generateRandomId(size?: number, dict?: string): string

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 };

package/dist/result.d.mts

@@ -24,11 +24,10 @@ declare class Ok<T, E = never> {
   mapError<E2>(_fn: (error: E) => E2): Ok<T, E2>;
   /** Chains a `Result`-returning function. */
   andThen<U, E2>(fn: (value: T) => Result<U, E2>): Result<U, E | E2>;
-  /** Extracts the value. */
   unwrap(_message?: string): T;
+  unwrapErr(message?: string): never;
   /** Returns the value, ignoring the fallback. */
   unwrapOr<U>(_fallback: U): T;
-  /** Pattern matches on the `Result`. */
   match<R>(handlers: {
     ok: (value: T) => R;
     err: (error: E) => R;
@@ -49,11 +48,10 @@ declare class Err<T, E> {
   mapError<E2>(fn: (error: E) => E2): Err<T, E2>;
   /** Returns this `Err` unchanged, with a widened error type. */
   andThen<U, E2>(_fn: (value: T) => Result<U, E2>): Err<U, E | E2>;
-  /** Throws an error with the given message. */
   unwrap(message?: string): never;
+  unwrapErr(_message?: string): E;
   /** Returns the fallback value. */
   unwrapOr<U>(fallback: U): T | U;
-  /** Pattern matches on the `Result`. */
   match<R>(handlers: {
     ok: (value: T) => R;
     err: (error: E) => R;

package/dist/result.mjs

@@ -21,15 +21,16 @@ var Ok = class Ok {
 	andThen(fn) {
 		return fn(this.value);
 	}
-	/** Extracts the value. */
 	unwrap(_message) {
 		return this.value;
 	}
+	unwrapErr(message) {
+		throw new Error(message ?? `unwrapErr called on Ok: ${String(this.value)}`);
+	}
 	/** Returns the value, ignoring the fallback. */
 	unwrapOr(_fallback) {
 		return this.value;
 	}
-	/** Pattern matches on the `Result`. */
 	match(handlers) {
 		return handlers.ok(this.value);
 	}
@@ -56,15 +57,16 @@ var Err = class Err {
 	andThen(_fn) {
 		return this;
 	}
-	/** Throws an error with the given message. */
 	unwrap(message) {
-		throw new Error(message ?? `Unwrap called on Err: ${String(this.error)}`);
+		throw new Error(message ?? `unwrap called on Err: ${String(this.error)}`);
+	}
+	unwrapErr(_message) {
+		return this.error;
 	}
 	/** Returns the fallback value. */
 	unwrapOr(fallback) {
 		return fallback;
 	}
-	/** Pattern matches on the `Result`. */
 	match(handlers) {
 		return handlers.err(this.error);
 	}

package/dist/types.d.mts

@@ -1,6 +1,4 @@
 //#region src/types.d.ts
-type AutocompletableString = string & {};
-type LooseAutocomplete<T extends string> = T | AutocompletableString;
 /** Also commonly referred to as `Prettify`. */
 type UnifyIntersection<T> = { [K in keyof T]: T[K]; } & {};
 declare const brand: unique symbol;
@@ -8,4 +6,4 @@ type BrandedType<T, B> = T & {
   [brand]: B;
 };
 //#endregion
-export { AutocompletableString, BrandedType, LooseAutocomplete, UnifyIntersection };
+export { BrandedType, UnifyIntersection };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "packageManager": "pnpm@11.15.1",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
@@ -14,6 +14,15 @@
   "bugs": {
     "url": "https://github.com/johannschopplich/utilful/issues"
   },
+  "keywords": [
+    "csv",
+    "defu",
+    "emitter",
+    "result",
+    "typescript",
+    "url",
+    "utilities"
+  ],
   "sideEffects": false,
   "exports": {
     ".": {