use-entity

Fast, typed entity state for React with minimal boilerplate. It gives you consistent CRUD operations for normalized collections, plus a ready-to-use hook and selector helpers that stay portable across state managers. Powered by Redux Toolkit's createEntityAdapter.

Why it’s useful:

• useState-like API for collections with CRUD actions.
• CRUD-first API for collections (add, update, remove, upsert) with strong typing.
• TanStack Store integration (see docs).
• Normalized data with built-in selectors (all, ids, entities, byId, total).

Install

npm install use-entity

Quick Start (React useState)

import { useStateEntity } from "use-entity";

type User = { id: string; name: string; age: number };

export function Users() {
    const [users, actions] = useStateEntity<User>();

    const addUser = () =>
        actions.addOne({ id: String(Date.now()), name: `User ${users.length + 1}`, age: 20 });

    const birthday = (user: User) =>
        actions.updateOne({ id: user.id, changes: { age: user.age + 1 } });
    
    return (
        <div>
            <button onClick={addUser}>Add user</button>
            <ul>
                {users.map((user) => (
                    <li key={user.id}>
                        <span>
                            {user.name} ({user.age})
                        </span>
                        <button onClick={() => birthday(user)}>+1 age</button>
                        <button onClick={() => actions.removeOne(user.id)}>Remove</button>
                    </li>
                ))}
            </ul>
        </div>
    );
}

Actions

All actions mirror Redux Toolkit's entity adapter API (docs):

addOne, addMany,
setOne, setMany, setAll,
removeOne, removeMany, removeAll,
updateOne, updateMany,
upsertOne, upsertMany

Selectors

useEntity() and useStateEntity() default to the "all" selector, which returns the array of items. You can opt into other selectors (including the full selector object) and access byId. (Based on rtk docs)

Selector options:

all: T[];
ids: string[];
entities: Record<string, T>;
total: number;
full: {
  all: T[];
  ids: string[];
  entities: Record<string, T>;
  total: number;
  byId: (id: string) => T | undefined;
};

Usage:

const [all] = useStateEntity<User>([], "all");
const [ids] = useStateEntity<User>([], "ids");
const [entities] = useStateEntity<User>([], "entities");
const [total] = useStateEntity<User>([], "total");
const [full] = useStateEntity<User>([], "full");

const user2 = full.byId("2");

Notes

• T must include id: string (number as id is not yet supported).

Releases

This repo uses Changesets.

1. For any user-facing package change, run bun run changeset and commit the generated file in .changeset/.
2. When changesets reach main, GitHub Actions opens or updates a release PR with the version bump and generated CHANGELOG.md.
3. Merge the release PR to publish.