Skip to content
sourcerer logoSourcererData
Framework-agnostic collection pagination and observable single-value resources.
Version
v26.11.20
Size
2.5 KB gzip
BrowserNode ≥22SSRDeno
createLocalSourcecreatePageSourcecreateCursorSourcecreateInfiniteSourcecreateResource

Why Sourcerer? ​

Paginated views need collection data, loading state, errors, parameters, and navigation to change coherently. Sourcerer owns that state and request succession without coupling it to a framework or transport client.

ts
// Before
let items = [];
let loading = false;
let page = 1;

// After
const source = createPageSource({
  load: async ({ page, pageSize }) => ({ items: await loadUsers(page, pageSize), totalItems: 100 }),
});
source.subscribe((state) => render(state));
FeatureSourcererManual storeGeneral query cache
Bundle size2.5 KBApplication-definedPackage-defined
Zero runtime dependencies
Page, cursor, and infinite navigationApplication-definedApplication-defined
Framework-neutral subscriptionsApplication-defined
HTTP transport policyLoader-definedApplication-definedLoader-defined

Use Sourcerer when a collection view needs explicit pagination, observable state, cancellation, and lifecycle ownership.

Consider a general query cache when your primary requirement is shared keyed caching, invalidation, mutations, or server-state normalization rather than collection navigation.

Installation ​

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

Quick Start ​

Create a page source, load it, read its state, and dispose it with its owner.

ts
import { createPageSource } from '@vielzeug/sourcerer';

type User = { id: number; name: string };
const users: User[] = [
  { id: 1, name: 'Ada' },
  { id: 2, name: 'Grace' },
];
const source = createPageSource({
  load: async ({ page, pageSize }) => {
    const start = (page - 1) * pageSize;
    return { items: users.slice(start, start + pageSize), totalItems: users.length };
  },
  pageSize: 1,
});

try {
  await source.reload();
  console.log(source.state.items);
} catch (error) {
  console.error(error);
} finally {
  source.dispose();
}

Features ​

  • createLocalSource(): filters and paginates an in-memory collection synchronously
  • createPageSource(): loads numbered pages and exposes direct navigation commands
  • createCursorSource(): follows opaque cursors returned by the loader
  • createInfiniteSource(): appends pages while preserving loaded items
  • createResource(): starts loading one value immediately, or awaits reload() with start: false
  • setParams(): replaces consumer-owned loader parameters and resets pagination
  • PageSource.apply(): reconciles page and structurally compared params in at most one request
  • subscribe(): publishes complete immutable state replacements

Documentation ​

See Also ​

  • Courier: provide HTTP transport, middleware, and structured transport errors inside loaders
  • Scout: index larger in-memory collections before passing matches to a local source
  • Ripple: project source state into reactive computations
  • Wayfinder: validate and synchronize source parameters with route state