@agoric/store 0.9.3-u14.0 → 0.9.3-u17.0

package/src/stores/store-utils.js

@@ -1,34 +1,41 @@
+import { Fail, q } from '@endo/errors';
 import { Far } from '@endo/marshal';
 import { M, matches } from '@endo/patterns';
 
-const { Fail, quote: q } = assert;
+/**
+ * @import {RankCompare} from '@endo/marshal';
+ * @import {MapStore, WeakMapStore} from '../types.js';
+ * @import {Passable} from '@endo/pass-style';
+ * @import {Key} from '@endo/patterns';
+ */
 
+// 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
+ * @param {unknown} 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
+ * @param {unknown} m
  * @returns {m is CopyMap}
  */
 export const isCopyMap = m => matches(m, M.map());
 
 /**
- * @template K,V
+ * @template {Key} K
+ * @template {Passable} V
  * @typedef {object} CurrentKeysKit
  * @property {(k: K, v?: V) => void} assertUpdateOnAdd
  * @property {(k: K) => void} assertUpdateOnDelete
@@ -36,14 +43,15 @@ export const isCopyMap = m => matches(m, M.map());
  */
 
 /**
- * @template K,V
+ * @template {Key} K
+ * @template {Passable} V
  * @param {() => Iterable<K>} getRawKeys
  * @param {(k: K) => boolean} checkHas
  * @param {RankCompare} compare
  * @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 +115,13 @@ 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
+ * @template {Key} K
+ * @template {Passable} V
+ * @param {WeakMapStore<K, V>} mapStore
  * @param {K} key
  * @param {(key: K) => V} makeValue
  * @returns {V}
@@ -127,19 +135,18 @@ 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
  * storage.
  *
- * @template K
- * @template V
+ * @template {Key} K
+ * @template {Passable} V
  * @param {WeakMapStore<K, V>} store
  */
 export const makeAtomicProvider = store => {
@@ -147,17 +154,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) => {
@@ -190,13 +196,14 @@ export const makeAtomicProvider = store => {
 };
 harden(makeAtomicProvider);
 /**
- * @template K
- * @template V
+ * @template {Key} K
+ * @template {Passable} V
  * @typedef {ReturnType<typeof makeAtomicProvider<K, V>>} AtomicProvider<K, V>
  */
 
 /**
- * @template K, V
+ * @template {Key} K
+ * @template {Passable} V
  * @param {MapStore<K, V[]>} mapStore
  * @param {K} key
  * @param {V} item

package/src/types.js

@@ -1,264 +1,180 @@
-/// <reference types="ses"/>
+/// <reference types="ses" />
 
-/** @typedef {import('@endo/marshal').Passable} Passable */
-/** @typedef {import('@endo/marshal').PassStyle} PassStyle */
-/** @typedef {import('@endo/marshal').CopyTagged} CopyTagged */
-/** @template T @typedef {import('@endo/marshal').CopyRecord<T>} CopyRecord */
-/** @template T @typedef {import('@endo/marshal').CopyArray<T>} CopyArray */
-/** @typedef {import('@endo/marshal').Checker} Checker */
-/** @typedef {import('@endo/marshal/src/rankOrder').RankCompare} RankCompare */
-/** @typedef {import('@endo/marshal/src/rankOrder').RankComparison} RankComparison */
-
-// /////////////////////////////////////////////////////////////////////////////
-// Placeholder redundant types, to be imported from `@endo/patterns` instead.
-
-/**
- * @typedef {Passable} Key
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
-
-/**
- * @typedef {Passable} Pattern
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
-
-/**
- * @template {Key} [K=Key]
- * @typedef {CopyTagged & {
- *   [Symbol.toStringTag]: 'copySet',
- *   payload: Array<K>,
- * }} CopySet
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
-
-/**
- * @template {Key} [K=Key]
- * @typedef {CopyTagged & {
- *   [Symbol.toStringTag]: 'copyBag',
- *   payload: Array<[K, bigint]>,
- * }} CopyBag
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
+// Ensure this is a module.
+export {};
 
 /**
- * @template {Key} [K=Key]
- * @template {Passable} [V=Passable]
- * @typedef {CopyTagged & {
- *   [Symbol.toStringTag]: 'copyMap',
- *   payload: { keys: Array<K>, values: Array<V> },
- * }} CopyMap
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
-
-/**
- * @typedef {object} GuardMakers
- * @property {<M extends Record<any, any>>(interfaceName: string,
- *             methodGuards: M,
- *             options?: {sloppy?: boolean}
- * ) => InterfaceGuard} interface
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- *
- * @property {(...argGuards: ArgGuard[]) => MethodGuardMaker} call Guard a synchronous call
+ * Note TODO https://github.com/endojs/endo/issues/1488
  *
- * @property {(...argGuards: ArgGuard[]) => MethodGuardMaker} callWhen Guard an async call
- *
- * @property {(argGuard: ArgGuard) => ArgGuard} await Guard an await
- */
-
-/**
- * @typedef {(...args: any[]) => any} Method
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
-
-/**
- * @typedef {{
- * klass: 'Interface',
- * interfaceName: string,
- * methodGuards: Record<string | symbol, MethodGuard>
- * sloppy?: boolean
- * }} InterfaceGuard
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
-
-/**
- * @typedef {any} MethodGuardMaker
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
-
-/**
- * @typedef {{ klass: 'methodGuard', callKind: 'sync' | 'async', returnGuard: unknown }} MethodGuard
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
-
-/**
- * @typedef {any} ArgGuard
- * TODO placeholder. Figure out how to import from `@endo/patterns` instead
- */
-
-// /////////////////////////////////////////////////////////////////////////////
-
-/**
- * @typedef {object} StoreOptions
- * Of the dimensions on which KeyedStores can differ, we only represent a few
- * of them as standard options. A given store maker should document which
- * options it supports, as well as its positions on dimensions for which it
- * does not support options.
- * @property {boolean} [longLived=true] Which way to optimize a weak store. True means
- * that we expect this weak store to outlive most of its keys, in which
- * case we internally may use a JavaScript `WeakMap`. Otherwise we internally
- * may use a JavaScript `Map`.
- * Defaults to true, so please mark short lived stores explicitly.
- * @property {boolean} [durable=false]  The contents of this store survive termination
+ * @import {Passable, RemotableObject} from '@endo/pass-style'
+ * @import {CopySet, CopyMap, Pattern} from '@endo/patterns'
+ * @import {Key} from '@endo/patterns'
+ */
+
+/**
+ * @typedef {object} StoreOptions Of the dimensions on which KeyedStores can
+ *   differ, we only represent a few of them as standard options. A given store
+ *   maker should document which options it supports, as well as its positions
+ *   on dimensions for which it does not support options.
+ * @property {boolean} [longLived] Which way to optimize a weak store. True
+ *   means that we expect this weak store to outlive most of its keys, in which
+ *   case we internally may use a JavaScript `WeakMap`. Otherwise we internally
+ *   may use a JavaScript `Map`. Defaults to true, so please mark short lived
+ *   stores explicitly.
+ * @property {boolean} [durable] The contents of this store survive termination
  *   of its containing process, allowing for restart or upgrade but at the cost
- *   of forbidding storage of references to ephemeral data.  Defaults to false.
- * @property {boolean} [fakeDurable=false]  This store pretends to be a durable store
+ *   of forbidding storage of references to ephemeral data. Defaults to false.
+ * @property {boolean} [fakeDurable] This store pretends to be a durable store
  *   but does not enforce that the things stored in it actually be themselves
  *   durable (whereas an actual durable store would forbid storage of such
- *   items).  This is in service of allowing incremental transition to use of
+ *   items). This is in service of allowing incremental transition to use of
  *   durable stores, to enable normal operation and testing when some stuff
- *   intended to eventually be durable has not yet been made durable.  A store
+ *   intended to eventually be durable has not yet been made durable. A store
  *   marked as fakeDurable will appear to operate normally but any attempt to
- *   upgrade its containing vat will fail with an error.
+ *   upgrade its containing vat will fail with an error. Defaults to false.
  * @property {Pattern} [keyShape]
  * @property {Pattern} [valueShape]
  */
 
 /**
  * Most store methods are in one of three categories
- *   * lookup methods (`has`,`get`)
- *   * update methods (`add`,`init`,`set`,`delete`,`addAll`)
- *   * query methods (`snapshot`,`keys`,`values`,`entries`,`getSize`)
- *   * query-update methods (`clear`)
  *
- * WeakStores have the lookup and update methods but not the query
- * or query-update methods.
- * Non-weak Stores are like their corresponding WeakStores, but with the
- * additional query and query-update methods.
- */
-
-/**
- * @template {Key & object} [K=Key]
- * @typedef {object} WeakSetStore
- * @property {(key: K) => boolean} has
- * Check if a key exists. The key can be any JavaScript value, though the
- * answer will always be false for keys that cannot be found in this store.
- * @property {(key: K) => void} add
- * Add the key to the set if it is not already there. Do nothing silently if
- * already there.
- * The key must be one allowed by this store. For example a scalar store only
- * allows primitives and remotables.
- * @property {(key: K) => void} delete
- * Remove the key. Throws if not found.
- * @property {(keys: CopySet<K> | Iterable<K>) => void} addAll
- */
-
-/**
- * @template {Key} [K=Key]
- * @typedef {object} SetStore
- * @property {(key: K) => boolean} has
- * Check if a key exists. The key can be any JavaScript value, though the
- * answer will always be false for keys that cannot be found in this store.
- * @property {(key: K) => void} add
- * Add the key to the set if it is not already there. Do nothing silently if
- * already there.
- * The key must be one allowed by this store. For example a scalar store only
- * allows primitives and remotables.
- * @property {(key: K) => void} delete
- * Remove the key. Throws if not found.
- * @property {(keys: CopySet<K> | Iterable<K>) => void} addAll
+ * - lookup methods (`has`,`get`)
+ * - update methods (`add`,`init`,`set`,`delete`,`addAll`)
+ * - query methods (`snapshot`,`keys`,`values`,`entries`,`getSize`)
+ * - query-update methods (`clear`)
+ *
+ * WeakStores have the lookup and update methods but not the query or
+ * query-update methods. Non-weak Stores are like their corresponding
+ * WeakStores, but with the additional query and query-update methods.
+ */
+
+// TODO use Key for K
+/**
+ * @template K
+ * @typedef {object} WeakSetStoreMethods
+ * @property {(key: K) => boolean} has Check if a key exists. The key can be any
+ *   JavaScript value, though the answer will always be false for keys that
+ *   cannot be found in this store.
+ * @property {(key: K) => void} add Add the key to the set if it is not already
+ *   there. Do nothing silently if already there. The key must be one allowed by
+ *   this store. For example a scalar store only allows primitives and
+ *   remotables.
+ * @property {(key: K) => void} delete Remove the key. Throws if not found.
+ * @property {(keys: CopySet<any> | Iterable<K>) => void} addAll
+ */
+/**
+ * @template K
+ * @typedef {RemotableObject & WeakSetStoreMethods<K>} WeakSetStore
+ */
+
+// TODO use Key for K
+/**
+ * @template K
+ * @typedef {object} SetStoreMethods
+ * @property {(key: K) => boolean} has Check if a key exists. The key can be any
+ *   JavaScript value, though the answer will always be false for keys that
+ *   cannot be found in this store.
+ * @property {(key: K) => void} add Add the key to the set if it is not already
+ *   there. Do nothing silently if already there. The key must be one allowed by
+ *   this store. For example a scalar store only allows primitives and
+ *   remotables.
+ * @property {(key: K) => void} delete Remove the key. Throws if not found.
+ * @property {(keys: CopySet<any> | Iterable<K>) => void} addAll
  * @property {(keyPatt?: Pattern) => Iterable<K>} keys
  * @property {(keyPatt?: Pattern) => Iterable<K>} values
- * @property {(keyPatt?: Pattern) => CopySet<K>} snapshot
+ * @property {(keyPatt?: Pattern) => CopySet<any>} snapshot
  * @property {(keyPatt?: Pattern) => number} getSize
  * @property {(keyPatt?: Pattern) => void} clear
  */
-
 /**
- * @template {Key & object} [K=Key]
- * @template {Passable} [V=Passable]
- * @typedef {object} WeakMapStore
- * @property {(key: K) => boolean} has
- * Check if a key exists. The key can be any JavaScript value, though the
- * answer will always be false for keys that cannot be found in this store.
- * @property {(key: K) => V} get
- * Return a value for the key. Throws if not found.
- * @property {(key: K, value: V) => void} init
- * Initialize the key only if it doesn't already exist.
- * The key must be one allowed by this store. For example a scalar store only
- * allows primitives and remotables.
- * @property {(key: K, value: V) => void} set
- * Set the key. Throws if not found.
- * @property {(key: K) => void} delete
- * Remove the key. Throws if not found.
- * @property {(entries: CopyMap<K,V> | Iterable<[K,V]>) => void} addAll
+ * @template K
+ * @typedef {RemotableObject & SetStoreMethods<K>} SetStore
  */
 
+// TODO use Key for K
+// TODO use Passable for V
 /**
- * @template {Key} [K=Key]
- * @template {Passable} [V=Passable]
- * @typedef {object} MapStore
- * @property {(key: K) => boolean} has
- * Check if a key exists. The key can be any JavaScript value, though the
- * answer will always be false for keys that cannot be found in this map
- * @property {(key: K) => V} get
- * Return a value for the key. Throws if not found.
- * @property {(key: K, value: V) => void} init
- * Initialize the key only if it doesn't already exist.
- * The key must be one allowed by this store. For example a scalar store only
- * allows primitives and remotables.
- * @property {(key: K, value: V) => void} set
- * Set the key. Throws if not found.
- * @property {(key: K) => void} delete
- * Remove the key. Throws if not found.
- * @property {(entries: CopyMap<K,V> | Iterable<[K,V]>) => void} addAll
+ * @template K
+ * @template V
+ * @typedef {object} WeakMapStore
+ * @property {(key: K) => boolean} has Check if a key exists. The key can be any
+ *   JavaScript value, though the answer will always be false for keys that
+ *   cannot be found in this store.
+ * @property {(key: K) => V} get Return a value for the key. Throws if not
+ *   found.
+ * @property {(key: K, value: V) => void} init Initialize the key only if it
+ *   doesn't already exist. The key must be one allowed by this store. For
+ *   example a scalar store only allows primitives and remotables.
+ * @property {(key: K, value: V) => void} set Set the key. Throws if not found.
+ * @property {(key: K) => void} delete Remove the key. Throws if not found.
+ * @property {(entries: CopyMap<any, any> | Iterable<[K, V]>) => void} addAll
+ */
+
+// TODO use Key for K
+// TODO use Passable for V
+/**
+ * @template K
+ * @template V
+ * @typedef {object} MapStoreMethods
+ * @property {(key: K) => boolean} has Check if a key exists. The key can be any
+ *   JavaScript value, though the answer will always be false for keys that
+ *   cannot be found in this map
+ * @property {(key: K) => V} get Return a value for the key. Throws if not
+ *   found.
+ * @property {(key: K, value: V) => void} init Initialize the key only if it
+ *   doesn't already exist. The key must be one allowed by this store. For
+ *   example a scalar store only allows primitives and remotables.
+ * @property {(key: K, value: V) => void} set Set the key. Throws if not found.
+ * @property {(key: K) => void} delete Remove the key. Throws if not found.
+ * @property {(entries: CopyMap<any, Passable> | Iterable<[K, V]>) => void} addAll
  * @property {(keyPatt?: Pattern, valuePatt?: Pattern) => Iterable<K>} keys
  * @property {(keyPatt?: Pattern, valuePatt?: Pattern) => Iterable<V>} values
+ * @property {(keyPatt?: Pattern, valuePatt?: Pattern) => Iterable<[K, V]>} entries
  * @property {(
  *   keyPatt?: Pattern,
- *   valuePatt?: Pattern
- * ) => Iterable<[K,V]>} entries
- * @property {(keyPatt?: Pattern, valuePatt?: Pattern) => CopyMap<K,V>} snapshot
+ *   valuePatt?: Pattern,
+ * ) => CopyMap<any, Passable>} snapshot
  * @property {(keyPatt?: Pattern, valuePatt?: Pattern) => number} getSize
  * @property {(keyPatt?: Pattern, valuePatt?: Pattern) => void} clear
  */
-
-// ///////////////////////// Deprecated Legacy /////////////////////////////////
-
 /**
- * @template K,V
- * @typedef {object} LegacyWeakMap
- * LegacyWeakMap is deprecated. Use WeakMapStore instead if possible.
- * @property {(key: K) => boolean} has
- * Check if a key exists
- * @property {(key: K) => V} get
- * Return a value for the key. Throws if not found.
- * @property {(key: K, value: V) => void} init
- * Initialize the key only if it
- * doesn't already exist
- * @property {(key: K, value: V) => void} set
- * Set the key. Throws if not found.
- * @property {(key: K) => void} delete
- * Remove the key. Throws if not found.
+ * @template [K=any]
+ * @template [V=any]
+ * @typedef {RemotableObject & MapStoreMethods<K, V>} MapStore
  */
 
+// ///////////////////////// Deprecated Legacy /////////////////////////////////
+
 /**
- * @template K,V
- * @typedef {object} LegacyMap
- * LegacyMap is deprecated. Use MapStore instead if possible.
- * @property {(key: K) => boolean} has
- * Check if a key exists
- * @property {(key: K) => V} get
- * Return a value for the key. Throws if not found.
- * @property {(key: K, value: V) => void} init
- * Initialize the key only if it
- * doesn't already exist
- * @property {(key: K, value: V) => void} set
- * Set the key. Throws if not found.
- * @property {(key: K) => void} delete
- * Remove the key. Throws if not found.
+ * @template K
+ * @template V
+ * @typedef {object} LegacyWeakMap LegacyWeakMap is deprecated. Use WeakMapStore
+ *   instead if possible.
+ * @property {(key: K) => boolean} has Check if a key exists
+ * @property {(key: K) => V} get Return a value for the key. Throws if not
+ *   found.
+ * @property {(key: K, value: V) => void} init Initialize the key only if it
+ *   doesn't already exist
+ * @property {(key: K, value: V) => void} set Set the key. Throws if not found.
+ * @property {(key: K) => void} delete Remove the key. Throws if not found.
+ */
+
+/**
+ * @template K
+ * @template V
+ * @typedef {object} LegacyMap LegacyMap is deprecated. Use MapStore instead if
+ *   possible.
+ * @property {(key: K) => boolean} has Check if a key exists
+ * @property {(key: K) => V} get Return a value for the key. Throws if not
+ *   found.
+ * @property {(key: K, value: V) => void} init Initialize the key only if it
+ *   doesn't already exist
+ * @property {(key: K, value: V) => void} set Set the key. Throws if not found.
+ * @property {(key: K) => void} delete Remove the key. Throws if not found.
  * @property {() => Iterable<K>} keys
  * @property {() => Iterable<V>} values
- * @property {() => Iterable<[K,V]>} entries
+ * @property {() => Iterable<[K, V]>} entries
  * @property {() => number} getSize
  * @property {() => void} clear
  */