Toolkit API Reference

• API At a Glance
• Overview
• Quick Navigation
• Array Utilities
  • Transformation
  • Aggregation
  • Querying
  • Sorting
  • Selection
  • Pagination
• Object Utilities
• String Utilities
  • Casing
  • Manipulation
  • Analysis
• Function Utilities
• Async Utilities
• Math Utilities
  • Arithmetic Operations
  • Distribution
  • Statistics
  • Number Utilities
• Money Utilities
• Date Utilities
• Random Utilities
• Typed Utilities
  • is Namespace Methods
• Import Reference
  • Individual Imports (Recommended)
• See Also

API At a Glance

Symbol	Purpose	Execution mode	Common gotcha
chunk()	Split arrays into fixed-size groups	Sync	Validate positive chunk sizes
retry()	Retry async operations with delay strategy	Async	Use bounded retries to avoid runaway loops
currency()	Format monetary values safely	Sync	Match currency precision to business requirements

Overview

Toolkit provides 75+ utilities organized into 10 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

Quick Navigation

• 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 more
• Async Utilities – Async control flow, retry, and concurrency
• 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
chunk	Split into chunks of specific size	chunk([1,2,3,4,5], 2) → [[1,2],[3,4],[5]]
fold	Reduce to single value (no initial value)	fold([1,2,3], (a,b) => a+b) → 6
replace	Replace first matching element	replace([1,2,3], x => x === 2, 0) → [1,0,3]
rotate	Rotate array positions	rotate([1,2,3], 1) → [2,3,1]
toggle	Toggle item in array (add/remove)	toggle([1,2], 2) → [1]

Aggregation

Utility	Description	Example
group	Group elements by key or function	group(users, u => u.role)
keyBy	Index array by property	keyBy(users, 'id')
uniq	Remove duplicate values	uniq([1,2,2,3]) → [1,2,3]

Querying

Utility	Description	Example
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 by selector or object selectors	sort(users, { age: 'desc', name: 'asc' })

Selection

Utility	Description	Example
pick	Pick and transform element	pick([1,2,3], x => x*2, x => x > 1) → 4
select	Map non-null elements with callback	select([null, 1, 2], x => x * 2) → [2, 4]

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
stash	Key-value cache with automatic GC	stash<T>({ hash: key => ... })
diff	Find differences between objects	diff(obj1, obj2)
merge	Merge objects (deep/shallow/etc.)	merge('deep', obj1, obj2)
parseJSON	Safely parse JSON with fallback	parseJSON(str, defaultValue)
get	Access nested properties safely	get(obj, 'user.profile.name')
proxy	Object proxy with get/set hooks	proxy(obj, { set: logger })
prune	Remove null/empty values recursively	prune({ a: 1, b: null })
seek	Search object values by similarity	seek(obj, 'hello', 0.8) → true

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 flow, composition, and assertions.

See Function Examples for detailed usage.

Utility	Description	Example
assert	Assert condition (throws or warns)	assert(x > 0, 'Must be positive')
assertParams	Assert required object keys are present	assertParams(params, ['id', 'name'])
compare	Compare two values → -1, 0, or 1	compare('a', 'b') → -1
compareBy	Multi-key object comparator	compareBy({ name: 'asc', age: 'desc' })
compose	Compose functions right-to-left	compose(f, g, h)
curry	Curry function with partial application	curry(add)(1)(2) → 3
debounce	Delay execution until idle	debounce(fn, 300)
fp	Functional programming pipeline wrapper	fp(map, double)([1,2,3])
memo	Memoize/cache function results	memo(expensiveFn)
once	Execute function only once	once(fn)
pipe	Compose functions left-to-right	pipe(f, g, h)
throttle	Limit execution rate	throttle(fn, 100)

Async Utilities

Async control flow, retry strategies, and concurrency primitives.

See Async Examples for detailed usage.

Utility	Description	Example
attempt	Execute fn with retry and error handling	attempt(fetchFn, { times: 3, timeout: 5000 })
defer	Create deferred promise with external control	const { promise, resolve } = defer()
parallel	Process array with controlled concurrency	await parallel(5, items, asyncFn)
pool	Concurrency-limited promise pool	const slot = pool(3); await slot(fn)
queue	Sequential queue with concurrency control	const q = queue(); q.add(task)
race	Race promise with minimum delay	race(fetchFn(), 500)
retry	Retry async fn with backoff, per-attempt delay, and predicate	retry(asyncFn, { times: 3, delay: 250, shouldRetry: fn })
Scheduler	Task scheduler with native API or polyfill fallback	new Scheduler().postTask(fn, { delay: 100, priority: 'background' })
polyfillScheduler	Install the Scheduler polyfill globally when not natively supported	polyfillScheduler()
sleep	Wait milliseconds	await sleep(1000)
waitFor	Poll condition until true	await waitFor(() => isReady, { timeout: 5000 })

Math Utilities

Statistics, calculations, and number operations.

See Math Examples for detailed usage.

Arithmetic Operations

Utility	Description	Example
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
linspace	Evenly spaced number sequence	linspace(0, 1, 5) → [0, 0.25, 0.5, 0.75, 1]
percent	Calculate percentage	percent(25, 100) → 25
range	Generate number range	range(1, 6, 1) → [1,2,3,4,5]
round	Round to decimal places	round(3.14159, 2) → 3.14

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('2030-01-01') → 'LATER'
interval	Generate date range	interval('2024-01-01', '2024-01-07', { interval: 'day' })
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

Typed checks are exposed through the is namespace plus is.typeOf(...).

See Typed Examples for detailed usage.

is Namespace Methods

Method	Description	Example
is.string(value)	Check if value is a string	is.string('x')
is.number(value)	Check if value is a number (excluding NaN)	is.number(42)
is.boolean(value)	Check if value is a boolean	is.boolean(false)
is.array(value)	Check if value is an array	is.array([1, 2])
is.object(value)	Check if value is a plain object	is.object({ a: 1 })
is.fn(value)	Check if value is a function	is.fn(() => {})
is.date(value)	Check if value is a valid Date	is.date(new Date())
is.regex(value)	Check if value is a RegExp	is.regex(/a/)
is.promise(value)	Check if value is a Promise	is.promise(Promise.resolve())
is.defined(value)	Check if value is not undefined	is.defined(0)
is.nil(value)	Check if value is null or undefined	is.nil(null)
is.primitive(value)	Check if value is string/number/boolean	is.primitive('x')
is.empty(value)	Check if value is empty	is.empty([])
is.equal(a, b)	Deep equality comparison	is.equal({ a: 1 }, { a: 1 })
is.match(object, source)	Partial deep-match	is.match(user, { role: 'admin' })
is.within(value, min, max)	Inclusive range check	is.within(5, 1, 10)
is.even(value)	Check if number is even	is.even(4)
is.odd(value)	Check if number is odd	is.odd(3)
is.positive(value)	Check if number is positive	is.positive(3)
is.negative(value)	Check if number is negative	is.negative(-3)
is.zero(value)	Check if value is exactly zero	is.zero(0)
is.gt(a, b) / is.ge(a, b)	Greater-than / greater-or-equal	is.gt(5, 3)
is.lt(a, b) / is.le(a, b)	Less-than / less-or-equal	is.le(5, 5)
is.typeOf(value)	Runtime type tag	is.typeOf([]) // 'array'

Import Reference

Individual Imports (Recommended)

// Best for tree-shaking — all utilities come from the main package
import { chunk, fold, group, keyBy, select } from '@vielzeug/toolkit';
import { retry, sleep, parallel, Scheduler, polyfillScheduler } from '@vielzeug/toolkit';
import { debounce, throttle, memo } from '@vielzeug/toolkit';
import { merge, prune, diff } from '@vielzeug/toolkit';

See Also

• Usage Guide – Installation and best practices
• Examples – Category-specific examples
• GitHub Repository
• NPM Package

---

Note: Error behavior is utility-specific. See each utility page for exact validation and thrown error types.