@germondai/ts-utils 0.0.5 → 0.1.0

package/dist/runtime/array.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Determines whether an array contains duplicate values.
+ *
+ * @param array - The array to check for duplicates.
+ * @param keyExtractor - Optional function to extract a key for comparison. If provided, duplicates are determined based on the extracted key.
+ * @returns True if the array contains duplicates, false otherwise.
+ *
+ * @example
+ * // Basic usage with primitive values
+ * hasDuplicates([1, 2, 3, 4, 1]); // true
+ * hasDuplicates(['a', 'b', 'c']); // false
+ *
+ * // Usage with objects and a key extractor
+ * hasDuplicates([{ id: 1 }, { id: 2 }, { id: 1 }], (item) => item.id); // true
+ */
+export declare const hasDuplicates: <T>(array: T[], keyExtractor?: (value: T, index: number, array: T[]) => string | number) => boolean;
+/**
+ * Removes duplicates from an array based on a key function.
+ *
+ * @param array - The array to process.
+ * @param keyExtractor - Function to generate a unique key for each item.
+ * @returns A new array without duplicates.
+ */
+/**
+ * Returns a new array containing only unique elements from the input array.
+ * Uniqueness is determined based on the values returned by the `keyExtractor` function,
+ * or by the elements themselves if no `keyExtractor` is provided.
+ *
+ * @typeParam T - The type of elements in the input array.
+ * @param array - The input array from which to extract unique elements.
+ * @param keyExtractor - An optional function that extracts a key from each element
+ * to determine uniqueness. If not provided, the elements themselves are used.
+ * The function receives the current element, its index, and the entire array as arguments.
+ * @returns A new array containing only unique elements from the input array.
+ *
+ * @example
+ * // Using default behavior (elements themselves determine uniqueness)
+ * const numbers = [1, 2, 2, 3, 4, 4];
+ * const uniqueNumbers = uniqueArray(numbers);
+ * console.log(uniqueNumbers); // Output: [1, 2, 3, 4]
+ *
+ * @example
+ * // Using a keyExtractor to determine uniqueness
+ * const users = [
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ *   { id: 1, name: 'Alice' },
+ * ];
+ * const uniqueUsers = uniqueArray(users, user => user.id);
+ * console.log(uniqueUsers);
+ * // Output: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ */
+export declare const uniqueArray: <T>(array: T[], keyExtractor?: (value: T, index: number, array: T[]) => string | number) => T[];
+/**
+ * Splits an array into chunks of the specified size.
+ *
+ * @param array - The array to split.
+ * @param size - The size of each chunk.
+ * @returns An array of chunks.
+ *
+ * @example
+ * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
+ */
+export declare const chunk: <T>(array: T[], size: number) => T[][];
+/**
+ * Returns a new array with elements shuffled using the Fisher-Yates algorithm.
+ *
+ * @param array - The array to shuffle.
+ * @returns A new shuffled array.
+ *
+ * @example
+ * shuffle([1, 2, 3, 4, 5]) // [3, 1, 5, 2, 4] (random order)
+ */
+export declare const shuffle: <T>(array: T[]) => T[];
+/**
+ * Groups array elements by a key or function.
+ *
+ * @param array - The array to group.
+ * @param key - A property key or function to determine the group.
+ * @returns An object with groups as keys and arrays of items as values.
+ *
+ * @example
+ * groupBy([{ type: 'a', v: 1 }, { type: 'b', v: 2 }, { type: 'a', v: 3 }], 'type')
+ * // { a: [{ type: 'a', v: 1 }, { type: 'a', v: 3 }], b: [{ type: 'b', v: 2 }] }
+ */
+export declare const groupBy: <T>(array: T[], key: keyof T | ((item: T) => string)) => Record<string, T[]>;
+/**
+ * Returns elements common to all provided arrays.
+ *
+ * @param arrays - The arrays to intersect.
+ * @returns An array of common elements.
+ *
+ * @example
+ * intersection([1, 2, 3], [2, 3, 4], [3, 4, 5]) // [3]
+ */
+export declare const intersection: <T>(...arrays: T[][]) => T[];
+/**
+ * Returns elements that are in the first array but not in the second.
+ *
+ * @param a - The source array.
+ * @param b - The array of elements to exclude.
+ * @returns A new array with elements from `a` not found in `b`.
+ *
+ * @example
+ * difference([1, 2, 3, 4], [2, 4]) // [1, 3]
+ */
+export declare const difference: <T>(a: T[], b: T[]) => T[];
+/**
+ * Generates an array of numbers in a given range.
+ *
+ * @param start - The start of the range.
+ * @param end - The end of the range (exclusive).
+ * @param step - The step between numbers (default: 1).
+ * @returns An array of numbers.
+ *
+ * @example
+ * range(0, 5) // [0, 1, 2, 3, 4]
+ * range(0, 10, 3) // [0, 3, 6, 9]
+ */
+export declare const range: (start: number, end: number, step?: number) => number[];
+/**
+ * Returns a new sorted array by a key or comparator function.
+ *
+ * @param array - The array to sort.
+ * @param key - A property key or function returning a comparable value.
+ * @param order - Sort order: 'asc' (default) or 'desc'.
+ * @returns A new sorted array.
+ *
+ * @example
+ * sortBy([{ age: 30 }, { age: 20 }], 'age') // [{ age: 20 }, { age: 30 }]
+ */
+export declare const sortBy: <T>(array: T[], key: keyof T | ((item: T) => number | string), order?: "asc" | "desc") => T[];
+/**
+ * Removes all falsy values from an array.
+ *
+ * @param array - The array to compact.
+ * @returns A new array with falsy values removed.
+ *
+ * @example
+ * compact([0, 1, false, 2, '', 3, null, undefined]) // [1, 2, 3]
+ */
+export declare const compact: <T>(array: (T | null | undefined | false | 0 | "")[]) => T[];
+/**
+ * Returns the last element of an array.
+ *
+ * @param array - The array.
+ * @returns The last element, or undefined if empty.
+ *
+ * @example
+ * last([1, 2, 3]) // 3
+ * last([]) // undefined
+ */
+export declare const last: <T>(array: T[]) => T | undefined;
+/**
+ * Returns a random element from an array.
+ *
+ * @param array - The array.
+ * @returns A random element, or undefined if empty.
+ *
+ * @example
+ * sample([1, 2, 3]) // 2 (random)
+ */
+export declare const sample: <T>(array: T[]) => T | undefined;

package/dist/runtime/collection.d.ts

@@ -1,53 +1 @@
-/**
- * Determines whether an array contains duplicate values.
- *
- * @param array - The array to check for duplicates.
- * @param keyExtractor - Optional function to extract a key for comparison. If provided, duplicates are determined based on the extracted key.
- * @returns True if the array contains duplicates, false otherwise.
- *
- * @example
- * // Basic usage with primitive values
- * hasDuplicates([1, 2, 3, 4, 1]); // true
- * hasDuplicates(['a', 'b', 'c']); // false
- *
- * // Usage with objects and a key extractor
- * hasDuplicates([{ id: 1 }, { id: 2 }, { id: 1 }], (item) => item.id); // true
- */
-export declare const hasDuplicates: <T>(array: T[], keyExtractor?: (value: T, index: number, array: T[]) => string | number) => boolean;
-/**
- * Removes duplicates from an array based on a key function.
- *
- * @param array - The array to process.
- * @param keyExtractor - Function to generate a unique key for each item.
- * @returns A new array without duplicates.
- */
-/**
- * Returns a new array containing only unique elements from the input array.
- * Uniqueness is determined based on the values returned by the `keyExtractor` function,
- * or by the elements themselves if no `keyExtractor` is provided.
- *
- * @typeParam T - The type of elements in the input array.
- * @param array - The input array from which to extract unique elements.
- * @param keyExtractor - An optional function that extracts a key from each element
- * to determine uniqueness. If not provided, the elements themselves are used.
- * The function receives the current element, its index, and the entire array as arguments.
- * @returns A new array containing only unique elements from the input array.
- *
- * @example
- * // Using default behavior (elements themselves determine uniqueness)
- * const numbers = [1, 2, 2, 3, 4, 4];
- * const uniqueNumbers = uniqueArray(numbers);
- * console.log(uniqueNumbers); // Output: [1, 2, 3, 4]
- *
- * @example
- * // Using a keyExtractor to determine uniqueness
- * const users = [
- *   { id: 1, name: 'Alice' },
- *   { id: 2, name: 'Bob' },
- *   { id: 1, name: 'Alice' },
- * ];
- * const uniqueUsers = uniqueArray(users, user => user.id);
- * console.log(uniqueUsers);
- * // Output: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
- */
-export declare const uniqueArray: <T>(array: T[], keyExtractor?: (value: T, index: number, array: T[]) => string | number) => T[];
+export { hasDuplicates, uniqueArray } from './array';

package/dist/runtime/color.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a hex color string to an RGB object.
+ *
+ * @param hex - The hex color string (e.g., "#ff5733" or "#f53").
+ * @returns An RGB object, or null if the hex string is invalid.
+ *
+ * @example
+ * hexToRgb("#ff5733") // { r: 255, g: 87, b: 51 }
+ * hexToRgb("#f53") // { r: 255, g: 85, b: 51 }
+ */
+export declare const hexToRgb: (hex: string) => {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * Converts RGB values to a hex color string.
+ *
+ * @param r - The red value (0-255).
+ * @param g - The green value (0-255).
+ * @param b - The blue value (0-255).
+ * @returns The hex color string.
+ *
+ * @example
+ * rgbToHex(255, 87, 51) // "#ff5733"
+ */
+export declare const rgbToHex: (r: number, g: number, b: number) => string;
+/**
+ * Lightens a hex color by a given percentage.
+ *
+ * @param hex - The hex color string.
+ * @param amount - The amount to lighten (0-1, where 1 is white).
+ * @returns The lightened hex color string.
+ *
+ * @example
+ * lighten("#000000", 0.5) // "#808080"
+ */
+export declare const lighten: (hex: string, amount: number) => string;
+/**
+ * Darkens a hex color by a given percentage.
+ *
+ * @param hex - The hex color string.
+ * @param amount - The amount to darken (0-1, where 1 is black).
+ * @returns The darkened hex color string.
+ *
+ * @example
+ * darken("#ffffff", 0.5) // "#808080"
+ */
+export declare const darken: (hex: string, amount: number) => string;

package/dist/runtime/convertor.d.ts

@@ -1,6 +1,11 @@
+/**
+ * Splits an input string into words, handling camelCase, PascalCase,
+ * snake_case, kebab-case, spaces, and mixed formats.
+ */
+export declare const splitWords: (input: string) => string[];
 /**
  * Converts a string to camelCase.
- * Example: "hello world" → "helloWorld"
+ * Example: "hello world" → "helloWorld", "myVariableName" → "myVariableName"
  * @param input The input string.
  * @returns The camelCase version of the input.
  */
@@ -14,14 +19,14 @@ export declare const toCamelCase: (input: string) => string;
 export declare const toPascalCase: (input: string) => string;
 /**
  * Converts a string to snake_case.
- * Example: "hello world" → "hello_world"
+ * Example: "hello world" → "hello_world", "myVariableName" → "my_variable_name"
  * @param input The input string.
  * @returns The snake_case version of the input.
  */
 export declare const toSnakeCase: (input: string) => string;
 /**
  * Converts a string to kebab-case.
- * Example: "hello world" → "hello-world"
+ * Example: "hello world" → "hello-world", "myVariableName" → "my-variable-name"
  * @param input The input string.
  * @returns The kebab-case version of the input.
  */

package/dist/runtime/crypto.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generates a random alphanumeric ID.
+ *
+ * @param length - The length of the ID (default: 16).
+ * @returns A random alphanumeric string.
+ *
+ * @example
+ * generateId() // "a3bF9kL2mN7xP1qR"
+ * generateId(8) // "x4Hy9zKm"
+ */
+export declare const generateId: (length?: number) => string;
+/**
+ * Generates a simple non-cryptographic hash of a string (djb2 algorithm).
+ *
+ * @param str - The string to hash.
+ * @returns A numeric hash value.
+ *
+ * @example
+ * hash("hello") // 261238937
+ */
+export declare const hash: (str: string) => number;

package/dist/runtime/data.d.ts

@@ -22,4 +22,4 @@ export declare const clone: <T>(data: T) => T;
  * - For objects, the function checks if they have the same keys and recursively compares their corresponding values.
  * - The function does not handle circular references and may result in a stack overflow for deeply nested structures.
  */
-export declare const isEqual: <T>(a: T, b: T) => boolean;
+export declare const isEqual: <T>(a: T, b: T, seen?: WeakSet<object>) => boolean;

package/dist/runtime/function.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Creates a debounced version of a function that delays invoking the function
+ * until after `ms` milliseconds have elapsed since the last time it was called.
+ *
+ * @param fn - The function to debounce.
+ * @param ms - The debounce delay in milliseconds.
+ * @returns The debounced function with a `cancel` method.
+ *
+ * @example
+ * const debouncedSave = debounce(save, 300)
+ * debouncedSave() // Only executes after 300ms of inactivity
+ * debouncedSave.cancel() // Cancel pending execution
+ */
+export declare const debounce: <T extends (...args: any[]) => any>(fn: T, ms: number) => T & {
+    cancel(): void;
+};
+/**
+ * Creates a throttled version of a function that only invokes the function
+ * at most once per `ms` milliseconds.
+ *
+ * @param fn - The function to throttle.
+ * @param ms - The throttle interval in milliseconds.
+ * @returns The throttled function with a `cancel` method.
+ *
+ * @example
+ * const throttledScroll = throttle(onScroll, 100)
+ * window.addEventListener('scroll', throttledScroll)
+ * throttledScroll.cancel() // Cancel pending execution
+ */
+export declare const throttle: <T extends (...args: any[]) => any>(fn: T, ms: number) => T & {
+    cancel(): void;
+};
+/**
+ * Creates a function that can only be called once. Subsequent calls return
+ * the result of the first invocation.
+ *
+ * @param fn - The function to restrict.
+ * @returns A function that only executes once.
+ *
+ * @example
+ * const initialize = once(() => console.log("init"))
+ * initialize() // logs "init"
+ * initialize() // does nothing
+ */
+export declare const once: <T extends (...args: any[]) => any>(fn: T) => T;
+/**
+ * A no-operation function that does nothing.
+ *
+ * @example
+ * const callback = options.onComplete || noop
+ */
+export declare const noop: () => void;

package/dist/runtime/index.d.ts

@@ -1,13 +1,19 @@
-export * from './collection';
+export * from './array';
+export * from './color';
 export * from './constants';
 export * from './convertor';
+export * from './crypto';
 export * from './data';
 export * from './errors';
+export * from './function';
 export * from './math';
 export * from './media';
+export * from './normalize';
+export * from './object';
 export * from './promise';
 export * from './regex';
 export * from './size';
+export * from './string';
 export * from './time';
 export * from './type';
 export * from './url';

package/dist/runtime/math.d.ts

@@ -33,3 +33,66 @@ export declare const clamp: (num: number, min: number, max: number) => number;
  * @returns A string with formatted number (e.g., "1,234,567").
  */
 export declare const formatNumber: (num: number) => string;
+/**
+ * Sums an array of numbers.
+ *
+ * @param numbers - The numbers to sum.
+ * @returns The sum, or 0 for an empty array.
+ *
+ * @example
+ * sum([1, 2, 3]) // 6
+ */
+export declare const sum: (numbers: number[]) => number;
+/**
+ * Calculates the average of an array of numbers.
+ *
+ * @param numbers - The numbers to average.
+ * @returns The average, or 0 for an empty array.
+ *
+ * @example
+ * average([1, 2, 3, 4]) // 2.5
+ */
+export declare const average: (numbers: number[]) => number;
+/**
+ * Calculates the median of an array of numbers.
+ *
+ * @param numbers - The numbers to find the median of.
+ * @returns The median, or 0 for an empty array.
+ *
+ * @example
+ * median([1, 2, 3]) // 2
+ * median([1, 2, 3, 4]) // 2.5
+ */
+export declare const median: (numbers: number[]) => number;
+/**
+ * Returns the minimum value in an array of numbers.
+ *
+ * @param numbers - The numbers.
+ * @returns The minimum value, or Infinity for an empty array.
+ *
+ * @example
+ * min([3, 1, 4, 1, 5]) // 1
+ */
+export declare const min: (numbers: number[]) => number;
+/**
+ * Returns the maximum value in an array of numbers.
+ *
+ * @param numbers - The numbers.
+ * @returns The maximum value, or -Infinity for an empty array.
+ *
+ * @example
+ * max([3, 1, 4, 1, 5]) // 5
+ */
+export declare const max: (numbers: number[]) => number;
+/**
+ * Rounds a number to the specified number of decimal places.
+ *
+ * @param value - The number to round.
+ * @param decimals - The number of decimal places (default: 0).
+ * @returns The rounded number.
+ *
+ * @example
+ * round(1.2345, 2) // 1.23
+ * round(1.5) // 2
+ */
+export declare const round: (value: number, decimals?: number) => number;

package/dist/runtime/normalize.d.ts

@@ -0,0 +1 @@
+export declare const normalize: <T>(value: T | null | undefined) => T | null;

package/dist/runtime/object.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Creates a new object with only the specified keys.
+ *
+ * @param obj - The source object.
+ * @param keys - The keys to pick.
+ * @returns A new object with only the specified keys.
+ *
+ * @example
+ * pick({ a: 1, b: 2, c: 3 }, ['a', 'c']) // { a: 1, c: 3 }
+ */
+export declare const pick: <T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
+/**
+ * Creates a new object without the specified keys.
+ *
+ * @param obj - The source object.
+ * @param keys - The keys to omit.
+ * @returns A new object without the specified keys.
+ *
+ * @example
+ * omit({ a: 1, b: 2, c: 3 }, ['b']) // { a: 1, c: 3 }
+ */
+export declare const omit: <T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+/**
+ * Deep merges multiple objects together. Later values override earlier ones.
+ *
+ * @param objects - The objects to merge.
+ * @returns The merged object.
+ *
+ * @example
+ * merge({ a: 1, b: { c: 2 } }, { b: { d: 3 } }) // { a: 1, b: { c: 2, d: 3 } }
+ */
+export declare const merge: <T extends Record<string, any>>(...objects: Partial<T>[]) => T;
+/**
+ * Flattens a nested object into a single-level object with dot-separated keys.
+ *
+ * @param obj - The object to flatten.
+ * @param prefix - The prefix for keys (used internally for recursion).
+ * @returns A flat object.
+ *
+ * @example
+ * flattenObject({ a: { b: 1, c: { d: 2 } } }) // { 'a.b': 1, 'a.c.d': 2 }
+ */
+export declare const flattenObject: (obj: Record<string, any>, prefix?: string) => Record<string, any>;
+/**
+ * Unflattens a dot-separated flat object into a nested object.
+ *
+ * @param obj - The flat object to unflatten.
+ * @returns A nested object.
+ *
+ * @example
+ * unflattenObject({ 'a.b': 1, 'a.c.d': 2 }) // { a: { b: 1, c: { d: 2 } } }
+ */
+export declare const unflattenObject: (obj: Record<string, any>) => Record<string, any>;
+/**
+ * Gets the deep differences between two objects.
+ * Recursively compares nested objects and returns only the differing branches.
+ * For arrays, if they differ the entire new array is returned.
+ *
+ * @param a - The first object.
+ * @param b - The second object.
+ * @returns An object with the differing values from `b`.
+ *
+ * @example
+ * diff({ a: 1, b: { c: 2, d: 3 } }, { a: 1, b: { c: 5, d: 3 } })
+ * // { b: { c: 5 } }
+ *
+ * diff({ tags: [1, 2] }, { tags: [1, 3] })
+ * // { tags: [1, 3] }
+ */
+export declare const diff: <T extends Record<string, any>>(a: T, b: T) => Partial<T>;

package/dist/runtime/promise.d.ts

@@ -5,3 +5,33 @@
  * @returns A promise that resolves after the delay.
  */
 export declare const sleep: (ms: number) => Promise<void>;
+/**
+ * Retries a function up to a specified number of times with optional exponential backoff.
+ *
+ * @param fn - The async function to retry.
+ * @param options - Retry options.
+ * @param options.retries - The maximum number of retries (default: 3).
+ * @param options.delay - The delay in milliseconds between retries (default: 1000).
+ * @param options.backoff - Whether to use exponential backoff (default: false).
+ * @returns The result of the function.
+ *
+ * @example
+ * const data = await retry(() => fetch('/api/data'), { retries: 3, delay: 1000, backoff: true })
+ */
+export declare const retry: <T>(fn: () => Promise<T>, options?: {
+    retries?: number;
+    delay?: number;
+    backoff?: boolean;
+}) => Promise<T>;
+/**
+ * Wraps a promise with a timeout. Rejects if the promise doesn't resolve within the specified time.
+ *
+ * @param promise - The promise to wrap.
+ * @param ms - The timeout in milliseconds.
+ * @param message - Optional custom error message.
+ * @returns The result of the promise.
+ *
+ * @example
+ * const data = await timeout(fetch('/api/data'), 5000, 'Request timed out')
+ */
+export declare const timeout: <T>(promise: Promise<T>, ms: number, message?: string) => Promise<T>;