Merge pull request #8212 from Agoric/6125-store-jsdoc

style: prettier jsdoc for 'store'

package.json

@@ -44,6 +44,7 @@
         "files": [
           "packages/ERTP/**/*.{js,ts}",
           "packages/inter-protocol/**/*.{js,ts}",
+          "packages/store/**/*.{js,ts}",
           "packages/vats/**/*.{js,ts}"
         ],
         "options": {

packages/store/src/legacy/legacyMap.js

@@ -3,35 +3,37 @@ import { q, Fail } from '@agoric/assert';
 import '../types.js';
 
 /**
- * This module and its fraternal sibling legacyWeakMap exist only to
- * ease a transition to the modern `store` system, are deprecated,
- * and will eventually disappear. They are needed for now to support
- * some of the uses of the old behavior that are not compatible with
- * the new. The constraint imposed by the new is that only passables can
- * be used as values, and only keys (roughly, structures, aka comparables)
- * can be used as values.
+ * This module and its fraternal sibling legacyWeakMap exist only to ease a
+ * transition to the modern `store` system, are deprecated, and will eventually
+ * disappear. They are needed for now to support some of the uses of the old
+ * behavior that are not compatible with the new. The constraint imposed by the
+ * new is that only passables can be used as values, and only keys (roughly,
+ * structures, aka comparables) can be used as values.
  *
  * See https://github.com/Agoric/agoric-sdk/pull/3567
+ *
  * TODO Once that PR is merged, link to the documents rather than the PRs.
  *
  * Each of these non-conforming uses should be marked with a
+ *
  * ```js
  * // Legacy because...
  * ```
- * comment explaining the problem inhibiting conversion to the new
- * system. Some of these problems as of this writing:
- *    * A promiseKit used as a value, even though a promiseKit is not
- *      a passable. Solutions are to make it a passable, or to convert
- *      the container back to a conventional JavaScript Map.
- *    * A mutable array used as a value, that is subsequently mutated.
- *      Freezing the array wouldn't work of course because it would break
- *      the subsequent mutation. Using a far object wrapping an array would
- *      likely work fine.
+ *
+ * comment explaining the problem inhibiting conversion to the new system. Some
+ * of these problems as of this writing:
+ *
+ * - A promiseKit used as a value, even though a promiseKit is not a passable.
+ *   Solutions are to make it a passable, or to convert the container back to a
+ *   conventional JavaScript Map.
+ * - A mutable array used as a value, that is subsequently mutated. Freezing the
+ *   array wouldn't work of course because it would break the subsequent
+ *   mutation. Using a far object wrapping an array would likely work fine.
  *
  * @deprecated switch to ScalarMap if possible, Map otherwise
  * @template K,V
  * @param {string} [tag] - tag for debugging
- * @returns {LegacyMap<K,V>}
+ * @returns {LegacyMap<K, V>}
  */
 export const makeLegacyMap = (tag = 'key') => {
   const m = new Map();

packages/store/src/legacy/legacyWeakMap.js

@@ -7,7 +7,7 @@ import '../types.js';
  * @deprecated switch to ScalarWeakMap if possible, WeakMap otherwise
  * @template K,V
  * @param {string} [tag] - tag for debugging
- * @returns {LegacyWeakMap<K,V>}
+ * @returns {LegacyWeakMap<K, V>}
  */
 export const makeLegacyWeakMap = (tag = 'key') => {
   /** @type {WeakMap<K & object, V>} */

packages/store/src/stores/scalarMapStore.js

@@ -20,12 +20,12 @@ const { quote: q } = assert;
 /**
  * @template {Key} K
  * @template {Passable} V
- * @param {Map<K,V>} jsmap
+ * @param {Map<K, V>} jsmap
  * @param {(k: K, v: V) => void} assertKVOkToAdd
  * @param {(k: K, v: V) => void} assertKVOkToSet
- * @param {((k: K) => void)} [assertKeyOkToDelete]
+ * @param {(k: K) => void} [assertKeyOkToDelete]
  * @param {string} [tag]
- * @returns {MapStore<K,V>}
+ * @returns {MapStore<K, V>}
  */
 export const makeMapStoreMethods = (
   jsmap,
@@ -77,7 +77,7 @@ export const makeMapStoreMethods = (
   /**
    * @param {Pattern} [keyPatt]
    * @param {Pattern} [valuePatt]
-   * @returns {Iterable<[K,V]>}
+   * @returns {Iterable<[K, V]>}
    */
   const entries = (keyPatt = undefined, valuePatt = undefined) =>
     mapIterable(keys(keyPatt, valuePatt), k => [
@@ -117,21 +117,21 @@ export const makeMapStoreMethods = (
 };
 
 /**
- * Distinguishes between adding a new key (init) and updating or
- * referencing a key (get, set, delete).
+ * Distinguishes between adding a new key (init) and updating or referencing a
+ * key (get, set, delete).
  *
- * `init` is only allowed if the key does not already exist. `Get`,
- * `set` and `delete` are only allowed if the key does already exist.
+ * `init` is only allowed if the key does not already exist. `Get`, `set` and
+ * `delete` are only allowed if the key does already exist.
  *
- * This is a *scalar* map in that the keys can only be atomic values, primitives
+ * This is a _scalar_ map in that the keys can only be atomic values, primitives
  * or remotables. Other storeMaps will accept, for example, copyArrays and
  * copyRecords, as keys and look them up based on equality of their contents.
  *
  * @template {Key} K
  * @template {Passable} V
  * @param {string} [tag] - the column name for the key
  * @param {StoreOptions} [options]
- * @returns {MapStore<K,V>}
+ * @returns {MapStore<K, V>}
  */
 export const makeScalarMapStore = (
   tag = 'key',

packages/store/src/stores/scalarSetStore.js

@@ -74,13 +74,13 @@ export const makeSetStoreMethods = (
 };
 
 /**
- * Distinguishes between adding a new key (init) and updating or
- * referencing a key (get, set, delete).
+ * Distinguishes between adding a new key (init) and updating or referencing a
+ * key (get, set, delete).
  *
- * `init` is only allowed if the key does not already exist. `Get`,
- * `set` and `delete` are only allowed if the key does already exist.
+ * `init` is only allowed if the key does not already exist. `Get`, `set` and
+ * `delete` are only allowed if the key does already exist.
  *
- * This is a *scalar* set in that the keys can only be atomic values, primitives
+ * This is a _scalar_ set in that the keys can only be atomic values, primitives
  * or remotables. Other storeSets will accept, for example, copyArrays and
  * copyRecords, as keys and look them up based on equality of their contents.
  *

packages/store/src/stores/scalarWeakMapStore.js

@@ -11,7 +11,7 @@ const { quote: q, Fail } = assert;
  * @param {(k: K, v: V) => void} assertKVOkToSet
  * @param {(k: K) => void} [assertKeyOkToDelete]
  * @param {string} [keyName]
- * @returns {WeakMapStore<K,V>}
+ * @returns {WeakMapStore<K, V>}
  */
 export const makeWeakMapStoreMethods = (
   jsmap,
@@ -75,22 +75,22 @@ export const makeWeakMapStoreMethods = (
 };
 
 /**
- * This is a *scalar* mapStore in that the keys can only be atomic values:
- * primitives or remotables.
- * Other mapStores will accept, for example, copyArrays and
- * copyRecords as keys and look them up based on equality of their contents.
+ * This is a _scalar_ mapStore in that the keys can only be atomic values:
+ * primitives or remotables. Other mapStores will accept, for example,
+ * copyArrays and copyRecords as keys and look them up based on equality of
+ * their contents.
  *
  * TODO For now, this scalarWeakMap accepts only remotables, reflecting the
- * constraints of the underlying JavaScript WeakMap it uses internally. But
- * it should accept the primitives as well, storing them in a separate internal
+ * constraints of the underlying JavaScript WeakMap it uses internally. But it
+ * should accept the primitives as well, storing them in a separate internal
  * map. What makes it "weak" is that it provides no API for enumerating what's
- * there. Though note that this would only enables collection of the
- * remotables, since the other primitives may always reappear.
+ * there. Though note that this would only enables collection of the remotables,
+ * since the other primitives may always reappear.
  *
  * @template K,V
  * @param {string} [tag] - tag for debugging
  * @param {StoreOptions} [options]
- * @returns {WeakMapStore<K,V>}
+ * @returns {WeakMapStore<K, V>}
  */
 export const makeScalarWeakMapStore = (
   tag = 'key',

packages/store/src/stores/scalarWeakSetStore.js

@@ -58,16 +58,16 @@ export const makeWeakSetStoreMethods = (
 };
 
 /**
- * This is a *scalar* set in that the keys can only be atomic values, primitives
+ * This is a _scalar_ set in that the keys can only be atomic values, primitives
  * or remotables. Other storeSets will accept, for example, copyArrays and
  * copyRecords, as keys and look them up based on equality of their contents.
  *
  * TODO For now, this scalarWeakSet accepts only remotables, reflecting the
- * constraints of the underlying JavaScript WeakSet it uses internally. But
- * it should accept the primitives as well, storing them in a separate internal
+ * constraints of the underlying JavaScript WeakSet it uses internally. But it
+ * should accept the primitives as well, storing them in a separate internal
  * set. What makes it "weak" is that it provides no API for enumerating what's
- * there. Though note that this would only enables collection of the
- * remotables, since the other primitives may always appear.
+ * there. Though note that this would only enables collection of the remotables,
+ * since the other primitives may always appear.
  *
  * @template K
  * @param {string} [tag] - tag for debugging

packages/store/src/stores/store-utils.js

@@ -3,24 +3,24 @@ import { M, matches } from '@endo/patterns';
 
 const { Fail, quote: q } = assert;
 
+// TODO: Undate `@endo/patterns` to export the original, and delete the
+// reimplementation here.
 /**
- * Should behave identically to the one in `@endo/patterns`, but
- * reimplemented for now because `@endo/patterns` forgot to export this one.
- * This one is simple enough that I prefer a reimplementation to a deep import.
- * TODO: Undate `@endo/patterns` to export the original, and delete the
- * reimplementation here.
+ * Should behave identically to the one in `@endo/patterns`, but reimplemented
+ * for now because `@endo/patterns` forgot to export this one. This one is
+ * simple enough that I prefer a reimplementation to a deep import.
  *
  * @param {Passable} s
  * @returns {s is CopySet}
  */
 export const isCopySet = s => matches(s, M.set());
 
+// TODO: Undate `@endo/patterns` to export the original, and delete the
+// reimplementation here.
 /**
- * Should behave identically to the one in `@endo/patterns`, but
- * reimplemented for now because `@endo/patterns` forgot to export this one.
- * This one is simple enough that I prefer a reimplementation to a deep import.
- * TODO: Undate `@endo/patterns` to export the original, and delete the
- * reimplementation here.
+ * Should behave identically to the one in `@endo/patterns`, but reimplemented
+ * for now because `@endo/patterns` forgot to export this one. This one is
+ * simple enough that I prefer a reimplementation to a deep import.
  *
  * @param {Passable} m
  * @returns {m is CopyMap}
@@ -43,7 +43,7 @@ export const isCopyMap = m => matches(m, M.map());
  * @param {(k: K, v?: V) => void} assertOkToAdd
  * @param {(k: K) => void} [assertOkToDelete]
  * @param {string} [keyName]
- * @returns {CurrentKeysKit<K,V>}
+ * @returns {CurrentKeysKit<K, V>}
  */
 export const makeCurrentKeysKit = (
   getRawKeys,
@@ -107,13 +107,12 @@ export const makeCurrentKeysKit = (
 harden(makeCurrentKeysKit);
 
 /**
- * Call `provideLazy` to get or make the value associated with the key.
- * If there already is one, return that. Otherwise,
- * call `makeValue(key)`, remember it as the value for
- * that key, and return it.
+ * Call `provideLazy` to get or make the value associated with the key. If there
+ * already is one, return that. Otherwise, call `makeValue(key)`, remember it as
+ * the value for that key, and return it.
  *
  * @template K,V
- * @param {WeakMapStore<K,V>} mapStore
+ * @param {WeakMapStore<K, V>} mapStore
  * @param {K} key
  * @param {(key: K) => V} makeValue
  * @returns {V}
@@ -127,12 +126,11 @@ export const provideLazy = (mapStore, key, makeValue) => {
 harden(provideLazy);
 
 /**
- * Helper for use cases in which the maker function is async.
- * For two provideLazy calls with the same key, one may be making when the
- * other call starts and it would make again.
- * (Then there'd be a collision when the second tries to store
- * the key.) This prevents that race condition by immediately storing a Promise
- * for the maker in an ephemeral store.
+ * Helper for use cases in which the maker function is async. For two
+ * provideLazy calls with the same key, one may be making when the other call
+ * starts and it would make again. (Then there'd be a collision when the second
+ * tries to store the key.) This prevents that race condition by immediately
+ * storing a Promise for the maker in an ephemeral store.
  *
  * When the `store` argument is durable storage, note that it's possible for
  * termination to happen after the make completes and before it reaches durable
@@ -147,17 +145,16 @@ export const makeAtomicProvider = store => {
   const pending = new Map();
 
   /**
-   * Call `provideAsync` to get or make the value associated with the key,
-   * when the maker is asynchronous.
-   * If there already is one, return that. Otherwise,
-   * call `makeValue(key)`, remember it as the value for
-   * that key, and return it.
+   * Call `provideAsync` to get or make the value associated with the key, when
+   * the maker is asynchronous. If there already is one, return that. Otherwise,
+   * call `makeValue(key)`, remember it as the value for that key, and return
+   * it.
    *
    * @param {K} key
-   * @param {(key: K) => Promise<V>} makeValue make the value for the store
-   * if it hasn't been made yet or the last make failed
+   * @param {(key: K) => Promise<V>} makeValue make the value for the store if
+   *   it hasn't been made yet or the last make failed
    * @param {(key: K, value: V) => Promise<void>} [finishValue] runs exactly
-   * once after a new value is added to the store
+   *   once after a new value is added to the store
    * @returns {Promise<V>}
    */
   const provideAsync = (key, makeValue, finishValue) => {