@rokkit/data

Data manipulation utilities for the Rokkit design system — filtering, joining, schema inference, and dataset views.

Install

npm install @rokkit/data
# or
bun add @rokkit/data

Overview

@rokkit/data provides general-purpose data utilities for working with arrays of objects. It is used internally by @rokkit/ui table and grid components and can also be used standalone.

• Type inference — detect column types from data samples
• Filtering — apply single or multiple filters with standard operators
• Joins — relational join operations across two datasets
• Dataset / Dataview — composable dataset abstraction with filter, sort, and pagination
• Metadata — derive column definitions and types from raw data
• Renaming — remap object keys with a rename spec

Usage

Type inference

import { typeOf } from '@rokkit/data'

typeOf('hello') // 'string'
typeOf(42) // 'number'
typeOf(new Date()) // 'date'
typeOf([1, 2]) // 'array'
typeOf({ a: 1 }) // 'object'
typeOf(true) // 'boolean'

Filtering

import { filterObjectArray, filterData } from '@rokkit/data'

// Single filter
const adults = filterObjectArray(users, {
  column: 'age',
  value: 18,
  operator: 'gte'
})

// Multiple filters combined
const results = filterData(users, [
  { column: 'status', value: 'active', operator: 'eq' },
  { column: 'age', value: 18, operator: 'gte' }
])

Supported operators: eq, ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn.

Joins

import { leftJoin, innerJoin } from '@rokkit/data'

const result = leftJoin(orders, customers, 'customerId', 'id')
// Each order row merged with its matching customer row (nulls if unmatched)

Available joins: innerJoin, leftJoin, rightJoin, fullJoin, crossJoin, antiJoin, semiJoin.

Schema inference

import { deriveMetadata, deriveColumns } from '@rokkit/data'

const metadata = deriveMetadata(data)
// [{ column: 'name', type: 'string' }, { column: 'age', type: 'number' }, ...]

const columns = deriveColumns(data)
// Column definitions ready for use in a table component

Dataset and dataview

import { dataset, dataview } from '@rokkit/data'

const ds = dataset(rawData)
const view = dataview(ds, {
  filters: [{ column: 'active', value: true, operator: 'eq' }],
  sort: [{ column: 'name', direction: 'asc' }],
  page: { size: 20, index: 0 }
})

Key renaming

import { renamer } from '@rokkit/data'

const rename = renamer({ firstName: 'first_name', lastName: 'last_name' })
const remapped = data.map(rename)

Filter string parsing

import { parseFilters } from '@rokkit/data'

const filters = parseFilters('age >= 18 AND status = "active"')

API

| Export | Description | | --------------------------------- | ----------------------------------------------------- | | typeOf(value) | Infer type string from a value | | filterObjectArray(data, filter) | Apply a single filter object to an array | | filterData(data, filters) | Apply an array of filters to a dataset | | parseFilters(string) | Parse a filter expression string into filter objects | | innerJoin(a, b, keyA, keyB) | Inner join two arrays on matching keys | | leftJoin(a, b, keyA, keyB) | Left join — all rows from a, matched rows from b | | rightJoin(a, b, keyA, keyB) | Right join — all rows from b, matched rows from a | | fullJoin(a, b, keyA, keyB) | Full outer join | | crossJoin(a, b) | Cartesian product of two arrays | | antiJoin(a, b, keyA, keyB) | Rows in a with no match in b | | semiJoin(a, b, keyA, keyB) | Rows in a that have a match in b | | deriveMetadata(data) | Infer column names and types from a data sample | | deriveColumns(data) | Derive column definitions from data | | deriveSortableColumn(col) | Mark a column as sortable | | dataset(data, options?) | Create a dataset abstraction | | dataview(dataset, options?) | Create a filtered/sorted/paged view over a dataset | | renamer(mapping) | Create a function that renames object keys | | model(data) | Create a reactive data model |

Benchmarks

Results from benchmark/results/p4-lazy-fusion.json — Bun 1.3.11, Apple Silicon (arm64). All times in ms (mean) over 10 iterations. Dataset sizes: small = 100 rows, medium = 1 000 rows, large = 10 000 rows.

| Operation | Small | Medium | Large | | --------------------------- | ----: | -----: | -----: | | groupBy + rollup | 0.113 | 0.236 | 1.617 | | groupBy + summarize + rollup | 0.042 | 0.097 | 0.534 | | groupBy + alignBy + rollup | 0.133 | 0.090 | 0.085 | | where + apply + sortBy| 0.024 | 0.120 | 1.328 | | filterData | 0.020 | 0.022 | 0.081 | | leftJoin | 0.044 | 0.448 | 23.620 | | antiJoin | 0.045 | 0.340 | 13.798 | | semiJoin | 0.032 | 0.172 | 11.318 | | crossJoin | 0.034 | 0.023 | — |

To run benchmarks locally:

bun run benchmark          # print results to console
bun run benchmark:save     # save results to benchmark/results/baseline.json

Part of Rokkit — a Svelte 5 component library and design system.