Toolkit API Reference

Complete reference for all utilities available in @vielzeug/toolkit.

Overview

Toolkit provides 110+ utilities organized into 9 categories. All utilities are:

✅ Type-safe with full TypeScript inference
✅ Tree-shakeable for minimal bundle sizes
✅ Isomorphic (Browser + Node.js)
✅ Well-tested with >95% code coverage

Array Utilities - Transform, filter, group, and sort arrays
Object Utilities - Deep operations, merging, and traversal
String Utilities - Formatting, casing, and manipulation
Function Utilities - Debounce, throttle, memoize, and retry
Math Utilities - Statistics, calculations, and ranges
Money Utilities - Currency formatting and conversion
Date Utilities - Time intervals and differences
Random Utilities - Random values, shuffling, and sampling
Typed Utilities - Type guards and runtime checks

Array Utilities

Transform, filter, and manipulate arrays with type safety.

See Array Examples for detailed usage.

Transformation

Utility	Description	Example
`map`	Transform each element (async supported)	`map([1,2,3], x => x*2)` → `[2,4,6]`
`filter`	Filter elements by predicate (async supported)	`filter([1,2,3], x => x > 1)` → `[2,3]`
`reduce`	Reduce array to single value	`reduce([1,2,3], (a,b) => a+b)` → `6`
`chunk`	Split into chunks of specific size	`chunk([1,2,3,4,5], 2)` → `[[1,2],[3,4],[5]]`
`flatten`	Flatten nested arrays	`flatten([[1,2],[3,4]])` → `[1,2,3,4]`
`compact`	Remove null/undefined values	`compact([1,null,2])` → `[1,2]`
`alternate`	Toggle item in array (add/remove)	`alternate([1,2], 2)` → `[1]`
`shift`	Rotate array elements	`shift([1,2,3], 1)` → `[2,3,1]`
`substitute`	Replace elements conditionally	`substitute([1,2,3], x => x === 2, 0)` → `[1,0,3]`

Aggregation

Utility	Description	Example
`group`	Group elements by key or function	`group(users, u => u.role)`
`aggregate`	Aggregate array to object by key	`aggregate(items, 'id')`
`uniq`	Remove duplicate values	`uniq([1,2,2,3])` → `[1,2,3]`

Querying

Utility	Description	Example
`find`	Find first matching element	`find([1,2,3], x => x > 1)` → `2`
`findIndex`	Find index of first match	`findIndex([1,2,3], x => x > 1)` → `1`
`findLast`	Find last matching element	`findLast([1,2,3], x => x > 1)` → `3`
`some`	Check if any element matches	`some([1,2,3], x => x > 2)` → `true`
`every`	Check if all elements match	`every([1,2,3], x => x > 0)` → `true`
`contains`	Check if array contains value	`contains([1,2,3], 2)` → `true`
`search`	Fuzzy search in array	`search(users, 'alice')`

Sorting

Utility	Description	Example
`sort`	Sort with custom comparator	`sort([3,1,2], (a,b) => a-b)` → `[1,2,3]`
`arrange`	Sort by property or function	`arrange(users, {age: 'asc'})`

Selection

Utility	Description	Example
`pick`	Pick and transform element	`pick([1,2,3], x => x*2, x => x > 1)` → `4`
`select`	Map and filter in one step	`select([1,2,3], x => x > 1 ? x*2 : null)`

Pagination

Utility	Description	Example
`list`	Client-side reactive pagination	`list(data, {limit: 10})`
`remoteList`	Server-side reactive pagination with caching	`remoteList({fetch: fetchFn, limit: 20})`

Object Utilities

Deep operations, merging, and property manipulation.

See Object Examples for detailed usage.

Utility	Description	Example
`cache`	Key-value cache with automatic GC	`cache<T>()`
`clone`	Deep clone an object	`clone({a: {b: 1}})`
`merge`	Merge objects (deep/shallow/etc.)	`merge('deep', obj1, obj2)`
`diff`	Find differences between objects	`diff(obj1, obj2)`
`path`	Access nested properties safely	`path(obj, 'user.profile.name')`
`seek`	Find value by key anywhere in object	`seek(obj, 'email')`
`parseJSON`	Safely parse JSON with fallback	`parseJSON(str, defaultValue)`
`keys`	Type-safe Object.keys()	`keys(obj)`
`values`	Type-safe Object.values()	`values(obj)`
`entries`	Type-safe Object.entries()	`entries(obj)`

String Utilities

Formatting, casing, similarity, and manipulation.

See String Examples for detailed usage.

Casing

Utility	Description	Example
`camelCase`	Convert to camelCase	`camelCase('hello-world')` → `'helloWorld'`
`snakeCase`	Convert to snake_case	`snakeCase('helloWorld')` → `'hello_world'`
`kebabCase`	Convert to kebab-case	`kebabCase('helloWorld')` → `'hello-world'`
`pascalCase`	Convert to PascalCase	`pascalCase('hello-world')` → `'HelloWorld'`

Manipulation

Utility	Description	Example
`truncate`	Truncate string with ellipsis	`truncate('long text', 5)` → `'long...'`

Analysis

Utility	Description	Example
`similarity`	Calculate string similarity	`similarity('hello', 'hallo')` → `0.8`

Function Utilities

Control execution timing and behavior.

See Function Examples for detailed usage.

Utility	Description	Example
`debounce`	Delay execution until idle	`debounce(fn, 300)`
`throttle`	Limit execution rate	`throttle(fn, 100)`
`memo`	Memoize/cache function results	`memo(expensiveFn)`
`retry`	Retry failed operations	`retry(asyncFn, {attempts: 3})`
`parallel`	Process array with controlled concurrency	`parallel(5, items, asyncFn)`
`compose`	Compose functions right-to-left	`compose(f, g, h)`
`pipe`	Compose functions left-to-right	`pipe(f, g, h)`
`once`	Execute function only once	`once(fn)`
`delay`	Delay execution	`await delay(1000)`
`prune`	Remove nullable/empty values	`prune({ a: 1, b: null })` → `{ a: 1 }`

Math Utilities

Statistics, calculations, and number operations.

See Math Examples for detailed usage.

Arithmetic Operations

Utility	Description	Example
`add`	Add two numbers	`add(10, 20)` → `30`
`subtract`	Subtract numbers	`subtract(20, 10)` → `10`
`multiply`	Multiply numbers	`multiply(10, 5)` → `50`
`divide`	Divide numbers	`divide(20, 5)` → `4`
`abs`	Absolute value	`abs(-5)` → `5`

Distribution

Utility	Description	Example
`allocate`	Distribute proportionally	`allocate(100, [1,2,3])` → `[16,33,51]`
`distribute`	Distribute evenly	`distribute(100, 3)` → `[34,33,33]`

Statistics

Utility	Description	Example
`sum`	Sum of numbers	`sum([1,2,3])` → `6`
`average`	Calculate average/mean	`average([1,2,3])` → `2`
`median`	Find median value	`median([1,2,3,4,5])` → `3`
`min`	Find minimum value	`min([1,2,3])` → `1`
`max`	Find maximum value	`max([1,2,3])` → `3`

Number Utilities

Utility	Description	Example
`clamp`	Clamp value to range	`clamp(10, 0, 5)` → `5`
`range`	Generate number range	`range(1, 5)` → `[1,2,3,4,5]`
`round`	Round to decimal places	`round(3.14159, 2)` → `3.14`
`rate`	Calculate percentage	`rate(25, 100)` → `25`
`boil`	Reduce with comparator	`boil([1,2,3], (a,b) => a+b)`

Money Utilities

Currency formatting and conversion with precision.

See Money Examples for detailed usage.

Utility	Description	Example
`currency`	Format money for display	`currency({amount: 123456n, currency: 'USD'})` → `'$1,234.56'`
`exchange`	Convert between currencies	`exchange(usd, {from: 'USD', to: 'EUR', rate: 0.85})`

Date Utilities

Time intervals, differences, and expiration checks.

See Date Examples for detailed usage.

Utility	Description	Example
`expires`	Check expiration status	`expires('2026-01-01')` → `'SOON'`
`interval`	Generate date range	`interval('2024-01-01', '2024-01-31', {interval: 'D'})`
`timeDiff`	Calculate time difference	`timeDiff(date1, date2)` → `{value: 5, unit: 'DAY'}`

Random Utilities

Random generation, shuffling, and sampling.

See Random Examples for detailed usage.

Utility	Description	Example
`random`	Random number in range	`random(1, 10)` → `7`
`draw`	Random array element	`draw([1,2,3])` → `2`
`shuffle`	Shuffle array	`shuffle([1,2,3])` → `[3,1,2]`
`uuid`	Generate UUID v4	`uuid()` → `'550e8400-...'`

Typed Utilities

Comprehensive type guards and runtime type checking.

See Typed Examples for detailed usage.

Type Guards

Utility	Description	TypeScript Narrowing
`isString`	Check if string	`unknown` → `string`
`isNumber`	Check if number	`unknown` → `number`
`isBoolean`	Check if boolean	`unknown` → `boolean`
`isArray`	Check if array	`unknown` → `Array<unknown>`
`isObject`	Check if object	`unknown` → `object`
`isFunction`	Check if function	`unknown` → `Function`
`isDate`	Check if Date	`unknown` → `Date`
`isRegex`	Check if RegExp	`unknown` → `RegExp`
`isPromise`	Check if Promise	`unknown` → `Promise<unknown>`
`isDefined`	Check if not null/undefined	`T` → `NonNullable<T>`
`isNil`	Check if null or undefined	`unknown` → `null \| undefined`
`isPrimitive`	Check if primitive type	`unknown` → `boolean`

Value Checks

Utility	Description	Example
`isEmpty`	Check if empty	`isEmpty([])` → `true`
`isEqual`	Deep equality comparison	`isEqual({a:1}, {a:1})` → `true`
`isMatch`	Pattern matching	`isMatch(obj, {role: 'admin'})`
`isWithin`	Check if number in range	`isWithin(5, 0, 10)` → `true`
`isEven`	Check if even number	`isEven(4)` → `true`
`isOdd`	Check if odd number	`isOdd(3)` → `true`
`isPositive`	Check if positive	`isPositive(5)` → `true`
`isNegative`	Check if negative	`isNegative(-5)` → `true`
`isZero`	Check if zero	`isZero(0)` → `true`

Comparison

Utility	Description	Example
`gt`	Greater than	`gt(5, 3)` → `true`
`ge`	Greater or equal	`ge(5, 5)` → `true`
`lt`	Less than	`lt(3, 5)` → `true`
`le`	Less or equal	`le(5, 5)` → `true`

Multi-Purpose

Utility	Description	Example
`is`	Multi-purpose type checker	`is('string', val)` → `boolean`
`typeOf`	Get type of value	`typeOf([])` → `'array'`

Import Reference

Individual Imports (Recommended)

// Best for tree-shaking
import { map, filter, group } from '@vielzeug/toolkit';

Category Imports

import { chunk, map } from '@vielzeug/toolkit/array';
import { merge, clone } from '@vielzeug/toolkit/object';
import { camelCase } from '@vielzeug/toolkit/string';
import { debounce } from '@vielzeug/toolkit/function';
import { sum, average } from '@vielzeug/toolkit/math';
import { interval } from '@vielzeug/toolkit/date';
import { random, uuid } from '@vielzeug/toolkit/random';
import { isString, isArray } from '@vielzeug/toolkit/typed';

Toolkit API Reference ​

Overview ​

Quick Navigation ​

Array Utilities ​

Transformation ​

Aggregation ​

Querying ​

Sorting ​

Selection ​

Pagination ​

Object Utilities ​

String Utilities ​

Casing ​

Manipulation ​

Analysis ​

Function Utilities ​

Math Utilities ​

Arithmetic Operations ​

Distribution ​

Statistics ​

Number Utilities ​

Money Utilities ​

Date Utilities ​

Random Utilities ​

Typed Utilities ​

Type Guards ​

Value Checks ​

Comparison ​

Multi-Purpose ​

Import Reference ​

Individual Imports (Recommended) ​

Category Imports ​

See Also ​