Array Utilities

Array utilities provide a powerful set of tools to transform, query, and manipulate arrays in a type-safe, ergonomic way.

📚 Quick Reference

Problem

Implement 📚 quick reference in a production-friendly way with @vielzeug/toolkit while keeping setup and cleanup explicit.

Runnable Example

The snippet below is copy-paste runnable in a TypeScript project with @vielzeug/toolkit installed.

Method	Category	Description
chunk	Transformation	Split array into chunks of a specific size
contains	Query	Check if array contains a value (deep equality)
fold	Aggregation	Reduce without an initial value
group	Aggregation	Group elements by a key or function
keyBy	Aggregation	Index elements by a key
list	Pagination	Client-side reactive pagination with filtering
pick	Query	Pick and transform single element
remoteList	Pagination	Server-side reactive pagination with caching
replace	Transformation	Replace first matching element
rotate	Transformation	Rotate elements by N positions
search	Query	Fuzzy search in array
select	Transformation	Map and filter in one step
sort	Sorting	Sort by selector or multi-field object selector
toggle	Transformation	Add or remove item (toggle behaviour)
uniq	Set	Remove duplicate values

💡 Practical Examples

Data Transformation

import { chunk, select, toggle, uniq } from '@vielzeug/toolkit';

const rawData = [1, 2, 2, 3, 4, 5];

// Remove duplicates
const unique = uniq(rawData); // [1, 2, 3, 4, 5]

// Map + filter in one pass (select returns only non-null results)
const doubled = select(unique, (x) => (x > 2 ? x * 2 : null)); // [6, 8, 10]

// Batch for processing
const batches = chunk(doubled, 2); // [[6, 8], [10]]

// Toggle item in/out of a set
const tags = toggle(['ts', 'react'], 'react'); // ['ts']
const withNew = toggle(['ts'], 'vue'); // ['ts', 'vue']

Advanced Grouping & Indexing

import { group, keyBy } from '@vielzeug/toolkit';

const users = [
  { id: 1, name: 'Alice', role: 'admin' },
  { id: 2, name: 'Bob', role: 'user' },
  { id: 3, name: 'Carol', role: 'user' },
];

// Group by role
const byRole = group(users, (u) => u.role);
/*
{
  admin: [{ id: 1, name: 'Alice', role: 'admin' }],
  user:  [{ id: 2, ... }, { id: 3, ... }]
}
*/

// Index by id (last wins when keys collide)
const byId = keyBy(users, 'id');
/*
{
  '1': { id: 1, name: 'Alice', ... },
  '2': { id: 2, name: 'Bob',   ... },
  '3': { id: 3, name: 'Carol', ... }
}
*/

Fold — Reduce Without Initial Value

import { fold } from '@vielzeug/toolkit';

fold([1, 2, 3], (a, b) => a + b); // 6
fold([3, 1, 4], (a, b) => (a > b ? a : b)); // 4 (max)
fold([], (a, b) => a + b); // undefined

🔗 All Array Utilities

• chunk
• contains
• fold
• group
• keyBy
• list
• pick
• remoteList
• replace
• rotate
• search
• select
• sort
• toggle
• uniq

Expected Output

• The example runs without type errors in a standard TypeScript setup.
• The main flow produces the behavior described in the recipe title.

Common Pitfalls

• Forgetting cleanup/dispose calls can leak listeners or stale state.
• Skipping explicit typing can hide integration issues until runtime.
• Not handling error branches makes examples harder to adapt safely.

Related Recipes

• Async Examples
• Date Examples
• Function Examples