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

package/README.md

@@ -22,36 +22,6 @@ Store adds some additional functionality on top of Map.
 
 See `makeScalarWeakMapStore` for the wrapper around JavaScript's WeakMap abstraction.
 
-# External Store
-
-An External Store is defined by its maker function, and provides abstractions
-that are compatible with large, synchronous secondary storage that can be paged
-in and out of local memory.
-
-```js
-import { makeExternalStore } from '@agoric/store';
-
-// Here is us defining an instance store for 'hello' objects.
-const estore = makeExternalStore((msg = 'Hello') => ({
-  hello(nickname) {
-    return `${msg}, ${nickname}!`;
-  },
-}));
-
-const h = estore.makeInstance('Hi');
-h.hello('friend') === 'Hi, friend!';
-const wm = estore.makeWeakMap('Hello object');
-wm.init(h, 'data');
-// ... time passes and h is paged out and reloaded.
-wm.get(h) === 'data';
-wm.set(h, 'new-data');
-// ... time passes and h is paged out and reloaded.
-map.delete(h);
-```
-
-Note that when you import and use the `makeExternalStore` function, the platform
-you are running on may rewrite your code to use a more scalable implementation
-of that function.  If it is not rewritten, then `makeExternalStore` will use
-`makeMemoryExternalStore`, a full-featured, though in-memory-only
-implementation.  If you don't desire rewriting, then use
-`makeMemoryExternalStore` directly.
+---
+
+Be aware that both `@agoric/base-zone` and this package `@agoric/store` will move from the agoric-sdk repository to the endo repository and likely renamed `@endo/zone` and `@endo/store`. At that time, we will first deprecate the versions here, then replace them with deprecated stubs that reexport from their new home. We hope to eventually remove even these stubs, depending on the compat cost at that time.

package/exported.js

@@ -1 +1 @@
-import './src/types.js';
+// Dummy file for .d.ts twin to declare ambients

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@agoric/store",
-  "version": "0.9.3-u14.0",
+  "version": "0.9.3-u17.0",
   "description": "Wrapper for JavaScript map",
   "type": "module",
   "main": "src/index.js",
   "engines": {
-    "node": ">=14.15.0"
+    "node": "^18.12 || ^20.9"
   },
   "scripts": {
     "build": "exit 0",
@@ -13,7 +13,7 @@
     "test:xs": "exit 0",
     "lint-fix": "yarn lint:eslint --fix",
     "lint": "run-s --continue-on-error lint:*",
-    "lint:types": "tsc -p jsconfig.json",
+    "lint:types": "tsc",
     "lint:eslint": "eslint ."
   },
   "repository": {
@@ -30,17 +30,16 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "^0.6.1-u11wf.0",
-    "@endo/exo": "0.2.2",
-    "@endo/marshal": "0.8.5",
-    "@endo/pass-style": "0.1.3",
-    "@endo/patterns": "0.2.2"
+    "@endo/errors": "^1.2.5",
+    "@endo/exo": "^1.5.3",
+    "@endo/marshal": "^1.5.3",
+    "@endo/pass-style": "^1.4.3",
+    "@endo/patterns": "^1.4.3"
   },
   "devDependencies": {
-    "@agoric/swingset-vat": "^0.32.3-u14.0",
-    "@agoric/time": "^0.3.3-u14.0",
-    "@endo/ses-ava": "0.2.40",
-    "ava": "^5.2.0"
+    "@endo/init": "^1.1.4",
+    "@endo/ses-ava": "^1.2.5",
+    "ava": "^5.3.0"
   },
   "files": [
     "src/",
@@ -52,9 +51,15 @@
   },
   "ava": {
     "files": [
-      "test/**/test-*.js"
+      "test/**/*.test.*"
+    ],
+    "require": [
+      "@endo/init/debug.js"
     ],
     "timeout": "2m"
   },
-  "gitHead": "b3a6f3374cb3bddab39fc6d6f426429cae6c29c6"
+  "typeCoverage": {
+    "atLeast": 89.53
+  },
+  "gitHead": "515c4c0efccfc91b97da30037c10fc4b076851e2"
 }

package/src/index.js

@@ -1,3 +1,18 @@
+/**
+ * @import {MustMatch} from '@agoric/internal';
+ */
+import { mustMatch as typelessMustMatch } from '@endo/patterns';
+
+export { makeScalarWeakSetStore } from './stores/scalarWeakSetStore.js';
+export { makeScalarSetStore } from './stores/scalarSetStore.js';
+export { makeScalarWeakMapStore } from './stores/scalarWeakMapStore.js';
+export { makeScalarMapStore } from './stores/scalarMapStore.js';
+
+export { provideLazy } from './stores/store-utils.js';
+
+// /////////////////////// Deprecated Re-exports ///////////////////////////////
+// Importers should import directly from the packages shown below
+
 export {
   isKey,
   assertKey,
@@ -41,9 +56,15 @@ export {
   isPattern,
   assertPattern,
   matches,
-  mustMatch,
+  isCopySet,
+  isCopyMap,
 } from '@endo/patterns';
 
+// XXX @agoric/store should not depend on @agoric/internal
+// TODO move to Endo
+/** @type {MustMatch} */
+export const mustMatch = typelessMustMatch;
+
 export {
   initEmpty,
   defineExoClass,
@@ -51,14 +72,9 @@ export {
   makeExo,
 } from '@endo/exo';
 
-export { makeScalarWeakSetStore } from './stores/scalarWeakSetStore.js';
-export { makeScalarSetStore } from './stores/scalarSetStore.js';
-export { makeScalarWeakMapStore } from './stores/scalarWeakMapStore.js';
-export { makeScalarMapStore } from './stores/scalarMapStore.js';
-
-export { provideLazy } from './stores/store-utils.js';
-
 // /////////////////////// Deprecated Legacy ///////////////////////////////////
 
 export { makeLegacyMap } from './legacy/legacyMap.js';
 export { makeLegacyWeakMap } from './legacy/legacyWeakMap.js';
+// eslint-disable-next-line import/export
+export * from './types.js';

package/src/legacy/legacyMap.js

@@ -1,37 +1,40 @@
-import { q, Fail } from '@agoric/assert';
+/** @import {LegacyMap, LegacyWeakMap} from '../types.js'; */
 
-import '../types.js';
+// TODO, once migrated to endo, import from @endo/errors instead
+import { Fail, q } from '@endo/errors';
 
 /**
- * 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='key'] - tag for debugging
- * @returns {LegacyMap<K,V>}
+ * @param {string} [tag] - tag for debugging
+ * @returns {LegacyMap<K, V>}
  */
 export const makeLegacyMap = (tag = 'key') => {
   const m = new Map();

package/src/legacy/legacyWeakMap.js

@@ -1,13 +1,15 @@
-import { q, Fail } from '@agoric/assert';
-import '../types.js';
+/** @import {LegacyWeakMap} from '../types.js'; */
+
+// TODO, once migrated to endo, import from @endo/errors instead
+import { Fail, q } from '@endo/errors';
 
 /**
  * See doccomment in the closely related `legacyMap.js` module.
  *
  * @deprecated switch to ScalarWeakMap if possible, WeakMap otherwise
  * @template K,V
- * @param {string} [tag='key'] - tag for debugging
- * @returns {LegacyWeakMap<K,V>}
+ * @param {string} [tag] - tag for debugging
+ * @returns {LegacyWeakMap<K, V>}
  */
 export const makeLegacyWeakMap = (tag = 'key') => {
   /** @type {WeakMap<K & object, V>} */

package/src/stores/scalarMapStore.js

@@ -1,3 +1,4 @@
+import { q } from '@endo/errors';
 import {
   Far,
   assertPassable,
@@ -15,17 +16,21 @@ import {
 import { makeWeakMapStoreMethods } from './scalarWeakMapStore.js';
 import { makeCurrentKeysKit } from './store-utils.js';
 
-const { quote: q } = assert;
+/**
+ * @import {Passable} from '@endo/pass-style';
+ * @import {Key, Pattern} from '@endo/patterns';
+ * @import {MapStore, MapStoreMethods, StoreOptions} from '../types.js';
+ */
 
 /**
  * @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 {MapStoreMethods<K, V>}
  */
 export const makeMapStoreMethods = (
   jsmap,
@@ -77,7 +82,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 +122,19 @@ 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='key'] - the column name for the key
+ * @param {string} [tag] - the column name for the key
  * @param {StoreOptions} [options]
- * @returns {MapStore<K,V>}
+ * @returns {MapStore<any, any>}
  */
 export const makeScalarMapStore = (
   tag = 'key',

package/src/stores/scalarSetStore.js

@@ -1,3 +1,4 @@
+import { q } from '@endo/errors';
 import { Far, filterIterable } from '@endo/pass-style';
 import { compareRank } from '@endo/marshal';
 import {
@@ -10,15 +11,18 @@ import {
 import { makeWeakSetStoreMethods } from './scalarWeakSetStore.js';
 import { makeCurrentKeysKit } from './store-utils.js';
 
-const { quote: q } = assert;
+/**
+ * @import {Key, Pattern} from '@endo/patterns';
+ * @import {SetStore, SetStoreMethods, StoreOptions} from '../types.js';
+ */
 
 /**
- * @template K
+ * @template {Key} K
  * @param {Set<K>} jsset
  * @param {(k: K) => void} assertKeyOkToAdd
  * @param {(k: K) => void} [assertKeyOkToDelete]
  * @param {string} [keyName]
- * @returns {SetStore<K>}
+ * @returns {SetStoreMethods<K>}
  */
 export const makeSetStoreMethods = (
   jsset,
@@ -74,18 +78,18 @@ 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.
  *
  * @template K
- * @param {string} [tag='key'] - tag for debugging
+ * @param {string} [tag] - tag for debugging
  * @param {StoreOptions} [options]
  * @returns {SetStore<K>}
  */

package/src/stores/scalarWeakMapStore.js

@@ -1,17 +1,27 @@
+import { q, Fail } from '@endo/errors';
 import { Far, assertPassable, passStyleOf } from '@endo/pass-style';
-import { getCopyMapEntries, mustMatch, assertPattern } from '@endo/patterns';
-import { isCopyMap } from './store-utils.js';
+import {
+  getCopyMapEntries,
+  mustMatch,
+  assertPattern,
+  isCopyMap,
+} from '@endo/patterns';
 
-const { quote: q, Fail } = assert;
+/**
+ * @import {Key} from '@endo/patterns';
+ * @import {Passable, RemotableObject} from '@endo/pass-style';
+ * @import {WeakMapStore, StoreOptions} from '../types.js';
+ */
 
 /**
- * @template K,V
+ * @template {Key} K
+ * @template {Passable} V
  * @param {WeakMap<K & object, V>} jsmap
  * @param {(k: K, v: V) => void} assertKVOkToAdd
  * @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,
@@ -58,8 +68,13 @@ export const makeWeakMapStoreMethods = (
     },
 
     addAll: entries => {
-      if (isCopyMap(entries)) {
-        entries = getCopyMapEntries(entries);
+      if (typeof entries[Symbol.iterator] !== 'function') {
+        if (Object.isFrozen(entries) && isCopyMap(entries)) {
+          // @ts-expect-error XXX
+          entries = getCopyMapEntries(entries);
+        } else {
+          Fail`provided data source is not iterable: ${entries}`;
+        }
       }
       for (const [key, value] of /** @type {Iterable<[K, V]>} */ (entries)) {
         // Don't assert that the key either does or does not exist.
@@ -71,22 +86,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='key'] - tag for debugging
+ * @param {string} [tag] - tag for debugging
  * @param {StoreOptions} [options]
- * @returns {WeakMapStore<K,V>}
+ * @returns {RemotableObject & WeakMapStore<K, V>}
  */
 export const makeScalarWeakMapStore = (
   tag = 'key',

package/src/stores/scalarWeakSetStore.js

@@ -1,16 +1,24 @@
+import { q, Fail } from '@endo/errors';
 import { Far, passStyleOf } from '@endo/pass-style';
-import { getCopySetKeys, mustMatch, assertPattern } from '@endo/patterns';
-import { isCopySet } from './store-utils.js';
+import {
+  getCopySetKeys,
+  mustMatch,
+  assertPattern,
+  isCopySet,
+} from '@endo/patterns';
 
-const { quote: q, Fail } = assert;
+/**
+ * @import {Key} from '@endo/patterns';
+ * @import {StoreOptions, WeakSetStore, WeakSetStoreMethods} from '@agoric/store';
+ */
 
 /**
- * @template K
+ * @template {Key} K
  * @param {WeakSet<K & object>} jsset
  * @param {(k: K) => void} assertKeyOkToAdd
  * @param {(k: K) => void} [assertKeyOkToDelete]
  * @param {string} [keyName]
- * @returns {WeakSetStore<K>}
+ * @returns {WeakSetStoreMethods<K>}
  */
 export const makeWeakSetStoreMethods = (
   jsset,
@@ -42,8 +50,13 @@ export const makeWeakSetStoreMethods = (
     },
 
     addAll: keys => {
-      if (isCopySet(keys)) {
-        keys = getCopySetKeys(keys);
+      if (typeof keys[Symbol.iterator] !== 'function') {
+        if (Object.isFrozen(keys) && isCopySet(keys)) {
+          // @ts-expect-error XXX
+          keys = getCopySetKeys(keys);
+        } else {
+          Fail`provided data source is not iterable: ${keys}`;
+        }
       }
       for (const key of /** @type {Iterable<K>} */ (keys)) {
         assertKeyOkToAdd(key);
@@ -54,19 +67,19 @@ 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='key'] - tag for debugging
+ * @param {string} [tag] - tag for debugging
  * @param {StoreOptions} [options]
  * @returns {WeakSetStore<K>}
  */