@vielzeug/toolkit 1.0.12 → 1.0.14

package/dist/index.d.ts

@@ -1,3 +1,40 @@
+/**
+ * Returns the absolute value of a number.
+ * Supports both regular numbers and bigint.
+ *
+ * @example
+ * ```ts
+ * abs(-5); // 5
+ * abs(3); // 3
+ * abs(-100n); // 100n
+ * ```
+ *
+ * @param value - The number or bigint to get absolute value of
+ * @returns Absolute value
+ */
+export declare function abs(value: number): number;
+
+export declare function abs(value: bigint): bigint;
+
+/**
+ * Adds two numbers with precision handling for financial calculations.
+ * Supports both regular numbers and bigint for exact precision.
+ *
+ * @example
+ * ```ts
+ * add(10, 20); // 30
+ * add(0.1, 0.2); // 0.3 (precision-safe)
+ * add(100n, 200n); // 300n
+ * ```
+ *
+ * @param a - First number or bigint
+ * @param b - Second number or bigint
+ * @returns Sum of a and b
+ */
+export declare function add(a: number, b: number): number;
+
+export declare function add(a: bigint, b: bigint): bigint;
+
 /**
  * Aggregates an array of objects into an object based on a key generated by a selector function.
  *
@@ -20,6 +57,31 @@ export declare namespace aggregate {
     var fp: boolean;
 }
 
+/**
+ * Distributes an amount proportionally according to given ratios.
+ * Handles rounding to ensure the sum equals the original amount exactly.
+ * Critical for financial operations like splitting payments to avoid rounding errors.
+ *
+ * @example
+ * ```ts
+ * // Split $100 in ratio 1:2:3
+ * allocate(100, [1, 2, 3]);
+ * // [17, 33, 50] - sum is exactly 100
+ *
+ * // Split with bigint (e.g., cents)
+ * allocate(10000n, [1, 1, 1]);
+ * // [3334n, 3333n, 3333n] - sum is exactly 10000n
+ * ```
+ *
+ * @param amount - Total amount to allocate
+ * @param ratios - Array of ratios for distribution
+ * @returns Array of allocated amounts (sum equals original amount)
+ * @throws {Error} If ratios array is empty or contains negative values
+ */
+export declare function allocate(amount: number, ratios: number[]): number[];
+
+export declare function allocate(amount: bigint, ratios: number[]): bigint[];
+
 /**
  * Either adds or removes an item from an array, based on whether it already exists in the array.
  *
@@ -54,6 +116,27 @@ export declare namespace alternate {
 
 export declare type ArgType = 'array' | 'boolean' | 'date' | 'error' | 'function' | 'map' | 'nan' | 'null' | 'number' | 'object' | 'promise' | 'regexp' | 'set' | 'string' | 'symbol' | 'weakmap' | 'weakset' | 'undefined';
 
+/**
+ * Arranges (sorts) an array of objects based on multiple selectors.
+ *
+ * @example
+ * ```ts
+ * const data = [
+ *   { name: 'Alice', age: 30 },
+ *   { name: 'Bob', age: 25 },
+ *   { name: 'Charlie', age: 35 },
+ *   { name: 'Alice', age: 25 },
+ *   { name: 'Bob', age: 30 },
+ *   { name: 'Charlie', age: 30 },
+ * ].arrange(data, { name: 'asc', age: 'desc' }); // [ { name: 'Alice', age: 30 }, { name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }, { name: 'Bob', age: 25 }, { name: 'Charlie', age: 35 }, { name: 'Charlie', age: 30 } ]
+ * ```
+ *
+ * @param array - The array to sort.
+ * @param selectors - An object where keys are the properties to sort by and values are 'asc' or 'desc'.
+ * @returns A new sorted array.
+ */
+export declare const arrange: <T>(array: T[], selectors: Partial<Record<keyof T, "asc" | "desc">>) => T[];
+
 /**
  * Asserts that the condition is true. If the condition is false, it throws an error
  * with the provided message or logs a warning in soft mode.
@@ -264,6 +347,8 @@ export declare function clamp(n: number, min: number, max: number): number;
  * @param item - The data to clone.
  *
  * @returns A deep copy of the provided data.
+ *
+ * @throws {Error} If the item cannot be cloned.
  */
 export declare function clone<T>(item: T): T;
 
@@ -359,12 +444,6 @@ export declare function compose<T extends FnDynamic[]>(...fns: T): ComposeReturn
 
 declare type ComposeReturn<T extends FnDynamic[]> = (...args: LastParameters<T>) => FirstReturnType<T> extends Promise<any> ? Promise<Awaited<FirstReturnType<T>>> : FirstReturnType<T>;
 
-declare type Config<T> = {
-    filterFn?: Predicate<T>;
-    limit?: number;
-    sortFn?: (a: T, b: T) => number;
-};
-
 /**
  * Checks if a value is present in an array.
  *
@@ -388,42 +467,53 @@ export declare namespace contains {
     var fp: boolean;
 }
 
-declare type CurriedFunction<Params extends any[], R> = Params extends [infer A, ...infer Rest] ? (arg: A) => CurriedFunction<Rest, R> : R;
-
 /**
- * Curries a function, allowing it to be called with partial arguments.
+ * Formats a monetary amount as a currency string with proper locale and symbol.
+ * Handles decimal places automatically based on currency.
  *
  * @example
  * ```ts
- * const add = (a: number, b: number) => a + b;
- * const curriedAdd = curry(add);
- * curriedAdd(1)(2) // 3;
- * ```
+ * const money = { amount: 123456n, currency: 'USD' };
  *
- * @param fn - The function to curry.
+ * currency(money); // '$1,234.56' (default en-US)
+ * currency(money, { locale: 'de-DE' }); // '1.234,56 $'
+ * currency(money, { style: 'code' }); // 'USD 1,234.56'
+ * currency(money, { style: 'name' }); // '1,234.56 US dollars'
+ * ```
  *
- * @returns A curried version of the function.
+ * @param money - Money object to format
+ * @param options - Formatting options
+ * @returns Formatted currency string
  */
-export declare const curry: <T extends (...args: any[]) => any>(fn: T) => T extends (...args: infer P) => infer R ? CurriedFunction<P, R> : never;
+export declare function currency(money: Money, options?: CurrencyFormatOptions): string;
 
 /**
- * Creates a debounced function that delays invoking the provided function until after
- * a specified wait time has elapsed since the last invocation.
- *
- * @example
- * ```ts
- * const debouncedLog = debounce(console.log, 1000);
- *
- * debouncedLog('Hello'); // Will log after 1 second if not called again
- * debouncedLog('World'); // Resets the timer, will log 'World' after 1 second
- * ```
- *
- * @param fn - The function to debounce.
- * @param [delay=300] - - The number of milliseconds to delay invoking the function.
- *
- * @returns - A debounced function
+ * Options for currency formatting.
  */
-export declare function debounce<T extends Fn>(fn: T, delay?: number): (...args: Parameters<T>) => void;
+export declare type CurrencyFormatOptions = {
+    locale?: string;
+    style?: 'symbol' | 'code' | 'name';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+};
+
+export declare type Curried<P extends readonly unknown[], R> = P extends readonly [] ? () => R : <A extends readonly [unknown, ...(readonly unknown[])]>(...args: A) => P extends readonly [...A, ...infer Rest] ? (Rest extends readonly [] ? R : Curried<Rest, R>) : never;
+
+export declare function curry<T extends (...args: any[]) => any>(fn: T): Curried<Parameters<T>, ReturnType<T>>;
+
+export declare function curry<T extends (...args: any[]) => any, N extends number>(fn: T, arity: N): Curried<Take<N, Parameters<T>>, ReturnType<T>>;
+
+/**
+ * Debounce a function (trailing). Use `flush` to invoke immediately,
+ * `cancel` to clear, and `pending` to check if an invocation is scheduled.
+ */
+export declare function debounce<T extends Fn>(fn: T, delay?: number): Debounced<T>;
+
+export declare type Debounced<T extends Fn> = ((this: ThisParameterType<T>, ...args: Parameters<T>) => void) & {
+    cancel(): void;
+    flush(): ReturnType<T> | undefined;
+    pending(): boolean;
+};
 
 declare type DeepMerge<T, U> = T extends Obj ? U extends Obj ? {
     [K in keyof T | keyof U]: K extends keyof T ? K extends keyof U ? DeepMerge<T[K], U[K]> : T[K] : K extends keyof U ? U[K] : never;
@@ -464,6 +554,51 @@ export declare function delay<T extends Fn>(fn: T, delay?: number): Promise<any>
  */
 export declare function diff<T extends Obj>(curr?: T, prev?: T, compareFn?: (a: unknown, b: unknown) => boolean): Partial<T>;
 
+/**
+ * Distributes an amount evenly among N parties.
+ * Handles rounding to ensure the sum equals the original amount exactly.
+ * Useful for splitting bills, costs, or payments equally.
+ *
+ * @example
+ * ```ts
+ * // Split $100 among 3 people
+ * distribute(100, 3);
+ * // [34, 33, 33] - sum is exactly 100
+ *
+ * // Split with bigint (e.g., cents)
+ * distribute(10000n, 3);
+ * // [3334n, 3333n, 3333n] - sum is exactly 10000n
+ * ```
+ *
+ * @param amount - Total amount to distribute
+ * @param parts - Number of parts to divide into
+ * @returns Array of distributed amounts (a sum equals original amount)
+ * @throws {Error} If parts are less than 1
+ */
+export declare function distribute(amount: number, parts: number): number[];
+
+export declare function distribute(amount: bigint, parts: number): bigint[];
+
+/**
+ * Divides a number by a divisor with precision handling for financial calculations.
+ * Supports both regular numbers and bigint for exact precision.
+ *
+ * @example
+ * ```ts
+ * divide(20, 5); // 4
+ * divide(0.6, 3); // 0.2 (precision-safe)
+ * divide(500n, 5n); // 100n
+ * ```
+ *
+ * @param a - Number to divide (dividend)
+ * @param b - Divisor
+ * @returns Quotient of a divided by b
+ * @throws {Error} If divisor is zero
+ */
+export declare function divide(a: number, b: number): number;
+
+export declare function divide(a: bigint, b: bigint): bigint;
+
 /**
  * “Draw” a random item from an array.
  *
@@ -522,6 +657,35 @@ export declare namespace every {
     var fp: boolean;
 }
 
+/**
+ * Converts money from one currency to another using the provided exchange rate.
+ * Maintains precision by using bigint arithmetic.
+ *
+ * @example
+ * ```ts
+ * const usd = { amount: 100000n, currency: 'USD' }; // $1,000.00
+ * const rate = { from: 'USD', to: 'EUR', rate: 0.85 };
+ *
+ * exchange(usd, rate);
+ * // { amount: 85000n, currency: 'EUR' } // €850.00
+ * ```
+ *
+ * @param money - Money to convert
+ * @param rate - Exchange rate information
+ * @returns Converted money in target currency
+ * @throws {Error} If source currency doesn't match rate.from
+ */
+export declare function exchange(money: Money, rate: ExchangeRate): Money;
+
+/**
+ * Exchange rate for currency conversion.
+ */
+export declare type ExchangeRate = {
+    from: string;
+    to: string;
+    rate: number;
+};
+
 export declare type Expires = 'EXPIRED' | 'SOON' | 'LATER' | 'NEVER' | 'UNKNOWN';
 
 /**
@@ -718,7 +882,7 @@ export declare function ge(a: unknown, b: unknown): boolean;
  *
  * @throws {TypeError} If the provided array is not an array.
  */
-export declare function group<T, K extends keyof T, R extends T[K] extends string ? T[K] : never>(array: T[], selector: Selector<T>): Record<R, T[]>;
+export declare function group<T, _K extends keyof T, R extends string | number | symbol>(array: T[], selector: Selector<T>): Record<R, T[]>;
 
 export declare namespace group {
     var fp: boolean;
@@ -1314,32 +1478,42 @@ declare type LastReturnType<T> = T extends [...any, infer Last extends FnDynamic
  */
 export declare function le(a: unknown, b: unknown): boolean;
 
-export declare function list<T>(initialData: T[], config?: Config<T>): {
-    readonly current: T[];
-    data: T[];
-    filter(predicate: (item: T) => boolean): T[];
-    limit: number;
-    readonly meta: {
-        end: number;
-        isEmpty: boolean;
-        isFirst: boolean;
-        isLast: boolean;
-        limit: number;
-        page: number;
-        pages: number;
-        start: number;
-        total: number;
-    };
+export declare type List<T, F, S> = {
+    readonly current: readonly T[];
+    readonly meta: Meta;
+    subscribe(listener: () => void): () => void;
+    goTo(page: number): void;
     next(): void;
-    page: number;
-    readonly pages: T[][];
     prev(): void;
-    reset(): T[];
-    search: (str: string) => void;
-    sort(fn?: (a: T, b: T) => number): T[];
-    [Symbol.iterator](): Generator<T[], void, unknown>;
+    reset(): void;
+    search(query: string, opts?: {
+        immediate?: boolean;
+    }): void;
+    setData?(data: readonly T[]): void;
+    setFilter(filter: F): void;
+    setLimit(n: number): void;
+    setSort(sort?: S): void;
+    batch(mutator: (ctx: {
+        setLimit(n: number): void;
+        setFilter(f: F): void;
+        setSort(s?: S): void;
+        setQuery(q: string): void;
+        setData?(d: readonly T[]): void;
+        goTo(p: number): void;
+    }) => void): void;
 };
 
+export declare function list<T>(initialData: readonly T[], cfg?: LocalConfig<T>): List<T, Predicate<T>, Sorter<T>>;
+
+declare type LocalConfig<T> = Readonly<{
+    debounceMs?: number;
+    filterFn?: Predicate<T>;
+    limit?: number;
+    searchFn?: (items: readonly T[], query: string, tone: number) => readonly T[];
+    searchTone?: number;
+    sortFn?: Sorter<T>;
+}>;
+
 /**
  * Checks if the first argument is less than the second argument.
  *
@@ -1438,14 +1612,16 @@ export declare function median<T>(arr: T[], callback?: (item: T) => number | Dat
  * @param options - Memoization options.
  * @param [options.ttl] - (optional) time-to-live (TTL) for cache expiration (in milliseconds).
  * @param [options.maxSize] - (optional) maximum cache size (LRU eviction).
+ * @param [options.resolver] - (optional) custom function to resolve the cache key.
  *
  * @returns A new function that memorizes the input function.
  */
-export declare function memo<T extends Fn>(fn: T, { ttl, maxSize }?: MemoizeOptions): (...args: Parameters<T>) => ReturnType<T>;
+export declare function memo<T extends Fn>(fn: T, { ttl, maxSize, resolver }?: MemoizeOptions<T>): (...args: Parameters<T>) => ReturnType<T>;
 
-declare type MemoizeOptions = {
+declare type MemoizeOptions<T extends Fn> = {
     ttl?: number;
     maxSize?: number;
+    resolver?: (...args: Parameters<T>) => string;
 };
 
 declare type Merge<T extends Obj[]> = T extends [infer First, ...infer Rest] ? First extends Obj ? Rest extends Obj[] ? DeepMerge<First, Merge<Rest>> : First : Obj : Obj;
@@ -1471,6 +1647,18 @@ export declare function merge<T extends Obj[]>(strategy?: MergeStrategy, ...item
 
 declare type MergeStrategy = 'deep' | 'shallow' | 'lastWins' | 'arrayConcat' | 'arrayReplace' | ((target: any, source: any) => any);
 
+export declare type Meta = Readonly<{
+    end: number;
+    isEmpty: boolean;
+    isFirst: boolean;
+    isLast: boolean;
+    limit: number;
+    page: number;
+    pages: number;
+    start: number;
+    total: number;
+}>;
+
 /**
  * Finds the minimum item in an array.
  *
@@ -1494,6 +1682,34 @@ declare type MergeStrategy = 'deep' | 'shallow' | 'lastWins' | 'arrayConcat' | '
  */
 export declare function min<T>(array: T[], callback?: (item: T) => string | number | Date): T | undefined;
 
+/**
+ * Represents a monetary amount with currency.
+ * Amount is stored as bigint (minor units/cents) for precision.
+ */
+export declare type Money = {
+    readonly amount: bigint;
+    readonly currency: string;
+};
+
+/**
+ * Multiplies a number by a scalar with precision handling for financial calculations.
+ * Supports both regular numbers and bigint for exact precision.
+ *
+ * @example
+ * ```ts
+ * multiply(10, 5); // 50
+ * multiply(0.1, 3); // 0.3 (precision-safe)
+ * multiply(100n, 5n); // 500n
+ * ```
+ *
+ * @param a - Number to multiply
+ * @param b - Multiplier
+ * @returns Product of a and b
+ */
+export declare function multiply(a: number, b: number): number;
+
+export declare function multiply(a: bigint, b: bigint): bigint;
+
 export declare type Obj = Record<string, any>;
 
 /**
@@ -1519,6 +1735,37 @@ export declare const once: <T extends Fn>(fn: T) => T & {
     reset: () => void;
 };
 
+/**
+ * Processes an array with an async callback with controlled parallelism.
+ * Similar to Promise.all, but limits how many items are processed concurrently.
+ * Returns an ordered array of results.
+ *
+ * @example
+ * ```ts
+ * // Process 3 items at a time
+ * const results = await parallel(3, [1, 2, 3, 4, 5], async (n) => {
+ *   await delay(100);
+ *   return n * 2;
+ * });
+ * // [2, 4, 6, 8, 10]
+ *
+ * // With abort signal
+ * const controller = new AbortController();
+ * const results = await parallel(2, items, async (item) => {
+ *   return processItem(item);
+ * }, controller.signal);
+ * ```
+ *
+ * @param limit - Maximum number of concurrent operations (must be >= 1)
+ * @param array - Array of items to process
+ * @param callback - Async function to process each item
+ * @param signal - Optional AbortSignal to cancel processing
+ * @returns Promise resolving to an ordered array of results
+ * @throws {Error} If limit is less than 1
+ * @throws {DOMException} If aborted via signal
+ */
+export declare function parallel<T, R>(limit: number, array: T[], callback: (item: T, index: number, array: T[]) => Promise<R>, signal?: AbortSignal): Promise<R[]>;
+
 /**
  * Parses a JSON string and returns the resulting object.
  *
@@ -1542,12 +1789,12 @@ export declare const once: <T extends Fn>(fn: T) => T & {
  */
 export declare function parseJSON<T extends JSONValue>(json: unknown, options?: ParseJSONOptions<T>): T | undefined;
 
-declare interface ParseJSONOptions<T> {
+declare type ParseJSONOptions<T> = {
     defaultValue?: T;
     reviver?: (key: string, value: any) => any;
     validator?: (value: any) => boolean;
     silent?: boolean;
-}
+};
 
 /**
  * Converts a string to Pascal case.
@@ -1615,7 +1862,7 @@ declare type PathValue<T, P extends string> = P extends `${infer Key}.${infer Re
  *
  * @throws {TypeError} If the first argument is not an array.
  */
-export declare function pick<T, R, C extends CallbackDynamic<T, R>>(array: T[], callback: C, predicate?: Predicate<T>): Result<C> | undefined;
+export declare function pick<T, R = T>(array: T[], callback: (item: T, index: number, array: T[]) => R, predicate?: (item: T, index: number, array: T[]) => boolean): R | undefined;
 
 export declare namespace pick {
     var fp: boolean;
@@ -1651,7 +1898,7 @@ export declare function pipe<T extends FnDynamic[]>(...fns: T): PipeReturn<T>;
 
 declare type PipeReturn<T extends FnDynamic[]> = (...args: FirstParameters<T>) => LastReturnType<T> extends Promise<any> ? Promise<Awaited<LastReturnType<T>>> : LastReturnType<T>;
 
-export declare type Predicate<T> = (value: T, index: number, array: T[]) => boolean | boolean[];
+export declare type Predicate<T> = (value: T, index: number, array: readonly T[]) => boolean;
 
 /**
  * Creates a Promise that can be aborted using an AbortController.
@@ -1708,6 +1955,27 @@ declare type ProxyOptions<T> = {
     watch?: (keyof T)[];
 };
 
+/**
+ * Removes all nullable and empty values from strings, arrays, or objects.
+ *
+ * - For strings: Removes leading/trailing whitespace and returns undefined if empty
+ * - For arrays: Recursively removes null, undefined, empty strings, and empty objects/arrays
+ * - For objects: Recursively removes properties with null, undefined, empty strings, and empty objects/arrays
+ *
+ * @example
+ * ```ts
+ * prune('  hello  '); // 'hello'
+ * prune('   '); // undefined
+ * prune([1, null, '', 2, undefined, 3]); // [1, 2, 3]
+ * prune({ a: 1, b: null, c: '', d: 2 }); // { a: 1, d: 2 }
+ * prune({ a: { b: null, c: '' }, d: 1 }); // { d: 1 }
+ * ```
+ *
+ * @param value - The value to prune (can be string, array, object, or any other type)
+ * @returns The pruned value, or undefined if the result would be empty
+ */
+export declare function prune<T>(value: T): T | undefined;
+
 /**
  * Generates a random integer between two values, inclusive.
  *
@@ -1739,6 +2007,9 @@ export declare function random(min: number, max: number): number;
  * @param step - The value to increment or decrement by.
  *
  * @returns The range of numbers.
+ *
+ * @throws {TypeError} If start, stop, or step are not finite numbers.
+ * @throws {Error} If step is 0 or if range exceeds maximum size.
  */
 export declare function range(start: number, stop: number, step: number): number[];
 
@@ -1789,6 +2060,72 @@ export declare namespace reduce {
     var fn: boolean;
 }
 
+declare type RemoteConfig<T, F, S> = Readonly<{
+    debounceMs?: number;
+    fetch: (q: RemoteQuery<F, S>) => Promise<RemoteResult<T>>;
+    initialFilter?: F;
+    initialSort?: S;
+    limit?: number;
+}>;
+
+export declare type RemoteList<T, F, S> = {
+    readonly current: readonly T[];
+    readonly meta: RemoteMeta;
+    subscribe(listener: () => void): () => void;
+    goTo(page: number): Promise<void>;
+    invalidate?(): void;
+    next(): Promise<void>;
+    prev(): Promise<void>;
+    refresh(): Promise<void>;
+    reset(): Promise<void>;
+    search(query: string, opts?: {
+        immediate?: boolean;
+    }): Promise<void>;
+    setFilter(filter: F): Promise<void>;
+    setLimit(n: number): Promise<void>;
+    setSort(sort?: S): Promise<void>;
+    batch(mutator: (ctx: {
+        setLimit(n: number): void;
+        setFilter(f: F): void;
+        setSort(s?: S): void;
+        setQuery(q: string): void;
+        setData?(d: readonly T[]): void;
+        goTo(p: number): void;
+    }) => void): Promise<void>;
+};
+
+export declare function remoteList<T, F = Record<string, unknown>, S = {
+    key?: string;
+    dir?: 'asc' | 'desc';
+}>(cfg: RemoteConfig<T, F, S>): RemoteList<T, F, S>;
+
+export declare type RemoteMeta = Readonly<{
+    end: number;
+    error: string | null;
+    isEmpty: boolean;
+    isFirst: boolean;
+    isLast: boolean;
+    limit: number;
+    loading: boolean;
+    page: number;
+    pages: number;
+    start: number;
+    total: number;
+}>;
+
+declare type RemoteQuery<F, S> = Readonly<{
+    filter?: F;
+    limit: number;
+    page: number;
+    search?: string;
+    sort?: S;
+}>;
+
+declare type RemoteResult<T> = Readonly<{
+    items: readonly T[];
+    total: number;
+}>;
+
 declare type RemoveFirstParameter<T extends Fn> = T extends (first: any, ...rest: infer R) => any ? R : never;
 
 export declare type Result<C extends FnDynamic> = C extends FnAsync ? Promise<Awaited<ReturnType<C>>> : ReturnType<C>;
@@ -1817,7 +2154,7 @@ export declare type ResultArray<C extends FnDynamic> = C extends FnAsync ? Promi
 export declare function retry<T>(fn: () => Promise<T>, { times, delay, backoff, signal, }?: {
     times?: number;
     delay?: number;
-    backoff?: number;
+    backoff?: number | ((attempt: number, delay: number) => number);
     signal?: AbortSignal;
 }): Promise<T>;
 
@@ -1984,6 +2321,8 @@ export declare function similarity(str1: unknown, str2: unknown): number;
  * @param timeout - The number of milliseconds to wait before resolving the Promise.
  *
  * @returns A Promise that resolves after the specified time.
+ *
+ * @throws {TypeError} If timeout is not a non-negative number.
  */
 export declare function sleep(timeout: number): Promise<void>;
 
@@ -2046,26 +2385,7 @@ export declare const sort: {
     fp: boolean;
 };
 
-/**
- * Sorts an array of objects based on multiple selectors.
- *
- * @example
- * ```ts
- * const data = [
- *   { name: 'Alice', age: 30 },
- *   { name: 'Bob', age: 25 },
- *   { name: 'Charlie', age: 35 },
- *   { name: 'Alice', age: 25 },
- *   { name: 'Bob', age: 30 },
- *   { name: 'Charlie', age: 30 },
- * ].sortBy(data, { name: 'asc', age: 'desc' }); // [ { name: 'Alice', age: 30 }, { name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }, { name: 'Bob', age: 25 }, { name: 'Charlie', age: 35 }, { name: 'Charlie', age: 30 } ]
- * ```
- *
- * @param array - The array to sort.
- * @param selectors - An object where keys are the properties to sort by and values are 'asc' or 'desc'.
- * @returns A new sorted array.
- */
-export declare const sortBy: <T>(array: T[], selectors: Partial<Record<keyof T, "asc" | "desc">>) => T[];
+export declare type Sorter<T> = (a: T, b: T) => number;
 
 /**
  * Replaces the first element in an array that satisfies the provided predicate function with a new value.
@@ -2089,6 +2409,25 @@ export declare namespace substitute {
     var fn: boolean;
 }
 
+/**
+ * Subtracts one number from another with precision handling for financial calculations.
+ * Supports both regular numbers and bigint for exact precision.
+ *
+ * @example
+ * ```ts
+ * subtract(20, 10); // 10
+ * subtract(0.3, 0.1); // 0.2 (precision-safe)
+ * subtract(300n, 100n); // 200n
+ * ```
+ *
+ * @param a - Number to subtract from
+ * @param b - Number to subtract
+ * @returns Difference of a and b
+ */
+export declare function subtract(a: number, b: number): number;
+
+export declare function subtract(a: bigint, b: bigint): bigint;
+
 /**
  * Sum numbers in an array or numbers mapped by a callback function.
  *
@@ -2097,7 +2436,6 @@ export declare namespace substitute {
  * sum([1, 2, 3]) // 6
  * sum([{value: 1}, {value: 2}, {value: 3}], (item) => item.value) // 6
  * sum(['apple', 'banana', 'cherry']) // TypeError
- * sum([new Date('2023-01-01'), new Date('2022-01-01')]) // 467308800000
  * ```
  *
  * @param array - The array to sum.
@@ -2105,29 +2443,49 @@ export declare namespace substitute {
  *
  * @returns The sum of the numbers in the array or the sum of the mapped values.
  */
-export declare function sum<T>(array: T[], callback?: (item: T) => number | Date): number | Date | undefined;
+export declare function sum<T>(array: T[], callback?: (item: T) => number): number | undefined;
 
 declare type SyncCallback<R, T> = (prev: R, curr: T, index: number, array: T[]) => R;
 
+/** biome-ignore-all lint/suspicious/noExplicitAny: - */
 /**
- * Creates a throttled function that only invokes the provided function at most once per every specified milliseconds.
+ * Curries a function, allowing it to be called with partial arguments.
  *
  * @example
  * ```ts
- * const log = () => console.log('Hello, world!');
- * const throttledLog = throttle(log, 1000);
- *
- * throttledLog(); // logs 'Hello, world!' immediately
- * throttledLog(); // does nothing because less than 1 second has passed since the last invocation
- * setTimeout(throttledLog, 1000); // logs 'Hello, world!' after 1 second
+ * const add = (a: number, b: number) => a + b;
+ * const curriedAdd = curry(add);
+ * curriedAdd(1)(2) // 3;
  * ```
  *
- * @param fn - The function to throttle.
- * @param [delay=700] - The number of milliseconds to wait before invoking the function again.
+ * @param fn - The function to curry.
+ * @param arity - The number of arguments the function expects. Defaults to the function's length.
+ *
+ * @returns A curried version of the function.
+ */
+declare type Take<N extends number, T extends readonly unknown[], Acc extends readonly unknown[] = []> = Acc['length'] extends N ? Acc : T extends readonly [infer H, ...infer R] ? Take<N, R, readonly [...Acc, H]> : Acc;
+
+/**
+ * Throttles a function. By default, leading and trailing are both true (lodash-like behavior).
+ * The function is invoked at the leading edge and trailing edge of the throttle period.
  *
- * @returns A new function that throttles the input function.
+ * Example:
+ * const fn = () => ...
+ * const t = throttle(fn, 700);
+ * const leadingOnly = throttle(fn, 700, { trailing: false });
  */
-export declare function throttle<T extends Fn>(fn: T, delay?: number): (...args: Parameters<T>) => void;
+export declare function throttle<T extends Fn>(fn: T, delay?: number, options?: ThrottleOptions): Throttled<T>;
+
+export declare type Throttled<T extends Fn> = ((this: ThisParameterType<T>, ...args: Parameters<T>) => void) & {
+    cancel(): void;
+    flush(): ReturnType<T> | undefined;
+    pending(): boolean;
+};
+
+export declare type ThrottleOptions = {
+    leading?: boolean;
+    trailing?: boolean;
+};
 
 /**
  * Calculates the remaining time until a target date.
@@ -2178,6 +2536,8 @@ export declare type TimeUnit = 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MIN
  * @param ellipsis - The characters to end the truncated string with.
  *
  * @returns The truncated string.
+ *
+ * @throws {TypeError} If str is not a string or limit is not a positive number.
  */
 export declare function truncate(str: string, limit?: number, completeWords?: boolean, ellipsis?: string): string;