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

package/dist/ServiceExceptions.js

@@ -2,10 +2,10 @@
 // A caller is expected to catch them and decide what to do: sign in again, retry, or show the shop
 // it has cached. They mirror Java com.merabills.repository.client.exception, so both clients of
 // this server describe a failure the same way.
-// Each carries the status code. The derived classes let a caller catch the one case it can handle
-// without testing a number.
-// A call reached the server and the server refused it. Thrown directly for a status code none of the
-// classes below names, so an unrecognised failure is still a ServiceException.
+// Each ServiceException carries the status code. The derived classes let a caller catch the one
+// case it can handle without testing a number.
+// A call reached the server and the server refused it. Thrown directly for a status code that no
+// class below covers, so an unrecognised failure is still a ServiceException.
 export class ServiceException extends Error {
     constructor(httpStatusCode, message) {
         super(message);
@@ -21,7 +21,7 @@ export class BadRequestException extends ServiceException {
     }
 }
 BadRequestException.STATUS_CODE = 400;
-// HTTP 401 - the credentials were missing, expired or not the caller's to present
+// HTTP 401 - the credentials were missing, expired or did not belong to the caller
 export class UnauthorizedException extends ServiceException {
     constructor(message) {
         super(UnauthorizedException.STATUS_CODE, message);
@@ -80,4 +80,4 @@ export class NetworkConnectionException extends Error {
         this.name = new.target.name;
     }
 }
-// The status code each of these stands for is mapped in HttpStatusCodes.ts.
+// HttpStatusCodes.ts maps each status code to its class.

package/dist/ServiceProxy.js

@@ -13,12 +13,12 @@ import Routes from "./Routes";
 import { NetworkConnectionException } from "./ServiceExceptions";
 // A Service that reaches a real MeraBills server. Every call is one POST to the route named after
 // it, with the encoded request message as the body and the encoded response message as the answer.
-// This class translates nothing and reads no field of either.
-// One call is one page: the loop over a paged sync out belongs to whoever caches what comes back,
-// so each page is written as it arrives (see Model.businessSyncIn).
+// This class only encodes and decodes the messages, and reads none of their fields.
+// One call is one page. The caller that caches the pages runs the loop over a paged sync out, so
+// that each page is written as it arrives (see Model.businessSyncIn).
 export default class ServiceProxy {
-    // The base url is everything before the route, with or without a trailing slash or a path of its
-    // own. The route is joined onto it, so a server reached under a prefix works.
+    // The base url is everything before the route. It may end in a slash and may include a path. The
+    // route is appended to it, so a server reached under a prefix works.
     constructor(serviceBaseUrl, fetchFunction = null) {
         this._serviceBaseUrl = serviceBaseUrl.replace(TRAILING_SLASHES, "");
         this._fetchFunction = fetchFunction;
@@ -35,23 +35,23 @@ export default class ServiceProxy {
     async createUser(request, authTokens) {
         return this.post(Routes.CREATE_USER, proto_CreateUserRequest, request, proto_ProfileSyncOutResponse, authTokens);
     }
-    // The User is the whole request, there being no wrapper message for one
+    // The User is the whole request, since there is no wrapper message for it
     async updateUser(user, authTokens) {
         return this.post(Routes.UPDATE_USER, proto_User, user, proto_ProfileSyncOutResponse, authTokens);
     }
-    // One call: encode, send, turn a refusal into its exception, decode. The message types are
-    // passed in so every route is sent and read the same way.
+    // One call: encode, send, throw the matching exception on an error status, decode. The message
+    // types are passed in so every route is sent and read the same way.
     async post(route, requestType, request, responseType, authTokens) {
         const response = await this.send(route, requestType.toBinary(request), authTokens);
-        // The body of a failure is not a response message, so it has to be dealt with before decoding
+        // The body of a failure is not a response message, so the status is checked before decoding
         if (isError(response.status))
             throwOnError(response.status, await ServiceProxy.readErrorMessage(route, response));
         return responseType.fromBinary(new Uint8Array(await response.arrayBuffer()));
     }
     async send(route, body, authTokens) {
         const headers = { [CONTENT_TYPE_HEADER]: CONTENT_TYPE_PROTOBUF };
-        // An anonymous visitor gets no header, not an empty one. The protocol has no anonymous form of
-        // the message, so the absence says nobody claims to be calling.
+        // An anonymous visitor sends no header rather than an empty one. The protocol has no anonymous
+        // form of the message, so a missing header means the caller is anonymous.
         if (authTokens !== null)
             headers[AUTHORIZATION_HEADER] = toBase64(buildAuthTokensBytes(authTokens));
         try {
@@ -79,9 +79,10 @@ export default class ServiceProxy {
         // Bound, because fetch called detached from globalThis is refused by browsers
         return platform.bind(globalThis);
     }
-    // What the response says went wrong, if anything. This protocol has no error message of its own
-    // yet, so a failure body can be anything (a stack trace, an HTML page) and only its start is
-    // worth carrying. A body that cannot be read adds nothing to the status code.
+    // The message for a failed response: the route, plus the start of the body when there is one. The
+    // protocol defines no error message, so a failure body can be anything (a stack trace, an HTML
+    // page) and only its first MAX_ERROR_MESSAGE_LENGTH characters are kept. A body that cannot be
+    // read is left out.
     static async readErrorMessage(route, response) {
         let body;
         try {

package/dist/ShoppingList.js

@@ -8,21 +8,22 @@ import TaxHelper from "./TaxHelper";
 // A list of packages being bought: a shopping cart, or what an order contains.
 //
 // Every unit price on a list is WITHOUT taxes, with the taxes worked out on top (see
-// ShoppingListItem). Each item also offers the price WITH taxes that a customer is shown.
-// Everything that adds up (line totals, the list's total, a discount) already has its taxes in it.
-// The taxes inside a total are available by type (computedTaxes).
+// ShoppingListItem). Each item also has the price WITH taxes that a customer is shown.
+// Line totals, the list's total and a discount are all amounts with taxes included. computedTaxes
+// gives the taxes inside a total, by type.
 //
-// Wire totals are authoritative: totalAmount is the number to display. The computed ones reproduce
-// Java's arithmetic to the unit for the items that are here, so they match the wire whenever the
-// items were sent. A list can arrive without its items, and then only the wire total covers it.
+// Wire totals are authoritative: totalAmount is the number to display. The computed totals
+// reproduce Java's arithmetic to the unit for the items that are here, so they match the wire
+// whenever the items were sent. A list can arrive without its items, and then only the wire total
+// is complete.
 class ShoppingList {
     // For ProtoMap, which sees totals still multiplied by Constants.AMOUNT_FACTOR.
     static fromScaledValues(isFinal, autoAddDeliveryCharge, autoAddServiceCharge, inventoryLocationId, priceListId, scaledTotalAmountBeforeDiscount, scaledDiscount, existingItemCount, deletedItemCount, existingItems, deletedItems) {
         return new ShoppingList(isFinal, autoAddDeliveryCharge, autoAddServiceCharge, inventoryLocationId, priceListId, amountFromScaledValue(scaledTotalAmountBeforeDiscount), amountFromScaledValue(scaledDiscount), existingItemCount, deletedItemCount, existingItems, deletedItems);
     }
-    // What these items come to, taxes included and each item's own discount taken off: the sum of
-    // their finalPrice, which a list of them has as totalAmountBeforeDiscount. Added in scaled values
-    // and unscaled once, so adding unscaled numbers adds no rounding error.
+    // The sum of finalPrice over these items: taxes included, each item's discount taken off. A list
+    // of them has this as totalAmountBeforeDiscount. It adds in scaled values and unscales once, to
+    // avoid floating point rounding error.
     static sumOfFinalPrices(items) {
         return amountFromScaledValue(sumOf(items, (pricing) => pricing.finalPrice));
     }
@@ -39,17 +40,17 @@ class ShoppingList {
         this._existingItems = _existingItems;
         this._deletedItems = _deletedItems;
     }
-    // True once the customer is done editing, after which the business may edit it. Only a final
-    // list can have deleted items. It is never unset.
+    // True once the customer has finished editing, after which the business may edit it. Only a
+    // final list can have deleted items. It is never unset.
     get isFinal() {
         return this._isFinal;
     }
-    // True when the delivery charge is a line of its own, carrying the reserved package id
-    // ReservedPackage.DELIVERY_CHARGE_PACKAGE, rather than being added to the total
+    // True when the delivery charge is an item with the reserved package id
+    // ReservedPackage.DELIVERY_CHARGE_PACKAGE, rather than an amount added to the total
     get autoAddDeliveryCharge() {
         return this._autoAddDeliveryCharge;
     }
-    // The same, for ReservedPackage.SERVICE_CHARGE_PACKAGE
+    // The same for the service charge, with ReservedPackage.SERVICE_CHARGE_PACKAGE
     get autoAddServiceCharge() {
         return this._autoAddServiceCharge;
     }
@@ -57,8 +58,10 @@ class ShoppingList {
     get inventoryLocationId() {
         return this._inventoryLocationId;
     }
-    // The price list these prices came from, which is the one a storefront sells from: a cart with
-    // none uses Constants.MERABILLS_ONLINE_PRICE_LIST_ID, the list Catalog.priceList holds.
+    // The id of the price list the cart is priced from. A storefront names
+    // Constants.MERABILLS_ONLINE_PRICE_LIST_ID, the list in Catalog.priceList, for every line, including
+    // one priced from that list's parent. CartEditor falls back to that id when the catalog has no
+    // price list.
     get priceListId() {
         return this._priceListId;
     }
@@ -66,15 +69,13 @@ class ShoppingList {
     get totalAmountBeforeDiscount() {
         return this._totalAmountBeforeDiscount;
     }
-    // The discount on the whole list, not on one line. It comes off a total that already has its
-    // taxes in it.
+    // The discount on the whole list, not on one line. It comes off a total that includes taxes.
     get discount() {
         return this._discount;
     }
-    // What the customer owes, taxes included. Derived from the authoritative totals above, so it is
-    // the number to display. Never less than zero, as in Java ShoppingList.getTotalAmount: a discount
-    // greater than the total leaves nothing to pay. Worked out in scaled values, so there is no
-    // floating point error.
+    // The amount to pay, taxes included, and the number to display. Calculated from the wire totals
+    // above. Never less than zero, as in Java ShoppingList.getTotalAmount: a discount greater than
+    // the total gives zero. It subtracts in scaled values to avoid floating point error.
     get totalAmount() {
         const total = amountToScaledValue(this._totalAmountBeforeDiscount) - amountToScaledValue(this._discount);
         return total > 0n ? amountFromScaledValue(total) : 0;
@@ -99,15 +100,15 @@ class ShoppingList {
         return this._deletedItems;
     }
     // The existing items that are packages bought from the catalog, in the order of the list
-    // (shoppingListOrder). The server sends them by package id, so that differs from the order
-    // received. The charge lines are in chargeItems, and the items taken out since the list was made
-    // final are in removedItems.
+    // (shoppingListOrder). The server sends items in package id order, so this differs from the
+    // order received. The charge lines are in chargeItems, and the items deleted or replaced since
+    // the list was made final are in removedItems.
     get goodsItems() {
         return this.derived.goods;
     }
     // The existing items that are charge lines (the delivery charge and the service charge), in the
-    // order of the list. The other two reserved ids, for a discount and a total, are summary lines a
-    // list does not carry as items. They are discount and totalAmount.
+    // order of the list. A list does not carry the other two reserved ids, for a discount and a
+    // total, as items. It has them as discount and totalAmount.
     get chargeItems() {
         return this.derived.charges;
     }
@@ -115,23 +116,23 @@ class ShoppingList {
     get deliveryCharge() {
         return (this._existingItems.find((item) => item.reservedPackage === proto_ReservedPackage.DELIVERY_CHARGE_PACKAGE) ?? null);
     }
-    // The service charge, in the same way
+    // The service charge item, or null when this list has none
     get serviceCharge() {
         return (this._existingItems.find((item) => item.reservedPackage === proto_ReservedPackage.SERVICE_CHARGE_PACKAGE) ?? null);
     }
-    // The items the business took out of the list after the customer made it final, or replaced with
-    // a changed one, as the customer ordered them. It is deletedItems in the order of the list. A
-    // deleted charge line is among them, and is told apart by reservedPackage.
+    // The items the business deleted or replaced after the customer made the list final, as the
+    // customer ordered them. This is deletedItems in the order of the list. A deleted charge line is
+    // included, and reservedPackage identifies it.
     get removedItems() {
         return this.derived.removed;
     }
-    // What the business has done to one line of this list since the customer made it final. It is
-    // ShoppingListItem.change, except for a legacy order, written by a storefront that did not set
-    // isOriginal (CartEditor, up to 1.4.0). Every line of such an order reads as added by the
-    // business. A final list with no original, modified or deleted line is taken to be one, since no
-    // change the business can make leaves that (adding a line keeps the others original, taking one
-    // out leaves it in deletedItems, changing one leaves the old line there too).
-    // Show a list's marks with this, not ShoppingListItem.change.
+    // What the business has done to one line of this list since the customer made it final. This is
+    // ShoppingListItem.change, except for a legacy order: one written by a storefront that did not
+    // set isOriginal (CartEditor, up to 1.4.0). Every line of such an order has change ADDED. A
+    // final list with no original, modified or deleted line is taken to be a legacy order, because
+    // no change by the business can produce that state: adding a line keeps the others original,
+    // deleting one leaves it in deletedItems, and changing one leaves the old line there too.
+    // Use this to show a list's marks, not ShoppingListItem.change.
     changeOf(item) {
         const change = item.change;
         if (change !== ItemChange.ADDED)
@@ -139,12 +140,12 @@ class ShoppingList {
         return this.derived.isUntouchedLegacyOrder ? ItemChange.NONE : ItemChange.ADDED;
     }
     // Sum of finalPrice over existingItems, taxes included. Not authoritative (the wire total is),
-    // and only covers the whole list when existingItems.length equals existingItemCount.
+    // and complete only when existingItems.length equals existingItemCount.
     get computedTotal() {
         return ShoppingList.sumOfFinalPrices(this._existingItems);
     }
-    // The same for the goods alone: what the packages come to, without the charges on top of them.
-    // This is what the free delivery threshold is measured against.
+    // The same for goodsItems alone: what the packages come to, without the charges. The free
+    // delivery threshold is compared with this.
     get computedGoodsTotal() {
         return ShoppingList.sumOfFinalPrices(this.goodsItems);
     }
@@ -154,12 +155,12 @@ class ShoppingList {
         return amountFromScaledValue(sumOf(this._existingItems, (pricing) => pricing.totalTax));
     }
     // The taxes inside computedTotal, one entry per TYPE of tax, in the order of the types, added up
-    // over every item. A type none of the items has is not here. An amount can be zero, for a type
+    // over every item. A type none of the items has is not listed. An amount can be zero, for a type
     // that applies only to free items. Java ShoppingList.getTotalTaxesByTaxCode leaves such a type
     // out (JavaVectorsTest pins that), and a bill shows no line for it.
-    // A discount does not change the taxes: it comes off a price that already has them in it.
-    // Worked out once, like derived but kept apart: this prices the items, and an item that cannot be
-    // priced must not stop the list's lines being listed.
+    // A discount does not change the taxes, because it comes off a price that already includes them.
+    // Computed once, like derived but stored apart from it: this prices the items, and an item that
+    // cannot be priced must not stop the list's lines from being listed.
     get computedTaxes() {
         const existing = TAXES.get(this);
         if (existing !== undefined)
@@ -177,24 +178,24 @@ class ShoppingList {
         TAXES.set(this, created);
         return created;
     }
-    // What the existing items come to at their regular prices, with their taxes and none of their own
-    // discounts taken off: the total had nothing been on offer. Compared with totalAmount it gives
-    // what the customer saved. Same caveat as computedTotal.
+    // The existing items at their regular prices, taxes included and no item discounts taken off:
+    // the total if nothing had been on offer. Its difference from totalAmount is what the customer
+    // saved (see savings). Same caveat as computedTotal.
     get computedTotalWithoutDiscounts() {
         return amountFromScaledValue(sumOf(this._existingItems, (pricing) => pricing.finalPriceWithoutDiscounts));
     }
     // What the offers on the items, the discounts on them and the discount on the list took off,
-    // taxes included, shown on a bill as savings. A waived delivery charge counts too, being an item
-    // with a price discount like any other, as in the merchant app's total row. So a basket can save
-    // more once delivery is in the list. Zero when nothing was taken off, never negative. Same caveat
-    // as computedTotal: it needs the items.
+    // taxes included. A bill shows it as savings. A waived delivery charge counts too, as an item
+    // with a price discount like any other, as in the merchant app's total row. So the savings can
+    // rise once the delivery charge is in the list. Zero when nothing was taken off, never negative.
+    // Same caveat as computedTotal: it needs the items.
     get savings() {
         const saved = sumOf(this._existingItems, (pricing) => pricing.finalPriceWithoutDiscounts) -
             amountToScaledValue(this.totalAmount);
         return saved > 0n ? amountFromScaledValue(saved) : 0;
     }
-    // Worked out once, since the list never changes, so a UI reads the same array every time (a
-    // stable dependency) and the list is not sorted at every render
+    // Computed once, because the list never changes. A UI gets the same array on every read (a
+    // stable dependency), and the items are not sorted on every render.
     get derived() {
         const existing = DERIVED.get(this);
         if (existing !== undefined)
@@ -221,13 +222,13 @@ export default ShoppingList;
 //
 // THE PRICE IS STORED WITHOUT TAXES: unitPrice and priceDiscount are before taxes, which are worked
 // out on top, as in Java ShoppingListItem and ShoppingListItem.proto. A customer sees prices WITH
-// taxes, so CartEditor takes them out on the way in and the *WithTaxes members put them back. Show
-// those, never unitPrice, which is not what a customer is charged for a unit.
+// taxes, so CartEditor takes them out on the way in and the *WithTaxes members add them back. Show
+// those, never unitPrice, which leaves out taxes and so is not what a customer is charged.
 //
-// The arithmetic is Java's to the unit and rounds in the same places: the tax base (unit price
-// times quantity) to a whole amount, then each tax on its own, half up (see TaxHelper). An amount
-// of Transaction.MAX_AMOUNT or more throws an InvalidArgumentException when something first reads
-// a price off the item, as in Java (see validatePricing).
+// The arithmetic matches Java to the unit and rounds in the same places: the tax base (unit price
+// times quantity) to a whole amount, then each tax separately, half up (see TaxHelper). An amount
+// of Transaction.MAX_AMOUNT or more throws an InvalidArgumentException the first time a price is
+// read off the item, as in Java (see validatePricing).
 export class ShoppingListItem {
     // For ProtoMap, which sees a quantity multiplied by Constants.QUANTITY_FACTOR and prices
     // multiplied by Constants.AMOUNT_FACTOR.
@@ -254,11 +255,11 @@ export class ShoppingListItem {
         return this._packageId;
     }
     // True when this line is a charge/summary (delivery, service charge, discount, or total) rather
-    // than a catalog package. A UI must label such lines itself.
+    // than a catalog package. Such a line has no catalog name, so a UI must label it.
     get isReservedPackage() {
         return Ids.isReservedPackageId(this._packageId);
     }
-    // Which of the four that is, and null for a catalog package
+    // Which of the four reserved ids this is, or null for a catalog package
     get reservedPackage() {
         return this.isReservedPackage
             ? Number(Ids.getLowPart(this._packageId))
@@ -276,22 +277,23 @@ export class ShoppingListItem {
     get shoppingListOrder() {
         return this._shoppingListOrder;
     }
-    // True when this line was created before the list was made final. Everything a customer puts in
-    // a cart is, which separates it from what the business adds or changes afterwards.
+    // True when this line was created before the list was made final. Every line a customer puts in
+    // a cart is original. Lines the business adds or changes afterwards are not.
     get isOriginal() {
         return this._isOriginal;
     }
-    // True when this line has been deleted or replaced since the list was made final. Original and
-    // modified: deleted (and in ShoppingList.deletedItems). Not original but modified: replaced an
-    // original one. Neither: added by the business.
+    // True when the business deleted this line, or made it to replace another, since the list was
+    // made final. Original and modified: deleted (and in ShoppingList.deletedItems). Not original but
+    // modified: the replacement of an original line. Neither original nor modified: added by the
+    // business.
     get isModified() {
         return this._isModified;
     }
     // What the business has done to this line since the customer made the list final, read off
-    // isOriginal and isModified as the merchant app does: a "+" beside a line it added, an "x" beside
-    // one it changed, and the old line listed apart as removed. This reads the line's own flags only.
-    // To show a list use ShoppingList.changeOf, which also knows that an order written before 1.5.0
-    // flagged its lines wrongly.
+    // isOriginal and isModified as the merchant app does: it marks an added line with "+", a changed
+    // line with "x", and lists the old line apart as removed. This uses the line's own flags only.
+    // To show a list use ShoppingList.changeOf, which also handles orders written before 1.5.0 that
+    // flagged their lines wrongly.
     get change() {
         if (this._isOriginal)
             return this._isModified ? ItemChange.REMOVED : ItemChange.NONE;
@@ -326,10 +328,10 @@ export class ShoppingListItem {
         return amountFromScaledValue(pricingOf(this).regularUnitPrice);
     }
     // What one unit costs a customer: unitPrice with the taxes on it, the offer price when the
-    // package is on offer. It is the price the customer saw when adding it, and the one to show
-    // wherever the item is shown. Each tax is rounded, so not every price with taxes can be reached.
-    // When it cannot, this is the nearest that can, which differs from the catalog's by a thousandth
-    // or so (Java ShoppingListItem.setDetailsFromTaxInclusivePrices).
+    // package is on offer. It is the price the customer saw when adding it, and the one to show for
+    // the item. Each tax is rounded, so not every price with taxes can be reached. When it cannot,
+    // this is the nearest price that can, which differs from the catalog's by a thousandth or so
+    // (Java ShoppingListItem.setDetailsFromTaxInclusivePrices).
     get unitPriceWithTaxes() {
         return amountFromScaledValue(pricingOf(this).unitPriceWithTaxes);
     }
@@ -344,7 +346,7 @@ export class ShoppingListItem {
         return amountFromScaledValue(pricingOf(this).taxBase);
     }
     // Each tax on this line, in the order of taxes: that tax's rate on amount, rounded half up. All
-    // zero when amount is, since a tax only applies to something that costs. Included in finalPrice.
+    // zero when amount is, since a tax applies only to an amount above zero. Included in finalPrice.
     get taxAmounts() {
         return pricingOf(this).unscaledTaxes;
     }
@@ -357,20 +359,20 @@ export class ShoppingListItem {
     get finalPrice() {
         return amountFromScaledValue(pricingOf(this).finalPrice);
     }
-    // What this line would add at the package's regular price, taxes included, with none of its own
-    // discount taken off: what a customer would have paid had nothing been on offer. Strike it
+    // What this line would add at the package's regular price, taxes included, with the line's
+    // discount not taken off: what a customer would have paid if nothing had been on offer. Strike it
     // through beside finalPrice when it is greater (Java calculateFinalPriceWithoutDiscounts).
     get finalPriceWithoutDiscounts() {
         return amountFromScaledValue(pricingOf(this).finalPriceWithoutDiscounts);
     }
-    // True when this line costs less than at the regular price with none of its discount, so
-    // finalPriceWithoutDiscounts is worth striking through beside finalPrice
+    // True when finalPrice is less than finalPriceWithoutDiscounts, so the latter can be struck
+    // through beside finalPrice
     get isDiscounted() {
         const pricing = pricingOf(this);
         return pricing.finalPriceWithoutDiscounts > pricing.finalPrice;
     }
     // True when this line costs nothing though it would have cost something: a delivery charge that
-    // has been waived, a package given away. A bill reads FREE, with finalPriceWithoutDiscounts
+    // has been waived, a package given away. A bill shows FREE, with finalPriceWithoutDiscounts
     // struck through.
     get isFree() {
         const pricing = pricingOf(this);
@@ -378,8 +380,8 @@ export class ShoppingListItem {
     }
 }
 // What the business has done to a line of an order since the customer made it final. The merchant
-// app marks the second and third with a "+" and an "x" and explains them in a legend, and lists the
-// fourth under "Removed by merchant".
+// app marks ADDED with a "+" and MODIFIED with an "x", explains them in a legend, and lists
+// REMOVED under "Removed by merchant".
 export var ItemChange;
 (function (ItemChange) {
     // As the customer ordered it. Every line of a list that is not final yet is this.
@@ -393,11 +395,11 @@ export var ItemChange;
     // ShoppingList.deletedItems.
     ItemChange[ItemChange["REMOVED"] = 3] = "REMOVED";
 })(ItemChange || (ItemChange = {}));
-// Kept beside the item so it stays a plain value: two equal items compare equal whether or not
-// either has been priced.
+// Held in a WeakMap rather than a field, so the item stays a plain value: two equal items compare
+// equal whether or not either has been priced.
 const PRICINGS = new WeakMap();
 const DERIVED = new WeakMap();
-// The taxes of a list by type, which only a list whose items can be priced has
+// The taxes of a list by type. See computedTaxes for why this is stored apart from DERIVED.
 const TAXES = new WeakMap();
 function pricingOf(item) {
     const existing = PRICINGS.get(item);
@@ -423,26 +425,26 @@ function pricingOf(item) {
         finalPrice: discounted > 0n ? discounted : 0n,
         finalPriceWithoutDiscounts: TaxHelper.addTaxes(scaledProduct(regularUnitPrice, item.quantity), rates),
     };
-    // Before it is kept, so that an item that cannot be priced is refused every time it is asked
+    // Validate before storing, so an item that cannot be priced throws on every read
     validateAmounts(created);
     PRICINGS.set(item, created);
     return created;
 }
 // Throws an InvalidArgumentException unless every amount the item works out is one the protocol can
-// carry. CartEditor calls it before keeping a line. Anything else finds out when it first reads a
-// price off the item.
+// carry. CartEditor calls it before storing a line's quantity. Other code gets the exception the
+// first time it reads a price off the item.
 export function validatePricing(item) {
     pricingOf(item);
 }
-// Java Transaction.validateAmount refuses an amount of MAX_AMOUNT or more. This applies it to the
+// Java Transaction.validateAmount rejects an amount of MAX_AMOUNT or more. This applies it to the
 // amounts Java checks on an item: each tax and the final price (recalculate), and the results of
 // calculateFinalPriceWithoutDiscounts, calculateUnitPriceWithTaxes and
-// calculateUnitRegularPriceWithTaxes. They are checked together, once, where the item is priced, so
-// an item answers as Java does however it was made (a cart line or the wire) and hands out no
+// calculateUnitRegularPriceWithTaxes. They are checked together, once, when the item is priced.
+// So an item behaves as in Java however it was made (a cart line or the wire), and never returns a
 // number the protocol cannot carry.
-// The amounts are not independent. finalPriceWithoutDiscounts is the cost at the regular price,
-// never less than the offer price, and each tax and the final price are parts of it. So none of
-// them is over the limit unless that cost is (test/JavaVectors.ts shows this item by item).
+// The amounts are related. finalPriceWithoutDiscounts is the cost at the regular price, never less
+// than the offer price, and each tax and the final price are parts of it. So none of them is over
+// the limit unless that cost is (test/JavaVectors.ts shows this item by item).
 function validateAmounts(pricing) {
     const amounts = [
         ...pricing.taxes.map((tax) => ["tax", tax]),
@@ -458,17 +460,17 @@ function validateAmounts(pricing) {
 // A scaled amount times a quantity, rounded to a whole amount as Java does:
 // Math.round(((double) amount) * NumberHelper.intToFloat(scaledQuantity, QUANTITY_FACTOR)). The
 // quantity is a FLOAT there, so it is one here (fround), and a quantity like 0.7 is not quite 0.7
-// in either. That matters only where the product lands on a half.
+// in either. That changes the result only when the product is a half.
 function scaledProduct(scaledAmount, quantity) {
     const scaledQuantity = quantityToScaledValue(quantity);
     const floatQuantity = Math.fround(Math.fround(scaledQuantity) / proto_Constants.QUANTITY_FACTOR);
     const product = Math.round(Number(scaledAmount) * floatQuantity);
     return Number.isFinite(product) ? BigInt(product) : 0n;
 }
-// A copy in the order of the list. Java sorts the existing items by shoppingListOrder before
-// showing a list (ShoppingListAdapter), and an order arrives with its items in package id order.
-// The merchant app shows the removed items in package id order, having no better one. This library
-// uses the order they had, which is the customer's.
+// A copy sorted by shoppingListOrder. Java sorts the existing items this way before showing a
+// list (ShoppingListAdapter), and an order arrives with its items in package id order. The
+// merchant app shows the removed items in package id order. This library uses their
+// shoppingListOrder, which is the order the customer made.
 function sortedByOrder(items) {
     return [...items].sort((left, right) => left.shoppingListOrder - right.shoppingListOrder);
 }