refactor: clean up types some more

Closes #1707, closes #1465

packages/cosmic-swingset/lib/ag-solo/vats/lib-board.js

@@ -1,14 +1,29 @@
+// @ts-check
 /* global harden */
 
 import { generateSparseInts } from '@agoric/sparse-ints';
 import { assert, details } from '@agoric/assert';
 import makeStore from '@agoric/store';
 
+/**
+ * @typedef {Object} Board
+ * @property {(id: string) => any} getValue
+ * @property {(value: any) => string} getId
+ * @property {(value: any) => boolean} has
+ * @property {() => string[]} ids```
+ */
+
+/**
+ * Create a board to post things on.
+ * @param {number} [seed=0]
+ * @returns {Board}
+ */
 function makeBoard(seed = 0) {
   const idToVal = makeStore('boardId');
   const valToId = makeStore('value');
   const sparseInts = generateSparseInts(seed);
 
+  /** @type {Board} */
   const board = harden({
     // Add if not already present
     getId: value => {
@@ -37,5 +52,3 @@ function makeBoard(seed = 0) {
 }
 
 export { makeBoard };
-
-/** @typedef {ReturnType<typeof makeBoard>} Board */

packages/sparse-ints/src/sparseInts.js

@@ -2,10 +2,13 @@
 
 /* global harden */
 
-// Generator function to produce a stream of positive integers that are
-// sparsely scattered across the number space. This supports IDs that
-// are guessable, but for example mistyping a correct ID is unlikely to
-// mistakenly match another generated ID.
+/**
+ * Generator function to produce a stream of positive integers that are
+ * sparsely scattered across the number space. This supports IDs that
+ * are guessable, but for example mistyping a correct ID is unlikely to
+ * mistakenly match another generated ID.
+ * @returns {Generator<number, number, number>}
+ */
 function* generateSparseInts(seed) {
   // This is a linear-feedback shift register with computed startState.
   // Thus, it is totally deterministic, but at least looks a little random

packages/zoe/docs/seats.md

@@ -56,7 +56,7 @@ The type of the ZCFSeat is:
 /**
  * @typedef {Object} ZCFSeat
  * @property {() => void} exit
- * @property {(msg: string=) => never} kickOut
+ * @property {(msg?: string) => never} kickOut
  * @property {() => Notifier<Allocation>} getNotifier
  * @property {() => boolean} hasExited
  * @property {() => ProposalRecord} getProposal

packages/zoe/src/contractFacet/offerSafety.js

@@ -5,7 +5,7 @@
  * allocationAmount greater than or equal to requiredAmount for every
  * keyword of giveOrWant?
  * @param {(brand: Brand) => AmountMath} getAmountMath
- * @param {ProposalRecord["give"] | ProposalRecord["want"]} giveOrWant
+ * @param {AmountKeywordRecord} giveOrWant
  * @param {AmountKeywordRecord} allocation
  */
 const satisfiesInternal = (getAmountMath, giveOrWant = {}, allocation) => {

packages/zoe/src/contractFacet/types.js

@@ -26,7 +26,7 @@
  * @property {(brand: Brand) => Issuer} getIssuerForBrand
  * @property {GetAmountMath} getAmountMath
  * @property {MakeZCFMint} makeZCFMint
- * @property {(exit: ExitRule=) => ZcfSeatKit} makeEmptySeatKit
+ * @property {(exit?: ExitRule) => ZcfSeatKit} makeEmptySeatKit
  */
 
 /**
@@ -96,7 +96,7 @@
  * @callback MakeZCFMint
  * @param {Keyword} keyword
  * @param {AmountMathKind=} amountMathKind
- * @returns {ZCFMint}
+ * @returns {Promise<ZCFMint>}
  */
 
 /**

packages/zoe/src/contractSupport/types.js

@@ -8,9 +8,9 @@
  * @param {ContractFacet} zcf
  * @param {SeatGainsLossesRecord} left
  * @param {SeatGainsLossesRecord} right
- * @param {String} [leftHasExitedMsg] A custom error message if
+ * @param {string} [leftHasExitedMsg] A custom error message if
  * the left seat has been exited already
- * @param {String} [rightHasExitedMsg] A custom error message if the
+ * @param {string} [rightHasExitedMsg] A custom error message if the
  * right seat has been exited already
  * @returns {void}
  *
@@ -45,7 +45,7 @@
  * @param {ContractFacet} zcf
  * @param {ZCFSeat} leftSeat
  * @param {ZCFSeat} rightSeat
- * @param {String} [leftHasExitedMsg]
- * @param {String} [rightHasExitedMsg]
+ * @param {string} [leftHasExitedMsg]
+ * @param {string} [rightHasExitedMsg]
  * @returns {string}
  */

packages/zoe/src/contractSupport/zoeHelpers.js

@@ -214,9 +214,9 @@ export const swap = (
 
 /**
  * @typedef ExpectedRecord
- * @property {Record<keyof ProposalRecord['give'],null>} [want]
- * @property {Record<keyof ProposalRecord['want'],null>} [give]
- * @property {Partial<Record<keyof ProposalRecord['exit'],null>>} [exit]
+ * @property {Record<Keyword, null>} [want]
+ * @property {Record<Keyword, null>} [give]
+ * @property {Record<keyof ProposalRecord['exit'], null>} [exit]
  */
 
 /**

packages/zoe/src/contracts/auction/secondPriceAuction.js

@@ -42,7 +42,6 @@ const start = zcf => {
   // seller will use 'Asset' and 'Ask'. buyer will use 'Asset' and 'Bid'
   assertIssuerKeywords(zcf, harden(['Asset', 'Ask']));
 
-  /** @type {Timer} */
   E(timerAuthority)
     .setWakeup(
       closesAfter,

packages/zoe/src/internal-types.js

@@ -92,7 +92,7 @@
  * @property {(zoeSeatAdmin: ZoeSeatAdmin) => boolean} hasZoeSeatAdmin
  * @property {(zoeSeatAdmin: ZoeSeatAdmin) => void} removeZoeSeatAdmin
  * @property {() => Instance} getInstance
- * @property {() => PublicFacet} getPublicFacet
+ * @property {() => Object} getPublicFacet
  * @property {() => IssuerKeywordRecord} getIssuers
  * @property {() => BrandKeywordRecord} getBrands
  * @property {() => Object} getTerms
@@ -235,8 +235,3 @@
  * @property {() => Object} adminData
  * provides some statistics about the vat in which the contract is running.
  */
-
-/**
- * @template T
- * @typedef {import('@agoric/promise-kit').ERef<T>} ERef
- */

packages/zoe/src/objArrayConversion.js

@@ -4,11 +4,12 @@ import { assert, details, q } from '@agoric/assert';
 
 /**
  * @typedef {bigint|boolean|null|number|string|symbol|undefined} Primitive
+ * @typedef {string|number|symbol} PropertyName
  */
 
 /**
  * @template T
- * @template {string | number | symbol} U
+ * @template {PropertyName} U
  * @param {T[]} array
  * @param {U[]} keys
  */
@@ -24,6 +25,11 @@ export const arrayToObj = (array, keys) => {
   return obj;
 };
 
+/**
+ * Assert all values from `part` appear in `whole`.
+ * @param {string[]} whole
+ * @param {string[]} part
+ */
 export const assertSubset = (whole, part) => {
   part.forEach(key => {
     assert.typeof(key, 'string');

packages/zoe/src/types.js

@@ -37,7 +37,7 @@
  * @property {Issuer} issuer
  * @property {AmountMath} amountMath
  *
- * @typedef {Record<Keyword,Amount>} Allocation
+ * @typedef {AmountKeywordRecord} Allocation
  * @typedef {Record<Keyword,AmountMath>} AmountMathKeywordRecord
  */
 

packages/zoe/src/zoeService/types.js

@@ -125,7 +125,7 @@
  *
  * @typedef {{give: AmountKeywordRecord,
  *            want: AmountKeywordRecord,
- *            exit: ExitRule
+ *            exit: ExitRule<any>
  *           }} ProposalRecord
  */
 
@@ -140,17 +140,24 @@
  * @typedef {Object} Waker
  * @property {() => void} wake
  *
- * @typedef {Object} Timer
- * @property {(deadline: Deadline, wakerP: ERef<Waker>) => void} setWakeup
- *
- * @typedef {number} Deadline
- *
  * @typedef {{waived:null}} Waived
  * @typedef {{onDemand:null}} OnDemand
- *
- * @typedef {{afterDeadline:{timer:Timer, deadline:Deadline}}} AfterDeadline
- *
- * @typedef {Partial<Waived>&Partial<OnDemand>&Partial<AfterDeadline>} ExitRule
+ */
+
+/**
+ * @template Deadline
+ * @typedef {Object} Timer
+ * @property {(deadline: Deadline, wakerP: ERef<Waker>) => void} setWakeup
+ */
+
+/**
+ * @template Deadline
+ * @typedef {{afterDeadline:{timer:Timer<Deadline>, deadline:Deadline}}} AfterDeadline
+ */
+
+/**
+ * @template Deadline
+ * @typedef {Waived | OnDemand | AfterDeadline<Deadline>} ExitRule
  * The possible keys are 'waived', 'onDemand', and 'afterDeadline'.
  * `timer` and `deadline` only are used for the `afterDeadline` key.
  * The possible records are:

packages/zoe/test/unitTests/zcf/test-zcf.js

@@ -39,7 +39,7 @@ const setupZCFTest = async (issuerKeywordRecord, terms) => {
 //  * @property {MakeInvitation} makeInvitation
 //  * @property {() => void} shutdown
 //  * @property {MakeZCFMint} makeZCFMint
-//  * @property {(exit: ExitRule=) => ZcfSeatKit} makeEmptySeatKit
+//  * @property {<Deadline>(exit?: ExitRule<Deadline>) => ZcfSeatKit} makeEmptySeatKit
 
 test(`zcf.getZoeService`, async t => {
   const { zoe, zcf } = await setupZCFTest();