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

package/dist/SyncCache.js

@@ -1,66 +1,114 @@
+import { Constants as proto_Constants } from "./generated/Constants";
 import Ids from "./Ids";
 import * as ProtoMap from "./ProtoMap";
-// What the server has already said, so that the next call need only ask for what has changed since. A read cache and nothing else: everything in it came out of a response, so giving a container up costs one refetch.
-// Not write through, not an identity (it stamps nothing) and not a sync - a caller calls the Service and hands the response in, which is why the cursors are the caller's. It holds the wire and only the wire, and ProtoMap reads every field. See SYNC LAYER in ../Prompt.txt.
-// One response is one write: the entities it brought are stored and the entities its tombstones
-// named are deleted, in a single batch. There is nothing to work out beyond that, because the
-// server sends a tombstone for every entity it deleted, children included - so this cache never
-// infers a deletion from another one, and a write costs one transaction whether or not the page
-// happened to carry a tombstone.
+import * as SyncKeys from "./SyncKeys";
+// What the server has already said, so the next call asks only for what changed. A read cache:
+// everything in it came from a response, so giving up a container costs one refetch.
+// It does not write through or sync. The caller calls the Service, does the paging and says which
+// writes are reads. It holds only the wire, which ProtoMap reads. See SYNC LAYER in ../Prompt.txt.
+// - One response is one write. A tombstone is a blob nothing older replaces. The server sends one
+//   for every deleted entity, children included, so the cache never infers a deletion.
+// - Tombstones are stored as sent, so a deleted message keeps its order (a completed order is a
+//   deleted message). readDeletedBusiness, readDeletedProfile and readDeletedOrders answer them.
+//   readOrders and readPartyPreferences leave them out.
+// - A cursor is a blob per entity type (its eTag is the cursor), not derived from the entities,
+//   since tombstones and this client's own changes would move it. It rises only with a page of a
+//   read, in that page's batch, and the store keeps the greater.
 export default class SyncCache {
     constructor(_database) {
         this._database = _database;
         this._containers = new Map();
     }
-    // Everything cached for one business, as the response that carried it, or null before anything has been written for it.
+    // Everything cached for one business, as the response that carried it, or null before anything is
+    // written. Tombstones are included as sent: a deleted entity carries what it was, or only its header
+    // for an item. Whatever builds on this must leave tombstones out, except for the order of a message.
     async readBusiness(containerName) {
         return ProtoMap.businessResponseFromBlobs(await this.readAll(containerName));
     }
-    // Takes in what one business sync out returned, one blob per entity versioned by Entity.updatedAt, so the later of two copies wins and a page that arrives twice changes nothing the second time.
-    // What its tombstones named goes in the same batch, deleted rather than stored: a page brings what
-    // has changed and says what has gone, and applying half of that would leave the cache holding an
-    // entity the server has already reported dead.
-    // Answers how much of the page it kept - blobs stored plus ids deleted, which is what the container
-    // now differs by. That is how a caller tells a response that changed something from one that
-    // changed nothing, and what it publishes on: the store keeps a blob only when its eTag is later, so
-    // a response can be rejected in full, and one that was cannot change what a later read of this
-    // container answers - see MODEL.
+    // The cursors the next read sends: the highest update number of each entity type that a page of a
+    // read brought, tombstones included, or zero for a type none has brought. Only a read moves them, so
+    // the next read brings back what this client pushed.
+    async readBusinessCursors(containerName) {
+        return this.readCursors(containerName, SyncKeys.BUSINESS_SYNC_IN);
+    }
+    // Stores one page of a business read, a blob per entity versioned by ProtoMap.entityETag, so the later
+    // copy wins and a repeated page changes nothing. A tombstone wins over the copies of what it deleted,
+    // since a delete is a later write. The cursors the page raises go in the same batch, so they cannot
+    // get ahead of their entities and an interrupted read resumes from its last page.
+    // Answers how many blobs it stored, which tells a caller whether the response changed anything and
+    // what to publish on. The store keeps a blob only when its eTag is later, so a response can be
+    // rejected in full, and a rejected one cannot change what a later read answers - see MODEL.
     async writeBusiness(containerName, response) {
+        return this.writeRead(containerName, ProtoMap.businessResponseToCacheWrite(response), SyncKeys.BUSINESS_SYNC_IN, (cursors) => ProtoMap.raiseBusinessCursors(cursors, response));
+    }
+    // Stores what a business response brought that was not read. It moves no cursor, since what is merged
+    // here is not something this container was read for. Otherwise the same as writeBusiness.
+    async storeBusiness(containerName, response) {
         return this.write(containerName, ProtoMap.businessResponseToCacheWrite(response));
     }
+    // The tombstones cached for one business, as a response, each as stored and as the server sent it.
+    // Null when there are none. The entities a deleted entity owned are tombstones of their own.
+    async readDeletedBusiness(containerName) {
+        return ProtoMap.deletedBusinessResponseFromBlobs(await this.readAll(containerName));
+    }
     // The same for one profile: the customer, the businesses they may reach, and the link to each.
     async readProfile(containerName) {
         return ProtoMap.profileResponseFromBlobs(await this.readAll(containerName));
     }
+    // The tombstones of a profile, as readDeletedBusiness answers those of a business.
+    async readDeletedProfile(containerName) {
+        return ProtoMap.deletedProfileResponseFromBlobs(await this.readAll(containerName));
+    }
+    async readProfileCursors(containerName) {
+        return this.readCursors(containerName, SyncKeys.PROFILE_SYNC_IN);
+    }
+    // One page of a profile read - see writeBusiness
     async writeProfile(containerName, response) {
+        return this.writeRead(containerName, ProtoMap.profileResponseToCacheWrite(response), SyncKeys.PROFILE_SYNC_IN, (cursors) => ProtoMap.raiseProfileCursors(cursors, response));
+    }
+    // What a call that is not a read answered with (a sign up, an update). It is a change this client
+    // made, so it moves no cursor and the next read brings it back. Otherwise the same as writeProfile.
+    async storeProfile(containerName, response) {
         return this.write(containerName, ProtoMap.profileResponseToCacheWrite(response));
     }
-    // The credentials that sign calls about this container - the user token in a profile container, the link token in a business one - and null before the server has issued either.
+    // The credentials that sign calls about this container (the user token in a profile container, the
+    // link token in a business one), or null before the server issues either.
     async readAuthTokens(containerName) {
         const blob = await (await this.getContainer(containerName)).read(Ids.AUTH_TOKENS_BLOB_ID);
         if (blob === null)
             return null;
         return ProtoMap.authTokensFromBytes(blob.bytes);
     }
-    // Unconditional, unlike everything else here: a reissued token is not a later version of an earlier one, so there is nothing to compare and the latest wins.
-    // Keeps only what this server issued - see ProtoMap.authTokensToBlob for why the authentication token is dropped whatever is passed in.
+    // Written without comparison, unlike everything else here: a reissued token is not a later version of
+    // the old one, so the latest wins. Keeps only what this server issued - see ProtoMap.authTokensToBlob
+    // for why the authentication token is dropped.
     async writeAuthTokens(containerName, authTokens) {
         await this.writeBlobs(containerName, [ProtoMap.authTokensToBlob(authTokens)]);
     }
-    // The orders of whoever the responses written here answered, since a server sends a caller only their own messages.
-    // Nothing here records which caller that was, or notices when it changes - see THE MESSAGES OF A BUSINESS ARE NOT PUBLIC.
+    // The open orders of whoever the written responses answered, since a server sends a caller only their
+    // own messages. Open means the business has not completed them; completed ones are deleted messages,
+    // which readDeletedOrders answers. Nothing here records which caller that was or notices when it
+    // changes. See THE MESSAGES OF A BUSINESS ARE NOT PUBLIC.
     async readOrders(containerName) {
         return ProtoMap.orderMessagesFromBlobs(await this.readAll(containerName));
     }
-    // The cursor a push sends: the highest update number among this customer's messages already
-    // cached here, party preferences and orders alike. Not persisted, like every cursor in this
-    // library - read off the store fresh each time rather than kept anywhere.
+    // The orders the business has completed, by fulfilling or cancelling. The merchant app completes an
+    // order by deleting its message, so each is a tombstone, but one a server sends whole because the
+    // customer is shown the order afterwards. Each is as stored and as sent. A tombstone with no order is
+    // not one of them.
+    async readDeletedOrders(containerName) {
+        return ProtoMap.deletedOrderMessagesFromBlobs(await this.readAll(containerName));
+    }
+    // The cursor a push sends: how far reads of this container have got with this customer's messages,
+    // party preferences and orders alike. It is the cursor the next read sends. What a push stores here
+    // does not move it, so a change made during the push is not skipped.
     async readMessageUpdateNumber(containerName) {
-        return ProtoMap.highestCachedMessageUpdateNumber(await this.readAll(containerName));
+        return (await this.readBusinessCursors(containerName)).getUpdateNumber(proto_Constants.MESSAGE_ENTITY_TYPE_ID);
     }
-    // Refuses a message that is not an order, since only the payload says which it is: one stored as the other would never be read back.
+    // Refuses a message that is not an order. Only the payload says which it is, and one stored as the
+    // other would never be read back.
     async writeOrder(containerName, order) {
-        return this.writeBlobs(containerName, [ProtoMap.orderToBlob(order)]);
+        return this.writeOwnMessage(containerName, order, ProtoMap.orderToBlob);
     }
     // The party preferences message in this container, or null when there is none. Two mean two
     // callers, which is the same open question as the orders above.
@@ -68,49 +116,61 @@ export default class SyncCache {
         return ProtoMap.partyPreferencesMessageFromBlobs(await this.readAll(containerName));
     }
     async writePartyPreferences(containerName, partyPreferences) {
-        return this.writeBlobs(containerName, [ProtoMap.partyPreferencesToBlob(partyPreferences)]);
-    }
-    // Drops the party preferences message this container holds, and answers zero when it holds none.
-    // The one delete here that no tombstone asked for, and the only reason it exists: one written
-    // before anybody signed in is handed over to the container named for the membership, and the
-    // copy left behind would otherwise be read by the next anonymous visitor and by the next customer
-    // to sign in - see Model.businessSyncIn. Nothing else about a container is a caller's to remove:
-    // everything in one came off the wire, and what the server has not said is gone stays.
+        return this.writeOwnMessage(containerName, partyPreferences, ProtoMap.partyPreferencesToBlob);
+    }
+    // Gives up everything cached for a business: entities, cursors and tokens. For when a container turns
+    // out to hold another business than the one it is named for, which can happen because a businessId is
+    // only how a business is found. Only the id of its Business tells them apart, and a cursor of one is
+    // no cursor of the other: the store keeps a blob only when its eTag is greater, so the old cursors
+    // would never be lowered and what the new business has below them would never be requested. The
+    // container is dropped here too, since this cache holds each fetched container by name.
+    async deleteBusiness(containerName) {
+        this._containers.delete(containerName);
+        await this._database.deleteContainer(containerName);
+    }
+    // Drops the party preferences message this container holds, and answers zero when there is none. It
+    // is the one delete no tombstone asked for. A cart written before anybody signed in is handed over to
+    // the container named for the membership, and the copy left behind would be read by the next anonymous
+    // visitor and the next customer to sign in - see Model.businessSyncIn. Nothing else in a container is
+    // a caller's to remove: it all came off the wire, and anything the server has not said is gone stays.
     async deletePartyPreferences(containerName) {
         const partyPreferences = await this.readPartyPreferences(containerName);
         if (partyPreferences === null)
             return 0;
         return this.write(containerName, {
             blobs: NO_BLOBS,
-            deletedIds: [ProtoMap.partyPreferencesToBlob(partyPreferences).id],
+            deletedIds: [ProtoMap.getMessageId(partyPreferences)],
         });
     }
-    // The messages a sync in response carried, in a single batch - a pushed order and the party
-    // preferences message it emptied belong in one write, so that this cache cannot come to hold the
-    // order without the emptying. Tombstones included, the same as any other entity array read off
-    // the wire: this is what a push's own messages are stored as once the server has echoed them back
-    // with real update numbers, and it is also how anything else of this customer's that the response
-    // carried lands here. Neither is checked against a payload type, unlike the two writers above -
-    // those are for a caller handing in a message it was given, where storing an order as party
-    // preferences would be a mistake worth catching, and this is for messages the response itself is
-    // the authority on.
+    // The messages a sync in response carried, in one batch, so the cache cannot hold a pushed order
+    // without the party preferences message it emptied. Tombstones are included, as for any entity array
+    // off the wire. This stores a push's own messages once the server has echoed them with real update
+    // numbers. It checks no payload type, unlike writeOrder and writePartyPreferences: those take a
+    // message the caller was given, where an order stored as party preferences is a mistake worth
+    // catching, and here the response is the authority. It moves no cursor, since this client made the
+    // change and the next read brings the same messages back.
     async writeMessages(containerName, messages) {
         return this.write(containerName, ProtoMap.messagesToCacheWrite(messages));
     }
     async readAll(containerName) {
         return (await this.getContainer(containerName)).readAll();
     }
-    // For the writers that store one thing and delete nothing - a credential or a single message,
-    // none of which a tombstone ever arrives for on its own
+    // A message the caller holds rather than one a response carried, versioned from what this container
+    // holds of it. One this client amended has no update number, so it is stored at that of the copy it
+    // amends - see ProtoMap.messageToBlob
+    async writeOwnMessage(containerName, message, toBlob) {
+        const held = await (await this.getContainer(containerName)).read(ProtoMap.getMessageId(message));
+        return this.writeBlobs(containerName, [toBlob(message, held?.eTag ?? null)]);
+    }
+    // For writers that store one thing and delete nothing (a credential or a single message), since no
+    // tombstone arrives for either on its own
     async writeBlobs(containerName, blobs) {
         return this.write(containerName, { blobs: blobs, deletedIds: NO_DELETES });
     }
-    // One transaction per call, which is what makes an interrupted write repeat itself rather than leave the cache part written.
-    // The count the store answers with covers only what it stored: a delete is unconditional, so
-    // there is nothing for it to compare and nothing for it to report. Counting the ids instead can
-    // therefore call a page that deleted nothing a page that changed something, when a tombstone
-    // names an entity this container never held - which is the harmless direction, since a caller
-    // republishes once for nothing rather than going on showing an entity the server has said is gone.
+    // One transaction per call, so an interrupted write repeats instead of leaving the cache part written.
+    // The store's count covers only what it stored: a blob it already holds a copy of that is as new (a
+    // tombstone too) is not stored and not counted. A delete has nothing to compare, so the ids are
+    // counted instead. The only delete is a caller's own - see deletePartyPreferences.
     async write(containerName, cacheWrite) {
         const blobs = cacheWrite.blobs;
         const deletedIds = cacheWrite.deletedIds;
@@ -119,8 +179,28 @@ export default class SyncCache {
         const storedCount = await (await this.getContainer(containerName)).write(blobs, deletedIds);
         return storedCount + deletedIds.length;
     }
-    // Held against their names, so each container is fetched once however often it is used. The promise is held rather than the container, so two calls arriving together share one fetch.
-    // A caller that deletes a container from the store gives up this cache with it: nothing here can tell that what it holds is no longer what the store would hand out.
+    // A page of a read: what it brought and the cursors it moved, in one batch. The count is what the
+    // page's entities changed, so the cursors are subtracted. The store keeps a cursor only where it is
+    // greater, and each moved one is greater than the one read, so it stores the moved cursors or fewer,
+    // when another writer moved one first. That is why the count is clamped at zero.
+    async writeRead(containerName, cacheWrite, cursorKeys, raiseCursors) {
+        const cursors = await this.readCursors(containerName, cursorKeys);
+        const movedKeys = raiseCursors(cursors);
+        const blobs = [...cacheWrite.blobs, ...ProtoMap.cursorsToBlobs(cursors, movedKeys)];
+        const deletedIds = cacheWrite.deletedIds;
+        if (blobs.length === 0 && deletedIds.length === 0)
+            return 0;
+        const storedCount = await (await this.getContainer(containerName)).write(blobs, deletedIds);
+        return Math.max(0, storedCount - movedKeys.size) + deletedIds.length;
+    }
+    async readCursors(containerName, keys) {
+        const container = await this.getContainer(containerName);
+        const blobs = await Promise.all(keys.map((key) => container.read(Ids.getSyncCursorBlobId(key))));
+        return ProtoMap.cursorsFromBlobs(keys, blobs);
+    }
+    // Held by name, so each container is fetched once. The promise is held, so two calls arriving
+    // together share one fetch. Whoever deletes a container from the store must drop it here too, since
+    // nothing here can tell that it no longer matches the store.
     getContainer(containerName) {
         const held = this._containers.get(containerName);
         if (held !== undefined)

package/dist/SyncKeys.js

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

package/dist/SyncState.js

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

package/dist/Tax.d.ts

@@ -1,10 +1,18 @@
-import { TaxType as proto_TaxType } from "./generated/TaxType";
+import { TaxType } from "./TaxType";
 export default class Tax {
     private readonly _type;
     private readonly _rate;
-    static fromScaledValues(type: proto_TaxType, scaledRate: number): Tax;
-    constructor(_type: proto_TaxType, _rate: number);
-    get type(): proto_TaxType;
+    static fromScaledValues(countryCode: number, taxCode: number, scaledRate: number): Tax;
+    constructor(_type: TaxType, _rate: number);
+    get type(): TaxType;
     get countryCode(): number;
+    get taxCode(): number;
     get rate(): number;
 }
+export declare class TaxAmount {
+    private readonly _type;
+    private readonly _amount;
+    constructor(_type: TaxType, _amount: number);
+    get type(): TaxType;
+    get amount(): number;
+}

package/dist/Tax.js

@@ -1,13 +1,18 @@
+import { countryCodeOf, createTaxType, taxCodeOf } from "./TaxType";
 import { taxRateFromScaledValue } from "./Constants";
-// A tax and its rate, applying to a product or a shopping-list line. Rate is exposed as a
-// percentage (18 for 18%), though the wire carries it scaled by Constants.TAX_RATE_FACTOR.
-// Deliberately doesn't compute tax on an amount - only a line item knows the amount, and does
-// that itself.
+// A tax and its rate, on a product or a shopping-list line. The rate is a percentage (18 for 18%),
+// though the wire carries it scaled by Constants.TAX_RATE_FACTOR.
+//
+// Taxes are included in the prices a customer sees: a product's in its package prices, the
+// delivery charge's in the charge. A shopping list item stores its price without taxes, so
+// CartEditor takes them out on the way in and ShoppingListItem.unitPriceWithTaxes puts them back
+// for display. A Tax holds no amount. Only a line item knows one.
 export default class Tax {
-    // Only ProtoMap calls this: it is the one place that sees a rate still multiplied by
-    // Constants.TAX_RATE_FACTOR.
-    static fromScaledValues(type, scaledRate) {
-        return new Tax(type, taxRateFromScaledValue(scaledRate));
+    // For ProtoMap, which sees a rate still multiplied by Constants.TAX_RATE_FACTOR. The wire carries
+    // a tax as its raw code, which means something only within a country (that of the business the
+    // tax is on), so the type is made here from the two, as Java TaxType.createId does.
+    static fromScaledValues(countryCode, taxCode, scaledRate) {
+        return new Tax(createTaxType(countryCode, taxCode), taxRateFromScaledValue(scaledRate));
     }
     constructor(_type, _rate) {
         this._type = _type;
@@ -16,15 +21,34 @@ export default class Tax {
     get type() {
         return this._type;
     }
-    // The country this tax belongs to, ISO 3166-1 numeric. A TaxType value is not a raw Java tax
-    // code - it is Java TaxType.createId(country, taxCode), the country in its high bits - so the
-    // country comes back out of the value itself rather than having to be carried alongside it.
-    // Zero for TaxType.UNSPECIFIED_TAX_TYPE, no country's code being zero.
+    // The country this tax belongs to, ISO 3166-1 numeric. A TaxType value is Java
+    // TaxType.createId(country, taxCode), with the country in its high bits, so the country comes
+    // out of the value itself. Zero for TaxType.UNSPECIFIED_TAX_TYPE, as no country's code is zero.
     get countryCode() {
-        return this._type >> 8;
+        return countryCodeOf(this._type);
+    }
+    // The raw tax code, which is all the wire carries of a tax: the low eight bits of the type
+    get taxCode() {
+        return taxCodeOf(this._type);
     }
     // A percentage: 18 means 18%
     get rate() {
         return this._rate;
     }
 }
+// How much one type of tax comes to across a shopping list: the line a bill shows for it, "GST
+// 5.25". Several taxes of one type, on one item or on many, are added into one. Always included in
+// the list's total, never an extra on top.
+export class TaxAmount {
+    constructor(_type, _amount) {
+        this._type = _type;
+        this._amount = _amount;
+    }
+    get type() {
+        return this._type;
+    }
+    // Zero is possible (a list of free items has taxes and owes none), and a bill shows no line for it
+    get amount() {
+        return this._amount;
+    }
+}

package/dist/TaxHelper.d.ts

@@ -0,0 +1,12 @@
+import Tax from "./Tax";
+export default class TaxHelper {
+    static scaledRatesOf(taxes: ReadonlyArray<Tax>): ReadonlyArray<number>;
+    static calculateTaxAmount(taxBase: bigint, taxRate: number): bigint;
+    static calculateTaxes(taxBase: bigint, taxRates: ReadonlyArray<number>): Array<bigint>;
+    static calculateTotalTaxRate(taxRates: ReadonlyArray<number>): number;
+    static addTaxes(taxBase: bigint, taxRates: ReadonlyArray<number>): bigint;
+    static removeTaxes(amountWithTaxes: bigint, taxRates: ReadonlyArray<number>): bigint;
+    private static divideAndRound;
+    private static abs;
+    private static readonly TAX_RATE_FACTOR;
+}

package/dist/TaxHelper.js

@@ -0,0 +1,85 @@
+import { Constants as proto_Constants } from "./generated/Constants";
+import { taxRateToScaledValue } from "./Constants";
+// The arithmetic of taxes, ported from Java com.merabills.repository.entities.helpers.TaxHelper to
+// give the same answer to the unit. The only place in this library that works out a tax, adds it to
+// an amount or takes it out. Not on the public surface (see index.ts): a UI reads unscaled taxes
+// off a ShoppingListItem, ShoppingList or CartLine.
+//
+// Unlike the rest of this library it works on scaled integers, as Java does: an amount is a bigint
+// multiplied by Constants.AMOUNT_FACTOR, a rate a number multiplied by Constants.TAX_RATE_FACTOR
+// (5% is 500). Floating point would round some taxes the other way. Amounts are bigint because one
+// can reach 2^44, and multiplying by a rate overflows 2^53.
+// A tax is the tax base times the rate, divided by TAX_RATE_FACTOR and rounded half up (as
+// Math.round). Each tax is rounded on its own, as each is shown and paid on its own.
+class TaxHelper {
+    // The rates of these taxes as the arithmetic below takes them: scaled, in the same order. A rate
+    // not greater than zero is no tax. Java refuses one (validateTaxes) and drops one that arrives
+    // (getTaxCodesAndRates), so here it is zero, which keeps the taxes in step with their amounts.
+    static scaledRatesOf(taxes) {
+        return taxes.map((tax) => Number.isFinite(tax.rate) && tax.rate > 0 ? taxRateToScaledValue(tax.rate) : 0);
+    }
+    // One tax on a tax base (the amount before taxes)
+    static calculateTaxAmount(taxBase, taxRate) {
+        return TaxHelper.divideAndRound(taxBase * BigInt(taxRate), TaxHelper.TAX_RATE_FACTOR);
+    }
+    // Each of the taxes with these rates on a tax base, in the order of the rates
+    static calculateTaxes(taxBase, taxRates) {
+        return taxRates.map((taxRate) => TaxHelper.calculateTaxAmount(taxBase, taxRate));
+    }
+    // The sum of these rates (zero when there are none), scaled
+    static calculateTotalTaxRate(taxRates) {
+        let result = 0;
+        for (const taxRate of taxRates)
+            result += taxRate;
+        return result;
+    }
+    // The tax base plus the taxes with these rates on it. Taxes only apply to a tax base greater
+    // than zero.
+    static addTaxes(taxBase, taxRates) {
+        if (taxBase <= 0n)
+            return taxBase;
+        let result = taxBase;
+        for (const taxRate of taxRates)
+            result += TaxHelper.calculateTaxAmount(taxBase, taxRate);
+        return result;
+    }
+    // The inverse of addTaxes: the amount that gives this amount with taxes. Each tax is rounded on
+    // its own, so some amounts with taxes cannot be reached. Then this answers the amount for which
+    // addTaxes comes closest (the lower one on a tie). So removeTaxes(addTaxes(amount, rates),
+    // rates) is always amount.
+    static removeTaxes(amountWithTaxes, taxRates) {
+        if (amountWithTaxes <= 0n || taxRates.length === 0)
+            return amountWithTaxes;
+        // Ignoring rounding, the amount with taxes is the amount multiplied by (1 + the total rate), so
+        // dividing by that estimates the amount. Rounding moves each tax by at most half a unit and the
+        // estimate is rounded too, so the amount is within the number of taxes of the estimate (Java
+        // looks as far). Look at every amount that close.
+        const estimate = TaxHelper.divideAndRound(amountWithTaxes * TaxHelper.TAX_RATE_FACTOR, TaxHelper.TAX_RATE_FACTOR + BigInt(TaxHelper.calculateTotalTaxRate(taxRates)));
+        const reach = BigInt(taxRates.length);
+        const first = estimate > reach ? estimate - reach : 0n;
+        let result = estimate;
+        let smallestDifference = null;
+        for (let candidate = first; candidate <= estimate + reach; ++candidate) {
+            const difference = TaxHelper.abs(TaxHelper.addTaxes(candidate, taxRates) - amountWithTaxes);
+            // Strictly smaller, so of two equally close the lower amount (reached first) is kept
+            if (smallestDifference === null || difference < smallestDifference) {
+                smallestDifference = difference;
+                result = candidate;
+            }
+        }
+        return result;
+    }
+    // Divides by a positive denominator and rounds half up, as Math.round does. A bigint division
+    // truncates towards zero, so the floor is taken by hand.
+    static divideAndRound(numerator, denominator) {
+        const doubled = numerator * 2n + denominator;
+        const divisor = denominator * 2n;
+        const quotient = doubled / divisor;
+        return doubled % divisor !== 0n && doubled < 0n ? quotient - 1n : quotient;
+    }
+    static abs(value) {
+        return value < 0n ? -value : value;
+    }
+}
+TaxHelper.TAX_RATE_FACTOR = BigInt(proto_Constants.TAX_RATE_FACTOR);
+export default TaxHelper;

package/dist/TaxType.d.ts

@@ -0,0 +1,7 @@
+export declare enum TaxType {
+    UNSPECIFIED_TAX_TYPE = 0,
+    GST = 91136
+}
+export declare function createTaxType(countryCode: number, taxCode: number): TaxType;
+export declare function countryCodeOf(type: TaxType): number;
+export declare function taxCodeOf(type: TaxType): number;

package/dist/TaxType.js

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

package/dist/UserProfile.js

@@ -1,7 +1,7 @@
 import Entity from "./Entity";
 // The customer: whose orders and cart the business sees. Named for the database it lives in
-// (profile, not business) - a signed-out storefront has no user but still shows its catalog.
-// Exactly the User message, with no derived state added.
+// (profile, not business), since a signed-out storefront has no user but still shows its catalog.
+// Holds the User message and no derived state.
 export default class UserProfile extends Entity {
     constructor(header, _firstName, _lastName, _mobilePhoneNumber, _addresses, _preferredLanguageCode) {
         super(header);
@@ -21,8 +21,8 @@ export default class UserProfile extends Entity {
     get mobilePhoneNumber() {
         return this._mobilePhoneNumber;
     }
-    // The delivery addresses of this customer, and which of them is the default. This is also what
-    // resolves Order.deliveryAddressId, which is an id into this list.
+    // The customer's delivery addresses, and which is the default. Also resolves
+    // Order.deliveryAddressId, an id into this list.
     get addresses() {
         return this._addresses;
     }