@peabody-soft/mbs-model-ts 1.5.0 → 1.7.0

package/dist/SyncCache.js

@@ -2,53 +2,63 @@ 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 that the next call need only ask for what has changed since. A read cache and nothing else: everything in it came out of a response, so giving a container up costs one refetch.
-// Not write through, not an identity (it stamps nothing) and not a sync - a caller calls the Service and hands the response in, which is why the paging, and which writes are reads, are the caller's. It holds the wire and only the wire, and ProtoMap reads every field. See SYNC LAYER in ../Prompt.txt.
-// One response is one write: every entity it brought, and every tombstone, is stored in a single
-// batch. A tombstone is kept, as a blob that nothing older replaces, and there is nothing to work out
-// beyond that, because the server sends a tombstone for every entity it deleted, children included - so
-// this cache never infers a deletion from another one.
-// How far a container has been read is kept too, as a blob of its own for each entity type and not
-// worked out from the entities: a read that came back with tombstones, or changes made by this
-// client, would otherwise move it. It moves only with a page of a read, in the batch of the page that
-// moved it, and only upwards: each blob is versioned by its cursor, so the store keeps the greater.
+// 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.
+// - 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.
+//   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.
 export default class SyncCache {
     constructor(_database) {
         this._database = _database;
         this._containers = new Map();
     }
-    // Everything cached for one business, as the response that carried it, or null before anything has been written for it.
-    // Tombstones are among it, as the entities they are of, and whatever builds on this has to leave them out.
+    // 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.
     async readBusiness(containerName) {
         return ProtoMap.businessResponseFromBlobs(await this.readAll(containerName));
     }
-    // The cursors the next read of this business sends, which is how far the reads of it have got: the
-    // highest update number of every entity type that a page of one brought, tombstones included, and zero for a
-    // type that none has. Nothing else moves them, so, what this client pushes is read back by the next read.
+    // 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. Only a read moves them, so
+    // the next read brings back what this client pushed.
     async readBusinessCursors(containerName) {
         return this.readCursors(containerName, SyncKeys.BUSINESS_SYNC_IN);
     }
-    // Takes in one page of a business read, one blob per entity versioned by ProtoMap.entityETag, so the later of two copies wins and a page that arrives twice changes nothing the second time.
-    // A tombstone is stored the same way, and wins over the copies of what it is of, a delete being a later write than any of them. The cursors are raised
-    // by the page, tombstones included, in the same batch: they cannot get ahead of the entities they
-    // describe, and an interrupted read repeats itself from where its last page got to.
-    // Answers how much of the page it kept - the blobs stored, which is what the container now differs
-    // by. That is how a caller tells a response that changed something from one that changed nothing,
-    // and what it publishes on: the store keeps a blob only when its eTag is later, so a response can be
-    // rejected in full, and one that was cannot change what a later read of this container answers - see MODEL.
+    // Stores one page of a business read, a blob per entity versioned by ProtoMap.entityETag, so the later
+    // 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.
     async writeBusiness(containerName, response) {
         return this.writeRead(containerName, ProtoMap.businessResponseToCacheWrite(response), SyncKeys.BUSINESS_SYNC_IN, (cursors) => ProtoMap.raiseBusinessCursors(cursors, response));
     }
-    // Takes in what a business response brought that was not read, which moves no cursor: it is how
-    // far the container has been read that this does not change, and what is merged in here is not
-    // something this container was read for. Otherwise the same as writeBusiness.
+    // 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.
     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.
+    async readDeletedBusiness(containerName) {
+        return ProtoMap.deletedBusinessResponseFromBlobs(await this.readAll(containerName));
+    }
     // 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));
     }
+    // The tombstones of a profile, as readDeletedBusiness answers those of a business.
+    async readDeletedProfile(containerName) {
+        return ProtoMap.deletedProfileResponseFromBlobs(await this.readAll(containerName));
+    }
     async readProfileCursors(containerName) {
         return this.readCursors(containerName, SyncKeys.PROFILE_SYNC_IN);
     }
@@ -56,35 +66,47 @@ 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 - which is a change this client
-    // made, and so, moves no cursor: the next read brings it back. Otherwise the same as writeProfile.
+    // 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.
     async storeProfile(containerName, response) {
         return this.write(containerName, ProtoMap.profileResponseToCacheWrite(response));
     }
-    // The credentials that sign calls about this container - the user token in a profile container, the link token in a business one - and null before the server has issued either.
+    // The credentials that sign calls about this container (the user token in a profile container, the
+    // link token in a business one), or null before the server issues either.
     async readAuthTokens(containerName) {
         const blob = await (await this.getContainer(containerName)).read(Ids.AUTH_TOKENS_BLOB_ID);
         if (blob === null)
             return null;
         return ProtoMap.authTokensFromBytes(blob.bytes);
     }
-    // Unconditional, unlike everything else here: a reissued token is not a later version of an earlier one, so there is nothing to compare and the latest wins.
-    // Keeps only what this server issued - see ProtoMap.authTokensToBlob for why the authentication token is dropped whatever is passed in.
+    // 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.
     async writeAuthTokens(containerName, authTokens) {
         await this.writeBlobs(containerName, [ProtoMap.authTokensToBlob(authTokens)]);
     }
-    // The orders of whoever the responses written here answered, since a server sends a caller only their own messages.
-    // 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 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.
     async readOrders(containerName) {
         return ProtoMap.orderMessagesFromBlobs(await this.readAll(containerName));
     }
-    // The cursor a push sends: how far the reads of this container have got with this customer's
-    // messages, party preferences and orders alike - the cursor the next read sends for them. What a push
-    // stores here does not move it, so that a change made while it was being made is not skipped.
+    // 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.
+    async readDeletedOrders(containerName) {
+        return ProtoMap.deletedOrderMessagesFromBlobs(await this.readAll(containerName));
+    }
+    // The cursor a push 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. What a push stores here
+    // does not move it, so a change made during the push is not skipped.
     async readMessageUpdateNumber(containerName) {
         return (await this.readBusinessCursors(containerName)).getUpdateNumber(proto_Constants.MESSAGE_ENTITY_TYPE_ID);
     }
-    // Refuses a message that is not an order, since only the payload says which it is: one stored as the other would never be read back.
+    // 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.
     async writeOrder(containerName, order) {
         return this.writeOwnMessage(containerName, order, ProtoMap.orderToBlob);
     }
@@ -96,23 +118,21 @@ export default class SyncCache {
     async writePartyPreferences(containerName, partyPreferences) {
         return this.writeOwnMessage(containerName, partyPreferences, ProtoMap.partyPreferencesToBlob);
     }
-    // Gives up everything cached for a business: the entities, the cursors that say how far they were read, and the tokens
-    // that were filed with them. For when what a container holds turns out to be of another business than the one it is
-    // named for - which a businessId, being only how a business is found, can come to be. It cannot be told apart from the
-    // business that the same name now finds by anything but the id of its Business, and a cursor of the one is no cursor
-    // of the other: this cache keeps a blob only when its eTag is the greater, so, the cursors of the old would never be
-    // lowered to the numbers of the new, and what the new has below them would never be asked for.
-    // The container is let go of here as well as in the store, as this cache holds each one it has fetched against its name.
+    // 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.
     async deleteBusiness(containerName) {
         this._containers.delete(containerName);
         await this._database.deleteContainer(containerName);
     }
-    // Drops the party preferences message this container holds, and answers zero when it holds none.
-    // The one delete here that no tombstone asked for, and the only reason it exists: one written
-    // before anybody signed in is handed over to the container named for the membership, and the
-    // copy left behind would otherwise be read by the next anonymous visitor and by the next customer
-    // to sign in - see Model.businessSyncIn. Nothing else about a container is a caller's to remove:
-    // everything in one came off the wire, and what the server has not said is gone stays.
+    // 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.
     async deletePartyPreferences(containerName) {
         const partyPreferences = await this.readPartyPreferences(containerName);
         if (partyPreferences === null)
@@ -122,15 +142,13 @@ export default class SyncCache {
             deletedIds: [ProtoMap.getMessageId(partyPreferences)],
         });
     }
-    // The messages a sync in response carried, in a single batch - a pushed order and the party
-    // preferences message it emptied belong in one write, so that this cache cannot come to hold the
-    // order without the emptying. Tombstones included, the same as any other entity array read off
-    // the wire: this is what a push's own messages are stored as once the server has echoed them back
-    // with real update numbers. Neither is checked against a payload type, unlike the two writers above -
-    // those are for a caller handing in a message it was given, where storing an order as party
-    // preferences would be a mistake worth catching, and this is for messages the response itself is
-    // the authority on. It moves no cursor, as it is a change that this client made: the next read
-    // brings the messages back, and what is stored here is the same, so, that changes nothing.
+    // 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.
     async writeMessages(containerName, messages) {
         return this.write(containerName, ProtoMap.messagesToCacheWrite(messages));
     }
@@ -138,22 +156,21 @@ export default class SyncCache {
         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 of its own, and is stored at the update
-    // number of the copy it amends - see ProtoMap.messageToBlob
+    // 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
     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 the writers that store one thing and delete nothing - a credential or a single message,
-    // none of which a tombstone ever arrives for on its own
+    // For writers that store one thing and delete nothing (a credential or a single message), since no
+    // tombstone arrives for either on its own
     async writeBlobs(containerName, blobs) {
         return this.write(containerName, { blobs: blobs, deletedIds: NO_DELETES });
     }
-    // One transaction per call, which is what makes an interrupted write repeat itself rather than leave the cache part written.
-    // The count the store answers with covers only what it stored: a blob it already holds a copy of that
-    // is as new, a tombstone it already holds included, is not stored, and is not counted. A delete is
-    // unconditional, so there is nothing for it to compare, and the ids are counted instead: the only
-    // delete there is is a caller's own - see deletePartyPreferences.
+    // 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.
     async write(containerName, cacheWrite) {
         const blobs = cacheWrite.blobs;
         const deletedIds = cacheWrite.deletedIds;
@@ -162,11 +179,10 @@ 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 cursors are not what the
-    // page brought, so they are not counted: the count is what the entities of it changed. The store
-    // keeps a cursor only where it is the greater, which it is of the one that was read, so what it
-    // stored of them is the cursors that moved - or fewer, where another writer moved one first, which
-    // is why the count cannot go below zero.
+    // 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.
     async writeRead(containerName, cacheWrite, cursorKeys, raiseCursors) {
         const cursors = await this.readCursors(containerName, cursorKeys);
         const movedKeys = raiseCursors(cursors);
@@ -182,8 +198,9 @@ export default class SyncCache {
         const blobs = await Promise.all(keys.map((key) => container.read(Ids.getSyncCursorBlobId(key))));
         return ProtoMap.cursorsFromBlobs(keys, blobs);
     }
-    // Held against their names, so each container is fetched once however often it is used. The promise is held rather than the container, so two calls arriving together share one fetch.
-    // A caller that deletes a container from the store gives up this cache with it: nothing here can tell that what it holds is no longer what the store would hand out.
+    // 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.
     getContainer(containerName) {
         const held = this._containers.get(containerName);
         if (held !== undefined)

package/dist/SyncKeys.js

@@ -1,10 +1,10 @@
 import { Constants as proto_Constants } from "./generated/Constants";
-// Which update numbers a SyncState keeps, and what entity type counts under which key. Kept here
-// rather than in SyncState since these are facts about the protocol, not about counting.
-// A state refuses keys outside its set on purpose: Business arrives from both sync outs with
-// unrelated update numbers, and these must never mix.
-// The cursors a business sync in sends: the business itself, its attachments, its configurations,
-// its messages and its items. These are the five cursor fields of a BusinessSyncOutRequest.
+// 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
+// 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).
 export const BUSINESS_SYNC_IN = Object.freeze([
     proto_Constants.BUSINESS_ENTITY_TYPE_ID,
     proto_Constants.ATTACHMENT_ENTITY_TYPE_ID,
@@ -12,8 +12,8 @@ export const BUSINESS_SYNC_IN = Object.freeze([
     proto_Constants.MESSAGE_ENTITY_TYPE_ID,
     proto_Constants.ITEM_ENTITY_TYPE_ID,
 ]);
-// The cursors a profile sync in sends - the three entity types Java keeps in a profile database.
-// BUSINESS also appears above, with an unrelated number in each; never mix the two.
+// The cursors a profile sync in sends: the three entity types Java keeps in a profile database.
+// BUSINESS also appears above with an unrelated number, so never mix the two.
 export const PROFILE_SYNC_IN = Object.freeze([
     proto_Constants.USER_ENTITY_TYPE_ID,
     proto_Constants.BUSINESS_ENTITY_TYPE_ID,

package/dist/SyncState.js

@@ -1,9 +1,9 @@
 import { InvalidArgumentException } from "./Exceptions";
 import * as SyncKeys from "./SyncKeys";
-// How far one read has got, as an update number per entity type computed from what arrives and sent back on the next call, which is what makes a read incremental. One class for both directions - only the keys differ.
-// A value held in memory: SyncCache keeps it between sessions, one blob per entity type, so that a new session asks only for what changed. A container that holds none asks from zero and is sent what it already holds, which costs bandwidth alone, since the store keeps a blob only when its eTag is the greater. "In" and "out" name the direction relative to this store, the opposite way round to the calls of the wire.
+// 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.
 export default class SyncState {
-    // The keys this state accepts, which is the whole difference between a business state and a profile one. Anything else is refused, because a Business arrives from both calls with an unrelated update number in each.
+    // The keys this state accepts, which is the whole difference between a business state and a profile one. Others are refused (see SyncKeys).
     constructor(_keys) {
         this._keys = _keys;
         this._updateNumbers = new Map();
@@ -12,8 +12,8 @@ export default class SyncState {
     getUpdateNumber(entityTypeId) {
         return this._updateNumbers.get(this.checkKey(entityTypeId)) ?? 0n;
     }
-    // Raises the cursor for this entity type (tombstones included - skipping one would refetch it for ever) and reports whether it moved.
-    // Numbers only ever rise; a lower one is ignored as stale or redelivered.
+    // 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.
     raiseUpdateNumber(entityTypeId, updateNumber) {
         const key = this.checkKey(entityTypeId);
         if (updateNumber <= (this._updateNumbers.get(key) ?? 0n))

package/dist/Tax.js

@@ -1,20 +1,16 @@
 import { countryCodeOf, createTaxType, taxCodeOf } from "./TaxType";
 import { taxRateFromScaledValue } from "./Constants";
-// A tax and its rate, applying to a product or a shopping-list line. Rate is exposed as a
-// percentage (18 for 18%), though the wire carries it scaled by Constants.TAX_RATE_FACTOR.
+// A tax and its rate, on a product or a shopping-list line. The rate is a percentage (18 for 18%),
+// though the wire carries it scaled by Constants.TAX_RATE_FACTOR.
 //
-// The taxes of a product are INCLUDED in the prices of its packages, and the taxes of the delivery
-// charge in the charge: nothing is added to a price a customer is shown. A shopping list item is
-// the other way round - it stores its price WITHOUT taxes and works its taxes out on top - which is
-// why a price has its taxes taken out on the way into an item (see CartEditor) and put back for
-// display (see ShoppingListItem.unitPriceWithTaxes).
-// Deliberately doesn't compute tax on an amount - only a line item knows the amount, and does
-// that itself.
+// 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.
 export default class Tax {
-    // Only ProtoMap calls this: it is the one place that 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,
-    // the same way Java TaxType.createId does.
+    // 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.
     static fromScaledValues(countryCode, taxCode, scaledRate) {
         return new Tax(createTaxType(countryCode, taxCode), taxRateFromScaledValue(scaledRate));
     }
@@ -25,10 +21,9 @@ export default class Tax {
     get type() {
         return this._type;
     }
-    // The country this tax belongs to, ISO 3166-1 numeric. A TaxType value is not a raw Java tax
-    // code - it is Java TaxType.createId(country, taxCode), the country in its high bits - so the
-    // country comes back out of the value itself rather than having to be carried alongside it.
-    // Zero for TaxType.UNSPECIFIED_TAX_TYPE, no country's code being zero.
+    // 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.
     get countryCode() {
         return countryCodeOf(this._type);
     }
@@ -41,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 a tax that
-// is included in the total the list comes to, never an extra on top of it.
+// 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.
 export class TaxAmount {
     constructor(_type, _amount) {
         this._type = _type;
@@ -52,7 +47,7 @@ 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 and owes none), and a bill shows no line for it
     get amount() {
         return this._amount;
     }

package/dist/TaxHelper.js

@@ -1,27 +1,20 @@
 import { Constants as proto_Constants } from "./generated/Constants";
 import { taxRateToScaledValue } from "./Constants";
-// The arithmetic of taxes, which is Java com.merabills.repository.entities.helpers.TaxHelper and
-// is meant to give the same answer to the unit. It is the only place in this library where a tax is
-// worked out, added to an amount or taken out of one.
+// The arithmetic of taxes, ported from Java com.merabills.repository.entities.helpers.TaxHelper to
+// give the same answer to the unit. The only place in this library that works out a tax, adds it to
+// an amount or takes it out. Not on the public surface (see index.ts): a UI reads unscaled taxes
+// off a ShoppingListItem, ShoppingList or CartLine.
 //
-// It works on SCALED values, not the unscaled numbers the rest of this library speaks: an amount is
-// a bigint multiplied by Constants.AMOUNT_FACTOR, and a rate is a number multiplied by
-// Constants.TAX_RATE_FACTOR, so 5% is 500. Java does the same in longs and ints, and rounding a
-// tax in floating point instead would round some of them the other way, which is the difference
-// between a bill that agrees with the merchant's and one that is a paisa out. A bigint rather than
-// a number because an amount can be as large as 2^44 and a product with a rate overflows 2^53.
-//
-// Only integer arithmetic is used: a tax is the tax base multiplied by the rate, and the division
-// by TAX_RATE_FACTOR and the rounding (half up, as Math.round) are the last steps. Each tax is
-// rounded on its own, as each is shown (and paid) on its own.
-//
-// Not on the public surface (see index.ts): a UI reads a tax off a ShoppingListItem, a ShoppingList
-// or a CartLine, which have done this arithmetic already, in unscaled numbers.
+// Unlike the rest of this library it works on scaled integers, as Java does: an amount is a bigint
+// multiplied by Constants.AMOUNT_FACTOR, a rate a number multiplied by Constants.TAX_RATE_FACTOR
+// (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.
 class TaxHelper {
-    // The rates of these taxes the way the arithmetic below takes them: scaled, and in the same
-    // order. A rate that is not greater than zero is no tax at all - Java refuses one (validateTaxes)
-    // and drops one that arrives (getTaxCodesAndRates) - so it is a zero here, adding and removing
-    // nothing, and the taxes stay in step with the amounts worked out for them.
+    // 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.
     static scaledRatesOf(taxes) {
         return taxes.map((tax) => Number.isFinite(tax.rate) && tax.rate > 0 ? taxRateToScaledValue(tax.rate) : 0);
     }
@@ -50,18 +43,17 @@ class TaxHelper {
             result += TaxHelper.calculateTaxAmount(taxBase, taxRate);
         return result;
     }
-    // The inverse of addTaxes: the amount the taxes with these rates have to be added to for the
-    // result to be this amount with taxes. Each tax is rounded on its own, so some amounts with taxes
-    // cannot be reached; this then answers the amount for which addTaxes comes closest (the lower
-    // one, when two are equally close). 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 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.
     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
-        // estimate the amount by dividing by that. Rounding moves each tax by at most half a unit, and
-        // the estimate is itself rounded, so the amount looked for is within the number of taxes of the
-        // estimate (Java looks as far): look at every amount that close.
+        // 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.
         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;
@@ -77,8 +69,8 @@ class TaxHelper {
         }
         return result;
     }
-    // Divides by a positive denominator and rounds half up, exactly as Math.round does. A bigint
-    // division truncates towards zero, so the floor is taken by hand.
+    // Divides by a positive denominator and rounds half up, as Math.round does. A bigint division
+    // truncates towards zero, so the floor is taken by hand.
     static divideAndRound(numerator, denominator) {
         const doubled = numerator * 2n + denominator;
         const divisor = denominator * 2n;

package/dist/TaxType.js

@@ -1,15 +1,14 @@
 // 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, which is unique only within a country, and ProtoMap combines it with the country of the
-// business the tax is on. The values are Java TaxType.createId(country, taxCode) =
-// (country.getNumeric() << 8) | taxCode, so each is globally unique; the country is recovered with
-// countryCodeOf and the raw tax code with taxCodeOf. They are copied from Java's TaxType by hand, and
-// pinned there by TaxTypeIdsTest (repository/test/com/merabills/repository/entities/helpers), which
-// fails when GST or the shift of the country changes, or a type is added, until this file has
-// followed - so a tax added there must be added here with the same value. The tests of this
-// library pin the same values (Values.test.ts).
+// 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).
 export var TaxType;
 (function (TaxType) {
-    // No country's numeric code is ever 0, so this can never collide with a real type
+    // No country's numeric code is 0, so this cannot collide with a real type
     TaxType[TaxType["UNSPECIFIED_TAX_TYPE"] = 0] = "UNSPECIFIED_TAX_TYPE";
     // India (country code 356): Goods and Services Tax (tax code 0)
     TaxType[TaxType["GST"] = 91136] = "GST";

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) - a signed-out storefront has no user but still shows its catalog.
-// Exactly the User message, with no derived state added.
+// (profile, not business), since 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 delivery addresses of this customer, and which of them is the default. This is also what
-    // resolves Order.deliveryAddressId, which is an id into this list.
+    // The customer's delivery addresses, and which is the default. Also resolves
+    // Order.deliveryAddressId, an id into this list.
     get addresses() {
         return this._addresses;
     }