utilful 2.1.1 → 2.2.0

package/README.md

@@ -55,14 +55,16 @@ Converts an array of objects to a comma-separated values (CSV) string that conta
 ```ts
 declare function createCSV<T extends Record<string, unknown>>(
   data: T[],
-  columns: (keyof T)[],
+  columns: readonly (keyof T)[],
   options?: {
     /** @default ',' */
     delimiter?: string
     /** @default true */
-    includeHeaders?: boolean
+    addHeader?: boolean
     /** @default false */
     quoteAll?: boolean
+    /** @default '\n' */
+    lineEnding?: string
   }
 ): string
 ```
@@ -94,10 +96,18 @@ type CSVRow<T extends string = string> = Record<T, string>
 declare function parseCSV<Header extends string>(
   csv?: string | null | undefined,
   options?: {
-  /** @default ',' */
+    /** @default ',' */
     delimiter?: string
-    /** @default true */
-    trimValues?: boolean
+    /**
+     * 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>[]
 ```
@@ -105,9 +115,11 @@ declare function parseCSV<Header extends string>(
 **Example:**
 
 ```ts
-const csv = `name,age
+const csv = `
+name,age
 John,30
-Jane,25`
+Jane,25
+`
 
 const data = parseCSV<'name' | 'age'>(csv) // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
 ```

package/dist/{csv.d.ts → csv.d.mts}

@@ -18,13 +18,15 @@ type CSVRow<T extends string = string> = Record<T, string>;
 * // John,30
 * // Jane,25
 */
-declare function createCSV<T extends Record<string, unknown>>(data: T[], columns: (keyof T)[], options?: {
+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;
 /**
 * Escapes a value for a CSV string.
@@ -61,8 +63,16 @@ declare function escapeCSVValue(value: unknown, options?: {
 declare function parseCSV<Header extends string>(csv?: string | null | undefined, options?: {
   /** @default ',' */
   delimiter?: string;
-  /** @default true */
-  trimValues?: boolean;
+  /**
+  * 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>[];
 //#endregion
 export { CSVRow, createCSV, escapeCSVValue, parseCSV };

package/dist/csv.mjs

@@ -0,0 +1,119 @@
+//#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 = {}) {
+	const { delimiter = ",", addHeader = true, quoteAll = false, lineEnding = "\n" } = options;
+	const formatCell = (value) => escapeCSVValue(value, {
+		delimiter,
+		quoteAll
+	});
+	const rows = data.map((obj) => columns.map((key) => formatCell(obj[key])).join(delimiter));
+	if (addHeader) rows.unshift(columns.map(formatCell).join(delimiter));
+	return rows.join(lineEnding);
+}
+/**
+* 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"""
+*/
+function escapeCSVValue(value, options = {}) {
+	const { delimiter = ",", quoteAll = false } = options;
+	if (value == null) return "";
+	const coercedValue = String(value);
+	if (quoteAll || coercedValue.includes(delimiter) || coercedValue.includes("\"") || coercedValue.includes("\n") || coercedValue.includes("\r")) return `"${coercedValue.replaceAll("\"", "\"\"")}"`;
+	return coercedValue;
+}
+/**
+* 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' }]
+*/
+function parseCSV(csv, options = {}) {
+	if (!csv?.trim()) return [];
+	const rows = [];
+	let currentRow = [];
+	let currentField = "";
+	let inQuotes = false;
+	const { delimiter = ",", trim = true, strict = true } = options;
+	const appendField = () => {
+		currentRow.push(currentField);
+		currentField = "";
+	};
+	const appendRow = () => {
+		appendField();
+		rows.push(currentRow);
+		currentRow = [];
+	};
+	for (let i = 0; i < csv.length; i++) {
+		const character = csv[i];
+		const nextCharacter = i + 1 < csv.length ? csv[i + 1] : "";
+		if (character === "\"") if (inQuotes && nextCharacter === "\"") {
+			currentField += "\"";
+			i++;
+		} else inQuotes = !inQuotes;
+		else if (character === delimiter && !inQuotes) appendField();
+		else if ((character === "\n" || character === "\r" && nextCharacter === "\n") && !inQuotes) {
+			if (character === "\r") i++;
+			appendRow();
+		} else currentField += character;
+	}
+	if (currentField || currentRow.length > 0) appendRow();
+	if (rows.length <= 1) return [];
+	const [headerRow] = rows;
+	if (!headerRow) return [];
+	const headers = trim ? headerRow.map((h) => h.trim()) : headerRow;
+	if (headers.filter((h) => h.length === 0).length > 0) {
+		const positions = headers.map((h, i) => h.length === 0 ? i + 1 : -1).filter((i) => i > 0).join(", ");
+		throw new SyntaxError(`CSV header row contains empty column name(s) at position(s): ${positions}`);
+	}
+	const duplicateHeaderNames = headers.filter((h, i) => headers.indexOf(h) !== i);
+	if (duplicateHeaderNames.length > 0) throw new SyntaxError(`CSV header row contains duplicate column name(s): ${[...new Set(duplicateHeaderNames)].join(", ")}`);
+	const isFieldPopulated = trim ? (field) => field.trim().length > 0 : (field) => field.length > 0;
+	return rows.slice(1).filter((row) => row.length > 1 || row.some(isFieldPopulated)).map((fieldValues, rowIndex) => {
+		if (fieldValues.length > headers.length) {
+			const containsNonEmptyOverflow = fieldValues.slice(headers.length).some(isFieldPopulated);
+			if (strict && containsNonEmptyOverflow) {
+				const expectedCount = headers.length;
+				const actualCount = fieldValues.length;
+				const excessCount = actualCount - expectedCount;
+				throw new SyntaxError(`CSV row ${rowIndex + 2} has ${excessCount} extra field(s): expected ${expectedCount} column(s), found ${actualCount}`);
+			}
+		}
+		return Object.fromEntries(headers.map((header, columnIndex) => {
+			const untrimmedValue = columnIndex < fieldValues.length ? fieldValues[columnIndex] ?? "" : "";
+			return [header, trim ? untrimmedValue.trim() : untrimmedValue];
+		}));
+	});
+}
+
+//#endregion
+export { createCSV, escapeCSVValue, parseCSV };

package/dist/{defu.d.ts → defu.d.mts}

@@ -1,5 +1,4 @@
 //#region src/defu.d.ts
-// Forked from unjs/defu (MIT)
 type PlainObject = Record<PropertyKey, any>;
 type DefuMerger<T extends PlainObject = PlainObject> = (target: T, key: PropertyKey, value: any, namespace: string) => boolean | void;
 /**

package/dist/{emitter.d.ts → emitter.d.mts}

@@ -1,13 +1,9 @@
 //#region src/emitter.d.ts
-/* eslint-disable ts/method-signature-style */
 type EventType = string | symbol;
-// An event handler can take an optional event argument
-// and should not return a value
 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>[];
-// A map of event types and their corresponding event handlers.
 type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<keyof Events | "*", EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>>;
 interface Emitter<Events extends Record<EventType, unknown>> {
   events: EventHandlerMap<Events>;

package/dist/index.d.mts

@@ -0,0 +1,12 @@
+import { MaybeArray, toArray } from "./array.mjs";
+import { 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";
+import { interopDefault } from "./module.mjs";
+import { deepApply, memoize, objectEntries, objectKeys } from "./object.mjs";
+import { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.mjs";
+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 };

package/dist/{index.js → index.mjs}

@@ -1,12 +1,12 @@
-import { toArray } from "./array.js";
-import { createCSV, escapeCSVValue, parseCSV } from "./csv.js";
-import { createDefu, defu } from "./defu.js";
-import { createEmitter } from "./emitter.js";
-import { cloneJSON, tryParseJSON } from "./json.js";
-import { interopDefault } from "./module.js";
-import { deepApply, memoize, objectEntries, objectKeys } from "./object.js";
-import { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.js";
-import { Err, Ok, err, ok, toResult, tryCatch, unwrapResult } from "./result.js";
-import { generateRandomId, template } from "./string.js";
+import { toArray } from "./array.mjs";
+import { createCSV, escapeCSVValue, parseCSV } from "./csv.mjs";
+import { createDefu, defu } from "./defu.mjs";
+import { createEmitter } from "./emitter.mjs";
+import { cloneJSON, tryParseJSON } from "./json.mjs";
+import { interopDefault } from "./module.mjs";
+import { deepApply, memoize, objectEntries, objectKeys } from "./object.mjs";
+import { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.mjs";
+import { Err, Ok, err, ok, toResult, tryCatch, unwrapResult } from "./result.mjs";
+import { generateRandomId, template } from "./string.mjs";
 
 export { Err, Ok, 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.d.ts → types.d.mts}

@@ -3,5 +3,9 @@ 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;
+type BrandedType<T, B> = T & {
+  [brand]: B;
+};
 //#endregion
-export { AutocompletableString, LooseAutocomplete, UnifyIntersection };
+export { AutocompletableString, BrandedType, LooseAutocomplete, UnifyIntersection };

package/dist/types.mjs

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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "2.1.1",
-  "packageManager": "pnpm@10.11.1",
+  "version": "2.2.0",
+  "packageManager": "pnpm@10.21.0",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
   "license": "MIT",
@@ -78,13 +78,13 @@
     "release": "bumpp"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^4.13.3",
-    "@types/node": "^22.15.29",
-    "bumpp": "^10.1.1",
-    "eslint": "^9.28.0",
-    "tsdown": "^0.12.6",
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.1"
+    "@antfu/eslint-config": "^6.2.0",
+    "@types/node": "^24.10.0",
+    "bumpp": "^10.3.1",
+    "eslint": "^9.39.1",
+    "tsdown": "^0.16.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.8"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/dist/csv.js

@@ -1,98 +0,0 @@
-//#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 = {}) {
-	const { delimiter = ",", addHeader = true, quoteAll = false } = options;
-	const escapeAndQuote = (value) => escapeCSVValue(value, {
-		delimiter,
-		quoteAll
-	});
-	const rows = data.map((obj) => columns.map((key) => escapeAndQuote(obj[key])).join(delimiter));
-	if (addHeader) rows.unshift(columns.map(escapeAndQuote).join(delimiter));
-	return rows.join("\n");
-}
-/**
-* 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"""
-*/
-function escapeCSVValue(value, options = {}) {
-	const { delimiter = ",", quoteAll = false } = options;
-	if (value == null) return "";
-	const stringValue = String(value);
-	const needsQuoting = quoteAll || stringValue.includes(delimiter) || stringValue.includes("\"") || stringValue.includes("\n") || stringValue.includes("\r");
-	if (needsQuoting) return `"${stringValue.replaceAll("\"", "\"\"")}"`;
-	return stringValue;
-}
-/**
-* 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' }]
-*/
-function parseCSV(csv, options = {}) {
-	if (!csv?.trim()) return [];
-	const rows = [];
-	let currentRow = [];
-	let currentField = "";
-	let inQuotes = false;
-	const { delimiter = ",", trimValues = true } = options;
-	for (let i = 0; i < csv.length; i++) {
-		const char = csv[i];
-		const nextChar = i + 1 < csv.length ? csv[i + 1] : "";
-		if (char === "\"") if (inQuotes && nextChar === "\"") {
-			currentField += "\"";
-			i++;
-		} else inQuotes = !inQuotes;
-		else if (char === delimiter && !inQuotes) {
-			currentRow.push(trimValues ? currentField.trim() : currentField);
-			currentField = "";
-		} else if ((char === "\n" || char === "\r" && nextChar === "\n") && !inQuotes) {
-			if (char === "\r") i++;
-			currentRow.push(trimValues ? currentField.trim() : currentField);
-			rows.push(currentRow);
-			currentRow = [];
-			currentField = "";
-		} else currentField += char;
-	}
-	if (currentField || currentRow.length > 0) {
-		currentRow.push(trimValues ? currentField.trim() : currentField);
-		rows.push(currentRow);
-	}
-	if (rows.length <= 1) return [];
-	const headers = rows[0];
-	return rows.slice(1).filter((row) => row.some((field) => field.trim().length > 0)).map((values) => {
-		return Object.fromEntries(headers.map((header, index) => [header, index < values.length ? values[index] : ""]));
-	});
-}
-
-//#endregion
-export { createCSV, escapeCSVValue, parseCSV };

package/dist/index.d.ts

@@ -1,12 +0,0 @@
-import { MaybeArray, toArray } from "./array.js";
-import { CSVRow, createCSV, escapeCSVValue, parseCSV } from "./csv.js";
-import { DefuFn, DefuMerger, createDefu, defu } from "./defu.js";
-import { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter } from "./emitter.js";
-import { cloneJSON, tryParseJSON } from "./json.js";
-import { interopDefault } from "./module.js";
-import { deepApply, memoize, objectEntries, objectKeys } from "./object.js";
-import { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from "./path.js";
-import { Err, ErrData, Ok, OkData, Result, ResultData, err, ok, toResult, tryCatch, unwrapResult } from "./result.js";
-import { generateRandomId, template } from "./string.js";
-import { AutocompletableString, LooseAutocomplete, UnifyIntersection } from "./types.js";
-export { AutocompletableString, 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 };