refactor(patterns): improve types. Prepare for compression

endojs · Apr 29, 2024 · 1943903 · 1943903
1 parent 89c9617
commit 1943903
Show file tree

Hide file tree

Showing 16 changed files with 379 additions and 239 deletions.
diff --git a/packages/patterns/src/keys/checkKey.js b/packages/patterns/src/keys/checkKey.js
@@ -20,9 +20,11 @@ import { checkBagEntries, makeBagOfEntries } from './copyBag.js';
 
 const { ownKeys } = Reflect;
 
-/** @import {Checker} from '@endo/marshal' */
-/** @import {Passable} from '@endo/pass-style' */
-/** @import {CopyBag, CopyMap, CopySet, Key} from '../types' */
+/**
+ * @import {Passable} from '@endo/pass-style'
+ * @import {Checker} from '@endo/marshal'
+ * @import {CopyBag, CopyMap, CopySet, Key} from '../types'
+ */
 
 // ////////////////// Primitive and Scalar keys ////////////////////////////////
 
@@ -586,7 +588,7 @@ const checkKeyInternal = (val, check) => {
     }
     case 'error':
     case 'promise': {
-      return check(false, X`A ${q(passStyle)} cannot be a key`);
+      return check(false, X`A ${q(passStyle)} cannot be a key: ${val}`);
     }
     default: {
       // Unexpected tags are just non-keys, but an unexpected passStyle

diff --git a/packages/patterns/src/keys/compareKeys.js b/packages/patterns/src/keys/compareKeys.js
@@ -17,7 +17,7 @@ import {
 } from './checkKey.js';
 import { makeCompareCollection } from './keycollection-operators.js';
 
-/** @import {CopySet} from '../types' */
+/** @import {CopySet, KeyCompare} from '../types.js' */
 
 /**
  * CopySet X is smaller than CopySet Y iff all of these conditions hold:
@@ -86,7 +86,7 @@ const _mapCompare = makeCompareCollection(
 );
 harden(_mapCompare);
 
-/** @type {import('../types').KeyCompare} */
+/** @type {KeyCompare} */
 export const compareKeys = (left, right) => {
   assertKey(left);
   assertKey(right);

diff --git a/packages/patterns/src/keys/copyBag.js b/packages/patterns/src/keys/copyBag.js
@@ -12,10 +12,11 @@ import {
 
 import { X } from '@endo/errors';
 
-/** @import {CopyBag} from '../types' */
-/** @import {FullCompare} from '../types' */
-/** @import {Checker} from '@endo/marshal' */
-/** @import {Passable} from '@endo/pass-style' */
+/**
+ * @import {Passable} from '@endo/pass-style'
+ * @import {Checker} from '@endo/marshal'
+ * @import {CopyBag, FullCompare} from '../types'
+ */
 
 /**
  * @template T

diff --git a/packages/patterns/src/keys/copySet.js b/packages/patterns/src/keys/copySet.js
@@ -13,9 +13,9 @@ import {
 import { X } from '@endo/errors';
 
 /**
- * @import {CopySet, FullCompare} from '../types'
- * @import {Checker} from '@endo/marshal'
  * @import {Passable} from '@endo/pass-style'
+ * @import {Checker} from '@endo/marshal'
+ * @import {CopySet, FullCompare} from '../types'
  */
 
 /**

diff --git a/packages/patterns/src/keys/keycollection-operators.js b/packages/patterns/src/keys/keycollection-operators.js
@@ -8,11 +8,10 @@ import {
 import { makeIterator } from '@endo/common/make-iterator.js';
 import { makeArrayIterator } from '@endo/common/make-array-iterator.js';
 
-/** @import {RankCompare} from '@endo/marshal' */
-/** @import {KeyComparison} from '../types' */
-/** @import {KeyCompare} from '../types' */
-/** @import {FullCompare} from '../types' */
-/** @import {KeyCollection} from '../types' */
+/**
+ * @import {RankCompare} from '@endo/marshal'
+ * @import {Key, KeyCompare, FullCompare, KeyComparison, KeyCollection} from '../types'
+ */
 
 import { q, Fail } from '@endo/errors';
 
@@ -22,10 +21,10 @@ import { q, Fail } from '@endo/errors';
  * rank, into an iterable that resolves those ties using `fullCompare`.
  *
  * @template [V=unknown]
- * @param {Array<[import('../types.js').Key, V]>} entries
+ * @param {Array<[Key, V]>} entries
  * @param {RankCompare} rankCompare
  * @param {FullCompare} fullCompare
- * @returns {IterableIterator<[import('../types.js').Key, V]>}
+ * @returns {IterableIterator<[Key, V]>}
  */
 const generateFullSortedEntries = (entries, rankCompare, fullCompare) => {
   assertRankSorted(entries, rankCompare);
@@ -82,9 +81,9 @@ harden(generateFullSortedEntries);
  * @template [V=unknown]
  * @param {C} c1
  * @param {C} c2
- * @param {(collection: C) => Array<[import('../types.js').Key, V]>} getEntries
+ * @param {(collection: C) => Array<[Key, V]>} getEntries
  * @param {any} absentValue
- * @returns {IterableIterator<[import('../types.js').Key, V | absentValue, V | absentValue]>}
+ * @returns {IterableIterator<[Key, V | absentValue, V | absentValue]>}
  */
 export const generateCollectionPairEntries = (
   c1,
@@ -127,7 +126,7 @@ export const generateCollectionPairEntries = (
   nextY();
   return makeIterator(() => {
     let done = false;
-    /** @type {[import('../types.js').Key, V | absentValue, V | absentValue]} */
+    /** @type {[Key, V | absentValue, V | absentValue]} */
     let value;
     if (xDone && yDone) {
       done = true;
@@ -178,7 +177,7 @@ harden(generateCollectionPairEntries);
  *
  * @template [C=KeyCollection]
  * @template [V=unknown]
- * @param {(collection: C) => Array<[import('../types.js').Key, V]>} getEntries
+ * @param {(collection: C) => Array<[Key, V]>} getEntries
  * @param {any} absentValue
  * @param {KeyCompare} compareValues
  * @returns {(left: C, right: C) => KeyComparison}

diff --git a/packages/patterns/src/keys/merge-bag-operators.js b/packages/patterns/src/keys/merge-bag-operators.js
@@ -7,9 +7,10 @@ import {
 import { q, Fail } from '@endo/errors';
 import { assertNoDuplicateKeys, makeBagOfEntries } from './copyBag.js';
 
-/** @import {KeyComparison} from '../types' */
-/** @import {FullCompare} from '../types' */
-/** @import {RankCompare} from '@endo/marshal' */
+/**
+ * @import {RankCompare} from '@endo/marshal'
+ * @import {FullCompare} from '../types'
+ */
 
 // Based on merge-set-operators.js, but altered for the bag representation.
 // TODO share more code with that file and keycollection-operators.js.

diff --git a/packages/patterns/src/keys/merge-set-operators.js b/packages/patterns/src/keys/merge-set-operators.js
@@ -7,9 +7,10 @@ import {
 import { q, Fail } from '@endo/errors';
 import { assertNoDuplicates, makeSetOfElements } from './copySet.js';
 
-/** @import {KeyComparison} from '../types' */
-/** @import {FullCompare} from '../types' */
-/** @import {RankCompare} from '@endo/marshal' */
+/**
+ * @import {RankCompare} from '@endo/marshal'
+ * @import {FullCompare, KeyComparison} from '../types'
+ */
 
 // TODO share more code with keycollection-operators.js.
 

diff --git a/packages/patterns/src/patterns/getGuardPayloads.js b/packages/patterns/src/patterns/getGuardPayloads.js
@@ -16,7 +16,9 @@ import {
 } from './patternMatchers.js';
 import { getCopyMapKeys, makeCopyMap } from '../keys/checkKey.js';
 
-/** @import {AwaitArgGuard, AwaitArgGuardPayload, InterfaceGuard, InterfaceGuardPayload, MethodGuard, MethodGuardPayload} from '../types.js' */
+/**
+ * @import {AwaitArgGuard, AwaitArgGuardPayload, InterfaceGuard, InterfaceGuardPayload, MethodGuard, MethodGuardPayload} from '../types.js'
+ */
 
 // The get*GuardPayload functions exist to adapt to the worlds both
 // before and after https://github.com/endojs/endo/pull/1712 . When