Standalone records
A standalone record is one identity with no key and no collection —
settings, a session, a view model. It is the single of the entity pair: a store
slot of createOIMSingleSlotService() — an OIMSingleSlotService over an entity content service keyed
by void over OIMSingleSlotStoreService.INSTANCE — made by createStoreSlot(db) and filled by
writeSlotContentByKey. The other half of the pair is a collection, a store slot of a
keyed entity collection.
Use it for one value the program shares, that something subscribes to, and that nobody looks up by key. Values told apart by a key are a collection — even if there are only two of them, because a collection is what mints, files and releases identities per key. A value derived from other slots is a single computed, not a record you keep writing.
Setup shared by the examples on this page
import { OIMDB, OIMEffectService, OIMSingleSlotStoreService, insertOIMEntityWithCopy, createOIMComputedService, createOIMInPlaceEntityWriter, createOIMReplacingEntityWriter, type TOIMComputedSlot, type TOIMSingleSlotStore, createOIMEntityContentService, createOIMSingleSlotService, createOIMSingleComputedService } from '@oimdb/core';
type Settings = { theme: string; fontSize: number; sidebar?: boolean };
const db = new OIMDB();
const effectService = OIMEffectService.INSTANCE;
const settingsService = createOIMSingleSlotService({ slotContentService: createOIMEntityContentService<Settings>() });
const settings = settingsService.createStoreSlot(db);
const settingsContentService = settingsService.slotContentService;
settingsService.writeSingleSlotContent(settings, { theme: 'dark', fontSize: 14 });
const settingsSlot = settingsService.getSingleSlot(settings);
The service is built once, and each createStoreSlot(db) is one record. It mints nothing: the
record's first value arrives through writeSingleSlotContent(storeSlot, entity), an ordinary write that is
announced to the channel like any other, and until then peekSingleSlot(storeSlot)
answers undefined.
createOIMSingleSlotService(options) takes a required slotContentService and the optional defaults,
slotReleasePolicy, slotSubscriptionListener, columnSlotStoreService, columnNames and columnGroups; an option left out comes
from defaults and then the built-in defaults. entityWriter and slotEmptinessPolicy are options of the content
service, createOIMEntityContentService<Settings>({ entityWriter, slotEmptinessPolicy }). columnNames names the
columns, files their slots in the ordinal store OIMColumnSlotOrdinalStoreService and types the column doors on
those names; columnGroups declares the groups (from createOIMColumnGroup) its group doors accept. The column doors are on the slot — settingsSlot.getColumnSlot(columnName), holdColumnSlot(columnName),
getColumnGroupSlot(group), holdColumnGroupSlot(group), getAnyColumnSlot(), holdAnyColumnSlot() — and on the service's
columnSlotService: getColumnSlot(slot, columnName), holdColumnSlot(slot, columnName),
getColumnGroupSlot(slot, group), holdColumnGroupSlot(slot, group), getAnyColumnSlot(slot), holdAnyColumnSlot(slot) and
unholdColumnSlot(columnSlot).
The record owns one slot, and it is read through the single doors:
settingsService.getSingleSlot(settings) hands it back, and mints it if none is filed;
settingsService.holdSingleSlot(settings) hands it back held;
settingsService.peekSingleSlot(settings) answers it without minting, and hasSingleSlotContent(settings)
whether it holds a value. The slot is a plain TOIMEntitySlot, the same shape a collection files —
.entity is the stored value, .effects its subscribers — so there is no handle to resolve and nothing to
look up. Its owner is the content service's slot owner, and it is released under the release policy like any
other entity slot: under the default OIMSlotAtEmptyReleasePolicy
it stays while it has a value or something holds it, and a record given
OIMSlotNeverReleasePolicy.INSTANCE keeps it for good. Once released, the next get or hold mints a fresh slot,
exactly as a collection mints a key again.
Everything that reads an entity slot reads this one — an effect over it, or over one
of its columns, or a computed that names it as a source.
effectService.createEffect(db, () => { console.log(settingsSlot.entity?.theme); }, [settingsSlot]);
effectService.createEffect(db, () => {
console.log(settingsSlot.entity?.fontSize);
}, [settingsSlot.holdColumnSlot('fontSize')]);
const fontLabelService = createOIMSingleComputedService<string>();
const fontLabel = fontLabelService.createStoreSlot(
db,
() => `${settingsSlot.entity?.fontSize ?? 0}px`,
() => ({ sourceSlots: [settingsSlot] }),
);
const fontLabelSlot = fontLabelService.getSingleSlot(fontLabel);
fontLabelSlot.value;
An effect on a column takes the column slot as its root.
settingsService.holdColumnSlot(settingsSlot, name) is what mints it and holds it. settingsService.unholdColumnSlot(column)
gives the hold back, and the column slot goes once nothing holds it and no effect is filed on it. An
effect on a column runs only when a write moved that column; an effect on the
record runs on any write that moved something.
Writing
settingsSlot.updateEntity({ theme: 'light' }); // patch: named columns move
settingsSlot.deleteEntityColumns(['sidebar']); // the thing a patch cannot say
settingsSlot.writeSlotContent({ theme: 'dark', fontSize: 16 }); // becomes exactly this
db.flush();
| Method | Writer call | What moves |
|---|---|---|
updateEntity(slot, patch) | patchEntity (PATCH) | the columns the patch names whose value differs |
updateEntityColumn(slot, columnName, value) | patchColumn | that column, if its value differs |
deleteEntityColumns(slot, names) | deleteColumns | the named columns the record holds with a value other than undefined |
writeSlotContent(slot, next) | putEntity (PUT) | the columns that differ, plus the columns the record had and next does not |
These are the slot doors of the entity content service, the same ones a collection's slots take: none of
them takes a store slot, because the slot carries the one it is filed in. A write that moved nothing
wakes nobody. Whether a column moved is the writer's sameValueGuard, isOIMSameValueZero by
default. Delivery happens at the next db.flush().
writeSlotContent is what restoring a saved state needs: a patch alone leaves behind
every key that was deleted before the snapshot was taken, so a plain load quietly
resurrects them. It reads the own properties of a value that is an instance of
a class, so the prototype's names are not reported as columns.
Under both writers a column that leaves — named in deleteEntityColumns, or dropped by
writeSlotContent — is written undefined rather than deleted (in place, or into the
replacing writer's copy), so the stored object keeps its shape; a column holding
undefined counts as absent. See Writing.
A misspelt column in deleteEntityColumns is a compile error naming the column — its
parameter is readonly TOIMColumnName<TEntity>[].
The writer
Every store slot has a channel (see
Every collection has a channel).
A record nobody subscribes to still pays, per write that moved something, the column
marking and the one channel write. The writer is the entityWriter option of the service,
so every record of one service shares it:
const initial: Settings = { theme: 'dark', fontSize: 14 };
const inPlaceSettingsService = createOIMSingleSlotService({ slotContentService: createOIMEntityContentService<Settings>({ entityWriter: createOIMInPlaceEntityWriter() }) });
inPlaceSettingsService.writeSingleSlotContent(inPlaceSettingsService.createStoreSlot(db), initial);
const replacingSettingsService = createOIMSingleSlotService({ slotContentService: createOIMEntityContentService<Settings>({ entityWriter: createOIMReplacingEntityWriter() }) });
replacingSettingsService.writeSingleSlotContent(replacingSettingsService.createStoreSlot(db), initial);
Use the in-place writer when readers are effects; use the replacing one when a
reader decides "did it change?" by comparing the slot's entity to the last one it
saw. Name no writer and defaults.entityWriter answers, then the in-place writer,
createOIMInPlaceEntityWriter().
The object you hand it is stored as handed — by default
The first value, upserted while no slot is filed, goes through the writer's fillEntity. Both writer factories
default it to insertOIMEntityWithoutCopy, which stores your object itself. With the
in-place writer a later update edits that same object. If you keep your own reference
and mutate it, the stored value changes without telling anyone: no sameValueGuard
runs, no frame opens, nobody is woken.
When the caller must keep its object untouched, insertOIMEntityWithCopy stores a
shallow copy ({ ...entity }), one level deep: a nested object is shared with
the value you handed in.
const copyingSettingsService = createOIMSingleSlotService({ slotContentService: createOIMEntityContentService<Settings>({ entityWriter: createOIMInPlaceEntityWriter({ entityInserter: insertOIMEntityWithCopy }) }) });
copyingSettingsService.writeSingleSlotContent(copyingSettingsService.createStoreSlot(db), { theme: 'dark', fontSize: 14 });
For untrusted JSON, insertOIMEntityWithSanitizedCopy also removes an own __proto__
key from the copy; for later writes take the guarded walk arms
(patchEntityColumns: guardOIMEntityColumnsPatch, patchEntityColumn: guardOIMEntityColumnPatch,
putEntityColumns: guardOIMEntityColumnsPut), which skip that name.
The frame guard
A write during a flush, or to a released slot, throws before any column changes. The flush
includes onBeforeFlush and the after-each-frame handlers, so a write in response to a change
happens after flush() has returned. See the frame.