Sourceit

⚡ Quick Reference

Package: @vielzeug/sourceit  ·  Category: Data

Key exports: createLocalSource, createRemoteSource

When to use: Reactive local and remote data sources with pagination, filtering, sorting, search, and URL query-param sync.

Related: Fetchit · Stateit · Routeit

@vielzeug/sourceit provides lightweight, typed source models for list-like UIs:

• createLocalSource() for in-memory collections
• createRemoteSource() for async server-backed collections

Both expose a consistent read model (current, meta, snapshot) and mutation model (goTo, search, searchNow, setFilter, setSort, setLimit, batch).

Installation

pnpm

pnpm add @vielzeug/sourceit

npm

npm install @vielzeug/sourceit

yarn

yarn add @vielzeug/sourceit

Quick Start

import { createLocalSource } from '@vielzeug/sourceit';

const source = createLocalSource(
  [
    { id: 1, name: 'Ada' },
    { id: 2, name: 'Grace' },
    { id: 3, name: 'Linus' },
  ],
  { limit: 2 },
);

source.searchNow('a');
console.log(source.current); // [{ id: 1, name: 'Ada' }, { id: 2, name: 'Grace' }]
console.log(source.meta.pageNumber); // 1

import { createRemoteSource } from '@vielzeug/sourceit';

const remote = createRemoteSource({
  fetch: async ({ limit, page, search }) => {
    const result = await api.users.list({ limit, page, search });

    return { items: result.items, total: result.total };
  },
  limit: 20,
});

remote.refresh();
await remote.ready();

Why Sourceit?

• Typed and small API surface
• Deterministic pagination/search behavior
• Local and remote sources with aligned usage patterns
• URL sync helpers via query param encode/decode
• Selector subscriptions via utility (subscribeSelector)

Feature	Sourceit	TanStack Query	SWR
Bundle size	0.5 KB	~16 kB	~6 kB
Local in-memory source primitive	✅	❌	❌
Remote source primitive	✅	✅	✅
Typed page/filter/sort/search model	✅	Partial	Partial
Shared local + remote API shape	✅	❌	❌
URL query encode/decode helpers	✅	Partial	Partial
Framework agnostic	✅	✅	⚠️ (React-first)
Zero dependencies	✅	❌	❌

Use Sourceit when you want one typed source abstraction for both local collections and server-backed lists.

Consider query-focused libraries when your app only needs remote fetching and cache synchronization.

Features

• Typed local and remote source contracts with a shared API shape
• Deterministic pagination, search, sort, and filter state transitions
• Snapshot/meta/current read model for predictable rendering
• Batch updates for grouped source state changes
• URL query encode/decode helpers for route synchronization
• Selector subscriptions via subscribeSelector
• Zero dependencies

Compatibility

Environment	Support
Browser	✅
Node.js	✅
SSR	✅

Documentation

• Usage Guide
• API Reference
• Examples

See Also

• Stateit
• Toolkit
• Routeit