# OIMDB > **For AI assistants: read this file before writing any OIMDB code.** > > **WHICH API TO WRITE — decide this first.** One engine, one database per application: > > | you are writing | what you call | the database | > |---|---|---| > | an application (the common case) | the store aggregates inside `createSchemas`, then slot methods and `db.createEffect` | `new OIMDB({ createSchemas })`, built once; call `db.flush()` after a batch of writes — nothing is delivered before it, unless the `OIMDB` was given a `channelScheduler`. | > | a library, SSR (a database per request), tests that need isolated databases | the same: call the function that builds the database once per request or test | one per request or test; two databases never share a flush | > | what the aggregates do not cover: set / sorted-at-write / custom bucket stores, composite or tree keys, positional bucket writes, column slots and column-group reads (`getEntity(group)`), custom writers, persist or devtools wiring | `@oimdb/core` services (`createOIMSlotCollectionService` …), the rest of this file | the same `OIMDB` | > > There is no global database and no second entry point: `@oimdb/core` is the whole package. > `new OIMDB({ createSchemas: (db) => ({ default: createCardSchema(db) }) })` calls `createSchemas` once, at the > end of its constructor, and `db.schemas` is what it returned. A schema is a plain object built from the store > aggregates (`createOIMEntitySlotCollectionStoreAggregate`, `createOIMSlotCollectionIndexStoreAggregate`, > `createOIMSingleSlotStoreAggregate`, a computed service's `createStoreAggregate`); schemas are namespaces only — > one channel and one flush per database. The collection writes the whole entity under a key > (`cards.writeSlotContentByKey(key, entity)`) and hands out slots (`getSlotByKey`, `holdSlotByKey`); every other > act is a slot method: `slot.entity`, `slot.updateEntity(patch)`, `slot.writeSlotContent(entity)`, > `slot.clearSlotContent()`, a bucket slot's `getBucketMemberSlotCount()`, a computed slot's `value`. Effects are > `db.createEffect(body, sourceSlots?, { lazy? })`, which returns the disposer. In React: > `` and `useOIMSelector(() => cards.getSlotByKey(id).entity)`; a handler > that writes calls `db.flush()` when it is done, and the components re-render at that flush. A list of every > entity needs no index: `cards.getEntities()` (no strict order; a sorted computed for one) and > `cards.getEntityCount()`, both tracked. > > `@oimdb/core` is an in-memory reactive engine. This file is its API reference, > written against the current source. > > **Services hold no data; state lives on slots.** An `OIMDB` owns the clock, the collector slot and > its `defaultChannelSlot`. One channel per database; for isolation, a separate `OIMDB` — a write is > delivered at its own channel's flush to every effect on the slots it moved, so a second channel on > the same clock isolates nothing. A collection service (`OIMSlotCollectionService`) or a single slot service > (`OIMSingleSlotService`) is built once per collection type, and `service.createStoreSlot(db)` makes an > instance, a `TOIMStoreSlot`, which is NOT a slot (no owner, holds or effects) and carries its > `channelSlot`. > READS and minting are on the collection service and take the store slot first > (`cardService.getSlotByKey(cards, key)`, `holdSlotByKey`, `peekSlotByKey`, `getSlots`, `getSlotCount`, the > column doors). One WRITE is on the collection and takes a key: > `cardService.writeSlotContentByKey(cards, key, entity)`, which mints the slot on a miss and writes the whole > value on a hit. Every other write is a method of the slot > (`slot.updateEntity(patch)`, `slot.writeSlotContent(entity)`, > `slot.clearSlotContent()`). There are NO bulk writes and no `selectKey`: the key is always the caller's. A load is a > loop of `writeSlotContentByKey` inside `cardService.writeInBatch(cards, () => { … })`, so an index on the > collection hears the whole loop in one call. > A single — one slot under no key — is an `OIMSingleSlotService`: `writeSingleSlotContent(storeSlot, value)`, > `getSingleSlot(storeSlot)`, `holdSingleSlot(storeSlot)`, `peekSingleSlot(storeSlot)`, > `clearSingleSlotContent(storeSlot)`. No key is `void` or `undefined`: `TKey extends NonNullable`. > > Every collection is `createOIMSlotCollectionService({ slotContentService })` and every single is > `createOIMSingleSlotService({ slotContentService })`. The content service decides what the slots hold: > `createOIMEntityContentService(…)` for entities, `new OIMSetBucketContentService()`, > `new OIMPositionalArrayBucketContentService()` or `new OIMSortedArrayBucketContentService({ … })` for > buckets. An index is `createOIMSlotCollectionIndexService({ entityService, selectKey | columns, slotContentService? })`; > its `selectKey` is the index's key of an entity, not the collection's. An array key needs a tree store: > `slotStoreService` on the collection, `bucketSlotStoreService` on the index. > Position reads and writes (`getBucketMemberSlotAt`, `getBucketMemberSlotPosition`, `insertBucketMemberSlotAt`, > `removeBucketMemberSlotAt`, `removeBucketMemberSlotRange`, `moveBucketMemberSlotToPosition`, > `moveBucketMemberSlotRangeToPosition`) are on `OIMPositionalArrayBucketContentService`, the default bucket > content service; the set-driven one has none. A bucket sorts only on the sorted-at-write content service > (`createOIMSlotCollectionSortedArrayIndexService`); on every other bucket its order is the caller's. A sorted list > over any index is `createOIMSortedComputedService`. The render script is `OIMBucketCommands`. > The channel has no class: its operations are on `OIMChannelService.INSTANCE` and take a channel slot. > Effects are `OIMEffectService.INSTANCE.createEffect(db, body, sourceSlots?, sourceComputeds?, sourceTrackingComputeds?)`. > Every stateless singleton is a static `INSTANCE` on its class. Module-level defaults are on `OIMDefaults`. > > Check every symbol you write against [the full export list](#full-export-list). > > Install: `npm install @oimdb/core` (4.x). The 3.x line is the previous engine with a different API. > > `packages/core/src/index.ts` is the entire public surface of `@oimdb/core`. Start with > [A database with schemas](#a-database-with-schemas). ## A database with schemas The shortest way in, and the one to write first for an application. Build one `OIMDB` with `createSchemas`; every collection, index and computed in its schemas runs on it. A `new OIMDB()` with no `channelScheduler` delivers nothing until `db.flush()`, which delivers every write since the last flush once: call it where a batch of writes ends (after applying a response, at the end of an event handler). ```ts file=oimdb-schemas.ts import { OIMDB, createOIMEntitySlotCollectionStoreAggregate, createOIMSlotCollectionIndexStoreAggregate, createOIMSortedComputedService, createOIMSingleSourceTrackingComputedService, createOIMSingleSlotStoreAggregate, createOIMEntityContentService, } from '@oimdb/core'; type TCard = { id: string; deck: string; title: string; rank: number }; type TConnection = { isOnline: boolean }; const createConnectionSchema = (db: OIMDB) => ({ connections: createOIMEntitySlotCollectionStoreAggregate(db), settings: createOIMSingleSlotStoreAggregate(db, { slotContentService: createOIMEntityContentService<{ theme: string }>() }), }); const createCardSchema = (db: OIMDB, connectionSchema: ReturnType) => { const cards = createOIMEntitySlotCollectionStoreAggregate(db); // keyed by string | number const byDeck = createOIMSlotCollectionIndexStoreAggregate(cards, { selectKey: (card) => card.deck }); // or { columns: ['deck'] } const byRankService = createOIMSortedComputedService({ indexService: byDeck.slotService, sortColumns: [{ columnName: 'rank', direction: 'asc' }] }); const byRank = byRankService.createStoreAggregate(byRankService.createSortedStoreSlot(byDeck.storeSlot)); const visibleSpadeCountService = createOIMSingleSourceTrackingComputedService({ derive: () => (connectionSchema.connections.getSlotByKey('self').entity?.isOnline === true ? byDeck.getSlotByKey('spades').getBucketMemberSlotCount() : 0), initialValue: 0, }); const visibleSpadeCount = visibleSpadeCountService .createStoreAggregate(visibleSpadeCountService.createStoreSlot(db)); return { cards, byDeck, byRank, visibleSpadeCount }; }; const createAppDB = () => new OIMDB({ createSchemas: (db) => { const connection = createConnectionSchema(db); // a schema another one reads: build it first return { connection, default: createCardSchema(db, connection) }; }, }); const db = createAppDB(); const { cards, byDeck, byRank, visibleSpadeCount } = db.schemas.default; const ace = cards.writeSlotContentByKey('c1', { id: 'c1', deck: 'spades', title: 'Ace', rank: 14 }); // the slot cards.getSlotByKey('c1') === ace; // true: the slot is the entity's identity ace.updateEntity({ rank: 1 }); // every other write is a slot method ace.entity; // TCard | undefined; tracked inside a computed / effect cards.getSlotByKey('c9').clearSlotContent(); // delete; a slot nothing holds goes with it cards.getEntities(); // TCard[], no index, no strict order; tracked: adds, edits, deletes cards.getEntityCount(); // number; tracked: adds and deletes byDeck.getEntitiesByKey('spades'); // TCard[], tracked: membership and member edits byDeck.getSlotByKey('spades').getBucketMemberSlotCount(); // number, tracked byRank.getSlotByKey('spades').value; // the member slots in rank order, tracked db.schemas.connection.settings.writeSingleSlotContent({ theme: 'dark' }); db.schemas.connection.connections.writeSlotContentByKey('self', { isOnline: true }); const stop = db.createEffect(() => console.log(visibleSpadeCount.getSingleSlot().value)); // tracking: runs at once const stopNamed = db.createEffect(() => () => console.log('cleanup'), [ace], { lazy: true }); // named: waits for a change db.flush(); // effects run here, once per flush stop(); stopNamed(); ``` | Call | Signature | Notes | |---|---|---| | `new OIMDB(options?)` | `OIMDB`; options `createSchemas?: (db: OIMDB) => TSchemas`, `channelScheduler`, `errorPolicy`, `onBeforeFlush`, `getNowMs`, `releaseTimer` | `createSchemas` is called once, at the end of the constructor; `db.schemas` is its result, `undefined` without the option | | `db.createEffect` | `(body: () => void \| (() => void), sourceSlots?, options?: { lazy? }): TOIMDisposer` | no list: `createSourceTrackingEffect`, runs at once (`lazy` is ignored); a list: `createAndRunEffect`, or `createEffect` with `lazy`; `[]`: runs once, its cleanup on stop | | `db.flush()` | `(): void` | delivers every write since the last flush | | `db.dispose()` | `(): void` | drops the database: `OIMChannelService.INSTANCE.dropChannelSlot(db.defaultChannelSlot)`, so no later flush delivers, its effects stop and its release wheels are cancelled | | `createOIMEntitySlotCollectionStoreAggregate` | `(db, options?)` | `writeSlotContentByKey(key, entity): slot`, `getSlotByKey`, `holdSlotByKey`, `peekSlotByKey`, `hasSlotContentByKey`, `getSlots`, `getSlotCount`, `getEntities()`, `getEntityCount()`, `writeInBatch(write)` | | `createOIMSingleSlotStoreAggregate` | `(db, { slotContentService, … })` | `writeSingleSlotContent(value)`, `getSingleSlot()`, `holdSingleSlot()`, `peekSingleSlot()`, `hasSingleSlotContent()`, `clearSingleSlotContent()` | | `createOIMSlotCollectionIndexStoreAggregate` | `(collection, { selectKey } \| { columns }, plus the index factory options)` | `getEntitiesByKey(key)` tracked; `getSlotByKey(key)`: the bucket slot (`getBucketMemberSlots()`, `getBucketMemberSlotCount()`); on the collection's db | | a computed's store aggregate | `service.createStoreAggregate(service.createStoreSlot(db))`; a sorted list: `sortedService.createStoreAggregate(sortedService.createSortedStoreSlot(index.storeSlot))` | read `getSingleSlot().value` / `getSlotByKey(key).value`; the slot goes when nothing holds it and the next read derives it again | A body's returned cleanup runs before its next run and on the disposer. A computed — anything with `sourceComputeds` — cannot be passed in `sourceSlots` (excluded by type); read it through `.value` in a body without a list. An entity's column slot has a `value` but is not a computed, and is accepted. `slot.watch(body, columnNames?)` is the one-slot form: it runs at once with `slot.entity` (a computed: its `value`; a bucket: the bucket slot) and on every change of that slot, and returns the disposer. `OIMEffectService.INSTANCE` is the layer under `db.createEffect`. In React: `useOIMSelector(() => cards.getSlotByKey(key).entity)` re-renders on what the function read, under ``, at the next `db.flush()`. ### Dependency injection The database is the container; there is no container library, registry or global database. The function that builds it (`createAppDB` above) is the composition root: it takes what the application chooses and passes it on. - **Built once, handed down, never imported.** The entry point calls `createAppDB()` and passes the result: `` in React, `new CNS(neurons, undefined, db)` under cnstra (read as `{ global }`), an argument anywhere else. A module that exports a built database is a global by another name — export the function and `ReturnType`, not an instance. - **Strategies are chosen at construction.** Every factory takes one options object (`entityWriter`, `slotEmptinessPolicy`, `slotReleasePolicy`, `slotContentService`, `slotStoreService`, …), and so does `new OIMDB` (the table above). A choice shared by many factories is one `OIMDefaults` passed to each as `defaults` — see [`OIMDefaults`](#oimdefaults--where-an-optional-dependency-comes-from). The built object is the chosen arm, so the write path has no branch on it. - **Two collections of the same kind are two schema entries**, each with its own options. - **A test, a request, a library builds its own** from the same function and calls `db.dispose()` after. Full page: `website/docs/guides/dependency-injection.md`. ## Contents - [A database with schemas](#a-database-with-schemas) — and [dependency injection](#dependency-injection) - [The domains](#the-domains) - [The doctrine](#the-doctrine) — the four doors, the injected seams, the idle windows, the collectors, forks - [The runtime: the channel slot](#the-runtime-the-channel-slot) - [`OIMDB` and the three doors](#oimdb-and-the-three-doors) - [`OIMDefaults` — where an optional dependency comes from](#oimdefaults--where-an-optional-dependency-comes-from) - [Entity services](#entity-services) - [Writing](#writing) - [Write strategies](#write-strategies) - [Single entities](#single-entities) - [Buckets](#buckets) - [Derivations](#derivations) - [Key stores](#key-stores) - [Lifetime — the owner protocol](#lifetime--the-owner-protocol) - [Ordered lists](#ordered-lists) - [Types](#types) - [Full export list](#full-export-list) - [Known defects](#known-defects) - [Other packages](#other-packages) - [`@oimdb/persist`](#oimdbpersist) - [Performance](#performance) --- ## The setup the examples share Every `ts` example in this file compiles against `packages/*/src`, on top of this block and the one under [One derivation per key](#one-derivation-per-key). Blocks marked `ts signature` are listings of an API and are not compiled. ```ts setup import { OIMChannelService, OIMSlotContentChangeListenerService, OIMDB, OIMDefaults, OIMEffectService, OIMPositionalArrayBucketContentService, OIMSetBucketContentService, OIMSlotMapStoreService, OIMSingleSlotStoreService, OIMSlotTreeStoreService, OIMUnusedSlotCollectorService, createOIMBucketMemoComputedService, createOIMComputedService, createOIMSortedComputedService, createOIMSortedCollectionSingleSlotStoreAggregate, createOIMInPlaceEntityWriter, createOIMReplacingEntityWriter, createOIMSlotCollectionIndexService, createOIMSlotCollectionSortedArrayIndexService, createOIMSlotCollectionService, createOIMEntityContentService, createOIMColumnGroup, createOIMSingleSlotService, createOIMSingleComputedService, createOIMUnusedSlotCollectorSlot, OIMSlotCollectionBucketService, getOIMBucketMemberSlotEntities, isOIMSlotEmpty, isOIMSlotReleased, patchOIMEntityColumn, patchOIMEntityColumns, putOIMEntityColumns, isOIMSameValueZero, OIMBucketCommands, OIMSlotEarliestReleasePolicy, OIMSlotAfterWriteReleasePolicy, OIMSlotAfterIdleReleasePolicy, OIMThrowAtOnceErrorPolicy, type TOIMSlotStoreTree, OIMScalarKeyTreeWalk, OIMCompositeKeyTreeWalk } from '@oimdb/core'; import type { IOIMEntityWriter, TOIMEditable, OIMEntitySlot, TOIMBucketSlotsArrayStore, TOIMBucketSlot, TOIMBucketSlotsSetStore, TOIMComputedSlot, TOIMDisposer, TOIMEntityContentSlot, TOIMEntitySlot, TOIMOrderedListCommand, TOIMSingleSlotStore, TOIMStoreKey, TOIMStoreSlot, } from '@oimdb/core'; type Card = { id: string; title: string; rank: number; deck: string }; declare function paint(card: Card | undefined): void; declare function measureAndScroll(): void; declare function poll(): void; declare function reindex(slot: TOIMEntitySlot): void; declare function render(slots: readonly TOIMEntitySlot[]): void; declare function applyToTheRenderedList(commands: readonly TOIMOrderedListCommand[]): void; declare const payload: readonly Card[]; const db = new OIMDB(); const channelSlot = db.defaultChannelSlot; const effectService = OIMEffectService.INSTANCE; const cardService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService() }); const cards = cardService.createStoreSlot(db); const slot = cardService.writeSlotContentByKey(cards, 'c1', { id: 'c1', title: 'Ace', rank: 1, deck: 'spades' }); const orderedService = createOIMSlotCollectionService({ slotContentService: new OIMPositionalArrayBucketContentService>() }); const ordered = orderedService.createStoreSlot(db); const orderedBucketSlot = orderedService.holdSlotByKey(ordered, 'top'); const pageService = createOIMSlotCollectionService({ slotContentService: new OIMPositionalArrayBucketContentService>({ bucketCommands: new OIMBucketCommands({ maxCommandsPerSlot: undefined }) }) }); const page = pageService.createStoreSlot(db); const todo = pageService.holdSlotByKey(page, 'todo'); const done = pageService.holdSlotByKey(page, 'done'); ``` `createOIMSlotCollectionService` and `createOIMSlotCollectionStoreAggregate` read the key, the slot and the content off the content service's `createSlot` and `writeSlotContent` (options type `TOIMSlotCollectionServiceFactoryOptions`), so a function generic over its entity or key (`createOIMEntityContentService()`) calls them with no cast. While the key type is a type parameter, pass `slotStoreService` (a Map store for a scalar key, a tree store for a chain): TypeScript cannot tell then whether the key is a chain. --- ## The domains `src/` holds one folder per domain and `index.ts`, the entire public surface; a factory lives in the domain of what it builds. Where a file goes is in `packages/core/src/README.md`. | Domain | Contents | |---|---| | `slot/` | `OIMSlotOwner`, `OIMSlotOwnerService` (type-only export), `OIMSlotCollectionService`, `OIMWritableSlotCollectionService`, `OIMSingleSlotService`, `OIMWritableSingleSlotService`, `OIMSlotContentChangeListenerService`, `createOIMSlotCollectionService`, `createOIMSingleSlotService`, `TOIMSlot`, `TOIMEditable` | | `store/` | `TOIMStoreSlot`, the slot store services | | `channel/` | `OIMChannelService`, `TOIMChannelSlot` | | `effect/` | `OIMEffectService`, `TOIMEffect` | | `computed/` | `OIMComputedValueService`, `OIMComputedService`, `OIMSingleComputedService`, `OIMSortedComputedService`, `OIMBucketMemoComputedService`, the source-tracking computed services, their factories, `TOIMComputedSlot` | | `entity/` | `OIMEntityContentService`, `createOIMEntityContentService`, `createOIMInPlaceEntityWriter`, `createOIMReplacingEntityWriter` | | `column/` | abstract `OIMColumnSlotOwner` with `OIMPushColumnSlotOwner` and `OIMPullColumnSlotOwner`, `OIMColumnSlotService` | | `bucket/` | `OIMBucketContentService` (abstract), `OIMSetBucketContentService`, `OIMArrayBucketContentService` (abstract), `OIMPositionalArrayBucketContentService`, `OIMSortedArrayBucketContentService`, `OIMBucketCommands` | | `index/` | `OIMSlotCollectionIndexService`, `OIMSlotCollectionSortedArrayIndexService`, their factories, the index keys services | | `key/` | the key tree walks | | `collector/` | the release policies, `OIMSlotReleaseWheel`, `OIMSlotRefetchWheel`, `OIMUnusedSlotCollectorService` | | `schedule/` | `OIMFlushSchedulerService` | | `error/` | the error policies | | `db/` | `OIMDB`, `OIMDefaults`, `OIMDefaultValue`, the default constants | **A service holds no data; state lives on slots.** A collection service is built once per collection type and holds only configuration and other services: its slot owner, its store service and its content service (`service.slotContentService`). `service.createStoreSlot(db)` makes an instance, a `TOIMStoreSlot`, which is NOT a slot (no owner, holds or effects): its `store` is what the store service built, its `channelSlot` is the db's channel, its `slotService` is the service that made it, and it carries the per-store state (content-change listeners, index key positions, the open batch and its queued changes). Every slot filed in it points back to it through `slot.storeSlot`, which is why a slot door needs no store slot. Reads and the keyed write are called on the service (`cardService.getSlotByKey(cards, pk)`, `cardService.getSlots(cards)`, `cardService.writeSlotContentByKey(cards, pk, card)`, or through the store slot: `cards.slotService.writeSlotContentByKey(cards, pk, card)`); writes on a slot go to its content service (`slot.updateEntity(patch)`), and the column doors to `cardService.columnSlotService`. A store slot's `store` is the store service's to read, never the caller's. --- ## The doctrine ### Four doors mint an identity, and nothing else **Writing a value, subscribing, taking a hold, and reading a key that has none.** Each act leaves a **reference** behind on what it produced — a value, an effect, a count, or a tracked mint — so nothing can unfile the identity under the caller who just got it. ```ts cardService.writeSlotContentByKey(cards, 'c2', { id: 'c2', title: 'Two', rank: 2, deck: 'spades' }); // write effectService.createEffect(db, () => { paint(slot.entity); }, [slot]); // subscribe cardService.holdSlotByKey(cards, 'c1'); // hold, by key -> the slot, holdCount up by one const rankColumn = slot.holdColumnSlot('rank'); // hold, on a column rankColumn.unholdSlot(); // give the column back cardService.getSlotByKey(cards, 'c1'); // read, by key -> the slot, tracked by the collector ``` **The non-minting lookup leaves no reference.** `peekSlotByKey(storeSlot, key)` (and `peekSingleSlot(storeSlot)` on a single) answers `undefined` on a miss and mints nothing, and the slot it does hand back is protected by nothing the caller took; the entity is `peekSlotByKey(storeSlot, key)?.entity`. The one by-key write is `writeSlotContentByKey`, the write door above; to patch or clear an entity by key, find the slot first and write through it. Do not write a helper over any of the four doors — it would be a second spelling of a mint, not a fifth door. **Subscribing leaves BOTH kinds of reference.** `OIMEffectService.INSTANCE.createEffect(db, …)` files the effect in `slot.effects` *and* holds each root it subscribed to and each computed source it was given (through `owner.subscribeToSlot`); `disposeEffect(effect)` gives both back. That hold is why no idle window has to count subscribers — see [where an idle window opens](#two-release-markers-one-per-policy). A root reached only *through* a computed is subscribed but **not** held by the effect; a computed minted by `OIMComputedService` holds its own `sourceSlots` and `sourceComputeds` when it is minted and gives them back when its content is released. **`getSlotByKey(storeSlot, key)` is the fourth door, and the collector is what admits it.** It mints what is missing, then hands the slot to the unused-slot collector of the store slot's channel (`OIMUnusedSlotCollectorService.INSTANCE` over `storeSlot.channelSlot.collectorSlot.unusedSlotCollectorSlot`), which holds it for the caller and gives that hold back at the next `db.flush()`. So a `getSlotByKey` inside one turn of work cannot be unfiled under you, and nothing is left standing after it. ### A slot goes when nothing refers to it There is **no release API, no sweep a caller runs, and no owner a caller assigns**. Two things ask. The release queue calls `slot.owner.releaseSlotIfUnheld(slot)` at a deadline; `slot.unholdSlot()` asks on the give-back of the last hold. `releaseSlotIfUnheld` is PUBLIC on `IOIMSlotOwner`. Public does not mean "release on demand" — `releaseSlotIfUnheld` is still a guard, and it returns without doing anything unless the slot is unheld, carries no column slots, still owned by the object asked, and out of grace. Terms, and who gives each back: | Term | Given back by | |---|---| | `holdCount` | `slot.unholdSlot()`, or `columnSlot.unholdSlot()` for a column; the unused-slot collector's flush; a slot leaving a bucket; `effectService.disposeEffect(effect)`, for the hold the effect took | | `effects` | `effectService.disposeEffect(effect)` | | a held column | its last column effect being disposed, through the service's column owner (`unsubscribeFromSlot`) | | the value | `slot.clearSlotContent()`, on an entity slot or a bucket slot alike; `clearSingleSlotContent(storeSlot)` on a single | | a composite-key edge | `OIMCompositeKeyTreeWalk.deleteKey` unlinking that composite key part | `clearSlotContent(slot)` takes the **value**. Subscribers stay, holds stay, and the identity stays with them. Slots you wrote into a bucket are held by that bucket until you empty it. ### A service COMPOSES; nothing is overridden Optional behaviour is added without a branch on the hot path: a collection service is built from three stateless parts, wired once at construction, plus the injected seams below. | Part | Where | What it does | |---|---|---| | the slot owner, `OIMSlotOwnerService` (type-only export) | `slot.owner`, typed `IOIMSlotOwner` | holds, subscriptions, release, emptiness, `assertWritable`, the column owner; one per collection type | | the store service, `IOIMSlotStoreService` | given to the factory (`slotStoreService`, `bucketSlotStoreService`, …) or the Map default | files and finds the slots of each store slot's `store` | | the content service | `service.slotContentService` | the writes and reads of one kind of content (`OIMEntityContentService`, the bucket content services, `OIMComputedContentService`) and the answers the owner asks of that kind | The factory reads what it needs off the content service it is handed, through four small interfaces, never through a subclass of the service: ```ts signature interface IOIMKeyedSlotCreator, TSlot> { createSlot(key: TKey, storeSlot: TOIMStoreSlot, slotOwner: IOIMSlotOwner): TSlot; } interface IOIMSingleSlotCreator { createSingleSlot(storeSlot: TOIMStoreSlot, slotOwner: IOIMSlotOwner): TSlot; } interface IOIMSlotContentWriter { insertSlotContent(slot: TSlot, content: TContent, changedSlots?: TSlot[]): void; writeSlotContent(slot: TSlot, content: TContent): boolean; clearSlotContent(slot: TSlot): void; } interface IOIMSlotContentService { isSlotEmpty(slot: TSlot): boolean; releaseSlotContent(slot: TSlot): void; peekColumnValue(slot: TSlot, columnName: string): unknown; peekColumnGroupValue(slot: TSlot, columnNames: readonly string[]): unknown; peekAnyColumnValue(slot: TSlot): unknown; } ``` A content service with `createSlot` goes into `createOIMSlotCollectionService`, one with `createSingleSlot` into `createOIMSingleSlotService`; the entity and bucket content services have both. Every write door asserts the identity is still filed (`assertWritable`). `releaseSlotContent` is what the slot owner calls when it releases a slot nothing holds, and it throws on a slot that is still held. The three `peek…Value` reads are what a column slot's `value` is computed from; they mint, hold and track nothing. The entity, bucket, collection-set bucket and computed content services implement them. ### The injected seams Each is one small interface handed to a constructor, and each answers one question that the engine asks but does not decide. There is no flag and no option object. ```ts signature interface IOIMSlotEmptinessPolicy { isEmpty(slot: TSlot): boolean; } interface IOIMSlotStamp { stamp(editableSlot: TOIMEditable): void; } ``` **What a kind of content answers is not a seam.** Mint, write, clear and release belong to the content service, which the collection service hands its owner as `slotContentService`. "Does this still hold something" no part declares — the owner asks `isOIMSlotEmpty(slot)` and the release policy's `isSlotReleasable` separately. **`IOIMSlotEmptinessPolicy`** decides what counts as empty, and the answer is written once per write into the EMPTY flag of `slot.slotFlags` — never recomputed at a read. The entity content service defaults to "the entity is `undefined`" (the `slotEmptinessPolicy` option of `createOIMEntityContentService` replaces it); a bucket content service answers "no members"; a computed answers `false`, because a derivation always has a value to produce. **Emptiness decides lifetime, never the write path.** A `writeSlotContent` (or `writeSlotContentByKey` on a hit) onto an entity slot that still carries an entity is put over it even when emptiness calls the slot empty (a soft delete, a seed planted by `IOIMSlotStamp`): a column the new entity drops is woken, an unchanged one is not, and a write that repeats the entity exactly wakes nothing. Only an entity slot with no entity at all is filled whole. **`IOIMSlotStamp`** writes onto the slot at every write, just before emptiness is settled. It is a chain, not a single: each stamp takes the `next` one and calls it first. It is for stamps that are not about release. ### The release policy ```ts signature interface IOIMSlotReleasePolicy { readonly releasesWrittenSlots: boolean; readonly schedulesReleaseOnWrite: boolean; onSlotWritten(slot: TOIMSlot): void; onSlotIdle(slot: TOIMSlot): boolean; onSlotUnheld(slot: TOIMSlot): void; isSlotReleasable(slot: TOIMSlot): boolean; isEmptySlotReleasable(slot: TOIMSlot): boolean; cancelSlotRelease(slot: TOIMSlot): void; } new OIMSlotAfterWriteReleasePolicy({ keepAfterWriteMs: number, slotReleaseDueFramePolicy?: IOIMSlotReleaseDueFramePolicy }) OIMSlotReleaseAutoDueFramePolicy.INSTANCE new OIMSlotReleaseManualDueFramePolicy() // openSlotReleaseDueFrame() · closeSlotReleaseDueFrame() · writeInSlotReleaseDueFrame(write) new OIMSlotAfterIdleReleasePolicy({ keepAfterIdleMs: number }) new OIMSlotAfterUnholdReleasePolicy({ keepAfterUnholdMs: number }) OIMSlotAtUnholdReleasePolicy.INSTANCE OIMSlotAtEmptyReleasePolicy.INSTANCE OIMSlotNeverReleasePolicy.INSTANCE new OIMSlotEarliestReleasePolicy(slotReleasePolicies: readonly IOIMSlotReleasePolicy[]) ``` `releasesWrittenSlots` is whether the policy can ever release a slot that holds data; a service reads it once at construction and skips the after-write release check when it is false (`OIMSlotAtEmptyReleasePolicy`, `OIMSlotNeverReleasePolicy`: false; `OIMSlotAtUnholdReleasePolicy` and the timed policies: true; `OIMSlotEarliestReleasePolicy`: true when any policy it combines is). `schedulesReleaseOnWrite` is whether a write can make the policy schedule a release; a service reads it once at construction and, when it is false and no `slotStamp` is set, skips `onSlotWritten` and the first-fill `onSlotIdle` on every write (`OIMSlotAfterWriteReleasePolicy`, `OIMSlotAfterIdleReleasePolicy`: true; `OIMSlotAtEmptyReleasePolicy`, `OIMSlotNeverReleasePolicy`, `OIMSlotAtUnholdReleasePolicy`, `OIMSlotAfterUnholdReleasePolicy`: false; `OIMSlotEarliestReleasePolicy`: true when any policy it combines is). `onSlotIdle` is still called when the last subscriber leaves. A policy decides whether and when a slot goes; it does no work itself. A factory, and an `OIMDefaults` (whose `slotReleasePolicy` a factory given it as `defaults` reads as its default), takes ONE through the option `slotReleasePolicy`. With none, the slot owner is built with `OIMSlotAtEmptyReleasePolicy`, so a slot with a value stays for good and an empty one with nothing holding it goes; there is no "no policy" branch on any path. Computed services default to `OIMSlotAtUnholdReleasePolicy`. | Policy | A slot goes | |---|---| | `OIMSlotAfterWriteReleasePolicy` | once its last write is older than `keepAfterWriteMs` | | `OIMSlotAfterIdleReleasePolicy` | once nothing has watched it for `keepAfterIdleMs` | | `OIMSlotAfterUnholdReleasePolicy` | once `keepAfterUnholdMs` has passed since its LAST unhold; a hold taken again inside the window keeps it | | `OIMSlotAtUnholdReleasePolicy` | at the last unhold, even with a value | | `OIMSlotAtEmptyReleasePolicy` | once it has no value and nothing holds it; a computed, never empty, stays while its owner lives | | `OIMSlotNeverReleasePolicy` | never, empty or not; a deleted key's slot stays filed | | `OIMSlotEarliestReleasePolicy` | when the earliest deadline of its members falls due — a `min` over deadlines | **WHICH WRITES MOVE THE WRITE DEADLINE is a strategy of `OIMSlotAfterWriteReleasePolicy`**, `slotReleaseDueFramePolicy`, chosen at construction. `OIMSlotReleaseAutoDueFramePolicy` (the default) makes every write its own frame, so every write moves the deadline. `OIMSlotReleaseManualDueFramePolicy` moves it only for writes made while one of its frames is open: `openSlotReleaseDueFrame()` and `closeSlotReleaseDueFrame()` (which throws by name when no frame is open), or `writeInSlotReleaseDueFrame(write)`, which opens, calls `write` and closes in a `finally`. One Manual object can be passed to several `OIMSlotAfterWriteReleasePolicy` policies with different windows: one frame then moves each slot's deadline by its own collection's window. This is what keeps a local edit or a client-only field from extending data that only a server response should refresh. `write` must be synchronous: a frame closes when the function returns. The release wheels live on the db's collector slot, at most one of each per `OIMDB`: `db.collectorSlot.afterWriteSlotReleaseWheel`, `afterIdleSlotReleaseWheel` and `afterUnholdSlotReleaseWheel`, each an `OIMSlotReleaseWheel` that holds its own slices, timer and clock. A wheel is created by the first policy that needs it, through `mintOIMAfterWriteSlotReleaseWheel(collectorSlot)` (and its after-idle and after-unhold twins), which returns the existing wheel or creates it; until then the field is `undefined`, and a db with no timed policy never pulls the wheel code into a bundle. The clock and the timer are the db's: pass `new OIMDB({ getNowMs, releaseTimer })` to control time (tests), and sweep with `mintOIMAfterIdleSlotReleaseWheel(db.collectorSlot).flush()`. `OIMSlotAtUnholdReleasePolicy` is the zero window and has no collector. A zero window never touches a release queue or a timer: when a slot goes idle with `onSlotIdle` answering `true`, it is released at once if nothing holds it, and a freshly minted slot that is already due goes to the unused-slot collector and leaves at the end of the frame. A window above zero is filed in that policy's own queue. **Two writes keep their slot until the unused-slot collector flushes, and this is deliberate.** (1) a value that the collection's emptiness policy calls empty, and (2) a write under a zero window (`OIMSlotAfterWriteReleasePolicy` / `OIMSlotAfterIdleReleasePolicy` with `0`) on a slot with no subscriber. Released at once, the slot `writeSlotContentByKey` returned would be dead on the next line: a second write to it throws, and handing it to a bucket throws ("an identity handed to a bucket was released") — which is what persist's restore does with the slots `writeInBatch` returns. The collector gives the hold back when it flushes — at the end of `db.flush()`, or when a collector scope (`OIMUnusedSlotCollectorService.INSTANCE.run`) closes — and the slot is released there. ```ts const releasingDefaults = new OIMDefaults({ slotReleasePolicy: new OIMSlotEarliestReleasePolicy([ new OIMSlotAfterWriteReleasePolicy({ keepAfterWriteMs: 60_000 }), new OIMSlotAfterIdleReleasePolicy({ keepAfterIdleMs: 30_000 }), ]), }); ``` ### Two release markers, one per policy `TOIMSlot` carries TWO deadlines, and each release policy moves its own and no other: | Marker | Moved by | Not moved by | |---|---|---| | `releaseDueAfterWriteMs` | every write, under `OIMSlotAfterWriteReleasePolicy` | a subscriber arriving or leaving | | `releaseDueAfterIdleMs` | the first content of a slot with no subscriber, and the departure of the last subscriber, under `OIMSlotAfterIdleReleasePolicy` | a later write, and the give-back of a hold | | `releaseDueAfterUnholdMs` | every last unhold, under `OIMSlotAfterUnholdReleasePolicy` | a write | `-1` means unset. A slot goes on the SOONEST of those that are set — each marker is an eviction deadline, so whichever says "out" first decides — and a hold outranks both, so a subscribed entity slot is never taken for age and goes at the give-back. **ONE NUMBER CANNOT CARRY BOTH POLICIES.** A single field cannot say which event is allowed to move it: a write arriving after the subscriber left would push the deadline out and destroy the idle policy's verdict, and the last subscriber leaving after a write would destroy the write policy's. Both directions are pinned by `collector/tests/which-release-marker-each-collector-may-move.test.ts`; collapse the two markers into one and six of its nine cases go red. **The release policy's `isSlotReleasable(slot)`** is what the release guard asks for a slot that is not empty and has nothing left keeping it. `true` releases it now; `false` keeps it, and a policy with a finite deadline has itself filed the slot into its release queue (a marker of `-1` is kept with nothing scheduled). An **empty** slot is released without asking, and a service given no release policy keeps a non-empty slot. `OIMComputedService` defaults its policy to `OIMSlotAtUnholdReleasePolicy`, which always answers `true`, so a derivation nothing refers to goes at once. `OIMSlotEarliestReleasePolicy` asks every member and answers `true` if any does. **AN IDLE WINDOW OPENS IN EXACTLY TWO PLACES, AND NOWHERE ELSE:** 1. **when the slot first gets content with no subscriber** — the write that takes it from empty to filled, in `settleEmptiness`. A slot minted empty (a `getSlotByKey` miss) is on NO clock and costs the queue nothing; 2. **when the LAST SUBSCRIBER leaves** — `OIMSlotOwner.unsubscribeFromSlot` empties `slot.effects` and runs the idle step, which opens one. Both ask the policy's `onSlotIdle(slot)`; under `OIMSlotAfterIdleReleasePolicy` it stamps `releaseDueAfterIdleMs` and files the slot into the policy's queue. An **empty** slot gets no window, and the release guard takes it without asking a clock at all. **A GIVE-BACK OPENS NONE.** `OIMSlotOwner.unholdSlot` drops `holdCount` and runs `releaseSlotIfUnheld`; it stamps no marker. A slot whose window already ran out is therefore taken at the give-back and not one window later. **A HELD SLOT IS OFF THE CLOCK.** A sweep that meets one calls `releaseSlotIfUnheld`, which stops at its first guard, `holdCount > 0`, and decides nothing — and the queue has taken the slot off its slice, so nothing re-files it. The give-back is where the guard is asked again. ### The release wheels Each of `OIMSlotAfterWriteReleasePolicy`, `OIMSlotAfterIdleReleasePolicy` and `OIMSlotAfterUnholdReleasePolicy` files into its own release wheel, and the difference between the wheels is WHICH MARKER each reads and writes — injected at construction, so there is no flag and no branch on the sweep path. A wheel is an aggregate: its slices, its timer and its clock are fields of the object. ```ts signature abstract class OIMSlotWheel { readonly getNowMs: () => number; getNextSliceNumber(): number | undefined; // the nearest filed slice, or undefined sweepUpToSliceNumber(upToSliceNumber: number): void; flush(): void; // sweeps what is due now and re-arms the timer cancelAllSlots(): void; // takes the timer down and drops every filing } class OIMSlotReleaseWheel extends OIMSlotWheel { constructor(options: TOIMSlotReleaseWheelOptions); // { getNowMs, timer, errorPolicy, getReleaseDueMs, setReleaseDueMs, releaseScheduledSlotFlag } readonly getReleaseDueMs: (slot: TOIMSlot) => number; markSlotReleaseDue(slot, keepMs): number; // stamps now + keepMs on this marker, returns now markSlotReleaseDueNow(slot): void; // the marker is now; an unheld, unwatched slot goes at once scheduleSlotRelease(slot, nowMs): void; // files the slot at its marker; -1 or already filed files nothing isSlotReleasable(slot): boolean; // due now; if not yet, files it on the wheel cancelSlotRelease(slot): void; // no-op for a slot whose marker is -1 isSlotReleaseScheduled(slot): boolean; } type TOIMCollectorSlot = { readonly unusedSlotCollectorSlot: TOIMUnusedSlotCollectorSlot; readonly slotWheelOptions: TOIMSlotWheelOptions; // the db's clock, timer and error policy afterIdleSlotReleaseWheel: OIMSlotReleaseWheel | undefined; // created on first use afterWriteSlotReleaseWheel: OIMSlotReleaseWheel | undefined; afterUnholdSlotReleaseWheel: OIMSlotReleaseWheel | undefined; }; mintOIMAfterWriteSlotReleaseWheel(collectorSlot): OIMSlotReleaseWheel // and …AfterIdle…, …AfterUnhold… ``` The clock (`getNowMs`, default `Date.now`), the timer (`releaseTimer`, default an unref'd `setTimeout`) and the `errorPolicy` (default `OIMLogAndContinueErrorPolicy.INSTANCE`) are `OIMDB` options, shared by the channel, every release collector of that db and every `OIMSlotRefetchWheel` built on it. A release that throws inside a hand-called `flush` throws to that caller; one that throws on the collector's own timer tick has no caller and goes to the db's `errorPolicy`. So one error policy on the db routes every error through one place: ```ts const oneSinkDb = new OIMDB({ errorPolicy: new OIMThrowAtOnceErrorPolicy() }); const idleReleasingDefaults = new OIMDefaults({ slotReleasePolicy: new OIMSlotAfterIdleReleasePolicy({ keepAfterIdleMs: 30_000 }), }); ``` | Wheel | Reads | What renews it | What does not | |---|---|---|---| | `afterIdleSlotReleaseWheel` | `releaseDueAfterIdleMs` | the first content of a slot, and the give-back of the last hold | a later write | | `afterWriteSlotReleaseWheel` | `releaseDueAfterWriteMs` | every write, under its policy | a subscriber arriving or leaving | | `afterUnholdSlotReleaseWheel` | `releaseDueAfterUnholdMs` | every last unhold | a hold taken again inside the window | **A CONSUMER MAY RUN BOTH, AND THEY SHARE NOTHING.** Each wheel has its own slices and its own scheduled run. Whichever deadline falls due first takes the slot, and nothing has to be reconciled: `OIMSlotEarliestReleasePolicy` answers a `min` over its members' deadlines, so a sweep of either queue reaches the same verdict. **NEITHER MEANS UNREAD.** No read is seen and no door reports one: an identity a consumer subscribed to is in use whatever else is true of it. An effect takes a HOLD on each root it was given — `OIMEffectService.INSTANCE.createEffect` calls `root.owner.subscribeToSlot(root, …)`, which holds, for every slot in `sourceSlots` and every computed source — so the hold is the whole signal, and neither collector reads `slot.effects`. **The deadline is only consulted on a slot that is NOT empty.** The slot owner's `releaseSlotIfUnheld` returns at once on a slot that is RELEASED or queued in an open batch, and on a slot that is not empty under a policy that does not release written slots; then it checks `holdCount > 0`, `slot.owner !== this` and `columnSlotStore !== undefined`, and only then — on a slot that is not empty — asks the policy's `isSlotReleasable`; an empty slot asks `isEmptySlotReleasable` instead, which every policy but `OIMSlotNeverReleasePolicy` answers `true`. So only `OIMSlotNeverReleasePolicy` keeps an identity that holds nothing. **A release that falls inside a flush happens at once.** A slot at `holdCount` 0 has no subscriber (a subscription is a hold), so clearing its value wakes nobody, and a release notifies no content-change listener. When the last hold goes during a frame — an effect body disposing another effect, say — the slot is released there, whatever its kind. A later `holdSlotByKey` for the same key in that flush mints a new slot. *The `owner !== this` line costs no lookup. A KEYLESS slot — a single's, filed in an `OIMSingleSlotStoreService` store — goes through the same guard under its service's policy: an emptied single bucket nothing holds is released like a keyed one, and the single service's `getSingleSlot(storeSlot)` mints a fresh slot on the next read.* ### Two consequences to generate code against **(a) An entity slot watched through an expired sweep gets a WHOLE window when the subscriber leaves, not an immediate release.** The seconds it spent watched were not idle ones, so `dispose` on a slot whose deadline passed long ago stamps a whole idle window afresh on `releaseDueAfterIdleMs` and the release comes one whole window later. **A give-back is NOT that moment**: `unholdSlot` stamps nothing, so a slot held through an expired sweep goes at the give-back. ```ts const effect = effectService.createEffect(db, () => { paint(slot.entity); }, [slot]); // …the window passes, sweeps run, nothing happens to this slot… effectService.disposeEffect(effect); isOIMSlotReleased(slot); // false — a whole new window starts here ``` **(b) A cascade is taken in ONE sweep, not one window per level.** The sweep releases the stale index, which gives back one reference per entity slot it named, and each entity slot whose own window already ran out is taken by the ordinary guard the instant that reference departs. Pinned by `collector/tests/what-a-stale-index-takes-with-it.test.ts`, `…/what-an-identity-nobody-subscribed-to-costs-after-a-while.test.ts` and `…/what-a-subscribed-row-costs-the-release-clock.test.ts`. ### The release guard, and who fires it **THE WHEEL DECIDES AT A DEADLINE, NOT THE OWNER.** `OIMSlotReleaseWheel.sweepUpToSliceNumber`, per slot in a slice at or below the one due: 1. its bit is clear → a stale entry, skip it; `isOIMSlotReleased(slot)` → skip it; 2. its own marker, read through `getReleaseDueMs(slot)` — the ONE field this wheel answers for; 3. `-1` → the slot is dropped from the wheel: this policy does not claim it; 4. a moment still in the future → the wheel **re-files the slot itself**, into `getOIMSliceOfMs(getReleaseDueMs)` through its own slice arithmetic; 5. a moment already passed → `slot.owner.releaseSlotIfUnheld(slot)`, which asks the policy's `isSlotReleasable` and so declines when the other policy still keeps the slot, or when the slot is held. **INVALIDATING IS MARKING THE DEADLINE NOW.** `wheel.markSlotReleaseDueNow(slot)` sets this wheel's marker to now and hands the slot to `slot.owner.releaseSlotIfUnheld(slot)` at once: a slot nothing holds or watches goes with its data; a held or watched slot stays, keeps its data, and goes the moment its last hold or subscriber leaves, because its deadline is already past. The next marked write moves the marker a window ahead again. It writes no content, so it wakes no effect. The owner files nothing from inside a sweep. It **opens** a window on its own events, through the policy's `onSlotIdle` — when a slot first gets content, and when the last subscriber leaves — and `onSlotUnheld` on the give-back of the last hold. **A SLOT ALREADY ON A QUEUE STAYS WHERE IT IS.** `scheduleSlotRelease` of a slot that is already filed moves nothing: the sweep re-reads the deadline when that slice comes due and re-files the slot then (the timing-wheel lazy re-insertion). So a write to a queued entity slot costs the queue one bit test, not an unfile and a refile. A deadline only ever moves later — each policy adds a fixed window to a clock that does not go back — so the slice a slot already sits in is never later than its deadline. `releaseSlotIfUnheld(slot)` is the guard, and it releases only when all of `isOIMSlotReleased(slot)` is false (checked first), the slot is not queued in an open batch, the slot is empty or its policy releases written slots, `holdCount === 0`, `slot.owner === this`, the slot has no column slot store (`columnSlotStore === undefined`), and the policy's `isSlotReleasable` answers `true` (`isEmptySlotReleasable` for an empty slot). It is the one release door: a slot queued in an open batch is refused there and released after the batch closes. **A held slot stops at `holdCount > 0`** and nothing happens to it. On a slot that is not empty with time still owed, `isSlotReleasable` answers `false` and the policy files the slot into its queue at its own marker, so a filing can neither shorten nor extend a deadline. That is the path from `unholdSlot` and from a write, never from a sweep, which had already re-filed at step 4. Releasing hands the slot to the content service's `releaseSlotContent` (which gives back what the content held), calls the policy's `cancelSlotRelease(slot)`, unfiles the key through `slotFilingService.delete(store, slot)`, sets the RELEASED flag in `slot.slotFlags`, and marks the slot empty. The `owner` is NOT cleared — the slot keeps pointing at the object that let it go, which is what makes `slot.owner !== this` a usable guard afterwards. The RELEASED flag (`isOIMSlotReleased(slot)`) is the other half of that protocol, and the two sides are opposite: - **Releasing an already-released slot is SILENT.** `releaseSlotIfUnheld` reads `isOIMSlotReleased(slot)` and returns; it does not throw. A sweep meeting a slot something else already let go must not raise. - **Trying to WORK with a released slot throws by name.** `assertNotReleased` guards the content services' write doors (`writeSlotContent`, `clearSlotContent`, `updateEntity`, `markEntityChanged`, `addBucketMemberSlot`, `removeBucketMemberSlot`, `markContentChanged`) and the reference doors (`holdSlot`, `unholdSlot`, `subscribeToSlot`, `unsubscribeFromSlot`). The refusal message starts `This identity was released:`. ### The wheels and the unused-slot collector ```ts signature mintOIMAfterWriteSlotReleaseWheel(db.collectorSlot) // and …AfterIdle…, …AfterUnhold… new OIMSlotRefetchWheel(db: OIMDB, options: TOIMSlotRefetchWheelOptions) // { slotRefetchListener }; clock, timer, error policy from db.collectorSlot.slotWheelOptions OIMUnusedSlotCollectorService.INSTANCE createOIMUnusedSlotCollectorSlot(): TOIMUnusedSlotCollectorSlot ``` **A wheel is the clock.** `OIMSlotWheel` is its own scheduled slot (a `TOIMFlushSchedulerSlot`, driven by `OIMFlushSchedulerService` by composition, not inheritance): `flush()` sweeps what is due and re-arms the timer to the next deadline. `cancelAllSlots()` takes the timer down and drops every filing; the next filing arms it again. The release wheels take the clock (`getNowMs`) and the timer from the db, so a test drives them through `new OIMDB({ getNowMs, releaseTimer })`. The default timer is a `setTimeout` that calls `unref` where the platform has it, so an idle Node process is not held open, and caps a delay at `2^31 − 1` ms (about 24.8 days), so a longer window still fires instead of overflowing. **A wheel files slots into time slices**, not one entry each. `getOIMSliceOfMs(ms)` is `Math.floor(ms / OIM_SLICE_LENGTH_MS)` and `OIM_SLICE_LENGTH_MS` is `1024`, so every slot due inside the same ~1s slice shares one array and one timer. A release wheel's sweep takes every slice up to and including the current one (`getSweptSliceNumberAt(now)` is `getOIMSliceOfMs(now)`), and within a slice it releases only the slots whose deadline has passed: a manual `flush()` releases a slot past its deadline even inside its slice. The timer arms for the end of the next filed slice, so on the timer alone a slot goes never before its deadline and at most one slice (1024 ms) after it. (`OIMSlotRefetchWheel` sweeps only ended slices, `getOIMSliceOfMs(now) − 1`.) **WHETHER A SLOT IS ON A RELEASE WHEEL IS A BIT ON THE SLOT, NOT A MAP.** Each of the three release wheels of a db owns one bit of `slot.slotFlags` (`releaseScheduledSlotFlag`, `4`, `8`, `16`), so a slot can sit on all three at once, once on each. Filing pushes the slot onto its slice's array and sets the bit; cancelling clears the bit and leaves the entry, which the sweep skips when its slice comes due. A cancelled slot therefore keeps its slice named by `getNextSliceNumber` until that sweep. A slot filed during a sweep into a slice the sweep is still walking — the wheel's own re-file at step 4 of a slot from the current slice not yet due, or one a release makes — is held aside and, when the sweep ends, filed into its OWN slice. The sweep never meets it twice, so it cannot loop, and the timer then arms for the end of that slice. **`OIMSlotRefetchWheel` is a wheel of slots due a refetch at an explicit time.** It computes no deadline, keeps no bit and no field on the slot: `scheduleSlotRefetchAt(slot, atMs)` files an entry into the slice of `atMs`, every call files one more. Its sweep takes only slices that have fully elapsed, skips released slots, and calls `slotRefetchListener.onSlotsRefetchDue(slots)` ONCE per sweep with every slot that came due, watched or not (a slot that is held but has no effect at that moment is handed over too); the array is reused and emptied after the call, so a listener does not keep it. Moving a refetch earlier is another `scheduleSlotRefetchAt`; the listener decides from its own data whether an entry is current, so an early or duplicate entry is skipped there. The wheel is created by whoever needs it, not by the db, but on a db: `new OIMSlotRefetchWheel(db, { slotRefetchListener })` takes the db's clock, timer and error policy (`db.collectorSlot.slotWheelOptions`), like the release wheels. **The unused-slot collector** has nothing to do with time. It is the one that makes `getSlotByKey(storeSlot, key)` safe: `OIMUnusedSlotCollectorService.INSTANCE.holdSlotUntilFlush(unusedSlotCollectorSlot, slot)` takes a hold, `flush(unusedSlotCollectorSlot)` gives every tracked hold back. `open` / `close` nest a scope and `run(unusedSlotCollectorSlot, body)` is the `try/finally` form; `flush` does nothing while a scope is open, so an outer scope's slots survive an inner one closing. `close` with no open scope throws by name. The channel flush flushes the db's unused-slot collector slot (`db.collectorSlot.unusedSlotCollectorSlot`) once the frame is delivered, which is why a turn of work that only read through `getSlotByKey` leaves nothing standing after `db.flush()`. **AN ARENA IS AN UNUSED-SLOT COLLECTOR SLOT THAT THE CALLER CREATES.** `createOIMUnusedSlotCollectorSlot()` is exported, so a consumer who wants to FORCE-CACHE a derivation makes its own and ends it when it chooses. The db's collector slot is the default, not the only one: ```ts const unusedSlotCollectorSlot = createOIMUnusedSlotCollectorSlot(); OIMUnusedSlotCollectorService.INSTANCE.holdSlotUntilFlush( unusedSlotCollectorSlot, rankService.getSlotByKey(ranks, 'c1'), ); // held until this arena says otherwise db.flush(); // the db's collector lets its own go; this one does not // … the derivation is still there, and still the same object … OIMUnusedSlotCollectorService.INSTANCE.flush(unusedSlotCollectorSlot); // now it goes, and so does everything only it held ``` **TRACKING ONE DERIVATION KEEPS ITS WHOLE SUBTREE, and no caller walks a tree to get that.** A computed takes a hold on each of its own direct sources at the mint and gives them back when it is released, so an arena holds the top and the chain holds itself. Pinned by `collector/tests/what-a-named-arena-keeps-cached.test.ts`: the derivation survives a settle, is the SAME instance on the next read (built once), is rebuilt only after the arena is flushed, and `open`/`close` nest so an inner scope ending drops nothing an outer one stands on. `@oimdb/react`'s `useOIMSelector` does not use an arena: its subscription holds the slots its function read, from commit until unmount or until the next commit moves them. ```ts signature type TOIMTimer = (run: () => void, inMs: number) => TOIMDisposer; ``` `TOIMTimer` is how a host schedules a collector's run. It is given the body and a delay and hands back the cancel. `OIMFlushSchedulerService` is the abstract base that owns the schedule/cancel around it, on a `TOIMFlushSchedulerSlot` (`timer`, `scheduledCallback`, `timerDisposer`): protected `schedule(flushSchedulerSlot, delayMs)` does nothing if a scheduled run is already standing, and `cancelSchedule(flushSchedulerSlot)` drops it. **The standing run is the callback itself**: the slot keeps the one handed to the timer, and a callback that is no longer that one — a run the host could not cancel, still queued after a manual flush — returns without touching anything, so it neither flushes early nor lets the next request arm a second wake. The channel schedules with `0`. The release collectors read the clock once, schedule to the next slice, and cancel and re-schedule only when a shorter window arrives; the deadline they compare against is reset by `cancelSchedule`. Pass a `TOIMTimer` of your own to drive a collector off a frame callback, a worker message or a test clock instead of `setTimeout`. ### A fork is a strategy, not a decision Both strategies ship, chosen at **construction**, so no branch survives onto a hot path. There is no `if (inPlace)` anywhere in the engine. | Fork | Strategies | |---|---| | how a write lands | `createOIMInPlaceEntityWriter()` / `createOIMReplacingEntityWriter()` | | how a bucket holds slots | `OIMSetBucketContentService` / `OIMPositionalArrayBucketContentService` (the positions are the caller's) | | what naming a slot records | `bucketMemberSlotsArrayService: OIMBucketMemberSlotsArrayService` (one per mention, the default) / `new OIMBucketUniqueMemberSlotsArrayService()` (one per slot), on either array bucket | | which writes re-sort a sorted list | `sortColumns` (only a write changing one of them on a member) / `comparator` alone (any member write), the options of `createOIMSortedComputedService` | | how a key is addressed | `OIMScalarKeyTreeWalk.INSTANCE` / `OIMCompositeKeyTreeWalk.INSTANCE` | | when a slot may go | `OIMSlotAfterIdleReleasePolicy` / `OIMSlotAfterWriteReleasePolicy`, either or both | | who decides a bucket's slots | a bucket collection (`createOIMSlotCollectionService` over a bucket content service, the caller) / an index (`createOIMSlotCollectionIndexService`, filed from the entity's own key) | **One strategy per kind per app.** A V8 call site is shared by every service that runs the same engine code, so mixing strategies of one kind in one process shows that site several hidden classes or functions. Up to four is polymorphic: V8 still caches each one and can still inline (`--max-valid-polymorphic-map-count`, default 4). Five or more is megamorphic: no per-site cache and no inlining through it. The kinds that count: release policies (the `IOIMSlotReleasePolicy` strategies), set-driven vs array-driven buckets and indexes, entity writers (`createOIMInPlaceEntityWriter` / `createOIMReplacingEntityWriter`) and `TOIMEntityInserter`, `TOIMSameValueGuard`, `IOIMSlotEmptinessPolicy`, and `TOIMChannelScheduler`. Two or three of one kind is fine; five release policies in one process is not. The pair `alt.slot-shape.three-shapes-against-one-at-the-write` measures three slot shapes at one write site against one, and its ratio is close to 1; no pair measures five. Generate code with one strategy per kind unless the task names a second. ### Every store slot has a channel — read this before generating code `createStoreSlot(db)` stamps the db's `defaultChannelSlot` on the store slot, and every write to its slots is reported to that channel. No service holds a channel; there is no `channel` option and no `unusedSlotCollector` option: ```ts const cardContentService = createOIMEntityContentService(); const handBuiltCardService = createOIMSlotCollectionService({ slotContentService: cardContentService }); handBuiltCardService.createStoreSlot(db); ``` A single entity is `createOIMSingleSlotService({ slotContentService: createOIMEntityContentService() })`, and its store slot takes the db's channel too and always reports. ### A bucket's slots are the caller's A bucket's slots are a fact about the **response** being composed — a search result, a page, a window — and **no column can express absence**. So a bucket collection is manual, and `slot.clearSlotContent()` does not take a slot out of any bucket. Use an index (`createOIMSlotCollectionIndexService`) when the slots are determined by the entity's key value, and an index should maintain buckets only for keys being held. --- ## The runtime: the channel slot There is no channel class. A channel is the struct `TOIMChannelSlot`; every operation is on the stateless `OIMChannelService.INSTANCE` and takes the channel slot first. An `OIMDB` builds its `defaultChannelSlot` from its own options, and every store slot created with `createStoreSlot(db)` carries it as `storeSlot.channelSlot`. A test that needs a second, independent channel makes a second `new OIMDB()`. ```ts signature new OIMDB(options?: TOIMDBOptions) type TOIMDBOptions = { channelScheduler?: TOIMChannelScheduler | null; // absent or null = you flush by hand errorPolicy?: IOIMErrorPolicy; // absent = OIMLogAndContinueErrorPolicy.INSTANCE onBeforeFlush?: () => void; // start of the flush, before the frame; READ ONLY, a write is refused getNowMs?: () => number; // the release collectors' clock; absent = Date.now releaseTimer?: TOIMTimer; // the release collectors' timer; absent = an unref'd setTimeout createSchemas?: (db: OIMDB) => TSchemas; // called once, at the end of the constructor }; db.clock // TOIMChannelClock, the same object as db.defaultChannelSlot.clock db.addSlotReleaseListener(listener) // TOIMDisposer; listener.onSlotReleased(slot) hears every released slot and column slot, slot.data still on it db.claimSlotDataCell() // number: a cell index of slot.data that is yours alone, 0, 1, 2… per db db.collectorSlot // TOIMCollectorSlot db.defaultChannelSlot // TOIMChannelSlot db.schemas // TSchemas: what createSchemas returned; undefined without it db.flush() // OIMChannelService.INSTANCE.flush(db.defaultChannelSlot) db.createEffect(body, sourceSlots?, { lazy? }) // TOIMDisposer; see "A database with schemas" db.dispose() // OIMChannelService.INSTANCE.dropChannelSlot(db.defaultChannelSlot): no later flush delivers interface IOIMErrorPolicy { onErrorCaught(error: unknown): void } OIMLogAndContinueErrorPolicy.INSTANCE // console.error; the flush goes on new OIMLogAndContinueErrorPolicy({ onError?: (error: unknown) => void }) // console.error, then onError new OIMThrowAtOnceErrorPolicy() // throws the first error out of the flush ``` `OIMThrowAtOnceErrorPolicy` throws the first error out of `flush()`, but the end of a flush still runs in `finally` blocks — the unused-slot collector's flush, then the after-each-flush handlers — and a throw there replaces the error already on its way out: the caller sees the later one. **What the error policy covers** — every error with no synchronous caller to throw to: effect bodies and their cleanups, `onBeforeFlush`, after-each-frame and after-each-flush handlers, the unused-slot sweep at the end of a flush, and a release collector's own timer tick. A call that has a caller — a write, a hand-called collector `flush` — throws to it. `channelSlot.errorPolicy` is the instance the channel reports through; it is the db's `errorPolicy`, which the release collectors share, so one policy answers for the whole database. **The default digests and logs**: each throw goes to `console.error` and then to `onError` (where Sentry or the devtools registry plugs in), and the flush finishes every other effect and handler. `OIMThrowAtOnceErrorPolicy` throws the first error out of `flush()` at once; the effects the frame had not reached yet stay queued and run at the next flush. **An effect whose body or cleanup threw has not taken the change it woke for**: its `ranAtRevision`/`ranAtEpoch` are written only after the body returns, so its next wake — any later write to its roots, even one through a computed that settles to the same value — sees that change as still new and runs it again. It is never re-run inside the frame it threw in (each pending effect runs once per frame, and writes are refused during a flush), so a body that always throws costs one run and one caught error per wake, not a loop. A cleanup that disposes its own effect stops the body that would have run after it. **A computed is stamped fresh only after its derive and its `sameValueGuard` both returned**: if either threw, the next read derives again. A computed with no sources at all derives on its first read. **A computed whose value changed is stamped with the revision of its newest source**, not with the clock at the moment it was read — so whether an effect over it owes a run depends only on its sources, never on an unrelated write that moved the clock. An effect born after a computed's source changed is owed nothing for it, as one over the root itself. **A throw does not stop the channel asking for frames**: the request flag is cleared before `onBeforeFlush` runs, and a write that finds effects still pending with no frame requested asks for one — so a frame aborted by a throw is followed by a frame at the next write, under either policy. **A throw in one release of a sweep leaves the rest of that slice on the release clock**; the next sweep takes them, and the clock is re-armed even when the sweep threw. Code that maintains DERIVED state — an index's `selectKey`, an emptiness check — is not under the policy: a throw there leaves the state consistent and is thrown in either mode. **An index whose `selectKey` throws on an entity files that entity slot under no key** — it leaves the bucket its old key named — and finishes the rest of the write or batch before it rethrows the first error; the entity stays in its store slot, and the next write the index accepts files it again. A NEW entity refused by a single write is withdrawn from the store slot instead. This costs nothing on a write where nothing throws. **A bucket minted by a scan of the source moves an entity slot out of the bucket its stored key still names** — an entity mutated by hand whose `markEntityChanged` has not run yet — so it ends in one bucket, not two; the scan pays one read of the stored key per entity slot it files, and the move keeps the entity slot held until the next flush so its last hold never goes mid-mint. Inside a flush, where writes are refused, the move is skipped. Every door below is on `OIMChannelService.INSTANCE` and takes the channel slot first. | Door | Signature | |---|---| | `flush(channelSlot)` | `void` — the only place anything is delivered; from the TAIL of a flush it returns having done nothing. `db.flush()` is this on the default channel | | `scheduleEffectRun(channelSlot, effect)` | `void` — only enqueues the effect on this channel's queue and asks for a flush. It sets no bit and does not dedupe: the caller first calls `OIMEffectService.INSTANCE.markEffectRunScheduled(effect, isSourceCheckOwed)`, which sets the RUN_SCHEDULED bit of `effect.effectFlags` (and SOURCE_CHECK_OWED, `OIM_EFFECT_FLAG_SOURCE_CHECK_OWED`, when asked) and answers `false` when the effect is already queued. Effects are made by `OIMEffectService.INSTANCE`, not here; `createEffect` calls this when the open batch already has writes and no frame is running, so an effect created inside a running frame is never queued | | `subscribeAfterEachFrame(channelSlot, handler)` | `TOIMDisposer` — after every frame, but still INSIDE the flush: a write from it is refused | | `subscribeOnceAfterFrame(channelSlot, handler)` | `TOIMDisposer` — the same phase, told **once**; see below | | `subscribeAfterEachFlush(channelSlot, handler)` | `TOIMDisposer` — told once the flush has FULLY ended: after the after-each-frame phase and after the unused-slot collector of the db is flushed. For what may live only one frame — `OIMBucketCommands` empties its render scripts here | | `isRefusingWrites(channelSlot)` | `boolean` — `channelSlot.isFlushing`; refusal is per channel | | `assertNotFlushing(channelSlot)` | `void` — throws if the channel is flushing or its frame is running, i.e. for the whole of a flush | | `write(channelSlot, slot)` | `void` — asks `assertNotFlushing`, then marks and queues | | `writeWithoutFlushCheck(channelSlot, slot)` | `void` — the same marking and queueing WITHOUT the guard, for a door that already refused. Who may call it is pinned by `tests/who-may-write-without-asking-the-channel.test.ts`; a caller not on that list fails the suite | | `dropChannelSlot(channelSlot)` | `void` — kill the channel whole; see below | | `isChangedInCurrentFrame(channelSlot, slot)` | `boolean` — whether the slot was written after the last frame ended, i.e. in the frame being collected now; compares `slot.changedAtRevision`/`changedAtEpoch` with the clock reading the last frame closed at. `write` uses it to queue a slot's effects once per frame, and a source-tracking effect to see that a source it just started reading already moved. (`OIMBucketCommands` does not use it: a script is stale when the frame opened after the script started, its own `isScriptStale`.) | The channel slot's own fields that a caller reads: `frame` (`TOIMChannelFrame`, `{ isRunning, openedAtRevision, openedAtEpoch, … }`; a frame carries no number, the clock reading it opened at is its boundary), `clock` (`TOIMChannelClock`, `{revision, epoch, unheldSlotWriteCount}`, shared by every channel of one db; an epoch holds `OIM_REVISIONS_PER_EPOCH` (2^30) revisions, so the counter stays a V8 small integer under pointer compression; the epoch is an int32 that wraps, compared as `(epoch − sinceEpoch) | 0`. `unheldSlotWriteCount` counts writes to slots nobody held, which move neither the revision nor a stamp, and wraps to `0` at the same 2^30; a reader compares it for inequality only), `collectorSlot`, `errorPolicy`, `isFlushing`. Everything else on it is engine state. ### A subscription hears only what happens after it `effectService.createEffect` is told about changes made **after** the call and about nothing before them. This holds for every kind of source — an entity slot, a column, a bucket, a computed — and a batch does not soften it: writes accumulate until `flush()`, and subscribing behind a write of the still-open batch is subscribing after it. ```ts cardService.writeSlotContentByKey(cards, 'a', { id: 'a', title: 'A', rank: 1, deck: 'spades' }); const entitySlot = cardService.getSlotByKey(cards, 'a'); effectService.createEffect(db, () => { /* NEVER runs for the upsert above */ }, [entitySlot]); db.flush(); // A first value is `createAndRunEffect`'s job, not `createEffect`'s: effectService.createAndRunEffect(db, () => { paint(entitySlot.entity); }, [entitySlot]); // runs now ``` A later write in that same batch IS delivered — "after I subscribed" is decided by the revision (`clock.revision` advances on every write), not by the frame number, which is one number for the whole batch and cannot separate the two. ### `subscribeOnceAfterFrame(channelSlot, handler)` Told after **one** frame — the first that ends after the call — and then gone. The place that asks decides which frame that is. ```ts effectService.createEffect(db, () => { paint(slot.entity); // the tail of THIS frame, after every other effect of it OIMChannelService.INSTANCE.subscribeOnceAfterFrame(channelSlot, () => { measureAndScroll(); }); }, [slot]); ``` - **Registered from inside an effect body it runs in the tail of that very frame**, after every other effect of it. The after-each-frame phase settles who it owes when the phase *begins*, and the drain is before that — so a handler added from the drain falls on the "owed" side. That is the whole reason the method exists: a consumer whose work needs the **settled** screen (a measurement, a scroll to an item that moved, a size written back) asks from inside its effect and is answered at the end of that same frame. - Registered from the after-each-frame phase itself, it sits that frame out and is told after the next one — the phase had already settled who it owed. - **It is not `subscribeAfterEachFrame` plus a disposal.** The effect runs again next frame and registers again, so a standing handler accumulates one per run: `tests/a-handler-that-wants-one-frame-and-not-every-frame.test.ts` measures the one-shot at 1, 2, 3 calls over three frames against the standing handler's 1, 3, 6. - It comes off **before** its body runs, so a handler that throws is not left standing for the next frame; the throw is reported by the frame that ran it. - One list, not two: it goes into the same set at the same phase, so one-shot and standing handlers are called in registration order among each other. ### Batches: `openBatch` / `closeBatch` / `writeInBatch` on a collection There are no bulk writes. A load or a sync is a loop of single writes, and a writable collection service (`OIMWritableSlotCollectionService`: an entity or a hand-made bucket collection) wraps it in a batch on its store slot. An index service and a computed service have no batch: ```ts cardService.writeInBatch(cards, () => { for (const card of payload) cardService.writeSlotContentByKey(cards, card.id, card); }); ``` - `openBatch(storeSlot)` / `closeBatch(storeSlot)` nest by a count on the store slot; `closeBatch` with no batch open throws. `writeInBatch` is the `try/finally` form and returns what its function returns. - **What the batch changes is who hears the writes, and when.** A content-change listener on the store slot (an index on the collection) hears every write of the batch in ONE call, `onManyContentsChanged`, when the outermost batch closes. Code inside the batch reads the index as it was before the batch. - A batch a listener opens on the same store slot while that delivery runs gets its own queues and is delivered once, when it closes; it does not join the batch being delivered. - Effects are not batched by it: every write marks its slot on the channel as usual, and the frame delivers each identity once whatever the batch did. A `flush()` inside a batch is allowed; the index catches up when the batch closes. - A single write outside a batch tells the index at once, and is not rolled back: the slot is filed first and the index is told after, so an index that throws leaves the write in place and the throw reaches the caller. ### `dropChannelSlot(channelSlot)` Kills the whole channel on the caller's word that **nothing is subscribed to anything in it**. The engine does not verify that: checking would mean asking every slot whether its `effects` list is empty, which is exactly the walk the method exists to skip — the check IS the cost, which is what the suffix of its name says. ```ts // every subscriber disposed, the screen is going away db.dispose(); // OIMChannelService.INSTANCE.dropChannelSlot(db.defaultChannelSlot) // drop your own references; every slot, store and derivation goes with them ``` - It empties the effect queue and the after-each-frame and after-each-flush handlers, cancels the scheduled flush and the db's three release wheels (`cancelAllSlots`), sets the `dropped` flag, and returns. **Nothing walks a slot to ask who is subscribed to it** — that is the walk the name refuses. - **It does flush the unused-slot collector**, which is the channel's own debt and not a walk of your graph: every getter that minted an identity this frame filed a hold there, and a flush was the only thing that ever gave those back. Since `flush` returns on the flag, a drop that skipped this would pin every such identity for as long as the db's collector slot lives. A drop made from INSIDE a flush leaves it to that flush, which still runs it. - The flag exists because `TOIMChannelScheduler` gives back no handle, so a frame asked for before the call still arrives; `flush` returns on it. - **The flag is read in TWO places.** `flush` returns on it, and so does the private `requestFlush` — which `write` reaches at the end of every write that got past the per-frame coalescing guard with at least one dependent to schedule, and which `scheduleEffectRun` reaches when `OIMEffectService.INSTANCE.createEffect` finds a source that already moved in the open batch outside a running frame. A dropped channel therefore stops asking its host for frames instead of arming a timer whose flush is guaranteed to return on the flag. - **A write after the call is not refused, and it is not unnoticed either.** It passes `assertNotFlushing`, advances the clock, stamps the slot and schedules the dependents it finds — and then asks for no frame, so nothing it scheduled is ever delivered. Do not read "not refused" as "still works". - Called with subscribers still standing, their bodies simply never run again — no throw and no report. That is the bargain the name states. - There is no checked sibling. One would cost the walk this avoids; if a diagnostic is ever wanted it ships under its own name, not as an option here. ### Frame rules - **Delivery is coalesced per identity per frame.** - **Writes during a FLUSH throw — not just during the frame body:** `OIMChannelService: writes are refused for the whole of a flush — onBeforeFlush and every after-each-frame handler included, …` and then tells you to write after `flush` returns. `flush` raises `channelSlot.isFlushing` before `onBeforeFlush` and lowers it in its `finally`; `assertNotFlushing` throws on `isFlushing` or `frame.isRunning`, so all three phases are refused. Refusal is per channel: a flush of one db's channel does not refuse a write to another db's. - **Each door asks once, then writes through `writeWithoutFlushCheck`.** A content service door opens with `assertWritable`, which asks the channel, and every write it makes after that asks nothing. The per-entity ask is NOT removable and stays — user code runs inside a door (`index.selectKey`, `slotEmptinessPolicy.isEmpty`, an `IOIMEntityWriter`) and can call `flush()`, so each entity is a new question. What went is the SECOND and THIRD ask of the same entity. - **`flush` during a frame throws:** the message says a frame is already running, and a second one inside it would end the first. - **`flush()` from the TAIL of a flush** (`onBeforeFlush`, an after-each-frame handler, or anything either called) returns having done nothing. Not a deferral: one flush spends exactly one frame however many handlers ask for another. - **There is NO door that writes from inside a flush.** `subscribeAfterEachFrame`, `subscribeOnceAfterFrame` and `onBeforeFlush` all run inside it. To write in response to a change, write after `flush()` has returned — a tail handler hands the work to a microtask or a later callback rather than writing itself. - A refusal raised from a tail handler does NOT reach the caller at the call: it goes to the error policy like any handler throw — logged by default, or thrown out of `flush()` under `OIMThrowAtOnceErrorPolicy`. - Effects are isolated under the default policy: a throw is logged and handed to `onError`, and the frame finishes every other effect. - **A derivation is asked, never woken.** No frame walks to a computed slot. ### Subscribing ```ts const effect = effectService.createEffect(db, () => { paint(slot.entity); }, [slot]); effectService.disposeEffect(effect); ``` A `TOIMEffect` is a plain object with no methods; its behaviour lives in the stateless `OIMEffectService.INSTANCE`, which takes the channel map (`db`) on every create and files the effect on its `defaultChannelSlot` (`effect.channelSlot`). `createEffect` schedules the new effect when the current frame already has writes; it still never receives writes made before it was created. For a detached function, `effectService.subscribeEffect(db, body, sourceSlots?, sourceComputeds?, sourceTrackingComputeds?)` creates the effect exactly as `createEffect` does and returns its `TOIMDisposer` — `disposers.push(…)` it, or return it from a React cleanup. `holdOIMSlots(slots)` takes one hold on each slot of a list, through its owner; to give back a list of holds taken around one write, `unholdOIMSlotsIfAlive(slots)` unholds each slot that was not released meanwhile. Two things about how an effect is filed: - **The derivation list is deduplicated.** Naming one computed slot twice in the second argument gets it one edge, not two. Nothing is allocated for a list of one or none, and a list that turns out to be distinct keeps the caller's array. - **`disposeEffect` unfiles by a remembered position, not by scanning.** Each effect records where it sits in every list it is on; removal swaps in the tail and tells the moved effect its new position. The consequence a consumer can observe: **a slot's `effects` is not in subscription order**, and it never was guaranteed to be. - **The moved effect is told by EDGE, not found by search.** Beside `effects` a slot keeps `effectEdges` — for each effect, which of that effect's sources this slot is — and the swap carries both, so the moved effect updates one number. Taking one of two effects off the same N slots reads the other's source list ZERO times (a search read it N(N+1)/2). Only the slot's owner writes either array. The body's type is `TOIMEffectBody = () => (() => void) | void`. **A returned function is the undo**: it is called before the next run of that body and by `disposeEffect`. ```ts effectService.createEffect(db, () => { const timer = setInterval(poll, 1000); return () => clearInterval(timer); }, [slot]); ``` The return is checked with `typeof`, not for truthiness — `() => set.add(key)` hands back the `Set` — so anything that is not a function is discarded. The undo is cleared before it is called, so one that throws is not called again by the `disposeEffect` behind it. **A derivation that finds its sources as it reads:** `createOIMSourceTrackingComputedService({ derive, … })` and `createOIMSingleSourceTrackingComputedService({ derive, … })`. `derive: TOIMSourceTrackingComputedDerive` is `(computedSlot) => TValue`; there is no `createSources`, and `createStoreSlot(db)` takes no per-store `derive`. Every derive holds what it read and gives back what it no longer reads (new holds first). The slot (`TOIMSourceTrackingComputedSlot` / `TOIMSourceTrackingComputedContentSlot`, `sourceTracker` set) is read through `computed.value` (in `createSourceTrackingEffect` or another source-tracking derive) or through `createEffect`'s fifth list; `createEffect`'s `sourceComputeds` and a `createSources` list refuse it by type, because a declared effect subscribes once to the slots under a derivation. When a derive switches sources, a source-tracking effect or derivation over it re-subscribes even when the value held. A body that cannot read through a tracker may pass them as the fifth list, `createEffect(db, body, sourceSlots, sourceComputeds, sourceTrackingComputeds)`; such an effect derives them at creation and re-subscribes when their root slots are replaced. Prefer `createSourceTrackingEffect`: the root check runs after every run of such an effect. An effect with no fifth list pays nothing for it. Options otherwise as `createOIMComputedService` / `createOIMSingleComputedService` (`sameValueGuard`, `releaseValue`, `initialValue`, `slotReleasePolicy`, column options). **Sources found at read: `createSourceTrackingEffect(db, body)`.** The second way to build an effect takes no source lists. Reading is the subscription: inside the body, `slot.entity` on an entity slot, `computed.value` on a computed and the membership reads of a bucket slot (`bucket.getBucketMemberSlots()`, `getBucketMemberSlotCount()`, `hasBucketMemberSlot(member)`, `getBucketMemberSlotsMissingFrom(members)`) make that slot a source of the run — signal-style tracking, with nothing passed around. `computed.value` makes the computed itself a source, so the run is refreshed through it before it decides to run again. ```ts signature createSourceTrackingEffect(channelMap: IOIMChannelMap, body: TOIMSourceTrackingEffectBody): TOIMEffect; type TOIMSourceTrackingEffectBody = () => (() => void) | void; ``` ```ts const fallback = cardService.writeSlotContentByKey(cards, 'c2', { id: 'c2', title: 'King', rank: 13, deck: 'hearts' }); effectService.createSourceTrackingEffect(db, () => { const isFirst = slot.entity?.rank === 1; paint((isFirst ? slot : fallback).entity); }); ``` - The body runs once at creation: that run is what finds the sources. - After every run the effect is subscribed to exactly what the run read: a branch not taken is unsubscribed, a slot read twice is subscribed once. A run in the previous order costs one comparison per read; once it diverges, each read is looked up among the run's sources so far — a scan up to 16 distinct sources, a `Map` beyond. - A read through a service door that takes the slot as an argument (`slotContentService.…(slot)`) is not tracked: read through the slot. - A tracked read of `entity` makes the whole entity a source. `cardSlot.getEntity(columnGroup)` reads the same entity and makes only that group's columns a source: a write to another column does not wake the run. Build the group once, outside the body (`createOIMColumnGroup(names)`); a group is compared by identity. `getEntity` needs no declaration: any group works there. - A column slot (`cardSlot.holdColumnSlot(name)`, `cardSlot.holdColumnGroupSlot(group)`) is a source of an effect with declared sources, and a tracked read of its `value` makes that column alone a source. - A run that reads the same sources in the same order compares each read with the one before and changes no subscription. - `createEffect` with declared sources is unchanged; the choice is made per effect, at creation. A returned function is the undo, exactly as for `TOIMEffectBody`. ```ts const onRank = effectService.createEffect(db, () => { paint(slot.entity); }, [slot.holdColumnSlot('rank')]); ``` **A column effect takes the `TOIMColumnSlot` as a root, not a slot and a name.** Minting the column is the caller's call and it is a separate door, on the collection (or single) service: `service.holdColumnSlot(slot, columnName)` mints and HOLDS (`service.unholdColumnSlot(columnSlot)` gives it back), and `service.getColumnSlot(slot, columnName)` mints and lets the db's unused-slot collector hold it until the end of the next flush. Every collection and single service has them (a single entity's doors take the slot its service hands back: `settingsService.getColumnSlot(settingsService.getSingleSlot(settings), 'theme')`), and all go through the owner's column owner, which is configuration built at construction: its column slot store and the declared column groups. The column slots themselves live on their carrier, in `slot.columnSlotStore`; nothing about columns lives on the store slot. Every service also has `getAnyColumnSlot(slot)` / `holdAnyColumnSlot(slot)`, a column slot that wakes on any column write to its carrier. An index store slot's buckets have the same doors on the index service, taking the bucket slot. `createEffect` returns the **effect**, not the column. **`columnSlot.value` reads what the column stands for** (`OIMColumnSlot`, one class for entity, bucket and computed carriers; the entity's owner pushes, the computed's pulls): | column slot | `value` | |---|---| | entity column `name` | `entity[name]` | | entity any-column | the entity | | entity group | the group's field values, in the group's SORTED name order (`createOIMColumnGroup` sorts) | | bucket column `name` | array of `member.entity[name]`, in bucket order (a Set bucket: insertion order) | | bucket group | row-major, one array per member: `[[m1.a, m1.b], [m2.a, m2.b]]` | | bucket any-column | the members' entities | | computed column `name` | `computed.value[name]` | The value is cached and keeps its identity while it stays equal element by element. It is computed from the content service's pure reads `peekColumnValue` / `peekColumnGroupValue` / `peekAnyColumnValue`. A released column slot throws on `value`. **`slot.watch(body, columnNames?)`** — on an entity slot, a computed's carrier slot and a bucket slot — is an effect over that one slot with an explicit source (no tracker). It runs `body` at once and returns a `TOIMDisposer`. Entity: `body(entity | undefined)`, `columnNames` one name or the names of a declared group. Computed: `body(value)`, the same `columnNames` over the value's fields. Bucket: `body(bucketSlot)`, no `columnNames`; read `commands` / `isWholeListRecorded` inside it. ```ts const stopTitle = slot.watch(card => { paint(card); }, ['title']); stopTitle(); ``` **The name is compile-time checked only as far as the service's column-name type goes** — `holdColumnSlot` takes the service's `TColumnName`, which `createOIMEntityContentService` sets to `TOIMColumnName`. `TOIMColumnName` is the type that narrows a name to the entity's own columns, and `slotContentService.deleteEntityColumns` is typed on it. **A column group is one column slot for several columns.** `createOIMColumnGroup(['rank', 'label'])` returns a `TOIMColumnGroup` — `{ key, columnNames }`, the names deduplicated and sorted, a fresh frozen object per call; it throws on an empty list. A group's slot is filed only for a group DECLARED on the service with the `columnGroups` option (on `createOIMSlotCollectionService`, `createOIMSingleSlotService`, `createOIMEntitySlotCollectionStoreAggregate`, the computed and index factories); the group doors throw "… Name it in `columnGroups`" for any other, and with `columnNames` a group naming an undeclared column throws at construction. ```ts const rendered = createOIMColumnGroup(['rank', 'title']); const renderedCardService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService(), columnGroups: [rendered] }); const renderedCards = renderedCardService.createStoreSlot(db); const renderedCardSlot = renderedCardService.holdSlotByKey(renderedCards, 'c1'); const groupSlot = renderedCardSlot.holdColumnGroupSlot(rendered); ``` `service.holdColumnGroupSlot(slot, columnGroup)` mints and holds the group's column slot on `slot`, and `service.unholdColumnSlot(columnSlot)` gives it back. `service.getColumnGroupSlot(slot, columnGroup)` is the get door: it returns the filed slot or mints one the unused-slot collector takes back at the next flush unless something holds it, which is what a source-tracking effect reads. A write wakes it once if it changes any of the group's columns and not at all if it changes only others. **`columnNames` picks the column slot store.** `createOIMSlotCollectionService({ slotContentService, columnNames: ['rank', 'label'] })` — and `columnNames` on any factory's options — files the service's column slots by ordinal: every named column gets a number, a group gets one at its first slot, and an entity slot's column slots sit in an array by number instead of a `Map` per entity slot, which is cheaper to create and give back. `holdColumnSlot` and `columnGroups` are typed on those names, and a slot for any other column throws. Without `columnNames` the store is the `columnSlotStoreService` option, defaulting to a shared map-driven store, and any name is accepted. THE ENTITY SLOT CARRIES THE NAMES: `TOIMEntitySlot`, `TOIMEntityContentSlot` and `OIMEntitySlot` (`TColumnName extends TOIMColumnName`, default every column); `slot.getColumnSlot` / `slot.holdColumnSlot` take `TColumnName`, and the aggregate passes it through. `createOIMEntitySlotCollectionStoreAggregate(db, { columnNames: ['title'] })` makes `slot.getColumnSlot('rank')` a type error. With `TEntity` written explicitly TypeScript infers no other type argument, so spell the names in the type arguments: `(db, { columnNames: ['title'] })` still accepts every column. --- ## `OIMDB` and the three doors ```ts signature new OIMDB(options?: TOIMDBOptions) // see the runtime section for the option list ``` It owns the shared `clock`, one `collectorSlot`, one `defaultChannelSlot` and `schemas`, all public. The defaults a factory falls back on are an `OIMDefaults`, not the db's. **It builds no service of its own**; the schemas are what the caller's `createSchemas` built. `db.createEffect` creates an effect on it, and `flush()` is `OIMChannelService.INSTANCE.flush(db.defaultChannelSlot)`, which flushes the db's unused-slot collector slot once the frame is delivered. `OIMDB` implements `IOIMChannelMap` (`{ readonly defaultChannelSlot }`), so every door typed `channelMap: IOIMChannelMap` takes the db. **There is no default scheduler, on purpose — do not add one and do not generate code that wraps every write in `flush()`.** A test calls `db.flush()` itself. An application hands it to its orchestrator: with cnstra the whole wiring is `cns.addDrainListener(() => db.flush())`, which runs at the end of every synchronous turn of every stimulation. Each turn becomes one frame; an `await` inside a neuron ends a turn, so a request delivers its loading state first and its data in a later frame, with no further code. Every mutation goes through a domain neuron — a write from outside the orchestrator is the mistake, not a case to cover with a fallback. The database reaches the neurons as cnstra's global, never by import: ```ts signature const { neuron } = withCNSGlobal(); // TTodoDb = ReturnType, an OIMDB const todoNeuron = neuron({}).bind(TodoUiAxon, { toggleClicked: ({ id, done }, _axon, { global }) => { global.schemas.default.todos.getSlotByKey(id).updateEntity({ done }); }, }); const cns = new CNS([todoNeuron], undefined, db); // the third argument is the global: the OIMDB itself cns.addDrainListener(() => db.flush()); ``` `withCNSGlobal` is in the `@cnstra/core` release after 3.0.0. The view subscribes (`db.createEffect`, the React hooks) and stimulates (`cns.stimulate(signal)`); it never writes. Full page: `website/docs/guides/with-cnstra.md`. The doors are free functions, one module each, so a consumer ships only the one they import. Every factory takes ONE options object and no `db`; the `db` goes to `createStoreSlot(db)`. Each builds a SERVICE, once per collection type; the store slot is made separately: | Door | Builds | Store slot | |---|---|---| | `createOIMEntityContentService({ entityWriter?, slotEmptinessPolicy? }?)` | `OIMEntityContentService`, the entity content service; it creates keyed and single entity slots alike | — | | `createOIMSlotCollectionService({ slotContentService, slotStoreService?, slotReleasePolicy?, slotSubscriptionListener?, columnSlotStoreService? \| columnNames? })` | `OIMWritableSlotCollectionService` over any keyed content service (entity or bucket): the read doors, `writeSlotContentByKey`, the batch doors and `columnSlotService`. `slotStoreService` defaults to a Map store and is REQUIRED by type for an array key (`OIMSlotTreeStoreService`) | `createStoreSlot(db)` | | `createOIMSingleSlotService({ slotContentService, slotReleasePolicy?, slotSubscriptionListener?, columnSlotStoreService? \| columnNames? })` | `OIMWritableSingleSlotService` over any content service with `createSingleSlot` (entity or bucket) | `createStoreSlot(db)` | | `createOIMSlotCollectionIndexService({ entityService, columns? \| selectKey?, slotContentService?, bucketSlotStoreService?, slotReleasePolicy?, slotSubscriptionListener?, columnSlotStoreService? \| columnNames? })` | `OIMSlotCollectionIndexService`, over the entity collection service whose store slots it will index (it takes a `Pick` of `getSlots`); `slotContentService` defaults to an `OIMPositionalArrayBucketContentService`, pass `new OIMSetBucketContentService()` for an unordered one. A scalar key is inferred from ONE inline column or from `selectKey`'s return; an array key (two or more columns, or an array-returning `selectKey`) needs `bucketSlotStoreService: new OIMSlotTreeStoreService(…)` | `createIndexStoreSlot(entityStoreSlot)` | | `createOIMSlotCollectionSortedArrayIndexService({ entityService, columns? \| selectKey?, sortColumns, … })` | `OIMSlotCollectionSortedArrayIndexService`: the index whose buckets are kept in the order of `sortColumns` (`readonly TOIMSortColumn[]`, required) through an `OIMSortedArrayBucketContentService`. See [Sorted at write](#sorted-at-write) | `createIndexStoreSlot(entityStoreSlot)` | | `createOIMComputedService({ createSources?, derive?, sameValueGuard?, initialValue?, slotReleasePolicy?, slotStoreService?, columnSlotStoreService?, columnNames? })` | `OIMComputedService`; its reads are on the service itself (it extends `OIMSlotCollectionService`); `derive` and `createSources` may instead be given per store slot; `slotStoreService` is REQUIRED for a non-Map store (a single: `OIMSingleSlotStoreService`); see [One derivation per key](#one-derivation-per-key) | `createStoreSlot(db, derive?, createSources?)` | | `createOIMSortedComputedService({ indexService, sortColumns?, comparator?, slotReleasePolicy?, columnSlotStoreService?, slotStoreService? })` | `OIMSortedComputedService` — per key, the entity slots of the index bucket under that key, sorted; see [Sorted lists](#sorted-lists) | `createSortedStoreSlot(indexStoreSlot)` | | `createOIMSortedCollectionSingleSlotStoreAggregate(entitySlotCollectionStoreAggregate, { sortColumns?, comparator? })` | an `OIMSingleSlotStoreAggregate` of a computed whose `value` is every entity slot of the collection, sorted; no index; see [A whole collection, sorted](#a-whole-collection-sorted) | — (it takes the collection's aggregate and runs on its channel slot) | | `createOIMBucketMemoComputedService({ bucketCollectionService, slotReleasePolicy?, columnSlotStoreService?, slotStoreService? })` | `OIMBucketMemoComputedService` — per key, the bucket's slots as one array; see [The order of a bucket](#the-order-of-a-bucket-as-one-derivation-per-key) | `createBucketMemoStoreSlot(bucketStoreSlot)` | `entityWriter` and `slotReleasePolicy` on these doors default to those of the `defaults` option, so naming one overrides it for that service alone. **A store aggregate is the store slot with its store methods, so a call does not pass the store slot.** `service.createStoreAggregate(storeSlot)` wraps a store slot you have (the collection, single and index services each return their own aggregate); `createOIMSlotCollectionStoreAggregate(db, options)` and `createOIMSingleSlotStoreAggregate(db, options)` build service + store slot + aggregate in one call, with the options of `createOIMSlotCollectionService` / `createOIMSingleSlotService` (a new service per call: for many store slots of one type, build the service once). `createOIMEntitySlotCollectionStoreAggregate(db, options?)` is the same for a collection of entities: it builds the entity content service itself, takes its options (`entityWriter`, `slotEmptinessPolicy`) beside the collection's, keys by `TOIMStoreKey`, checks `columnNames` against the entity's columns, and returns an `OIMEntitySlotCollectionStoreAggregate`: the writable aggregate plus `getEntities()` / `getEntityCount()`. A composite key needs `slotStoreService` and goes through `createOIMSlotCollectionStoreAggregate`. `createOIMSlotCollectionIndexStoreAggregate(cardStoreAggregate, options)` does the same for an index over a collection aggregate, with the options of `createOIMSlotCollectionIndexService` minus `entityService` and with the default bucket store; a sorted-array index or a custom bucket store goes through its service's `createStoreAggregate(createIndexStoreSlot(…))`. ```ts import { createOIMEntitySlotCollectionStoreAggregate, createOIMSlotCollectionIndexStoreAggregate } from '@oimdb/core'; const deckStoreAggregate = createOIMEntitySlotCollectionStoreAggregate(db); const aceSlot = deckStoreAggregate.writeSlotContentByKey('c1', { id: 'c1', title: 'Ace', rank: 1, deck: 'spades' }); // = service.writeSlotContentByKey(storeSlot, 'c1', …) aceSlot.updateEntity({ rank: 14 }); deckStoreAggregate.storeSlot; // for hooks, indexes and computeds deckStoreAggregate.slotService; // the service itself deckStoreAggregate.getEntities(); // [Ace], no index const byDeckStoreAggregate = createOIMSlotCollectionIndexStoreAggregate(deckStoreAggregate, { selectKey: (card) => card.deck }); byDeckStoreAggregate.getEntitiesByKey('spades'); // [Ace] ``` | Aggregate | Methods (the service's, minus the store slot argument) | |---|---| | `OIMSlotCollectionStoreAggregate` | `peekSlotByKey`, `hasSlotContentByKey`, `getSlotByKey`, `holdSlotByKey`, `getSlots`, `getSlotCount` | | `OIMWritableSlotCollectionStoreAggregate` | + `writeSlotContentByKey`, `openBatch`, `closeBatch`, `writeInBatch` | | `OIMEntitySlotCollectionStoreAggregate` | + `getEntities`, `getEntityCount` (from `createOIMEntitySlotCollectionStoreAggregate`) | | `OIMSingleSlotStoreAggregate` | `peekSingleSlot`, `hasSingleSlotContent`, `getSingleSlot`, `holdSingleSlot` | | `OIMWritableSingleSlotStoreAggregate` | + `writeSingleSlotContent`, `clearSingleSlotContent` | | `OIMSlotCollectionIndexStoreAggregate` | the collection methods + `getEntitiesByKey`, `getSlotsByKeys`, `holdSlotsByKeys`, `get/holdBucketColumnSlotByKey`, `get/holdAnyBucketColumnSlotByKey`, `disposeIndexStoreSlot` | Every aggregate carries `storeSlot`, `slotService` (typed as the service it came from), `slotContentService`. Methods that take a slot stay on their service. **A DOOR ALWAYS PASSES; IT NEVER LETS A CLASS REACH FOR A GLOBAL.** Every option a service would otherwise answer with `?? OIMDefaults.x` is in the object its door hands it, so there is one answer to each question and not two. Pinned in `src/db/tests/which-answer-a-collection-the-root-mints-gets.test.ts`, which also fails when an option arrives on a service and is not forwarded, when the root mints anything but the channel and the collector, or when a public member appears on the root that is not one of the seven it owns. **`new OIMPositionalArrayBucketContentService({ bucketCommands })` is the content service for a list whose order is yours.** It is — insertion order, never re-decided — that records an `OIMBucketCommands` script per bucket. The recorder holds no subscription: it lists store slots on the channel slot, and the script lives for one frame. ```ts const freshPageService = createOIMSlotCollectionService({ slotContentService: new OIMPositionalArrayBucketContentService>({ bucketCommands: new OIMBucketCommands({ maxCommandsPerSlot: undefined }) }) }); const freshPage = freshPageService.createStoreSlot(db); const freshBucketSlot = freshPageService.holdSlotByKey(freshPage, 'page-1'); // freshBucketSlot.commands and freshBucketSlot.isWholeListRecorded carry the script; read them in an effect on the bucket slot ``` `new OIMBucketCommandsCursor({ bucketSlot }).takeBucketCommands()` hands a view what it has not applied yet, in the `TOIMOrderedListCommand` vocabulary: one `reset` with every member on the first take, after a whole-list record and on every wake of a bucket that records no commands; otherwise the commands of the frame, and only the tail it has not taken when it already took part of the same script. Take it inside an effect on the bucket slot. --- ## `OIMDefaults` — where an optional dependency comes from `OIMDefaults` is an instance holding the strategies factories fall back on when their own options leave them out. Build one with what you want shared and pass it as `defaults` to every factory that should use it; a factory given none uses `OIMDefaults.INSTANCE`, which is empty. A field left undefined falls back to the built-in default. Nothing is global and nothing can be replaced after the fact. ```ts signature new OIMDefaults({ slotStamp?: IOIMSlotStamp; // none slotReleasePolicy?: IOIMSlotReleasePolicy; // none: a slot with a value stays entityWriter?: IOIMEntityWriter; // createOIMInPlaceEntityWriter() entitySlotEmptinessPolicy?: IOIMSlotEmptinessPolicy; // "empty means slot.entity === undefined" indexKeysService?: IOIMIndexKeysService; // OIMAppendingIndexKeysService columnSlotStoreService?: IOIMSlotStoreService; // a shared map-driven store computedColumnSlotStoreService?: IOIMSlotStoreService; // a shared map-driven store storeSlotListener?: IOIMStoreSlotListener; // OIMNoStoreSlotListener: hears nothing }?) // TOIMDefaultsOptions ``` ```ts const replacingDefaults = new OIMDefaults({ entityWriter: createOIMReplacingEntityWriter() }); const replacingCardService = createOIMSlotCollectionService({ defaults: replacingDefaults, slotContentService: createOIMEntityContentService({ defaults: replacingDefaults }), }); ``` An option given to a factory wins over `defaults`; `defaults` wins over the built-in default. A tool that wants to hear every store slot (devtools' `OIM_DEV_DEFAULTS`) is a `defaults` with a `storeSlotListener`. **Each built-in default is its own module, so reaching one retains only its arm.** Every built-in default lives in its own file under `packages/core/src/db/constants/` as an `OIMDefaultValue` whose `getValue()` builds it on the first call and hands the same instance back after; a factory reads the modules it needs. `OIMDefaults` imports none of them, so importing it retains no arm. `packages/core/tests/what-an-import-retains.test.ts` pins it — *"a default is one door to its own arm, and the defaults class to none of them"*. --- ## Entity services **An entity collection is two objects: the content service and the collection service.** The entity content service (`OIMEntityContentService`) is the writes and reads of entities, built once per collection type with its slot owner; the collection service (`OIMSlotCollectionService`) over it is the read and column doors. Neither holds an entity: each `createStoreSlot(db)` is one instance of that type's store. ```ts signature createOIMEntityContentService({ entityWriter?: IOIMEntityWriter; // defaults.entityWriter, then the in-place writer slotEmptinessPolicy?: IOIMSlotEmptinessPolicy>; // defaults.entitySlotEmptinessPolicy, then "entity is undefined" }?): OIMEntityContentService createOIMSlotCollectionService({ slotContentService, slotStoreService?: IOIMSlotStoreService; // Map; REQUIRED for an array key slotReleasePolicy?: IOIMSlotReleasePolicy; // defaults.slotReleasePolicy, then OIMSlotAtEmptyReleasePolicy slotSubscriptionListener?: IOIMSlotSubscriptionListener; // OIMNoSlotSubscriptionListener columnSlotStoreService?: IOIMSlotStoreService; // defaults.columnSlotStoreService, then a shared map store columnNames?: readonly TColumnName[]; // the ordinal column store over those names }): OIMWritableSlotCollectionService, TStore, TEntity, …> collectionService.createStoreSlot(db): TOIMStoreSlot, Partial, typeof collectionService> ``` **Each collection type has its own column owner.** It is stateless configuration built with the slot owner over `columnSlotStoreService` (or the ordinal store `columnNames` names) and the declared `columnGroups`; the column slots live on their carrier (`slot.columnSlotStore`), not on the store slot. The doors are on the collection's `columnSlotService` (`getColumnSlot`, `holdColumnSlot`, `unholdColumnSlot`, `getColumnGroupSlot`, `holdColumnGroupSlot`, `getAnyColumnSlot`, `holdAnyColumnSlot`). The column owner has two strategies, chosen by the factory: write-driven column slots, woken by the marks a write makes (`OIMPushColumnSlotOwner`, entities and buckets), and derive-driven column slots, each a computed slot over its carrier (`OIMPullColumnSlotOwner`, computeds). Example, over the `db`, `cardService`, `cards` and `slot` of the setup block: ```ts const effect = effectService.createEffect(db, () => { console.log(slot.entity?.title); }, [slot]); slot.updateEntity({ title: 'Ace of Spades' }); db.flush(); effectService.disposeEffect(effect); ``` Assembled with a store service of your own: ```ts const baseCardService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService(), slotStoreService: new OIMSlotMapStoreService>(), }); const baseCards = baseCardService.createStoreSlot(db); ``` The writer is omitted because the db and `OIMDefaults` supply it, and so is the column store. The slot stamp is not an option of any factory: it is `new OIMDefaults({ slotStamp })`, passed as `defaults`. ### Public properties | Property | Of | Type | |---|---|---| | `slotContentService` | the collection service | the content service: the write doors on a slot | | `columnSlotService` | the collection service | `OIMColumnSlotService`: the column doors | | `slotService` | the store slot | the service that created it | A store slot is not a slot, so nothing holds, subscribes or wakes it: there is no `effectService.createEffect(db, …, [cards])` that hears the population. "An entity joined or left" is the collection's list, `OIMSlotCollectionBucketService.INSTANCE.holdBucketSlot(storeSlot)`; "something in one part of the population changed" is an index over the store slot and a subscription to its bucket — the bucket's door is written when an entity slot joins or leaves it — or a content-change listener on the store slot (`OIMSlotContentChangeListenerService.INSTANCE.addContentChangeListener(storeSlot, listener, readColumnNames)`, removed by the same listener object). The slot owner is what `slot.owner` points at for every slot the type filed, in every one of its store slots; `slot.storeSlot` names which store slot. **THE WHOLE POPULATION IS `OIMSlotCollectionBucketService.INSTANCE`.** Two doors, like `getSlotByKey` / `holdSlotByKey`: `getBucketSlot(storeSlot)` returns the collection's list of every slot that holds an entity, held by the unused-slot collector until the flush when nothing else holds it, so a later read builds it again; `holdBucketSlot(storeSlot)` returns the same list held until `bucketSlot.unholdSlot()`. Both return a `TOIMCollectionBucketSlot`, which is read-only: `getBucketMemberSlots`, `getBucketMemberSlotCount`, `hasBucketMemberSlot`, `holdSlot`, `unholdSlot`. While it lives it is kept in step on every emptiness transition; a collection nobody asks pays nothing. `holdBucketSlot` is `getBucketSlot` plus `holdSlot()`; both take a `TOIMSlotCollectionStoreSlot`. ORDER IS NOT A GUARANTEE: while the list is alive it is the order entities got data (cleared and refilled goes last); a list built afresh follows the order the slots were created in the collection, and a read with no data creates a slot. After a held entity is cleared and refilled, or a key read before its first write, the two differ. For a strict order use `createOIMSortedCollectionSingleSlotStoreAggregate` ([A whole collection, sorted](#a-whole-collection-sorted)). The list does NOT hold its members: an entity goes by its collection's release policy even while the list is read, and leaves the list when released. Subscribe to it to hear joins and leaves. Its column slots (`getBucketColumnSlot(storeSlot, columnName)` / `holdBucketColumnSlot`, `getAnyBucketColumnSlot(storeSlot)` / `holdAnyBucketColumnSlot`) wake like an index bucket's: on a member's write to the column and on a join or leave; `getOIMBucketMemberSlotEntities(bucketSlot.getBucketMemberSlots())` reads its entities. An `OIMEntitySlotCollectionStoreAggregate` (what `createOIMEntitySlotCollectionStoreAggregate` returns) has the same as `getEntities()` / `getEntityCount()`. **The list has column slots too**: `getBucketColumnSlot(storeSlot, columnName)` / `holdBucketColumnSlot(storeSlot, columnName)` and `getAnyBucketColumnSlot(storeSlot)` / `holdAnyBucketColumnSlot(storeSlot)` on `OIMSlotCollectionBucketService.INSTANCE` return a `TOIMColumnSlot` that wakes when a member's write changes that column (any column). They are registered when first asked for and released with the list, and the get / hold pair is the same as for the list. ```ts const everyCard = OIMSlotCollectionBucketService.INSTANCE.holdBucketSlot(cards); effectService.createEffect(db, () => { for (const card of getOIMBucketMemberSlotEntities(everyCard.getBucketMemberSlots())) paint(card); }, [everyCard]); // joins and leaves everyCard.getBucketMemberSlotCount(); // how many cards hold an entity cardService.getSlotCount(cards); // how many ids are filed, empty ones included for (const filedSlot of cardService.getSlots(cards)) { if (isOIMSlotEmpty(filedSlot)) continue; // getSlots walks every filed slot, empty ones included paint(filedSlot.entity); } everyCard.unholdSlot(); ``` For one part of the population, or a sorted view of the whole one (`sorted` / `createOIMSortedComputedService` take an index), declare an index. An index's bucket is an injected lifetime — a `slotReleasePolicy` — so it is the consumer who says how long the answer outlives its last reader. An index maintains buckets only while they are held, filing entity slots from the source store slot on every write by the entity's key value. The bucket is created on first `holdSlotByKey` by walking the source store slot's slots once, and released on the last give-back. **`holdColumnSlot(slot, columnName)`** is on the collection's `columnSlotService` and takes a hold on a column slot; `columnSlot.unholdSlot()` gives that hold back. **`slot.getColumnSlot(columnName)`** returns the same column slot without a hold: a column slot it mints is held by the unused-slot collector until the end of the next flush, so `getColumnSlot` is the door that does not hold but tracks. `peekSlotByKey(storeSlot, key)?.entity` reads the entity itself, so it mints nothing: a miss answers `undefined` and leaves no slot behind. ### The doors every service has **The read doors are the collection service's and take the store slot first; the write doors are the content service's.** Every collection service (entity, bucket, index and computed) has the read doors below; a single slot service has `getSingleSlot` / `holdSingleSlot` / `peekSingleSlot` / `hasSingleSlotContent` in their place. ```ts signature abstract class OIMSlotCollectionService { readonly slotContentService: TSlotContentService; peekSlotByKey(storeSlot, key): TSlot | undefined; hasSlotContentByKey(storeSlot, key): boolean; getSlotByKey(storeSlot, key): TSlot; holdSlotByKey(storeSlot, key): TSlot; getSlots(storeSlot): IterableIterator; getSlotCount(storeSlot): number; isSameKey(key, otherKey): boolean; readonly columnSlotService: OIMColumnSlotService; // getColumnSlot / holdColumnSlot / getAnyColumnSlot / holdAnyColumnSlot / getColumnGroupSlot / holdColumnGroupSlot / unholdColumnSlot } // the base builds no store slot in public; each subclass has its own door for it: // createOIMSlotCollectionService returns OIMWritableSlotCollectionService, which adds: // createStoreSlot(channelMap: IOIMChannelMap): TOIMStoreSlot; createStoreAggregate(storeSlot) // writeSlotContentByKey(storeSlot, key, content, changedSlots?): TSlot // openBatch(storeSlot): void; closeBatch(storeSlot): void // writeInBatch(storeSlot, write: () => TResult): TResult // an index service and a computed service have no openBatch / closeBatch / writeInBatch // an index service builds its store slots with createIndexStoreSlot(sourceStoreSlot) (+ createStoreAggregate) only // a computed service extends OIMSlotCollectionService directly (+ its own createStoreAggregate); its store slots // come only from its own door: createStoreSlot / createSortedStoreSlot / createBucketMemoStoreSlot // createOIMSingleSlotService returns OIMWritableSingleSlotService, which adds: // writeSingleSlotContent(storeSlot, content, changedSlots?): TSlot; clearSingleSlotContent(storeSlot): void ``` | Door | Of | Signature | Mints? | |---|---|---|---| | `getSlotCount(storeSlot)` | collection | `number` | no | | `getSlots(storeSlot)` | collection | `IterableIterator` | no | | `peekSlotByKey(storeSlot, key)` | collection | `TSlot \| undefined` — the store lookup alone; takes no hold and leaves nothing tracked | no | | `getSlotByKey(storeSlot, key)` | collection | `TSlot` — never `undefined`; minted if missing, then tracked by the unused-slot collector | **yes** | | `holdSlotByKey(storeSlot, key)` | collection | `TSlot` — minted if missing, `holdCount` up by one | **yes** | | `hasSlotContentByKey(storeSlot, key)` | collection | `boolean` — **does this key have content right now**, not whether an identity is filed under it: a slot a read or a hold minted and nobody wrote answers `false`. It hands back no slot, which is why it can answer without minting, and it is not a read: the answer is about the past the moment it returns | no | | `isSameKey(key, otherKey)` | collection | `boolean` — whether two keys name one slot here, answered by the store service (SameValueZero for a Map store, part by part for a tree store) | no | | `writeSlotContentByKey(storeSlot, key, content, changed?)` | collection | `TSlot` — **total; always the identity it resolved or minted**. A hit writes the whole value through `slotContentService.writeSlotContent`; a miss mints and files the slot (the collection service), then `insertSlotContent` fills it | **yes** | | `writeSlotContent(slot, content)` | content | `boolean` — on a slot you already hold; the boolean is about the CONTENT | no | | `clearSlotContent(slot)` | content | `void` — it takes the value, not the identity | no | | `markContentChanged(bucketSlot)` | bucket content | `void` — re-settle emptiness and re-ask the guard after a write you made another way; the entity counterpart is `markEntityChanged(slot, changedColumns?)` | no | | `slot.holdSlot()` / `slot.unholdSlot()` | `void` — the `IOIMSlotOwner` pair; `unholdSlot` on an unheld slot throws by name | no | | `slot.owner.releaseSlotIfUnheld(slot)` | `void` — run the release guard; it releases nothing unless the slot is unheld, carries no column slots, still owned here and out of grace | no | **`releaseSlotIfUnheld` is PUBLIC and it is still not a "release" door.** It is public because the release queue calls it through `slot.owner`, and it is a guard, not a command: on a held, referenced, foreign- owned or in-grace slot it returns having done nothing, and on an already-released one it returns silently rather than throwing. **`writeSlotContentByKey` does not keep a key whose content is refused.** ONE MINT PATH: every door creates a slot with `createSlot`, calls the `onSlotMinted` hook, and the collection / single service files it (`mintSlotByKey` / `mintSingleSlot`); a get or hold then settles its emptiness (and `getSlotByKey` holds it until the flush). On a MISS the write mints that way and calls the content service's `insertSlotContent`, which does NOT file the slot: inside a `try` it fills it, settles emptiness and writes the channel, and on a throw runs the release guard on the unheld, empty slot — which unfiles it — before re-raising, so the caller's error is the only thing that leaves. The HIT path looks the key up first and never mints, so a refused write on an existing key leaves that key exactly as it was. **REFUSED IS NOT UNCHANGED**, and the two get opposite answers: | | What happened | What the caller gets | |---|---|---| | **Refused** | The write threw; **no content ever arrived** | The throw. A key minted for it is unwound — `writeSlotContentByKey` files nothing | | **Unchanged** | The write **did** happen and the content was already there | The identity, like any other write. Nothing is unwound | `writeSlotContentByKey` is **total**: whatever it decides about the content, it hands back the identity it resolved or minted. A door that mints must leave a reference behind, which is the one test that admits a door at all. **`changed?` — the verdict, into an array you own.** ```ts const changed: TOIMEntitySlot[] = []; cardService.writeSlotContentByKey(cards, 'c1', { id: 'c1', title: 'Ace', rank: 1, deck: 'spades' }, changed); // pushed exactly when the content differed ``` - **Optional, yours, and appended to** — never read by the engine, never cleared. The slot is pushed exactly when the write put in content different from what the slot held. - A batch therefore comes out of one loop as the list of entity slots that **actually changed**, which is what a consumer owning a bucket this engine does not maintain needs. - It is an out-parameter and not a return because the return is spoken for (see above), and a `{ slot, changed }` record would allocate once per write on the path this exists to make cheaper. What it costs a caller who does not want it is one `undefined` compare per write. --- ## Writing The keyed write is on the collection; every other write is on its content service, `service.slotContentService`, and takes the slot alone. There is no `selectKey`: the caller names the key. There are no bulk writes: a load is a loop of single writes inside `service.writeInBatch(storeSlot, () => { … })`. | Call | Signature | |---|---| | `service.writeSlotContentByKey(storeSlot, key, entity, changedEntitySlots?)` | `(storeSlot, TKey, TEntity, TOIMEntitySlot[]?) => TOIMEntitySlot` — **total**: a miss mints and fills, a hit writes the whole value | | `writeSlotContent(slot, entity)` | `(slot, TEntity) => boolean` — the whole value onto a slot you hold; columns it had and `entity` does not, go | | `updateEntity(slot, patch)` | `(slot, Partial) => slot` | | `updateEntityColumn(slot, columnName, value)` | `(slot, C, TEntity[C]) => slot` — one column, no patch object and no walk over it | | `clearSlotContent(slot)` | `(slot) => void` — the entity goes; the identity stays while anything refers to it | | `markEntityChanged(slot, changedColumns?)` | `(slot, readonly (keyof TEntity & string)[]?) => void` | | `deleteEntityColumns(slot, columnNames)` | `(slot, readonly TOIMColumnName[]) => slot` — the named columns go | | `service.writeInBatch(storeSlot, write)` | `(storeSlot, () => TResult) => TResult` — an index on the collection hears the whole batch in one call | | `service.peekSlotByKey(storeSlot, key)?.entity` | the entity alone; mints nothing | - **The store keeps your object by default.** Under the default `insertOIMEntityWithoutCopy` the slot holds the object you hand in, so with the in-place writer a later update edits that same object; pass `entityInserter: insertOIMEntityWithCopy` to store `{ ...entity }` and leave your object untouched. After an insert, change the object only through the content service (`updateEntity`, or `markEntityChanged` after a hand edit): editing it and calling `writeSlotContent` with the same object again wakes nobody, because no column reads as changed. `insertOIMEntityWithSanitizedCopy` also removes an own `__proto__` key: pick it for untrusted JSON. - `updateEntity` takes a **patch** — named columns move, unnamed ones stay. `writeSlotContentByKey` and `writeSlotContent` take a **whole value**, and a column the new value does not name is removed from the entity. - A write that moves no column wakes nobody. - **`writeSlotContentByKey` always hands back the slot**, whatever the write changed. - **`changedEntitySlots?`**: optional, yours, appended with the entity slots whose content was different from what they already held. One array reused across a whole batch is the intended use, so a pass over its slots costs the entities that changed rather than the entities that arrived. It is never cleared — you empty it. ```ts const changed: TOIMEntitySlot[] = []; cardService.writeInBatch(cards, () => { for (const card of payload) cardService.writeSlotContentByKey(cards, card.id, card, changed); }); for (const slot of changed) reindex(slot); // the re-sent entities are not in here changed.length = 0; ``` ### `markEntityChanged` — you mutated the entity yourself, now say so ```ts signature markEntityChanged( slot: TOIMEntitySlot, changedColumns?: readonly (keyof TEntity & string)[], ): void ``` Every other write door computes what moved: the writer walks the patch (`patchOIMEntityColumns`, `putOIMEntityColumns`) and puts each value through `sameValueGuard`. A caller who edited the stored object by hand already knows the answer, and this door takes it instead of recomputing it — no patch object, no copy, no per-column comparison. The shape is: mutate `slot.entity`, then report it. ```ts slot.entity!.title = 'two'; slot.markEntityChanged(['title']); ``` - **The hand mutation already compiles.** `TOIMEntitySlot` declares `readonly entity: TEntity | undefined`, and `readonly` forbids REPLACING the object, not writing its columns — `entity.title = 'two'` needs no cast, only the usual narrowing of `| undefined`. The stored object itself, `content`, is not on the public slot types: a custom writer receives the engine's slot class `OIMEntitySlot`, the one type that carries it (`entity` is a getter over `content`). - **With a list, only the named columns wake. Without it, every watched column does** — the column owner walks the slot's whole column store, and a column slot exists there only while something holds it or subscribes to it (the slot owner drops it otherwise, in `releaseSlotIfUnheld`), so "watched" is exactly what the store holds. **Pass the list.** The no-argument form is the convenient one and it gives back the per-column walk this door exists to skip. - **An empty list wakes nothing at all** — not the columns, not the entity slot, not the store slot's listeners. `[]` is the caller saying nothing moved, so it returns before anything is marked: a write that changes nothing wakes nobody here too. - **With either of the other two it wakes the entity slot and the store slot's content-change listeners**, so an effect on the slot itself and an index over the store slot both see a hand mutation. - **It re-stamps emptiness** whenever emptiness can depend on the mutation — with no column list, on a slot whose `entity` is `undefined`, and on a content service with a `slotEmptinessPolicy` other than "the entity is `undefined`", a release policy that releases written slots, or a db with a `slotStamp` — so a hand mutation that emptied the entity leaves `isOIMSlotEmpty(slot)` true rather than lying, and the release guard can take the identity when it should. - **It refuses inside a frame**, through the same `assertWritable` → `OIMChannelService.INSTANCE.assertNotFlushing(channelSlot)` as every other write, and throws on a released identity. - **The column names are type-checked**: `keyof TEntity & string` rejects a misspelt name, a bare runtime `string`, and a slot of another entity type. --- ## Write strategies A **writer** is the operations that move an entity's columns, and nothing else: it reaches no channel, takes no holds and knows nothing about lifetime. Both strategies ship as factories; the fork is chosen once, as the content service's `entityWriter` (or for every factory given it, `new OIMDefaults({ entityWriter })` as `defaults`). ```ts signature interface IOIMEntityWriter { readonly fillEntity: (slot: TOIMEntityContentSlot, entity: object) => void; readonly putEntity: (slot: TOIMEntityContentSlot, entity: object, changedColumnNames: string[] | undefined) => boolean; readonly patchEntity: (slot: TOIMEntityContentSlot, patch: object, changedColumnNames: string[] | undefined) => boolean; readonly patchColumn: ( slot: TOIMEntityContentSlot, columnName: string, value: unknown, changedColumnNames: string[] | undefined, ) => boolean; readonly deleteColumns: (slot: TOIMEntityContentSlot, names: readonly string[]) => readonly string[]; readonly clearEntity: (slot: TOIMEntityContentSlot) => void; } type TOIMEntityWriterOptions = { sameValueGuard?: TOIMSameValueGuard; entityInserter?: TOIMEntityInserter; putEntityColumns?: typeof putOIMEntityColumns; // putOIMEntityColumns | guardOIMEntityColumnsPut patchEntityColumns?: typeof patchOIMEntityColumns; // patchOIMEntityColumns | guardOIMEntityColumnsPatch patchEntityColumn?: typeof patchOIMEntityColumn; // patchOIMEntityColumn | guardOIMEntityColumnPatch }; createOIMInPlaceEntityWriter(options?: TOIMEntityWriterOptions): IOIMEntityWriter // stored object keeps its identity createOIMReplacingEntityWriter(options?: TOIMEntityWriterOptions): IOIMEntityWriter // a new object per write that changed something ``` `entityInserter` is the first-write strategy: `insertOIMEntityWithoutCopy` (the default) stores your object itself, `insertOIMEntityWithCopy` stores `{ ...entity }`, `insertOIMEntityWithSanitizedCopy` stores a copy with an own `__proto__` key removed (for untrusted JSON). `deleteColumns` hands back **the names that actually moved**, a frozen empty array when nothing did — that list is what the entity content service routes to column subscribers, and it is why a write that changes nothing wakes nobody. **`putEntity` and `patchEntity` answer whether anything moved, and name the moved columns only into the array they are handed**: one pass compares and writes (a put then walks the stored columns the new value lacks), and with `undefined` they build no list at all. The entity content service asks whether the slot has changed-column readers — the slot has column slots, or its store slot has a content listener such as an index — and hands an array only then, so a write of an entity nobody reads by column allocates no names. The list it builds goes on to the listeners: an index wakes a bucket column exactly when a member's value of it changed, left, or became `undefined`. The first write into an empty slot tells listeners `undefined` ("everything"), not an empty list. `sameValueGuard` defaults to `isOIMSameValueZero` and is the per-column comparison that decides "moved". `putEntity` is PUT, `patchEntity` is PATCH (HTTP semantics). PUT makes the stored entity the value handed in — changed columns written, columns the value lacks removed — in ONE call, returning both sets of names; PATCH writes only the columns named. `writeSlotContentByKey` of a key that already has a value and `slot.writeSlotContent(entity)` are PUT: a whole-entity write that drops a column is ONE channel write of the slot, and the replacing writer builds ONE new object. Pick `createOIMReplacingEntityWriter` when something downstream compares by reference — a React `useSyncExternalStore` snapshot, a memo, a shallow-equal selector. Under `createOIMInPlaceEntityWriter` the entity reference never moves, so a value comparison never fires and a binding needs a counter bumped inside its handler. Replacing allocates one object per changed write; in-place allocates none. Neither writer `delete`s: a column a PUT drops or `deleteColumns` takes away is written `undefined` — into the stored object in place, into a spread copy when replacing — so the entity keeps its hidden class, and the key stays in `Object.keys` and `in`. A column holding `undefined` counts as absent — a later write that leaves it out does not report it, and taking the entity away does not wake its readers. **Neither strategy reports anything.** Reporting is `OIMEntityContentService`'s: after the writer returns, it marks the slot on the channel and tells the store slot's content-change listeners once for the whole write. **A writer of your own** reuses the column walks both shipped writers run: ```ts signature patchOIMEntityColumns(slot, patch: object, sameValueGuard, changedColumnNames: string[] | undefined, targetOf: (entity: Record) => Record): Record | undefined patchOIMEntityColumn(slot, columnName: string, value: unknown, sameValueGuard, changedColumnNames: string[] | undefined, targetOf: (entity: Record) => Record): Record | undefined putOIMEntityColumns(slot, entity: object, sameValueGuard, changedColumnNames: string[] | undefined, targetOf: (entity: Record) => Record): Record | undefined guardOIMEntityColumnsPut(slot, entity: object, sameValueGuard, changedColumnNames: string[] | undefined, targetOf: (entity: Record) => Record): Record | undefined guardOIMEntityColumnsPatch(slot, patch: object, sameValueGuard, changedColumnNames, targetOf) // same signature as the unguarded walk guardOIMEntityColumnPatch(slot, columnName: string, value: unknown, sameValueGuard, changedColumnNames, targetOf) ``` Each compares every column through `sameValueGuard`, writes the moved ones into the object `targetOf` hands back on the first move (the stored entity in place, a copy when replacing), pushes their names into `changedColumnNames` when it is an array, and returns that object; `undefined` means nothing moved or the slot holds no entity. The put walk also writes `undefined` over every column the new value lacks. Each walk is a strategy, an option of the writer factories (`TOIMEntityWriterOptions`), and each ships two arms: | Option | Default (unguarded) | Guarded arm | |---|---|---| | `putEntityColumns` | `putOIMEntityColumns` — skips neither `__proto__` keys nor inherited stored columns | `guardOIMEntityColumnsPut` — skips both | | `patchEntityColumns` | `patchOIMEntityColumns` — every enumerable key of the patch, `__proto__` included | `guardOIMEntityColumnsPatch` — skips a `__proto__` key and a key the patch does not own | | `patchEntityColumn` | `patchOIMEntityColumn` | `guardOIMEntityColumnPatch` — refuses the column name `__proto__` | Take the guarded arms, at a cost on every write, for values that can carry a `__proto__` key or are class instances — `createOIMInPlaceEntityWriter({ putEntityColumns: guardOIMEntityColumnsPut, patchEntityColumns: guardOIMEntityColumnsPatch, patchEntityColumn: guardOIMEntityColumnPatch })`, the same options on `createOIMReplacingEntityWriter`. The writer decides only where the result goes — this one stores every value frozen: ```ts const copyColumns = (entity: Record): Record => ({ ...entity }); function storeFrozen(slot: OIMEntitySlot, next: Record | undefined): boolean { if (next === undefined) return false; slot.content = Object.freeze(next); return true; } const replacingWriter = createOIMReplacingEntityWriter(); const freezingWriter: IOIMEntityWriter = { fillEntity: (slot, entity) => { storeFrozen(slot, copyColumns(entity as Record)); }, clearEntity: replacingWriter.clearEntity, putEntity: (slot, entity, changedColumnNames) => storeFrozen(slot, putOIMEntityColumns(slot, entity, isOIMSameValueZero, changedColumnNames, copyColumns)), patchEntity: (slot, patch, changedColumnNames) => storeFrozen(slot, patchOIMEntityColumns(slot, patch, isOIMSameValueZero, changedColumnNames, copyColumns)), patchColumn: (slot, columnName, value, changedColumnNames) => storeFrozen(slot, patchOIMEntityColumn(slot, columnName, value, isOIMSameValueZero, changedColumnNames, copyColumns)), deleteColumns: (slot, names) => { const deleted = replacingWriter.deleteColumns(slot, names); if (deleted.length !== 0) storeFrozen(slot, slot.content as Record); return deleted; }, }; ``` --- ## Single entities A single entity — one value under no key, such as settings or a session — is a store slot of an `OIMSingleSlotService` over an entity content service; its store service is `OIMSingleSlotStoreService.INSTANCE`, which files at most one slot per store slot. It has no key and no by-key doors: its doors name the one slot. ```ts signature createOIMSingleSlotService({ slotContentService: createOIMEntityContentService(), slotReleasePolicy?, slotSubscriptionListener?, columnSlotStoreService?, columnNames?, }): OIMWritableSingleSlotService, TEntity, …> class OIMWritableSingleSlotService { readonly slotContentService: TSlotContentService; readonly columnSlotService: OIMColumnSlotService; createStoreSlot(channelMap: IOIMChannelMap): TOIMStoreSlot, TSlot, TPatch, this>; writeSingleSlotContent(storeSlot, content, changedSlots?): TSlot; // minted if missing clearSingleSlotContent(storeSlot): void; peekSingleSlot(storeSlot): TSlot | undefined; // mints nothing hasSingleSlotContent(storeSlot): boolean; // mints nothing getSingleSlot(storeSlot): TSlot; // minted if missing, tracked until the next flush holdSingleSlot(storeSlot): TSlot; // minted if missing, holdCount up by one } ``` One service serves every single entity of that type: each `createStoreSlot(db)` is another one, and starts with no value until something writes it. Its store slot is a `TOIMSingleSlotStoreSlot`, which is what `@oimdb/persist`'s single-entity source takes. ```ts type Settings = { theme: 'light' | 'dark'; zoom: number }; const settingsService = createOIMSingleSlotService({ slotContentService: createOIMEntityContentService() }); const settings = settingsService.createStoreSlot(db); settingsService.writeSingleSlotContent(settings, { theme: 'light', zoom: 1 }); const settingsSlot = settingsService.holdSingleSlot(settings); const themeColumn = settingsSlot.holdColumnSlot('theme'); const themeEffect = effectService.createEffect(db, () => { console.log(settingsSlot.entity?.theme); }, [themeColumn]); settingsSlot.updateEntity({ theme: 'dark' }); db.flush(); effectService.disposeEffect(themeEffect); themeColumn.unholdSlot(); settingsSlot.unholdSlot(); ``` **The slot is reached only through the service.** `getSingleSlot(storeSlot)` hands back the live slot, and mints a fresh one — tracked by the unused-slot collector until the next flush — when there is none; `holdSingleSlot(storeSlot)` does the same and takes a hold. `writeSingleSlotContent` and `clearSingleSlotContent` are the store doors, and every slot door of the content service (`updateEntity`, `updateEntityColumn`, `deleteEntityColumns`, `writeSlotContent`, `markEntityChanged`, `clearSlotContent`) takes that slot. The slot is of the keyed entity slot's literal shape (with `key: undefined` and `indexKeys: undefined`), and its `storeSlot` is `settings` — so `effectService.createEffect(db, …, [settingsSlot])` works and a column of it is a root like any other. Its key is `undefined`, and its store is `{ slot }` (`TOIMSingleSlotStore`). Its lifetime is the `slotReleasePolicy` (`defaults.slotReleasePolicy`, then `OIMSlotAtEmptyReleasePolicy`), so a single entity that holds a value stays; one emptied and unheld is released, and the slot `getSingleSlot` mints next holds no entity. The value is stored by the writer's `entityInserter`, which by default keeps the object handed in rather than a copy. --- ## Buckets A bucket collection is, like an entity collection, a content service and the collection service over it. The content service is the strategy — how a bucket keeps its member slots — and it is chosen at the factory: ```ts signature createOIMSlotCollectionService({ slotContentService: new OIMPositionalArrayBucketContentService(), // or one of the others below slotStoreService?: IOIMSlotStoreService, TStore>; // Map; REQUIRED for an array key slotReleasePolicy?, slotSubscriptionListener?, columnSlotStoreService?, columnNames?, }): OIMWritableSlotCollectionService, TStore, readonly TBucketMemberSlot[], …> new OIMSetBucketContentService({ bucketCommands? }) new OIMPositionalArrayBucketContentService({ bucketCommands?, bucketMemberSlotsArrayService? }) new OIMSortedArrayBucketContentService({ compareBucketMemberSlots, bucketMemberSlotsArrayService? }) // no bucketCommands // bucketMemberSlotsArrayService: OIMBucketMemberSlotsArrayService (every mention, the default) // or new OIMBucketUniqueMemberSlotsArrayService() (each slot once) ``` A bucket holds bucket member slots of any slot type — entity slots, bucket slots, computeds — and its type parameter `TBucketMemberSlot extends TOIMSlot` (default `TOIMEntitySlot`) is that slot type, not the entity type. The services hold no bucket: `createStoreSlot(db)` is one keyed set of buckets, the read doors of the collection service take that store slot first, and the bucket doors of the content service take the bucket slot. ```ts const colourService = createOIMSlotCollectionService({ slotContentService: new OIMSetBucketContentService>() }); const colours = colourService.createStoreSlot(db); const red = colourService.holdSlotByKey(colours, 'red'); red.writeSlotContent([slot, cardService.getSlotByKey(cards, 'c2')]); db.flush(); for (const deckSlot of red.getBucketMemberSlots()) { paint(deckSlot.entity); } red.clearSlotContent(); red.unholdSlot(); ``` Every door below is the bucket content service's and takes the bucket slot: | Door | Signature | |---|---| | `writeSlotContent(bucketSlot, bucketMemberSlots)` | `boolean` — states the whole bucket; idempotent; true when anything arrived or departed | | `getBucketMemberSlotsMissingFrom(bucketSlot, bucketMemberSlots)` | `TBucketMemberSlot[]` — the members the given list leaves out, so a sync can write into them (clear a group key, set a deleted flag) instead of dropping them | | `addBucketMemberSlot(bucketSlot, bucketMemberSlot)` / `addBucketMemberSlots(bucketSlot, bucketMemberSlots)` | joins the named bucket member slots and touches nothing else. REMOVES NOTHING | | `removeBucketMemberSlot(bucketSlot, bucketMemberSlot)` / `removeBucketMemberSlots(bucketSlot, bucketMemberSlots)` | takes the named bucket member slots out and touches nothing else | | `clearSlotContent(bucketSlot)` | empties it | | `getBucketMemberSlots(bucketSlot)` | `Iterable` | | `getBucketMemberSlotCount(bucketSlot)` | `number` | | `hasBucketMemberSlot(bucketSlot, bucketMemberSlot)` | `boolean` — the content service's own membership test: one `Set.has` on a set bucket; on an array bucket its `bucketMemberSlotsArrayService.hasBucketMemberSlot` (a `Set.has` when unique, `indexOf` otherwise) | | `markContentChanged(bucketSlot)` | `void` — re-settle emptiness and re-ask the release guard after a write made another way | | `fillBucketMemberSlots(bucketSlot, bucketMemberSlots)` | `void` — fills a bucket slot nobody was told about yet; it throws on one that was already announced, which `addBucketMemberSlots` / `writeSlotContent` are for | The entities of a bucket by key are the index's door, `indexService.getEntitiesByKey(indexStoreSlot, key)` ([The index that fills itself](#the-index-that-fills-itself--oimindexservice)). ### Which door: you hold the answer, or you hold the delta `writeSlotContent` is for a caller who has THE LIST THAT SHOULD BE THERE and does not know what changed — a search result, a page from a server, a filter re-run. One call, and the engine works out the arrivals and the departures. Its cost is proportional to WHAT THE BUCKET HOLDS, not to the change: the difference builds a map over the whole incoming list and walks the standing one, so a batch of ten into a bucket of two hundred pays for two hundred and ten. `addBucketMemberSlots` / `removeBucketMemberSlots` are for a caller who KNOWS THE DELTA — an entity arrived over a socket, a card was dragged in, an infinite list appended a page, an entity was deleted. The standing slots keep the holds they already have. Adding costs what you name. Removing k slots from an ordered bucket of n is ONE pass, n + k, through the content service's `removeSlots` (the erase-remove idiom, as in Java's ArrayList.removeAll); k separate `removeBucketMemberSlot` calls are up to k·n. The recorded `remove` commands come in LIST order, not argument order, each at its position after the earlier ones applied, so replaying them draws the same list. A set-driven bucket removes them in the order you name them. **`addBucketMemberSlots` removes nothing.** If the authoritative list SHRANK and you call `addBucketMemberSlots`, the entity slots that left stay in the bucket, held. Not knowing what left is exactly when `writeSlotContent` is the right door, and its cost is the price of not knowing. The keyed doors are the collection service's and take the store slot first — `decksService.getSlotByKey(decks, key)`, `decksService.holdSlotByKey(decks, key)` — and a hold is given back with `bucketSlot.unholdSlot()`. The by-key write is `decksService.writeSlotContentByKey(decks, key, members)`; on a bucket slot you hold it is `bucketSlot.writeSlotContent(members)`. A bucket's emptiness is the content service's `isSlotEmpty(bucketSlot)`, a member count of zero, so an emptied bucket that nothing holds and nothing watches is released by the guard on the same call that emptied it. **A bucket never sorts.** Its order is what the caller put in — `addBucketMemberSlots` appends, `insertBucketMemberSlotAt` inserts, a move moves, `writeSlotContent` takes the sequence given. A sorted list is a computed over an index: [Sorted lists](#sorted-lists); or the bucket of a `createOIMSlotCollectionSortedArrayIndexService` index, which orders itself: [Sorted at write](#sorted-at-write). `writeSlotContent(bucketSlot, members)` runs `assertWritable` — the frame guard (`assertNotFlushing`) and the released-identity check — then the reconcile (an empty `arrived` and `departed` is an unchanged write, which wakes nobody), the holds taken on arrivals, the holds given back by departures and the single channel write of the bucket slot. It is handed a slot, so it hands back a `boolean`: true when anything arrived or departed. `writeSlotContent` **joins before it evicts**, so a slot named by both the old and the new list never reaches zero references. It empties with one `drainSlots` rather than one removal at a time — per-slot eviction on an array-driven bucket is n(n-1)/2 element moves. The commit itself is the strategy's, through the content service's protected `reconcileSlots` — the reconciliation pattern (diff, then patch): bring the bucket to the new list and fill two out-queues with one entry per hold taken and one per hold given up, so the write links each of the first and unlinks each of the second. Both empty means nothing changed. Each content service reconciles its own way: - **Array-driven**: the caller's sequence IS the slots, so the same sequence is left alone and any other sequence — a reordered one included — is drained and re-added whole. - **Set-driven** takes the set difference and never rebuilds: an untouched member keeps its hold. **NO FRAME NUMBER IS PASSED ON THIS PATH.** `reconcileSlots` and `drainSlots` take none. A render script lives for exactly one frame: `OIMBucketCommands` records onto the bucket slot (`bucket.commands`) as the writes land and empties it once the flush has fully ended, so a consumer reads it INSIDE the frame and what it reads can only describe the writes it was woken for. `clearSlotContent` asks whether the bucket is empty **before** it touches the store, so an already-empty bucket records nothing for a call that reports nothing. ### Bucket content services | Class | Storage type | One add records | |---|---|---| | `OIMSetBucketContentService({ bucketCommands? })` | `TOIMBucketSlotsSetStore` = `Set` | one per slot | | `OIMPositionalArrayBucketContentService({ bucketCommands?, bucketMemberSlotsArrayService? })` | `TOIMBucketSlotsArrayStore` = `{ bucketMemberSlots, uniqueBucketMemberSlots, sortedCount }` | one per **mention**; one per slot, order kept, with `new OIMBucketUniqueMemberSlotsArrayService()` | | `OIMSortedArrayBucketContentService({ compareBucketMemberSlots, bucketMemberSlotsArrayService? })` | `TOIMBucketSlotsArrayStore` | one per mention or per slot, at its sorted place | The first two are the ones a caller picks between, and neither sorts: the array-driven services keep the caller's order. The last is the one the sorted-at-write index builds for itself ([Sorted at write](#sorted-at-write)); its `repositionBucketMemberSlot(bucketSlot, bucketMemberSlot)` moves one member to its place after its sort columns changed. Which slots an array bucket keeps is its `bucketMemberSlotsArrayService`, the only writer of the list and the `Set` beside it: `OIMBucketMemberSlotsArrayService` keeps every mention and no `Set`; `OIMBucketUniqueMemberSlotsArrayService` keeps each slot once and the list and its `Set` together, so the two never disagree. With the unique one `hasBucketMemberSlot` answers from the `Set` (no array walk); with the default it walks the array. Nothing positional is on the abstract `OIMBucketContentService`: the reads `getBucketMemberSlotAt` and `getBucketMemberSlotPosition` are on the array-based services (array-driven and sorted), and the five position writes on the array-driven one only. The set-driven service has none — a `Set` has no place to name, so asking it does not compile. A content service keeps no per-bucket state. The protected `removeSlot` answers WHERE the slot was, so the door recording an edit script never asks for a position the removal itself had to compute. Two of its answers are not positions, and both are exported as named constants: | returns | means | |---|---| | `0` and up | the index the slot occupied, now vacated | | `OIM_NOTHING_WAS_REMOVED` (`-1`) | the bucket did not hold it; nothing changed | | `OIM_REMOVED_WITHOUT_A_POSITION` (`-2`) | removed from a store that keeps no positions, which is the set-driven service | A removal answering the third is recorded as `recordWholeList(bucketSlot)`: a set has no index to patch, so the consumer is told to re-read the bucket rather than handed a fabricated one. `OIM_NOTHING_WAS_INSERTED` (`-1`) is the insert's answer when nothing was inserted, which is a repeat on an array bucket with `OIMBucketUniqueMemberSlotsArrayService`. The recorded insert names the index the slot LANDED on — `at` clamped to the ends of the list — and not `getBucketMemberSlotPosition`, because the default ordered list keeps one place per **mention**: inserting a slot the bucket already holds gives it a second position, and the position read names the FIRST. A command script built from it would tell the consumer to patch at an index the slot is not at, and the consumer's list would diverge from the bucket's permanently. **A bucket's storage kind is in its type.** `TOIMBucketSlot>>` names it, so a mismatched pairing is a compile error; the storage itself is read through the bucket slot's methods and its content service. **One content service instance may serve two bucket collections** — it keeps no per-bucket state. ### Positions the caller decides A bucket whose positions are the caller's is one over `OIMPositionalArrayBucketContentService`, which is the `pageService` of the setup block. The two position reads and the five writes are that content service's, they take the bucket slot and no store slot, and an index is valid only until the next write: | Door | What it does | |---|---| | `getBucketMemberSlotAt(bucketSlot, index)` | who sits there, `undefined` past the end | | `getBucketMemberSlotPosition(bucketSlot, bucketMemberSlot)` | where it sits, `-1` when it does not | | `insertBucketMemberSlotAt(bucketSlot, at, bucketMemberSlot)` | puts it at `at`, clamped to the ends of the list | | `removeBucketMemberSlotAt(bucketSlot, at)` | takes it out and hands it back, `undefined` past the end | | `removeBucketMemberSlotRange(bucketSlot, at, count)` | takes a run out and hands it back | | `moveBucketMemberSlotToPosition(bucketSlot, from, to)` | moves one slot; refuses `from === to` and either end out of range | | `moveBucketMemberSlotRangeToPosition(bucketSlot, from, count, to)` | moves a run; the landing is read in the list WITHOUT the run in it | Every position and count must be a whole number: `NaN` or a fraction throws (`a position must be a whole number`) before anything moves, because the list and `splice` would read it two different ways. `±Infinity` is allowed and clamps like any other out-of-range position. Each wraps a store change in the frame guard, the holds, the report and the release question. The default ordered list records one place per MENTION, so `insertBucketMemberSlotAt` of a slot the bucket already holds gives it a second position — take `bucketMemberSlotsArrayService: new OIMBucketUniqueMemberSlotsArrayService()` when a position must name exactly one entity slot. Per strategy, generating code: ```ts const bucketContentService = pageService.slotContentService; // kanban, between columns const cardItWasDroppedOn = cardService.getSlotByKey(cards, 'c2'); bucketContentService.removeBucketMemberSlotAt(todo, bucketContentService.getBucketMemberSlotPosition(todo, slot)); bucketContentService.insertBucketMemberSlotAt( done, bucketContentService.getBucketMemberSlotPosition(done, cardItWasDroppedOn) + 1, slot, ); // priority queue — raise to the front, then nudge down two bucketContentService.moveBucketMemberSlotToPosition(todo, bucketContentService.getBucketMemberSlotPosition(todo, slot), 0); bucketContentService.moveBucketMemberSlotToPosition( todo, bucketContentService.getBucketMemberSlotPosition(todo, slot), bucketContentService.getBucketMemberSlotPosition(todo, slot) + 2, ); // a whole list at once, in the order the server sent bucketContentService.writeSlotContent(todo, cardService.writeInBatch(cards, () => (payload).map(entity => cardService.writeSlotContentByKey(cards, entity.id, entity)))); ``` ### The render script: `OIMBucketCommands` ```ts signature new OIMBucketCommands(options: { maxCommandsPerSlot?: number }) // default OIM_MAX_COMMANDS_PER_SLOT // a bucket content service takes it at construction, once: new OIMPositionalArrayBucketContentService({ bucketCommands: new OIMBucketCommands({ maxCommandsPerSlot: Infinity }) }); ``` **Recording is a strategy chosen when the bucket content service is built.** `bucketCommands` is read once into a readonly field; left out of a content service built with `new`, it is `OIMNoBucketCommands`, whose every method is empty, so a bucket nobody renders positionally pays one empty call per write and allocates no command. There is no setter: a content service records into the one recorder it was built with. One recorder serves every bucket of every store slot and of every db — it is stateless. It writes the script onto the BUCKET slot itself, and is handed the member count for the cap below. The bucket content service already writes the bucket slot on every mutation, so a consumer subscribes to the bucket and reads the script inside the effect: ```ts effectService.createEffect(db, () => { if (todo.isWholeListRecorded) render(Array.from(todo.getBucketMemberSlots())); else applyToTheRenderedList(todo.commands ?? []); }, [todo]); ``` `TOIMBucketSlot` carries two fields for it, and a consumer reads both: | Field | What it says | |---|---| | `commands` | `readonly TOIMOrderedListCommand[]`, or `undefined` before the first write — what this frame's writes did, in order | | `isWholeListRecorded` | the script was given up on; read the bucket's slots and rebuild | **READ BOTH INSIDE THE FRAME.** They are reset once the flush has FULLY ended — after `db.flush()` returns, `commands` is empty and `isWholeListRecorded` is `false` — so the only places they exist are an effect body and a `OIMChannelService.INSTANCE.subscribeAfterEachFrame(channelSlot, handler)` handler. No frame number is passed back: a consumer that did not read this frame's script reads the list instead. A script is stamped with the clock reading it started at (`commandsStartedAtRevision`/`commandsStartedAtEpoch`), and it is stale once a frame has opened after that stamp (`channelSlot.frame.openedAtRevision`/`openedAtEpoch`). The recorder clears a stale script before it records into it, as well as in the after-flush reset, so a write that lands after a flush but before that reset starts a new script instead of extending one consumers already read. The reset is subscribed with `subscribeAfterEachFlush` on the first script a channel slot ever sees, and walks only the buckets that recorded. A positional write is always recorded as a position. `isWholeListRecorded` is set by a write of the whole bucket — `writeSlotContent`, `clearSlotContent`, `moveBucketMemberSlotRangeToPosition` — by a removal from a bucket whose content service keeps no positions, which has no index to patch, and by the script outgrowing the list it describes. `maxCommandsPerSlot` is that ratio; it defaults to `OIM_MAX_COMMANDS_PER_SLOT`, which is 1, the same ratio `getOIMOrderedListCommands` takes as `maxCommandsPerSlot`. `Infinity` refuses the collapse outright, which is what a consumer animating item moves needs: a whole-list answer tells it everything changed and costs it every move it meant to animate. `IOIMBucketCommands` is the interface the bucket content service records through: `recordInsert(bucketSlot, index, bucketMemberSlot, bucketMemberSlotCount)`, `recordRemove(bucketSlot, index, count, bucketMemberSlotCount)`, `recordMove(bucketSlot, from, to, bucketMemberSlotCount)` and `recordWholeList(bucketSlot)`. They take positions, not a command object, so the empty strategy is handed nothing to allocate. A consumer does not call the record methods; the content service's own write doors do. ### A single bucket One bucket under no key is a store slot of an `OIMSingleSlotService` over a bucket content service, with `OIMSingleSlotStoreService.INSTANCE` as the store service: ```ts signature createOIMSingleSlotService({ slotContentService: new OIMPositionalArrayBucketContentService(), // or the set one slotReleasePolicy?, slotSubscriptionListener?, columnSlotStoreService?, columnNames?, }): OIMWritableSingleSlotService, readonly TBucketMemberSlot[], …> ``` ```ts const handService = createOIMSingleSlotService({ slotContentService: new OIMPositionalArrayBucketContentService>({ bucketCommands: new OIMBucketCommands({ maxCommandsPerSlot: undefined }) }) }); const hand = handService.createStoreSlot(db); const handSlot = handService.holdSingleSlot(hand); handSlot.writeSlotContent([slot]); handService.slotContentService.insertBucketMemberSlotAt(handSlot, 0, cardService.getSlotByKey(cards, 'c2')); effectService.disposeEffect(effectService.createEffect(db, () => { render(Array.from(handSlot.getBucketMemberSlots())); }, [handSlot])); handSlot.unholdSlot(); ``` One bucket, no key: the single-slot store files its one bucket slot as the store's `slot`. The bucket slot is a `TOIMBucketContentSlot` of the keyed bucket slot's shape (`key: undefined`), what an effect subscribes to and what a reader is handed, so the channel's write door still sees three slot shapes. Every door of the bucket content service takes it as it takes a keyed bucket slot, and the util `markOIMBucketColumnsChanged(bucketSlot, patch, changedColumns)` is how the caller that changed members says which of their columns moved, as the index does for a keyed bucket. Each door writes the bucket slot to the channel once. **Its lifetime is the `slotReleasePolicy`.** With none named (here or on the db) it is `OIMSlotAtEmptyReleasePolicy.INSTANCE`, so an emptied single bucket that nothing holds or watches is released, and `getSingleSlot(storeSlot)` mints a fresh, empty one on the next read. Hold the slot (`holdSingleSlot(storeSlot)`) for as long as you write into it, or name `OIMSlotNeverReleasePolicy.INSTANCE`. ### The index that fills itself — `OIMSlotCollectionIndexService` ```ts signature createOIMSlotCollectionIndexService({ entityService: Pick, TSourceStore, unknown>, 'getSlots'>; ...TOIMIndexKeyOptions; // { columns } | { selectKey } | { selectKey, columns } slotContentService?: OIMBucketContentService, TSlots>; // default: array-driven, no commands bucketSlotStoreService?: IOIMSlotStoreService, TStore>; // REQUIRED for an array TKey slotReleasePolicy?: IOIMSlotReleasePolicy; columnSlotStoreService?: IOIMSlotStoreService; columnNames?: readonly string[]; }): OIMSlotCollectionIndexService class OIMSlotCollectionIndexService<…> extends OIMSlotCollectionService<…> { createIndexStoreSlot(sourceStoreSlot: TOIMStoreSlot, Partial>): TOIMIndexStoreSlot<…>; disposeIndexStoreSlot(indexStoreSlot: TOIMIndexStoreSlot<…>): void; getEntitiesByKey(indexStoreSlot, key): TEntity[]; getSlotsByKeys(indexStoreSlot, keys): TBucketSlot[]; holdSlotsByKeys(indexStoreSlot, keys): TBucketSlot[]; getBucketColumnSlotByKey / holdBucketColumnSlotByKey(indexStoreSlot, key, columnName): TOIMColumnSlot; getAnyBucketColumnSlotByKey / holdAnyBucketColumnSlotByKey(indexStoreSlot, key): TOIMColumnSlot; } ``` `OIMSlotCollectionIndexService` is a collection service of buckets, so it has every read door of one, and its `slotContentService` is the bucket content service narrowed by type to its reads (`getBucketMemberSlots`, `getBucketMemberSlotCount`, `hasBucketMemberSlot`, and the positional reads where the strategy has them) — the index is the only writer of its buckets. The strategy is chosen at the factory: `OIMPositionalArrayBucketContentService` by default, `OIMSetBucketContentService` passed as `slotContentService`, and the sorted one built by `createOIMSlotCollectionSortedArrayIndexService`. Only the array-based content services answer by position: `getBucketMemberSlotAt(bucketSlot, index)` (O(1), `undefined` past the end) and `getBucketMemberSlotPosition(bucketSlot, entitySlot)` (walks the array, O(n), `-1` for a non-member). The index's default content service records no commands; pass one built with `bucketCommands` for a render script. **One index service per entity collection type; one index store slot per entity store slot.** `indexService.createIndexStoreSlot(entityStoreSlot)` registers the index on that entity store slot and hands back the index's bucket store slot, a `TOIMIndexStoreSlot` — a store slot of buckets that also names its `sourceStoreSlot`. Entity slots are filed into it by a key derived from the entity. You read through the index service, passing that store slot; the index is what writes its buckets. **No bucket exists for a key until it is minted**: `getSlotByKey`, `holdSlotByKey`, `getSlotsByKeys` and `holdSlotsByKeys` mint it and fill it from the source entities written before it, without a flush, so minting inside an effect body does not throw. `getSlotsByKeys` / `holdSlotsByKeys` fill every new bucket in ONE pass over the source. How long it lives after that is **the `slotReleasePolicy`'s ordinary business**, exactly as for a hand-held bucket; the index injects no lifetime of its own. With none named it is `OIMSlotAtEmptyReleasePolicy.INSTANCE`: the bucket stands while it has members and is maintained on every write. ```ts const byDeckService = createOIMSlotCollectionIndexService({ entityService: cardService, selectKey: (card: Card) => card.deck, }); const byDeck = byDeckService.createIndexStoreSlot(cards); const spades = byDeckService.holdSlotByKey(byDeck, 'spades'); effectService.createEffect(db, () => render(Array.from(spades.getBucketMemberSlots())), [spades]); ``` A set-driven index names its content service with the bucket member slot type and the index key type spelled out — `new OIMSetBucketContentService()` infers `` and fails to type-check: ```ts const bySuitService = createOIMSlotCollectionIndexService({ entityService: cardService, columns: ['deck'], slotContentService: new OIMSetBucketContentService, string>(), }); const bySuit = bySuitService.createIndexStoreSlot(cards); ``` - **Passing the entity store slot to `createIndexStoreSlot` is the whole wiring.** It registers a content-change listener on that store slot (`OIMSlotContentChangeListenerService.INSTANCE.addContentChangeListener`); the entity services know nothing about indexes. Call `createIndexStoreSlot` twice over one entity store slot and it files into both. `entityService` is used only for its `getSlots`, to fill a new bucket from the source. - **The key comes from `columns`, `selectKey`, or both** — the same pair as the sorter's `sortColumns` / `comparator` (`TOIMIndexKeyOptions`). `{ columns: ['deck'] }`: the key is the value of that ONE column, typed by `TOIMIndexKey` from the column itself. `{ selectKey }`: any function, read again on every write, because a function does not say which columns it reads. `{ selectKey, columns }`: the columns are the ones `selectKey` reads. With `columns`, a patch or put whose changed columns include none of them keeps the entity's key and calls nothing; a write of the whole value (a fill, a clear, `markEntityChanged(slot)` with no names) always reads the key again. - **A key of several columns**: `createOIMSlotCollectionIndexService({ entityService, columns: ['deck', 'suit'], bucketSlotStoreService: new OIMSlotTreeStoreService(OIMScalarKeyTreeWalk.INSTANCE) })` makes the key the array of those values in order, typed as a tuple. Only that store knows the key is an array (its `isSameKey`), so a fresh array with the same parts moves nothing. `createOIMSlotCollectionIndexService` takes a scalar key unless it is handed a `bucketSlotStoreService`: two columns or an array `selectKey` without one do not compile. `getSlotsByKeys` / `holdSlotsByKeys` fill array-keyed buckets one pass over the source per key (the cost of `getSlotByKey` each); only a scalar key gets one pass for all. - **Entity slots are filed on write**, using the index's key. Writes inside `writeInBatch` on the collection notify once per batch; the index groups the entity slots by key and moves each group with one bucket write. - **Reading**, each taking the index store slot first: `getSlotByKey`, `holdSlotByKey`, `peekSlotByKey`, `hasSlotContentByKey`, `getSlotsByKeys`, `holdSlotsByKeys`, `getSlots`, `getSlotCount`, `getEntitiesByKey`, and the bucket column slot doors `getAnyBucketColumnSlotByKey`, `holdAnyBucketColumnSlotByKey`, `getBucketColumnSlotByKey`, `holdBucketColumnSlotByKey`; on a bucket slot, `slotContentService.getBucketMemberSlots`, `getBucketMemberSlotCount`, `hasBucketMemberSlot`; and `unholdColumnSlot` (below). `getEntitiesByKey` resolves the bucket with `getSlotByKey`, so a key with no bucket MINTS one — one `selectKey` walk over the source — and an empty unheld bucket is released at the flush, so reading an empty key every frame walks every frame. Hold a key you read repeatedly. - **The channel** is the index store slot's `channelSlot`, the source store slot's — what a React hook checks before subscribing. - **`disposeIndexStoreSlot(indexStoreSlot)`** unsubscribes from the source store slot, empties that store slot's buckets and gives back every entity slot it held. The minting doors (`getSlotByKey`, `holdSlotByKey`, `getSlotsByKeys`, `holdSlotsByKeys`, `getEntitiesByKey`, the bucket column doors) throw after it, for that store slot; the two give-backs (`slot.owner.unholdSlot`, `indexService.unholdColumnSlot`) still take back a hold given out before it, so a cleanup that runs late does not throw. - **A key with no bucket is not maintained at all**, so a write under such a key costs nothing beyond one key read and one comparison — no bucket store, no maintenance nodes. What decides it is the BUCKET, not the hold: a standing bucket is maintained whether anyone holds it or not. - **Order is not the bucket's business, unless you pick the strategy that makes it so.** A bucket keeps its arrival order; a sorted list is `createOIMSortedComputedService(db, { indexService, sortColumns?, comparator? })` — see [Sorted lists](#sorted-lists) — or the index is built with `createOIMSlotCollectionSortedArrayIndexService`, whose buckets are already in order — see [Sorted at write](#sorted-at-write). A second computed over the bucket handles projection or filtering. - **Members are read through the bucket content service**: `Array.from(bucketSlot.getBucketMemberSlots())`. There is no `.value`. - **Subscription is on the bucket, not a computed.** The bucket is a ROOT slot, so it goes in the FIRST array of `createEffect` — not the second. **The bucket wakes on membership only**: an entity slot joining or leaving. A write to an entity that stays in the bucket does not wake it — subscribe to that entity's own slot for that. - **Bucket lifetime is the `slotReleasePolicy` option, not the index's.** Name nothing (here or on the db) and it is `OIMSlotAtEmptyReleasePolicy.INSTANCE`: an unheld bucket stays while it has members and goes once empty; `OIMSlotNeverReleasePolicy.INSTANCE` keeps it for good; pass an `OIMSlotAfterIdleReleasePolicy` and it cools on its queue; pass `OIMSlotAtUnholdReleasePolicy.INSTANCE` and it dies at the last give-back, and the next hold builds a fresh one by walking the source again. **The bucket's any-column slot exists, but it is not the recommended path.** `holdAnyBucketColumnSlotByKey(indexStoreSlot, key)` (and `getAnyBucketColumnSlotByKey(indexStoreSlot, key)`) returns a `TOIMColumnSlot` on the bucket slot that wakes when the content of a member changes — any write to a member inside — and when a member joins or leaves, because its `value` lists the members' entities. A write to a member of another bucket does not wake it. The bucket slot (`getSlotByKey` / `holdSlotByKey`) wakes on membership alone; the example subscribes to both only to show the two doors. ```ts const deckIndexService = createOIMSlotCollectionIndexService({ entityService: cardService, selectKey: (card: Card) => card.deck }); const deckIndex = deckIndexService.createIndexStoreSlot(cards); const spadesBucket = deckIndexService.holdSlotByKey(deckIndex, 'spades'); const spadesAnyColumn = deckIndexService.holdAnyBucketColumnSlotByKey(deckIndex, 'spades'); const entitiesEffect = effectService.createEffect(db, () => { console.log(deckIndexService.getEntitiesByKey(deckIndex, 'spades')); }, [spadesBucket, spadesAnyColumn]); effectService.disposeEffect(entitiesEffect); spadesAnyColumn.unholdSlot(); spadesBucket.unholdSlot(); ``` A column slot taken with `getAnyBucketColumnSlotByKey` and subscribed to is held by the effect, so a plain getter is enough: the slot lives while the effect does and goes at the next `flush()` after `disposeEffect`; one nobody kept is gone at the next `flush()`. **Do not reach for it to render a list.** Every edit of every member wakes whoever reads it, so a list bound to it re-renders whole for a one-field change. Subscribe the list to the bucket (membership) and each item to its own entity slot — that is the path the engine is built for. The any-column slot is for a reader that genuinely needs the whole list each time: an export, an aggregate over the entities, a log. It costs nothing until someone asks for one: a write is checked against it only after the index has been asked for the first any-column slot. **The content-change hook.** `OIMSlotContentChangeListenerService.INSTANCE.addContentChangeListener(storeSlot, listener, readColumnNames): TOIMSlotContentChangeListenerReadColumns` and `removeContentChangeListener(storeSlot, listener): boolean` file and unfile a listener on that one store slot, by the listener object. `addContentChangeListener` returns the listener's record, `{ declaredColumnNames, addedColumnNames, isAnyColumnAdded }`. `addListenerReadColumn(storeSlot, listener, columnName)` and `addListenerReadAnyColumn(storeSlot, listener)` add reads to that listener later, which is how an index declares its bucket columns; the counts behind them are private. `isOIMAnyAddedColumnRead(listenerReadColumns, changedColumns)`, a util, says whether a write's changed columns hit one of the added reads. Removing the listener gives back its declared and its added columns. **Which columns a listener reads** is declared when it is added: `readColumnNames` lists them, and `undefined` means every column. Removing the listener gives its columns back. An index store slot declares its key `columns` (all columns when the key is an opaque `selectKey`), and adds each column its bucket column slots watch, and all columns once a bucket any-column slot was asked for. Column slots on entities are not in it: a write finds them on the entity itself. A write whose changed columns no listener reads costs one `Map.has` per name: no listener is called, nothing is buffered, and the names array is reused across writes. A write that names no columns (a fill, a clear) always reaches the listeners. A listener of your own that must see every column write is added with `readColumnNames` `undefined`. **The filter is the union, per store slot, not per listener**: once a write touches a column ANY listener of that store reads, every listener of that store is called, so a listener that declared a narrower set still checks `changedColumns` itself, as `OIMSlotCollectionIndexService` does against its key columns. `IOIMSlotContentChangeListener` has two methods: `onContentChanged(slot, patch, changedColumns)` and `onManyContentsChanged(slotChannelQueue, patchChannelQueue, changedColumnsChannelQueue)` — three parallel `OIMChannelQueue`s read with `getEntryCount()` / `getEntryAt(i)`, valid only during the call, so a listener copies what it keeps — `patch` is what an update wrote, `changedColumns` the names `markEntityChanged(slot, columns)` was given, either `undefined` when the write carries none. A single write outside a batch delivers one `onContentChanged` as soon as it is filed; inside `writeInBatch` (or `openBatch` / `closeBatch`) on the collection the writes are queued on the store slot and delivered as ONE `onManyContentsChanged` when the outermost batch closes. Code inside the batch reads the index as it was before the batch. This hook is the only seam an index uses; an index of your own is a listener. **Bucket column slots.** An index hands out one column slot per bucket and column: `getBucketColumnSlotByKey(indexStoreSlot, key, columnName)`, `holdBucketColumnSlotByKey(indexStoreSlot, key, columnName)`, `indexService.unholdColumnSlot(columnSlot)`. It is a `TOIMColumnSlot` whose `carrierSlot` is the bucket slot, and it is written when a write changes that column on any member of the bucket, and when a member joins or leaves, since its `value` lists that column across the members (the index calls `markOIMBucketColumnsChanged(bucketSlot, patch, changedColumns)`, as the caller does on a single bucket). The any-column doors `getAnyBucketColumnSlotByKey(indexStoreSlot, key)` / `holdAnyBucketColumnSlotByKey(indexStoreSlot, key)` return the same kind of slot, written when any column of any member changes. A give-back is `slot.unholdSlot()`. ```ts const decksService = createOIMSlotCollectionIndexService({ entityService: cardService, selectKey: (card: Card) => card.deck }); const decks = decksService.createIndexStoreSlot(cards); const rankOfSpades = decksService.holdBucketColumnSlotByKey(decks, 'spades', 'rank'); effectService.disposeEffect(effectService.createEffect(db, () => {}, [rankOfSpades])); rankOfSpades.unholdSlot(); ``` ### Sorted lists ```ts signature createOIMSortedComputedService({ indexService: OIMSlotCollectionIndexService; sortColumns?: readonly TOIMSortColumn[]; // { columnName: TOIMSortableColumnName; direction: 'asc' | 'desc' } comparator?: (left: TEntity, right: TEntity) => number; slotReleasePolicy?: IOIMSlotReleasePolicy; // default OIMSlotAtUnholdReleasePolicy.INSTANCE columnSlotStoreService?: IOIMSlotStoreService; slotStoreService?: IOIMSlotStoreService, TComputedStore>; // Map; REQUIRED for any other store }): OIMSortedComputedService createSortedStoreSlot(indexStoreSlot: TOIMIndexStoreSlot<…>): TOIMStoreSlot> // OIMSortedComputedService extends OIMSlotCollectionService, TComputedStore, …, TOIMComputedColumnSlot, OIMPullColumnSlotOwner> ``` `slotReleasePolicy` decides whether a key's sorted list outlives its last hold. The default lets it go at the unhold, so holding the key again sorts from scratch; `OIMSlotNeverReleasePolicy.INSTANCE` keeps every key that was ever read and re-sorts it only when a read finds it changed — the arm for a view that switches between groups. Pass the same policy to the index the list reads, or its bucket is rebuilt instead. An `OIMSortedComputedService` takes no db: its store slots run on the channel slot of the index store slot they sort. One per index service. `createSortedStoreSlot(indexStoreSlot)` makes one sorted store slot over one index store slot, and the service's own read doors take that store slot first: `getSlotByKey`, `holdSlotByKey`, `peekSlotByKey`, `getSlots`, `getSlotCount`, and the column doors; per key a computed slot whose value, read through `slot.value`, is that key's entity slots sorted. A hold is given back with `slot.unholdSlot()`. - **`sortColumns` decide which writes re-sort**: only a write that changes one of them on a member. A `TOIMSortableColumnName` is a column whose values are strings, numbers or bigints. - **`comparator` decides the order.** Without it the order is `createOIMColumnsComparator(sortColumns)`: the columns in turn, each by its `direction`, an undefined or null value last. An entity slot with no entity sorts last. - **Only `comparator`** → any write to a member re-sorts, since nothing names the columns it reads. - **Neither** → a member keeps the place it first took; an arrival is appended. - **Both `sortColumns` and `comparator`** → the two split the job: `comparator` orders, `sortColumns` is the list of columns whose change wakes the sort. **List every column the comparator reads**: a change to a column it reads but `sortColumns` omits does not re-sort, and the list stays in its old order until something listed changes. This is the combination to reach for when the order needs a rule `createOIMColumnsComparator` cannot express — a locale compare, a computed key, a tie-break — and the sort should still wake only for the columns that rule reads, instead of for every write to a member as with `comparator` alone. ```ts const cardsInDeckService = createOIMSlotCollectionIndexService({ entityService: cardService, selectKey: (card: Card) => card.deck, }); createOIMSortedComputedService({ indexService: cardsInDeckService, sortColumns: [{ columnName: 'title', direction: 'asc' }, { columnName: 'rank', direction: 'asc' }], comparator: (l, r) => l.title.localeCompare(r.title, 'de') || l.rank - r.rank, }).createSortedStoreSlot(cardsInDeckService.createIndexStoreSlot(cards)); // a write to `title` or `rank` re-sorts; a write to `note` does not ``` Its sources are the bucket slot of the key (membership) plus the bucket column slot of each column — or the bucket's any-column slot when only a comparator is given. It is a pull computed: re-derived on the read that asks; an effect subscribes to it in the SECOND array of `createEffect`. A re-sort that yields the same sequence (`isOIMSameSlotSequence`) keeps the previous array, so its identity is stable. ```ts const decksService = createOIMSlotCollectionIndexService({ entityService: cardService, selectKey: (card: Card) => card.deck }); const decks = decksService.createIndexStoreSlot(cards); const byRankInDeckService = createOIMSortedComputedService({ indexService: decksService, sortColumns: [{ columnName: 'rank', direction: 'asc' }], }); const byRankInDeck = byRankInDeckService.createSortedStoreSlot(decks); const spadesByRank = byRankInDeckService.holdSlotByKey(byRankInDeck, 'spades'); const sortedEffect = effectService.createEffect(db, () => { render(spadesByRank.value); }, [], [spadesByRank]); effectService.disposeEffect(sortedEffect); spadesByRank.unholdSlot(); ``` ### A whole collection, sorted `createOIMSortedCollectionSingleSlotStoreAggregate(entitySlotCollectionStoreAggregate, { sortColumns?, comparator? })` sorts every entity of a collection with no index. The options are those of `createOIMSortedComputedService`; given both, `comparator` decides the order. It returns an `OIMSingleSlotStoreAggregate` of a computed: `getSingleSlot().value` is the collection's entity slots in order. ```ts const byRank = createOIMSortedCollectionSingleSlotStoreAggregate(cardService.createStoreAggregate(cards), { sortColumns: [{ columnName: 'rank', direction: 'asc' }] }); db.createEffect(() => render(byRank.getSingleSlot().value)); ``` - It re-sorts when an entity arrives or leaves and on a write to a sort column; with a `comparator`, on a write to any column. A write to another column does not wake its reader. - Its sources are the collection's list (`OIMSlotCollectionBucketService.INSTANCE.getBucketSlot`) and one list column slot per sort column (`getBucketColumnSlot`), or the list's any-column slot with a `comparator`. - While nobody reads it, the collection pays nothing: its listener goes with the list. - In a schema it sits next to the collection: `createSchemas: (db) => { const cards = createOIMEntitySlotCollectionStoreAggregate(db); return { default: { cards, byRank: createOIMSortedCollectionSingleSlotStoreAggregate(cards, { sortColumns: [{ columnName: 'rank', direction: 'asc' }] }) } }; }`. ### Sorted at write A second way to get a sorted list. `createOIMSortedComputedService` sorts at read, over any index. `createOIMSlotCollectionSortedArrayIndexService` keeps the index's own buckets sorted at write, and the user picks one at construction. ```ts signature createOIMSlotCollectionSortedArrayIndexService({ entityService, ...TOIMIndexKeyOptions, // as createOIMSlotCollectionIndexService, scalar key sortColumns: readonly TOIMSortColumn[]; // REQUIRED bucketCommands?, // records every change as the whole list bucketSlotStoreService?, slotReleasePolicy?, columnSlotStoreService?, columnNames?, }): OIMSlotCollectionSortedArrayIndexService<…> // its slotContentService is an OIMSortedArrayBucketContentService ``` ```ts declare const someCardSlot: TOIMEntitySlot; const cardsByDeckService = createOIMSlotCollectionSortedArrayIndexService({ entityService: cardService, columns: ['deck'], sortColumns: [{ columnName: 'rank', direction: 'asc' }, { columnName: 'id', direction: 'desc' }], }); const cardsByDeck = cardsByDeckService.createIndexStoreSlot(cards); const spades = cardsByDeckService.holdSlotByKey(cardsByDeck, 'spades'); for (const cardSlot of spades.getBucketMemberSlots()) { /* in rank order */ } cardsByDeckService.slotContentService.getBucketMemberSlotAt(spades, 0); cardsByDeckService.slotContentService.getBucketMemberSlotPosition(spades, someCardSlot); ``` - **Reads come back in order**: `getBucketMemberSlots`, `getBucketMemberSlotAt` and `getBucketMemberSlotPosition` on `OIMSortedArrayBucketContentService` answer in `sortColumns` order, so no sorted computed is needed. - **A lazy insertion buffer.** A write appends the arrival to an unsorted tail of the bucket's array (`TOIMBucketSlotsArrayStore`: the array store plus `sortedCount`). The first read settles the tail: binary insertion when the tail is short, one sort of the array when it is long. A bucket nobody reads is never sorted. - **The index re-files a member when one of its sort columns changes, and only then.** A write to a column that is neither the key nor a sort column neither reorders the bucket nor wakes it. A re-file wakes the bucket once per frame. - **There are no positional writes** on this bucket (`insertBucketMemberSlotAt` and the other position writes belong to `OIMPositionalArrayBucketContentService`): the order is the comparator's, not the caller's. - **Bucket commands record the whole list.** With `bucketCommands`, every change is recorded as `isWholeListRecorded` with no commands, since the next settle could move any position a command would name; the view rebuilds from `getBucketMemberSlots()`. Without it, `OIMNoBucketCommands` records nothing. - **Parts**: `OIMSortedArrayBucketContentService` (options `TOIMSortedArrayBucketContentServiceOptions`: `compareBucketMemberSlots`; adds `repositionBucketMemberSlot(bucketSlot, bucketMemberSlot)`), `OIMSlotCollectionSortedArrayIndexService`. **Choosing between the two arms.** Sort-at-write suits point updates: a change to a sort column re-files one member. Sort-at-read (`createOIMSortedComputedService` over any index) suits bulk loads. Both are shipped; neither is a default. **`indexKeys` on each entity slot.** Each indexable slot carries, per index store slot, the key the entity is filed under now, so a moved entity slot leaves its old bucket in O(1), also under the in-place writer. Only the index writes it, through the `IOIMIndexKeysService` (`get(slot, position)`, `set(slot, position, indexKey)`), at the position `createIndexStoreSlot` allocated (`indexStoreSlot.indexKeysPosition`). Positions are allocated per entity store slot (`sourceStoreSlot.indexKeysPositions`). Pick the strategy with `new OIMDefaults({ indexKeysService })` passed as `defaults` (default `OIMAppendingIndexKeysService.INSTANCE`): | strategy | on `disposeIndexStoreSlot` | cost | |---|---|---| | `OIMAppendingIndexKeysService` (default) | the index's position is never reused; its stale entry stays on each entity slot | an entity slot's `indexKeys` grows to the highest position any index wrote on it (K indexes made and disposed → an array of K on an entity slot the last one filed), and a stale entry keeps its key reachable. Writes pay nothing for a disposed index: only live listeners are kept | | `OIMReclaimingIndexKeysService` | wipes that position on every entity slot of the source store slot and reuses it | O(N) per dispose | Switch to `OIMReclaimingIndexKeysService` only if you create indexes dynamically and often. Creating indexes dynamically and often is expensive, so avoid it. ### The channel of a bucket store slot A bucket store slot takes its channel slot at `createStoreSlot(db)` (an index store slot, from its source store slot). The refusal to write during a flush lives inside `OIMChannelService.INSTANCE.write`. --- ## Derivations ```ts signature type TOIMComputedSources = { readonly sourceSlots: readonly TOIMSlot[]; readonly sourceComputeds: readonly TOIMComputedSlot[]; }; ``` In a `createSources` result (of `createOIMComputedService`'s options, or of `createStoreSlot`) both `sourceSlots` and `sourceComputeds` are optional; a missing one means none. ```ts signature type TOIMComputedSlot = NonNullable> = TOIMIndexableSlot & Readonly & { readonly owner: IOIMSlotOwner; readonly value: TValue; readonly checkedAtRevision: number; readonly checkedAtEpoch: number; readonly isDeriving: boolean; readonly rootSlots: readonly TOIMSlot[] | undefined; }; interface IOIMComputedValueService { getValueForSlot(computedSlot: TOIMComputedSlot): TValue; } ``` A computed is a SLOT, the plain data type `TOIMComputedSlot`. Its owner is the slot owner of the `OIMComputedService` that minted it, and the service is the only writer of the slot. The value service (`OIMComputedValueService`, behind the slot's `value` getter) holds the `sameValueGuard` ONCE, the store slot holds its `derive` and `createSources` and its channel slot's clock, and the value service serves the value. Every source list in this engine — `createEffect`'s third argument and `sourceComputeds` — is typed `readonly TOIMComputedSlot[]`; a source computed is a slot taken from its own service, through `computedService.getSlotByKey(storeSlot, key)`, or for a single computed (`createOIMSingleComputedService`) through the service's own `getSingleSlot(storeSlot)`. Inside `derive`, `computedSlot.value` is the previous value. A derivation is **asked, never woken**. A chain short-circuits on "did anything I read move?", so `filter → sort → page` over quiet roots is a walk of integer comparisons. A cycle cannot be built. **Creating a service or a store slot takes no hold.** A computed slot is held on every slot in its `sourceSlots` and on every entry of its `sourceComputeds`, and the holder is its owner: it takes them when it mints the slot and gives them back when the slot's content is released. The slot dies when nothing holds it; the store slot lives on and mints a fresh slot on the next read or hold. ### One derivation per key ```ts signature class OIMComputedService extends OIMSlotCollectionService, TComputedStore, OIMComputedValueService, Extract, TOIMComputedColumnSlot, OIMPullColumnSlotOwner> { constructor(options: TOIMComputedServiceOptions); createStoreSlot(channelMap: IOIMChannelMap, derive?, createSources?): TOIMComputedStoreSlot; } createOIMComputedService>>({ createSources?: (computedSlot: TOIMComputedSlot) => Partial; derive?: (computedSlot: TOIMComputedSlot) => TValue; sameValueGuard?: TOIMSameValueGuard; // default Object.is releaseValue?: TOIMComputedValueReleaser; // default: gives back nothing initialValue?: TValue; slotReleasePolicy?: IOIMSlotReleasePolicy; // default OIMSlotAtUnholdReleasePolicy.INSTANCE columnSlotStoreService?: IOIMSlotStoreService; // defaults.computedColumnSlotStoreService, then a shared map store columnNames?: readonly Extract[]; slotStoreService?: IOIMSlotStoreService, TComputedStore>; // Map; REQUIRED for any other store }): OIMComputedService ``` **`releaseValue(value)` gives back what a derived value holds** (a request in flight, a timer). It is called with the previous value when `derive` produced one `sameValueGuard` calls different; with a new object the guard calls equal (the slot keeps the old one, the new one is dropped); with the current value when the computed slot is released; with the value a `derive` returned after its own slot was released (not stored). It is not called when `derive` returns the object the slot already holds, and never with `initialValue`. `createOIMSingleComputedService` takes it too. The factory takes no db: a computed service is configuration, and each store slot takes its channel slot at `createStoreSlot(db, …)`. **`derive` and `createSources` come from the store slot or from the service.** Each one a store slot is given (`createStoreSlot(db, derive, createSources)`) is used for that store slot; each one it is not given comes from the service's options. A store slot that would end up without one of the two throws by name at `createStoreSlot`. So one service per value type can serve many derivations, each its own store slot. Doors of a keyed computed store slot are the computed service's own read doors, each taking it first: `getSlotByKey(storeSlot, key)`, `holdSlotByKey(storeSlot, key)`, `peekSlotByKey(storeSlot, key)`, `getSlots(storeSlot)`, `getSlotCount(storeSlot)`, and the column doors; the value is `slot.value`, and a give-back is `slot.unholdSlot()`. **A single computed is its own service.** `createOIMSingleComputedService({ … })` builds an `OIMSingleComputedService`, whose store slots each hold at most one computed slot, read through the service itself (it extends `OIMSingleSlotService`) (`getSingleSlot`, `holdSingleSlot`, `peekSingleSlot`). Like a keyed one, a store slot outlives every computed slot it mints and mints a fresh one on the next read or hold once the previous one is gone. ```ts const topRankService = createOIMSingleComputedService({ sameValueGuard: isOIMSameValueZero, initialValue: -1, }); const topRank = topRankService.createStoreSlot( db, () => cardService.getSlotByKey(cards, 'c1').entity?.rank ?? -1, () => ({ sourceSlots: [cardService.getSlotByKey(cards, 'c1')] }), ); const heldTopRank = topRankService.holdSingleSlot(topRank); // the same slot while anything holds it heldTopRank.value; heldTopRank.unholdSlot(); // gone; the next holdSingleSlot(topRank) mints a new one ``` A single computed store slot has no key and a store of one slot. `getSingleSlot(storeSlot)` hands a slot without a hold — a fresh one goes to the unused-slot collector and is let go at the next flush unless something holds it — and `holdSlotByKey(storeSlot, undefined)` holds the live slot, minting one if the previous is gone. A computed slot goes at its last unhold once no effect reads it (`OIMSlotAtUnholdReleasePolicy`, the default), and gives back the holds it took on its sources. A last unhold during a flush releases it at once, as for every slot. The holds a computed takes on its sources and gives back are one stateless service, shared by both shapes. **`createSources` takes the key and the store slot, and nothing else. There is no `keep`.** A build that needs a source resolves it with `holdSlotByKey` or `getSlotByKey` like any other caller, and the holds the service itself takes are the ones named in `sourceSlots` / `sourceComputeds` — so the source list IS the dependency list, and a source a build closes over without naming is a source nothing holds. **A derivation is never empty.** `OIMComputedService` answers "empty" with `false`, so a filed derivation is released only when nothing holds it, nothing watches it, and the grace is `0` — which is what `OIMSlotAtUnholdReleasePolicy` answers, and the default when no `slotReleasePolicy` is given. ```ts setup const rankService = createOIMComputedService({ createSources: ({ key }) => ({ sourceSlots: [cardService.getSlotByKey(cards, key)] }), derive: (computedSlot) => cardService.getSlotByKey(cards, computedSlot.key).entity?.rank ?? -1, sameValueGuard: isOIMSameValueZero, initialValue: -1, }); const ranks = rankService.createStoreSlot(db); ``` ```ts const rank = rankService.holdSlotByKey(ranks, 'c1'); rank.value; rank.unholdSlot(); ``` ### Computed columns A computed's value can be subscribed to by field. A computed's carrier slot has the same six column doors an entity slot has: `getColumnSlot(columnName)`, `holdColumnSlot(columnName)`, `getColumnGroupSlot(group)`, `holdColumnGroupSlot(group)` (a group named in the factory's `columnGroups`), `getAnyColumnSlot()` / `holdAnyColumnSlot()`, plus `watch(body, columnNames?)`. Its type is `TOIMComputedCarrierSlot` = `TOIMComputedContentSlot` plus those members; `TOIMComputedSlot` is built on it, and a single computed service's `getSingleSlot` / `holdSingleSlot` hand it out. The service's `columnSlotService` has the same doors with the slot first, and `unholdColumnSlot(columnSlot)`. Every computed factory takes `columnNames`, `columnGroups` and `slotSubscriptionListener`. On the sorted and bucket-memo factories the value is an array of slots, so a column of it is a key of the array (`length`, for one), not a member's field. Column names are typed as the keys of the value. A computed's column slot is the same `OIMColumnSlot` an entity's is, under the pull column owner: its value is `carrier.value[column]` (a tuple of the group's fields, ordered by the sorted column names, for a group, the whole value for the any-column), compared with `Object.is`. It is a `TOIMComputedColumnSlot`, which carries the carrier's tracker type: a column of a plain computed goes in the SECOND array of `createEffect`; a column of a source-tracking computed is refused there by type and goes in the fifth list (`sourceTrackingComputeds`, which takes any computed). It wakes an effect only when that field of the derived value changes. Pinned by `computed/tests/what-a-computed-column-wakes-on.test.ts`. ```ts type Summary = { top: number; count: number }; const summaryService = createOIMSingleComputedService(); const summary = summaryService.createStoreSlot( db, () => ({ top: slot.entity?.rank ?? -1, count: cardService.getSlotCount(cards) }), () => ({ sourceSlots: [slot] }), ); const summaryTop = summaryService.getSingleSlot(summary).holdColumnSlot('top'); const topEffect = effectService.createEffect(db, () => { paint(slot.entity); }, [], [summaryTop]); effectService.disposeEffect(topEffect); summaryTop.unholdSlot(); ``` ### The order of a bucket, as one derivation per key ```ts signature createOIMBucketMemoComputedService({ bucketCollectionService: OIMSlotCollectionService, TBucketStore, OIMBucketContentService, …>; slotReleasePolicy?: IOIMSlotReleasePolicy; // default OIMSlotAtUnholdReleasePolicy.INSTANCE columnSlotStoreService?: IOIMSlotStoreService; slotStoreService?: IOIMSlotStoreService, TComputedStore>; }): OIMBucketMemoComputedService createBucketMemoStoreSlot(bucketStoreSlot: TOIMStoreSlot, readonly TBucketMemberSlot[]>): TOIMStoreSlot> ``` It takes no db: a memo store slot runs on the channel slot of the bucket store slot it reads. The class is `new OIMBucketMemoComputedService(options)` (options type `TOIMBucketMemoComputedServiceOptions`), whose The service's own read doors read the per-key derivations; `createBucketMemoStoreSlot(bucketStoreSlot)` makes one memo store slot over one bucket store slot. Subscribe to THIS, not to the bucket, when a consumer wants the list as an array it can compare by identity. The value is the bucket's slots in the bucket's order; it is produced on the read that asks for it and never while nothing reads it, and its `changedAtRevision` and `changedAtEpoch` move only when the list a reader would see actually changed. The list is handed back by IDENTITY: it is the same array for as long as the list holds, so a consumer memoising on identity needs no comparison of its own. For a SORTED list use [`createOIMSortedComputedService`](#sorted-lists). The source list is ONE slot — the bucket — and it never grows: a bucket change is a move of the bucket's value, not of the derivation's sources. ```ts const orderService = createOIMBucketMemoComputedService({ bucketCollectionService: orderedService, }); const order = orderService.createBucketMemoStoreSlot(ordered); const deck = orderService.holdSlotByKey(order, 'spades'); // mints the bucket too, and holds it effectService.createEffect(db, () => render(deck.value), [], [deck]); ``` --- ## Key stores ```ts signature interface IOIMSlotStoreService, TSlot extends TOIMKeyedSlot = TOIMKeyedSlot, TStore = unknown> extends IOIMSlotFilingService { createStore(): TStore; // from IOIMSlotFilingService, with the next two set(store: TStore, slot: TSlot): void; // files the slot under slot.key delete(store: TStore, slot: TSlot): void; // unfiles it ownKey(key: TOwnedKey): TOwnedKey; isSameKey(key: TKey, otherKey: TKey): boolean; get(store: TStore, key: TKey): TSlot | undefined; getSlots(store: TStore): IterableIterator; // keyed stores only; a single slot store has neither getSlotCount(store: TStore): number; } ``` **The store service is STATELESS and the storage is its first argument.** It builds the storage with `createStore()` and the store slot keeps it, as `storeSlot.store`; `getSlotCount` is a method taking that storage, not a getter. One store service instance can therefore serve every store slot of every service in a process. **`ownKey(key)` is the key a slot is minted with, and the store never touches a slot.** The collection service asks it once, before the content service's `createSlot`, so the slot's `key` is written by its owner and no one else. The map-driven store answers the key itself; the tree-driven one answers a copy of the composite key, so a caller reusing the array it handed in cannot change the key of a slot already filed. **`isSameKey(key, otherKey)` is what the store means by one key.** The map-driven store answers SameValueZero; the tree-driven one compares length and then every part by SameValueZero, so two arrays with the same parts are one key. Every collection service answers the same question as `service.isSameKey(key, otherKey)`, asking its own store service; an index deciding whether a key moved first checks `===` (the key columns did not change) and otherwise asks its bucket store service. ```ts signature type TOIMSlotStoreTree = { readonly rootCompositeKeyNode: TOIMCompositeKeyNode; readonly slots: Set; }; type TOIMCompositeKeyNode = { childNodes: Map> | undefined; atThisKey: TAtKey | undefined; }; ``` `TOIMSlotStoreTree` is what `OIMSlotTreeStoreService.createStore()` builds: the tree's root plus a flat `Set` of every filed slot, which makes `getSlots()` and `getSlotCount()` O(1) rather than a walk, and keeps `getSlots()` in filing order like every other store. `TOIMCompositeKeyNode` is one level of that tree — a `Map` from composite key part to the level below, created only when the first longer key is filed under it (a leaf has `childNodes: undefined`), and the slot, if any, whose key ends here. Both are exported so a caller can annotate the storage they are holding; neither is something you build by hand. | Store | Key type | |---|---| | `OIMSlotMapStoreService` | `TOIMStoreKey` = `string \| number` | | `OIMSlotTreeStoreService` built with `OIMScalarKeyTreeWalk.INSTANCE` | `readonly TOIMStoreKey[]` — **a chain of VALUES**; a part may also be `null` or `undefined` | | `OIMSlotTreeStoreService` built with `OIMCompositeKeyTreeWalk.INSTANCE` | `readonly TOIMEntitySlot[]` — **a chain of entity SLOTS** | | `OIMSingleSlotStoreService.INSTANCE` | `void` — one slot per store slot, its store a `TOIMSingleSlotStore` (`{ slot }`); what every single is built on | Two stores for keys, one per shape of address, and the single-slot store for no key. The chain store descends one `Map` lookup per composite key part, keeps `[a]` and `[a, b]` apart, and has **no encoding step**: `JSON.stringify` and a NUL-join were both rejected — the latter was not injective, so `['a b']` and `['a', 'b']` were one key. **The two DESCENTS are a fork chosen at construction, and the choice is about lifetime.** The store takes an `IOIMKeyTreeWalk` as its only constructor argument; there is no runtime branch on what a composite key part is, and the first type parameter is the composite key part type. Do not treat the strategies as one store with looser typing, and do not expect a class per strategy — there is one store class and two walks. ```ts signature interface IOIMKeyTreeWalk { mintNodeAt( rootCompositeKeyNode: TOIMCompositeKeyNode, compositeKey: readonly TStoreCompositeKeyPart[], ): TOIMCompositeKeyNode; nodeAt( rootCompositeKeyNode: TOIMCompositeKeyNode, compositeKey: readonly TStoreCompositeKeyPart[], ): TOIMCompositeKeyNode | undefined; deleteKey( rootCompositeKeyNode: TOIMCompositeKeyNode, compositeKey: readonly TStoreCompositeKeyPart[], ): TAtKey | undefined; } ``` `deleteKey` takes the value filed at the key and hands it back, in one descent: one `Map.get` per key part and no array of the path. On the way back up it unlinks every node the delete left empty and stops at the first one that still holds a value or leads to a longer key, so `['u1', 'p7', 'x']` survives a delete of `['u1', 'p7']`. A key that is only a prefix of filed keys, or reaches nothing, deletes nothing and returns `undefined`. | Walk | Class | Shared instance | What a composite key part is | Holds? | |---|---|---|---|---| | scalar | `OIMScalarKeyTreeWalk` | `OIMScalarKeyTreeWalk.INSTANCE` | `TOIMStoreKey`, `null` or `undefined` | no | | composite | `OIMCompositeKeyTreeWalk` | `OIMCompositeKeyTreeWalk.INSTANCE` | `TOIMEntitySlot` | **yes — one hold per edge** | **The hold is the whole difference.** `OIMCompositeKeyTreeWalk.mintNodeAt` calls `holdCompositeKeyPart` the first time it creates an edge, which runs `entitySlot.holdSlot()`; `deleteKey` calls `unholdCompositeKeyPart` on exactly the edges it unlinked, deepest first and only after every unlink is done, which runs `entitySlot.unholdSlot()` unless `isOIMSlotReleased(entitySlot)` — so an entity slot stays addressable for as long as its composite key parts are, and a composite key part nothing else refers to goes the moment the last entity keyed on it does. The scalar walk holds nothing: a value has no identity to keep alive. Under both, `[]` is a key: its slot is filed at the root node. Construct the classes yourself only if you want your own instance; both walks are stateless, and the shared one on `OIMDefaults` is what you normally pass. ```ts // A CHAIN OF VALUES — `['deck-1', 'red']`. type TScalarChain = readonly TOIMStoreKey[]; type Tally = { deck: string; day: string; count: number }; type TTallyStore = import('@oimdb/core').TOIMSlotStoreTree, TOIMStoreKey>; const tallyService = createOIMSlotCollectionService< ReturnType>, TTallyStore >({ slotContentService: createOIMEntityContentService(), slotStoreService: new OIMSlotTreeStoreService>( OIMScalarKeyTreeWalk.INSTANCE, ), }); const tallies = tallyService.createStoreSlot(db); tallyService.writeSlotContentByKey(tallies, ['spades', 'mon'], { deck: 'spades', day: 'mon', count: 1 }); tallyService.getSlotByKey(tallies, ['spades', 'mon']); ``` ```ts // A CHAIN OF IDENTITIES — each composite key part is a slot, and each edge takes a counted // hold on it, so the entity keeps its composite key parts resolvable for as long as it is // addressable. type User = { id: string }; type Group = { id: string }; declare const alice: TOIMEntitySlot; declare const admins: TOIMEntitySlot; type Enrolment = { user: TOIMEntitySlot; group: TOIMEntitySlot; since: number; }; type TChain = readonly TOIMEntitySlot[]; type TEnrolmentStore = import('@oimdb/core').TOIMSlotStoreTree, TOIMEntitySlot>; const enrolmentService = createOIMSlotCollectionService< ReturnType>, TEnrolmentStore >({ slotContentService: createOIMEntityContentService(), slotStoreService: new OIMSlotTreeStoreService>( OIMCompositeKeyTreeWalk.INSTANCE, ), }); const enrolments = enrolmentService.createStoreSlot(db); enrolmentService.writeSlotContentByKey(enrolments, [alice, admins], { user: alice, group: admins, since: 2026 }); enrolmentService.getSlotByKey(enrolments, [alice, admins]); ``` **Never put a scalar in a composite-walk key.** It is a type error, and past a cast it throws a TypeError inside the mint, setting `holdCount` on a string, after the edge is already in the tree. `OIMScalarKeyTreeWalk.INSTANCE` is the walk for that key — the same store class, the other strategy. **Compare a chain with the strategy that matches it**: `isOIMSameSlotSequence` for identities (reference, per composite key part), `isOIMSameKeySequence` for a chain or list of values. `isOIMSameSlotSequence` over a scalar chain is the `NaN` defect — it answers "a different address" for the address the tree is looking at. --- ## Lifetime — the owner protocol **`slot.owner` is the only reference a slot carries, and it is never `undefined`.** Every slot minted anywhere has one: a slot a collection filed carries that collection type's slot owner (an `OIMSlotOwnerService`) — keyed or single alike — and a slot that has been released KEEPS its owner and raises the RELEASED flag in `slot.slotFlags` instead, which the doors below read. ```ts signature interface IOIMSlotOwner { holdSlot(slot: TOIMSlot): void; unholdSlot(slot: TOIMSlot): void; releaseSlotIfUnheld(slot: TOIMSlot): void; unsafeMutateSlot(slot: TOIMSlot, mutateSlot: (editableSlot: TOIMEditable) => void): void; subscribeToSlot(slot: TOIMSlot, effect: TOIMEffect, edge: number, columnGroup?: TOIMColumnGroup): number; unsubscribeFromSlot(slot: TOIMSlot, positionInSlot: number, effect: TOIMEffect): boolean; } ``` At a deadline the release queue reads its MARKER off the slot, decides, and calls `releaseSlotIfUnheld` itself. The owner has no "how long is left" question. | Door | What it is for | |---|---| | `holdSlot(slot)` | `holdCount++`. That is all — no handle, no `{ slot, release }` record. **Throws by name** on a released slot | | `unholdSlot(slot)` | `holdCount--`; at `0` it calls the `protected onSlotUnheld(slot)` hook, whose base body runs `releaseSlotIfUnheld`. **The base opens no window** — nothing is stamped here, so a slot whose deadline has passed goes at this call. **Throws by name** on a released slot, and when `holdCount` is already `0`: a second unhold against one hold would release a slot somebody else is reading | | `releaseSlotIfUnheld(slot)` | run the release guard. Releases only an unheld, still-owned, out-of-grace slot that carries no column slots; **returns silently** on one already released | | `subscribeToSlot(slot, effect, edge)` | push the effect onto `slot.effects` and its `edge` (which of the effect's sources this slot is) onto `slot.effectEdges`, and hand back **the position**, which the effect remembers. **It takes a hold** through `holdSlot`, so a subscribed slot is a held one and nothing can subscribe without holding. **Throws by name** on a released slot: a subscriber filed on one would never be woken | | `unsubscribeFromSlot(slot, at, effect)` | swap the tail of both arrays into `at`, tell the moved effect its new position at its edge (one write, no search), and **if that emptied the list, call the `protected onSlotLastUnsubscribed(slot)` hook**, then give the subscription's hold back through `unholdSlot`; hand back whether it unfiled. Unfiling by remembered position is why taking N subscribers off one identity is O(N) and not quadratic. **Throws by name** on a released slot | **`OIMSlotOwner`** is the ABSTRACT base class of the six doors of `IOIMSlotOwner`: `releaseSlotIfUnheld` is abstract, the other five are its own. Its constructor takes `(slotSubscriptionListener?: IOIMSlotSubscriptionListener)`, default `OIMNoSlotSubscriptionListener.INSTANCE`. Its protected hooks (not on `IOIMSlotOwner`): `onSlotFirstSubscribed(slot)` / `onSlotLastUnsubscribed(slot)` call that listener, and `protected onSlotUnheld(slot)` runs `releaseSlotIfUnheld(slot)`. Its `unsafeMutateSlot(slot, mutateSlot)` hands `mutateSlot` the slot as `TOIMEditable` with no guard at all (it exists so a library that adds its own release wheel can keep its own bit in `slot.slotFlags`; the engine owns bits `1`, `2`, `4`, `8`, `16` and `32`, so a library starts at `64`; it is on the owner so a subclass can hook every such mutation), and a `protected assertNotReleased` is what every refusing door above calls. `OIMSlotOwnerService` implements `releaseSlotIfUnheld`, asking its release policy and its content service, and overrides two protected hooks: `onSlotLastUnsubscribed` asks the release policy's `onSlotIdle(slot)` (on a slot that is not empty) and then the listener, and `onSlotUnheld` asks the policy's `onSlotUnheld(slot)` and then runs the base release. The clock is the slot's channel slot's. It hands its subscription listener to its column slot owner as the second argument of `createColumnSlotOwner(columnSlotOwnerOptions, slotSubscriptionListener)`, so a column slot's first and last subscriber reach the same listener as the column slot itself; the column slot owner does not forward them to the carrier slot's owner. A single's slot is owned the same way: its owner is its collection type's slot owner, and that release policy applies to it. ### The column owner **Columns are a module of every collection.** The column slots of a carrier slot live in `carrierSlot.columnSlotStore`, a field of the base `TOIMSlot`, so any slot can carry them — an entity slot, a bucket slot, a computed slot. `OIMColumnSlotOwner` is abstract, an `OIMSlotOwner` subclass, with two strategies: `OIMPushColumnSlotOwner` (plain column slots woken by marks on a write; entity and bucket collections, keyed and single) and `OIMPullColumnSlotOwner` (each column slot a computed slot over its carrier; computed collections, keyed and single). The factory hands the strategy's factory to the slot owner as `createColumnSlotOwner(columnSlotOwnerOptions, slotSubscriptionListener)`; the strategies are built the same way, `createOIMPushColumnSlotOwner(options, slotSubscriptionListener?)` / `createOIMPullColumnSlotOwner(options, slotSubscriptionListener?)` or `new OIMPushColumnSlotOwner(options, slotSubscriptionListener?)` / `new OIMPullColumnSlotOwner(options, slotSubscriptionListener?)`. Each collection type has its own column owner, and every column slot it mints names that owner as its `owner`. The owner holds the column slot store service and the declared column groups, both fixed at construction; the column slots live on their carrier. The collection exposes them only through its column doors: `getColumnSlot(slot, columnName)`, `holdColumnSlot(slot, columnName)`, `unholdColumnSlot(columnSlot)`, `getColumnGroupSlot(slot, group)`, `holdColumnGroupSlot(slot, group)` (on a single the same doors, with the slot `getSingleSlot(storeSlot)` hands back; the computed ones take a computed slot and return a `TOIMComputedColumnSlot`), and `getAnyColumnSlot(slot)` / `holdAnyColumnSlot(slot)`. A column slot is released the moment its last effect is disposed and nothing holds it: disposing the effect gives its hold back through the column owner, which then runs its own `releaseSlotIfUnheld`, which stops on `holdCount > 0` or a non-empty `effects`, takes the column out of the carrier slot's column store — dropping that store entirely when it empties — sets the RELEASED flag of `columnSlot`, and then runs `carrierSlot.owner.releaseSlotIfUnheld(carrierSlot)`, because a carrier kept alive only by a watched column is one nothing watches any more. This guard is the one place a store lookup survives — it compares `columnSlotStoreService.get(columnSlotStore, columnSlot.key)` against the column slot — because a column is filed on its carrier slot, not in the store slot that the `owner` check covers. `OIMSlotOwnerService`'s release guard refuses while `slot.columnSlotStore` stands, so a slot with any live column slot is never released. --- ## Ordered lists ### Disposers The disposers this package hands back are the unsubscribes `OIMChannelService.INSTANCE.subscribeAfterEachFrame` and its siblings return, and the one `effectService.subscribeEffect(db, body, sourceSlots?, sourceComputeds?, sourceTrackingComputeds?)` returns. An effect from `createEffect` has none, so the caller writes `() => effectService.disposeEffect(effect)`. A hold is given back through its owner, not through a disposer. ```ts const effect = effectService.createEffect(db, () => { paint(slot.entity); }, [slot]); const disposers: TOIMDisposer[] = []; disposers.push(() => { effectService.disposeEffect(effect); }); disposers.push(() => { slot.unholdSlot(); }); for (let i = disposers.length - 1; i >= 0; i--) disposers[i](); ``` ### `getOIMOrderedListCommands` ```ts signature getOIMOrderedListCommands( prev: readonly TOIMEntitySlot[], next: readonly TOIMEntitySlot[], maxCommandsPerSlot?: number, // commands per slot of `next`; left out, it NEVER resets ): TOIMOrderedListCommand[] type TOIMOrderedListCommand = | { type: 'insert'; index: number; slot: TOIMEntitySlot } | { type: 'remove'; index: number } | { type: 'move'; from: number; to: number } | { type: 'reset'; slots: readonly TOIMEntitySlot[] }; ``` A free function, not a method on `OIMChannelService`: a class's methods cannot be dropped one at a time by a bundler. `prev` MUST BE A SNAPSHOT TAKEN WHERE YOU RENDERED. Every member read on a bucket content service hands back the LIVE list — declared `Iterable`, not an array, so `Array.from(bucketSlot.getBucketMemberSlots())` is required and is the copy. A `prev` kept live is the same array as `next` on the following frame: the diff is empty, no reorder is ever drawn, and nothing throws. The other safe `prev` is `createOIMBucketMemoComputedService`'s value — a fresh array on every write that changed the list, the same array while it did not. A LIST MAY NAME ONE SLOT TWICE, and then it holds that slot twice. `OIMPositionalArrayBucketContentService` records every mention, so an ordered bucket's list is exactly such a list. The mentions of one identity are matched in the order they appear, and the script reproduces `next` mention for mention. The minimal move count (`common − LIS`) is claimed for lists whose identities are distinct: where the two lists name one identity a different number of times, which mentions are matched decides how long the common subsequence can be, and matching them in order does not always leave the longest. --- ## Types ```ts signature type TOIMStoreKey = string | number; type TOIMDisposer = () => void; type TOIMEffectBody = () => (() => void) | void; // a returned function is the undo type TOIMSourceTrackingEffectBody = () => (() => void) | void; type TOIMSameValueGuard = (prev: TValue, next: TValue) => boolean; type TOIMChannelScheduler = (flush: () => void) => void; type TOIMSortColumn = { columnName: TOIMSortableColumnName; direction: 'asc' | 'desc' }; type TOIMSortableColumnName = // a column whose values are string | number | bigint { [TColumn in keyof TEntity]-?: NonNullable extends string | number | bigint ? TColumn : never }[keyof TEntity] & string; // EVERY property is `readonly`. A slot is written through its owner and its // service, never by assigning to it; `TOIMEditable` is how the engine // itself drops that guard where it is the one mutator. type TOIMSlot = { readonly effects: TOIMEffect[] | undefined; readonly effectEdges: number[] | undefined; // beside each effect, which of its sources this slot is readonly changedAtRevision: number; readonly changedAtEpoch: number; readonly holdCount: number; readonly releaseDueAfterWriteMs: number; // -1 until a write stamps it readonly releaseDueAfterIdleMs: number; // -1 until idleness stamps it readonly releaseDueAfterUnholdMs: number; // -1 until the last unhold stamps it readonly slotFlags: number; // OIM_SLOT_FLAG_EMPTY = 1, OIM_SLOT_FLAG_RELEASED = 2; bits up to 32 are the engine's readonly columnSlotStore: unknown; // the column slots this slot carries; undefined while none readonly storeSlot: TOIMStoreSlot; // the store slot it belongs to; a column slot's is its carrier's readonly owner: IOIMSlotOwner; // never undefined, never cleared data: unknown[] | undefined; // the consumer's cache, writable, on every slot; the core never touches it }; // A store slot is NOT a slot: nothing holds, subscribes or wakes it. It is the state of one // collection instance — its store, its channel slot, its listeners and column state — and every // service that touches it is stateless. Only the fields a consumer reads are shown. type TOIMStoreSlot = { readonly store: TStore; readonly channelSlot: TOIMChannelSlot; readonly contentChangeListeners: IOIMSlotContentChangeListener[] | undefined; readonly contentChangeListenerReadColumns: TOIMSlotContentChangeListenerReadColumns[] | undefined; readonly slotContentChangeListenerReadColumns: TOIMSlotContentChangeListenerReadColumns | undefined; // what this store slot's own listener on its source reads (an index, the collection list) readonly indexKeysPositions: TOIMIndexKeysPositions | undefined; readonly sourceStoreSlot: TOIMStoreSlot | undefined; // an index store slot's source readonly isDisposed: boolean; // an index store slot after disposeIndexStoreSlot readonly slotService: TSlotService; // the service that created the store slot readonly batchDepth: number; // openBatch / closeBatch nesting // … column listener counts, batch queues, bucket write queues: the services' own }; type TOIMSingleSlotStore = { slot: TSlot | undefined }; type TOIMSingleSlotStoreSlot = TOIMStoreSlot, TSlot, TPatch>; type TOIMIndexStoreSlot = TOIMStoreSlot & { readonly sourceStoreSlot: TOIMStoreSlot; readonly indexKeysPosition: number; readonly contentChangeListener: IOIMSlotContentChangeListener; readonly requestedKeys: readonly TKey[] | undefined; readonly isDisposed: boolean; }; type TOIMComputedStoreSlot< TStore = unknown, TValue = unknown, TComputedSlot extends TOIMComputedContentSlot = TOIMComputedContentSlot, TSlotService = unknown, > = TOIMStoreSlot & { readonly derive: ((computedSlot: TComputedSlot) => TValue) | undefined; readonly createSources: ((computedSlot: TComputedSlot) => Partial) | undefined; }; type TOIMEditable = { -readonly [K in keyof TSlot]: TSlot[K] }; type TOIMKeyedSlot = NonNullable> = TOIMSlot & { readonly key: TKey }; type TOIMIndexableSlot = NonNullable> = TOIMKeyedSlot & { readonly indexKeys: unknown[] | undefined }; type TOIMEntitySlot = NonNullable, TColumnName extends TOIMColumnName = TOIMColumnName> = TOIMIndexableSlot & { readonly entity: TEntity | undefined; }; // `data` (on TOIMSlot, so on every slot) belongs to the consumer: the core never reads or writes it, and clearing, // removing or releasing the slot does not reset it. Each index keeps its // last key for the entity slot in `indexKeys`, through the index's `IOIMIndexKeysService`. type TOIMColumnSlot = TOIMSlot & { readonly carrierSlot: TOIMSlot; // the entity slot or bucket slot it hangs off readonly key: string; readonly value: unknown; // what the column stands for; see "columnSlot.value" holdSlot(): void; unholdSlot(): void; }; type TOIMComputedColumnSlot = TOIMComputedContentSlot & TOIMKeyedSlot & { readonly carrierSlot: TOIMComputedContentSlot; }; // a computed's column doors return it; a plain computed's goes in createEffect's second list, a source-tracking one's in the fifth type TOIMBucketContentSlot = TOIMSlot & { readonly owner: IOIMSlotOwner; readonly storeSlot: TOIMStoreSlot>; readonly commands: readonly TOIMOrderedListCommand[] | undefined; // emptied when the flush has ended readonly isWholeListRecorded: boolean; // reset to false with it readonly commandsStartedAtRevision: number; // the clock the script started at readonly commandsStartedAtEpoch: number; getBucketMemberSlots(): Iterable; // the reads file the bucket into a tracked body getBucketMemberSlotCount(): number; hasBucketMemberSlot(bucketMemberSlot: TBucketMemberSlot): boolean; getBucketMemberSlotsMissingFrom(bucketMemberSlots: readonly TBucketMemberSlot[]): TBucketMemberSlot[]; writeSlotContent(bucketMemberSlots: readonly TBucketMemberSlot[]): boolean; addBucketMemberSlot(bucketMemberSlot: TBucketMemberSlot): void; removeBucketMemberSlot(bucketMemberSlot: TBucketMemberSlot): void; addBucketMemberSlots(bucketMemberSlots: readonly TBucketMemberSlot[]): void; removeBucketMemberSlots(bucketMemberSlots: readonly TBucketMemberSlot[]): void; clearSlotContent(): void; markContentChanged(): void; holdSlot(): void; unholdSlot(): void; }; type TOIMBucketSlot = NonNullable> = TOIMBucketContentSlot & TOIMIndexableSlot; // a keyed bucket slot; a single bucket is the content slot alone // `holdSlotByKey(storeSlot, key)` hands back the slot itself; give the hold back with `slot.unholdSlot()`. type TOIMBucketSlotsSetStore = Set; type TOIMBucketSlotsArrayStore = { bucketMemberSlots: TBucketMemberSlot[]; uniqueBucketMemberSlots: Set | undefined; // kept by OIMBucketUniqueMemberSlotsArrayService sortedCount: number; }; type TOIMColumnName = [TEntity] extends [never] ? never : object extends TEntity ? string : keyof TEntity & string; type TOIMComputedDerivation = TOIMComputedSources & { // what a computed slot and a TOIMEffect share ranAtRevision: number; ranAtEpoch: number; }; type TOIMTimer = (run: () => void, inMs: number) => TOIMDisposer; ``` **`TOIMEditable` strips `readonly` from every property.** It is exported because the rule "data has one mutator" is enforced by the slot types being readonly everywhere else: a class that IS the sole mutator of a slot's property casts through this type at the one place it writes, and every other reader is stopped by the compiler. `IOIMSlotStamp.stamp` takes one, which is what lets a stamp write `releaseDueAfterWriteMs` and nothing else write it. **Do not reach for this to work around a compile error** — if you need it and you do not own the property, the mutation belongs on whoever does. Comparison helpers — one per shape of address, plus the value rule. Use the one that matches what you are comparing; they are not interchangeable. | Helper | Compares | Rule | |---|---|---| | `isOIMSameValueZero(prev, next)` | a stored value, or one scalar address | SameValueZero | | `isOIMSameSlotSequence(prev, next)` | `readonly TOIMSlot[]` — a chain of identities | positional, by reference | | `isOIMSameKeySequence(keys, otherKeys)` | `readonly TKey[]` — a list of keys or a chain of values | positional, SameValueZero per key | --- ## Full export list **274 names, every export of `packages/core/src/index.ts`, grouped by topic.** *Deprecated, removed in 5.0* — `OIMSlotContentEntityService` → `OIMEntityContentService`, `createOIMSlotContentEntityService` → `createOIMEntityContentService`, `TOIMSlotContentEntityServiceOptions` → `TOIMEntityContentServiceOptions`, `OIMSlotContentBucketService` → `OIMBucketContentService`, `TOIMSlotContentBucketServiceOptions` → `TOIMBucketContentServiceOptions`, `OIMSlotContentSetBucketService` → `OIMSetBucketContentService`, `OIMSlotContentArrayBucketService` → `OIMArrayBucketContentService`, `TOIMSlotContentArrayBucketServiceOptions` → `TOIMArrayBucketContentServiceOptions`, `OIMSlotContentPositionalArrayBucketService` → `OIMPositionalArrayBucketContentService`, `OIMSlotContentSortedArrayBucketService` → `OIMSortedArrayBucketContentService`, `TOIMSlotContentSortedArrayBucketServiceOptions` → `TOIMSortedArrayBucketContentServiceOptions`, `OIMSlotContentComputedService` → `OIMComputedContentService`, `TOIMSlotContentComputedServiceOptions` → `TOIMComputedContentServiceOptions`, `OIMSlotContentSourceTrackingComputedService` → `OIMSourceTrackingComputedContentService`. *Store aggregates* — `OIMSlotCollectionStoreAggregate` · `OIMWritableSlotCollectionStoreAggregate` · `OIMSingleSlotStoreAggregate` · `OIMWritableSingleSlotStoreAggregate` · `OIMSlotCollectionIndexStoreAggregate` · `createOIMSlotCollectionStoreAggregate` · `createOIMSingleSlotStoreAggregate` *Channel and database slots* — `OIMChannelService` · `TOIMChannelSlot` · `TOIMChannelSlotOptions` · `createOIMChannelSlot` · `IOIMChannelMap` · `TOIMDBOptions` · `OIMFlushSchedulerService` · `TOIMFlushSchedulerSlot` · `IOIMFlushSchedulerListener` *Collector services and slots* — `OIMUnusedSlotCollectorService` · `TOIMUnusedSlotCollectorSlot` · `createOIMUnusedSlotCollectorSlot` · `TOIMCollectorSlot` · `TOIMCollectorSlotOptions` · `createOIMCollectorSlot` · `OIMSlotWheel` · `TOIMSlotWheelOptions` · `OIMSlotReleaseWheel` · `TOIMSlotReleaseWheelOptions` · `mintOIMAfterWriteSlotReleaseWheel` · `mintOIMAfterIdleSlotReleaseWheel` · `mintOIMAfterUnholdSlotReleaseWheel` · `OIMSlotRefetchWheel` · `TOIMSlotRefetchWheelOptions` · `IOIMSlotRefetchListener` · `IOIMSlotReleaseListener` *Slot services* — `OIMSlotCollectionService` · `OIMWritableSlotCollectionService` · `TOIMSlotCollectionServiceOptions` · `TOIMSlotCollectionServiceFactoryOptions` · `createOIMSlotCollectionService` · `OIMSingleSlotService` · `OIMWritableSingleSlotService` · `TOIMSingleSlotServiceOptions` · `createOIMSingleSlotService` · `OIMColumnSlotService` (the column doors, `service.columnSlotService`) · `OIMSlotOwnerService` (**type only**) · `TOIMSlotOwnerServiceOptions` · `IOIMSlotContentService` · `IOIMSlotContentWriter` · `IOIMKeyedSlotCreator` · `IOIMSingleSlotCreator` · `IOIMSlotFilingService` · `TOIMSlotContentServiceKey` · `TOIMSlotContentServiceSlot` · `TOIMSlotContentServiceSingleSlot` · `TOIMSlotContentServiceContent` · `TOIMSlotContentServicePatch` · `OIMSlotContentChangeListenerService` *Content services* — `OIMEntityContentService` · `TOIMEntityContentServiceOptions` · `createOIMEntityContentService` · `createOIMEntitySlotCollectionStoreAggregate` · `OIMEntitySlotCollectionStoreAggregate` · `OIMSlotCollectionBucketService` · `TOIMSlotCollectionStoreSlot` · `TOIMCollectionBucketSlot` · `OIMCollectionSetBucketContentService` · `getOIMBucketMemberSlotEntities` · `TOIMEntitySlotOwnerService` · `TOIMEntityContentSlot` · `OIMEntitySlot` · `OIMSlot` · `OIMBucketContentService` · `OIMArrayBucketContentService` · `OIMPositionalArrayBucketContentService` · `OIMSetBucketContentService` · `OIMSortedArrayBucketContentService` · `TOIMBucketContentServiceOptions` · `TOIMArrayBucketContentServiceOptions` · `TOIMSortedArrayBucketContentServiceOptions` · `TOIMBucketSlotOwnerService` · `TOIMBucketContentSlot` · `OIMComputedContentService` (**type only**) · `TOIMComputedContentServiceOptions` · `OIMExplicitSourceComputedContentService` · `TOIMExplicitSourceComputedContentServiceOptions` · `TOIMComputedContentSlot` · `TOIMComputedCarrierSlot` *Index and computed store slots* — `createOIMSlotCollectionIndexService` · `createOIMSlotCollectionIndexStoreAggregate` · `TOIMSlotCollectionIndexServiceFactoryOptions` · `TOIMSlotCollectionIndexServiceStoreSlot` · `TOIMSortedComputedSlot` · `TOIMBucketMemoComputedSlot` *Runtime* — `TOIMChannelFrame` · `TOIMChannelClock` · `TOIMChannelScheduler` · `TOIMDisposer` · `OIM_NOOP_DISPOSER` · `IOIMErrorPolicy` · `OIMLogAndContinueErrorPolicy` · `TOIMLogAndContinueErrorPolicyOptions` · `OIMThrowAtOnceErrorPolicy` · `OIMChannelQueue` (**type only**) · `isOIMAnySlotChangedAfter` `isOIMAnySlotChangedAfter(slots, revision, epoch): boolean` answers whether any of the slots was written after that clock reading — `channelSlot.clock` read earlier. *Derivations* — `OIMEffectService` · `IOIMEffectService` · `TOIMEffect` (**type only** — `OIMEffectService.createEffect` is the constructor) · `TOIMEffectBody` · `TOIMSourceTrackingEffectBody` · `OIMSourceTracker` · `IOIMSourceTracker` · `TOIMComputedSlot` · `TOIMComputedSources` · `TOIMComputedValueReleaser` · `OIMSourceTrackingComputedService` · `OIMSingleSourceTrackingComputedService` · `createOIMSourceTrackingComputedService` · `createOIMSingleSourceTrackingComputedService` · `TOIMSourceTrackingComputedSlot` · `TOIMSourceTrackingComputedContentSlot` · `TOIMSourceTrackingComputedDerive` · `OIMSourceTrackingComputedContentService` (**type only**) · `TOIMSourceTrackingComputedDerivationOptions` · `TOIMComputedServiceFactoryOptions` · `OIMComputedValueService` · `IOIMComputedValueService` · `TOIMComputedValueServiceOptions` · `refreshOIMSourceComputeds` · `TOIMComputedDerivation` `refreshOIMSourceComputeds(sourceComputeds)` brings every computed in the list current. Code that reads computeds outside an effect calls it on its `sourceComputeds` before `derive`, so the derive never reads a stale computed. `OIMSourceTracker` is also the door for reading in one place and subscribing in another, which is what `@oimdb/react` does: - `sourceTracker.runSourceTracking(read)` runs `read` with the tracker active and returns what `read` returned; every tracked read inside it (`slot.entity`, `slot.getEntity(group)`, `computed.value`, a bucket's members) is recorded, and nothing is subscribed. The tracker diffs each run against what it last committed: `isTrackedSourcesChanged()` is `true` when this run read other sources, and `commitTrackedSources()` makes them the committed ones. - `OIMEffectService.INSTANCE.createEffectOverSourceTracker(db, new OIMSourceTracker(), body)` makes an effect whose body reads nothing and tracks nothing. - `OIMEffectService.INSTANCE.subscribeEffectToTrackedSources(effect, sourceTracker): boolean` subscribes that effect to what `sourceTracker` recorded, keeping each column group, and gives back the sources it no longer names. It returns `true` when the sources moved. It throws for an effect not made by `createEffectOverSourceTracker`. So a read runs once: where it happened, the effect only learns which sources to wake on. *Slots and their owners* — `TOIMSlot` · `TOIMStoreSlot` · `TOIMSingleSlotStoreSlot` ·`IOIMStoreSlotListener` · `OIMNoStoreSlotListener` · `IOIMSlotSubscriptionListener` · `OIMNoSlotSubscriptionListener` ·`isOIMSlotEmpty` · `isOIMSlotReleased` · `TOIMEditable` · `TOIMKeyedSlot` · `TOIMIndexableSlot` · `TOIMEntitySlot` · `TOIMColumnSlot` · `TOIMComputedColumnSlot` · `TOIMColumnGroup` · `createOIMColumnGroup` · `OIMColumnSlotOwner` · `OIMPushColumnSlotOwner` · `OIMPullColumnSlotOwner` · `TOIMColumnSlotOwnerOptions` · `TOIMBucketSlot` · `TOIMSameValueGuard` · `OIMSlotOwner` · `IOIMSlotOwner` · `IOIMSlotEmptinessPolicy` · `IOIMSlotStamp` · `holdOIMSlots` · `unholdOIMSlotsIfAlive` · `IOIMSlotContentChangeListener` · `TOIMSlotContentChangeListenerReadColumns` · `isOIMAnyAddedColumnRead` · `markOIMBucketColumnsChanged` `isOIMSlotEmpty(slot): boolean` reads the EMPTY bit of `slot.slotFlags`. `isOIMSlotReleased(slot): boolean` reads its RELEASED bit. *Release policies* — `IOIMSlotReleasePolicy` · `OIMSlotAfterWriteReleasePolicy` · `TOIMSlotAfterWriteReleasePolicyOptions` · `IOIMSlotReleaseDueFramePolicy` · `OIMSlotReleaseAutoDueFramePolicy` · `OIMSlotReleaseManualDueFramePolicy` · `OIMSlotAfterIdleReleasePolicy` · `TOIMSlotAfterIdleReleasePolicyOptions` · `OIMSlotAfterUnholdReleasePolicy` · `TOIMSlotAfterUnholdReleasePolicyOptions` · `OIMSlotAtUnholdReleasePolicy` · `OIMSlotAtEmptyReleasePolicy` · `OIMSlotNeverReleasePolicy` · `OIMSlotEarliestReleasePolicy` · `TOIMTimer` · `getOIMSliceOfMs` · `OIM_SLICE_LENGTH_MS` *Entity writers* — `IOIMEntityWriter` · `createOIMInPlaceEntityWriter` · `createOIMReplacingEntityWriter` · `TOIMEntityWriterOptions` · `TOIMEntityInserter` · `insertOIMEntityWithCopy` · `insertOIMEntityWithoutCopy` · `insertOIMEntityWithSanitizedCopy` · `patchOIMEntityColumns` · `patchOIMEntityColumn` · `guardOIMEntityColumnsPatch` · `guardOIMEntityColumnPatch` · `putOIMEntityColumns` · `guardOIMEntityColumnsPut` · `TOIMColumnName` · `TOIMEntityColumnValue` *Buckets* — `OIMBucketCommands` · `OIMBucketCommandsCursor` · `TOIMBucketCommandsCursorOptions` · `TOIMBucketCommandsOptions` · `IOIMBucketCommands` · `IOIMBucketMemberSlotsArrayService` · `OIMBucketMemberSlotsArrayService` · `OIMBucketUniqueMemberSlotsArrayService` · `TOIMBucketSlotsSetStore` · `TOIMBucketSlotsArrayStore` · `OIM_NOTHING_WAS_INSERTED` · `OIM_NOTHING_WAS_REMOVED` · `OIM_FROZEN_EMPTY_SLOTS` · `OIM_REMOVED_WITHOUT_A_POSITION` *Index services* — `OIMSlotCollectionIndexService` · `OIMSlotCollectionSortedArrayIndexService` · `TOIMSlotCollectionIndexServiceOptions` · `TOIMIndexStoreSlot` · `createOIMSlotCollectionSortedArrayIndexService` · `TOIMIndexKeyOptions` · `TOIMIndexKey` · `IOIMIndexKeysService` · `TOIMIndexKeysPositions` · `OIMIndexKeysService` · `OIMAppendingIndexKeysService` · `OIMReclaimingIndexKeysService` *Computed services* — `OIMComputedService` · `TOIMComputedServiceOptions` · `createOIMComputedService` · `TOIMComputedStoreSlot` · `OIMSortedComputedService` · `TOIMSortedComputedServiceOptions` · `createOIMSortedComputedService` · `createOIMSortedCollectionSingleSlotStoreAggregate` · `OIMBucketMemoComputedService` · `TOIMBucketMemoComputedServiceOptions` · `createOIMBucketMemoComputedService` · `OIMSingleComputedService` · `createOIMSingleComputedService` · `TOIMComputedDerivationOptions` · `TOIMSortColumn` · `TOIMSortableColumnName` · `createOIMColumnsComparator` *Stores and keys* — `TOIMStoreKey` · `IOIMSlotStoreService` · `OIMSlotMapStoreService` · `OIMSlotTreeStoreService` · `OIMSingleSlotStoreService` · `TOIMSingleSlotStore` · `TOIMDefaultSlotStore` · `TOIMSlotStoreTree` · `IOIMKeyTreeWalk` · `TOIMCompositeKeyNode` · `OIMKeyTreeWalk` · `OIMCompositeKeyTreeWalk` · `OIMScalarKeyTreeWalk` *Assemblies* — `OIMDB` · `OIMDefaults` · `TOIMDefaultsOptions` · `OIMDefaultValue` · `TOIMFactoryOptions` *Comparison and diffing* — `isOIMSameValueZero` · `isOIMSameSlotSequence` · `isOIMSameKeySequence` · `getOIMOrderedListCommands` · `TOIMOrderedListCommand` *Shared defaults* — `OIMScalarKeyTreeWalk.INSTANCE` and `OIMCompositeKeyTreeWalk.INSTANCE`. **Nothing else is exported.** If a symbol is not on this list, it does not exist. --- ## Known defects ### A scalar in a key of the composite key tree walk throws `OIMSlotTreeStoreService` built with `OIMCompositeKeyTreeWalk.INSTANCE` keys on `readonly TOIMEntitySlot[]`, so a string or a number in the key throws a TypeError past a cast, setting `holdCount` on a string. The store for a tuple of scalars is `OIMSlotTreeStoreService` built with `OIMScalarKeyTreeWalk.INSTANCE` — see **Key stores** above. The fix is the other walk, never a cast. ### `TOIMEffect` is a type-only export `effectService.createEffect(...)` and `effectService.createAndRunEffect(...)` are the whole of legitimate construction. An object literal typed `TOIMEffect` subscribes to nothing and schedules nothing: when one of its sources already moved in the open batch, a later write to that source is swallowed by the coalescing guard and the effect silently sits out the frame it is owed. Scheduling it is what `createEffect` does after constructing it. ### Mixing `import` and `require` of `@oimdb/core` throws at the second load Every `@oimdb` package ships both formats — `dist/index.js` for `import`, `dist/index.cjs` for `require` (with `dist/index.d.cts` under the `require` condition so a CommonJS consumer's declarations match its runtime), both named in the `exports` map. A runtime loads a package once per format, so a process that reaches the core both ways would hold two copies of every class and every module-level value — two sets of built-in defaults and two `OIMDefaults` classes, so services built by the two copies share nothing. So `src/index.ts` registers its copy under `Symbol.for('@oimdb/core')` on `globalThis`, and the second copy to load throws `@oimdb/core is loaded twice in this process`. The same throw fires for two installed copies of the package. `@oimdb/react` loaded twice fails loudly instead: `useOIMSelector` and `useOIMDB` throw `useOIMDB: no above this component.` with the provider plainly above it, because a React context's identity is its lookup key. Do not generate code that reaches `@oimdb/core` — or any package that passes core objects around — through both spellings in one process. Pick one. --- ## Other packages `@oimdb/react`, `@oimdb/persist` (with its five backends) and `@oimdb/browser` build on the current core — persist and browser have sections of their own below. Every remaining package imports only names the core exports. Read a package's own source before generating code against it. `@oimdb/react` — `` carries the `OIMDB` and nothing else; `useOIMDB()` returns it, and `useOIMDB.withTypes()` is the same hook typed with the app's schemas. The one read hook is `useOIMSelector(select: (db) => TValue, deps?): TValue`, and `useOIMSelector.withTypes()` types its `db`: - `select` runs during render with the provider's database, and everything it reads with tracking (`slot.entity`, `slot.getEntity(group)`, `columnSlot.value`, `computed.value`, `getBucketMemberSlots()` and `getBucketMemberSlotCount()`, `getEntities()`, `getEntityCount()`) becomes a source. `peekSlotByKey`, `hasSlotContentByKey`, `getSlots` and `getSlotCount` do not track. - Without `deps`, `select` runs on every render and a key from props is closure. The render tracks into one `OIMSourceTracker` the component keeps; `isTrackedSourcesChanged()` says whether it read other sources than the last committed render, and only then does the commit run (`subscribeEffectToTrackedSources`). When the last tracked render is not the one being committed (React threw one away), the commit runs the committed `select` again and asks one more render. With `deps`, `select` runs only when a dep changes or a source is written (a slot the committed render read stamped since its last run counts, so a render before the flush still shows the write); `[]` is the static case, and a `select` defined outside the component without `deps` is memoised on its identity. A flush only bumps a version and tells React, and `select` runs in that render. Results are never compared, because an in-place write keeps the entity's reference. - Mounting, and a render that read other slots than the last committed one, cost one render. The render token keeps the clock reading (`revision`, `epoch`, `unheldSlotWriteCount`) taken before `select`; after the subscription or that commit, one more render is asked only if a slot it read was stamped after it, `unheldSlotWriteCount` moved, or a released slot was recovered. The commit runs in an insertion effect (before any layout effect of the commit) and asks its render from a layout effect once subscribed. On a released slot or computed the commit runs `select` again into its own tracker and subscribes in the same step, so `getSlotByKey` inside `select` mints a fresh slot held before a flush can release it, and one render shows it. If that run still reads a newly released slot (taken outside `select`) or throws, the render's sources minus the released ones are kept (a released computed gives way to its live roots, live computeds stay) and one render is asked; a second failed retry in a row asks nothing, so a flush during every render settles. A re-render over the same slots costs nothing more. `deps` are passed always or never, with the same length. - The shorthands pass their aggregate and key as `deps`. - An error in `select` reaches the error boundary. A slot filed on another `OIMDB` than the provider's throws, naming `useOIMSelector`. - A list selects member keys (`Array.from(bucket.getBucketMemberSlots(), member => member.key)`), and each row selects its own entity by key. One field of a wide entity is `slot.getEntity(createOIMColumnGroup(['title']))`, with the group made once at module scope. A component-owned computed is `useMemo(() => service.createStoreSlot(db, …), deps)`, read through `.value` in the selector. Writes need no hook. - StrictMode in development subscribes twice, so a slot subscription listener hears `onSlotFirstSubscribed` twice. - Shorthands, each one `useOIMSelector` call over the aggregate it is given: - `useOIMEntityByKey(slotCollectionStoreAggregate, key)`, which is `getSlotByKey(key).entity`; - `useOIMEntities(entitySlotCollectionStoreAggregate)`, which is `getEntities()`; - `useOIMEntitiesByKey(slotCollectionIndexStoreAggregate, key)`, which is `getEntitiesByKey(key)`; - `useOIMBucketMemberKeysByKey(slotCollectionIndexStoreAggregate, key)`, the member keys; - `useOIMComputedValueByKey(slotCollectionStoreAggregate, key)`, which is `getSlotByKey(key).value`; - `useOIMSingleEntity(singleSlotStoreAggregate)`, which is `getSingleSlot().entity`; - `useOIMSingleComputedValue(singleSlotStoreAggregate)`, which is `getSingleSlot().value`. Each parameter is typed by the one method the hook calls. See `packages/react/README.md`. `@oimdb/exodra` — the Exodra plugin; it only reads. `new OIMExodraPlugin({ db })` claims a `slot.data` cell (`db.claimSlotDataCell()`) and adds a release listener (`dispose()` removes it); compose it into the backend as `{ exodraPlugin: () => plugin }`. `resolveOIMExodraPlugin(c)` = `c.inject(OIM_EXODRA_PLUGIN_CONTEXT_TOKEN) ?? c.exodraPlugin`, throws when neither; a second db is a second plugin built once and provided above a subtree. `withOIMEffects(machine, effect => { effect((c, db) => …); })`: each body is a tracked `db.createEffect` bound to the node. `withOIMBucketChildren(machine, { childrenPort, memberMachine, selectBucketSlot: (params) => bucketSlot })`: an Exodra `withExoParamsEffects` effect keyed by `selectBucketSlot(params)` that applies `OIMBucketCommandsCursor` commands to `c.portChildList(childrenPort)` (give the bucket a `bucketCommands` recorder, or every change is a `reset`); a `wireExoNode` with another bucket restarts it, so whoever wires the node (e.g. a parent's tracked effect) picks the bucket; a `reset` detaches all and reattaches each member's own node; a node that leaves is parked in its slot's claimed cell (its own effects stopped), kept across bucket switches, and destroyed when the slot is released or the node's effects stop. Needs `@exodra/core`/`@exodra/dom` ^0.4.1. See `packages/exodra/README.md`. What each imports from `@oimdb/core`, read out of `src/`. The source moves — re-read the imports rather than trusting this table. | Package | Imports from the core | Imports a name the core does not export? | |---|---|---| | `@oimdb/persist` | `IOIMChannelMap`, `IOIMSlotContentChangeListener`, `IOIMEntityWriter`, `OIMChannelService`, `OIMPushColumnSlotOwner`, `OIMSlotContentChangeListenerService`, `OIMEffectService`, `OIMSingleSlotService`, `OIMSlotCollectionService`, `OIMBucketContentService`, `OIMEntityContentService`, `TOIMBucketSlot`, `TOIMChannelClock`, `TOIMChannelSlot`, `TOIMColumnSlot`, `TOIMDefaultSlotStore`, `TOIMDisposer`, `TOIMEffect`, `TOIMEntitySlot`, `TOIMSingleSlotStore`, `TOIMSingleSlotStoreSlot`, `TOIMSlot`, `TOIMStoreKey`, `TOIMStoreSlot`, `holdOIMSlots`, `isOIMAnySlotChangedAfter`, `isOIMSlotReleased`, `isOIMSameValueZero`, `unholdOIMSlotsIfAlive` | no | | `@oimdb/redux-adapter` | `IOIMChannelMap`, `IOIMSlotContentChangeListener`, `OIMChannelService`, `OIMPushColumnSlotOwner`, `OIMSlotContentChangeListenerService`, `OIMEffectService`, `OIMSlotCollectionService`, `OIMBucketContentService`, `OIMEntityContentService`, `TOIMBucketSlot`, `TOIMColumnSlot`, `TOIMDefaultSlotStore`, `TOIMDisposer`, `TOIMEffect`, `TOIMColumnName`, `TOIMEntitySlot`, `TOIMStoreKey`, `TOIMStoreSlot` | no | | `@oimdb/react` | `IOIMChannelMap`, `OIMComputedService`, `OIMDB`, `OIMEffectService`, `OIMSingleSlotService`, `OIMSlotCollectionService`, `OIMBucketContentService`, `OIM_FROZEN_EMPTY_SLOTS`, `TOIMBucketSlot`, `TOIMColumnSlot`, `TOIMComputedSlot`, `TOIMComputedSources`, `TOIMComputedStoreSlot`, `TOIMDisposer`, `TOIMColumnName`, `TOIMEntityColumnValue`, `TOIMEntitySlot`, `TOIMIndexableSlot`, `TOIMKeyedSlot`, `TOIMSingleSlotStore`, `TOIMSlot`, `TOIMStoreKey`, `TOIMStoreSlot`, `holdOIMSlots`, `refreshOIMSourceComputeds`, `isOIMSameKeySequence`, `unholdOIMSlotsIfAlive` | no | | `@oimdb/devtools` | `IOIMChannelMap`, `IOIMStoreSlotListener`, `OIMChannelService`, `OIMComputedService`, `OIMDefaults`, `OIMSlotCollectionService`, `TOIMBucketSlot`, `TOIMComputedStoreSlot`, `TOIMDefaultSlotStore`, `TOIMDisposer`, `TOIMEntitySlot`, `TOIMKeyedSlot`, `TOIMStoreKey`, `TOIMStoreSlot` | no | | `@oimdb/browser` | `IOIMSlotSubscriptionListener`, `OIMChannelService`, `OIMDefaults`, `OIMSingleSlotService`, `OIMEntityContentService`, `TOIMDisposer`, `TOIMEntityContentSlot`, `TOIMSlot`, `createOIMSingleSlotService`, `createOIMEntityContentService`, `isOIMSlotReleased` | no | | `@oimdb/exodra` | `IOIMSlotReleaseListener`, `OIMBucketCommandsCursor`, `OIMDB`, `TOIMBucketContentSlot`, `TOIMBucketSlotsArrayStore`, `TOIMDisposer`, `TOIMOrderedListCommand`, `TOIMSlot` | no | | `@oimdb/async` | — | deprecated stub, `export {}` | | `@oimdb/snapshot-manager` | — | empty stub | Every package in the table has a `type-check` script (`tsc --noEmit`) that CI runs on each commit, and `@oimdb/core`, `@oimdb/persist`, `@oimdb/react`, and `@oimdb/redux-adapter` pass it. Their documentation pages name only shipped exports, but the source is still the final word on a signature. ## `@oimdb/persist` The persistence engine for `@oimdb/core` and its five backend packages. The engine names the parts and wires them; a backend package supplies the storage. Every constructor in the family takes ONE options object. | package | exports | |---|---| | `@oimdb/persist` | the engine, plus the key-value backend `OIMPersistKeyValueBackend` and its strategies; error types `TOIMPersistErrorHandler`, `TOIMPersistErrorContext`, `TOIMPersistOperation` and `TOIMPersistErrorReport` (`{ error, persistErrorContext }`, one failure as `onPersistError` receives it or as it lands in the `AggregateError`) | | `@oimdb/persist-memory` | `OIMPersistMemoryBackend`, `OIMPersistMemoryWriteBatch`, `OIMPersistMemoryRecordsService`, `OIMPersistMemorySnapshotService`, `TOIMPersistMemoryServiceOptions` | | `@oimdb/persist-json` | `OIMPersistJsonMemoryBackend`, `TOIMPersistJsonMemoryBackendOptions`, `TOIMPersistJsonDump`; depends on `@oimdb/persist-memory` | | `@oimdb/persist-idb` | `OIMPersistIndexedDbBackend`, `OIMPersistIndexedDbWriteBatch`, `OIMPersistIndexedDbRecordsService`, `OIMPersistIndexedDbSnapshotService`, `TOIMPersistIndexedDbBackendOptions`, `TOIMPersistIndexedDbRecordsServiceOptions`, `TOIMPersistIndexedDbSnapshotServiceOptions`, `TOIMPersistIndexedDbPrimaryKey`, `TOIMPersistIndexedDbTableRecord` | | `@oimdb/persist-localstorage` | `OIMPersistLocalStorageKeyValueBackend`, `TOIMPersistLocalStorageKeyValueBackendOptions` | | `@oimdb/persist-async-kv` | `OIMPersistAsyncKVStorage`, `TOIMPersistAsyncKVStorageOptions`, `TOIMPersistAsyncKVMultiStorage` | ### The wiring A persistor owns one backend, one scheduler and a list of resources. A resource is one thing being persisted: a source (the in-memory side), a strategy (where it lives in the backend) and what to do on hydrate. ```ts import { OIMPersistEntityWriter, OIMPersistCollectionWriteRecordSource, OIMPersistRecordsResource, OIMPersistMicrotaskScheduler, OIMPersistor, } from '@oimdb/persist'; import { OIMPersistMemoryBackend, OIMPersistMemoryRecordsService, OIMPersistMemoryWriteBatch } from '@oimdb/persist-memory'; const persistEntityWriter = new OIMPersistEntityWriter({ entityWriter: createOIMInPlaceEntityWriter(), }); const persistedCardCollectionService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService({ entityWriter: persistEntityWriter }) }); const persistedCardEntityStoreSlot = persistedCardCollectionService.createStoreSlot(db); const persistMemoryBackend = new OIMPersistMemoryBackend(); const persistor = new OIMPersistor({ persistBackend: persistMemoryBackend, persistScheduler: new OIMPersistMicrotaskScheduler(), onPersistError: (error, persistErrorContext) => { console.error(persistErrorContext.persistOperation, error); }, }); const cardPersistResourceRecords = persistor.addPersistResource(new OIMPersistRecordsResource({ persistRecordSource: new OIMPersistCollectionWriteRecordSource({ entityCollectionService: persistedCardCollectionService, entityStoreSlot: persistedCardEntityStoreSlot, persistEntityWriter, }), persistRecordsService: new OIMPersistMemoryRecordsService({ storageKey: 'cards' }), })); await persistor.hydrate(); persistor.start(); persistedCardCollectionService.writeSlotContentByKey(persistedCardEntityStoreSlot, 'c1', { id: 'c1', title: 'Ace', rank: 1, deck: 'spades' }); await persistor.persist(); await persistor.unload(cardPersistResourceRecords, ['c1']); await persistor.load(cardPersistResourceRecords, ['c1']); ``` Rules a generator must keep: - Pass both generics of `OIMPersistor`: the backend class and its write batch class (`OIMPersistMemoryWriteBatch`, `OIMPersistIndexedDbWriteBatch`, `OIMPersistKeyValueWriteBatch`; `OIMPersistJsonMemoryBackend` uses `OIMPersistMemoryWriteBatch`, `OIMPersistLocalStorageKeyValueBackend` uses `OIMPersistKeyValueWriteBatch`). - Pass the generics of strategies, codecs and `OIMPersistEntityWriter` explicitly; their options carry no type to infer them from. - An entity collection persisted through a collection source is built with the `OIMPersistEntityWriter` as its `entityWriter`, and the same writer goes into the source's `persistEntityWriter`. The source takes the collection service and ONE of its store slots (`entityCollectionService`, `entityStoreSlot`). The writer belongs to the content service, not to the store slot, and the source keeps only the writes whose `entitySlot.storeSlot` is its own store slot; a write to another store slot of the same collection type is ignored by it. `new OIMPersistEntityWriter({ entityWriter })` wraps the `IOIMEntityWriter` that really writes, and reports the entity slot of every fill, put, patch, column patch, column delete and clear that changed something (`subscribeEntitySlotWritten`). - The entity collection service a source takes is any collection service with `getSlots`, `peekSlotByKey`, `writeSlotContentByKey`, `writeInBatch` and a `slotContentService` with `clearSlotContent` (`TOIMPersistEntityCollectionService`): what `createOIMSlotCollectionService` over an entity content service builds. - A source refuses, by name, a store slot on another channel slot than the one it was given (the bucket source checks both the entity and the bucket store slot). - Order: `addPersistResource` every resource, `await persistor.hydrate()`, then `persistor.start()`. ### Constructors and option keys | constructor | options | |---|---| | `OIMPersistor` | `{ persistBackend, persistScheduler, onPersistError? }` | | `OIMPersistRecordsResource` | `{ persistRecordSource, persistRecordsService, persistHydrateReconcile? }` | | `OIMPersistSnapshotResource` | `{ persistSnapshotSource, persistSnapshotService, persistCodec, persistHydrateReconcile? }` | | `OIMPersistCollectionWriteRecordSource`, `OIMPersistCollectionChangeWriteRecordSource` | `{ entityCollectionService, entityStoreSlot, persistEntityWriter }` (`TOIMPersistRecordSourceCollectionOptions`) | | `OIMPersistBucketRecordSource` | `{ channelMap, entityCollectionService, entityStoreSlot, bucketContentService, bucketSlot }` — `channelMap` is the db, `bucketContentService` the bucket collection's `slotContentService` | | `OIMPersistSingleEntitySnapshotSource` | `{ channelMap, singleSlotService, entityStoreSlot }` — a single entity service (`createOIMSingleSlotService` over an entity content service) and one of its store slots (`TOIMSingleSlotStoreSlot`) | | `OIMPersistEntityWriter` | `{ entityWriter }` | | `OIMPersistMicrotaskScheduler` | none | | `OIMPersistFrameScheduler` | `{ channelSlot }` — `db.defaultChannelSlot` | | `OIMPersistIdentityCodec` | none | | `OIMPersistVersionedCodec` | `{ version, migrations, persistCodec }` | | `OIMPersistMemoryBackend` | none | | `OIMPersistMemoryRecordsService`, `OIMPersistMemorySnapshotService` | `{ storageKey }` | | `OIMPersistJsonMemoryBackend` | `{ initialPersistJsonDump? }`, the object itself optional | | `OIMPersistIndexedDbBackend` | `{ databaseName, databaseVersion?, indexedDb? }` | | `OIMPersistIndexedDbRecordsService` | `{ tableName }` | | `OIMPersistIndexedDbSnapshotService` | `{ tableName, primaryKey }` | | `OIMPersistKeyValueBackend` | `{ persistKeyValueStorage, persistKeyValueSerializer? }` | | `OIMPersistItemKeyValueStorage` | `{ persistKeyValueItemStorage }` | | `OIMPersistKeyValueEntrySnapshotService` | `{ storageKey }` | | `OIMPersistKeyValuePathSnapshotService` | `{ storageKey, path }` | | `OIMPersistLocalStorageKeyValueBackend` | `{ persistKeyValueItemStorage?, persistKeyValueSerializer? }`, the object itself optional | | `OIMPersistSlotSourceChangeMark` | `{ channelClock, slots }` | | `OIMPersistSubscriptionSourceChangeMark` | `{ subscribeSourceChanged }` | | `OIMPersistAsyncKVStorage` | `{ persistAsyncKVMultiStorage }` | `onPersistError(error, persistErrorContext)` receives a `TOIMPersistErrorContext`, `{ persistResource, persistOperation }`. `TOIMPersistOperation` is `'start' | 'persist' | 'hydrate' | 'clear' | 'quarantine'`. `TOIMPersistErrorReport` is one failure, `{ error, persistErrorContext }`, as it is handed to `onPersistError` or collected into the `AggregateError`. ### Two resource kinds, and when to pick each | | `OIMPersistRecordsResource` | `OIMPersistSnapshotResource` | |---|---|---| | source | a record source: entity store slot or bucket | any snapshot source: entity store slot, bucket or single entity | | strategy | `OIMPersistMemoryRecordsService`, `OIMPersistIndexedDbRecordsService` | `OIMPersistMemorySnapshotService`, `OIMPersistIndexedDbSnapshotService`, `OIMPersistKeyValueEntrySnapshotService`, `OIMPersistKeyValuePathSnapshotService` | | autosave writes | the delta: one upsert or one deletion per entity slot written since the last drain | the whole snapshot, read from the source and encoded | | `persist()` writes | every record, replacing what is stored; while any key is unloaded, every in-memory record as an upsert over what is stored, plus the deletions the resource already heard | the whole snapshot | | codec | none | `persistCodec`, required | | `unload` | yes | no | | `load` | yes | no | Pick records whenever the backend has a records strategy (memory, JSON, IndexedDB): autosave then costs one entry per written entity slot, independent of the store slot's size. Pick snapshot for a single entity, for the key-value backends (localStorage, async KV), which have no records strategy, or when a versioned codec must migrate what is stored. A record source is also a snapshot source whose snapshot is `TOIMPersistRecords` (`{ records: { key, entity }[] }`), so an entity store slot or a bucket goes into either kind. A records resource keeps its dirty state as a set of entity slots, read through the slot with no key lookup; a slot written several times between drains is one entry. At the drain each slot becomes an upsert of `{ key, entity }` when it holds an entity and is not released, and a deletion of its key otherwise. When a key has both, a released slot and a live slot minted again for that key inside one batch, the live slot wins: an upsert, not a deletion. ### The sources, and the scheduler each pairs with | source | reports | scheduler | |---|---|---| | `OIMPersistCollectionWriteRecordSource` | synchronously, at the write, from `OIMPersistEntityWriter` only | `OIMPersistMicrotaskScheduler` | | `OIMPersistCollectionChangeWriteRecordSource` | synchronously, at the write, from `OIMPersistEntityWriter` and from a content-change listener on the entity store slot | `OIMPersistMicrotaskScheduler` | | `OIMPersistBucketRecordSource` | from effects (`OIMEffectService`), when the channel runs its frame | `OIMPersistFrameScheduler({ channelSlot })` | | `OIMPersistSingleEntitySnapshotSource` | from an effect, when the channel runs its frame | `OIMPersistFrameScheduler({ channelSlot })` | - **Collection** (an entity collection service and one of its store slots): every entity slot of that store slot that holds an entity. Starting reports nothing; content present before `start()` is written by `persist()` or by its next write. An entity removed for any reason, a slot release policy included, goes through the writer's `clearEntity` and reaches the backend as a deletion; `unload` is the call that removes from memory and keeps the stored value. The two collection sources are one fork, chosen at construction, with the same options: | collection source | in-place edit announced with `entitySlot.markEntityChanged(changedColumns?)` | cost while a resource listens | pick it when | |---|---|---|---| | `OIMPersistCollectionWriteRecordSource` | NOT persisted: it hears only the writer | none: every write stays on the core fast path | every change goes through `writeSlotContentByKey`, `writeSlotContent`, `updateEntity` and `clearSlotContent` | | `OIMPersistCollectionChangeWriteRecordSource` | persisted: while subscribed it adds a content-change listener of every column to the store slot | EVERY write to that store slot leaves the core fast path, not only `markEntityChanged`: changed-column bookkeeping and the listener loop per write | the app edits entities in place | - **Bucket**: the entities one bucket slot holds. Get the slot with `bucketCollectionService.holdSlotByKey(bucketStoreSlot, key)`. The source watches the bucket slot with one effect and each member entity slot with one effect. An entity that leaves the bucket is deleted from the backend and stays in the entity store slot. The first subscription reports every member, so `start()` writes the current members on the first drain, except members still holding the value a hydrate restored. - **Single entity**: the snapshot is the entity itself (a store slot of a single entity service, read through `peekSingleSlot(entityStoreSlot)`), so it goes only into `OIMPersistSnapshotResource`. Its first subscription reports the current value unless it is the value a hydrate restored. `readSnapshot` throws when the entity slot holds no value. The bucket and single-entity sources tell their own restored writes apart from user writes by comparing the entity, column by column with SameValueZero (NaN equals NaN, as core's write guard does), against a copy taken when it was restored (`OIMPersistRestoredEntities`). A wake is not written while the source still holds the restored value. The first time a different value is seen, the memo for that key is gone, so an edit and a later revert to the restored value, in another frame, are both written. ```ts import { OIMPersistBucketRecordSource, OIMPersistRecordsResource, OIMPersistFrameScheduler, OIMPersistor, } from '@oimdb/persist'; import { OIMPersistMemoryBackend, OIMPersistMemoryRecordsService, OIMPersistMemoryWriteBatch } from '@oimdb/persist-memory'; type TDeckCardSlot = TOIMEntitySlot; const deckCardCollectionService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService() }); const deckCardEntityStoreSlot = deckCardCollectionService.createStoreSlot(db); const deckBucketService = createOIMSlotCollectionService({ slotContentService: new OIMPositionalArrayBucketContentService({ bucketCommands: new OIMBucketCommands({ maxCommandsPerSlot: undefined }) }) }); const deckBucketStoreSlot = deckBucketService.createStoreSlot(db); const spadesBucketSlot = deckBucketService.holdSlotByKey(deckBucketStoreSlot, 'spades'); const deckPersistor = new OIMPersistor({ persistBackend: new OIMPersistMemoryBackend(), persistScheduler: new OIMPersistFrameScheduler({ channelSlot: db.defaultChannelSlot }), }); deckPersistor.addPersistResource(new OIMPersistRecordsResource({ persistRecordSource: new OIMPersistBucketRecordSource({ channelMap: db, entityCollectionService: deckCardCollectionService, entityStoreSlot: deckCardEntityStoreSlot, bucketContentService: deckBucketService.slotContentService, bucketSlot: spadesBucketSlot, }), persistRecordsService: new OIMPersistMemoryRecordsService({ storageKey: 'spades' }), })); await deckPersistor.hydrate(); deckPersistor.start(); const aceSlot = deckCardCollectionService.writeSlotContentByKey(deckCardEntityStoreSlot, 'c1', { id: 'c1', title: 'Ace', rank: 1, deck: 'spades' }); spadesBucketSlot.writeSlotContent([aceSlot]); db.flush(); await deckPersistor.whenIdle(); ``` ### Schedulers `IOIMPersistScheduler` is `attachDrain(drain)`, `start()`, `stop()`, `requestDrain()`. The persistor calls `attachDrain` from its constructor; both shipped schedulers throw when a second persistor attaches, so construct one scheduler per persistor. - `OIMPersistMicrotaskScheduler`: `requestDrain()` queues one microtask; the requests that follow before it runs are absorbed by it. `stop()` makes a queued microtask do nothing. - `OIMPersistFrameScheduler({ channelSlot })`: while started it subscribes with `OIMChannelService.INSTANCE.subscribeAfterEachFrame(channelSlot, …)` and drains after a frame only when a drain was requested since the last one; `stop()` unsubscribes and forgets the request. It holds no slot and never asks the channel for a frame: it drains only after a frame the channel runs anyway. **The pairing is a rule.** A write to an entity slot that nobody holds causes no frame (`OIMChannelService.INSTANCE.writeWithoutFlushCheck` only counts it in `clock.unheldSlotWriteCount` when `holdCount` is `0`), so a collection source on the frame scheduler can report changes that no frame ever drains. Pair `OIMPersistCollectionWriteRecordSource` and `OIMPersistCollectionChangeWriteRecordSource` with `OIMPersistMicrotaskScheduler`. The bucket and single-entity sources report from effects, which cause the frames they run in, so pair them with `OIMPersistFrameScheduler`. Resources of both groups in one persistor share its one scheduler; give them two persistors when they need different schedulers. `whenIdle()` resolves when the work queued at the moment of the call has settled. On the frame scheduler the drain runs inside `db.flush()`, so `db.flush(); await persistor.whenIdle()` covers the autosave. On the microtask scheduler the autosave is queued on the microtask after the write: let one microtask pass before calling `whenIdle()`, or call `persist()`. ### Persistor methods | method | what it does | |---|---| | `addPersistResource(persistResource)` | registers and returns it; on a started persistor it starts the resource first and registers it only if that start succeeded (a failed start is thrown from `addPersistResource`) | | `removePersistResource(persistResource)` | stops it and drops its pending write | | `start()` / `stop()` | subscribe / unsubscribe every resource and the scheduler; `start()` skips quarantined resources; pending writes survive `stop()`. A resource whose subscribe throws does not stop the others: each failure goes to `onPersistError` with `persistOperation: 'start'`, or, without a handler, all are thrown as one `AggregateError`. A resource whose start failed stays registered and unsubscribed, with no autosave, until `stop()` and `start()` again; `addPersistResource` on a started persistor does not register a resource whose start throws. A bucket or single-entity source reports its current value at subscribe time (except a hydrate-restored value), so the first drain after `start()` writes it; a collection source reports nothing then | | `destroy()` | `stop()`, then forgets every resource | | `hydrate()` | reads every resource and writes it into its source; ends the upsert-only mode of an unloaded resource | | `persist()` | writes every resource in full, started or not, in one write batch; a records resource with unloaded keys writes its in-memory records as upserts over the stored table instead of replacing it, plus the deletions it already heard | | `clearPersisted()` | deletes every resource's stored data in one write batch; memory is untouched; ends the upsert-only mode of an unloaded resource | | `unload(persistRecordsResource, keys)` | writes the keys' current values plus the resource's pending change in one write batch, repeated until the keys have no unwritten change (unload holds the keys' entity slots while it writes and compares their revision stamps, a slot's stamp moving only on a real write; it also checks the resource's pending set and whether a key's slot was replaced), then removes the keys from memory only | | `load(persistRecordsResource, keys)` | the pair of `unload`: queued after the pending writes, reads only those keys from the backend (`readRecordsOfKeys`) and puts the stored entities back without writing them back; skips a key that holds a value in memory or has a change the resource has not written yet; the keys stop counting as unloaded | | `whenIdle()` | resolves when the queued work settles; never rejects | Every promise-returning call and every autosave runs on one ordered chain, one at a time, in request order. A snapshot is read when its work runs, not when it was queued. ### The write batch, retry and quarantine - **One batch per drain.** A drain takes every dirty resource with a pending write, calls `persistBackend.createWriteBatch()` once, lets each resource write into it, and calls `commit()` once. `persist()` and `clearPersisted()` do the same for every registered resource. - **Whole-batch failure.** Every resource in the batch puts its in-flight change back (a records resource returns the failed entity slots to its dirty set; a snapshot resource marks itself pending), then the persistor writes each resource again in a batch of its own, so the healthy ones commit and the failure is attributed to the resource that caused it. A failed batch of N resources costs 1 + N commits. - **Retry.** A failed autosave leaves the resource dirty; the next drain writes it. The next drain comes from the next drain request (a change in any resource), a `persist()` or an `unload`. There is no retry timer. - **Quarantine.** Three consecutive autosave failures of one resource stop it listening to its source and drop its pending write; it is reported once with `persistOperation: 'quarantine'`, or on `console.error` without `onPersistError`. A successful `persist()` of it lifts the quarantine and, on a started persistor, starts it again; `start()` skips a quarantined resource. Any successful write resets the count, whichever operation committed it (autosave, `persist()`, `clearPersisted()`, `unload`); `persist()` failures do not add to it. - **Errors.** With `onPersistError`, each failure is handed over and the promise resolves; a failed autosave below quarantine is reported with `'persist'`, a failed resource subscribe in `start()` with `'start'`. Without it, `start()` (throws), `hydrate()`, `persist()` and `clearPersisted()` attempt every resource, then reject with one `AggregateError` whose `errors` holds every failure; a failed autosave below quarantine is silently retained, and the quarantine logs to the console. `unload` rejects its own promise when its write fails, and then leaves the keys in memory. ### Hydrate: reconcile and refusal `hydrate()` reads each resource through its strategy. A read that resolves `undefined` means nothing is stored, and nothing is applied. Anything else, an empty `{ records: [] }` included, is applied: decoded through `persistCodec` on a snapshot resource, passed through `persistHydrateReconcile(currentSnapshot, incomingSnapshot)` when set, then written into the source. Hydrate's own writes are not reported as changes, so `start()` after `hydrate()` writes nothing back. What the source does with it: - collection: upserts every record into the entity store slot, then deletes every entity the records do not name; the store slot becomes exactly the stored content; - bucket: upserts every record into the entity store slot and sets the bucket's members to exactly the restored entities; - single entity: `singleSlotService.writeSingleSlotContent(entityStoreSlot, entity)`. **Refusal.** If the source changes while the backend read is in flight and the resource has no `persistHydrateReconcile`, hydrate throws instead of applying, because applying would revert that change. The source keeps its newer state; the error goes to `onPersistError` with `'hydrate'`, or into the `AggregateError`. Before the read the resource calls `persistSnapshotSource.markSourceChanges()`, which returns an `IOIMPersistSourceChangeMark` (`isSourceChangedSinceMark()`, `dispose()`): the single-entity and bucket sources return an `OIMPersistSlotSourceChangeMark` that holds the slots and compares their revision stamps (`changedAtRevision`, `changedAtEpoch`) with the channel clock reading taken at the mark (`isOIMAnySlotChangedAfter`), the collection sources an `OIMPersistSubscriptionSourceChangeMark` whose flag their own report sets. A change made during the read is seen even when no frame runs, and the guard runs whether or not the persistor is started. **Reconcile.** `reconcileOIMByKey(resolveEntity)` builds a `TOIMPersistHydrateReconcile>`. `resolveEntity(currentEntity, incomingEntity, key)` runs for every stored key, with `currentEntity` `undefined` when memory lacks the key, and returns the entity to keep or `undefined` to drop it. Keys only in memory are kept. Order: memory's keys first, then the stored keys memory lacked. A snapshot resource over a single entity takes any `(currentSnapshot, incomingSnapshot) => snapshot` function. ```ts import { reconcileOIMByKey } from '@oimdb/persist'; const answerReconcile = reconcileOIMByKey( (currentEntity, incomingEntity) => currentEntity === undefined ? incomingEntity : { ...currentEntity, rank: incomingEntity.rank }, ); ``` ### unload, load and clearPersisted `persistor.unload(persistRecordsResource, keys)` takes an `OIMPersistRecordsResource` only. It first drains the persistor's dirty resources onto the chain, then, in its own turn, writes in one write batch that resource's pending change and the current value of every unloaded key (`persistRecordSource.readRecordsDelta(persistRecordSource.peekEntitySlotsByKeys(keys))`), so an edit no drain had reached, or one made while the persistor was stopped or the resource quarantined, is saved. unload holds the keys' entity slots while it writes, and after each commit it compares their revision stamps (a slot's stamp moves only on a real write), checks the resource's pending set and whether a key's slot was replaced; while any of those moved it writes another batch of the same shape, so an edit made during any commit (and, on the bucket source, an edit the channel has not flushed yet) reaches the backend. Only then does it remove the keys from the source with this resource's reporting suppressed, so the removal is not written by it. The backend keeps the keys; `load` brings those keys back and the next `hydrate()` brings back everything, and a restored entity persists its next edit like any other. A failed write rejects the unload and leaves the keys in memory. On a collection source and on the bucket source the keys are deleted from the entity store slot. Deleting an entity does not take it out of a bucket: the bucket keeps the slot as a member until it is refiled. The bucket source remembers the deletion as restored for every key that is a member of the bucket at unload time, whether or not the persistor is listening. While any key of a records resource is unloaded, `persist()` writes that resource's in-memory records as upserts over the stored table instead of replacing it, plus the deletions the resource already heard (its pending deletions), so the unloaded records stay on the backend. A deletion it never heard is not written in that mode. `hydrate()` and `clearPersisted()` end that mode, and so does a `load` of every unloaded key. `persistor.load(persistRecordsResource, keys)` is the pair of `unload` and takes an `OIMPersistRecordsResource` only (a key-value backend has no records strategy, so a snapshot resource has no `load`). It drains the dirty resources onto the chain and runs after those writes. In its turn it reads only those keys through `persistRecordsService.readRecordsOfKeys(persistBackend, keys)`: on IndexedDB one `readonly` transaction with one `get` per key, on memory a lookup of each key in the stored map; a key the backend does not hold is left out. It skips every key that holds a value in memory or has a change the resource has not written yet (pending or in a commit), so neither a write nor a heard deletion made during the read is overwritten. The rest goes to `persistRecordSource.loadRecords(persistRecords)` with this resource's reporting suppressed, so the loaded entities are not written back. A collection source upserts them into the entity store slot; the bucket source upserts them into the entity store slot, adds the slots back to the bucket (`bucketContentService.addBucketMemberSlots`) and remembers them as restored. The keys stop counting as unloaded, so once none is, `persist()` replaces the stored table again. Another resource over the same entity store slot is not suppressed and hears the upserts as writes. A failed read rejects the promise `load` returned. When to unload and when to load (on a screen change, on idle, on a read miss) is the application's decision, or an orchestrator's; persist offers the two doors and decides neither. **Limit:** another resource over the same entity store slot is not suppressed. It reports the unloaded keys as deletions, and its next autosave deletes them from ITS storage. Unload only keys no other resource persists. **Limit:** a deletion made while the persistor is stopped, or the resource is quarantined, is not heard. While any key of the resource is unloaded, `persist()` writes no deletion it did not hear, and `unload` writes it only while the entity's slot still exists (once the slot was released no slot is found for the key); otherwise the record comes back on the next `hydrate()`. Call `persist()` while started, and with no key unloaded, to make a deletion the resource never heard durable. `persistor.clearPersisted()` calls every resource's strategy delete (`deleteRecords` / `deleteSnapshot`) inside one write batch with one commit, under the same whole-batch split and error rules as `persist()`. Memory is untouched. ### Codecs A snapshot resource encodes on every write and decodes on hydrate through its required `persistCodec`, an `IOIMPersistCodec` (`encode`, `decode`). A records resource has no codec: it stores entities as the source holds them. - `new OIMPersistIdentityCodec()`: passes the snapshot through. - `new OIMPersistVersionedCodec({ version, migrations, persistCodec })`: stores a `TOIMPersistVersionedShape`, `{ version, data }`, where `data` is the inner `persistCodec`'s encoding (required; use `OIMPersistIdentityCodec` when nothing transforms). `migrations` is a `Record unknown>` keyed by the version each migration produces. On decode it runs, ascending, every migration whose key is above the stored `version` and at most the current one, then decodes with the inner codec. A stored `version` above the codec's own is refused: `decode` throws and the hydrate reports it with `'hydrate'`. The strategy is typed with `TOIMPersistVersionedShape`. ```ts import { OIMPersistIdentityCodec, OIMPersistVersionedCodec, OIMPersistKeyValueBackend, OIMPersistKeyValueEntrySnapshotService, OIMPersistItemKeyValueStorage, OIMPersistKeyValueWriteBatch, OIMPersistSnapshotResource, OIMPersistFrameScheduler, OIMPersistSingleEntitySnapshotSource, OIMPersistor, } from '@oimdb/persist'; import type { TOIMPersistVersionedShape } from '@oimdb/persist'; type TSettings = { theme: 'light' | 'dark'; density: 'compact' | 'comfortable' }; const settingsSingleEntityService = createOIMSingleSlotService({ slotContentService: createOIMEntityContentService() }); const settingsEntityStoreSlot = settingsSingleEntityService.createStoreSlot(db); settingsSingleEntityService.writeSingleSlotContent(settingsEntityStoreSlot, { theme: 'light', density: 'compact' }); const itemByStorageKey = new Map(); const settingsPersistor = new OIMPersistor({ persistBackend: new OIMPersistKeyValueBackend({ persistKeyValueStorage: new OIMPersistItemKeyValueStorage({ persistKeyValueItemStorage: { getItem: storageKey => itemByStorageKey.get(storageKey) ?? null, setItem: (storageKey, item) => { itemByStorageKey.set(storageKey, item); }, removeItem: storageKey => { itemByStorageKey.delete(storageKey); }, }, }), }), persistScheduler: new OIMPersistFrameScheduler({ channelSlot: db.defaultChannelSlot }), }); settingsPersistor.addPersistResource(new OIMPersistSnapshotResource({ persistSnapshotSource: new OIMPersistSingleEntitySnapshotSource({ channelMap: db, singleSlotService: settingsSingleEntityService, entityStoreSlot: settingsEntityStoreSlot, }), persistSnapshotService: new OIMPersistKeyValueEntrySnapshotService({ storageKey: 'settings' }), persistCodec: new OIMPersistVersionedCodec({ version: 2, migrations: { 2: data => ({ density: 'comfortable', ...(data as object) }) }, persistCodec: new OIMPersistIdentityCodec(), }), })); await settingsPersistor.hydrate(); settingsPersistor.start(); settingsSingleEntityService.getSingleSlot(settingsEntityStoreSlot).updateEntity({ theme: 'dark' }); db.flush(); await settingsPersistor.whenIdle(); ``` ### Backends and their strategies **Memory** (`@oimdb/persist-memory`). `new OIMPersistMemoryBackend()`. Snapshot values and records live in two separate maps, so a snapshot and a records resource may share a `storageKey`. `OIMPersistMemoryRecordsService({ storageKey })` keeps one `Map` of key to entity per `storageKey`: autosave sets and deletes keys, `persist()` replaces the map (while the resource has unloaded keys, sets keys and deletes only the deletions the resource already heard), `clearPersisted()` deletes it, and a `load` looks each of its keys up in the map through `readRecordsOfKeys`. `OIMPersistMemorySnapshotService({ storageKey })` keeps one value. `readRecords(storageKey)` and `readSnapshotValue(storageKey)` read what was committed. `OIMPersistMemoryWriteBatch` queues every change and applies them in order on `commit()`. **JSON** (`@oimdb/persist-json`, depends on `@oimdb/persist-memory`). `OIMPersistJsonMemoryBackend` extends `OIMPersistMemoryBackend` and takes the memory strategies. `dehydrate()` returns a `TOIMPersistJsonDump`, `{ snapshotValues: Record, recordsByStorageKey: Record }`; `new OIMPersistJsonMemoryBackend({ initialPersistJsonDump })` writes such a dump straight into its maps. The SSR flow: on the server, `await persistor.persist()` and then `JSON.stringify(persistJsonMemoryBackend.dehydrate())`; on the client, `new OIMPersistJsonMemoryBackend({ initialPersistJsonDump: JSON.parse(jsonText) })`, register the same resources under the same `storageKey`s, `await persistor.hydrate()`. To merge a durable cache over the server's content, hydrate the JSON persistor first, then the durable persistor with `persistHydrateReconcile`, then `start()` the durable one. **IndexedDB** (`@oimdb/persist-idb`). `new OIMPersistIndexedDbBackend({ databaseName, databaseVersion?, indexedDb? })`; `indexedDb` defaults to `globalThis.indexedDB` and the constructor throws without either. `OIMPersistIndexedDbRecordsService({ tableName })` stores one value per entity key in an object store: autosave puts and deletes per key, `persist()` clears the table and puts every entity (while the resource has unloaded keys, only puts plus a delete per deletion the resource already heard), `clearPersisted()` clears it, and a `load` reads its keys through `readRecordsOfKeys` in one `readonly` transaction, one `get` per key. `OIMPersistIndexedDbSnapshotService({ tableName, primaryKey })` stores one value at `primaryKey`. One commit is one `readwrite` transaction over every table the batch touches. A commit opens the database and creates missing tables by a version upgrade (retried when another connection upgrades first, up to five attempts; an upgrade blocked for five seconds rejects); a read never creates a table, and a missing table reads as `undefined`. A `TOIMPersistIndexedDbPrimaryKey` is an `IDBValidKey` or a plain object; a plain object is encoded as the string `oimdb:object:` plus its JSON with sorted property names, and is read back as that string. **Key-value** (`@oimdb/persist`). `new OIMPersistKeyValueBackend({ persistKeyValueStorage, persistKeyValueSerializer? })` stores serialized strings under string keys. `persistKeyValueStorage` is an `IOIMPersistKeyValueStorage` (`readItems(storageKeys)`, `writeItems(itemByStorageKey)`, `removeItems(storageKeys)`); `OIMPersistItemKeyValueStorage({ persistKeyValueItemStorage })` adapts any `TOIMPersistKeyValueItemStorage` (`getItem`, `setItem`, `removeItem`, synchronous or returning promises) with one call per key. The serializer is a `TOIMPersistKeyValueSerializer` (`serialize`, `deserialize`) and defaults to `OIM_PERSIST_KEY_VALUE_JSON_SERIALIZER`. Strategies, both snapshot strategies: | strategy | stored as | |---|---| | `OIMPersistKeyValueEntrySnapshotService({ storageKey })` | the whole snapshot under `storageKey` | | `OIMPersistKeyValuePathSnapshotService({ storageKey, path })` | the snapshot at `path` (a `string[]`) inside an object under `storageKey`; several resources may share the key; the constructor throws on an empty `path` | `OIMPersistKeyValueWriteBatch` commits with at most one `readItems` (keys with path writes or path deletions and no whole-value write in the batch), one `writeItems` and one `removeItems`; it serializes every value before writing any. Path segments are own properties, so a stored `__proto__` is data. - **localStorage** (`@oimdb/persist-localstorage`): `OIMPersistLocalStorageKeyValueBackend` extends `OIMPersistKeyValueBackend` over a `TOIMPersistKeyValueItemStorage` (`getItem`, `setItem`, `removeItem`) given as `persistKeyValueItemStorage`, which defaults to `globalThis.localStorage`; the constructor throws without either. One `setItem` per written key. - **async KV** (`@oimdb/persist-async-kv`): no backend class. Use `new OIMPersistKeyValueBackend({ persistKeyValueStorage: new OIMPersistAsyncKVStorage({ persistAsyncKVMultiStorage }) })`, where `persistAsyncKVMultiStorage` is a `TOIMPersistAsyncKVMultiStorage` (`multiGet`, `multiSet`, `multiRemove`, each returning a promise), the shape of React Native's `AsyncStorage`. One `multiGet`, one `multiSet` and one `multiRemove` per commit at most. ### Writing a backend, a strategy, a source - Backend: `IOIMPersistBackend` with `createWriteBatch()`; its batch is an `IOIMPersistWriteBatch` with `commit(): Promise`, collecting changes and applying them in `commit`. `OIMPersistWriteBatchChanges` is the list a batch keeps them in: `addWriteBatchChange(change)`, `hasWriteBatchChanges`, `applyWriteBatchChanges(target)`. `writeOIMPersistRecordsDelta(delta, putRecord, deleteRecord)` walks a `TOIMPersistRecordsDelta` in the one order every backend uses: upserts, then deletions. - Snapshot strategy: `IOIMPersistSnapshotService` with `readSnapshot(persistBackend)`, `writeSnapshot(writeBatch, snapshot)`, `deleteSnapshot(writeBatch)`. Records strategy: `IOIMPersistRecordsService` with `readRecords(persistBackend)`, `readRecordsOfKeys(persistBackend, keys)`, `writeRecords(writeBatch, persistRecords)`, `writeRecordsDelta(writeBatch, persistRecordsDelta)` (a `TOIMPersistRecordsDelta`, `{ upserts, deletedKeys }`), `deleteRecords(writeBatch)`. A read resolves `undefined` only when nothing is stored; `readRecordsOfKeys` resolves the records of the keys the backend holds and leaves out the rest. - Source: `IOIMPersistSnapshotSource` (`readSnapshot`, `writeSnapshot`, `subscribeSnapshotChanged`, `markSourceChanges`) or `IOIMPersistRecordSource`, which adds `subscribeEntitySlotChanged`, `readRecordsDelta(entitySlots)`, `peekEntitySlotsByKeys(keys)`, `markEntitySlotChanges(entitySlots)`, `loadRecords(persistRecords)`, `unloadKeys(keys)`. `markSourceChanges()` is required and returns an `IOIMPersistSourceChangeMark` (`isSourceChangedSinceMark()`, `dispose()`); build it with `new OIMPersistSlotSourceChangeMark({ channelClock, slots })` or `new OIMPersistSubscriptionSourceChangeMark({ subscribeSourceChanged })`. It must accept more than one subscription, each with its own `TOIMDisposer`. - Scheduler: `IOIMPersistScheduler`, above. ### Limits - **No key-value records strategy.** Over `OIMPersistKeyValueBackend` (localStorage, async KV) an entity store slot or a bucket goes through `OIMPersistSnapshotResource`: every autosave walks every entity slot of the source and serializes the whole snapshot under one key. - **A bucket membership change walks the bucket.** Each change of the bucket slot re-reads every member and every watched slot, and the source keeps one effect per member entity slot. - **The memory and JSON backends keep values by reference.** With `createOIMInPlaceEntityWriter()` the stored entity is the live entity object, so an in-place write moves the stored value before any commit, and `dehydrate()` returns the live objects. Use `createOIMReplacingEntityWriter()` with `entityInserter: insertOIMEntityWithCopy` where the stored value must stay what was committed, and serialize a dump at once. - **Hydrate without a reconcile replaces.** The collection source deletes every entity the stored records do not name, and an existing but empty records table (IndexedDB after `clearPersisted()`) reads as an empty list and empties the entity store slot. - **A key-value commit is not atomic across keys**: `writeItems` and `removeItems` are separate calls, and the item-driven storage calls `setItem` once per key. - **One backend and one scheduler per persistor.** Sources needing different schedulers, or two backends, take two persistors. --- ## `@oimdb/browser` Browser state as single slots. Each factory returns an `OIMSingleSlotService` (`TOIMBrowserSingleSlotService`) built with a slot subscription listener: the browser listener is added when the slot gets its first subscriber (directly or through a computed that reads it) and removed when the last one goes; the current value is written at the first subscription, and a write that would land during a flush is made right after it. ```ts signature createOIMBrowserOnlineSingleSlotService(options?: { defaults?: OIMDefaults; onBrowserEntityWritten?: () => void }): TOIMBrowserSingleSlotService // { isOnline } createOIMBrowserFocusSingleSlotService(options?): TOIMBrowserSingleSlotService // { isFocused }: document.hasFocus() createOIMBrowserVisibilitySingleSlotService(options?): TOIMBrowserSingleSlotService // { isVisible } createOIMBrowserLocationSingleSlotService(options?): TOIMBrowserSingleSlotService // { href, pathname, search, hash } ``` Read it like any single: `const onlineSlot = onlineService.getSingleSlot(onlineService.createStoreSlot(db))`, then an effect over `[onlineSlot]`, or `useOIMSelector(() => onlineService.getSingleSlot(online).entity)` in React. `isOnline` is `navigator.onLine` (a network interface exists, not a reachable internet); the location follows the Navigation API's `currententrychange` where it exists and `popstate` + `hashchange` otherwise, so without it a `history.pushState` is not seen until the next of those events. Without the API a sensor needs, the slot holds `true` (or an empty location). `OIMBrowserSlotSubscriptionListener` is the base class of the four listeners, built with `TOIMBrowserSlotSubscriptionListenerOptions` (`{ entityContentService, onBrowserEntityWritten? }`). `onBrowserEntityWritten` in the factory options commits what an event wrote: it is called after each write a browser event caused, never after the first value. It runs synchronously, inside the event's dispatch; a write that waited out a flush calls it right after that flush, from its after-flush handler. `focus()` and `blur()` called from your own code dispatch their events synchronously, so a `db.flush()` in it can run in the middle of the caller's turn; defer it (`queueMicrotask`) or hand it to your orchestrator when that matters. --- ## Performance **No figure may be quoted for this engine, and none is quoted anywhere in this file.** Every artifact under `packages/bench/measurements/` predates the surface documented in this file, so none of its figures prices what is described here. Such figures are **struck, not updated** — a stale number with a real-looking artifact path attached is worse than none. `packages/bench/results/` holds a timing series that is still in flight: fifty-five timing artifacts beside one memory artifact, of which eleven scenarios — `readByKey`, `scrollWindow`, `filterTwoAxes`, `consumerFloor`, `patchColumn`, `patchOutsideWindow`, `churnChain`, `churnShared`, `churnSharedDeep`, `churnWide`, `mountFloor` — carry all three points. Two things bound what it may be quoted for, and both are recorded in the artifacts themselves: the series is **incomplete**, and every run in it was taken with the load gate raised — to **3.5** foreign runnable processes on the 22 `small`/`wide` pieces, and to **25** on the 34 `default`-point ones — against the harness's own default of **0.5** (`packages/bench/src/harness/load.ts`, `DEFAULT_MAX_FOREIGN_LOAD`). Read `packages/bench/measurements/README.md` for what a raised gate does to a comparison before quoting anything out of that directory. Everything outside that series has **no number at all**. No strategy of any shipped fork has a measured price, so no consumer can pick with the numbers in front of them. The one quantity that needs no measurement, because it is arithmetic rather than a reading: emptying a bucket one slot at a time on an array-driven bucket costs n(n-1)/2 element moves — **499 500** for a thousand — which is why a bucket content service's `writeSlotContent` and `clearSlotContent` go through one `drainSlots`. Counted, not timed, in `packages/core/src/bucket/array/tests/everyone-out-at-once-and-not-one-at-a-time.test.ts`, which also pins `drainSlots` at zero element writes. Fast properties are checked, not timed. Every slot kind is one object literal with every field present at birth; per-index state lives in the `indexKeys` array; nothing adds a field to a slot later or deletes one; neither entity writer `delete`s a column — it writes `undefined`, in place or into a spread copy. So every slot of a kind keeps one V8 hidden class through holds, effects, moves between buckets, patches and release deadlines, and an entity keeps its own when a column leaves or arrives — `packages/core/tests/what-v8-keeps-on-fast-properties.test.ts` asks V8 directly through its own natives for fast properties and a shared map, and `packages/core/tests/how-many-shapes-reach-the-write-door.test.ts` pins three slot shapes at the write door, one below V8's polymorphic ceiling, and four at `holdSlot`, at it, a computed column slot among them as a computed slot. What that saves per read is not measured. An entity handed in with a few hundred fields is in dictionary mode before it arrives. The goal the measurement work serves: prove that **for every typical task there is a combination of shipped strategies whose cost is at or below the hand-written floor**, on the same tasks every framework in `packages/bench` is measured on. A ratio above 1.00 is a loss only when no strategy combination reaches the floor.