Introduction

Welcome

Have you ever struggled with managing cache keys in your application? String inconsistencies, verbose key construction, or manually building complex nested keys like ['users', 'list', { page: 1, filter: 'active' }] for every query?

@ibnlanre/builder solves this problem by letting you define your keys once in a structured way, then access them with full TypeScript autocomplete and type-safety.

The Problem

Here's a typical scenario when working with data fetching libraries:

// ❌ Without builder: Error-prone and repetitive
useQuery({ queryKey: ['users', 'detail', userId], ... }); // Manual string construction
 
useQuery({ queryKey: ['user', 'detail', userId], ... });  // Oops! Singular/plural mismatch
 
// Different developers might format keys differently
useQuery({ queryKey: ['userDetail', userId], ... });      // Inconsistent structure

The Solution

With @ibnlanre/builder, you define your key structure once:

// ✅ With builder: Type-safe and consistent
const api = createBuilder({
  users: {
    list: (params: { page: number }) => fetchUsers(params),
    detail: (id: number) => fetchUser(id)
  }
});
 
// Now use it anywhere with autocomplete
useQuery({
  queryKey: api.users.detail.$use(userId),  // ['users', 'detail', 123]
  queryFn: () => api.$use.users.detail(userId)
});

Benefits you get immediately:

  • ✨ Autocomplete - Your editor suggests available keys
  • 🛡️ Type-safe - Wrong parameters? TypeScript catches it
  • 🎯 Single source of truth - Change key structure in one place
  • 📦 Tiny - 0.4KB (opens in a new tab) gzipped

What is Builder?

The @ibnlanre/builder package is a lightweight tool that transforms a nested object (called a "register") into a smart builder object. This builder lets you:

  1. Generate keys dynamically with the $use or $get methods
  2. Access your functions and values through the $use property
  3. Keep everything organized in one central location

It's framework-agnostic (opens in a new tab). It works with React (opens in a new tab), Vue (opens in a new tab), Svelte (opens in a new tab), or vanilla JavaScript (opens in a new tab)/TypeScript (opens in a new tab).

I like builder. It is really nice! It's lightweight and robust.
Builder is 0.4KB (opens in a new tab) gzipped. That's very very light!
- Hemense Lan (opens in a new tab)

Why Builder?

Originally built to manage keys for TanStack Query (opens in a new tab) (formerly React Query), Builder proved useful for any scenario involving key-based data structures:

  • Cache keys (SWR, TanStack Query, Apollo)
  • Route parameters (React Router, Next.js)
  • Form field names (React Hook Form, Formik)
  • Localization keys (i18next, react-intl)
  • Storage keys (localStorage, IndexedDB)

By encapsulating keys and values together, you get better organization, easier refactoring, and type-safe access throughout your codebase.

Builder has made sooo much sense, not just for its housekeeping, but for its simplicity of use, as well as, efficiency. Honestly can't have it any other way.
- Prosper Jaja (opens in a new tab)

Next Steps

Ready to get started? Check out the installation guide or jump straight to basic usage to see Builder in action.

Installation