@peabody-soft/mbs-model-ts 1.6.0 → 1.7.1

package/dist/SyncCache.js

@@ -2,18 +2,19 @@ import { Constants as proto_Constants } from "./generated/Constants";
 import Ids from "./Ids";
 import * as ProtoMap from "./ProtoMap";
 import * as SyncKeys from "./SyncKeys";
-// What the server has already said, so the next call asks only for what changed. A read cache:
-// everything in it came from a response, so giving up a container costs one refetch.
-// It does not write through or sync. The caller calls the Service, does the paging and says which
-// writes are reads. It holds only the wire, which ProtoMap reads. See SYNC LAYER in ../Prompt.txt.
-// - One response is one write. A tombstone is a blob nothing older replaces. The server sends one
-//   for every deleted entity, children included, so the cache never infers a deletion.
+// What the server has already sent, so the next call can ask only for what changed. A read cache:
+// everything in it came from a response, so dropping a container costs one refetch.
+// It does not write through or sync. The caller calls the Service, does the paging, and chooses
+// which writes are reads. It holds only wire data, which ProtoMap reads. See SYNC LAYER in
+// ../Prompt.txt.
+// - One response is one write. A tombstone is a blob that no older blob replaces. The server sends
+//   one for every deleted entity, children included, so the cache never infers a deletion.
 // - Tombstones are stored as sent, so a deleted message keeps its order (a completed order is a
-//   deleted message). readDeletedBusiness, readDeletedProfile and readDeletedOrders answer them.
+//   deleted message). readDeletedBusiness, readDeletedProfile and readDeletedOrders return them.
 //   readOrders and readPartyPreferences leave them out.
-// - A cursor is a blob per entity type (its eTag is the cursor), not derived from the entities,
-//   since 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 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.
 export default class SyncCache {
     constructor(_database) {
         this._database = _database;
@@ -21,7 +22,7 @@ export default class SyncCache {
     }
     // Everything cached for one business, as the response that carried it, or null before anything is
     // written. Tombstones are included as sent: a deleted entity carries what it was, or only its header
-    // for an item. Whatever builds on this must leave tombstones out, except for the order of a message.
+    // 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));
     }
@@ -35,19 +36,20 @@ export default class SyncCache {
     // copy wins and a repeated page changes nothing. A tombstone wins over the copies of what it deleted,
     // since a delete is a later write. The cursors the page raises go in the same batch, so they cannot
     // get ahead of their entities and an interrupted read resumes from its last page.
-    // Answers how many blobs it stored, which tells a caller whether the response changed anything and
-    // what to publish on. The store keeps a blob only when its eTag is later, so a response can be
-    // rejected in full, and a rejected one cannot change what a later read answers - see MODEL.
+    // Returns how many blobs it stored, so a caller can tell whether the response changed anything and
+    // needs publishing. The store keeps a blob only when its eTag is later, so it can reject a
+    // response in full. A rejected response leaves the cache unchanged - see MODEL.
     async writeBusiness(containerName, response) {
         return this.writeRead(containerName, ProtoMap.businessResponseToCacheWrite(response), SyncKeys.BUSINESS_SYNC_IN, (cursors) => ProtoMap.raiseBusinessCursors(cursors, response));
     }
-    // Stores what a business response brought that was not read. It moves no cursor, since what is merged
-    // here is not something this container was read for. Otherwise the same as writeBusiness.
+    // Stores a business response that is not a page of a read of this container, for example one merged
+    // in from another container. It moves no cursor, because this container was not read for what the
+    // response holds. Otherwise the same as writeBusiness.
     async storeBusiness(containerName, response) {
         return this.write(containerName, ProtoMap.businessResponseToCacheWrite(response));
     }
     // 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 of their own.
+    // Null when there are none. The entities a deleted entity owned are tombstones too.
     async readDeletedBusiness(containerName) {
         return ProtoMap.deletedBusinessResponseFromBlobs(await this.readAll(containerName));
     }
@@ -55,7 +57,7 @@ export default class SyncCache {
     async readProfile(containerName) {
         return ProtoMap.profileResponseFromBlobs(await this.readAll(containerName));
     }
-    // The tombstones of a profile, as readDeletedBusiness answers those of a business.
+    // The tombstones of a profile, as readDeletedBusiness returns those of a business.
     async readDeletedProfile(containerName) {
         return ProtoMap.deletedProfileResponseFromBlobs(await this.readAll(containerName));
     }
@@ -66,8 +68,9 @@ export default class SyncCache {
     async writeProfile(containerName, response) {
         return this.writeRead(containerName, ProtoMap.profileResponseToCacheWrite(response), SyncKeys.PROFILE_SYNC_IN, (cursors) => ProtoMap.raiseProfileCursors(cursors, response));
     }
-    // What a call that is not a read answered with (a sign up, an update). It is a change this client
-    // made, so it moves no cursor and the next read brings it back. Otherwise the same as writeProfile.
+    // Stores the response to a call that is not a read (a sign up, an update). It holds a change this
+    // client made, so it moves no cursor and the next read brings it back. Otherwise the same as
+    // writeProfile.
     async storeProfile(containerName, response) {
         return this.write(containerName, ProtoMap.profileResponseToCacheWrite(response));
     }
@@ -80,22 +83,22 @@ export default class SyncCache {
         return 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 latest wins. Keeps only what this server issued - see ProtoMap.authTokensToBlob
-    // for why the authentication token is dropped.
+    // the old one, so the last one written wins. Stores only what this server issued - see
+    // ProtoMap.authTokensToBlob for why the authentication token is dropped.
     async writeAuthTokens(containerName, authTokens) {
         await this.writeBlobs(containerName, [ProtoMap.authTokensToBlob(authTokens)]);
     }
-    // The open orders of whoever the written responses answered, since a server sends a caller only their
-    // own messages. Open means the business has not completed them; completed ones are deleted messages,
-    // which readDeletedOrders answers. Nothing here records which caller that was or notices when it
-    // changes. See THE MESSAGES OF A BUSINESS ARE NOT PUBLIC.
+    // The open orders of the caller whose responses were written here, because a server sends a caller
+    // only their own messages. An open order is one the business has not completed. Completed orders
+    // 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));
     }
     // 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, but one a server sends whole because the
-    // customer is shown the order afterwards. Each is as stored and as sent. A tombstone with no order is
-    // not one of them.
+    // 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));
     }
@@ -105,34 +108,37 @@ export default class SyncCache {
     async readMessageUpdateNumber(containerName) {
         return (await this.readBusinessCursors(containerName)).getUpdateNumber(proto_Constants.MESSAGE_ENTITY_TYPE_ID);
     }
-    // Refuses a message that is not an order. Only the payload says which it is, and one stored as the
-    // other would never be read back.
+    // Throws for a message that is not an order. Only the payload shows which kind a message is, and
+    // one stored as the other kind would never be read back.
     async writeOrder(containerName, order) {
         return this.writeOwnMessage(containerName, order, ProtoMap.orderToBlob);
     }
-    // The party preferences message in this container, or null when there is none. Two mean two
-    // callers, which is the same open question as the orders above.
+    // The party preferences message in this container, or null when there is none. A customer has one
+    // 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));
     }
     async writePartyPreferences(containerName, partyPreferences) {
         return this.writeOwnMessage(containerName, partyPreferences, ProtoMap.partyPreferencesToBlob);
     }
-    // Gives up everything cached for a business: entities, cursors and tokens. For when a container turns
-    // out to hold another business than the one it is named for, which can happen because a businessId is
-    // only how a business is found. Only the id of its Business tells them apart, and a cursor of one is
-    // no cursor of the other: the store keeps a blob only when its eTag is greater, so the old cursors
-    // would never be lowered and what the new business has below them would never be requested. The
-    // container is dropped here too, since this cache holds each fetched container by name.
+    // Drops everything cached for a business: entities, cursors and tokens. Use it when a container
+    // turns out to hold a different business than the one it is named for. That can happen because a
+    // businessId only locates a business. Only the id of its Business tells two businesses apart, and
+    // cursors do not carry over from one to the other: the store keeps a blob only when its eTag is
+    // greater, so the old cursors would never be lowered and what the new business has below them
+    // would never be requested. The container is also dropped from this cache's map of fetched
+    // containers.
     async deleteBusiness(containerName) {
         this._containers.delete(containerName);
         await this._database.deleteContainer(containerName);
     }
-    // Drops the party preferences message this container holds, and answers zero when there is none. It
-    // is the one delete no tombstone asked for. A cart written before anybody signed in is handed over to
-    // the container named for the membership, and the copy left behind would be read by the next anonymous
-    // visitor and the next customer to sign in - see Model.businessSyncIn. Nothing else in a container is
-    // a caller's to remove: it all came off the wire, and anything the server has not said is gone stays.
+    // Deletes the party preferences message this container holds, and returns zero when there is none.
+    // It is the only delete that no tombstone caused. A cart written before anybody signed in is handed
+    // over to the container named for the membership. The copy left behind would be read by the next
+    // anonymous visitor and the next customer to sign in - see Model.businessSyncIn. A caller deletes
+    // nothing else from a container: it all came off the wire, and anything the server has not
+    // reported as deleted stays.
     async deletePartyPreferences(containerName) {
         const partyPreferences = await this.readPartyPreferences(containerName);
         if (partyPreferences === null)
@@ -142,35 +148,36 @@ export default class SyncCache {
             deletedIds: [ProtoMap.getMessageId(partyPreferences)],
         });
     }
-    // The messages a sync in response carried, in one batch, so the cache cannot hold a pushed order
-    // without the party preferences message it emptied. Tombstones are included, as for any entity array
-    // off the wire. This stores a push's own messages once the server has echoed them with real update
-    // numbers. It checks no payload type, unlike writeOrder and writePartyPreferences: those take a
-    // message the caller was given, where an order stored as party preferences is a mistake worth
-    // catching, and here the response is the authority. It moves no cursor, since this client made the
-    // change and the next read brings the same messages back.
+    // Stores the messages a sync in response carried, in one batch, so the cache cannot hold a pushed
+    // order without the party preferences message it emptied. Tombstones are included, as for any
+    // entity array off the wire. This stores a push's own messages once the server has echoed them with
+    // real update numbers. It checks no payload type, unlike writeOrder and writePartyPreferences.
+    // Those take a message from the caller, where storing an order as party preferences is a mistake
+    // worth catching. Here the response is taken as correct. It moves no cursor, because this client
+    // made the change and the next read brings the same messages back.
     async writeMessages(containerName, messages) {
         return this.write(containerName, ProtoMap.messagesToCacheWrite(messages));
     }
     async readAll(containerName) {
         return (await this.getContainer(containerName)).readAll();
     }
-    // A message the caller holds rather than one a response carried, versioned from what this container
-    // holds of it. One this client amended has no update number, so it is stored at that of the copy it
-    // amends - see ProtoMap.messageToBlob
+    // Stores a message the caller holds, not one a response carried, versioned from the copy this
+    // container holds. A message this client amended has no update number, so it is stored at that of
+    // the copy it amends - see ProtoMap.messageToBlob
     async writeOwnMessage(containerName, message, toBlob) {
         const held = await (await this.getContainer(containerName)).read(ProtoMap.getMessageId(message));
         return this.writeBlobs(containerName, [toBlob(message, held?.eTag ?? null)]);
     }
-    // For writers that store one thing and delete nothing (a credential or a single message), since no
-    // tombstone arrives for either on its own
+    // For writers that store one blob and delete nothing (a credential or a single message), because no
+    // tombstone comes with either
     async writeBlobs(containerName, blobs) {
         return this.write(containerName, { blobs: blobs, deletedIds: NO_DELETES });
     }
-    // One transaction per call, so an interrupted write repeats instead of leaving the cache part written.
-    // The store's count covers only what it stored: a blob it 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.
+    // 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.
     async write(containerName, cacheWrite) {
         const blobs = cacheWrite.blobs;
         const deletedIds = cacheWrite.deletedIds;
@@ -179,10 +186,11 @@ export default class SyncCache {
         const storedCount = await (await this.getContainer(containerName)).write(blobs, deletedIds);
         return storedCount + deletedIds.length;
     }
-    // A page of a read: what it brought and the cursors it moved, in one batch. The count is what the
-    // page's entities changed, so the cursors are subtracted. The store keeps a cursor only where it is
-    // greater, and each moved one is greater than the one read, so it stores the moved cursors or fewer,
-    // when another writer moved one first. That is why the count is clamped at zero.
+    // Stores a page of a read: its entities and the cursors it moved, in one batch. The count is the
+    // number of entities the page changed, so the moved cursors are subtracted from the store's count.
+    // The store keeps a cursor only if it is greater. Each moved cursor is greater than the one read,
+    // so the store keeps all of them, or fewer when another writer moved one first. That is why the
+    // count is clamped at zero.
     async writeRead(containerName, cacheWrite, cursorKeys, raiseCursors) {
         const cursors = await this.readCursors(containerName, cursorKeys);
         const movedKeys = raiseCursors(cursors);
@@ -198,16 +206,16 @@ export default class SyncCache {
         const blobs = await Promise.all(keys.map((key) => container.read(Ids.getSyncCursorBlobId(key))));
         return ProtoMap.cursorsFromBlobs(keys, blobs);
     }
-    // Held by name, so each container is fetched once. The promise is held, so two calls arriving
-    // together share one fetch. Whoever deletes a container from the store must drop it here too, since
-    // nothing here can tell that it no longer matches the store.
+    // Containers are held by name, so each is fetched once. The promise is held, so two calls arriving
+    // together share one fetch. Code that deletes a container from the store must also drop it here,
+    // because this cache cannot detect that the store no longer has it.
     getContainer(containerName) {
         const held = this._containers.get(containerName);
         if (held !== undefined)
             return held;
         const pending = this._database.getContainer(containerName);
         this._containers.set(containerName, pending);
-        // A failure is not remembered, or one unlucky read would poison this name for as long as this cache lives
+        // Forget a failed fetch, or one failure would make this name fail for as long as this cache lives
         void pending.catch(() => {
             if (this._containers.get(containerName) === pending)
                 this._containers.delete(containerName);

package/dist/SyncKeys.js

@@ -1,7 +1,7 @@
 import { Constants as proto_Constants } from "./generated/Constants";
-// Which update numbers a SyncState keeps, and which entity type counts under which key. Kept here
-// since these are facts about the protocol, not about counting.
-// A state refuses keys outside its set because Business arrives from both sync outs with
+// Which update numbers a SyncState keeps, and which key each entity type counts under. These are
+// facts about the protocol, so they are kept here and not in SyncState.
+// A state throws for keys outside its set because Business arrives from both sync outs with
 // unrelated update numbers, which must never mix.
 // The cursors a business sync in sends: the five cursor fields of a BusinessSyncOutRequest (the
 // business, its attachments, configurations, messages and items).
@@ -32,8 +32,8 @@ export const ITEM_ENTITY_TYPE_IDS = Object.freeze([
     proto_Constants.PRICE_ENTITY_TYPE_ID,
     proto_Constants.PRICE_LIST_ENTITY_TYPE_ID,
 ]);
-// The key an entity counts under: one update number per table, not per class - a product's number
-// is the shared item number.
+// The key an entity type counts under. There is one update number per table, so a product's
+// number is the shared item number.
 export function keyOf(entityTypeId) {
     return ITEM_ENTITY_TYPE_IDS.includes(entityTypeId)
         ? proto_Constants.ITEM_ENTITY_TYPE_ID

package/dist/SyncState.js

@@ -1,19 +1,27 @@
 import { InvalidArgumentException } from "./Exceptions";
 import * as SyncKeys from "./SyncKeys";
-// How far one read has got: an update number per entity type, computed from what arrives and sent back on the next call, which makes a read incremental. One class for both directions; only the keys differ.
-// Held in memory. SyncCache persists it, one blob per entity type, so a new session asks only for what changed. A container with none asks from zero and is sent what it already holds, which costs bandwidth only, since the store keeps a blob only when its eTag is greater. "In" and "out" are relative to this store, the opposite of the wire's calls.
+// How far one read has got: an update number per entity type. It is computed from what arrives and
+// sent with the next call, which makes a read incremental. One class serves both directions; only
+// the keys differ.
+// Held in memory. SyncCache persists it, one blob per entity type, so a new session asks only for
+// what changed. A container with no stored state asks from zero and is sent what it already holds.
+// That costs bandwidth only, because the store keeps a blob only when its eTag is greater. "In" and
+// "out" are relative to this store, the opposite of the wire's calls.
 export default class SyncState {
-    // The keys this state accepts, which is the whole difference between a business state and a profile one. Others are refused (see SyncKeys).
+    // The keys this state accepts. This is the only difference between a business state and a
+    // profile state. Other keys throw (see SyncKeys).
     constructor(_keys) {
         this._keys = _keys;
         this._updateNumbers = new Map();
     }
-    // Zero (an unset key) asks the server for everything of that type - what a first read sends for every key.
+    // Zero (an unset key) requests everything of that type from the server. A first read sends zero
+    // for every key.
     getUpdateNumber(entityTypeId) {
         return this._updateNumbers.get(this.checkKey(entityTypeId)) ?? 0n;
     }
-    // Raises the cursor for this entity type and reports whether it moved. Tombstones count too, since skipping one would refetch it for ever.
-    // A lower number is ignored as stale or redelivered.
+    // Raises the cursor for this entity type and returns whether it moved. Tombstones count too,
+    // because skipping one would refetch it for ever.
+    // A number that is not higher is ignored as stale or redelivered.
     raiseUpdateNumber(entityTypeId, updateNumber) {
         const key = this.checkKey(entityTypeId);
         if (updateNumber <= (this._updateNumbers.get(key) ?? 0n))

package/dist/Tax.js

@@ -5,12 +5,12 @@ import { taxRateFromScaledValue } from "./Constants";
 //
 // Taxes are included in the prices a customer sees: a product's in its package prices, the
 // delivery charge's in the charge. A shopping list item stores its price without taxes, so
-// CartEditor takes them out on the way in and ShoppingListItem.unitPriceWithTaxes puts them back
-// for display. A Tax holds no amount. Only a line item knows one.
+// CartEditor takes them out on the way in and ShoppingListItem.unitPriceWithTaxes adds them back
+// for display. A Tax holds no amount. The amounts are on a line item (ShoppingListItem.taxAmounts).
 export default class Tax {
     // For ProtoMap, which sees a rate still multiplied by Constants.TAX_RATE_FACTOR. The wire carries
-    // a tax as its raw code, which means something only within a country (that of the business the
-    // tax is on), so the type is made here from the two, as Java TaxType.createId does.
+    // a tax as its raw code, which is unique only within a country (that of the business the tax is
+    // on), so the type is made here from the two, as Java TaxType.createId does.
     static fromScaledValues(countryCode, taxCode, scaledRate) {
         return new Tax(createTaxType(countryCode, taxCode), taxRateFromScaledValue(scaledRate));
     }
@@ -22,8 +22,8 @@ export default class Tax {
         return this._type;
     }
     // The country this tax belongs to, ISO 3166-1 numeric. A TaxType value is Java
-    // TaxType.createId(country, taxCode), with the country in its high bits, so the country comes
-    // out of the value itself. Zero for TaxType.UNSPECIFIED_TAX_TYPE, as no country's code is zero.
+    // TaxType.createId(country, taxCode), with the country in its high bits, so the country can be
+    // read from the value itself. Zero for TaxType.UNSPECIFIED_TAX_TYPE, as no country's code is zero.
     get countryCode() {
         return countryCodeOf(this._type);
     }
@@ -36,9 +36,9 @@ export default class Tax {
         return this._rate;
     }
 }
-// How much one type of tax comes to across a shopping list: the line a bill shows for it, "GST
-// 5.25". Several taxes of one type, on one item or on many, are added into one. Always included in
-// the list's total, never an extra on top.
+// The total of one type of tax across a shopping list: the line a bill shows for it, "GST 5.25".
+// Several taxes of one type, on one item or on many, are added into one. It is already part of the
+// list's total and is not added to it.
 export class TaxAmount {
     constructor(_type, _amount) {
         this._type = _type;
@@ -47,7 +47,8 @@ export class TaxAmount {
     get type() {
         return this._type;
     }
-    // Zero is possible (a list of free items has taxes and owes none), and a bill shows no line for it
+    // Zero is possible (a list of free items has taxes but none are due), and a bill shows no line
+    // for it
     get amount() {
         return this._amount;
     }

package/dist/TaxHelper.js

@@ -10,11 +10,12 @@ import { taxRateToScaledValue } from "./Constants";
 // (5% is 500). Floating point would round some taxes the other way. Amounts are bigint because one
 // can reach 2^44, and multiplying by a rate overflows 2^53.
 // A tax is the tax base times the rate, divided by TAX_RATE_FACTOR and rounded half up (as
-// Math.round). Each tax is rounded on its own, as each is shown and paid on its own.
+// Math.round). Each tax is rounded separately, because each is shown and paid separately.
 class TaxHelper {
     // The rates of these taxes as the arithmetic below takes them: scaled, in the same order. A rate
-    // not greater than zero is no tax. Java refuses one (validateTaxes) and drops one that arrives
-    // (getTaxCodesAndRates), so here it is zero, which keeps the taxes in step with their amounts.
+    // not greater than zero is no tax. Java rejects one (validateTaxes) and drops one that arrives
+    // (getTaxCodesAndRates), so here it becomes zero, which keeps the indexes of the taxes and their
+    // amounts aligned.
     static scaledRatesOf(taxes) {
         return taxes.map((tax) => Number.isFinite(tax.rate) && tax.rate > 0 ? taxRateToScaledValue(tax.rate) : 0);
     }
@@ -43,17 +44,17 @@ class TaxHelper {
             result += TaxHelper.calculateTaxAmount(taxBase, taxRate);
         return result;
     }
-    // The inverse of addTaxes: the amount that gives this amount with taxes. Each tax is rounded on
-    // its own, so some amounts with taxes cannot be reached. Then this answers the amount for which
-    // addTaxes comes closest (the lower one on a tie). So removeTaxes(addTaxes(amount, rates),
-    // rates) is always amount.
+    // The inverse of addTaxes: the amount that gives this amount with taxes. Each tax is rounded
+    // separately, so some amounts with taxes cannot be reached. In that case this returns the amount
+    // for which addTaxes comes closest (the lower one on a tie). So
+    // removeTaxes(addTaxes(amount, rates), rates) is always amount.
     static removeTaxes(amountWithTaxes, taxRates) {
         if (amountWithTaxes <= 0n || taxRates.length === 0)
             return amountWithTaxes;
         // Ignoring rounding, the amount with taxes is the amount multiplied by (1 + the total rate), so
         // dividing by that estimates the amount. Rounding moves each tax by at most half a unit and the
         // estimate is rounded too, so the amount is within the number of taxes of the estimate (Java
-        // looks as far). Look at every amount that close.
+        // looks as far). Check every amount within that distance.
         const estimate = TaxHelper.divideAndRound(amountWithTaxes * TaxHelper.TAX_RATE_FACTOR, TaxHelper.TAX_RATE_FACTOR + BigInt(TaxHelper.calculateTotalTaxRate(taxRates)));
         const reach = BigInt(taxRates.length);
         const first = estimate > reach ? estimate - reach : 0n;

package/dist/TaxType.js

@@ -1,11 +1,11 @@
 // The name of a tax, for a UI to show. Not part of the wire protocol: a Tax is sent as its raw tax
 // code, unique only within a country, and ProtoMap combines it with the country of the business.
 // The values are Java TaxType.createId(country, taxCode) = (country.getNumeric() << 8) | taxCode,
-// so each is globally unique. countryCodeOf and taxCodeOf take one apart.
-// Copied by hand from Java's TaxType and pinned there by TaxTypeIdsTest
-// (repository/test/com/merabills/repository/entities/helpers), which fails when GST or the country
-// shift changes or a type is added. A tax added there must be added here with the same value. This
-// library's tests pin the same values (Values.test.ts).
+// so each is globally unique. countryCodeOf and taxCodeOf split a value into its parts.
+// Copied by hand from Java's TaxType. Java's TaxTypeIdsTest
+// (repository/test/com/merabills/repository/entities/helpers) pins the values: it fails when GST or
+// the country shift changes or a type is added. A tax added there must be added here with the same
+// value. This library's tests pin the same values (Values.test.ts).
 export var TaxType;
 (function (TaxType) {
     // No country's numeric code is 0, so this cannot collide with a real type
@@ -13,7 +13,8 @@ export var TaxType;
     // India (country code 356): Goods and Services Tax (tax code 0)
     TaxType[TaxType["GST"] = 91136] = "GST";
 })(TaxType || (TaxType = {}));
-// Bits of a TaxType value the raw tax code takes, below the country - Java TaxType.COUNTRY_CODE_SHIFT
+// The low bits of a TaxType value that hold the raw tax code, below the country (Java
+// TaxType.COUNTRY_CODE_SHIFT)
 const TAX_CODE_BITS = 8;
 const TAX_CODE_MASK = (1 << TAX_CODE_BITS) - 1;
 // Java TaxType.createId: the country in the high bits, the raw tax code in the low eight. Not

package/dist/UserProfile.js

@@ -1,7 +1,7 @@
 import Entity from "./Entity";
-// The customer: whose orders and cart the business sees. Named for the database it lives in
-// (profile, not business), since a signed-out storefront has no user but still shows its catalog.
-// Holds the User message and no derived state.
+// The customer, whose orders and cart the business sees. Named for the database it lives in (the
+// profile database, not the business one), because a signed-out storefront has no user but still
+// shows its catalog. Holds the User message and no derived state.
 export default class UserProfile extends Entity {
     constructor(header, _firstName, _lastName, _mobilePhoneNumber, _addresses, _preferredLanguageCode) {
         super(header);
@@ -21,8 +21,8 @@ export default class UserProfile extends Entity {
     get mobilePhoneNumber() {
         return this._mobilePhoneNumber;
     }
-    // The customer's delivery addresses, and which is the default. Also resolves
-    // Order.deliveryAddressId, an id into this list.
+    // The customer's delivery addresses, and which is the default. Order.deliveryAddressId is an id
+    // into this list.
     get addresses() {
         return this._addresses;
     }
@@ -30,8 +30,8 @@ export default class UserProfile extends Entity {
     get preferredLanguageCode() {
         return this._preferredLanguageCode;
     }
-    // The two names with a space between them, and just the first name when there is no last name.
-    // Computed here rather than sent.
+    // The first and last names separated by a space, or the first name alone when there is no last
+    // name. Computed here, not sent.
     get formattedName() {
         if (this._lastName === null || this._lastName.length === 0)
             return this._firstName;

package/dist/WorkingDays.js

@@ -1,9 +1,10 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import { InvalidArgumentException } from "./Exceptions";
-// Days and hours a business works. Absence is the permissive value throughout: no WorkingDays
-// means every day (ALL_DAYS), and a day with no hours or ranges is worked all day.
-// Hours are minutes after local midnight in timeZone, so a caller asking about a moment reads it
-// in that zone first, as a day and a minute.
+// Days and hours a business works. Missing hours mean open: no WorkingDays means every day
+// (ALL_DAYS), and a day with no hours or ranges is worked all day. A day missing from days is not
+// worked.
+// Hours are minutes after local midnight in timeZone, so to ask about a moment, convert it to
+// that zone first, as a day and a minute.
 class WorkingDays {
     constructor(_days, _timeZone, _workingHours) {
         this._days = _days;
@@ -17,12 +18,12 @@ class WorkingDays {
     }
     // The IANA ID of the zone the hours are in, for example "Asia/Kolkata", never an abbreviation
     // like "IST". Null when none was specified (settings saved before the protocol carried one, and
-    // ALL_DAYS). The hours then cannot be placed on a clock, and only a caller that knows the
-    // business's zone can read a moment into them.
+    // ALL_DAYS). The hours then cannot be placed on a clock. Only a caller that knows the
+    // business's zone can convert a moment to a day and a minute to compare with them.
     get timeZone() {
         return this._timeZone;
     }
-    // Indexed as days is. Shorter than days, or empty, is normal. See the class comment for what a
+    // Indexed like days. Shorter than days, or empty, is normal. See the class comment for what a
     // missing entry means.
     get workingHours() {
         return this._workingHours;
@@ -37,8 +38,9 @@ class WorkingDays {
         WorkingDays.checkDayOfWeek(dayOfWeek);
         return this._days[dayOfWeek] === true;
     }
-    // The hours of a worked day, or null when that day is worked all day or not at all. A UI showing
-    // opening times tests the day first, then treats null as all day.
+    // The hours of a day, or null when the day has no hours entry or its hours cover the whole day.
+    // This does not check whether the day is worked: a UI showing opening times tests isWorkingDay
+    // first, then treats null as all day.
     getWorkingHours(dayOfWeek) {
         WorkingDays.checkDayOfWeek(dayOfWeek);
         if (dayOfWeek >= this._workingHours.length)
@@ -54,8 +56,8 @@ class WorkingDays {
             throw new InvalidArgumentException(`Not a day of the week: ${dayOfWeek}`);
     }
 }
-// What an absent WorkingDays means: the business works every day, all day long. With no hours
-// there is nothing for a zone to place, so it has none.
+// The value for an absent WorkingDays: the business works every day, all day long. It has no
+// hours, so it has no time zone.
 WorkingDays.ALL_DAYS = new WorkingDays(Object.freeze([true, true, true, true, true, true, true]), null, Object.freeze([]));
 export default WorkingDays;
 // The worked hours of a single day, as ranges.
@@ -63,8 +65,8 @@ export class WorkingHours {
     constructor(_ranges) {
         this._ranges = _ranges;
     }
-    // Ordered by openMinute, non-overlapping and non-touching: a range that closes when the next
-    // opens arrives as one unbroken range.
+    // Ordered by openMinute, non-overlapping and non-touching: ranges where one closes when the
+    // next opens arrive merged into one.
     get ranges() {
         return this._ranges;
     }
@@ -93,8 +95,8 @@ export class WorkingHoursRange {
     constructor(_openMinute, _closeMinute) {
         this._openMinute = _openMinute;
         this._closeMinute = _closeMinute;
-        // Validated on the way in: a payload that breaks protocol rules fails the sync rather than
-        // producing opening times a customer would trust as fact.
+        // Validated on construction: a payload that breaks protocol rules fails the sync instead of
+        // producing opening times that a customer would trust.
         if (!Number.isInteger(_openMinute) ||
             _openMinute < 0 ||
             _openMinute >= proto_Constants.MINUTES_PER_DAY)
@@ -104,12 +106,13 @@ export class WorkingHoursRange {
             _closeMinute > proto_Constants.MINUTES_PER_DAY)
             throw new InvalidArgumentException(`Work cannot stop at minute ${_closeMinute} having started at ${_openMinute}`);
     }
-    // Worked. From 0 to Constants.MINUTES_PER_DAY - 1.
+    // The first minute that is worked, from 0 to Constants.MINUTES_PER_DAY - 1.
     get openMinute() {
         return this._openMinute;
     }
-    // Not worked; MINUTES_PER_DAY means work stops at midnight. Always greater than openMinute. A
-    // range never spans midnight, so overnight work is two ranges on two days.
+    // The first minute that is not worked. MINUTES_PER_DAY means work stops at midnight. Always
+    // greater than openMinute. A range never spans midnight, so overnight work is two ranges on two
+    // days.
     get closeMinute() {
         return this._closeMinute;
     }

package/dist/index.js

@@ -1,7 +1,10 @@
-// The public surface of this library. Excludes Attachment (UIs get Photo instead), the sync layer's internal cursors,
-// the auth tokens (except BusinessLink.linkToken, which the protocol hands to a client), ProtoMap (the wire boundary, except buildAuthTokensBytes),
-// the scaled-value conversions of Constants.ts (every getter is already unscaled),
-// and TaxHelper (tax arithmetic in scaled values; a UI reads a tax off a ShoppingListItem, ShoppingList or CartLine).
+// The public surface of this library. Not exported:
+// - Attachment (a UI gets Photo instead) and the sync layer's internal cursors.
+// - The auth tokens, except BusinessLink.linkToken, which the server sends to a client.
+// - ProtoMap, the wire boundary, except buildAuthTokensBytes.
+// - The scaled-value conversions of Constants.ts (every getter is already unscaled).
+// - 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 * as ContainerNames from "./ContainerNames";
 export { buildAuthTokensBytes } from "./ProtoMap";
@@ -45,14 +48,14 @@ export { default as ShoppingList, ItemChange, ShoppingListItem } from "./Shoppin
 export { default as Tax, TaxAmount } from "./Tax";
 export { default as WorkingDays, WorkingHours, WorkingHoursRange } from "./WorkingDays";
 // The enums of the protocol, the limits it obeys, and how an id is read. The price list a
-// storefront sells from is exported because a UI naming it on a cart it is building needs it,
-// while Catalog.priceList is null until the catalog has arrived.
+// storefront sells from is exported because a UI that builds a cart must name it, and
+// Catalog.priceList is null until the catalog has arrived.
 export * from "./Enums";
 export { Constants, 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 anything the server refused,
-// NetworkConnectionException for a call that never got an answer.
+// 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";
 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