@vielzeug/sourcerer

Typed reactive data sources for pagination, filtering, sorting, search, and infinite scroll.

@vielzeug/sourcerer is part of Vielzeug and ships as a TypeScript package with ESM+CJS output.

Installation

pnpm add @vielzeug/sourcerer
npm install @vielzeug/sourcerer
yarn add @vielzeug/sourcerer

Quick Start

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

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

await source.search('a', { immediate: true });
console.log(source.current); // [{ id: 1, name: 'Ada' }]
console.log(source.meta.pageNumber); // 1

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

const source = createRemoteSource({
  fetch: async ({ limit, page, search }, signal) => {
    const res = await fetch(`/api/users?page=${page}&limit=${limit}&q=${search ?? ''}`, { signal });
    return res.json(); // { items: User[], total: number }
  },
  limit: 20,
});

// autoFetch is true by default — initial data loads immediately
await source.ready();
console.log(source.current, source.meta.totalItems);

Sources Overview

| Factory | Data model | Navigation | | ------------------------ | ------------------ | ------------------------- | | createLocalSource() | In-memory array | Page number | | createRemoteSource() | Async server fetch | Page number | | createCursorSource() | Async server fetch | Cursor tokens (next/prev) | | createInfiniteSource() | Async server fetch | Append (load more) |

Error Handling

All async sources expose meta.error as a typed SourceError | null — not a plain string. SourceError extends Error and carries structured context:

import { sourceState } from '@vielzeug/sourcerer';

const state = sourceState(source);
if (state.status === 'error') {
  console.error(state.error.message); // human-readable message
  console.error(state.error.cause); // original thrown value
  console.error(state.error.context); // structured context bag (query fields, kind, etc.)
}

Documentation

• Overview
• Usage Guide
• API Reference
• Examples

License

MIT © Helmuth Saatkamp — part of the Vielzeug monorepo.