@peabody-soft/mbs-model-ts 1.12.0 → 1.13.0

package/dist/Constants.d.ts

@@ -9,3 +9,4 @@ export declare function quantityFromScaledValue(scaledQuantity: number): number;
 export declare function quantityToScaledValue(quantity: number): number;
 export declare function taxRateFromScaledValue(scaledTaxRate: number): number;
 export declare function taxRateToScaledValue(taxRate: number): number;
+export declare const MAX_PROFILE_STALENESS_MS: number;

package/dist/Constants.js

@@ -44,3 +44,6 @@ export function taxRateFromScaledValue(scaledTaxRate) {
 export function taxRateToScaledValue(taxRate) {
     return Math.round(taxRate * (proto_Constants.TAX_RATE_FACTOR / 100));
 }
+// How long a signed-in customer's profile may go without a read before Model.refreshProfileIfStale
+// reads it again. A profile changes only when the customer edits it, on this or another device.
+export const MAX_PROFILE_STALENESS_MS = 60 * 60 * 1000;

package/dist/Exceptions.d.ts

@@ -2,3 +2,8 @@ export declare class InvalidArgumentException extends Error {
 }
 export declare class IllegalOperationException extends Error {
 }
+export declare class StoreCorruptException extends Error {
+    readonly containerName: string;
+    readonly reason: unknown;
+    constructor(containerName: string, reason: unknown);
+}

package/dist/Exceptions.js

@@ -1,8 +1,22 @@
-// The two programming errors this library throws. A UI does not recover from either. A sync
-// failure is a rejected promise (see ServiceExceptions.ts).
+// The two programming errors this library throws, and the exception for a store it cannot read. A
+// UI does not recover from a programming error. A sync failure is a rejected promise (see
+// ServiceExceptions.ts).
 // A caller passed something this library cannot work with
 export class InvalidArgumentException extends Error {
 }
 // A caller did something in an order this library does not allow
 export class IllegalOperationException extends Error {
 }
+// The store holds data that cannot be decoded, for example a blob cut short or one written by an
+// incompatible version. Everything in a store came from a server, except a cart that was not sent
+// and the id of a sign up that is under way. So deleting the containers and calling
+// Model.initialize again recovers: SyncCache keeps the containers it has opened, so a new
+// Model.initialize is needed after a delete.
+// containerName is the container that failed, and reason is what the decoder threw.
+export class StoreCorruptException extends Error {
+    constructor(containerName, reason) {
+        super(`The store holds data in container ${containerName} that cannot be read`);
+        this.containerName = containerName;
+        this.reason = reason;
+    }
+}

package/dist/InMemoryLock.d.ts

@@ -0,0 +1,5 @@
+import Lock from "./Lock";
+export default class InMemoryLock implements Lock {
+    runExclusive<TValue>(key: string, action: () => Promise<TValue>): Promise<TValue>;
+    private readonly _tails;
+}

package/dist/InMemoryLock.js

@@ -0,0 +1,20 @@
+// A Lock that excludes only callers of this object, in order. For a test, or for a caller whose
+// store is used by one tab.
+export default class InMemoryLock {
+    constructor() {
+        this._tails = new Map();
+    }
+    runExclusive(key, action) {
+        const previous = this._tails.get(key) ?? Promise.resolve();
+        const result = previous.then(action);
+        // The next caller starts when this one settles, whether or not it failed
+        const tail = result.then(() => undefined, () => undefined);
+        this._tails.set(key, tail);
+        // Forget the key when nobody is waiting, so the map does not grow with every key used
+        void tail.then(() => {
+            if (this._tails.get(key) === tail)
+                this._tails.delete(key);
+        });
+        return result;
+    }
+}

package/dist/Lock.d.ts

@@ -0,0 +1,3 @@
+export default interface Lock {
+    runExclusive<TValue>(key: string, action: () => Promise<TValue>): Promise<TValue>;
+}

package/dist/Lock.js

@@ -0,0 +1 @@
+export {};

package/dist/Model.d.ts

@@ -4,19 +4,22 @@ import Address from "./Address";
 import Business from "./Business";
 import Database from "./Database";
 import LiveData from "./LiveData";
+import Lock from "./Lock";
 import Profile from "./Profile";
 import Service from "./Service";
 import ShoppingList from "./ShoppingList";
 import UserProfile from "./UserProfile";
 export default class Model {
     private constructor();
-    static initialize(service: Service, database: Database): void;
+    static initialize(service: Service, database: Database, lock?: Lock): void;
     static getInstance(): Model;
     get business(): LiveData<Business | null>;
     get profile(): LiveData<Profile | null>;
     signIn(authenticationMethod: proto_AuthenticationMethod, subjectId: string, authenticationToken: string): Promise<void>;
     createUser(authenticationMethod: proto_AuthenticationMethod, subjectId: string, authenticationToken: string, userToCreate: UserProfile): Promise<void>;
     updateUser(userProfile: UserProfile): Promise<void>;
+    changeUser(change: (current: UserProfile) => UserProfile): Promise<void>;
+    refreshProfileIfStale(): Promise<boolean>;
     signOut(): Promise<void>;
     setBusinessId(businessId: string): Promise<void>;
     updateCart(shoppingList: ShoppingList): Promise<void>;
@@ -41,6 +44,9 @@ export default class Model {
     private static getBusinessContainerName;
     private requireBusinessAuthTokens;
     private profileSyncIn;
+    private syncProfile;
+    private readStoredUser;
+    private sendUserUpdate;
     private createProfileOnServer;
     private readProfilePages;
     private static requireJoinedBusiness;
@@ -49,20 +55,27 @@ export default class Model {
     private requireProfileContainerName;
     private buildProfileAuthTokens;
     private requireProfileAuthTokens;
+    private static getProfileCursorsKey;
     private publishBusiness;
     private publish;
     private static buildPublishable;
     private publishProfile;
+    private publishProfileFromStore;
+    private refreshProfile;
     private static getService;
     private static getCache;
     private static _service;
     private static _cache;
+    private static _lock;
     private static _instance;
     private _authenticationMethod;
     private _subjectId;
     private _authenticationToken;
     private _businessId;
     private _isPublishedBusinessVetted;
+    private _profileReadAt;
+    private _publishedProfileCursors;
+    private _profileRefresh;
     private readonly _business;
     private readonly _profile;
 }

package/dist/Model.js

@@ -1,9 +1,11 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import { FulfillmentMode as proto_FulfillmentMode } from "./generated/FulfillmentMode";
 import AuthTokens from "./AuthTokens";
+import { MAX_PROFILE_STALENESS_MS } from "./Constants";
 import * as ContainerNames from "./ContainerNames";
 import { IllegalOperationException, InvalidArgumentException } from "./Exceptions";
 import Ids from "./Ids";
+import InMemoryLock from "./InMemoryLock";
 import LiveData from "./LiveData";
 import { canonicalizeBusinessId } from "./Profile";
 import * as ProtoMap from "./ProtoMap";
@@ -15,15 +17,26 @@ import SyncState from "./SyncState";
 // The root of the object model, and the only object a UI needs. Call initialize once, then get the
 // current instance with getInstance.
 //
-// THERE IS NO LOCKING. A caller makes one call at a time and awaits it. Otherwise:
+// CALLS ARE NOT QUEUED. A caller makes one call at a time and awaits it. Otherwise:
 // - A setBusinessId still reading when signIn reads the business too can publish the anonymous
 //   container's business over the customer's. The published business then has no cart or orders,
 //   and nothing publishes them again.
-// - Two reads at once interleave their pages and writes, as do two tabs on one store (each holds a
-//   Model), so a store supports one tab at a time.
-// A queue inside Model would not fix the tabs, and each public method would need an unqueued twin
-// (signIn calls signOut, businessSyncIn calls updateCart). A caller that calls from several places,
-// like a UI, queues the calls itself.
+// - Two reads at once interleave their pages and writes.
+// A queue inside Model would need an unqueued twin of each public method (signIn calls signOut,
+// businessSyncIn calls updateCart). A caller that calls from several places, like a UI, queues the
+// calls itself. Only changeUser takes a Lock, so that two tabs do not start from the same user.
+//
+// SEVERAL TABS can use one store, each with its own Model. The store applies a batch atomically and
+// keeps the greater eTag, so what the tabs store converges on what the server holds. A profile
+// container is shared by every tab the customer has open, on any shop, so concurrent use matters
+// more there than in a business container, which only tabs on the same shop share. A sequence of
+// calls is not atomic across tabs:
+// - Deleting a container (deleteBusiness, or an eviction by the store) while another tab writes
+//   pages to it can leave its cursors ahead of its entities.
+// - The Business and Profile a Model publishes change only when that Model reads or writes. A
+//   cart or a user built from them can be older than what the store holds, and sending it replaces
+//   the newer one on the server. changeUser starts from the stored user, and a caller can read the
+//   profile again with refreshProfileIfStale.
 class Model {
     constructor() {
         // True when the published business, if any, has been read to the end and found to be the one
@@ -32,6 +45,13 @@ class Model {
         // failure, a rejection) leaves the business published and unvetted. See readJoinBusinessId, which
         // does not join such a business.
         this._isPublishedBusinessVetted = false;
+        // When the last read of the profile ended, as Date.now() gave it. Null before the first.
+        this._profileReadAt = null;
+        // The profile cursors the published profile was read at, from getProfileCursorsKey. Null until a
+        // profile is published from the store.
+        this._publishedProfileCursors = null;
+        // The read that refreshProfileIfStale is running, so an overlapping call can share it
+        this._profileRefresh = null;
         this._business = new LiveData(null);
         this._profile = new LiveData(null);
         this._authenticationMethod = null;
@@ -40,10 +60,13 @@ class Model {
         this._businessId = null;
     }
     // Sets the service and store to use. Discards the current instance, so nobody is signed in and no
-    // business is browsed.
-    static initialize(service, database) {
+    // business is browsed. lock makes changeUser exclusive: pass one that spans every tab that shares
+    // the store (see Lock), or leave the default, which excludes calls in this tab only. A call still
+    // running on the discarded instance is not excluded against the new one.
+    static initialize(service, database, lock = new InMemoryLock()) {
         Model._service = service;
         Model._cache = new SyncCache(database);
+        Model._lock = lock;
         Model._instance = null;
     }
     // The current model. Fetch it each time and do not keep it: signOut discards it.
@@ -135,12 +158,62 @@ class Model {
     // is cached and published as a profile read is, so the User as the server stored it replaces the
     // held one (see readProfilePages).
     async updateUser(userProfile) {
+        if (this._profile.value === null)
+            throw new IllegalOperationException("Nobody is signed in, so this call cannot be made");
+        await this.sendUserUpdate(this.requireProfileContainerName(), userProfile);
+    }
+    // Changes this customer's own user. Reads the profile, calls change with the user the profile
+    // container stores, and sends the user change returns, as updateUser does. Use it instead of
+    // updateUser when the new user is the current one with something altered, for example an address
+    // added. The current user includes what other tabs and devices have written, which a user built
+    // from the published profile may lack, and sending that user would erase it.
+    // Calls for one profile run one at a time. When the Lock given to initialize spans tabs, a second
+    // tab that changes the user waits for this change and starts from its result. The server still
+    // takes the last write of two devices that change the user at once.
+    // change must return a user with the id it is given, and must not call changeUser, which would
+    // wait for its own lock. Throws IllegalOperationException if no profile has been read,
+    // InvalidArgumentException if change returns another id, and what change throws.
+    async changeUser(change) {
         if (this._profile.value === null)
             throw new IllegalOperationException("Nobody is signed in, so this call cannot be made");
         const containerName = this.requireProfileContainerName();
-        const request = ProtoMap.buildUserRequest(ProtoMap.buildUpdateUser(userProfile), await Model.getCache().readProfileCursors(containerName));
-        const authTokens = await this.requireProfileAuthTokens();
-        await this.readProfilePages(containerName, ProtoMap.getUserRequestSyncOutRequest(request), authTokens, () => Model.getService().updateUser(request, authTokens));
+        await Model._lock.runExclusive(containerName, async () => {
+            await this.syncProfile(containerName);
+            const current = await this.readStoredUser(containerName);
+            if (current === null)
+                throw new IllegalOperationException("No user has been read, so there is none to change");
+            const changed = change(current);
+            if (changed.id !== current.id)
+                throw new InvalidArgumentException("A change of the user must keep the id of the user");
+            await this.sendUserUpdate(containerName, changed);
+        });
+    }
+    // Reads the profile if the last read of it is older than MAX_PROFILE_STALENESS_MS, and returns
+    // whether it did. Every read of the profile counts, a sign in and an update included. Does
+    // nothing when nobody is signed in or the first read is still under way. The read fetches only
+    // what changed, and calls that overlap share one read, so a UI can call it from every event that
+    // shows a tab again. The profile is published if it differs from what was published, including
+    // when another tab stored the answer first. Throws what a read throws, and a failed read leaves
+    // the profile stale, so the next call reads again. A clock set back counts as stale.
+    async refreshProfileIfStale() {
+        if (this._profile.value === null)
+            return false;
+        if (this._profileRefresh !== null)
+            return this._profileRefresh;
+        const readAt = this._profileReadAt;
+        if (readAt === null)
+            return false;
+        const age = Date.now() - readAt;
+        if (age >= 0 && age < MAX_PROFILE_STALENESS_MS)
+            return false;
+        const refresh = this.refreshProfile();
+        this._profileRefresh = refresh;
+        try {
+            return await refresh;
+        }
+        finally {
+            this._profileRefresh = null;
+        }
     }
     // Discards this model. The next getInstance() builds a fresh one, signed out and browsing nothing.
     async signOut() {
@@ -585,9 +658,26 @@ class Model {
         if (link !== null)
             return link;
         const joinBusinessId = await this.readJoinBusinessId(businessId);
-        await this.profileSyncIn(ProtoMap.buildProfileSyncOutRequest(await Model.getCache().readProfileCursors(this.requireProfileContainerName()), joinBusinessId), await this.requireProfileAuthTokens());
-        // Tried once: a join that leaves no link is the server contradicting itself, and retrying
-        // would not fix it.
+        const containerName = this.requireProfileContainerName();
+        const cache = Model.getCache();
+        try {
+            await this.profileSyncIn(ProtoMap.buildProfileSyncOutRequest(await cache.readProfileCursors(containerName), joinBusinessId), await this.requireProfileAuthTokens());
+        }
+        catch (error) {
+            if (!(error instanceof JoinNotAnsweredException))
+                throw error;
+            // The answer lacks the link and the business because the cursors are past them. Either
+            // another tab stored them first, and profileSyncIn has published them from the store, or the
+            // container lost them (it was cleared while a read was under way). In the second case the
+            // cursors are deleted and the profile is read again from the start, once.
+            const published = this._profile.value;
+            if (published === null || Model.findBusinessLink(published, businessId) === null) {
+                await cache.resetProfileCursors(containerName);
+                await this.profileSyncIn(ProtoMap.buildProfileSyncOutRequest(await cache.readProfileCursors(containerName), joinBusinessId), await this.requireProfileAuthTokens());
+            }
+        }
+        // A join that still leaves no link after the profile was read again from the start is the
+        // server contradicting itself, and retrying would not fix it.
         const joined = this._profile.value;
         const joinedLink = joined === null ? null : Model.findBusinessLink(joined, businessId);
         if (joinedLink === null)
@@ -677,9 +767,30 @@ class Model {
         const containerName = this.getProfileContainerName();
         if (containerName === null)
             return;
-        this.publishProfile(await Model.getCache().readProfile(containerName));
+        await this.publishProfileFromStore(containerName);
         await this.readProfilePages(containerName, firstRequest, firstAuthTokens, () => Model.getService().profileSyncOut(firstRequest, firstAuthTokens));
     }
+    // Reads what changed in the profile since the cursors the container holds, as a sign in does, but
+    // without publishing the stored profile first.
+    async syncProfile(containerName) {
+        const request = ProtoMap.buildProfileSyncOutRequest(await Model.getCache().readProfileCursors(containerName));
+        const authTokens = await this.requireProfileAuthTokens();
+        await this.readProfilePages(containerName, request, authTokens, () => Model.getService().profileSyncOut(request, authTokens));
+    }
+    // The user the profile container stores, or null when it holds none
+    async readStoredUser(containerName) {
+        const stored = await Model.getCache().readProfile(containerName);
+        if (stored === null || this._subjectId === null)
+            return null;
+        return ProtoMap.buildProfile(this._subjectId, stored)?.user ?? null;
+    }
+    // Sends user over the one the server has, and stores and publishes the answer, which is the first
+    // page of a profile read.
+    async sendUserUpdate(containerName, user) {
+        const request = ProtoMap.buildUserRequest(ProtoMap.buildUpdateUser(user), await Model.getCache().readProfileCursors(containerName));
+        const authTokens = await this.requireProfileAuthTokens();
+        await this.readProfilePages(containerName, ProtoMap.getUserRequestSyncOutRequest(request), authTokens, () => Model.getService().updateUser(request, authTokens));
+    }
     // The sign-up call. Its answer is the first page of a profile read, which readProfilePages
     // continues if the page is full. The id saved for the sign up is deleted once that page is stored.
     async createProfileOnServer(request, authTokens) {
@@ -725,8 +836,9 @@ class Model {
             authTokens = ProtoMap.refreshAuthTokens(authTokens, ProtoMap.getResponseAuthTokens(page));
             page = await Model.getService().profileSyncOut(request, authTokens);
         }
+        this._profileReadAt = Date.now();
         if (changeCount !== 0)
-            this.publishProfile(await cache.readProfile(containerName));
+            await this.publishProfileFromStore(containerName);
         // After a sign up the User exists whatever became of the join, so what came back is kept and
         // published before this throws
         Model.requireJoinedBusiness(joinBusinessId, hasJoinedLink, hasJoinedBusiness);
@@ -752,7 +864,7 @@ class Model {
             : hasBusinessLink
                 ? "Business"
                 : "BusinessLink";
-        throw new InternalServerException(`A join of business ${joinBusinessId} was answered with no ${missing}`);
+        throw new JoinNotAnsweredException(`A join of business ${joinBusinessId} was answered with no ${missing}`);
     }
     // Stores the tokens a call received in the container the call was about: a profile call's tokens
     // in the subject's profile container, a business call's in that business's container. The caller
@@ -825,6 +937,9 @@ class Model {
     // be joined to it. A read that finds the published business is no longer open, or that the server
     // rejects, publishes null in its place. A business published from the cache counts as open only
     // once the read has ended (see _isPublishedBusinessVetted, which readJoinBusinessId checks).
+    static getProfileCursorsKey(cursors) {
+        return SyncKeys.PROFILE_SYNC_IN.map((key) => cursors.getUpdateNumber(key)).join(",");
+    }
     publishBusiness(response) {
         this.publish(Model.buildPublishable(response));
     }
@@ -843,6 +958,23 @@ class Model {
                 ? null
                 : ProtoMap.buildProfile(this._subjectId, response);
     }
+    // Publishes what the profile container stores, and notes the cursors it was read at, so that
+    // refreshProfileIfStale can tell whether the store has moved since.
+    async publishProfileFromStore(containerName) {
+        const cache = Model.getCache();
+        const cursorsKey = Model.getProfileCursorsKey(await cache.readProfileCursors(containerName));
+        this.publishProfile(await cache.readProfile(containerName));
+        this._publishedProfileCursors = cursorsKey;
+    }
+    // The read behind refreshProfileIfStale
+    async refreshProfile() {
+        const containerName = this.requireProfileContainerName();
+        await this.syncProfile(containerName);
+        const cursors = await Model.getCache().readProfileCursors(containerName);
+        if (Model.getProfileCursorsKey(cursors) !== this._publishedProfileCursors)
+            await this.publishProfileFromStore(containerName);
+        return true;
+    }
     // #endregion
     static getService() {
         const service = Model._service;
@@ -859,5 +991,10 @@ class Model {
 }
 Model._service = null;
 Model._cache = null;
+Model._lock = new InMemoryLock();
 Model._instance = null;
 export default Model;
+// A join the server answered with no link or business. It is a 500 like any other fault of the
+// server. requireBusinessLink catches it to read the profile again from the start.
+class JoinNotAnsweredException extends InternalServerException {
+}

package/dist/SyncCache.d.ts

@@ -15,6 +15,7 @@ export default class SyncCache {
     readProfile(containerName: string): Promise<proto_ProfileSyncOutResponse | null>;
     readDeletedProfile(containerName: string): Promise<proto_ProfileSyncOutResponse | null>;
     readProfileCursors(containerName: string): Promise<SyncState>;
+    resetProfileCursors(containerName: string): Promise<void>;
     writeProfile(containerName: string, response: proto_ProfileSyncOutResponse): Promise<number>;
     readAuthTokens(containerName: string): Promise<AuthTokens | null>;
     writeAuthTokens(containerName: string, authTokens: AuthTokens): Promise<void>;
@@ -30,7 +31,8 @@ export default class SyncCache {
     deleteBusiness(containerName: string): Promise<void>;
     deletePartyPreferences(containerName: string): Promise<number>;
     writeMessages(containerName: string, messages: ReadonlyArray<proto_Message>): Promise<number>;
-    private readAll;
+    private readDecoded;
+    private decode;
     private writeOwnMessage;
     private writeBlobs;
     private write;

package/dist/SyncCache.js

@@ -1,4 +1,5 @@
 import { Constants as proto_Constants } from "./generated/Constants";
+import { StoreCorruptException } from "./Exceptions";
 import Ids from "./Ids";
 import * as ProtoMap from "./ProtoMap";
 import * as SyncKeys from "./SyncKeys";
@@ -16,7 +17,8 @@ import * as SyncKeys from "./SyncKeys";
 //   readOrders and readPartyPreferences leave them out.
 // - A cursor is a blob per entity type (its eTag is the cursor). It is not derived from the
 //   entities, because tombstones and this client's own changes would move it. It rises only with
-//   a page of a read, in that page's batch, and the store keeps the greater.
+//   a page of a read, in that page's batch, and the store keeps the greater. Only
+//   resetProfileCursors lowers one.
 export default class SyncCache {
     constructor(_database) {
         this._database = _database;
@@ -26,7 +28,7 @@ export default class SyncCache {
     // written. Tombstones are included as sent: a deleted entity carries what it was, or only its header
     // for an item. Code that builds on this must leave tombstones out, except for the order of a message.
     async readBusiness(containerName) {
-        return ProtoMap.businessResponseFromBlobs(await this.readAll(containerName));
+        return this.readDecoded(containerName, ProtoMap.businessResponseFromBlobs);
     }
     // The cursors the next read sends: the highest update number of each entity type that a page of a
     // read brought, tombstones included, or zero for a type none has brought. A page is a response to a
@@ -53,19 +55,28 @@ export default class SyncCache {
     // The tombstones cached for one business, as a response, each as stored and as the server sent it.
     // Null when there are none. The entities a deleted entity owned are tombstones too.
     async readDeletedBusiness(containerName) {
-        return ProtoMap.deletedBusinessResponseFromBlobs(await this.readAll(containerName));
+        return this.readDecoded(containerName, ProtoMap.deletedBusinessResponseFromBlobs);
     }
     // The same for one profile: the customer, the businesses they may reach, and the link to each.
     async readProfile(containerName) {
-        return ProtoMap.profileResponseFromBlobs(await this.readAll(containerName));
+        return this.readDecoded(containerName, ProtoMap.profileResponseFromBlobs);
     }
     // The tombstones of a profile, as readDeletedBusiness returns those of a business.
     async readDeletedProfile(containerName) {
-        return ProtoMap.deletedProfileResponseFromBlobs(await this.readAll(containerName));
+        return this.readDecoded(containerName, ProtoMap.deletedProfileResponseFromBlobs);
     }
     async readProfileCursors(containerName) {
         return this.readCursors(containerName, SyncKeys.PROFILE_SYNC_IN);
     }
+    // Deletes the profile cursors, so the next read asks for the whole profile. Use it when the
+    // container lacks an entity that its cursors are past, which no read would send again. The
+    // entities, tokens and saved user id stay, and a repeated entity changes nothing.
+    async resetProfileCursors(containerName) {
+        await this.write(containerName, {
+            blobs: NO_BLOBS,
+            deletedIds: SyncKeys.PROFILE_SYNC_IN.map((key) => Ids.getSyncCursorBlobId(key)),
+        });
+    }
     // One page of a profile read, or the answer to a sign up or an update, which is the first page of
     // one. See writeBusiness.
     async writeProfile(containerName, response) {
@@ -77,7 +88,7 @@ export default class SyncCache {
         const blob = await (await this.getContainer(containerName)).read(Ids.AUTH_TOKENS_BLOB_ID);
         if (blob === null)
             return null;
-        return ProtoMap.authTokensFromBytes(blob.bytes);
+        return this.decode(containerName, () => ProtoMap.authTokensFromBytes(blob.bytes));
     }
     // Written without comparison, unlike everything else here: a reissued token is not a later version of
     // the old one, so the last one written wins. Stores only what this server issued - see
@@ -91,7 +102,7 @@ export default class SyncCache {
         const blob = await (await this.getContainer(containerName)).read(Ids.USER_ID_BLOB_ID);
         if (blob === null)
             return null;
-        return ProtoMap.userIdFromBytes(blob.bytes);
+        return this.decode(containerName, () => ProtoMap.userIdFromBytes(blob.bytes));
     }
     // Saves the id before the sign up is sent, and it stays until deleteUserId deletes it. It replaces
     // an id saved before.
@@ -107,14 +118,14 @@ export default class SyncCache {
     // are deleted messages, which readDeletedOrders returns. Nothing here records which caller that was
     // or detects a change of caller. See THE MESSAGES OF A BUSINESS ARE NOT PUBLIC.
     async readOrders(containerName) {
-        return ProtoMap.orderMessagesFromBlobs(await this.readAll(containerName));
+        return this.readDecoded(containerName, ProtoMap.orderMessagesFromBlobs);
     }
     // The orders the business has completed, by fulfilling or cancelling. The merchant app completes an
     // order by deleting its message, so each is a tombstone. A server sends these whole, because the
     // customer is shown the order afterwards. Each is returned as stored and as sent. A tombstone with
     // no order in it is not included.
     async readDeletedOrders(containerName) {
-        return ProtoMap.deletedOrderMessagesFromBlobs(await this.readAll(containerName));
+        return this.readDecoded(containerName, ProtoMap.deletedOrderMessagesFromBlobs);
     }
     // The cursor a sync in sends: how far reads of this container have got with this customer's
     // messages, party preferences and orders alike. It is the cursor the next read sends. The answer
@@ -131,7 +142,7 @@ export default class SyncCache {
     // per business, so two would mean two callers share the container, the open question described
     // for readOrders.
     async readPartyPreferences(containerName) {
-        return ProtoMap.partyPreferencesMessageFromBlobs(await this.readAll(containerName));
+        return this.readDecoded(containerName, ProtoMap.partyPreferencesMessageFromBlobs);
     }
     async writePartyPreferences(containerName, partyPreferences) {
         return this.writeOwnMessage(containerName, partyPreferences, ProtoMap.partyPreferencesToBlob);
@@ -173,8 +184,21 @@ export default class SyncCache {
     async writeMessages(containerName, messages) {
         return this.writeRead(containerName, ProtoMap.messagesToCacheWrite(messages), SyncKeys.BUSINESS_SYNC_IN, (cursors) => ProtoMap.raiseMessageCursors(cursors, messages));
     }
-    async readAll(containerName) {
-        return (await this.getContainer(containerName)).readAll();
+    // Reads every blob of the container and decodes them with decoder. Throws StoreCorruptException
+    // if decoder throws.
+    async readDecoded(containerName, decoder) {
+        const blobs = await (await this.getContainer(containerName)).readAll();
+        return this.decode(containerName, () => decoder(blobs));
+    }
+    // Anything thrown while reading what the store holds means the store holds something unreadable,
+    // since the same bytes decoded when they were written.
+    decode(containerName, decoder) {
+        try {
+            return decoder();
+        }
+        catch (error) {
+            throw new StoreCorruptException(containerName, error);
+        }
     }
     // Stores a message the caller built, not one a response carried, versioned from the copy this
     // container stores. A message this client amended has no update number, so it is stored at that of
@@ -191,8 +215,8 @@ export default class SyncCache {
     // One transaction per call, so an interrupted write can be repeated and never leaves the cache
     // partly written. The store's count covers only what it stored: a blob that the store already holds
     // a copy of that is as new (a tombstone too) is not stored and not counted. A delete has nothing
-    // to compare, so the ids are counted instead. The only delete is a caller's own - see
-    // deletePartyPreferences.
+    // to compare, so the ids are counted instead. A delete is a caller's own: see
+    // deletePartyPreferences, deleteUserId and resetProfileCursors.
     async write(containerName, cacheWrite) {
         const blobs = cacheWrite.blobs;
         const deletedIds = cacheWrite.deletedIds;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { default as Model } from "./Model";
 export { default as Database } from "./Database";
 export type { Container, StoredBlob } from "./Database";
+export { default as Lock } from "./Lock";
+export { default as InMemoryLock } from "./InMemoryLock";
 export { default as Service } from "./Service";
 export * as ContainerNames from "./ContainerNames";
 export { buildAuthTokensBytes } from "./ProtoMap";
@@ -45,8 +47,8 @@ export { default as ShoppingList, ItemChange, ShoppingListItem } from "./Shoppin
 export { default as Tax, TaxAmount } from "./Tax";
 export { default as WorkingDays, WorkingHours, WorkingHoursRange } from "./WorkingDays";
 export * from "./Enums";
-export { Constants, MERABILLS_ONLINE_PRICE_LIST_ID, buildPriceListId } from "./Constants";
+export { Constants, MAX_PROFILE_STALENESS_MS, MERABILLS_ONLINE_PRICE_LIST_ID, buildPriceListId, } from "./Constants";
 export { default as Ids } from "./Ids";
-export { IllegalOperationException, InvalidArgumentException } from "./Exceptions";
+export { IllegalOperationException, InvalidArgumentException, StoreCorruptException, } from "./Exceptions";
 export { BadRequestException, ConflictException, InternalServerException, MethodNotAllowedException, NetworkConnectionException, NotFoundException, ServiceException, ServiceUnavailableException, UnauthorizedException, UpgradeRequiredException, } from "./ServiceExceptions";
 export { default as MockDatabase, MockContainer } from "./MockDatabase";

package/dist/index.js

@@ -6,6 +6,7 @@
 // - TaxHelper, which does tax arithmetic in scaled values. A UI reads a tax off a ShoppingListItem,
 //   ShoppingList or CartLine.
 export { default as Model } from "./Model";
+export { default as InMemoryLock } from "./InMemoryLock";
 export * as ContainerNames from "./ContainerNames";
 export { buildAuthTokensBytes } from "./ProtoMap";
 // The Service implementation that reaches a real server, and its routes. A caller using plain
@@ -51,12 +52,13 @@ export { default as WorkingDays, WorkingHours, WorkingHoursRange } from "./Worki
 // storefront sells from is exported because a UI that builds a cart must name it. Catalog.priceList
 // is null until the catalog has arrived, and when the response did not carry that list.
 export * from "./Enums";
-export { Constants, MERABILLS_ONLINE_PRICE_LIST_ID, buildPriceListId } from "./Constants";
+export { Constants, MAX_PROFILE_STALENESS_MS, MERABILLS_ONLINE_PRICE_LIST_ID, buildPriceListId, } from "./Constants";
 export { default as Ids } from "./Ids";
-// Failures. The two in Exceptions.ts are programming errors. The rest are what a call fails with
-// and are meant to be caught: ServiceException for an error response from the server,
-// NetworkConnectionException for a call that got no response.
-export { IllegalOperationException, InvalidArgumentException } from "./Exceptions";
+// Failures. Two in Exceptions.ts are programming errors. StoreCorruptException means the store
+// holds data that cannot be read, and a caller recovers by deleting the store. The rest are what a
+// call fails with and are meant to be caught: ServiceException for an error response from the
+// server, NetworkConnectionException for a call that got no response.
+export { IllegalOperationException, InvalidArgumentException, StoreCorruptException, } from "./Exceptions";
 export { BadRequestException, ConflictException, InternalServerException, MethodNotAllowedException, NetworkConnectionException, NotFoundException, ServiceException, ServiceUnavailableException, UnauthorizedException, UpgradeRequiredException, } from "./ServiceExceptions";
 // The mock database: a Database over a Map, so a caller can pair it with any Service. MockService
 // and MockData (a Service and its data, answering out of memory) live in test/ only - see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peabody-soft/mbs-model-ts",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "MeraBills storefront client-side model (TypeScript)",
   "author": "Peabody Soft",
   "license": "AGPL-3.0-or-later",