liwi-subscribe-store
v15.1.0
Published
subscribe store proxy
Readme
About
A proxy around a liwi-store Store that adds live query subscriptions. It implements the full Store interface, so it is a drop-in replacement: every write goes through to the wrapped store and then notifies listeners, which is how open queries learn about inserts, updates and deletes.
Only writes made through this proxy, in this process are observed. Changes written directly to the database (mongo shell, migrations) are not detected; another process writing through its own subscribe store can relay them.
Install
npm install --save liwi-subscribe-storeUsage
import { SubscribeStore } from "liwi-subscribe-store";
const store = new SubscribeStore(mongoStore);With mongo, prefer the helper which builds the same thing with the types already applied:
import { createMongoSubscribeStore } from "liwi-mongo";
export const tasksStore = createMongoSubscribeStore<Task>(
createMongoStore("tasks"),
);Queries created from it support subscribe / fetchAndSubscribe:
const query = tasksStore.createQueryCollection({
criteria: { completed: false },
sort: { created: 1 },
limit: 100,
});
const subscription = query.fetchAndSubscribe((error, changes) => {
if (error) throw error;
for (const change of changes) {
// change.type: "initial" | "inserted" | "updated" | "deleted"
}
});
// later
subscription.stop();API
new SubscribeStore(store)
Wraps a SubscribableStore. Beyond the Store interface it adds:
subscribe(listener): () => void— listen to every write going through the proxy; returns an unsubscribe function.subscribeChangedKeys(callback): () => void— the keys of every document written through this store (not those notified withnotifyChanged, so two relays cannot loop), for relaying them to another process (see Writes from another process). Like any listener, it makes writes read theirprev.notifyChanged(keys): Promise<void>— documents were written outside this store: re-reads them in one query and emitschanged. Reads nothing when nobody listens. Itsnextonly tells subscriptions whether they are concerned: each concerned one re-reads the documents in its own order.resync(): void— emitsresync: every open query subscription refetches and sends its whole result again asinitial.callSubscribed(action): void— dispatch an action to listeners manually.
Actions<Model>
type Actions<Model> =
| { type: "inserted"; next: Model[] }
| { type: "updated"; changes: [Model, Model][] } // [previous, next]
| { type: "deleted"; prev: Model[] }
| { type: "changed"; keys: AllowedKeyValue[]; next: Model[] } // a key missing from next was deleted
| { type: "resync" };changed and resync come from notifyChanged and resync; a listener with an exhaustive switch must handle them.
prev is always the stored document, never the object passed by the caller: queries decide whether a document entered or left their result by testing prev and next against their criteria, so a stale copy would leave rows in lists they no longer belong to.
| Write | Where prev comes from |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| partialUpdateByKey / partialUpdateOne | partialUpdateByKeyWithInfo of the wrapped store (atomic with the write), else findOne just before the write |
| replaceOne / replaceSeveral | replaceOneWithInfo (atomic), else findByKey just before the write |
| deleteByKey / deleteOne | deleteByKeyWithInfo (atomic), else findByKey just before the write |
| upsertOne / upsertOneWithInfo | upsertOneWithInfo of the wrapped store |
| partialUpdateMany | the matching keys are read first, then each document is updated as by partialUpdateByKey, re-checking criteria |
| deleteMany | the matching keys are read first, then each document is deleted with deleteByKeyWithInfo, re-checking criteria; without it, a cursor read before one deleteMany (not atomic) |
See Writes with info for the …WithInfo contract.
For partialUpdateMany and deleteMany, the emitted documents are exactly the ones written: a document that stopped matching criteria after the keys were read is left alone and not emitted, and a document inserted after the keys were read is not written. This costs one round trip per document instead of a single command.
Without listeners
When nothing is subscribed (no subscribe listener and no open query subscription), nobody needs prev, so writes go straight to the wrapped store: partialUpdateMany and deleteMany are a single command again, and partialUpdateByKey, replaceOne and deleteByKey use the plain methods (one round trip for a partial update by key instead of two). Behaviour is otherwise the same, including NotFoundError on a missing key.
Missing keys and failures
- A write on a key that does not exist emits nothing.
partialUpdateByKey,partialUpdateOne,replaceOneandreplaceSeveralthrowNotFoundError, or resolveundefinedwithallowNotFound;deleteByKeyanddeleteOneresolve. - When a concurrent delete lands between a partial update and its read-back, the update was applied but there is no
next: nothing is emitted (the delete emits its owndeletedaction) andpartialUpdateByKey/partialUpdateOnethrowDeletedAfterUpdateError, a subclass ofNotFoundError(or resolveundefinedwithallowNotFound).partialUpdateManyskips that document. replaceSeveral,partialUpdateManyanddeleteManyemit the writes that succeeded before rethrowing the first failure, so listeners stay in sync with what was written.
updated
Stamping updated and rejecting protected field updates is done by the wrapped store (see created and updated); partial update options such as touchUpdated are passed through. Because partialUpdateMany writes document by document here, each document gets its own write time, where a plain MongoStore gives the whole command one.
Writes from another process
Listeners only see writes going through this proxy, in this process. When another process writes the same collection, relay its keys: that process exposes subscribeChangedKeys with createStoreRelayResource (liwi-resources-server), this one feeds them to notifyChanged and resync with connectStoreRelay (liwi-resources-client).
Only keys travel. notifyChanged reads the documents once to find the concerned query subscriptions (holding one of the keys, or matching one of the documents); each of them re-reads those documents in its own action order and compares them with what its client holds. So a notification repeated, late, or crossing a local write or a refetch leaves the client equal to a fresh fetch, at the cost of one read per concerned subscription.
AbstractSubscribableStoreQuery
Base class for store implementations providing subscribable queries. It holds the subscribe store (setSubscribeStore / getSubscribeStore) and implements fetchAndSubscribe / subscribe on top of an abstract _subscribe; implementations turn store actions into query Changes by testing each affected model against the query criteria. liwi-mongo does this in memory with mingo.
Queries built this way are fixed: changeParams / changePartialParams throw — create a new query instead.
