utilful 1.0.0 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-PRESENT Johann Schopplich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,378 @@
+# utilful
+
+A collection of TypeScript utilities that I use across my projects.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [API](#api)
+  - [Array](#array)
+  - [CSV](#csv)
+  - [Emitter](#emitter)
+  - [JSON](#json)
+  - [Lazy](#lazy)
+  - [Module](#module)
+  - [Object](#object)
+  - [Path](#path)
+  - [String](#string)
+
+## Installation
+
+Run the following command to add `utilful` to your project.
+
+```bash
+# npm
+npm install -D utilful
+
+# pnpm
+pnpm add -D utilful
+
+# yarn
+yarn add -D utilful
+```
+
+## API
+
+### Array
+
+#### `toArray`
+
+Converts `MaybeArray<T>` to `Array<T>`.
+
+```ts
+type MaybeArray<T> = T | T[]
+
+declare function toArray<T>(array?: MaybeArray<T> | null | undefined): T[]
+```
+
+### CSV
+
+#### `createCSV`
+
+Converts an array of objects to a comma-separated values (CSV) string that contains only the `columns` specified.
+
+```ts
+declare function createCSV<T extends Record<string, unknown>>(
+  data: T[],
+  columns: (keyof T)[],
+  options?: {
+    /** @default ',' */
+    delimiter?: string
+    /** @default true */
+    includeHeaders?: boolean
+    /** @default false */
+    quoteAll?: boolean
+  }
+): string
+```
+
+**Example:**
+
+```ts
+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
+```
+
+#### `parseCSV`
+
+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.
+
+```ts
+type CSVRow<T extends string = string> = Record<T, string>
+
+declare function parseCSV<Header extends string>(
+  csv?: string | null | undefined,
+  options?: {
+  /** @default ',' */
+    delimiter?: string
+    /** @default true */
+    trimValues?: boolean
+  }
+): CSVRow<Header>[]
+```
+
+**Example:**
+
+```ts
+const csv = `name,age
+John,30
+Jane,25`
+
+const data = parseCSV<'name' | 'age'>(csv) // [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
+```
+
+### Emitter
+
+Simple and tiny event emitter library for JavaScript.
+
+`createEmitter` accepts interface with event name to listener argument types mapping:
+
+```ts
+import { createEmitter } from 'utilful'
+
+interface Events {
+  set: (name: string, count: number) => void
+  tick: () => void
+}
+
+const emitter = createEmitter<Events>()
+
+// Correct calls:
+emitter.emit('set', 'prop', 1)
+emitter.emit('tick')
+
+// Compilation errors:
+emitter.emit('set', 'prop', '1')
+emitter.emit('tick', 2)
+```
+
+The `on` method returns an `unbind` function. Call it and this listener will be removed from event:
+
+```ts
+const unbind = emitter.on('tick', (number) => {
+  console.log(`on ${number}`)
+})
+
+emitter.emit('tick', 1)
+// Prints "on 1"
+
+unbind()
+emitter.emit('tick', 2)
+// Prints nothing
+```
+
+You can get the used events list by accessing the `events` property:
+
+```ts
+const unbind = emitter.on('tick', () => { })
+emitter.events // => { tick: [ [Function] ] }
+```
+
+### JSON
+
+#### `tryParseJSON`
+
+Type-safe wrapper around `JSON.stringify`.
+
+Falls back to the original value if the JSON serialization 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
+```
+
+### Lazy
+
+A simple general purpose memoizer utility.
+
+- Lazily computes a value when accessed
+- Auto-caches the result by overwriting the getter
+- Typesafe
+
+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.
+
+```ts
+declare function lazy<T>(getter: () => T): { value: T }
+```
+
+**Example:**
+
+```ts
+const myValue = lazy(() => 'Hello, World!')
+console.log(myValue.value) // Computes value, overwrites getter
+console.log(myValue.value) // Returns cached value
+console.log(myValue.value) // Returns cached value
+```
+
+### Module
+
+#### `interopDefault`
+
+Interop helper for default exports.
+
+```ts
+declare function interopDefault<T>(m: T | Promise<T>): Promise<T extends {
+  default: infer U
+} ? U : T>
+```
+
+**Example:**
+
+```ts
+import { interopDefault } from 'utilful'
+
+async function loadModule() {
+  const mod = await interopDefault(import('./module.js'))
+}
+```
+
+### Object
+
+#### `objectKeys`
+
+Strictly typed `Object.keys`.
+
+```ts
+declare function objectKeys<T extends Record<any, any>>(obj: T): Array<`${keyof T & (string | number | boolean | null | undefined)}`>
+```
+
+#### `objectEntries`
+
+Strictly typed `Object.entries`.
+
+```ts
+declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof T, T[keyof T]]>
+```
+
+#### `deepApply`
+
+Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays.
+
+```ts
+declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void
+```
+
+### Path
+
+#### `withoutLeadingSlash`
+
+Removes the leading slash from the given path if it has one.
+
+```ts
+declare function withoutLeadingSlash(path?: string): string
+```
+
+#### `withLeadingSlash`
+
+Adds a leading slash to the given path if it does not already have one.
+
+```ts
+declare function withLeadingSlash(path?: string): string
+```
+
+#### `withoutTrailingSlash`
+
+Removes the trailing slash from the given path if it has one.
+
+```ts
+declare function withoutTrailingSlash(path?: string): string
+```
+
+#### `withTrailingSlash`
+
+Adds a trailing slash to the given path if it does not already have one.
+
+```ts
+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
+```
+
+#### `withBase`
+
+Adds the base path to the input path, if it is not already present.
+
+```ts
+declare function withBase(input?: string, base?: string): string
+```
+
+#### `withoutBase`
+
+Removes the base path from the input path, if it is present.
+
+```ts
+declare function withoutBase(input?: string, base?: string): string
+```
+
+#### `getPathname`
+
+Returns the pathname of the given path, which is the path without the query string.
+
+```ts
+declare function getPathname(path?: string): string
+```
+
+#### `withQuery`
+
+Returns the URL with the given query parameters. If a query parameter is undefined, it is omitted.
+
+```ts
+declare function withQuery(input: string, query?: QueryObject): string
+```
+
+**Example:**
+
+```ts
+import { withQuery } from 'utilful'
+
+const url = withQuery('https://example.com', {
+  foo: 'bar',
+  // This key is omitted
+  baz: undefined,
+  // Object values are stringified
+  baz: { qux: 'quux' }
+})
+```
+
+### String
+
+#### `template`
+
+Simple template engine to replace variables in a string.
+
+```ts
+declare function template(
+  str: string,
+  variables: Record<string | number, any>,
+  fallback?: string | ((key: string) => string)
+): string
+```
+
+**Example:**
+
+```ts
+import { template } from 'utilful'
+
+const str = 'Hello, {name}!'
+const variables = { name: 'world' }
+
+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.
+
+```ts
+declare function generateRandomId(size?: number, dict?: string): string
+```
+
+## License
+
+[MIT](./LICENSE) License © 2024-PRESENT [Johann Schopplich](https://github.com/johannschopplich)

package/dist/array.d.mts

@@ -0,0 +1,10 @@
+/**
+ * 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[];
+
+export { type MaybeArray, toArray };

package/dist/array.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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[];
+
+export { type MaybeArray, toArray };

package/dist/array.mjs

@@ -0,0 +1,6 @@
+function toArray(array) {
+  array ??= [];
+  return Array.isArray(array) ? array : [array];
+}
+
+export { toArray };

package/dist/csv.d.mts

@@ -0,0 +1,67 @@
+/**
+ * Represents a row in a CSV file with column names of type T.
+ */
+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.
+ *
+ * @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
+ */
+declare function createCSV<T extends Record<string, unknown>>(data: T[], columns: (keyof T)[], options?: {
+    /** @default ',' */
+    delimiter?: string;
+    /** @default true */
+    addHeader?: boolean;
+    /** @default false */
+    quoteAll?: boolean;
+}): 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"""
+ */
+declare function escapeCSVValue(value: unknown, options?: {
+    /** @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;
+    /** @default true */
+    trimValues?: boolean;
+}): CSVRow<Header>[];
+
+export { type CSVRow, createCSV, escapeCSVValue, parseCSV };

package/dist/csv.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Represents a row in a CSV file with column names of type T.
+ */
+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.
+ *
+ * @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
+ */
+declare function createCSV<T extends Record<string, unknown>>(data: T[], columns: (keyof T)[], options?: {
+    /** @default ',' */
+    delimiter?: string;
+    /** @default true */
+    addHeader?: boolean;
+    /** @default false */
+    quoteAll?: boolean;
+}): 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"""
+ */
+declare function escapeCSVValue(value: unknown, options?: {
+    /** @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;
+    /** @default true */
+    trimValues?: boolean;
+}): CSVRow<Header>[];
+
+export { type CSVRow, createCSV, escapeCSVValue, parseCSV };

package/dist/csv.mjs

@@ -0,0 +1,77 @@
+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");
+}
+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;
+}
+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] : ""])
+    );
+  });
+}
+
+export { createCSV, escapeCSVValue, parseCSV };

package/dist/emitter.d.mts

@@ -0,0 +1,72 @@
+interface EventsMap {
+    [event: string]: any;
+}
+interface DefaultEvents extends EventsMap {
+    [event: string]: (...args: any) => void;
+}
+interface Unsubscribe {
+    (): void;
+}
+interface Emitter<Events extends EventsMap = DefaultEvents> {
+    /**
+     * Calls each of the listeners registered for a given event.
+     *
+     * @example
+     * emitter.emit('tick', tickType, tickDuration)
+     *
+     * @param event The event name.
+     * @param args The arguments for listeners.
+     */
+    emit: <K extends keyof Events>(this: this, event: K, ...args: Parameters<Events[K]>) => void;
+    /**
+     * Event names in keys and arrays with listeners in values.
+     *
+     * @example
+     * emitter1.events = emitter2.events
+     * emitter2.events = { }
+     */
+    events: Partial<{
+        [E in keyof Events]: Events[E][];
+    }>;
+    /**
+     * Add a listener for a given event.
+     *
+     * @example
+     * const unbind = emitter.on('tick', (tickType, tickDuration) => {
+     *   count += 1
+     * })
+     *
+     * disable () {
+     *   unbind()
+     * }
+     *
+     * @param event The event name.
+     * @param cb The listener function.
+     * @returns Unbind listener from event.
+     */
+    on: <K extends keyof Events>(this: this, event: K, cb: Events[K]) => Unsubscribe;
+}
+/**
+ * Create event emitter.
+ *
+ * @example
+ * import { createEmitter } from 'nanoevents'
+ *
+ * class Ticker {
+ *   constructor() {
+ *     this.emitter = createEmitter()
+ *   }
+ *   on(...args) {
+ *     return this.emitter.on(...args)
+ *   }
+ *   tick() {
+ *     this.emitter.emit('tick')
+ *   }
+ * }
+ *
+ * @remarks Ported from `nanoevents`.
+ * @see https://github.com/ai/nanoevents
+ */
+declare function createEmitter<Events extends EventsMap = DefaultEvents>(): Emitter<Events>;
+
+export { type Emitter, createEmitter };