refactor: add typings for some sample Zoe contracts

Agoric · Aug 16, 2020 · 8770e7c · 8770e7c
1 parent a263f9f
commit 8770e7c
Show file tree

Hide file tree

Showing 7 changed files with 61 additions and 6 deletions.
diff --git a/packages/zoe/src/contracts/automaticRefund.js b/packages/zoe/src/contracts/automaticRefund.js
@@ -27,6 +27,7 @@ const start = zcf => {
   };
   const makeRefundInvitation = () => zcf.makeInvitation(refund, 'getRefund');
 
+  /** @type {AutomaticRefundPublicFacet} */
   const publicFacet = harden({
     getOffersCount: () => offersCount,
     makeInvitation: makeRefundInvitation,

diff --git a/packages/zoe/src/contracts/autoswap.js b/packages/zoe/src/contracts/autoswap.js
@@ -237,6 +237,7 @@ const start = async zcf => {
 
   const getPoolAllocation = poolSeat.getCurrentAllocation;
 
+  /** @type {AutoswapPublicFacet} */
   const publicFacet = harden({
     getCurrentPrice,
     getLiquidityIssuer: () => liquidityIssuer,

diff --git a/packages/zoe/src/contracts/exported.js b/packages/zoe/src/contracts/exported.js
@@ -0,0 +1,49 @@
+/**
+ * @typedef {Object} SellItemsPublicFacet
+ * @property {() => Issuer} getItemsIssuer
+ * @property {() => Amount} getAvailableItems
+ *
+ * @typedef {Object} SellItemsCreatorOnly
+ * @property {() => Promise<Invitation>} makeBuyerInvitation
+ *
+ * @typedef {SellItemsPublicFacet & SellItemsCreatorOnly} SellItemsCreatorFacet
+ */
+
+/**
+ * @typedef {Object} SellItemsParameters
+ * @property {Record<string, any>} customValueProperties
+ * @property {number} count
+ * @property {Issuer} moneyIssuer
+ * @property {Installation} sellItemsInstallation
+ * @property {Amount} pricePerItem
+ *
+ * @typedef {Object} SellItemsResult
+ * @property {UserSeat} sellItemsCreatorSeat
+ * @property {SellItemsCreatorFacet} sellItemsCreatorFacet
+ * @property {Instance} sellItemsInstance
+ * @property {SellItemsPublicFacet} sellItemsPublicFacet
+ *
+ * @typedef {Object} MintAndSellNFTCreatorFacet
+ * @property {(sellParams: SellItemsParameters) => Promise<SellItemsResult>} sellTokens
+ * @property {() => Issuer} getIssuer
+ */
+
+/**
+ * @typedef {Object} AutoswapPublicFacet
+ * @property {() => Promise<Invitation>} makeSwapInvitation
+ * @property {() => Promise<Invitation>} makeAddLiquidityInvitation
+ * @property {() => Promise<Invitation>} makeRemoveLiquidityInvitation
+ * @property {() => Issuer} getLiquidityIssuer
+ * @property {(from: Amount, toBrand: Brand) => Amount} getCurrentPrice
+ * @property {() => Record<string, Amount>} getPoolAllocation
+ */
+/**
+ * @typedef {Object} AutomaticRefundPublicFacet
+ * @property {() => number} getOffersCount
+ * @property {() => Promise<Invitation>} makeInvitation
+ */
+/**
+ * @typedef {Object} SimpleExchangePublicFacet
+ * @property {() => Promise<Invitation>} makeInvitation
+ * @property {() => Notifier<any>} getNotifier
+ */
diff --git a/packages/zoe/src/contracts/mintAndSellNFT.js b/packages/zoe/src/contracts/mintAndSellNFT.js
@@ -9,7 +9,7 @@ import '../../exported';
  * This contract mints non-fungible tokens and creates a selling contract
  * instance to sell the tokens in exchange for some sort of money.
  *
- * startInstance() returns an invitation that, when exercised, returns a
+ * startInstance() returns an creatorFacet which is a
  * ticketMaker with a `.sellTokens()` method. `.sellTokens()` takes a
  * specification of what is being sold, such as:
  * {
@@ -85,14 +85,15 @@ const start = zcf => {
           .then(sellItemsCreatorSeat => {
             return harden({
               sellItemsCreatorSeat,
-              sellItemsCreatorFacet: creatorFacet,
+              sellItemsCreatorFacet: /** @type {SellItemsCreatorFacet} */ (creatorFacet),
               sellItemsInstance: instance,
-              sellItemsPublicFacet: publicFacet,
+              sellItemsPublicFacet: /** @type {SellItemsPublicFacet} */ (publicFacet),
             });
           });
       });
   };
 
+  /** @type {MintAndSellNFTCreatorFacet} */
   const creatorFacet = harden({ sellTokens, getIssuer: () => issuer });
 
   return harden({ creatorFacet });

diff --git a/packages/zoe/src/contracts/sellItems.js b/packages/zoe/src/contracts/sellItems.js
@@ -92,11 +92,13 @@ const start = zcf => {
 
   const getItemsIssuer = () => issuers.Items;
 
+  /** @type {SellItemsPublicFacet} */
   const publicFacet = {
     getAvailableItems,
     getItemsIssuer,
   };
 
+  /** @type {SellItemsCreatorFacet} */
   const creatorFacet = {
     makeBuyerInvitation: () => {
       const itemsAmount = sellerSeat.getAmountAllocated('Items');

diff --git a/packages/zoe/src/contracts/simpleExchange.js b/packages/zoe/src/contracts/simpleExchange.js
@@ -121,6 +121,7 @@ const start = zcf => {
   const makeExchangeInvitation = () =>
     zcf.makeInvitation(exchangeOfferHandler, 'exchange');
 
+  /** @type {SimpleExchangePublicFacet} */
   const publicFacet = harden({
     makeInvitation: makeExchangeInvitation,
     getNotifier: () => notifier,

diff --git a/packages/zoe/src/types.js b/packages/zoe/src/types.js
@@ -56,9 +56,9 @@
  * @property {(instance: Instance) => IssuerKeywordRecord} getIssuers
  * @property {(instance: Instance) => BrandKeywordRecord} getBrands
  * @property {(instance: Instance) => Object} getTerms
- * @property {(invitation: invitation) => Promise<Instance>} getInstance
- * @property {(invitation: invitation) => Promise<Installation>} getInstallation
- * @property {(invitation: invitation) => Promise<InvitationDetails>}
+ * @property {(invitation: Invitation) => Promise<Instance>} getInstance
+ * @property {(invitation: Invitation) => Promise<Installation>} getInstallation
+ * @property {(invitation: Invitation) => Promise<InvitationDetails>}
  * getInvitationDetails - return an object with the instance,
  * installation, description, invitation handle, and any custom properties
  * specific to the contract.