@vielzeug/toolkit 1.0.13 → 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.
@@ -361,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.
  *
@@ -390,6 +467,36 @@ export declare namespace contains {
     var fp: boolean;
 }
 
+/**
+ * Formats a monetary amount as a currency string with proper locale and symbol.
+ * Handles decimal places automatically based on currency.
+ *
+ * @example
+ * ```ts
+ * const money = { amount: 123456n, currency: 'USD' };
+ *
+ * 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'
+ * ```
+ *
+ * @param money - Money object to format
+ * @param options - Formatting options
+ * @returns Formatted currency string
+ */
+export declare function currency(money: Money, options?: CurrencyFormatOptions): string;
+
+/**
+ * Options for currency formatting.
+ */
+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>>;
@@ -447,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.
  *
@@ -505,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';
 
 /**
@@ -1297,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: Debounced<(str: string) => T[]>;
-    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.
  *
@@ -1456,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.
  *
@@ -1479,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>;
 
 /**
@@ -1504,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.
  *
@@ -1527,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.
@@ -1636,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.
@@ -1693,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.
  *
@@ -1777,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>;
@@ -2036,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.
@@ -2079,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.
  *