Skip to main content

Lists

Every list in OIMDB is a bucket: a slot whose content is other slots. This page covers these list tasks: grouping by a field, a sorted group, a whole entity store slot as one list, a filtered list, a page or an infinite list in server order, search results, a selection, drag-and-drop reordering, a count or a sum per group, and minting several groups in one call.

Setup shared by the examples on this page
import { OIMDB, OIMEffectService, createOIMSortedCollectionSingleSlotStoreAggregate, OIMSetBucketContentService, OIMSlotAtUnholdReleasePolicy, createOIMBucketMemoComputedService, createOIMComputedService, createOIMSortedComputedService, createOIMSlotCollectionIndexService, isOIMSameValueZero, type TOIMBucketSlotsSetStore, type TOIMEntitySlot, type TOIMOrderedListCommand, type TOIMStoreKey, createOIMEntityContentService, createOIMSlotCollectionService, OIMPositionalArrayBucketContentService, OIMBucketCommands, createOIMSingleSlotService, OIMSlotCollectionBucketService, getOIMBucketMemberSlotEntities } from '@oimdb/core';

type Card = {
id: string;
deck: string;
title: string;
rank: number;
points: number;
archived: boolean;
};

declare function render(value?: unknown): void;
declare function rebuildFrom(slots: Iterable<TOIMEntitySlot<Card>>): void;
declare function applyToTheRenderedList(commands: readonly TOIMOrderedListCommand[]): void;

const db = new OIMDB();
const effectService = OIMEffectService.INSTANCE;
const cardService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService<Card>() });
const cards = cardService.createStoreSlot(db);
const cardContentService = cardService.slotContentService;

function createSetBucketService() {
return createOIMSlotCollectionService({ slotContentService: new OIMSetBucketContentService<TOIMEntitySlot<Card>>() });
}

Group entities by a field​

Take: createOIMSlotCollectionIndexService with a selectKey that returns the field, and its createIndexStoreSlot(cards) for the index store slot. Its buckets keep arrival order and read by position; pass slotContentService: new OIMSetBucketContentService() when you need neither. Do not take a manual bucket collection here: it never looks at the entity, so it cannot follow a card that moves to another deck.

const cardsByDeckService = createOIMSlotCollectionIndexService({
entityService: cardService,
selectKey: (card: Card) => card.deck,
});
const cardsByDeck = cardsByDeckService.createIndexStoreSlot(cards);

const red = cardsByDeckService.holdSlotByKey(cardsByDeck, 'red');
const onRed = effectService.createAndRunEffect(db, () => {
for (const cardSlot of red.getBucketMemberSlots()) render(cardSlot.entity);
}, [red]);

const ace = cardService.writeSlotContentByKey(cards, 'c1', { id: 'c1', deck: 'red', title: 'Ace', rank: 1, points: 11, archived: false });
ace.updateEntity({ deck: 'blue' });
db.flush();

effectService.disposeEffect(onRed);
red.unholdSlot();

Why this way: an index is pushed to. Every write to cards reaches it through the store slot's content-change listener, and per entity it does one selectKey and one read of the key it filed the entity under before. Only when the two differ does it edit buckets, so the cost of a write does not depend on how many cards or decks exist. The bucket slot is written on membership changes only: a title edit on a red card wakes that card's own subscribers and not the list. The set-driven content service makes membership tests and removals a hash lookup. The array-driven one keeps the order cards arrived in, and is the only one with getBucketMemberSlotAt and getBucketMemberSlotPosition: a set has no positions to read. Left without a policy, an unheld bucket stays while it has members (OIMSlotAtEmptyReleasePolicy).

Reference: Indexes, How a bucket holds its slots, Why an index looks like this.

A sorted list per group​

Take: createOIMSortedComputedService over an index service, with sortColumns naming the columns the order depends on, and its createSortedStoreSlot(indexStoreSlot). Add comparator when the order is not a plain column comparison. Do not sort inside an effect on the bucket: it re-sorts on every wake, including the ones where no sort column moved.

const cardsByDeckService = createOIMSlotCollectionIndexService({
entityService: cardService,
selectKey: (card: Card) => card.deck,
});
const cardsByDeck = cardsByDeckService.createIndexStoreSlot(cards);

const byRankService = createOIMSortedComputedService({
indexService: cardsByDeckService,
sortColumns: [{ columnName: 'rank', direction: 'asc' }],
});
const byRank = byRankService.createSortedStoreSlot(cardsByDeck);

const byTitleService = createOIMSortedComputedService({
indexService: cardsByDeckService,
sortColumns: [{ columnName: 'title', direction: 'asc' }],
comparator: (left: Card, right: Card) => left.title.localeCompare(right.title),
});
const byTitle = byTitleService.createSortedStoreSlot(cardsByDeck);

const redByRank = byRankService.holdSlotByKey(byRank, 'red');
effectService.createAndRunEffect(db, () => render(redByRank.value), [], [redByRank]);

const redByTitle = byTitleService.getSlotByKey(byTitle, 'red');
redByTitle.value;

Why this way: an index files membership when the write happens, and the sorted view derives the order when it is read. The sorted computed's sources are the bucket slot of the key plus one bucket column slot per named column, so it derives again only when a card joined or left the deck or a write changed rank on a member; a title edit moves none of its sources. sortColumns says when to sort and comparator says how. Given a comparator alone, the engine cannot see which columns it reads, so its sources become the bucket slot and the bucket's any-column slot (getAnyBucketColumnSlotByKey, which wakes on member content and on a join or leave) and any write to a member re-sorts. A re-sort that yields the same sequence keeps the previous array, so a consumer comparing by identity sees no change. Read the value through slot.value: outside an effect body the slot's own value field is whatever the last read left there.

Reference: Ordering, The order of a bucket is a derivation.

A list that is a whole entity store slot​

Take: the collection's list, OIMSlotCollectionBucketService.INSTANCE.holdBucketSlot(cards). Do not iterate the entity store slot's getSlots for a list: nothing tells you when that iteration would read differently, and it can include slots that were minted by a read and hold no entity.

const all = OIMSlotCollectionBucketService.INSTANCE.holdBucketSlot(cards);
effectService.createAndRunEffect(db, () => render(getOIMBucketMemberSlotEntities(all.getBucketMemberSlots())), [all]);

Why this way: the list has every slot that holds an entity, in no strict order (sort it for one; see Reading the whole population); a slot joins it when its entity arrives and leaves when its entity is gone. It is built on the first call and kept in step while it is held, so it is the thing to subscribe to for "a card arrived or left". With createOIMEntitySlotCollectionStoreAggregate the same is getEntities() / getEntityCount() on the aggregate.

For the whole store slot sorted, take createOIMSortedCollectionSingleSlotStoreAggregate: it sorts the collection's list with no index, and its single slot's value is every entity slot in order.

const allByRank = createOIMSortedCollectionSingleSlotStoreAggregate(cardService.createStoreAggregate(cards), {
sortColumns: [{ columnName: 'rank', direction: 'desc' }],
});
allByRank.getSingleSlot().value;

It re-sorts when a card arrives or leaves or its rank is written, and a write to another column does not wake its reader. While nobody reads it, the collection pays nothing for it.

Reference: Reading the whole population, Indexes, The order of a bucket is a derivation.

A filtered list​

Take: an index whose selectKey returns the filter's value, and hold only the bucket of the value you show. For several criteria, return one composite key. Do not write the filter as a computed that scans the store slot: a computed learns that something changed, never what, so it would rescan every card on every write.

const cardsByStatusService = createOIMSlotCollectionIndexService({
entityService: cardService,
selectKey: (card: Card) => (card.archived ? 'archived' : 'active'),
});
const cardsByStatus = cardsByStatusService.createIndexStoreSlot(cards);
const active = cardsByStatusService.holdSlotByKey(cardsByStatus, 'active');
effectService.createAndRunEffect(db, () => render(cardsByStatusService.getEntitiesByKey(cardsByStatus, 'active')), [active]);

const cardsByDeckAndStatusService = createOIMSlotCollectionIndexService({
entityService: cardService,
selectKey: (card: Card) => `${card.deck}:${card.archived ? 'archived' : 'active'}`,
});
const cardsByDeckAndStatus = cardsByDeckAndStatusService.createIndexStoreSlot(cards);
const activeRedByRankService = createOIMSortedComputedService({
indexService: cardsByDeckAndStatusService,
sortColumns: [{ columnName: 'rank', direction: 'asc' }],
});
const activeRedByRank = activeRedByRankService.createSortedStoreSlot(cardsByDeckAndStatus);
const activeRed = activeRedByRankService.getSlotByKey(activeRedByRank, 'red:active');
activeRed.value;

Why this way: a key whose bucket was never minted is not maintained at all. An archived card costs one selectKey, one comparison and, when its key changed, one write of its index-key cell; no bucket is touched because nobody asked for the archived bucket. Flipping archived on a card moves it out of the active bucket in O(1), since the card's slot remembers the key it was filed under. getEntitiesByKey copies the entities into a fresh array, which suits a small list; for a long one, iterate getBucketMemberSlots and subscribe each item to its own slot.

Reference: What a write costs, and how long a bucket lives, So membership cannot be a computed.

A page or an infinite list in server order​

Take: a manual, array-driven bucket collection, createOIMSlotCollectionService(), and one store slot of it: the server decides which cards are on the list and in what order, and the bucket keeps the sequence it is handed. writeSlotContent for the first page or a refresh, addBucketMemberSlots for the next page. Do not take an index: no column of a card can say "the server did not return this one", and do not take a set-driven bucket: on a rewrite it keeps the old order of the survivors.

declare function fetchCardPage(cursor: string | undefined): Promise<{ cards: Card[]; nextCursor: string | undefined }>;

const feedService = createOIMSlotCollectionService({ slotContentService: new OIMPositionalArrayBucketContentService<TOIMEntitySlot<Card>>({ bucketCommands: new OIMBucketCommands({ maxCommandsPerSlot: undefined }) }) });
const feed = feedService.createStoreSlot(db);
const inbox = feedService.holdSlotByKey(feed, 'inbox');
let nextCursor: string | undefined;

async function loadFirstPage(): Promise<void> {
const page = await fetchCardPage(undefined);
inbox.writeSlotContent(cardService.writeInBatch(cards, () => (page.cards).map(entity => cardService.writeSlotContentByKey(cards, entity.id, entity))));
nextCursor = page.nextCursor;
}

async function loadNextPage(): Promise<void> {
const page = await fetchCardPage(nextCursor);
inbox.addBucketMemberSlots(cardService.writeInBatch(cards, () => (page.cards).map(entity => cardService.writeSlotContentByKey(cards, entity.id, entity))));
nextCursor = page.nextCursor;
}

const feedOrderService = createOIMBucketMemoComputedService({
bucketCollectionService: feedService,
});
const feedOrder = feedOrderService.createBucketMemoStoreSlot(feed);
const inboxOrder = feedOrderService.holdSlotByKey(feedOrder, 'inbox');
effectService.createAndRunEffect(db, () => render(inboxOrder.value), [], [inboxOrder]);

Why this way: the writeSlotContentByKey loop hands back the slots it wrote, in the order of the response, so the list is built from identities without a second lookup by id. writeSlotContent is for a caller holding the whole answer: it works out arrivals and departures, and an unchanged list wakes nobody. addBucketMemberSlots is for a caller holding the delta: the standing slots are not touched and its cost is the page, not the list; the default content service of createOIMSlotCollectionService records each arrival as an insert at the end, which a renderer can append without rebuilding. The default array-driven content service records one entry per mention, so a card sent on two overlapping pages appears twice; take OIMBucketUniqueMemberSlotsArrayService when pages can overlap, and a repeated add is refused. createOIMBucketMemoComputedService with its createBucketMemoStoreSlot(bucketStoreSlot) turns the bucket into an array that keeps its identity while the list does not change.

Reference: A bucket's slots are the caller's, Writing the whole answer or the delta, The order of a bucket is a derivation.

Search results, or one ad-hoc list​

Take: a manual bucket store slot with one bucket under a constant key, rewritten with writeSlotContent on every search; the default array-driven one keeps the ranking the server returned. When the list has no address at all, a single bucket, createOIMSingleSlotService() and the store slot from its createStoreSlot(db), makes a bucket under no key. The store slot mints nothing; its one bucket slot is minted and read through getSingleSlot(storeSlot) or holdSingleSlot(storeSlot), written with the content service's writeSlotContent, and subscribed to through that slot. It is released like any bucket once it is empty and nothing holds it, and the next getSingleSlot mints a fresh one. Do not keep the result as a plain array of entities: nothing can subscribe to it, and it goes stale when one of the cards in it is edited.

declare function searchCardIds(query: string): Promise<readonly string[]>;

const searchService = createOIMSingleSlotService({ slotContentService: new OIMPositionalArrayBucketContentService<TOIMEntitySlot<Card>>({ bucketCommands: new OIMBucketCommands({ maxCommandsPerSlot: undefined }) }) });
const search = searchService.createStoreSlot(db);
const results = searchService.holdSingleSlot(search);

async function runSearch(query: string): Promise<void> {
const ids = await searchCardIds(query);
results.writeSlotContent(ids.map((id) => cardService.getSlotByKey(cards, id)));
}

function closeSearch(): void {
results.clearSlotContent();
results.unholdSlot();
}

effectService.createAndRunEffect(db, () => rebuildFrom(results.getBucketMemberSlots()), [results]);

Why this way: a search result is a fact about the response, not about the entities, so the caller states it and the engine does not guess. getSlotByKey hands back a slot even for a card that has not been loaded yet; the bucket holds that slot, and an item subscribed to it renders once the card's entity is written into that same identity. Every member of a bucket is held, so clearSlotContent is what gives those holds back when the search closes. The array-driven content service compares the sequence: the same ids in the same order change nothing, and a reordered result is drained and re-added whole.

Reference: A bucket's slots are the caller's, A single bucket.

A selection set​

Take: a set-driven bucket collection, one bucket per screen that selects. Toggle with addBucketMemberSlot and removeBucketMemberSlot, ask with hasBucketMemberSlot. Do not take an array-driven bucket: a selection has no order, and its membership test scans the list.

const selectionService = createSetBucketService();
const selections = selectionService.createStoreSlot(db);
const selected = selectionService.holdSlotByKey(selections, 'board');
const selection = selectionService.slotContentService;

function toggleSelected(cardId: string): void {
const cardSlot = cardService.getSlotByKey(cards, cardId);
if (selection.hasBucketMemberSlot(selected, cardSlot)) selection.removeBucketMemberSlot(selected, cardSlot);
else selection.addBucketMemberSlot(selected, cardSlot);
}

effectService.createAndRunEffect(db, () => render(selection.getBucketMemberSlotCount(selected)), [selected]);

toggleSelected('c1');
toggleSelected('c2');
selection.clearSlotContent(selected);

Why this way: the set-driven content service makes a membership test and a removal a hash lookup, and adding a slot that is already there changes nothing and wakes nobody. The selection holds the card slots, not copies of the cards, so an edit to a selected card is seen through its own slot and does not touch the selection. Bulk selection is one call: addBucketMemberSlots with every slot, or writeSlotContent with the full set.

Reference: Writing a bucket's slots, How a bucket holds its slots.

Reorder by drag and drop​

Take: createOIMSlotCollectionService(): an array-driven bucket collection whose positions are the caller's, built with a recorder of what each frame's writes did (a frame is the delivery of every write since the previous one; see the glossary). Use the position writes: moveBucketMemberSlotToPosition inside one list, removeBucketMemberSlotAt and insertBucketMemberSlotAt between two. Do not take a sorted computed with a rank column for an order the user decides: the order would then be a column you compute and write on every drop.

const boardService = createOIMSlotCollectionService({ slotContentService: new OIMPositionalArrayBucketContentService<TOIMEntitySlot<Card>>({ bucketCommands: new OIMBucketCommands({ maxCommandsPerSlot: undefined }) }) });
const board = boardService.createStoreSlot(db);
const boardContentService = boardService.slotContentService;
const todo = boardService.holdSlotByKey(board, 'todo');
const done = boardService.holdSlotByKey(board, 'done');

todo.writeSlotContent(cardService.writeInBatch(cards, () => ([
{ id: 'c1', deck: 'todo', title: 'Write', rank: 0, points: 3, archived: false },
{ id: 'c2', deck: 'todo', title: 'Review', rank: 0, points: 1, archived: false },
]).map(entity => cardService.writeSlotContentByKey(cards, entity.id, entity))));

rebuildFrom(todo.getBucketMemberSlots());
const onTodo = effectService.createEffect(db, () => {
if (todo.isWholeListRecorded) rebuildFrom(todo.getBucketMemberSlots());
else applyToTheRenderedList(todo.commands ?? []);
}, [todo]);

boardContentService.moveBucketMemberSlotToPosition(todo, 1, 0);

const dragged = boardContentService.removeBucketMemberSlotAt(todo, 0);
if (dragged !== undefined) boardContentService.insertBucketMemberSlotAt(done, 0, dragged);
db.flush();

effectService.disposeEffect(onTodo);

Why this way: a drag handle reports positions, and the position writes take them as they are: nothing re-decides the order on a read. The recorder writes onto the bucket slot the commands this frame's writes did (insert, remove, move), so a renderer moves the existing nodes instead of rebuilding them, and focus, scroll anchors and animations stay attached. Read commands and isWholeListRecorded inside the effect body: they are reset once the flush has ended. isWholeListRecorded is set by a write of the whole list (writeSlotContent, clearSlotContent) and when the script outgrows the list it describes; a renderer that animates every move passes maxCommandsPerSlot: Infinity to the factory and always gets the script. If the card's column is also stored on the entity, write it as well; the bucket does not.

Reference: Positions the caller decides, The commands, on the bucket slot.

A count or a sum per group​

Take: createOIMComputedService keyed by the group, whose sources are the index bucket of that key, plus the bucket column slot of the summed column for a sum, and one createStoreSlot(db) of it. Read it through the slot's value service, slot.value. Do not keep a counter of your own updated in an effect: an effect's result has no slot, so nothing else in the graph can name it as a source.

const cardsByDeckService = createOIMSlotCollectionIndexService({
entityService: cardService,
selectKey: (card: Card) => card.deck,
});
const cardsByDeck = cardsByDeckService.createIndexStoreSlot(cards);
const deckReads = cardsByDeckService.slotContentService;

const cardCountByDeckService = createOIMComputedService<string, number>({
createSources: ({ key: deck }) => ({ sourceSlots: [cardsByDeckService.getSlotByKey(cardsByDeck, deck)] }),
derive: (computedSlot) => deckReads.getBucketMemberSlotCount(
cardsByDeckService.getSlotByKey(cardsByDeck, computedSlot.key),
),
sameValueGuard: isOIMSameValueZero,
initialValue: 0,
});
const cardCountByDeck = cardCountByDeckService.createStoreSlot(db);

const pointsByDeckService = createOIMComputedService<string, number>({
createSources: ({ key: deck }) => ({
sourceSlots: [
cardsByDeckService.getSlotByKey(cardsByDeck, deck),
cardsByDeckService.getBucketColumnSlotByKey(cardsByDeck, deck, 'points'),
],
}),
derive: (computedSlot) => {
let total = 0;
for (const cardSlot of deckReads.getBucketMemberSlots(
cardsByDeckService.getSlotByKey(cardsByDeck, computedSlot.key),
)) {
total += cardSlot.entity?.points ?? 0;
}
return total;
},
sameValueGuard: isOIMSameValueZero,
initialValue: 0,
});
const pointsByDeck = pointsByDeckService.createStoreSlot(db);

const redPoints = pointsByDeckService.holdSlotByKey(pointsByDeck, 'red');
effectService.createAndRunEffect(db, () => render(redPoints.value), [], [redPoints]);
const redCount = cardCountByDeckService.getSlotByKey(cardCountByDeck, 'red');
redCount.value;

Why this way: a computed is pulled. It derives on the read that asks, at most once per clock tick, and only when one of its sources moved since its last run. The bucket slot moves on membership, and the bucket column slot moves when a write changes points on a member, so a title edit derives neither total. The index marks bucket column slots only after one has been asked for, so a deck nobody sums pays nothing for them. A computed's sameValueGuard decides whether a re-derived total counts as unchanged, and an unchanged total wakes nothing above it; with none given the guard is Object.is, and isOIMSameValueZero also treats NaN as equal to NaN. A computed's default release policy is OIMSlotAtUnholdReleasePolicy: a slot only read goes at the next flush, a held one at its last unhold, and its holds on the bucket go with it.

Reference: One derivation per key, Ordering (bucket column slots), Releasing a computed and its sources.

Several groups fetched at once​

Take: holdSlotsByKeys on the index (or getSlotsByKeys for a read inside this turn) with every key the screen shows. Do not call holdSlotByKey once per key in a loop: each new bucket is filled by its own scan of the source store slot.

const cardsByColumnService = createOIMSlotCollectionIndexService({
entityService: cardService,
selectKey: (card: Card) => card.deck,
slotReleasePolicy: OIMSlotAtUnholdReleasePolicy.INSTANCE,
});
const cardsByColumn = cardsByColumnService.createIndexStoreSlot(cards);

const columns = cardsByColumnService.holdSlotsByKeys(cardsByColumn, ['todo', 'doing', 'done']);
const onColumns = effectService.createAndRunEffect(db, () => {
for (const column of columns) render(column.getBucketMemberSlotCount());
}, columns);

effectService.disposeEffect(onColumns);
for (const column of columns) column.unholdSlot();

Why this way: a bucket minted after its entities were written is filled from the source when it is minted, and that fill is the only scan an index ever does. Minting several keys in one call fills all the new buckets in one pass over the source instead of one pass per key. The slots come back in the order of the keys you passed. With OIMSlotAtUnholdReleasePolicy each column goes at its last unhold, and the next hold builds it again with one scan; leave the policy out when the same columns are opened over and over.

Reference: Indexes, Membership is a bucket, and it is pushed.