React
Each recipe below is one useOIMSelector call. It reads the database the provider holds and re-renders the
component when something it read changes. The recipes cover:
- providing the database;
- one entity by key;
- one field of a wide entity;
- a list whose rows re-render one at a time;
- a group an index keeps;
- a group sorted by a column;
- a derived value;
- delivering once per painted frame.
Setup shared by the examples on this page
import { memo, useMemo } from 'react';
import type { ReactNode } from 'react';
import {
OIMDB, createOIMColumnGroup, createOIMEntitySlotCollectionStoreAggregate, createOIMSingleComputedService,
createOIMSlotCollectionIndexStoreAggregate, createOIMSortedComputedService, isOIMSameValueZero,
} from '@oimdb/core';
import type { TOIMStoreKey } from '@oimdb/core';
import { OIMDBProvider, useOIMSelector } from '@oimdb/react';
type Card = { id: string; deckId: string; title: string; rank: number };
type User = { id: string; name: string; avatarUrl: string; bio: string };
const createAppDB = () => new OIMDB({
channelScheduler: (flush) => { void Promise.resolve().then(flush); },
createSchemas: (db) => {
const cards = createOIMEntitySlotCollectionStoreAggregate<Card>(db);
const users = createOIMEntitySlotCollectionStoreAggregate<User>(db);
const cardsByDeck = createOIMSlotCollectionIndexStoreAggregate(cards, { selectKey: (card: Card) => card.deckId });
return { default: { cards, users, cardsByDeck } };
},
});
const db = createAppDB();
const useAppSelector = useOIMSelector.withTypes<typeof db>();
Give every hook the database
Take: OIMDBProvider once at the root, and useOIMSelector.withTypes<typeof db>() once in a module. Do not
pass aggregates down as props: the selector already receives the database, and its schemas are typed.
function App({ children }: { children: ReactNode }) {
return <OIMDBProvider db={db}>{children}</OIMDBProvider>;
}
Why this way: the provider carries the database and nothing else. withTypes is the same hook typed with
your database, so appDb.schemas.default.cards needs no cast. A test renders the same component under a provider
holding a fresh database.
Reference: React.
Render one entity by its key
Take: useAppSelector(appDb => appDb.schemas.default.cards.getSlotByKey(id).entity).
function CardTitle({ cardId }: { cardId: string }) {
const card = useAppSelector((appDb) => appDb.schemas.default.cards.getSlotByKey(cardId).entity);
return <span>{card?.title ?? 'loading'}</span>;
}
Why this way:
getSlotByKeyhands back the one slot that key names, empty until its entity arrives.- Reading
.entitysubscribes to that slot and nothing else, and the subscription holds it while the component is mounted. - An in-place write keeps the entity's object reference, and the component still re-renders: what moved is the source, not the result.
Reference: Reading and subscribing.
Render one field of a wide entity
Take: a column group made once in a module, and slot.getEntity(group) in the selector. Do not use plain
.entity: it wakes on every column.
const AVATAR = createOIMColumnGroup<keyof User & string>(['avatarUrl']);
function Avatar({ userId }: { userId: string }) {
const avatarUrl = useAppSelector((appDb) => appDb.schemas.default.users.getSlotByKey(userId).getEntity(AVATAR)?.avatarUrl);
return <img src={avatarUrl} alt="" />;
}
Why this way: a write to bio or name does not wake the component, and neither does any column outside the
group. Make the group once, outside the component: a group is a value the engine compares by identity.
Reference: Column slots.
Render a list where each item re-renders alone
Take: the list selects keys, and each memo row selects its own entity by key.
const DeckRow = memo(function DeckRow({ cardId }: { cardId: TOIMStoreKey }) {
const card = useAppSelector((appDb) => appDb.schemas.default.cards.getSlotByKey(String(cardId)).entity);
return <li>{card?.title}</li>;
});
function Deck({ deckId }: { deckId: string }) {
const cardIds = useAppSelector((appDb) =>
Array.from(appDb.schemas.default.cardsByDeck.getSlotByKey(deckId).getBucketMemberSlots(), (member) => member.key));
return <ul>{cardIds.map((cardId) => <DeckRow key={String(cardId)} cardId={cardId} />)}</ul>;
}
Why this way:
- The list reads only the bucket's membership, so a title write does not re-render it.
- A row reads only its own entity, so a write reaches exactly one row.
- The rows take a primitive key, so
memokeeps every row the list did not change.
Reference: Index.
Render the group an index keeps
Take: cardsByDeck.getSlotByKey(deckId) inside the selector, and read the members there.
function DeckSize({ deckId }: { deckId: string }) {
const size = useAppSelector((appDb) => appDb.schemas.default.cardsByDeck.getSlotByKey(deckId).getBucketMemberSlotCount());
return <span>{size} cards</span>;
}
Why this way: an index files every entity under the key it derives from it. A deck nobody wrote yet is an empty bucket that fills when its first card is written, and the selector holds that bucket while it is mounted.
Reference: Index.
Render a group sorted by a column
Take: createOIMSortedComputedService({ indexService, sortColumns }) and its
createSortedStoreSlot(indexStoreSlot), built once in a module. In the component, read the sorted slots by key
through .value. Do not sort inside the render: it would re-sort on every render and still not re-render when a
rank changes.
const cardsByRankService = createOIMSortedComputedService({
indexService: db.schemas.default.cardsByDeck.slotService,
sortColumns: [{ columnName: 'rank', direction: 'asc' }],
});
const cardsByRank = cardsByRankService.createSortedStoreSlot(db.schemas.default.cardsByDeck.storeSlot);
const RankedRow = memo(function RankedRow({ cardId }: { cardId: TOIMStoreKey }) {
return <li>{useAppSelector((appDb) => appDb.schemas.default.cards.getSlotByKey(String(cardId)).entity?.title)}</li>;
});
function RankedDeck({ deckId }: { deckId: string }) {
const cardIds = useAppSelector(() => cardsByRankService.getSlotByKey(cardsByRank, deckId).value.map((slot) => slot.key));
return <ol>{cardIds.map((cardId) => <RankedRow key={String(cardId)} cardId={cardId} />)}</ol>;
}
Why this way: each sorted derivation re-sorts only when membership changes, or when a write changes a sort column on a member. A title write leaves the order alone and reaches one row. The selector's subscription holds the derivation while the component is mounted.
Reference: The order of a bucket is a derivation.
Show a derived value
Take: the selector itself, when one component derives the value. When several components share it, use a
single computed with a sameValueGuard, built once in a module and read through .value.
function DeckCount({ deckId }: { deckId: string }) {
const count = useAppSelector((appDb) => appDb.schemas.default.cardsByDeck.getSlotByKey(deckId).getBucketMemberSlotCount());
return <span>{count}</span>;
}
const heartsCountService = createOIMSingleComputedService<number>({ sameValueGuard: isOIMSameValueZero });
const hearts = db.schemas.default.cardsByDeck.getSlotByKey('hearts');
const heartsCount = heartsCountService.createStoreSlot(db, () => hearts.getBucketMemberSlotCount(), () => ({ sourceSlots: [hearts] }));
function HeartsBadge() {
const count = useAppSelector(() => heartsCountService.getSingleSlot(heartsCount).value);
return <span>{count} hearts</span>;
}
function OwnComputed({ deckId }: { deckId: string }) {
const own = useMemo(() => {
const bucket = db.schemas.default.cardsByDeck.getSlotByKey(deckId);
return heartsCountService.createStoreSlot(db, () => bucket.getBucketMemberSlotCount(), () => ({ sourceSlots: [bucket] }));
}, [deckId]);
return <span>{useAppSelector(() => heartsCountService.getSingleSlot(own).value)}</span>;
}
Why this way: a computed whose sameValueGuard calls the new value equal to the old keeps its stamp. So a frame
in which one card leaves hearts and another arrives renders nothing. The selector subscribes to the computed, which
holds it while mounted; a computed a component builds in useMemo lives exactly that long.
Reference: One derivation, no key.
Deliver once per painted frame
Take: the channelScheduler option of OIMDB, with a requestAnimationFrame deferral. Do not use a database
with no scheduler: nothing is delivered until somebody calls flush(), so a write from an event handler would
never reach a component.
const paintedDb = new OIMDB({
channelScheduler: (flush) => { requestAnimationFrame(() => { flush(); }); },
createSchemas: (database) => ({ default: { cards: createOIMEntitySlotCollectionStoreAggregate<Card>(database) } }),
});
function RenameButton({ cardId }: { cardId: string }) {
return <button onClick={() => {
paintedDb.schemas.default.cards.getSlotByKey(cardId).updateEntity({ title: 'Renamed' });
}}>Rename</button>;
}
Why this way:
- The scheduler is called with the flush when the first write of a batch needs a frame, and not again until that frame has run. So everything written before the next paint is one frame, and every component it wakes is told once.
- A microtask deferral,
Promise.resolve().then(flush), makes one synchronous turn of the event loop the batch instead. - The choice is made once, at construction, and no write asks which one it is on.
Reference: Schedulers, React.