Skip to main content

Snapshot Manager

@oimdb/snapshot-manager exports nothing. Do not add it to a new project.

Why there is no shared changelog​

A list of changed entities that is cleared when read is the wrong shape for a store with several consumers:

  • The read is not idempotent. Two calls with no write between them return different answers, because the first consumes what it returns. Whoever reads first takes the changes from everybody else, so two consumers cannot share one.
  • "Snapshot" already means the opposite. In @oimdb/persist a snapshot is the full current state of a source (TOIMPersistRecords for a collection).

Each job such a list is taken for has a door that exists for that job, and each of those doors belongs to the consumer that opens it.

Setup shared by the examples on this page
import { OIMDB, type TOIMStoreKey, createOIMSlotCollectionService, createOIMEntityContentService, OIMSlotContentChangeListenerService, OIMChannelService, type IOIMSlotContentChangeListener, type TOIMEntitySlot } from '@oimdb/core';

type Card = { id: string; title: string };

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

Which door for which job​

You want to know…UseDocumented at
which keys to write to storage@oimdb/persist: OIMPersistEntityWriter reports every entity slot it writes to whoever called its subscribeEntitySlotWritten(onEntitySlotWritten), and an OIMPersistRecordsResource over OIMPersistCollectionWriteRecordSource keeps those slots until the persistor's next write batch takes them. It needs no channel.Persist
that one entity, bucket or derived value changedan effect: OIMEffectService.INSTANCE.createEffect(db, body, [slot])Reading and subscribing
which entities of a collection changed during a framea content-change listener on the collection's store slot, read at the frame boundarybelow, and Indexes
whether a slot moved since a point you rememberthe slot's own stamps, changedAtRevision and changedAtEpoch, against db.clock (isOIMAnySlotChangedAfter)The clock

Which entities changed in a frame​

A content-change listener is told synchronously, at the write, about every slot whose content moved. It hears once per write through onContentChanged, or once per batch (writeInBatch, openBatch / closeBatch) through onManyContentsChanged. OIMChannelService.INSTANCE.subscribeAfterEachFrame(channelSlot, handler) gives you the boundary. The set below is yours, so clearing it after reading takes nothing away from anybody else:


const movedInFrame = new Set<TOIMStoreKey>();
const movedListener: IOIMSlotContentChangeListener<TOIMEntitySlot<Card, TOIMStoreKey>, Partial<Card>> = {
onContentChanged: slot => { movedInFrame.add(slot.key); },
onManyContentsChanged: slotChannelQueue => {
for (let i = 0; i < slotChannelQueue.getEntryCount(); i++) movedInFrame.add(slotChannelQueue.getEntryAt(i).key);
},
};
OIMSlotContentChangeListenerService.INSTANCE.addContentChangeListener(cards, movedListener, undefined);
const stopReporting = OIMChannelService.INSTANCE.subscribeAfterEachFrame(db.defaultChannelSlot, () => {
console.log([...movedInFrame]);
movedInFrame.clear();
});

cardService.writeSlotContentByKey(cards, 'c1', { id: 'c1', title: 'Ace' });
db.flush(); // logs ['c1']

stopReporting();
OIMSlotContentChangeListenerService.INSTANCE.removeContentChangeListener(cards, movedListener);

Why a listener rather than an effect here. An effect is per slot: watching a whole collection with effects means one effect per entity, and an entity written for the first time has no effect on it yet. The listener is per store slot and sees every write to it, including the first. Registered with every column (readColumnNames undefined), it makes every write to that store slot a little slower for as long as it is registered.

Why not inside the frame. The listener runs during the write, before the frame has delivered anything. The after-each-frame handler runs once the frame's effects have run, so what it reads is the settled state. A write from that handler is refused because it is still inside flush(), so act on the list after flush() returns, or hand it to something that does.

If you have it installed​

The versions published on npm are untouched and keep working for anything that installed them. Nothing was unpublished. They were built against the @oimdb/core this tree replaced — the latest, 2.2.0, declares @oimdb/core ^3.8.0 as its peer, as the registry reads, so it does not work with @oimdb/core 4.x.