utilful 2.5.2 → 3.0.0

package/README.md

@@ -13,13 +13,12 @@ A collection of TypeScript utilities that I use across my projects.
   - [JSON](#json)
   - [Module](#module)
   - [Object](#object)
+  - [Path](#path)
   - [Result](#result)
   - [String](#string)
 
 ## Installation
 
-Run the following command to add `utilful` to your project.
-
 ```bash
 # npm
 npm install -D utilful
@@ -105,30 +104,34 @@ const csv = createCSV(rows)
 Parses a comma-separated values (CSV) string into an array of objects.
 
 > [!NOTE]
-> The first row of the CSV string is used as the header row.
+> The first row of the CSV string is used as the header row. A leading UTF-8 byte order mark is stripped.
 
 ```ts
 type CSVRow<T extends string = string> = Record<T, string>
 
+interface CSVParseOptions {
+  /** @default ',' */
+  delimiter?: string
+  /**
+   * Trim whitespace from unquoted headers and values.
+   * @default false
+   */
+  trim?: boolean
+  /**
+   * Throw if a row's field count does not match the header row.
+   * @default true
+   */
+  strict?: boolean
+}
+
 declare function parseCSV<Header extends string>(
   csv?: string | null | undefined,
-  options?: {
-    /** @default ',' */
-    delimiter?: string
-    /**
-     * Trim whitespace from headers and values.
-     * @default true
-     */
-    trim?: boolean
-    /**
-     * Throw error if row has more fields than headers.
-     * @default true
-     */
-    strict?: boolean
-  }
+  options?: CSVParseOptions
 ): 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).
+
 **Example:**
 
 ```ts
@@ -141,6 +144,88 @@ Jane,25
 const data = parseCSV<'name' | 'age'>(csv) // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
 ```
 
+#### `createCSVStream`
+
+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.
+
+```ts
+declare function createCSVStream<T extends Record<string, unknown>>(
+  data: AsyncIterable<T> | Iterable<T>,
+  columns: readonly (keyof T)[],
+  options?: CSVCreateOptions
+): AsyncIterable<string>
+```
+
+**Example:**
+
+```ts
+for await (const chunk of createCSVStream(rows, ['name', 'age'])) {
+  process.stdout.write(chunk)
+}
+```
+
+#### `createCSVAsync`
+
+Convenience wrapper around `createCSVStream` that collects all chunks into a single string.
+
+> [!NOTE]
+> Unlike `createCSV`, the result has a trailing line ending.
+
+```ts
+declare function createCSVAsync<T extends Record<string, unknown>>(
+  data: AsyncIterable<T> | Iterable<T>,
+  columns: readonly (keyof T)[],
+  options?: CSVCreateOptions
+): Promise<string>
+```
+
+#### `parseCSVStream`
+
+Parses CSV data from an iterable or async iterable of string chunks, yielding rows as soon as they are complete. Chunks do not need to align with row boundaries – quotes and newlines are handled correctly across chunk boundaries.
+
+```ts
+declare function parseCSVStream<Header extends string>(
+  chunks: AsyncIterable<string> | Iterable<string>,
+  options?: CSVParseOptions
+): AsyncIterable<CSVRow<Header>>
+```
+
+**Example:**
+
+```ts
+const chunks = ['name,age\nJo', 'hn,30\nJane,25']
+
+for await (const row of parseCSVStream<'name' | 'age'>(chunks)) {
+  console.log(row) // { name: 'John', age: '30' }, then { name: 'Jane', age: '25' }
+}
+```
+
+> [!TIP]
+> `parseCSVStream` accepts any iterable of strings, including an array of lines.
+
+#### `escapeCSVValue`
+
+Escapes a single value for a CSV string. Returns an empty string for `null` and `undefined`. Values containing delimiters, quotes, or line breaks are quoted; embedded quotes are doubled.
+
+```ts
+declare function escapeCSVValue(
+  value: unknown,
+  options?: {
+    /** @default ',' */
+    delimiter?: string
+    /** @default false */
+    quoteAll?: boolean
+  }
+): string
+```
+
+**Example:**
+
+```ts
+escapeCSVValue('hello, world') // '"hello, world"'
+escapeCSVValue('contains "quotes"') // '"contains ""quotes"""'
+```
+
 ### Defu
 
 Recursively assign default properties. Simplified version based on [unjs/defu](https://github.com/unjs/defu).
@@ -154,10 +239,17 @@ The function replaces `null` and `undefined` values in the source with defaults,
 ```ts
 type PlainObject = Record<PropertyKey, any>
 
-declare function defu<T extends PlainObject>(
-  source: T,
-  ...defaults: PlainObject[]
-): T
+declare function defu<Source extends PlainObject, Defaults extends PlainObject[]>(
+  source: Source,
+  ...defaults: Defaults
+): Defu<Source, Defaults>
+```
+
+The return type is a deep merge of the source over the defaults, so keys that only exist in the defaults are part of the result type:
+
+```ts
+const result = defu({ a: 1 }, { b: 2 })
+result.b // number – no cast needed
 ```
 
 **Example:**
@@ -262,25 +354,14 @@ emitter.off('foo', onFoo) // Unlisten
 
 #### `tryParseJSON`
 
-Type-safe wrapper around `JSON.stringify`.
+Type-safe wrapper around `JSON.parse`.
 
-Falls back to the original value if the JSON serialization fails or the value is not a string.
+Falls back to the original value if parsing fails or the value is not a string.
 
 ```ts
 declare function tryParseJSON<T = unknown>(value: unknown): T
 ```
 
-#### `cloneJSON`
-
-Clones the given JSON value.
-
-> [!NOTE]
-> The value must not contain circular references as JSON does not support them. It also must contain JSON serializable values.
-
-```ts
-declare function cloneJSON<T>(value: T): T
-```
-
 ### Module
 
 #### `interopDefault`
@@ -312,7 +393,7 @@ A simple general purpose memoizer utility.
 - 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 invokation, since the getter itself is overwritten with the memoized value.
+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.
 
 ```ts
 declare function memoize<T>(getter: () => T): { value: T }
@@ -321,7 +402,7 @@ declare function memoize<T>(getter: () => T): { value: T }
 **Example:**
 
 ```ts
-const myValue = lazy(() => 'Hello, World!')
+const myValue = memoize(() => 'Hello, World!')
 console.log(myValue.value) // Computes value, overwrites getter
 console.log(myValue.value) // Returns cached value
 console.log(myValue.value) // Returns cached value
@@ -332,7 +413,7 @@ console.log(myValue.value) // Returns cached value
 Strictly typed `Object.keys`.
 
 ```ts
-declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${keyof T & (string | number | boolean | null | undefined)}`>
+declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${Extract<keyof T, string | number>}`>
 ```
 
 #### `objectEntries`
@@ -345,12 +426,97 @@ 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.
+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).
 
 ```ts
 declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => 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.
+
+```ts
+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.
+
+#### `withoutLeadingSlash` / `withLeadingSlash`
+
+Removes or adds a leading slash.
+
+```ts
+declare function withoutLeadingSlash(path?: string): string
+declare function withLeadingSlash(path?: string): string
+```
+
+#### `withoutTrailingSlash` / `withTrailingSlash`
+
+Removes or adds a trailing slash, preserving query strings and hash fragments.
+
+```ts
+declare function withoutTrailingSlash(path?: string): string
+declare function withTrailingSlash(path?: string): string
+```
+
+#### `joinURL`
+
+Joins the given URL path segments, ensuring that there is only one slash between them.
+
+```ts
+declare function joinURL(...paths: (string | undefined)[]): string
+```
+
+**Example:**
+
+```ts
+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).
+
+```ts
+declare function withBase(input?: string, base?: string): string
+declare function withoutBase(input?: string, base?: string): string
+```
+
+**Example:**
+
+```ts
+withBase('/users', '/api') // '/api/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.
+
+```ts
+declare function getPathname(path?: string): string
+```
+
+#### `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.
+
+```ts
+type QueryValue = string | number | boolean | QueryValue[] | Record<string, any> | null | undefined
+type QueryObject = Record<string, QueryValue | QueryValue[]>
+
+declare function withQuery(input: string, query?: QueryObject): string
+```
+
+**Example:**
+
+```ts
+withQuery('/api/users', { page: 2, tags: ['a', 'b'] }) // '/api/users?page=2&tags=a&tags=b'
+```
+
 ### Result
 
 The `Result` type represents either success (`Ok`) or failure (`Err`). It provides a type-safe way to handle errors without relying on exceptions.
@@ -492,6 +658,9 @@ declare function toResult<T, E = unknown>(fn: () => T): Result<T, E>
 declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>
 ```
 
+> [!NOTE]
+> The function overload must be synchronous. For asynchronous work, pass the promise itself – a function returning a promise throws a `TypeError`, since its rejection could not be captured as `Err`.
+
 **Example:**
 
 ```ts

package/dist/array.d.mts

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

package/dist/csv.d.mts

@@ -1,11 +1,11 @@
 //#region src/csv.d.ts
 /**
-* Represents a row in a CSV file with column names of type T.
-*/
+ * 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 `createCSV` function.
-*/
+ * Options for the CSV creation functions.
+ */
 interface CSVCreateOptions {
   /** @default ',' */
   delimiter?: string;
@@ -17,160 +17,150 @@ interface CSVCreateOptions {
   lineEnding?: string;
 }
 /**
-* Converts an array of objects to a comma-separated values (CSV) string.
-*
-* @remarks
-* When `columns` is omitted, the function automatically infers columns by collecting
-* the union of all keys across all objects in first-seen order. This means if different
-* objects have different keys, all keys will be included in the CSV. Objects missing
-* certain keys will have empty values for those columns.
-*
-* When `columns` is provided explicitly, only those columns are included in the output,
-* allowing you to control column order and filter out unwanted properties.
-*
-* @example
-* // With explicit columns
-* const data = [
-*   { name: 'John', age: '30', city: 'New York' },
-*   { name: 'Jane', age: '25', city: 'Boston' }
-* ]
-*
-* const csv = createCSV(data, ['name', 'age'])
-* // name,age
-* // John,30
-* // Jane,25
-*
-* @example
-* // With inferred columns (union of all keys in first-seen order)
-* const rows = [
-*   { name: 'John', age: '30' },
-*   { name: 'Jane', city: 'Boston' },
-* ]
-*
-* const csv = createCSV(rows)
-* // name,age,city
-* // John,30,
-* // Jane,,Boston
-*/
+ * Options for the CSV parsing functions.
+ */
+interface CSVParseOptions {
+  /** @default ',' */
+  delimiter?: string;
+  /**
+   * Trim whitespace from unquoted headers and values.
+   * @default false
+   */
+  trim?: boolean;
+  /**
+   * Throw if a row's field count does not match the header row.
+   * @default true
+   */
+  strict?: boolean;
+}
+/**
+ * Converts an array of objects to a comma-separated values (CSV) string.
+ *
+ * @remarks
+ * When `columns` is omitted, the function automatically infers columns by collecting
+ * the union of all keys across all objects in first-seen order. This means if different
+ * objects have different keys, all keys will be included in the CSV. Objects missing
+ * certain keys will have empty values for those columns.
+ *
+ * When `columns` is provided explicitly, only those columns are included in the output,
+ * allowing you to control column order and filter out unwanted properties.
+ *
+ * @example
+ * // With explicit columns
+ * const data = [
+ *   { name: 'John', age: '30', city: 'New York' },
+ *   { name: 'Jane', age: '25', city: 'Boston' }
+ * ]
+ *
+ * const csv = createCSV(data, ['name', 'age'])
+ * // name,age
+ * // John,30
+ * // Jane,25
+ *
+ * @example
+ * // With inferred columns (union of all keys in first-seen order)
+ * const rows = [
+ *   { name: 'John', age: '30' },
+ *   { name: 'Jane', city: 'Boston' },
+ * ]
+ *
+ * const csv = createCSV(rows)
+ * // name,age,city
+ * // John,30,
+ * // Jane,,Boston
+ */
 declare function createCSV<T extends Record<string, unknown>>(data: readonly T[], columns: readonly (keyof T)[], options?: CSVCreateOptions): string;
 declare function createCSV<T extends Record<string, unknown>>(data: readonly T[], options?: CSVCreateOptions): string;
 /**
-* Creates a CSV stream from an iterable or async iterable of objects.
-*
-* @remarks
-* This function yields CSV content as strings, including line endings.
-* Each yielded chunk contains complete lines (header and/or data rows).
-*
-* @example
-* const data = [
-*   { name: 'John', age: '30' },
-*   { name: 'Jane', age: '25' }
-* ]
-*
-* for await (const chunk of createCSVStream(data, ['name', 'age'])) {
-*   console.log(chunk)
-* }
-*/
+ * Creates a CSV stream from an iterable or async iterable of objects.
+ *
+ * @remarks
+ * This function yields CSV content as strings, including line endings.
+ * Each yielded chunk contains complete lines (header and/or data rows).
+ *
+ * @example
+ * const data = [
+ *   { name: 'John', age: '30' },
+ *   { name: 'Jane', age: '25' }
+ * ]
+ *
+ * for await (const chunk of createCSVStream(data, ['name', 'age'])) {
+ *   console.log(chunk)
+ * }
+ */
 declare function createCSVStream<T extends Record<string, unknown>>(data: AsyncIterable<T> | Iterable<T>, columns: readonly (keyof T)[], options?: CSVCreateOptions): AsyncIterable<string>;
 /**
-* Creates a CSV string from an async iterable or iterable of objects.
-*
-* @remarks
-* This is a convenience wrapper around `createCSVStream` that collects
-* all chunks into a single string. Note that the result will have a
-* trailing line ending, unlike the synchronous `createCSV`.
-*
-* @example
-* const data = [
-*   { name: 'John', age: '30' },
-*   { name: 'Jane', age: '25' }
-* ]
-*
-* const csv = await createCSVAsync(data, ['name', 'age'])
-*/
+ * Creates a CSV string from an async iterable or iterable of objects.
+ *
+ * @remarks
+ * This is a convenience wrapper around `createCSVStream` that collects
+ * all chunks into a single string. Note that the result will have a
+ * trailing line ending, unlike the synchronous `createCSV`.
+ *
+ * @example
+ * const data = [
+ *   { name: 'John', age: '30' },
+ *   { name: 'Jane', age: '25' }
+ * ]
+ *
+ * const csv = await createCSVAsync(data, ['name', 'age'])
+ */
 declare function createCSVAsync<T extends Record<string, unknown>>(data: AsyncIterable<T> | Iterable<T>, columns: readonly (keyof T)[], options?: CSVCreateOptions): Promise<string>;
 /**
-* Escapes a value for a CSV string.
-*
-* @remarks
-* Returns an empty string if the value is `null` or `undefined`.
-* Values containing delimiters, quotes, or line breaks are quoted.
-* Within quoted values, double quotes are escaped by doubling them.
-*
-* @example
-* escapeCSVValue('hello, world') // "hello, world"
-* escapeCSVValue('contains "quotes"') // "contains ""quotes"""
-*/
+ * Escapes a value for a CSV string.
+ *
+ * @remarks
+ * Returns an empty string if the value is `null` or `undefined`.
+ * Values containing delimiters, quotes, or line breaks are quoted.
+ * Within quoted values, double quotes are escaped by doubling them.
+ *
+ * @example
+ * escapeCSVValue('hello, world') // "hello, world"
+ * escapeCSVValue('contains "quotes"') // "contains ""quotes"""
+ */
 declare function escapeCSVValue(value: unknown, options?: {
-  /** @default ',' */delimiter?: string; /** @default false */
+  /** @default ',' */
+  delimiter?: string;
+  /** @default false */
   quoteAll?: boolean;
 }): string;
 /**
-* Parses a comma-separated values (CSV) string into an array of objects.
-*
-* @remarks
-* The first row of the CSV string is used as the header row.
-*
-* @example
-* const csv = `name,age
-* John,30
-* Jane,25`
-*
-* const data = parseCSV<'name' | 'age'>(csv)
-* // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
-*/
-declare function parseCSV<Header extends string>(csv?: string | null | undefined, options?: {
-  /** @default ',' */delimiter?: string;
-  /**
-  * Trim whitespace from headers and values.
-  * @default true
-  */
-  trim?: boolean;
-  /**
-  * Throw error if row has more fields than headers.
-  * @default true
-  */
-  strict?: boolean;
-}): CSVRow<Header>[];
+ * Parses a comma-separated values (CSV) string into an array of objects.
+ *
+ * @remarks
+ * The first row of the CSV string is used as the header row. A leading
+ * 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
+ * - A field is only treated as quoted if it starts with a quote; quotes inside
+ *   unquoted fields are kept as literal characters
+ *
+ * @example
+ * const csv = `name,age
+ * John,30
+ * Jane,25`
+ *
+ * const data = parseCSV<'name' | 'age'>(csv)
+ * // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
+ */
+declare function parseCSV<Header extends string>(csv?: string | null | undefined, options?: CSVParseOptions): CSVRow<Header>[];
 /**
-* Parses CSV data from an async iterable or iterable of string chunks.
-*
-* @remarks
-* This function yields CSV rows as they are parsed. Chunks do not need to
-* align with row boundaries; the parser handles quotes and newlines correctly
-* across chunk boundaries.
-*
-* @example
-* const chunks = ['name,age\nJo', 'hn,30\nJane,25']
-*
-* for await (const row of parseCSVStream<'name' | 'age'>(chunks)) {
-*   console.log(row)
-* }
-*/
-declare function parseCSVStream<Header extends string>(chunks: AsyncIterable<string> | Iterable<string>, options?: {
-  delimiter?: string;
-  trim?: boolean;
-  strict?: boolean;
-}): AsyncIterable<CSVRow<Header>>;
-/**
-* Parses CSV data from an async iterable or iterable of lines.
-*
-* @remarks
-* This is a convenience wrapper around `parseCSVStream` that treats each line
-* as a chunk. Note that lines do not necessarily correspond to CSV rows due to
-* quoted fields containing newlines. The parser handles this correctly.
-*
-* @example
-* const lines = ['name,age', 'John,30', 'Jane,25']
-*
-* for await (const row of parseCSVFromLines<'name' | 'age'>(lines)) {
-*   console.log(row)
-* }
-*/
-declare function parseCSVFromLines<Header extends string>(lines: AsyncIterable<string> | Iterable<string>, options?: {
-  delimiter?: string;
-  trim?: boolean;
-  strict?: boolean;
-}): AsyncIterable<CSVRow<Header>>;
+ * Parses CSV data from an async iterable or iterable of string chunks.
+ *
+ * @remarks
+ * This function yields CSV rows as they are parsed. Chunks do not need to
+ * align with row boundaries; the parser handles quotes and newlines correctly
+ * across chunk boundaries.
+ *
+ * @example
+ * const chunks = ['name,age\nJo', 'hn,30\nJane,25']
+ *
+ * for await (const row of parseCSVStream<'name' | 'age'>(chunks)) {
+ *   console.log(row)
+ * }
+ */
+declare function parseCSVStream<Header extends string>(chunks: AsyncIterable<string> | Iterable<string>, options?: CSVParseOptions): AsyncIterable<CSVRow<Header>>;
 //#endregion
-export { CSVCreateOptions, CSVRow, createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVFromLines, parseCSVStream };
+export { CSVCreateOptions, CSVParseOptions, CSVRow, createCSV, createCSVAsync, createCSVStream, escapeCSVValue, parseCSV, parseCSVStream };