@agoric/store - npm Package Compare versions

Comparing version 0.6.8 to 0.6.9-dev-3c4b2fb.0

exported.js

 import './src/types.js';
+
+// TODO The following line should be deleted. It exports the type
+// `MatchHelper` which is not used outside this store package. Without this
+// line, this store package lints fine. But linting the governance
+// package complains that it cannot find the type `MatchHelper`.
+// I don't know why. I even tried adding
+//   import '@agoric/store/exported.js';
+// to the modules in governance that import from '@agoric/store',
+// but it did not help.
+//
+// Even with this line, the solo package still has the same complaint.
+// So instead I moved the MatchHelper type, which should be internal,
+// to types.js. See the comment there.
+import './src/patterns/internal-types.js';

package.json

 {
   "name": "@agoric/store",
-  "version": "0.6.8",
+  "version": "0.6.9-dev-3c4b2fb.0+3c4b2fb",
   "description": "Wrapper for JavaScript map",
@@ -34,7 +34,9 @@ "type": "module",
   "dependencies": {
-    "@agoric/assert": "^0.3.15",
-    "@agoric/marshal": "^0.5.0"
+    "@agoric/assert": "0.3.16-dev-3c4b2fb.0+3c4b2fb",
+    "@agoric/eventual-send": "0.14.1-dev-3c4b2fb.0+3c4b2fb",
+    "@agoric/marshal": "0.5.1-dev-3c4b2fb.0+3c4b2fb",
+    "@agoric/promise-kit": "0.2.30-dev-3c4b2fb.0+3c4b2fb"
   },
   "devDependencies": {
-    "@agoric/swingset-vat": "^0.24.1",
+    "@agoric/swingset-vat": "0.24.2-dev-3c4b2fb.0+3c4b2fb",
     "ava": "^3.12.1"
@@ -68,3 +70,3 @@ },
   },
-  "gitHead": "2b0ce50c0dcb73674fee5587f7342cde2e06d09f"
+  "gitHead": "3c4b2fb7126f82211bacd0b4c5a1e0a7ea595ed9"
 }

src/index.js

@@ -1,9 +0,27 @@
-export { makeScalarMap, makeScalarMap as makeStore } from './scalarMap.js';
+// @ts-check
+
+export { isKey, assertKey } from './keys/checkKey.js';
+export { keyLT, keyLTE, keyEQ, keyGTE, keyGT } from './keys/compareKeys.js';
+
+export { makePatternKit } from './patterns/patternMatchers.js';
+export { compareRank } from './patterns/rankOrder.js';
+
+export { makeScalarWeakSetStore } from './stores/scalarWeakSetStore.js';
+export { makeScalarSetStore } from './stores/scalarSetStore.js';
 export {
-  makeScalarWeakMap,
-  makeScalarWeakMap as makeWeakStore,
-} from './scalarWeakMap.js';
+  makeScalarWeakMapStore,
+  makeScalarWeakMapStore as makeScalarWeakMap, // Deprecated legacy
+  makeScalarWeakMapStore as makeWeakStore, // Deprecated legacy
+} from './stores/scalarWeakMapStore.js';
+export {
+  makeScalarMapStore,
+  makeScalarMapStore as makeScalarMap, // Deprecated legacy
+  makeScalarMapStore as makeStore, // Deprecated legacy
+} from './stores/scalarMapStore.js';
+
+// /////////////////////// Deprecated Legacy ///////////////////////////////////
+
 // export default as well as makeLegacy* only for compatibility
 // during the transition.
-export { makeLegacyMap, makeLegacyMap as default } from './legacyMap.js';
-export { makeLegacyWeakMap } from './legacyWeakMap.js';
+export { makeLegacyMap, makeLegacyMap as default } from './legacy/legacyMap.js';
+export { makeLegacyWeakMap } from './legacy/legacyWeakMap.js';

src/types.js

@@ -7,25 +7,91 @@ // @ts-check
 /**
+ * @typedef {Passable} Key
+ */
+
+/**
+ * @typedef {Passable} Pattern
+ * Patterns can be either Keys or Matchers
+ */
+
+/**
+ * @typedef {CopyTagged} CopySet
+ */
+
+/**
+ * @typedef {CopyTagged} CopyMap
+ */
+
+/**
+ * @typedef {CopyTagged} Matcher
+ */
+
+/**
  * @typedef {Object} StoreOptions
- *
- * @property {boolean=} longLived Which way to optimize. True means that we
- * expect this store to outlive most of its keys, in which
- * case we internally may use a `WeakMap`. Otherwise we internally may
- * use a `Map`.
- * Defaults to true, so please mark short lived stores explicitly
+ * 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 {Pattern=} schema The store will reject
+ * the insertion of any content that does not match the schema pattern.
+ * For a SetStore, this is a key pattern.
+ * For a MapStore, this is an entry pattern,
+ * i.e., a pattern over `[key,value]` pairs.
+ * Defaults to `M.any()`.
  */
 
+/** @typedef {"forward" | "reverse"} Direction */
+
 /**
- * @template {Structure} K
- * @template {Passable} V
- * @typedef {Object} Store
- *
- * @property {(key: any) => boolean} has
+ * @template K
+ * @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 map
- * @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 map. For example a scalarMap only allows
- * primitives and remotables.
+ * 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.
+ */
+
+/**
+ * @template K
+ * @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 {(keyPattern?: Pattern) => K[]} keys
+ * @property {(keyPattern?: Pattern) => CopySet} snapshot
+ * @property {(copySet: CopySet) => void} addAll
+ * @property {(keyPattern?: Pattern,
+ *             direction?: Direction
+ * ) => Iterable<K>} cursor
+ */
+
+/**
+ * @template K,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
@@ -35,21 +101,16 @@ * Set the key. Throws if not found.
  * Remove the key. Throws if not found.
- * @property {() => K[]} keys - Return an array of keys
- * @property {() => V[]} values - Return an array of values
- * @property {() => [K, V][]} entries - Return an array of entries
  */
 
 /**
- * @template {Structure} K
- * @template {Passable} V
- * @typedef {Object} WeakStore
- *
+ * @template K,V
+ * @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, value: V) => void} init
- * Initialize the key only if it doesn't already exist. The key must
- * be one allowed by this map. For example a scalarMap only allows
- * primitives and remotables. For now, a scalarWeakMap allows remotables.
  * @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
@@ -59,17 +120,53 @@ * Set the key. Throws if not found.
  * Remove the key. Throws if not found.
+ * @property {(keyPattern?: Pattern) => K[]} keys
+ * @property {(valuePattern?: Pattern) => V[]} values
+ * @property {(entryPattern?: Pattern) => [K,V][]} entries
+ * @property {(entryPattern?: Pattern) => CopyMap} snapshot
+ * @property {(copyMap: CopyMap) => void} addAll
+ * @property {(entryPattern?: Pattern,
+ *             direction?: Direction
+ * ) => Iterable<[K,V]>} cursor
  */
 
-// ////////////////////////////////////////////////////////////////////
+// ///////////////////////// Deprecated Legacy /////////////////////////////////
 
 /**
  * @template K,V
+ * @typedef {WeakMapStore<K,V>} WeakStore
+ * Deprecated type name `WeakStore`. Use `WeakMapStore` instead.
+ */
+
+/**
+ * @template K,V
+ * @typedef {Object} Store
+ * Deprecated type name `Store`. Use `MapStore` instead.
+ * @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 {(keyPattern?: Pattern) => K[]} keys
+ * @property {(valuePattern?: Pattern) => V[]} values
+ * @property {(entryPattern?: Pattern) => [K,V][]} entries
+ */
+
+/**
+ * @template K,V
  * @typedef {Object} LegacyWeakMap
- *
+ * LegacyWeakMap is deprecated. Use WeakMapStore instead.
  * @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) => V} get
- * Return a value for the key. Throws if not found.
  * @property {(key: K, value: V) => void} set
@@ -84,5 +181,160 @@ * Set the key. Throws if not found.
  * @callback MakeLegacyWeakMap
- *
  * @param {string} [keyName='key'] - the column name for the key
  * @returns {LegacyWeakMap}
  */
+
+// /////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @callback CompareRank
+ * Returns `-1`, `0`, or `1` depending on whether the rank of `left`
+ * is before, tied-with, or after the rank of `right`.
+ *
+ * This comparison function is valid as argument to
+ * `Array.prototype.sort`. This is often described as a "total order"
+ * but, depending on your definitions, this is technically incorrect
+ * because it may return `0` to indicate that two distinguishable elements,
+ * like `-0` and `0`, are tied, i.e., are in the same equivalence class
+ * as far as this ordering is concerned. If each such equivalence class is
+ * a *rank* and ranks are disjoint, then this "rank order" is a
+ * total order among these ranks. In mathematics this goes by several
+ * other names such as "total preorder".
+ *
+ * This function establishes a total rank order over all passables.
+ * To do so it makes arbitrary choices, such as that all strings
+ * are after all numbers. Thus, this order is not intended to be
+ * used directly as a comparison with useful semantics. However, it must be
+ * closely enough related to such comparisons to aid in implementing
+ * lookups based on those comparisons. For example, in order to get a total
+ * order among ranks, we put `NaN` after all other JavaScript "number" values.
+ * But otherwise, we order JavaScript numbers by magnitude,
+ * with `-0` tied with `0`. A semantically useful ordering of JavaScript number
+ * values, i.e., IEEE floating point values, would compare magnitudes, and
+ * so agree with the rank ordering everywhere except `NaN`. An array sorted by
+ * rank would enable range queries by magnitude.
+ * @param {Passable} left
+ * @param {Passable} right
+ * @returns {-1 | 0 | 1}
+ */
+
+// ///////////////////// Should be internal only types /////////////////////////
+
+/**
+ * @typedef {[string, string]} RankCover
+ */
+
+/**
+ * @typedef {[number, number]} IndexCover
+ */
+
+/**
+ * @callback GetPassStyleCover
+ * Associate with each passStyle a RankCover that may be an overestimate,
+ * and whose results therefore need to be filtered down. For example, because
+ * there is not a smallest or biggest bigint, bound it by `NaN` (the last place
+ * number) and `''` (the empty string, which is the first place string). Thus,
+ * a range query using this range may include these values, which would then
+ * need to be filtered out.
+ * @param {PassStyle} passStyle
+ * @returns {RankCover}
+ */
+
+/**
+ * @callback GetIndexCover
+ * @param {Passable[]} sorted
+ * @param {CompareRank} compare
+ * @param {RankCover} rankCover
+ * @returns {IndexCover}
+ */
+
+/**
+ * @callback CoveredEntries
+ * @param {Passable[]} sorted
+ * @param {IndexCover} indexCover
+ * @returns {Iterable<[number, Passable]>}
+ */
+
+/**
+ * @callback CheckMatches
+ * @param {Passable} specimen
+ * @param {Pattern} pattern
+ * @param {Checker=} check
+ */
+
+/**
+ * @callback CheckPattern
+ * @param {Passable} allegedPattern
+ * @param {Checker=} check
+ * @returns {boolean}
+ */
+
+/**
+ * @callback CheckKeyPattern
+ * @param {Passable} allegedPattern
+ * @param {Checker=} check
+ * @returns {boolean}
+ */
+
+/**
+ * @callback KeyToDBKey
+ * @param {Passable} key
+ * @returns {string}
+ */
+
+/**
+ * @callback GetRankCover
+ * @param {Pattern} pattern
+ * @param {KeyToDBKey} encodeKey
+ * @returns {RankCover}
+ */
+
+/**
+ * @typedef {Object} PatternMatcher
+ * @property {GetRankCover} getRankCover
+ */
+
+// /////////////////////////////////////////////////////////////////////////////
+
+// TODO
+// The following commented out type should be in internal-types.js, since the
+// `MatchHelper` type is purely internal to this package. However,
+// in order to get the governance and solo packages both to pass lint,
+// I moved the type declaration itself to types.js. See the comments in
+// in internal-types.js and exports.js
+
+/**
+ * @typedef {Object} MatchHelper
+ * This factors out only the parts specific to each kind of Matcher. It is
+ * encapsulated, and its methods can make the stated unchecker assumptions
+ * enforced by the common calling logic.
+ *
+ * @property {(allegedPayload: Passable,
+ *             check?: Checker
+ * ) => boolean} checkIsMatcherPayload
+ * Assumes this is the payload of a CopyTagged with the corresponding
+ * matchTag. Is this a valid payload for a Matcher with that tag?
+ *
+ * @property {(specimen: Passable,
+ *             matcherPayload: Passable,
+ *             check?: Checker
+ * ) => boolean} checkMatches
+ * Assuming a valid Matcher of this type with `matcherPayload` as its
+ * payload, does this specimen match that Matcher?
+ *
+ * @property {(
+ *   payload: Passable,
+ *   encodeKey: KeyToDBKey
+ * ) => RankCover} getRankCover
+ * Assumes this is the payload of a CopyTagged with the corresponding
+ * matchTag. Return a RankCover to bound from below and above,
+ * in rank order, all possible Passables that would match this Matcher.
+ * The left element must be before or the same rank as any possible
+ * matching specimen. The right element must be after or the same
+ * rank as any possible matching specimen.
+ *
+ * @property {(allegedPattern: Passable,
+ *             check?: Checker
+ * ) => boolean} checkKeyPattern
+ * Assumes this is the payload of a CopyTagged with the corresponding
+ * matchTag. Is this a valid pattern for use as a query key or key schema?
+ */

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Manifest confusion

Supply chain risk

This package has inconsistent metadata. This could be malicious or caused by an error when publishing the package.

Found 1 instance in 1 package

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

120539

increased by208.98%

Number of package files

22

increased by83.33%

Lines of code

2707

increased by651.94%

Worsened metrics

Dependency count

4

increased by100%

Number of medium supply chain risk alerts

2

increased by100%

Dependency changes

• + Added@agoric/eventual-send@0.14.1-dev-3c4b2fb.0+3c4b2fb

• + Added@agoric/promise-kit@0.2.30-dev-3c4b2fb.0+3c4b2fb

• - Removed@agoric/assert@0.3.16(transitive)

• - Removed@agoric/eventual-send@0.14.1(transitive)

• - Removed@agoric/marshal@0.5.0(transitive)

• - Removed@agoric/nat@4.1.0(transitive)

• - Removed@agoric/promise-kit@0.2.29(transitive)

• Updated@agoric/assert@0.3.16-dev-3c4b2fb.0+3c4b2fb

• Updated@agoric/marshal@0.5.1-dev-3c4b2fb.0+3c4b2fb