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

package/dist/Routes.js

@@ -1,7 +1,7 @@
 // The last path segment of each call this library makes, appended to the base url a ServiceProxy is
-// built with. Named after the server method the segment reaches, in the kebab case Java Routes.java
-// uses, and prefixed to keep the storefront methods clear of the merchant ones that share the host.
-// No route takes an id: every one of these calls says everything it needs to in its request message.
+// built with. Named after the server method, in the kebab case Java Routes.java uses, with a prefix
+// that keeps storefront methods apart from the merchant ones on the same host.
+// No route takes an id: the request message carries everything.
 class Routes {
 }
 Routes.BUSINESS_SYNC_OUT = "shop-business-sync-out";

package/dist/ServiceExceptions.js

@@ -1,11 +1,11 @@
-// What a Service call fails with. Unlike the two in Exceptions.ts these are not programming errors:
-// a caller is expected to catch them and decide what to do - sign in again, retry, or show the shop
-// it already has cached. They mirror Java com.merabills.repository.client.exception so that the two
-// clients of this server describe the same failure the same way.
-// Each carries the status code rather than being told apart by a string, and the derived classes
-// exist so a caller can catch the one case it can actually handle without testing a number.
+// What a Service call fails with. Unlike the two in Exceptions.ts these are not programming errors.
+// 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 and not something else.
+// classes below names, so an unrecognised failure is still a ServiceException.
 export class ServiceException extends Error {
     constructor(httpStatusCode, message) {
         super(message);
@@ -70,9 +70,9 @@ export class ServiceUnavailableException extends ServiceException {
     }
 }
 ServiceUnavailableException.STATUS_CODE = 503;
-// The call never got an answer at all - offline, DNS, TLS, a refused connection or one cut short.
-// Not a ServiceException, because there is no status code and the server may well have acted on the
-// request: a caller that retries has to be prepared for the first attempt to have succeeded.
+// The call never got an answer: offline, DNS, TLS, a refused connection or one cut short.
+// Not a ServiceException, since there is no status code and the server may have acted on the
+// request. A caller that retries must be prepared for the first attempt to have succeeded.
 export class NetworkConnectionException extends Error {
     constructor(message, reason) {
         super(message);
@@ -80,5 +80,4 @@ export class NetworkConnectionException extends Error {
         this.name = new.target.name;
     }
 }
-// Which status code each of these stands for is HttpStatusCodes.ts, the way Java keeps the classes
-// in its exception package and the mapping in HttpStatusCodes.
+// The status code each of these stands for is mapped in HttpStatusCodes.ts.

package/dist/ServiceProxy.js

@@ -12,14 +12,13 @@ import { buildAuthTokensBytes } from "./ProtoMap";
 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, carrying its request message encoded, and answering with the response message encoded - so
-// this class translates nothing and reads no field of either.
-// One call is one page: a sync out is paged, and the loop belongs to whoever is caching what comes
-// back, so that each page is written as it arrives - see Model.businessSyncIn.
+// 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).
 export default class ServiceProxy {
-    // The base url is everything before the route, with or without a trailing slash and with or
-    // without a path of its own - both are joined onto rather than replaced, so a server reached
-    // under a prefix works without the caller having to know how a route is built.
+    // 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.
     constructor(serviceBaseUrl, fetchFunction = null) {
         this._serviceBaseUrl = serviceBaseUrl.replace(TRAILING_SLASHES, "");
         this._fetchFunction = fetchFunction;
@@ -40,8 +39,8 @@ export default class ServiceProxy {
     async updateUser(user, authTokens) {
         return this.post(Routes.UPDATE_USER, proto_User, user, proto_ProfileSyncOutResponse, authTokens);
     }
-    // One call: encode, send, turn a refusal into the exception it stands for, decode. The message
-    // types are passed in rather than named per call so that every route is sent and read identically.
+    // 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.
     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
@@ -51,8 +50,8 @@ export default class ServiceProxy {
     }
     async send(route, body, authTokens) {
         const headers = { [CONTENT_TYPE_HEADER]: CONTENT_TYPE_PROTOBUF };
-        // An anonymous visitor is given no header at all rather than an empty one - the protocol has no
-        // anonymous form of the message, so the absence is what says nobody is claiming to be calling.
+        // 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.
         if (authTokens !== null)
             headers[AUTHORIZATION_HEADER] = toBase64(buildAuthTokensBytes(authTokens));
         try {
@@ -63,14 +62,13 @@ export default class ServiceProxy {
             });
         }
         catch (reason) {
-            // fetch rejects only when no answer arrived at all; a server that refused the call answers
-            // with a status code and resolves. So the request may still have been acted on, and a caller
-            // that retries has to be prepared for the first attempt to have succeeded.
+            // fetch rejects only when no answer arrived. A refusal resolves with a status code. See
+            // NetworkConnectionException for what a caller must expect.
             throw new NetworkConnectionException(`The call to ${route} could not be completed`, reason);
         }
     }
-    // Resolved per call rather than at construction, so a platform that installs fetch after this
-    // object is built still works and an absent one fails where it is actually needed.
+    // Resolved per call, not at construction, so a platform that installs fetch after this object is
+    // built still works and an absent fetch fails where it is needed.
     getFetchFunction() {
         const supplied = this._fetchFunction;
         if (supplied !== null)
@@ -82,9 +80,8 @@ export default class ServiceProxy {
         return platform.bind(globalThis);
     }
     // What the response says went wrong, if anything. This protocol has no error message of its own
-    // yet, so the body of a failure can be anything at all - a stack trace, an HTML page - and only
-    // the start of one is worth carrying; a body that cannot be read says nothing the status code
-    // does not already.
+    // 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.
     static async readErrorMessage(route, response) {
         let body;
         try {
@@ -99,11 +96,10 @@ export default class ServiceProxy {
     }
 }
 // A header carries text, so the encoded credentials travel as base64. No scheme prefix: the server
-// reads the whole value as one encoded AuthTokens, exactly as the Java client sends the whole value
-// as one serialized AuthTokens.
+// reads the whole value as one encoded AuthTokens, as the Java client sends it.
 function toBase64(bytes) {
-    // Built a character at a time rather than by spreading the array into String.fromCharCode, which
-    // passes it as an argument list and overflows the stack once it is long enough
+    // Built a character at a time, since spreading the array into String.fromCharCode passes it as an
+    // argument list and overflows the stack when long enough
     let binary = "";
     for (const byte of bytes)
         binary += String.fromCharCode(byte);

package/dist/ShoppingList.js

@@ -7,25 +7,22 @@ import { TaxAmount } from "./Tax";
 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, and its taxes are worked out on top (see
-// ShoppingListItem). What a customer is shown is the other thing: the same prices WITH the taxes,
-// which is what the catalog gave them, so each item offers both. Everything that adds up - the
-// line totals, the list's total, a discount of a line or of the list - already has the taxes in
-// it. The taxes inside a total are available by type (computedTaxes).
+// 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).
 //
-// Wire totals are authoritative: totalAmount is the number to display. The computed ones (below)
-// reproduce Java's arithmetic to the unit for the items that are here, so they agree with the wire
-// whenever the items were sent - but a list can arrive without them, and then only the wire total
-// covers the whole list.
+// 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.
 class ShoppingList {
-    // Only ProtoMap calls this: it is the one place that sees a total still multiplied by
-    // Constants.AMOUNT_FACTOR.
+    // 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 is what a list of them has as totalAmountBeforeDiscount. Added up in
-    // scaled values and unscaled once, so no rounding creeps in from adding unscaled numbers.
+    // 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.
     static sumOfFinalPrices(items) {
         return amountFromScaledValue(sumOf(items, (pricing) => pricing.finalPrice));
     }
@@ -42,8 +39,8 @@ class ShoppingList {
         this._existingItems = _existingItems;
         this._deletedItems = _deletedItems;
     }
-    // True once the customer is done editing, after which the business may edit it instead. Only a
-    // final list can have deleted items, and this is never unset.
+    // 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.
     get isFinal() {
         return this._isFinal;
     }
@@ -69,21 +66,21 @@ class ShoppingList {
     get totalAmountBeforeDiscount() {
         return this._totalAmountBeforeDiscount;
     }
-    // The discount on the whole list, as opposed to a discount on one line of it. 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 already has its
+    // taxes in it.
     get discount() {
         return this._discount;
     }
-    // What the customer owes, taxes included. Derived rather than sent, but derived from the
-    // authoritative totals above, so this is the number to display. Never less than zero, which is
-    // Java ShoppingList.getTotalAmount: a discount greater than the total leaves nothing to pay, not
-    // a refund. Worked out in scaled values, so it is not a floating point difference.
+    // 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.
     get totalAmount() {
         const total = amountToScaledValue(this._totalAmountBeforeDiscount) - amountToScaledValue(this._discount);
         return total > 0n ? amountFromScaledValue(total) : 0;
     }
-    // Read from the wire and not from the length of the array below, because the protocol sends the
-    // count even when it does not send the items themselves
+    // Read from the wire because the protocol sends the count even when it sends no items, so the
+    // array length below can differ
     get existingItemCount() {
         return this._existingItemCount;
     }
@@ -97,25 +94,24 @@ class ShoppingList {
         return this._existingItems;
     }
     // The items that were in this list when it was made final and have since been deleted or
-    // replaced. Always empty until then.
+    // replaced. Empty until the list is final.
     get deletedItems() {
         return this._deletedItems;
     }
-    // The existing items that are packages bought from the catalog, in the order of the list - which
-    // is shoppingListOrder and not the order they were sent in, the server sending them by package id.
-    // The charge lines are not here (chargeItems), and neither are the items taken out since the
-    // list was made final (removedItems).
+    // 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.
     get goodsItems() {
         return this.derived.goods;
     }
-    // The existing items that are charge lines - the delivery charge and the service charge - in the
+    // 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 (the discount is discount, the total is totalAmount).
+    // list does not carry as items. They are discount and totalAmount.
     get chargeItems() {
         return this.derived.charges;
     }
-    // The delivery charge, which is an item like any other and priced like one, or null when this
-    // list has none
+    // The delivery charge, an item priced like any other, or null when this list has none
     get deliveryCharge() {
         return (this._existingItems.find((item) => item.reservedPackage === proto_ReservedPackage.DELIVERY_CHARGE_PACKAGE) ?? null);
     }
@@ -124,20 +120,18 @@ class ShoppingList {
         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 - deletedItems in the order of the list. A deleted
-    // charge line is among them, and tells itself apart by reservedPackage.
+    // 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.
     get removedItems() {
         return this.derived.removed;
     }
-    // What the business has done to one line of this list since the customer made it final, which is
-    // what ShoppingListItem.change says of it - except for a list the storefront wrote before it set
-    // isOriginal. CartEditor did not, up to 1.4.0: every line of such an order is flagged as made
-    // after the list was final, which on the merchant app's reading is a line the merchant added. But
-    // no change the business can make leaves a final list with no line of the customer's in it and
-    // nothing removed (adding a line leaves the others original; taking one out leaves it in
-    // deletedItems; changing one leaves the old line there too), so a final list with nothing
-    // original, nothing modified and nothing deleted is read as untouched. Show a list's marks with
-    // this and not with ShoppingListItem.change.
+    // 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.
     changeOf(item) {
         const change = item.change;
         if (change !== ItemChange.ADDED)
@@ -160,14 +154,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 - a type that
-    // applies to nothing but free items, which Java ShoppingList.getTotalTaxesByTaxCode leaves out
-    // altogether (JavaVectorsTest pins that) - and a bill shows no line for it, so it reads the same.
-    // The taxes are not changed by the discount of an item or of the list: those come off a price that
-    // has its taxes in it.
-    //
-    // Worked out once, like what derived holds, but apart from it: this prices the items, which the
-    // lines of a list do not need, and one that cannot be priced is no reason for a list not to list them.
+    // over every item. A type none of the items has is not here. 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.
     get computedTaxes() {
         const existing = TAXES.get(this);
         if (existing !== undefined)
@@ -185,24 +177,24 @@ class ShoppingList {
         TAXES.set(this, created);
         return created;
     }
-    // What the existing items come to at their regular prices, with their taxes and with none of
-    // their own discounts taken off: the total as it would have been had nothing been on offer.
-    // Compared with totalAmount it gives what the customer saved. Same caveat as computedTotal.
+    // 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.
     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, which is what a bill shows as savings - and a delivery charge that was waived,
-    // being an item with a price discount like any other, as the merchant app's total row has it. So
-    // a basket can save more once delivery is in the list than it did without. Zero when nothing was
-    // taken off, and never negative. Same caveat as computedTotal: it needs the items.
+    // 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.
     get savings() {
         const saved = sumOf(this._existingItems, (pricing) => pricing.finalPriceWithoutDiscounts) -
             amountToScaledValue(this.totalAmount);
         return saved > 0n ? amountFromScaledValue(saved) : 0;
     }
-    // Worked out once for this list, which never changes, so that what a UI reads is the same array
-    // every time - a dependency that holds still - and a list is not sorted at every render
+    // 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
     get derived() {
         const existing = DERIVED.get(this);
         if (existing !== undefined)
@@ -227,24 +219,18 @@ ShoppingList.EMPTY = new ShoppingList(false, false, false, 0, MERABILLS_ONLINE_P
 export default ShoppingList;
 // One line of a shopping list: the package being bought, how much of it, and at what price.
 //
-// THE PRICE IS STORED WITHOUT TAXES. unitPrice and priceDiscount are the prices before taxes, and
-// taxes are worked out on top of them - exactly as Java ShoppingListItem does and as
-// ShoppingListItem.proto says. The prices a customer sees (a Price in the catalog, the unit price
-// in a cart) INCLUDE taxes, so a price has its taxes taken out on its way into an item
-// (CartEditor does this, as Java ShoppingListItem.setDetailsFromTaxInclusivePrices does), and the
-// *WithTaxes members below put them back for display. Show those, never unitPrice: unitPrice is
-// what is stored, not what anyone is charged for a unit.
+// 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.
 //
-// The arithmetic is Java's to the unit, and rounds in the same places: the tax base (the unit price
-// multiplied by the quantity) is rounded to a whole amount, then each tax on it is rounded on its
-// own, half up. See TaxHelper. So are its limits: Java refuses an item for an amount of
-// Transaction.MAX_AMOUNT or more (validateAmount), and so does this - by throwing an
-// InvalidArgumentException when the item is priced, which is when something first reads a price
-// off it - for each of the taxes, the final price and the other prices it works out (see
-// validatePricing).
+// 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).
 export class ShoppingListItem {
-    // Only ProtoMap calls this: it is the one place that sees a quantity multiplied by
-    // Constants.QUANTITY_FACTOR and prices multiplied by Constants.AMOUNT_FACTOR.
+    // For ProtoMap, which sees a quantity multiplied by Constants.QUANTITY_FACTOR and prices
+    // multiplied by Constants.AMOUNT_FACTOR.
     static fromScaledValues(packageId, scaledQuantity, scaledUnitPrice, shoppingListOrder, isOriginal, isModified, isStockKeepingRequired, scaledPriceDiscount, scaledDiscount, taxes, expiryMinutes, description) {
         return new ShoppingListItem(packageId, quantityFromScaledValue(scaledQuantity), amountFromScaledValue(scaledUnitPrice), shoppingListOrder, isOriginal, isModified, isStockKeepingRequired, amountFromScaledValue(scaledPriceDiscount), amountFromScaledValue(scaledDiscount), taxes, expiryMinutes, description);
     }
@@ -262,8 +248,8 @@ export class ShoppingListItem {
         this._expiryMinutes = _expiryMinutes;
         this._description = _description;
     }
-    // The package being bought. Four ids are reserved for charge and summary lines rather than
-    // catalog packages and will not be found in the catalog - see isReservedPackage below.
+    // The package being bought. Four ids are reserved for charge and summary lines and are not in the
+    // catalog. See isReservedPackage.
     get packageId() {
         return this._packageId;
     }
@@ -281,8 +267,8 @@ export class ShoppingListItem {
     get quantity() {
         return this._quantity;
     }
-    // What one unit costs WITHOUT taxes, which is the offer price when the package is on offer. This
-    // is what is stored, not what a customer is charged: see unitPriceWithTaxes.
+    // What one unit costs WITHOUT taxes, the offer price when the package is on offer. This is what is
+    // stored. For what a customer is charged see unitPriceWithTaxes.
     get unitPrice() {
         return this._unitPrice;
     }
@@ -291,22 +277,21 @@ export class ShoppingListItem {
         return this._shoppingListOrder;
     }
     // True when this line was created before the list was made final. Everything a customer puts in
-    // a cart is, which is what separates it from what the business adds or changes afterwards.
+    // a cart is, which separates it from what the business adds or changes afterwards.
     get isOriginal() {
         return this._isOriginal;
     }
-    // True when this line has been deleted or replaced since the list was made final. An original
-    // line that is also modified has been deleted (and is in ShoppingList.deletedItems); one that is
-    // not original but is modified has replaced an original one; one that is neither has been added
-    // by the business.
+    // 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.
     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 the way 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 is the line's own flags
-    // and nothing more; to show a list use ShoppingList.changeOf, which also knows an order written
-    // before 1.5.0 flagged its lines wrongly.
+    // 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.
     get change() {
         if (this._isOriginal)
             return this._isModified ? ItemChange.REMOVED : ItemChange.NONE;
@@ -315,9 +300,9 @@ export class ShoppingListItem {
     get isStockKeepingRequired() {
         return this._isStockKeepingRequired;
     }
-    // What the offer takes off the unit price - the regular price of the package less its offer
-    // price, both WITHOUT taxes - and not a discount on this line. So the regular price of one unit,
-    // without taxes, is unitPrice + priceDiscount.
+    // What the offer takes off the unit price: the package's regular price less its offer price, both
+    // WITHOUT taxes. It is not a discount on this line (see discount). The regular price of one unit
+    // without taxes is unitPrice + priceDiscount.
     get priceDiscount() {
         return this._priceDiscount;
     }
@@ -341,20 +326,20 @@ 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. This is the price a customer saw when they added it, and the one to show
-    // wherever the item is shown. Each tax is rounded, so a price with taxes is not always one that
-    // can be reached; when it is not, this is the nearest that can, which differs from what the
-    // catalog said 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
+    // 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).
     get unitPriceWithTaxes() {
         return amountFromScaledValue(pricingOf(this).unitPriceWithTaxes);
     }
-    // The same for the regular price of one unit, which is what is struck through when this line is
-    // on offer (priceDiscount greater than zero)
+    // The same for the regular price of one unit, struck through when this line is on offer
+    // (priceDiscount greater than zero)
     get regularUnitPriceWithTaxes() {
         return amountFromScaledValue(pricingOf(this).regularUnitPriceWithTaxes);
     }
-    // What this line costs before its taxes and before its discount - the tax base: the unit price
-    // multiplied by the quantity, rounded to a whole amount as Java does
+    // What this line costs before its taxes and discount, the tax base: the unit price times the
+    // quantity, rounded to a whole amount as Java does
     get amount() {
         return amountFromScaledValue(pricingOf(this).taxBase);
     }
@@ -367,19 +352,19 @@ export class ShoppingListItem {
     get totalTax() {
         return amountFromScaledValue(pricingOf(this).totalTax);
     }
-    // What this line adds to the list: what it costs, plus the tax on it, less its discount, and not
-    // less than zero. This is the definition ShoppingListItem.proto gives, and it includes taxes.
+    // What this line adds to the list: its cost plus the tax on it, less its discount, and not less
+    // than zero. This is the definition in ShoppingListItem.proto, and it includes taxes.
     get finalPrice() {
         return amountFromScaledValue(pricingOf(this).finalPrice);
     }
-    // What this line would add at the regular price of the package, taxes included, with none of its
-    // own discount taken off: the price a customer would have paid had nothing been on offer. Strike
-    // it through beside finalPrice when it is greater (Java calculateFinalPriceWithoutDiscounts).
+    // 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
+    // through beside finalPrice when it is greater (Java calculateFinalPriceWithoutDiscounts).
     get finalPriceWithoutDiscounts() {
         return amountFromScaledValue(pricingOf(this).finalPriceWithoutDiscounts);
     }
-    // True when this line costs less than it would at the regular price with none of its discount:
-    // finalPriceWithoutDiscounts is then worth striking through beside finalPrice
+    // True when this line costs less than at the regular price with none of its discount, so
+    // finalPriceWithoutDiscounts is worth striking through beside finalPrice
     get isDiscounted() {
         const pricing = pricingOf(this);
         return pricing.finalPriceWithoutDiscounts > pricing.finalPrice;
@@ -408,8 +393,8 @@ export var ItemChange;
     // ShoppingList.deletedItems.
     ItemChange[ItemChange["REMOVED"] = 3] = "REMOVED";
 })(ItemChange || (ItemChange = {}));
-// Kept beside the item rather than in it: an item is a value, and two equal ones should compare
-// equal whether or not either has been priced yet.
+// Kept beside the item so it 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
@@ -444,23 +429,20 @@ function pricingOf(item) {
     return created;
 }
 // Throws an InvalidArgumentException unless every amount the item works out is one the protocol can
-// carry. CartEditor calls it before it keeps a line; everything else finds out when it first reads
-// a price off the item.
+// carry. CartEditor calls it before keeping a line. Anything else finds out when it first reads a
+// price off the item.
 export function validatePricing(item) {
     pricingOf(item);
 }
-// Java Transaction.validateAmount, which refuses an amount of MAX_AMOUNT or more, applied where Java
-// applies it to an item: each of its taxes and its final price when it works them out
-// (recalculate), and the results of calculateFinalPriceWithoutDiscounts, calculateUnitPriceWithTaxes
-// and calculateUnitRegularPriceWithTaxes. They are checked together, once, where the item is priced,
-// so that however it was made - a line of a cart being edited, or one that came from the wire - it
-// answers as Java does and no number that is not an amount of the protocol is ever handed out.
-//
-// They are not independent of each other. finalPriceWithoutDiscounts is what the item costs at its
-// regular price, which is never less than its offer price, and each tax and the final price (a
-// discount comes off that alone) are parts of it; likewise the regular unit price with taxes is
-// never less than the unit price with taxes. So no tax and no final price is over the limit unless
-// that cost is, which the vectors of test/JavaVectors.ts show item by item.
+// Java Transaction.validateAmount refuses 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
+// 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).
 function validateAmounts(pricing) {
     const amounts = [
         ...pricing.taxes.map((tax) => ["tax", tax]),
@@ -473,20 +455,20 @@ function validateAmounts(pricing) {
         if (amount >= MAX_SCALED_AMOUNT)
             throw new InvalidArgumentException(`The ${name} of an item, ${amountFromScaledValue(amount)}, is more than the ${amountFromScaledValue(MAX_SCALED_AMOUNT - 1n)} the protocol can carry`);
 }
-// A scaled amount multiplied by a quantity, rounded to a whole amount, to the letter of Java:
+// 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 such as 0.7 is not quite
-// 0.7 in either, which matters only where the product lands exactly on a half.
+// 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.
 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 it
-// shows a list (ShoppingListAdapter), and an order arrives with its items in the order of their
-// package ids. The removed items are in package id order in the merchant app, which has no better
-// order for them; this library puts them in the order they had, which is the customer's.
+// 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.
 function sortedByOrder(items) {
     return [...items].sort((left, right) => left.shoppingListOrder - right.shoppingListOrder);
 }

package/dist/SyncCache.d.ts

@@ -11,13 +11,16 @@ export default class SyncCache {
     readBusinessCursors(containerName: string): Promise<SyncState>;
     writeBusiness(containerName: string, response: proto_BusinessSyncOutResponse): Promise<number>;
     storeBusiness(containerName: string, response: proto_BusinessSyncOutResponse): Promise<number>;
+    readDeletedBusiness(containerName: string): Promise<proto_BusinessSyncOutResponse | null>;
     readProfile(containerName: string): Promise<proto_ProfileSyncOutResponse | null>;
+    readDeletedProfile(containerName: string): Promise<proto_ProfileSyncOutResponse | null>;
     readProfileCursors(containerName: string): Promise<SyncState>;
     writeProfile(containerName: string, response: proto_ProfileSyncOutResponse): Promise<number>;
     storeProfile(containerName: string, response: proto_ProfileSyncOutResponse): Promise<number>;
     readAuthTokens(containerName: string): Promise<AuthTokens | null>;
     writeAuthTokens(containerName: string, authTokens: AuthTokens): Promise<void>;
     readOrders(containerName: string): Promise<ReadonlyArray<proto_Message>>;
+    readDeletedOrders(containerName: string): Promise<ReadonlyArray<proto_Message>>;
     readMessageUpdateNumber(containerName: string): Promise<bigint>;
     writeOrder(containerName: string, order: proto_Message): Promise<number>;
     readPartyPreferences(containerName: string): Promise<proto_Message | null>;