Memory and lifetime
How long data stays in memory: keeping a screen's data while the screen is open, reading without keeping, caches that expire, store slots that never release, dropping everything on logout, and which handle to keep in long-lived code.
Setup shared by the examples on this page
import { OIMDB, isOIMSlotReleased, type TOIMStoreKey, createOIMSingleComputedService, createOIMSlotCollectionService, createOIMEntityContentService, OIMSlotAtUnholdReleasePolicy, createOIMSlotCollectionIndexService, OIMUnusedSlotCollectorService, createOIMUnusedSlotCollectorSlot, OIMSlotEarliestReleasePolicy, OIMSlotAfterWriteReleasePolicy, OIMSlotAfterIdleReleasePolicy, OIMSlotAfterUnholdReleasePolicy, OIMSlotNeverReleasePolicy, OIMChannelService, OIMDefaults } from '@oimdb/core';
type Card = { id: string; deckId: string; title: string; rank: number };
declare function render(value: unknown): void;
const db = new OIMDB();
const cardService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService<Card>() });
const cards = cardService.createStoreSlot(db);
Keep a screen's data only while the screen is open
Take: holdSlotByKey(storeSlot, key) when the screen opens and slot.unholdSlot() when it
closes — on a collection built with OIMSlotAtUnholdReleasePolicy if the data
must go with the screen. Do not rely on the default policy for that: under
OIMSlotAtEmptyReleasePolicy an unhold leaves a slot with a value standing.
const reserved = cardService.holdSlotByKey(cards, 'c1');
cardService.writeSlotContentByKey(cards, 'c1', { id: 'c1', deckId: 'spades', title: 'Ace', rank: 1 });
reserved.unholdSlot();
const keptByDefault = cardService.hasSlotContentByKey(cards, 'c1');
const screenDefaults = new OIMDefaults({ slotReleasePolicy: OIMSlotAtUnholdReleasePolicy.INSTANCE });
const deckCardService = createOIMSlotCollectionService({ defaults: screenDefaults, slotContentService: createOIMEntityContentService<Card>() });
const deckCards = deckCardService.createStoreSlot(db);
const deckCardsByDeckService = createOIMSlotCollectionIndexService({
defaults: screenDefaults,
entityService: deckCardService,
selectKey: (card: Card) => card.deckId,
});
const deckCardsByDeck = deckCardsByDeckService.createIndexStoreSlot(deckCards);
function openDeckScreen(deckId: string, loaded: readonly Card[]): () => void {
const deck = deckCardsByDeckService.holdSlotByKey(deckCardsByDeck, deckId);
deckCardService.writeInBatch(deckCards, () => (loaded).map(entity => deckCardService.writeSlotContentByKey(deckCards, entity.id, entity)));
render(deckCardsByDeckService.getEntitiesByKey(deckCardsByDeck, deckId));
return () => { deck.unholdSlot(); };
}
Why this way: a hold is a count on the slot, kept by its owner; the slot goes
only when nothing holds it, no effect is on it, and the release
policy agrees. The default OIMSlotAtEmptyReleasePolicy lets go of empty slots
only, so keptByDefault is true — a store of entities keeps what was written.
Under OIMSlotAtUnholdReleasePolicy a slot goes at its last unhold, value and
all, and a write into a key nobody holds is released at once. That is why the
screen holds the deck's bucket before it writes: a bucket holds each of its
members, so the cards filed into the held deck stay; when the bucket is unheld it
is released, its members' holds are given back, and they go.
Reference: Slot lifecycle, Releasing an identity on a clock.
Read without keeping
Take: slotContentService.peekSlotByKey(storeSlot, key) for a value you do not keep — it mints nothing — or
peekSlotByKey(storeSlot, key) for the slot without minting, getSlotByKey(storeSlot, key) when you need a slot
whether or not one exists, and hasSlotContentByKey(storeSlot, key) when you only need to know whether a value
exists. Wrap reads in OIMUnusedSlotCollectorService.INSTANCE.run(db.collectorSlot.unusedSlotCollectorSlot, body)
(or open / close) when they must survive a flush; for a set of reads with its own end, use an unused-slot
collector slot of your own. Do not use holdSlotByKey for a one-off read: that hold is yours to give back.
const unusedSlotCollectorService = OIMUnusedSlotCollectorService.INSTANCE;
const title = cardService.peekSlotByKey(cards, 'c2')?.entity?.title;
const known = cardService.hasSlotContentByKey(cards, 'c3');
unusedSlotCollectorService.run(db.collectorSlot.unusedSlotCollectorSlot, () => {
const first = cardService.getSlotByKey(cards, 'c2');
db.flush();
render(cardService.getSlotByKey(cards, 'c2') === first);
});
const panelUnusedSlotCollectorSlot = createOIMUnusedSlotCollectorSlot();
unusedSlotCollectorService.holdSlotUntilFlush(panelUnusedSlotCollectorSlot, cardService.getSlotByKey(cards, 'c4'));
unusedSlotCollectorService.holdSlotUntilFlush(panelUnusedSlotCollectorSlot, cardService.getSlotByKey(cards, 'c5'));
unusedSlotCollectorService.flush(panelUnusedSlotCollectorSlot);
Why this way: a getter that finds no identity mints one, so a subscription
taken right after the read lands on the slot every later write uses. The mint is
held by the db's unused-slot collector, which gives every such hold back at
the end of the next flush; an empty slot nothing else keeps then goes.
peekSlotByKey and hasSlotContentByKey mint nothing. A scope defers the give-back: scopes nest, only
the close that brings the depth to zero gives the holds back, close without an
open throws, and run closes from a finally. A collector slot of your own holds
each slot you holdSlotUntilFlush until its own flush.
Reference: The unused-slot collector, Which read mints.
Cache with expiry
Take: a timed slotReleasePolicy at construction —
OIMSlotAfterWriteReleasePolicy({ keepAfterWriteMs }) for data that goes stale,
OIMSlotAfterIdleReleasePolicy({ keepAfterIdleMs }) for what was recently watched,
OIMSlotAfterUnholdReleasePolicy({ keepAfterUnholdMs }) for navigating back to a
screen, and OIMSlotEarliestReleasePolicy([...]) to combine them. There is no
release call, so a sweep of your own over the store slot has nothing to call.
const cacheDb = new OIMDB();
const searchResultService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService<Card>(), slotReleasePolicy: new OIMSlotEarliestReleasePolicy([
new OIMSlotAfterWriteReleasePolicy({ keepAfterWriteMs: 60_000 }),
new OIMSlotAfterIdleReleasePolicy({ keepAfterIdleMs: 30_000 }),
]) });
const searchResults = searchResultService.createStoreSlot(cacheDb);
const backStackDefaults = new OIMDefaults({
slotReleasePolicy: new OIMSlotAfterUnholdReleasePolicy({ keepAfterUnholdMs: 5_000 }),
});
const recentCardService = createOIMSlotCollectionService({ defaults: backStackDefaults, slotContentService: createOIMEntityContentService<Card>() });
const recentCards = recentCardService.createStoreSlot(cacheDb);
Why this way: how long data is worth keeping is a property of the
collection type, so it is chosen once — through the slotReleasePolicy of an OIMDefaults shared as defaults, or
per collection through the option of the same name — and every store slot of that type shares it. Each timed
policy keeps its own deadline on the slot and its own queue; the clock and the timer are the db's. Every write
that leaves a value renews the write window, the last subscriber leaving opens an idle window,
and the last unhold opens an unhold window. A held slot is off the clock: a hold,
including the one an effect takes, outranks every deadline, and a slot whose
window ran out while held goes at the give-back. Slots are swept in slices of
OIM_SLICE_LENGTH_MS, so a slot goes at the first sweep at or after its
deadline, never before.
Reference: Releasing an identity on a clock, Controlling the clock.
Never release
Take: OIMSlotNeverReleasePolicy for a small, fixed key space whose
identities must stay stable — settings, a fixed set of decks, a computed every
screen reads. Do not use it for a store slot keyed by anything a user or a server
can grow: nothing in it ever leaves memory.
import { OIMSingleSlotStoreService, createOIMComputedService, type TOIMComputedSlot, type TOIMSingleSlotStore } from '@oimdb/core';
type Deck = { id: 'spades' | 'hearts' | 'diamonds' | 'clubs'; name: string };
const deckService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService<Deck>(), slotReleasePolicy: OIMSlotNeverReleasePolicy.INSTANCE });
const decks = deckService.createStoreSlot(db);
const spadesSlot = deckService.getSlotByKey(decks, 'spades');
const spadesNameService = createOIMSingleComputedService<string>({
initialValue: '',
slotReleasePolicy: OIMSlotNeverReleasePolicy.INSTANCE,
});
const spadesName = spadesNameService.createStoreSlot(
db,
() => spadesSlot.entity?.name ?? '',
() => ({ sourceSlots: [spadesSlot] }),
);
const spadesNameSlot = spadesNameService.getSingleSlot(spadesName);
render(spadesNameSlot.value);
Why this way: OIMSlotNeverReleasePolicy answers "keep it" for a slot with a
value and for an empty one, so a deleted key's slot stays filed, and so does
every empty slot a read minted — getSlotByKey over arbitrary keys grows the
store for good. In return a slot object stays the same for the life of the
store slot, so a reference to it never goes dead. On a computed it keeps the
computed slot and every source it holds for the life of the store slot.
Reference: Asked to go — the release policy answers, Releasing a computed and its sources.
Drop everything on logout
Take: db.dispose(), then drop every reference to that
OIMDB, its services, their store slots and their slots, and build a new OIMDB for the next
session. Do not call clearSlotContent over every
slot: it takes values away one by one and leaves every identity something keeps.
let sessionDb = new OIMDB();
let sessionCardService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService<Card>() });
let sessionCards = sessionCardService.createStoreSlot(sessionDb);
function logOut(): void {
sessionDb.dispose();
sessionDb = new OIMDB();
sessionCardService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService<Card>() });
sessionCards = sessionCardService.createStoreSlot(sessionDb);
}
Why this way: the call walks no slot. It sets a flag, cancels the frame it had
scheduled (a frame is the delivery of every write since the previous one; see the
glossary), gives back the unused-slot collector's holds, and empties the pending
effects and the after-each-frame and after-each-flush handlers; everything else
becomes garbage together once you drop your references. The condition is yours to
keep, and nothing checks it: nothing may still be subscribed to that channel and
expect to be told — a standing effect never runs again, with no throw and no
report. After the call, a write to the old channel is not refused, but it asks
for no frame and nothing it scheduled is delivered; flush() returns at once.
Reference: Dropping the whole channel.
Keep a long-lived handle correctly
Take: keep the collection service and its store slot (an entity, index or computed one) and the key, and resolve the slot when you need it; keep a slot only while you hold it. A slot stored in a module or a class field across flushes without a hold is a dead identity once it is released.
const late = cardService.getSlotByKey(cards, 'c9');
db.flush();
const isDead = isOIMSlotReleased(late);
try {
late.holdSlot();
} catch {
const fresh = cardService.holdSlotByKey(cards, 'c9');
render(fresh !== late);
fresh.unholdSlot();
}
class DeckView {
public constructor(
private readonly cardCollectionService: typeof cardService,
private readonly entityStoreSlot: typeof cards,
private readonly cardKey: TOIMStoreKey,
) {}
public showCard(): void {
render(this.cardCollectionService.getSlotByKey(this.entityStoreSlot, this.cardKey).entity);
}
}
Why this way: a released slot leaves the store and gets its RELEASED flag set;
every call that works with it — owner.holdSlot, owner.unholdSlot, a write, a subscription,
getValueForSlot on a computed — throws "This identity was released". The key is
not dead: the next door for it mints a new slot, so isDead above is true and
the slot from holdSlotByKey is a different object. A service holds no slots and
is never released, and a store slot is not one a release policy takes (an index
store slot goes only through disposeIndexStoreSlot); both outlive every slot minted
through them, which is what makes them the handles to keep.
Reference: Released — the slot is dead and its key can be minted again, Both shapes are factories.