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

package/dist/CartEditor.js

@@ -6,51 +6,42 @@ import { InvalidArgumentException } from "./Exceptions";
 import Ids from "./Ids";
 import ShoppingList, { ShoppingListItem, validatePricing } from "./ShoppingList";
 import TaxHelper from "./TaxHelper";
-// Builds the cart a customer is filling, in the terms a UI has to hand: packages rather than
-// package ids, quantities rather than quantities multiplied by Constants.QUANTITY_FACTOR, and
-// prices taken off the catalog rather than worked out and passed in. Get one from
-// Business.createCartEditor, edit it, then hand build() to Model.updateCartLocalOnly.
+// Builds the cart a customer is filling, in the terms a UI has to hand: packages, quantities as
+// the customer means them (not multiplied by Constants.QUANTITY_FACTOR), prices from the catalog.
+// Get one from Business.createCartEditor, edit it, then hand build() to Model.updateCartLocalOnly.
 //
-// Mutable, and deliberately the only mutable thing in this object model: it is a scratch copy of
-// the cart, not the cart. Nothing here writes anything - editing an editor changes no Business, no
-// store and nothing on the server until a built list is pushed. It is also a snapshot: it reads the
-// catalog, settings and cart once, at construction, so a sync arriving mid-edit does not move
-// prices under the customer. Make a fresh one when the Business republishes.
+// Mutable, and the only mutable thing in this object model. It is a scratch copy: editing it
+// changes no Business, store or server until a built list is handed to Model. It is also a
+// snapshot, read once at construction, so a sync mid-edit does not move prices under the customer.
+// Make a fresh one when the Business republishes.
 //
-// EVERY PRICE HERE INCLUDES TAXES. The price of a package includes the taxes of its product, and
-// the delivery charge the taxes the settings name for it, so what a customer sees in the catalog
-// is what they pay, and every total below is a total with its taxes already in it. A shopping list
-// item is the other way round - it stores a price WITHOUT taxes and works the taxes out on top -
-// so building one takes the taxes out of the price, exactly as Java ShoppingListItem
-// .setDetailsFromTaxInclusivePrices does, and all the arithmetic is Java's to the unit (see
-// TaxHelper). The taxes are there to be shown as what the total includes (taxes), never to be
-// added to it.
+// EVERY PRICE HERE INCLUDES TAXES: a package's includes its product's taxes, the delivery charge
+// the taxes the settings name for it, so a customer pays what the catalog shows. A shopping list
+// item stores a price WITHOUT taxes, so building one takes them out, as Java
+// ShoppingListItem.setDetailsFromTaxInclusivePrices does (to the unit, see TaxHelper). Taxes are
+// shown as what a total includes (taxes), never added to it.
 class CartEditor {
-    // Business.createCartEditor is how a UI gets one of these; this takes the three things it needs
-    // rather than the Business itself, so a caller can build a cart against a catalog and settings
-    // that are not the ones currently published.
+    // Business.createCartEditor is how a UI gets one. It takes the catalog, settings and cart, not
+    // the Business, so a caller can build a cart against ones that are not currently published.
     //
-    // Every line is priced off the catalog now, not off what the cart was holding: a cart lives
-    // until it is ordered, the merchant may have repriced in between, and what an order freezes is
-    // the price at the moment it is placed. Lines the catalog can no longer price - a package
-    // withdrawn, disabled, or left without a price - are dropped, and left in unavailableItems for a
-    // UI to tell the customer about. So is a line that cannot be bought as it is, which setQuantity
-    // would have refused, a cart that was read not being known to be one this class could have made:
-    // a quantity that is nothing or is not one, a fraction of what is not sold loose, more than the
-    // wire carries, or that comes to more than the protocol can at today's price, and any line past
-    // the most a cart holds (the first lines are kept, being in the order picked). The charge lines
-    // of the list it started from (see ShoppingListItem.isReservedPackage) are dropped too, being
-    // this class's to work out rather than a customer's to carry: build() puts back whatever the
-    // settings now say.
+    // Every line is priced off the catalog, not off what the cart held: the merchant may have
+    // repriced since, and an order freezes the price when it is placed. A line goes to
+    // unavailableItems, for a UI to tell the customer about, when the catalog can no longer price it
+    // (package withdrawn, disabled or without a price) or setQuantity would refuse it (a cart that
+    // was read is not known to be one this class could have made): a zero or invalid quantity, a
+    // fraction of a package not sold loose, more than the wire or the protocol carries at today's
+    // price, or a line past the most a cart holds (the first lines are kept, in pick order).
+    // The charge lines of the starting list (see ShoppingListItem.isReservedPackage) are dropped, not
+    // listed, since build() puts back what the settings now say.
     constructor(_catalog, _settings, cart) {
         this._catalog = _catalog;
         this._settings = _settings;
-        // Insertion ordered, which is what keeps a cart in the order the customer filled it and what
-        // gives each line its shoppingListOrder
+        // Insertion ordered: keeps the cart in the order the customer filled it and gives each line its
+        // shoppingListOrder
         this._quantities = new Map();
         this._inventoryLocationId = cart?.inventoryLocationId ?? 0;
-        // In the order of the list, which is the order the customer picked them in: the goods items are in it, and the items
-        // of the list are not, the server sending those by package id, so a cart that is read back would reorder itself
+        // goodsItems is in the order the customer picked. existingItems is not, the server sending it
+        // by package id, so a cart read back would reorder itself
         const unavailableItems = [];
         for (const item of cart?.goodsItems ?? []) {
             if (item.isReservedPackage)
@@ -60,8 +51,8 @@ class CartEditor {
         }
         this._unavailableItems = Object.freeze(unavailableItems);
     }
-    // What the customer has picked, in the order it was picked in, each line priced as it would be
-    // bought right now. Rebuilt on every read, so a line held across an edit is stale.
+    // What the customer has picked, in pick order, each line priced as it would be bought now.
+    // Rebuilt on every read, so a line held across an edit is stale.
     get lines() {
         const lines = [];
         for (const [packageId, quantity] of this._quantities) {
@@ -72,15 +63,15 @@ class CartEditor {
         }
         return Object.freeze(lines);
     }
-    // The lines of the cart this editor started from that its catalog can no longer price - see the
-    // note on the constructor. Empty for a cart built from nothing, and never added to by an edit.
+    // The lines of the starting cart that the catalog can no longer price (see the constructor).
+    // Empty for a cart built from nothing, and no edit adds to it.
     get unavailableItems() {
         return this._unavailableItems;
     }
     get isEmpty() {
         return this._quantities.size === 0;
     }
-    // How many lines the cart has, which is what a cart badge counts - not how many units are in it
+    // The number of lines, which is what a cart badge counts
     get lineCount() {
         return this._quantities.size;
     }
@@ -95,15 +86,15 @@ class CartEditor {
     getQuantity(item) {
         return this._quantities.get(item.id) ?? 0;
     }
-    // Sets how much of one package the cart holds; zero takes it out. A package a customer cannot
-    // buy - one disabled, or priced in no list this storefront sells from - is refused, as is a
-    // fractional quantity of a package that is not sold loose, and a quantity past what the wire can
-    // carry. Whether a package is sold loose is the catalog's word, and not that of the Package
-    // passed in, which may be one held from before the catalog changed. Returns this, so edits chain.
+    // Sets how much of one package the cart holds; zero takes it out. Refuses a package a customer
+    // cannot buy (disabled, or priced in no list this storefront sells from), a fractional quantity
+    // of a package that is not sold loose, and a quantity past what the wire can carry. Sold loose is
+    // read from the catalog's package, since the Package passed in may predate a catalog change.
+    // Returns this, so edits chain.
     setQuantity(item, quantity) {
         const wireQuantity = CartEditor.toWireQuantity(quantity);
-        // Less than half a thousandth is nothing on the wire - a line of zero, which would cost nothing
-        // - so it takes the line out, as zero does
+        // Less than half a thousandth rounds to zero on the wire, a line that costs nothing, so it
+        // takes the line out as zero does
         if (wireQuantity === 0) {
             this._quantities.delete(item.id);
             return this;
@@ -111,8 +102,8 @@ class CartEditor {
         this._quantities.set(item.id, this.checkQuantity(item.id, quantity, wireQuantity));
         return this;
     }
-    // Adds to what the cart already holds of this package, which is what a quantity stepper does.
-    // A negative amount takes away, and never below nothing.
+    // Adds to what the cart holds of this package, as a quantity stepper does. A negative amount
+    // takes away, down to zero at the lowest.
     add(item, quantity = 1) {
         return this.setQuantity(item, Math.max(0, this.getQuantity(item) + quantity));
     }
@@ -123,53 +114,50 @@ class CartEditor {
         this._quantities.clear();
         return this;
     }
-    // What the packages come to, taxes included and offers already taken off: the sum of the final
-    // prices of the lines, and what a customer sees to be the price of what is in the cart. Delivery
-    // is not in it.
+    // What the packages come to, taxes included and offers taken off: the sum of the lines' final
+    // prices, which a customer sees as the price of the cart. Delivery is not in it.
     get itemsTotal() {
         return ShoppingList.sumOfFinalPrices(this.lines.map((line) => line.item));
     }
-    // What the offers took off the packages, which is what a bill shows as savings: what they would
-    // have come to at their regular prices, less what they come to. Zero when nothing is on offer.
-    // Taxes are included on both sides.
+    // What the offers took off the packages, shown on a bill as savings: the total at regular prices
+    // less the total. Zero when nothing is on offer. Taxes are included on both sides.
     get savings() {
         return this.build().savings;
     }
-    // The taxes inside itemsTotal, all types together. They are part of the total and are not
-    // added to it: see taxes.
+    // The taxes already inside itemsTotal, all types together. See taxes for the split by type.
     get itemsTax() {
         return this.build().computedTotalTax;
     }
-    // The taxes the cart's total includes, one entry per TYPE of tax - a bill shows a line for each
-    // that is not zero. withDeliveryCharge is as for total: the taxes in the delivery charge are
-    // counted only when it is.
+    // The taxes the cart's total includes, one entry per TYPE of tax. A bill shows a line for each
+    // that is not zero. withDeliveryCharge is as for total: the delivery charge's taxes count only
+    // when it is true.
     taxes(withDeliveryCharge = false) {
         return this.build(withDeliveryCharge).computedTaxes;
     }
-    // True when this business delivers at all. False means no delivery charge exists to add, whatever
-    // build() is asked for, and a UI has no fulfillment choice to offer either.
+    // True when this business delivers. When false there is no delivery charge for build() to add,
+    // and no fulfillment choice for a UI to offer.
     get isDeliveryOffered() {
         return this._settings.fulfillmentModes.includes(proto_FulfillmentMode.DELIVERY);
     }
-    // What delivering this cart would cost, taxes included: the business's flat charge, or zero
-    // where it has been waived by the cart reaching freeDeliveryTotal, or where the business delivers
-    // free anyway. Always zero when the business does not deliver.
+    // What delivering this cart costs, taxes included: the business's flat charge, or zero when the
+    // cart has reached freeDeliveryTotal or the business delivers free. Zero when the business does
+    // not deliver.
     get deliveryCharge() {
         return this.buildDeliveryChargeItem(this.getDeliveryCharge(this.itemsTotal), 0)?.finalPrice ?? 0;
     }
-    // What delivery costs before any waiver - the price a bill strikes through when it reads FREE.
-    // Zero where the business delivers free anyway, in which case there is nothing to strike through.
+    // What delivery costs before any waiver, which a bill strikes through when it reads FREE. Zero
+    // where the business delivers free, so there is nothing to strike through.
     get regularDeliveryCharge() {
         return this.buildDeliveryChargeItem(this.regularCharge, 0)?.finalPrice ?? 0;
     }
-    // True when delivering this cart costs nothing, whether because the business never charges or
-    // because this cart has reached the threshold
+    // True when delivering this cart costs nothing, because the business never charges or the cart
+    // has reached the threshold
     get isDeliveryFree() {
         return this.isDeliveryOffered && this.deliveryCharge === 0;
     }
-    // How much more the customer would have to add for delivery to stop being charged, which is the
-    // "add X more for free delivery" note. Zero once it is already free, and null when the business
-    // has set no threshold, so there is no amount that would ever make it free.
+    // How much more the customer must add for free delivery, for the "add X more for free delivery"
+    // note. Zero when delivery is already free. Null when the business does not deliver or has set no
+    // threshold, so no amount would make it free.
     get amountToFreeDelivery() {
         if (!this.isDeliveryOffered)
             return null;
@@ -181,42 +169,30 @@ class CartEditor {
         const remaining = amountToScaledValue(freeDeliveryTotal) - amountToScaledValue(this.itemsTotal);
         return remaining > 0n ? amountFromScaledValue(remaining) : 0;
     }
-    // Tax on the delivery charge: how much of deliveryCharge is the taxes GeneralSettings
-    // .deliveryChargeTaxes carries - which are the business's own and have nothing to do with a
-    // product's. Included in the charge, not added to it. Zero when delivery is free, there being
-    // nothing to tax.
+    // The tax inside deliveryCharge, from GeneralSettings.deliveryChargeTaxes. Those are the
+    // business's own, unrelated to a product's. Included in the charge, not added to it. Zero when
+    // delivery is free.
     get deliveryTax() {
         return this.buildDeliveryChargeItem(this.getDeliveryCharge(this.itemsTotal), 0)?.totalTax ?? 0;
     }
-    // What the cart comes to, taxes included. Delivery is left out unless asked for, the way a cart
-    // page leaves it out and a checkout page puts it in - the same choice build() takes. It is the
-    // total of the list build() answers, so it is the total an order placed from it carries.
+    // What the cart comes to, taxes included. Delivery is left out unless asked for: a cart page
+    // leaves it out and a checkout page puts it in, as in build(). It is the total of the list
+    // build() answers, and so of an order placed from it.
     total(withDeliveryCharge = false) {
         return this.build(withDeliveryCharge).totalAmount;
     }
-    // The cart as a list to write: what Model.updateCartLocalOnly and Model.updateCart take, and
-    // what a later Model.createOrder turns into an order. It is also the list to SHOW - every price,
-    // total and tax a cart or a checkout page displays can be read off it, which is how a placed
-    // order is shown too.
+    // The cart as a list, to write (Model.updateCartLocalOnly, Model.updateCart, Model.createOrder)
+    // and to SHOW: every price, total and tax a cart or checkout page displays can be read off it.
+    // Each line stores its price without taxes and is flagged original, as Java ShoppingList.addItem
+    // does before a list is final. The list comes back not final: Model.createOrder makes it so.
     //
-    // Each line is an item that stores the price without taxes, as Java does, and is flagged
-    // original: a customer's lines are created before the list is final (Java ShoppingList.addItem
-    // sets isOriginal to !isFinal(), and the order becomes final only after its items are in it), and
-    // an item that is not original is what the merchant app marks as added by the business.
-    //
-    // withDeliveryCharge decides whether the delivery charge rides along as a line of its own,
-    // carrying ReservedPackage.DELIVERY_CHARGE_PACKAGE and flagged by
-    // ShoppingList.autoAddDeliveryCharge. A cart page has no fulfillment chosen yet and so leaves it
-    // out, which is the default; a checkout page that has settled on delivery asks for it. The line
-    // is added even when the charge has been waived - at zero, with the regular charge (less its
-    // taxes, like every price in an item) as its priceDiscount - so a bill can show FREE with the
-    // original struck through, which is what Java ShoppingCartViewModel.setDeliveryCharge writes
-    // too.
-    //
-    // Nothing is added to an empty cart: a list holding a delivery charge and no goods is not an
-    // order, and Java removes exactly that line when it is all that is left.
-    // The list comes back not final. Making it final is placing an order, which is
-    // Model.createOrder's to do.
+    // withDeliveryCharge adds the delivery charge as a line (ReservedPackage.DELIVERY_CHARGE_PACKAGE)
+    // and sets ShoppingList.autoAddDeliveryCharge. A cart page leaves it out (the default), a checkout
+    // page that has settled on delivery asks for it. The line is added even when the charge is
+    // waived: at zero, with the regular charge (less its taxes) as its priceDiscount, so a bill can
+    // show FREE with the original struck through (Java ShoppingCartViewModel.setDeliveryCharge).
+    // An empty cart gets no line: a list holding only a delivery charge is not an order, and Java
+    // removes that line when it is all that is left.
     build(withDeliveryCharge = false) {
         const items = [];
         for (const line of this.lines)
@@ -226,38 +202,38 @@ class CartEditor {
             : null;
         if (delivery !== null)
             items.push(delivery);
-        // The total is written off the lines being sent, the way ShoppingList.proto defines it: the
-        // sum of their final prices, tax included. There is no list-wide discount - an offer comes off
-        // a line, and a storefront gives no other.
+        // The total is the sum of the final prices of the lines sent, tax included, as ShoppingList.proto
+        // defines it. There is no list-wide discount: an offer comes off a line, and a storefront gives
+        // no other.
         return new ShoppingList(false, delivery !== null, false, this._inventoryLocationId, this._catalog.priceList?.id ?? MERABILLS_ONLINE_PRICE_LIST_ID, ShoppingList.sumOfFinalPrices(items), 0, items.length, 0, Object.freeze(items), Object.freeze([]));
     }
-    // The delivery charge as a line: one of it, at what it costs now (charge - the regular charge, or
-    // zero once waived), with the waived amount as its price discount - the same shape as a package
-    // bought on offer, which is what lets a bill render it with no special case beyond its label.
-    // Null when the business does not deliver. The charge in the settings includes the settings'
-    // delivery charge taxes, so they come out of it like those of any other price.
+    // The delivery charge as a line: one unit at what it costs now (charge: the regular charge, or
+    // zero once waived), with the waived amount as its price discount. That is the shape of a package
+    // bought on offer, so a bill renders it with no special case beyond its label. Null when the
+    // business does not deliver. The settings' charge includes the delivery charge taxes, so they
+    // come out of it like those of any other price.
     buildDeliveryChargeItem(charge, shoppingListOrder) {
         if (!this.isDeliveryOffered)
             return null;
         return buildItem(Ids.buildId(proto_Constants.PACKAGE_ENTITY_TYPE_ID, BigInt(proto_ReservedPackage.DELIVERY_CHARGE_PACKAGE)), 1, charge, this.regularCharge, this._settings.deliveryChargeTaxes, shoppingListOrder);
     }
-    // The charge before any waiver. Java clamps a negative charge to zero rather than treating it as
-    // a refund, and so does this. Zero when the business does not deliver.
+    // The charge before any waiver. Java clamps a negative charge to zero (no refund), and so does
+    // this. Zero when the business does not deliver.
     get regularCharge() {
         if (!this.isDeliveryOffered)
             return 0;
         return Math.max(0, this._settings.deliveryCharge);
     }
-    // The charge against a cart whose goods come to this much, which is the whole of the policy: the
-    // regular charge, or nothing once the goods reach the threshold. Java ShoppingCartViewModel
-    // .calculateDeliveryCharge compares the same total, taxes included and the delivery line left out.
+    // The charge for a cart whose goods come to itemsTotal: the regular charge, or nothing once the
+    // goods reach the threshold. Java ShoppingCartViewModel.calculateDeliveryCharge compares the same
+    // total, taxes included and the delivery line left out.
     getDeliveryCharge(itemsTotal) {
         const charge = this.regularCharge;
         if (charge === 0)
             return 0; // Free for everyone, or not delivered at all
         const freeDeliveryTotal = this._settings.freeDeliveryTotal;
         if (freeDeliveryTotal <= 0)
-            return charge; // Never free, whatever the cart totals
+            return charge; // Never free, at any total
         return itemsTotal >= freeDeliveryTotal ? 0 : charge;
     }
     // The package this id names, and null unless a customer could actually buy it right now
@@ -265,8 +241,8 @@ class CartEditor {
         const item = this._catalog.getPackage(packageId);
         return item !== null && item.isBuyable ? item : null;
     }
-    // Keeps a line of a cart that was read, as setQuantity would, and says whether it could: a line
-    // that cannot be kept is not a caller's mistake to be refused but one for unavailableItems
+    // Keeps a line of a cart that was read, as setQuantity would, and says whether it could. A line
+    // that cannot be kept goes to unavailableItems, as it is not the caller's mistake.
     tryKeep(item) {
         try {
             const wireQuantity = CartEditor.toWireQuantity(item.quantity);
@@ -281,40 +257,39 @@ class CartEditor {
             throw error;
         }
     }
-    // A quantity travels as an int32 multiplied by Constants.QUANTITY_FACTOR (Java rounds it to that:
-    // NumberHelper.floatToInt), so the least there is is a thousandth. This is a quantity as that,
-    // and what is kept is the quantity the wire will hold, so getQuantity never reports one the
-    // order will not have.
+    // A quantity travels as an int32 multiplied by Constants.QUANTITY_FACTOR (Java rounds to it with
+    // NumberHelper.floatToInt), so the least is a thousandth. This converts a quantity to that. What
+    // is kept is the quantity the wire holds, so getQuantity never reports one the order will not
+    // have.
     static toWireQuantity(quantity) {
         if (!Number.isFinite(quantity) || quantity < 0)
             throw new InvalidArgumentException(`${quantity} is not a quantity`);
         return Math.round(quantity * proto_Constants.QUANTITY_FACTOR);
     }
-    // The quantity to keep for this much of a package, which is what the wire will hold of it - or an
-    // InvalidArgumentException saying why the cart cannot have it: the package is not one the catalog
-    // sells, or it is not sold loose and the quantity is a fraction, or the quantity, or what it comes
-    // to, is more than the protocol carries, or the cart is full. All of it is read off the catalog's
-    // package, which is what the order will be priced from, and not off the caller's.
+    // The quantity to keep for this much of a package, as the wire holds it, or an
+    // InvalidArgumentException saying why the cart cannot have it: the catalog does not sell the
+    // package, it is not sold loose and the quantity is a fraction, the quantity or what it comes to
+    // is more than the protocol carries, or the cart is full. All of it is read off the catalog's
+    // package, which the order is priced from.
     checkQuantity(packageId, quantity, wireQuantity) {
         const buyable = this.getBuyablePackage(packageId);
         if (buyable === null)
             throw new InvalidArgumentException(`Package ${Ids.toStorageHexString(packageId)} cannot be bought from this catalog`);
         if (!buyable.isSoldLoose && !Number.isInteger(quantity))
             throw new InvalidArgumentException(`${buyable.name} is not sold loose, so it cannot be bought ${quantity} at a time`);
-        // This is the most of one package a cart can hold, and it is refused here rather than silently
-        // wrapping on the wire
+        // The most of one package a cart can hold. Refused here so it does not wrap silently on the wire
         if (wireQuantity > CartEditor.MAX_WIRE_QUANTITY)
             throw new InvalidArgumentException(`${quantity} is more than the ${CartEditor.MAX_WIRE_QUANTITY / proto_Constants.QUANTITY_FACTOR} the protocol can carry`);
         // A list holds at most Constants.SHOPPING_LIST_MAX_ITEMS items, and the delivery charge is one
-        // of them (Java ShoppingList.addItem counts it like any other, and a server refuses a list a
-        // line over). So where the business delivers, one place is kept for it: a cart that could be
-        // filled to the limit could not be ordered for delivery.
+        // (Java ShoppingList.addItem counts it like any other, and a server refuses a list one line
+        // over). Where the business delivers, one place is kept for it: a cart filled to the limit
+        // could not be ordered for delivery.
         const maxLines = proto_Constants.SHOPPING_LIST_MAX_ITEMS - (this.isDeliveryOffered ? 1 : 0);
         if (!this._quantities.has(packageId) && this._quantities.size >= maxLines)
             throw new InvalidArgumentException(`A cart holds at most ${maxLines} lines`);
         // Java refuses an amount past Transaction.MAX_AMOUNT (validateAmount) in the item that comes to
-        // it, and so does pricing an item here, which is done before the line is kept rather than when
-        // a list cannot be written
+        // it, and so does pricing an item here. It is priced before the line is kept, so the failure
+        // does not wait until a list is written.
         const stored = wireQuantity / proto_Constants.QUANTITY_FACTOR;
         try {
             validatePricing(new CartLine(buyable, this._catalog.getProduct(buyable.productId), stored).item);
@@ -327,16 +302,15 @@ class CartEditor {
         return stored;
     }
 }
-// The most an int32 holds, which is the most that a quantity multiplied by
-// Constants.QUANTITY_FACTOR can be
+// The most an int32 holds, which bounds a quantity multiplied by Constants.QUANTITY_FACTOR
 CartEditor.MAX_WIRE_QUANTITY = 0x7fffffff;
 export default CartEditor;
-// One line of a cart being edited: the package, the product it is a variant of, and how much of it
-// - with the prices the catalog gives it now, taxes included. A read-only view over what
-// CartEditor holds, rebuilt on every read of CartEditor.lines rather than kept.
+// One line of a cart being edited: the package, the product it is a variant of, and how much of it,
+// with the prices the catalog gives it now, taxes included. A read-only view over what CartEditor
+// holds, rebuilt on every read of CartEditor.lines.
 //
-// Everything here is read off item, the line as a shopping list would store it, so the cart page
-// shows exactly what the order will: no price is worked out twice.
+// Everything is read off item, the line as a shopping list would store it, so the cart page shows
+// what the order will and no price is worked out twice.
 export class CartLine {
     constructor(_package, _product, _quantity) {
         this._package = _package;
@@ -347,7 +321,7 @@ export class CartLine {
     get package() {
         return this._package;
     }
-    // Null only for a package whose product is not in the catalog, which a buyable package's never is
+    // Null when the package's product is not in the catalog, which a buyable package never has
     get product() {
         return this._product;
     }
@@ -355,24 +329,23 @@ export class CartLine {
         return this._quantity;
     }
     // This line as a shopping list holds it: priced without taxes, with the taxes beside it. Show
-    // this to show the line the way an order shows it. Its place in the list is not meaningful here.
+    // this to show the line as an order does. Its place in the list means nothing here.
     get item() {
         this._item ?? (this._item = this.toShoppingListItem(0));
         return this._item;
     }
-    // The taxes of the product this package belongs to, which its price includes. A rate that is not
-    // greater than zero is no tax, as in Java, and is not here.
+    // The taxes of the package's product, which its price includes. A rate not greater than zero is
+    // no tax, as in Java, and is left out.
     get taxes() {
         return includedTaxes(this._product?.taxes ?? []);
     }
     // What one unit costs, taxes included: the offer price where the package is on offer, else the
-    // regular price. This is the catalog's price, to within the rounding of taxes that a price with
-    // taxes in it is subject to (a thousandth or two, which no one is shown). A buyable package
-    // always has a price, so this is never guessed.
+    // regular price. This is the catalog's price to within tax rounding (a thousandth or two, which
+    // no one is shown). A buyable package always has a price, so nothing is guessed.
     get unitPrice() {
         return this.item.unitPriceWithTaxes;
     }
-    // The regular price of a unit, taxes included - what is struck through when it is on offer
+    // The regular price of a unit, taxes included. Struck through when it is on offer
     get regularUnitPrice() {
         return this.item.regularUnitPriceWithTaxes;
     }
@@ -380,7 +353,7 @@ export class CartLine {
         return this._package.price?.isOnOffer ?? false;
     }
     // What this line costs before its taxes: its tax base. A bill that shows prices with taxes shows
-    // finalPrice, not this.
+    // finalPrice.
     get amount() {
         return this.item.amount;
     }
@@ -394,34 +367,32 @@ export class CartLine {
     get totalTax() {
         return this.item.totalTax;
     }
-    // What this line adds to the cart, and what a customer pays for it: the price of a unit
-    // multiplied by the quantity, with its taxes already in it
+    // What this line adds to the cart and a customer pays for it: the unit price times the quantity,
+    // with its taxes already in it
     get finalPrice() {
         return this.item.finalPrice;
     }
-    // This line as the protocol carries it. Only CartEditor.build calls this, which is what assigns
-    // the order. Taxes come out of the price on the way (see buildItem).
+    // This line as the protocol carries it. CartEditor.build calls it and assigns the order. Taxes
+    // come out of the price on the way (see buildItem).
     toShoppingListItem(shoppingListOrder) {
         const price = this._package.price;
         return buildItem(this._package.id, this._quantity, price?.finalPrice ?? 0, price?.regularPrice ?? 0, this._product?.taxes ?? [], shoppingListOrder);
     }
 }
-// The taxes a price includes, as an item is to carry them: only those with a rate, which is what
-// Java does with the taxes of a product (TaxHelper.getTaxCodesAndRates drops the rest).
+// The taxes a price includes, as an item carries them: only those with a rate, as Java does with a
+// product's taxes (TaxHelper.getTaxCodesAndRates drops the rest).
 function includedTaxes(taxes) {
     return Object.freeze(taxes.filter((tax) => Number.isFinite(tax.rate) && tax.rate > 0));
 }
-// The one place a price with taxes in it becomes a shopping list item, and so the one place
-// CartEditor takes a tax out of a price. The item stores the prices without them, as Java
-// ShoppingListItem.setDetailsFromTaxInclusivePrices does: the offer price and the regular price
-// each have their taxes removed, and what the offer takes off is the difference of the two - which
-// is not the difference of the prices with taxes. Everything but the price is as Java's
-// ProductSelectionCard leaves a new item: unit quantity or the customer's, no discount of its own,
-// no description (that is for lines that have no package), and no stock keeping or expiry, a
-// storefront being told neither. It is flagged original, for the reason build gives.
-//
+// Where a price with taxes in it becomes a shopping list item, and so where CartEditor takes a tax
+// out of a price, as Java ShoppingListItem.setDetailsFromTaxInclusivePrices does. The offer price
+// and the regular price each have their taxes removed, and the price discount is the difference of
+// those two, which is not the difference of the prices with taxes. The rest is as Java's
+// ProductSelectionCard leaves a new item: no discount of its own, no description (that is for
+// lines with no package), no stock keeping or expiry (a storefront is not told). It is flagged
+// original, as in build.
 // A price is a whole number of thousandths and each tax is rounded, so some prices cannot be
-// reached: the item then has the price nearest to it (TaxHelper.removeTaxes).
+// reached. The item then has the nearest price (TaxHelper.removeTaxes).
 function buildItem(packageId, quantity, offerPriceWithTaxes, regularPriceWithTaxes, taxes, shoppingListOrder) {
     const included = includedTaxes(taxes);
     const rates = TaxHelper.scaledRatesOf(included);