@nimir/referencesResolve nested references, type-safely

Declare which fields are IDs, get fully resolved objects back. Batched, deduplicated, cached.

Why this exists

Get Started

⚡

Batching & dedup

All fetches for the same source are batched into one call. Duplicate IDs across the tree are fetched once.

🔒

Type inference

Resolved fields are inferred automatically. Single IDs get a T suffix, arrays get Ts. No manual typing needed.

🌳

Nested resolution

Resolve up to 10 levels deep. Chain through assignee to team to lead — one declaration, all resolved.

💾

Pluggable caching

In-memory, IndexedDB, or Redis. TTL, cache warming, and negative caching built in.

⚛️

React hooks

Wrap any data-fetching hook or resolve inline data reactively. Works with TanStack Query and custom hooks.

🛡️

Null-safe

null or undefined IDs resolve to null. Missing entities resolve to null. No crashes.

Before

const ticket = await fetchTicket('t-1');

const assignee = ticket.assigneeId ? await fetchUser(ticket.assigneeId) : null;

const watchers = await Promise.all(ticket.watcherIds.map(id => (id ? fetchUser(id) : null)));
// 3 network calls, no batching, no types, repeat per field...

After

const refs = defineReferences(c => ({
  User: c.source<User>({ batch: ids => fetchUsers(ids) }),
}));

const result = await refs.inline(ticket, {
  fields: { assigneeId: 'User', watcherIds: 'User' },
});

result.assigneeIdT; // User | null
result.watcherIdTs; // (User | null)[]
// 1 network call, all IDs batched, fully typed

AI / LLM integration — Machine-readable docs available at llms.txt and ship with the npm package.