utilful 3.0.1 → 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
@@ -113,12 +120,12 @@ interface CSVParseOptions {
   /** @default ',' */
   delimiter?: string
   /**
-   * Trim whitespace from unquoted headers and values.
+   * Whether to trim whitespace from unquoted headers and values.
    * @default false
    */
   trim?: boolean
   /**
-   * Throw if a row's field count does not match the header row.
+   * Whether to throw if a row's field count does not match the header row.
    * @default true
    */
   strict?: boolean
@@ -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/array.d.mts

@@ -1,11 +1,5 @@
 //#region src/array.d.ts
-/**
- * Represents a value that can be either a single value or an array of values.
- */
 type MaybeArray<T> = T | T[];
-/**
- * Converts `MaybeArray<T>` to `Array<T>`.
- */
 declare function toArray<T>(array?: MaybeArray<T> | null | undefined): T[];
 //#endregion
 export { MaybeArray, toArray };

package/dist/array.mjs

@@ -1,7 +1,4 @@
 //#region src/array.ts
-/**
-* Converts `MaybeArray<T>` to `Array<T>`.
-*/
 function toArray(array) {
 	array ??= [];
 	return Array.isArray(array) ? array : [array];

package/dist/csv.d.mts

@@ -1,11 +1,5 @@
 //#region src/csv.d.ts
-/**
- * Represents a row in a CSV file with column names of type T.
- */
 type CSVRow<T extends string = string> = Record<T, string>;
-/**
- * Options for the CSV creation functions.
- */
 interface CSVCreateOptions {
   /** @default ',' */
   delimiter?: string;
@@ -16,19 +10,16 @@ interface CSVCreateOptions {
   /** @default '\n' */
   lineEnding?: string;
 }
-/**
- * Options for the CSV parsing functions.
- */
 interface CSVParseOptions {
   /** @default ',' */
   delimiter?: string;
   /**
-   * Trim whitespace from unquoted headers and values.
+   * Whether to trim whitespace from unquoted headers and values.
    * @default false
    */
   trim?: boolean;
   /**
-   * Throw if a row's field count does not match the header row.
+   * Whether to throw if a row's field count does not match the header row.
    * @default true
    */
   strict?: boolean;
@@ -115,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 ',' */
@@ -132,10 +123,10 @@ declare function escapeCSVValue(value: unknown, options?: {
  * UTF-8 byte order mark is stripped.
  *
  * Parsing tolerances (lenient deviations from RFC 4180):
- * - LF, CR, and CRLF line endings are all accepted
- * - Whitespace between a closing quote and the next delimiter or line break is ignored
+ * - LF, CR, and CRLF line endings are all accepted.
+ * - Whitespace between a closing quote and the next delimiter or line break is ignored.
  * - A field is only treated as quoted if it starts with a quote; quotes inside
- *   unquoted fields are kept as literal characters
+ *   unquoted fields are kept as literal characters.
  *
  * @example
  * const csv = `name,age

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;
@@ -211,10 +211,10 @@ var CSVParserCore = class {
 * UTF-8 byte order mark is stripped.
 *
 * Parsing tolerances (lenient deviations from RFC 4180):
-* - LF, CR, and CRLF line endings are all accepted
-* - Whitespace between a closing quote and the next delimiter or line break is ignored
+* - LF, CR, and CRLF line endings are all accepted.
+* - Whitespace between a closing quote and the next delimiter or line break is ignored.
 * - A field is only treated as quoted if it starts with a quote; quotes inside
-*   unquoted fields are kept as literal characters
+*   unquoted fields are kept as literal characters.
 *
 * @example
 * const csv = `name,age

package/dist/defu.d.mts

@@ -1,19 +1,28 @@
 //#region src/defu.d.ts
 type PlainObject = Record<PropertyKey, any>;
 type DefuMerger<T extends PlainObject = PlainObject> = (target: T, key: PropertyKey, value: any, namespace: string) => boolean | void;
+type Nullish = null | undefined | void;
+/**
+ * Values that `isPlainObject` rejects at runtime, so the merged type keeps them
+ * intact rather than recursing into them. `PlainObject` cannot draw this line
+ * itself: its `any` value type makes every object type satisfy it, classes and
+ * built-ins included.
+ */
+type NonPlainObject = ((...args: any[]) => any) | {
+  [Symbol.iterator]: any;
+} | Date | RegExp | Promise<any> | Error | WeakMap<object, any> | WeakSet<object>;
 /**
  * Deeply merged result type of a source object over a list of defaults.
  */
 type Defu<Source, Defaults extends any[]> = Defaults extends [infer First, ...infer Rest] ? Defu<MergedObject<Source, First>, Rest> : Source;
-type MergedObject<Source, Defaults> = Source extends PlainObject ? Defaults extends PlainObject ? { [Key in keyof Source | keyof Defaults]: MergedValue<Key extends keyof Source ? Source[Key] : undefined, Key extends keyof Defaults ? Defaults[Key] : undefined>; } : Source : Source;
-type MergedValue<SourceValue, DefaultValue> = SourceValue extends null | undefined ? DefaultValue : SourceValue extends any[] ? DefaultValue extends any[] ? Array<SourceValue[number] | DefaultValue[number]> : SourceValue : SourceValue extends ((...args: any[]) => any) ? SourceValue : SourceValue extends PlainObject ? MergedObject<SourceValue, DefaultValue> : SourceValue;
 /**
- * Defu function type that accepts a source and multiple defaults
+ * Source merged over one defaults object, rebuilding only the shared keys.
+ * Everything else passes through `Omit`, which is what keeps optionality,
+ * `readonly` and the nominal identity of classes intact.
  */
+type MergedObject<Source, Defaults> = Source extends PlainObject ? Defaults extends PlainObject ? Source extends Defaults ? Source : Omit<Source, keyof Source & keyof Defaults> & Omit<Defaults, keyof Source & keyof Defaults> & { -readonly [Key in keyof Source & keyof Defaults]: MergedValue<Source[Key], Defaults[Key]>; } : Source : Source;
+type MergedValue<SourceValue, DefaultValue> = SourceValue extends Nullish ? DefaultValue : DefaultValue extends Nullish ? SourceValue : SourceValue extends readonly any[] ? DefaultValue extends readonly any[] ? Array<SourceValue[number] | DefaultValue[number]> : SourceValue : SourceValue extends NonPlainObject ? SourceValue : DefaultValue extends NonPlainObject ? SourceValue : MergedObject<SourceValue, DefaultValue>;
 type DefuFn = <Source extends PlainObject, Defaults extends PlainObject[]>(source: Source, ...defaults: Defaults) => Defu<Source, Defaults>;
-/**
- * Create a defu function with optional custom merger
- */
 declare function createDefu(merger?: DefuMerger): DefuFn;
 declare const defu: DefuFn;
 //#endregion

package/dist/defu.mjs

@@ -1,7 +1,4 @@
 //#region src/defu.ts
-/**
-* Create a defu function with optional custom merger
-*/
 function createDefu(merger) {
 	return ((source, ...defaults) => {
 		return defaults.reduce((mergedResult, currentDefaults) => _defu(mergedResult, currentDefaults ?? {}, "", merger), source ?? {});

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;
@@ -15,11 +15,11 @@ interface Emitter<Events extends Record<EventType, unknown>> {
   emit<Key extends keyof Events>(type: undefined extends Events[Key] ? Key : never): void;
 }
 /**
- * Simple functional event emitter / pubsub.
+ * Creates a functional pubsub event emitter.
  *
  * @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

@@ -1,6 +1,6 @@
 //#region src/emitter.ts
 /**
-* Simple functional event emitter / pubsub.
+* Creates a functional pubsub event emitter.
 *
 * @remarks Ported from `mitt`.
 * @see https://github.com/developit/mitt
@@ -13,9 +13,7 @@ function createEmitter(events) {
 		*/
 		events,
 		/**
-		* Register an event handler for the given type.
-		*
-		* @memberOf createEmitter
+		* Registers an event handler for the given type.
 		*/
 		on(type, handler) {
 			const handlers = events.get(type);
@@ -23,12 +21,10 @@ function createEmitter(events) {
 			else events.set(type, [handler]);
 		},
 		/**
-		* Remove an event handler for the given type.
+		* Removes an event handler for the given type.
 		*
 		* @remarks
 		* If `handler` is omitted, all handlers of the given type are removed.
-		*
-		* @memberOf createEmitter
 		*/
 		off(type, handler) {
 			const handlers = events.get(type);
@@ -36,13 +32,11 @@ function createEmitter(events) {
 			else events.set(type, []);
 		},
 		/**
-		* Invoke all handlers for the given type.
+		* Invokes all handlers for the given type.
 		*
 		* @remarks
 		* If present, `'*'` handlers are invoked after type-matched handlers.
-		* Manually firing '*' handlers is not supported.
-		*
-		* @memberOf createEmitter
+		* Manually firing `'*'` handlers is not supported.
 		*/
 		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/json.d.mts

@@ -1,6 +1,6 @@
 //#region src/json.d.ts
 /**
- * Type-safe wrapper around `JSON.parse`.
+ * Wraps `JSON.parse` with a typed return value.
  *
  * @remarks
  * Falls back to the original value if parsing fails or the value is not a string.

package/dist/json.mjs

@@ -1,6 +1,6 @@
 //#region src/json.ts
 /**
-* Type-safe wrapper around `JSON.parse`.
+* Wraps `JSON.parse` with a typed return value.
 *
 * @remarks
 * Falls back to the original value if parsing fails or the value is not a string.

package/dist/module.d.mts

@@ -1,6 +1,6 @@
 //#region src/module.d.ts
 /**
- * Interop helper for default exports.
+ * Unwraps a module's `default` export, or returns the module unchanged if it has none.
  *
  * @example
  * const mod = await interopDefault(import('./module.js'))

package/dist/module.mjs

@@ -1,6 +1,6 @@
 //#region src/module.ts
 /**
-* Interop helper for default exports.
+* Unwraps a module's `default` export, or returns the module unchanged if it has none.
 *
 * @example
 * const mod = await interopDefault(import('./module.js'))

package/dist/object.d.mts

@@ -1,8 +1,6 @@
 //#region src/object.d.ts
 /**
- * A simple general purpose memoizer utility.
- * - Lazily computes a value when accessed
- * - Auto-caches the result by overwriting the getter
+ * Wraps a getter so its value is computed on first access and cached from then on.
  *
  * @remarks
  * 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.
@@ -17,17 +15,22 @@ declare function memoize<T>(getter: () => T): {
   value: T;
 };
 /**
- * Strictly typed `Object.keys`.
+ * Wraps `Object.keys` with a stricter return type.
  */
 declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${Extract<keyof T, string | number>}`>;
 /**
- * Strictly typed `Object.entries`.
+ * Wraps `Object.entries` with a stricter return type.
  */
 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

@@ -1,8 +1,6 @@
 //#region src/object.ts
 /**
-* A simple general purpose memoizer utility.
-* - Lazily computes a value when accessed
-* - Auto-caches the result by overwriting the getter
+* Wraps a getter so its value is computed on first access and cached from then on.
 *
 * @remarks
 * 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.
@@ -21,19 +19,24 @@ function memoize(getter) {
 	} };
 }
 /**
-* Strictly typed `Object.keys`.
+* Wraps `Object.keys` with a stricter return type.
 */
 function objectKeys(obj) {
 	return Object.keys(obj);
 }
 /**
-* Strictly typed `Object.entries`.
+* Wraps `Object.entries` with a stricter return type.
 */
 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.
+ * 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.
+* 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

@@ -11,8 +11,8 @@ interface ErrData<E> {
 type ResultData<T, E> = OkData<T> | ErrData<E>;
 /**
  * Successful result variant.
- * @template T Success value type.
- * @template E Error type (phantom - for type unification).
+ * @template T Success value type
+ * @template E Error type (phantom – for type unification)
  */
 declare class Ok<T, E = never> {
   readonly value: T;
@@ -20,15 +20,14 @@ declare class Ok<T, E = never> {
   constructor(value: T);
   /** Transforms the success value. */
   map<U>(fn: (value: T) => U): Ok<U, E>;
-  /** No-op on Ok, returns self with new error type. */
+  /** Returns this `Ok` unchanged, with a new error type. */
   mapError<E2>(_fn: (error: E) => E2): Ok<T, E2>;
-  /** Chains a Result-returning function. */
+  /** 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;
@@ -36,24 +35,23 @@ declare class Ok<T, E = never> {
 }
 /**
  * Error result variant.
- * @template T Success type (phantom - for type unification).
- * @template E Error value type.
+ * @template T Success type (phantom – for type unification)
+ * @template E Error value type
  */
 declare class Err<T, E> {
   readonly error: E;
   readonly ok = false;
   constructor(error: E);
-  /** No-op on Err, returns self with new value type. */
+  /** Returns this `Err` unchanged, with a new value type. */
   map<U>(_fn: (value: T) => U): Err<U, E>;
   /** Transforms the error value. */
   mapError<E2>(fn: (error: E) => E2): Err<T, E2>;
-  /** No-op on Err, returns self with widened error type. */
+  /** 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

@@ -1,8 +1,8 @@
 //#region src/result.ts
 /**
 * Successful result variant.
-* @template T Success value type.
-* @template E Error type (phantom - for type unification).
+* @template T Success value type
+* @template E Error type (phantom – for type unification)
 */
 var Ok = class Ok {
 	constructor(value) {
@@ -13,38 +13,39 @@ var Ok = class Ok {
 	map(fn) {
 		return new Ok(fn(this.value));
 	}
-	/** No-op on Ok, returns self with new error type. */
+	/** Returns this `Ok` unchanged, with a new error type. */
 	mapError(_fn) {
 		return this;
 	}
-	/** Chains a Result-returning function. */
+	/** Chains a `Result`-returning function. */
 	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);
 	}
 };
 /**
 * Error result variant.
-* @template T Success type (phantom - for type unification).
-* @template E Error value type.
+* @template T Success type (phantom – for type unification)
+* @template E Error value type
 */
 var Err = class Err {
 	constructor(error) {
 		this.ok = false;
 		this.error = error;
 	}
-	/** No-op on Err, returns self with new value type. */
+	/** Returns this `Err` unchanged, with a new value type. */
 	map(_fn) {
 		return this;
 	}
@@ -52,19 +53,20 @@ var Err = class Err {
 	mapError(fn) {
 		return new Err(fn(this.error));
 	}
-	/** No-op on Err, returns self with widened error type. */
+	/** Returns this `Err` unchanged, with a widened error type. */
 	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/string.d.mts

@@ -1,7 +1,7 @@
 //#region src/string.d.ts
 declare const TEMPLATE_PLACEHOLDER_RE: RegExp;
 /**
- * Simple template engine to replace variables in a string.
+ * Replaces `{name}` placeholders in a string with the matching variable.
  *
  * @remarks
  * Only own properties of `variables` are substituted, so placeholders like

package/dist/string.mjs

@@ -2,7 +2,7 @@
 const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 const TEMPLATE_PLACEHOLDER_RE = /\{(\w+)\}/g;
 /**
-* Simple template engine to replace variables in a string.
+* Replaces `{name}` placeholders in a string with the matching variable.
 *
 * @remarks
 * Only own properties of `variables` are substituted, so placeholders like

package/dist/types.d.mts

@@ -1,11 +1,9 @@
 //#region src/types.d.ts
-type AutocompletableString = string & {};
-type LooseAutocomplete<T extends string> = T | AutocompletableString;
-/** Also commonly referred to as `Prettify` */
+/** Also commonly referred to as `Prettify`. */
 type UnifyIntersection<T> = { [K in keyof T]: T[K]; } & {};
 declare const brand: unique symbol;
 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.1",
+  "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": {
     ".": {