utilful 2.2.3 → 2.3.0

package/README.md

@@ -50,26 +50,24 @@ declare function toArray<T>(array?: MaybeArray<T> | null | undefined): T[]
 
 #### `createCSV`
 
-Converts an array of objects to a comma-separated values (CSV) string that contains only the `columns` specified.
+Converts an array of objects to a comma-separated values (CSV) string. You can either specify which columns to include explicitly, or let the function automatically infer all columns from your data.
 
 ```ts
+// With explicit columns
 declare function createCSV<T extends Record<string, unknown>>(
-  data: T[],
+  data: readonly T[],
   columns: readonly (keyof T)[],
-  options?: {
-    /** @default ',' */
-    delimiter?: string
-    /** @default true */
-    addHeader?: boolean
-    /** @default false */
-    quoteAll?: boolean
-    /** @default '\n' */
-    lineEnding?: string
-  }
+  options?: CSVCreateOptions
+): string
+
+// With automatic column inference
+declare function createCSV<T extends Record<string, unknown>>(
+  data: readonly T[],
+  options?: CSVCreateOptions
 ): string
 ```
 
-**Example:**
+**Example with explicit columns:**
 
 ```ts
 const data = [
@@ -77,12 +75,32 @@ const data = [
   { name: 'Jane', age: '25', city: 'Boston' }
 ]
 
+// Only include 'name' and 'age' columns
 const csv = createCSV(data, ['name', 'age'])
 // name,age
 // John,30
 // Jane,25
 ```
 
+**Example with automatic column inference:**
+
+When you omit the `columns` parameter, `createCSV` automatically collects all unique keys from your data in first-seen order. This is particularly useful when working with data that has varying structures:
+
+```ts
+const rows = [
+  { name: 'John', age: '30' },
+  { name: 'Jane', city: 'Boston' },
+  { name: 'Bob', age: '40', city: 'Chicago' }
+]
+
+// All columns are automatically detected: name, age, city
+const csv = createCSV(rows)
+// name,age,city
+// John,30,
+// Jane,,Boston
+// Bob,40,Chicago
+```
+
 #### `parseCSV`
 
 Parses a comma-separated values (CSV) string into an array of objects.
@@ -119,7 +137,7 @@ const csv = `
 name,age
 John,30
 Jane,25
-`
+`.trim()
 
 const data = parseCSV<'name' | 'age'>(csv) // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
 ```
@@ -134,7 +152,7 @@ Recursively assigns missing properties from defaults to the source object. The s
 
 **Key Features:**
 
-- **Null/undefined handling**: `null` and `undefined` values in source are replaced with defaults
+- **Nullish handling**: `null` and `undefined` values in source are replaced with defaults
 - **Array concatenation**: Arrays are concatenated (source + defaults)
 - **Deep merging**: Nested objects are recursively merged
 - **Type safety**: Preserves TypeScript types
@@ -171,7 +189,7 @@ const result = defu(
 // Result: { items: ['a', 'b', 'c', 'd'] }
 ```
 
-**Null/undefined handling:**
+**Handling null/undefined:**
 
 ```ts
 const result = defu(
@@ -455,8 +473,6 @@ else
 
 The `Result` type represents either success (`Ok`) or failure (`Err`).
 
-**Type Definition:**
-
 ```ts
 type Result<T, E> = Ok<T> | Err<E>
 ```
@@ -485,8 +501,6 @@ const result = new Err('Something went wrong')
 
 Shorthand function to create an `Ok` result. Use it to wrap a successful value.
 
-**Type Definition:**
-
 ```ts
 declare function ok<T>(value: T): Ok<T>
 ```
@@ -495,8 +509,6 @@ declare function ok<T>(value: T): Ok<T>
 
 Shorthand function to create an `Err` result. Use it to wrap an error value.
 
-**Type Definition:**
-
 ```ts
 declare function err<E extends string = string>(err: E): Err<E>
 declare function err<E = unknown>(err: E): Err<E>
@@ -506,8 +518,6 @@ declare function err<E = unknown>(err: E): Err<E>
 
 Wraps a function that might throw an error and returns a `Result` with the result of the function.
 
-**Type Definition:**
-
 ```ts
 declare function toResult<T, E = unknown>(fn: () => T): Result<T, E>
 declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>
@@ -517,25 +527,28 @@ declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T
 
 Unwraps a `Result`, `Ok`, or `Err` value and returns the value or error in an object. If the result is an `Ok`, the object contains the value and an `undefined` error. If the result is an `Err`, the object contains an `undefined` value and the error.
 
-**Example:**
-
 ```ts
-const result = toResult(() => JSON.parse('{"foo":"bar"}'))
-const { value, error } = unwrapResult(result)
+declare function unwrapResult<T>(result: Ok<T>): { value: T, error: undefined }
+declare function unwrapResult<E>(result: Err<E>): { value: undefined, error: E }
+declare function unwrapResult<T, E>(result: Result<T, E>): { value: T, error: undefined } | { value: undefined, error: E }
 ```
 
-**Type Definition:**
+**Example:**
 
 ```ts
-declare function unwrapResult<T>(result: Ok<T>): { value: T, error: undefined }
-declare function unwrapResult<E>(result: Err<E>): { value: undefined, error: E }
-declare function unwrapResult<T, E>(result: Result<T, E>): { value: T, error: undefined } | { value: undefined, error: E }
+const result = toResult(() => JSON.parse('{"foo":"bar"}'))
+const { value, error } = unwrapResult(result)
 ```
 
 #### `tryCatch`
 
 A simpler alternative to `toResult` + `unwrapResult`. It executes a function that might throw an error and directly returns the result in a `ResultData` format. Works with both synchronous functions and promises.
 
+```ts
+declare function tryCatch<T, E = unknown>(fn: () => T): { value: T, error: undefined } | { value: undefined, error: E }
+declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<{ value: T, error: undefined } | { value: undefined, error: E }>
+```
+
 **Example:**
 
 ```ts
@@ -548,13 +561,6 @@ const { value, error } = tryCatch(() => JSON.parse('{"foo":"bar"}'))
 const { value, error } = await tryCatch(fetch('https://api.example.com/data').then(r => r.json()))
 ```
 
-**Type Definition:**
-
-```ts
-declare function tryCatch<T, E = unknown>(fn: () => T): { value: T, error: undefined } | { value: undefined, error: E }
-declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<{ value: T, error: undefined } | { value: undefined, error: E }>
-```
-
 ### String
 
 #### `template`

package/dist/csv.d.mts

@@ -4,10 +4,32 @@
 */
 type CSVRow<T extends string = string> = Record<T, string>;
 /**
-* Converts an array of objects to a comma-separated values (CSV) string
-* that contains only the `columns` specified.
+* Options for the `createCSV` function.
+*/
+interface CSVCreateOptions {
+  /** @default ',' */
+  delimiter?: string;
+  /** @default true */
+  addHeader?: boolean;
+  /** @default false */
+  quoteAll?: boolean;
+  /** @default '\n' */
+  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' }
@@ -17,17 +39,21 @@ type CSVRow<T extends string = string> = Record<T, string>;
 * // 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: T[], columns: readonly (keyof T)[], options?: {
-  /** @default ',' */
-  delimiter?: string;
-  /** @default true */
-  addHeader?: boolean;
-  /** @default false */
-  quoteAll?: boolean;
-  /** @default '\n' */
-  lineEnding?: string;
-}): string;
+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;
 /**
 * Escapes a value for a CSV string.
 *
@@ -75,4 +101,4 @@ declare function parseCSV<Header extends string>(csv?: string | null | undefined
   strict?: boolean;
 }): CSVRow<Header>[];
 //#endregion
-export { CSVRow, createCSV, escapeCSVValue, parseCSV };
+export { CSVCreateOptions, CSVRow, createCSV, escapeCSVValue, parseCSV };

package/dist/csv.mjs

@@ -1,20 +1,15 @@
 //#region src/csv.ts
-/**
-* Converts an array of objects to a comma-separated values (CSV) string
-* that contains only the `columns` specified.
-*
-* @example
-* 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
-*/
-function createCSV(data, columns, options = {}) {
+function createCSV(data, columnsOrOptions, maybeOptions = {}) {
+	let columns;
+	let options;
+	if (Array.isArray(columnsOrOptions)) {
+		columns = columnsOrOptions;
+		options = maybeOptions;
+	} else {
+		columns = inferColumns(data);
+		options = columnsOrOptions ?? {};
+	}
+	if (columns.length === 0 && data.length === 0) return "";
 	const { delimiter = ",", addHeader = true, quoteAll = false, lineEnding = "\n" } = options;
 	if (delimiter.length !== 1) throw new RangeError(`CSV delimiter must be a single character, got "${delimiter}"`);
 	const formatCell = (value) => escapeCSVValue(value, {
@@ -22,7 +17,11 @@ function createCSV(data, columns, options = {}) {
 		quoteAll
 	});
 	const rows = data.map((obj) => columns.map((key) => formatCell(obj[key])).join(delimiter));
-	if (addHeader) return columns.map(formatCell).join(delimiter) + lineEnding + rows.join(lineEnding);
+	if (addHeader) {
+		const header = columns.map(formatCell).join(delimiter);
+		if (rows.length === 0) return header;
+		return header + lineEnding + rows.join(lineEnding);
+	}
 	return rows.join(lineEnding);
 }
 /**
@@ -122,6 +121,20 @@ function parseCSV(csv, options = {}) {
 		}));
 	});
 }
+/**
+* Infers column names from data by collecting the union of keys
+* across all rows in first-seen order.
+*/
+function inferColumns(rows) {
+	const seenColumns = /* @__PURE__ */ new Set();
+	const columns = [];
+	for (const row of rows) if (row && typeof row === "object") for (const columnName of Object.keys(row)) {
+		if (seenColumns.has(columnName)) continue;
+		seenColumns.add(columnName);
+		columns.push(columnName);
+	}
+	return columns;
+}
 
 //#endregion
 export { createCSV, escapeCSVValue, parseCSV };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { MaybeArray, toArray } from "./array.mjs";
-import { CSVRow, createCSV, escapeCSVValue, parseCSV } from "./csv.mjs";
+import { CSVCreateOptions, CSVRow, createCSV, escapeCSVValue, parseCSV } from "./csv.mjs";
 import { DefuFn, DefuMerger, createDefu, defu } from "./defu.mjs";
 import { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter } from "./emitter.mjs";
 import { cloneJSON, tryParseJSON } from "./json.mjs";
@@ -9,4 +9,4 @@ import { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSla
 import { Err, ErrData, Ok, OkData, Result, ResultData, err, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
 import { generateRandomId, template } from "./string.mjs";
 import { AutocompletableString, BrandedType, LooseAutocomplete, UnifyIntersection } from "./types.mjs";
-export { AutocompletableString, BrandedType, CSVRow, DefuFn, DefuMerger, Emitter, Err, ErrData, EventHandlerList, EventHandlerMap, EventType, Handler, LooseAutocomplete, MaybeArray, Ok, OkData, QueryObject, QueryValue, Result, ResultData, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, cloneJSON, createCSV, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };
+export { AutocompletableString, BrandedType, CSVCreateOptions, CSVRow, DefuFn, DefuMerger, Emitter, Err, ErrData, EventHandlerList, EventHandlerMap, EventType, Handler, LooseAutocomplete, MaybeArray, Ok, OkData, QueryObject, QueryValue, Result, ResultData, UnifyIntersection, WildCardEventHandlerList, WildcardHandler, cloneJSON, createCSV, createDefu, createEmitter, deepApply, defu, err, escapeCSVValue, generateRandomId, getPathname, interopDefault, joinURL, memoize, objectEntries, objectKeys, ok, parseCSV, template, toArray, toResult, tryCatch, tryParseJSON, unwrapResult, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash };

package/dist/types.mjs

@@ -0,0 +1 @@
+export {  };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "packageManager": "pnpm@10.21.0",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",