From 93399c85789b09f76811f28e3121a7181ed8bc63 Mon Sep 17 00:00:00 2001 From: Michael FIG Date: Sat, 5 Sep 2020 11:16:08 -0600 Subject: [PATCH] refactor: clean up types some more Closes #1707, closes #1465 --- .../lib/ag-solo/vats/lib-board.js | 17 ++++++++++-- packages/sparse-ints/src/sparseInts.js | 11 +++++--- packages/zoe/docs/seats.md | 2 +- packages/zoe/src/contractFacet/offerSafety.js | 2 +- packages/zoe/src/contractFacet/types.js | 4 +-- packages/zoe/src/contractSupport/types.js | 8 +++--- .../zoe/src/contractSupport/zoeHelpers.js | 6 ++--- .../contracts/auction/secondPriceAuction.js | 1 - packages/zoe/src/internal-types.js | 7 +---- packages/zoe/src/objArrayConversion.js | 8 +++++- packages/zoe/src/types.js | 2 +- packages/zoe/src/zoeService/types.js | 27 ++++++++++++------- packages/zoe/test/unitTests/zcf/test-zcf.js | 2 +- 13 files changed, 60 insertions(+), 37 deletions(-) diff --git a/packages/cosmic-swingset/lib/ag-solo/vats/lib-board.js b/packages/cosmic-swingset/lib/ag-solo/vats/lib-board.js index 4de2a444128..d40ce3cf829 100644 --- a/packages/cosmic-swingset/lib/ag-solo/vats/lib-board.js +++ b/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} Board */ diff --git a/packages/sparse-ints/src/sparseInts.js b/packages/sparse-ints/src/sparseInts.js index bf58321113e..2ffb78b9f02 100644 --- a/packages/sparse-ints/src/sparseInts.js +++ b/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} + */ 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 diff --git a/packages/zoe/docs/seats.md b/packages/zoe/docs/seats.md index f2978ce3769..63dde180573 100644 --- a/packages/zoe/docs/seats.md +++ b/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} getNotifier * @property {() => boolean} hasExited * @property {() => ProposalRecord} getProposal diff --git a/packages/zoe/src/contractFacet/offerSafety.js b/packages/zoe/src/contractFacet/offerSafety.js index ffa965768a9..0685619c4df 100644 --- a/packages/zoe/src/contractFacet/offerSafety.js +++ b/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) => { diff --git a/packages/zoe/src/contractFacet/types.js b/packages/zoe/src/contractFacet/types.js index 331adcd2dc1..c4dc93eb4b0 100644 --- a/packages/zoe/src/contractFacet/types.js +++ b/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} */ /** diff --git a/packages/zoe/src/contractSupport/types.js b/packages/zoe/src/contractSupport/types.js index 59f0ff00f72..6f351530b73 100644 --- a/packages/zoe/src/contractSupport/types.js +++ b/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} */ diff --git a/packages/zoe/src/contractSupport/zoeHelpers.js b/packages/zoe/src/contractSupport/zoeHelpers.js index 5e36cf80605..9944d2f70cd 100644 --- a/packages/zoe/src/contractSupport/zoeHelpers.js +++ b/packages/zoe/src/contractSupport/zoeHelpers.js @@ -214,9 +214,9 @@ export const swap = ( /** * @typedef ExpectedRecord - * @property {Record} [want] - * @property {Record} [give] - * @property {Partial>} [exit] + * @property {Record} [want] + * @property {Record} [give] + * @property {Record} [exit] */ /** diff --git a/packages/zoe/src/contracts/auction/secondPriceAuction.js b/packages/zoe/src/contracts/auction/secondPriceAuction.js index bee83a8c51a..1eb417e64ae 100644 --- a/packages/zoe/src/contracts/auction/secondPriceAuction.js +++ b/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, diff --git a/packages/zoe/src/internal-types.js b/packages/zoe/src/internal-types.js index 53847a4624f..c3bde70b5fd 100644 --- a/packages/zoe/src/internal-types.js +++ b/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} ERef - */ diff --git a/packages/zoe/src/objArrayConversion.js b/packages/zoe/src/objArrayConversion.js index e0e8903bc85..cad2f73f1d2 100644 --- a/packages/zoe/src/objArrayConversion.js +++ b/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'); diff --git a/packages/zoe/src/types.js b/packages/zoe/src/types.js index fa4d46eb462..03b9b7a52b2 100644 --- a/packages/zoe/src/types.js +++ b/packages/zoe/src/types.js @@ -37,7 +37,7 @@ * @property {Issuer} issuer * @property {AmountMath} amountMath * - * @typedef {Record} Allocation + * @typedef {AmountKeywordRecord} Allocation * @typedef {Record} AmountMathKeywordRecord */ diff --git a/packages/zoe/src/zoeService/types.js b/packages/zoe/src/zoeService/types.js index 600befe576b..fcf365d6d22 100644 --- a/packages/zoe/src/zoeService/types.js +++ b/packages/zoe/src/zoeService/types.js @@ -125,7 +125,7 @@ * * @typedef {{give: AmountKeywordRecord, * want: AmountKeywordRecord, - * exit: ExitRule + * exit: ExitRule * }} ProposalRecord */ @@ -140,17 +140,24 @@ * @typedef {Object} Waker * @property {() => void} wake * - * @typedef {Object} Timer - * @property {(deadline: Deadline, wakerP: ERef) => void} setWakeup - * - * @typedef {number} Deadline - * * @typedef {{waived:null}} Waived * @typedef {{onDemand:null}} OnDemand - * - * @typedef {{afterDeadline:{timer:Timer, deadline:Deadline}}} AfterDeadline - * - * @typedef {Partial&Partial&Partial} ExitRule + */ + +/** + * @template Deadline + * @typedef {Object} Timer + * @property {(deadline: Deadline, wakerP: ERef) => void} setWakeup + */ + +/** + * @template Deadline + * @typedef {{afterDeadline:{timer:Timer, deadline:Deadline}}} AfterDeadline + */ + +/** + * @template Deadline + * @typedef {Waived | OnDemand | AfterDeadline} ExitRule * The possible keys are 'waived', 'onDemand', and 'afterDeadline'. * `timer` and `deadline` only are used for the `afterDeadline` key. * The possible records are: diff --git a/packages/zoe/test/unitTests/zcf/test-zcf.js b/packages/zoe/test/unitTests/zcf/test-zcf.js index 5dc5fb55e95..c121082aa31 100644 --- a/packages/zoe/test/unitTests/zcf/test-zcf.js +++ b/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 {(exit?: ExitRule) => ZcfSeatKit} makeEmptySeatKit test(`zcf.getZoeService`, async t => { const { zoe, zcf } = await setupZCFTest();