Skip to content

Commit 258dfc6

Browse files
erightserights
authored
refactor(patterns): improve pattern types. Flatten @imports (#2256)
closes: #XXXX refs: #2248 #1584 Agoric/agoric-sdk#6432 ## Description Pure refactor. Changes only static info. Mostly more consistent and more readable use of `@import`. One case made less readable: Remove newlines within a large `@import` directive. The reason is that `yarn lerna run build:types` chokes on those newlines. TODO minimal repro + report issue. Extracted from other PRs #1584 #2248 which are now staged on this one. But this should be a reviewable and mergeable improvement regardless of whether we move forward on the others. ### Security Considerations none ### Scaling Considerations none ### Documentation Considerations none ### Testing Considerations none ### Compatibility Considerations none ### Upgrade Considerations none - ~[ ] Includes `*BREAKING*:` in the commit message with migration instructions for any breaking change.~ - ~[ ] Updates `NEWS.md` for user-facing changes.~
1 parent 89c9617 commit 258dfc6

13 files changed

+75
-79
lines changed

‎packages/patterns/src/keys/checkKey.js

+5-3
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,11 @@ import { checkBagEntries, makeBagOfEntries } from './copyBag.js';
2020

2121
const { ownKeys } = Reflect;
2222

23-
/** @import {Checker} from '@endo/marshal' */
24-
/** @import {Passable} from '@endo/pass-style' */
25-
/** @import {CopyBag, CopyMap, CopySet, Key} from '../types' */
23+
/**
24+
* @import {Passable} from '@endo/pass-style'
25+
* @import {Checker} from '@endo/marshal'
26+
* @import {CopyBag, CopyMap, CopySet, Key} from '../types.js'
27+
*/
2628

2729
// ////////////////// Primitive and Scalar keys ////////////////////////////////
2830

‎packages/patterns/src/keys/compareKeys.js

+2-2
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ import {
1717
} from './checkKey.js';
1818
import { makeCompareCollection } from './keycollection-operators.js';
1919

20-
/** @import {CopySet} from '../types' */
20+
/** @import {CopySet, KeyCompare} from '../types.js' */
2121

2222
/**
2323
* CopySet X is smaller than CopySet Y iff all of these conditions hold:
@@ -86,7 +86,7 @@ const _mapCompare = makeCompareCollection(
8686
);
8787
harden(_mapCompare);
8888

89-
/** @type {import('../types').KeyCompare} */
89+
/** @type {KeyCompare} */
9090
export const compareKeys = (left, right) => {
9191
assertKey(left);
9292
assertKey(right);

‎packages/patterns/src/keys/copyBag.js

+5-4
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,11 @@ import {
1212

1313
import { X } from '@endo/errors';
1414

15-
/** @import {CopyBag} from '../types' */
16-
/** @import {FullCompare} from '../types' */
17-
/** @import {Checker} from '@endo/marshal' */
18-
/** @import {Passable} from '@endo/pass-style' */
15+
/**
16+
* @import {Passable} from '@endo/pass-style'
17+
* @import {Checker} from '@endo/marshal'
18+
* @import {CopyBag, FullCompare} from '../types.js'
19+
*/
1920

2021
/**
2122
* @template T

‎packages/patterns/src/keys/copySet.js

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ import {
1313
import { X } from '@endo/errors';
1414

1515
/**
16-
* @import {CopySet, FullCompare} from '../types'
17-
* @import {Checker} from '@endo/marshal'
1816
* @import {Passable} from '@endo/pass-style'
17+
* @import {Checker} from '@endo/marshal'
18+
* @import {CopySet, FullCompare} from '../types.js'
1919
*/
2020

2121
/**

‎packages/patterns/src/keys/keycollection-operators.js

+10-11
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,10 @@ import {
88
import { makeIterator } from '@endo/common/make-iterator.js';
99
import { makeArrayIterator } from '@endo/common/make-array-iterator.js';
1010

11-
/** @import {RankCompare} from '@endo/marshal' */
12-
/** @import {KeyComparison} from '../types' */
13-
/** @import {KeyCompare} from '../types' */
14-
/** @import {FullCompare} from '../types' */
15-
/** @import {KeyCollection} from '../types' */
11+
/**
12+
* @import {RankCompare} from '@endo/marshal'
13+
* @import {Key, KeyCompare, FullCompare, KeyComparison, KeyCollection} from '../types.js'
14+
*/
1615

1716
import { q, Fail } from '@endo/errors';
1817

@@ -22,10 +21,10 @@ import { q, Fail } from '@endo/errors';
2221
* rank, into an iterable that resolves those ties using `fullCompare`.
2322
*
2423
* @template [V=unknown]
25-
* @param {Array<[import('../types.js').Key, V]>} entries
24+
* @param {Array<[Key, V]>} entries
2625
* @param {RankCompare} rankCompare
2726
* @param {FullCompare} fullCompare
28-
* @returns {IterableIterator<[import('../types.js').Key, V]>}
27+
* @returns {IterableIterator<[Key, V]>}
2928
*/
3029
const generateFullSortedEntries = (entries, rankCompare, fullCompare) => {
3130
assertRankSorted(entries, rankCompare);
@@ -82,9 +81,9 @@ harden(generateFullSortedEntries);
8281
* @template [V=unknown]
8382
* @param {C} c1
8483
* @param {C} c2
85-
* @param {(collection: C) => Array<[import('../types.js').Key, V]>} getEntries
84+
* @param {(collection: C) => Array<[Key, V]>} getEntries
8685
* @param {any} absentValue
87-
* @returns {IterableIterator<[import('../types.js').Key, V | absentValue, V | absentValue]>}
86+
* @returns {IterableIterator<[Key, V | absentValue, V | absentValue]>}
8887
*/
8988
export const generateCollectionPairEntries = (
9089
c1,
@@ -127,7 +126,7 @@ export const generateCollectionPairEntries = (
127126
nextY();
128127
return makeIterator(() => {
129128
let done = false;
130-
/** @type {[import('../types.js').Key, V | absentValue, V | absentValue]} */
129+
/** @type {[Key, V | absentValue, V | absentValue]} */
131130
let value;
132131
if (xDone && yDone) {
133132
done = true;
@@ -178,7 +177,7 @@ harden(generateCollectionPairEntries);
178177
*
179178
* @template [C=KeyCollection]
180179
* @template [V=unknown]
181-
* @param {(collection: C) => Array<[import('../types.js').Key, V]>} getEntries
180+
* @param {(collection: C) => Array<[Key, V]>} getEntries
182181
* @param {any} absentValue
183182
* @param {KeyCompare} compareValues
184183
* @returns {(left: C, right: C) => KeyComparison}

‎packages/patterns/src/keys/merge-bag-operators.js

+4-3
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ import {
77
import { q, Fail } from '@endo/errors';
88
import { assertNoDuplicateKeys, makeBagOfEntries } from './copyBag.js';
99

10-
/** @import {KeyComparison} from '../types' */
11-
/** @import {FullCompare} from '../types' */
12-
/** @import {RankCompare} from '@endo/marshal' */
10+
/**
11+
* @import {RankCompare} from '@endo/marshal'
12+
* @import {FullCompare} from '../types.js'
13+
*/
1314

1415
// Based on merge-set-operators.js, but altered for the bag representation.
1516
// TODO share more code with that file and keycollection-operators.js.

‎packages/patterns/src/keys/merge-set-operators.js

+4-3
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ import {
77
import { q, Fail } from '@endo/errors';
88
import { assertNoDuplicates, makeSetOfElements } from './copySet.js';
99

10-
/** @import {KeyComparison} from '../types' */
11-
/** @import {FullCompare} from '../types' */
12-
/** @import {RankCompare} from '@endo/marshal' */
10+
/**
11+
* @import {RankCompare} from '@endo/marshal'
12+
* @import {FullCompare, KeyComparison} from '../types.js'
13+
*/
1314

1415
// TODO share more code with keycollection-operators.js.
1516

‎packages/patterns/src/patterns/getGuardPayloads.js

+3-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@ import {
1616
} from './patternMatchers.js';
1717
import { getCopyMapKeys, makeCopyMap } from '../keys/checkKey.js';
1818

19-
/** @import {AwaitArgGuard, AwaitArgGuardPayload, InterfaceGuard, InterfaceGuardPayload, MethodGuard, MethodGuardPayload} from '../types.js' */
19+
/**
20+
* @import {AwaitArgGuard, AwaitArgGuardPayload, InterfaceGuard, InterfaceGuardPayload, MethodGuard, MethodGuardPayload} from '../types.js'
21+
*/
2022

2123
// The get*GuardPayload functions exist to adapt to the worlds both
2224
// before and after https://github.com/endojs/endo/pull/1712 . When

‎packages/patterns/src/patterns/patternMatchers.js

+15-17
Original file line numberDiff line numberDiff line change
@@ -34,16 +34,16 @@ import {
3434
} from '../keys/checkKey.js';
3535
import { generateCollectionPairEntries } from '../keys/keycollection-operators.js';
3636

37-
/// <reference types="ses"/>
38-
39-
/** @import {Checker, CopyRecord, CopyTagged, Passable} from '@endo/pass-style' */
40-
/** @import {ArgGuard, AwaitArgGuard, CheckPattern, GetRankCover, InterfaceGuard, MatcherNamespace, MethodGuard, MethodGuardMaker, Pattern, RawGuard, SyncValueGuard} from '../types.js' */
41-
/** @import {Kind, MatchHelper} from './types.js' */
37+
/**
38+
* @import {Checker, CopyRecord, CopyTagged, Passable} from '@endo/pass-style'
39+
* @import {ArgGuard, AwaitArgGuard, CheckPattern, GetRankCover, InterfaceGuard, MatcherNamespace, MethodGuard, MethodGuardMaker, Pattern, RawGuard, SyncValueGuard, Kind, Limits, AllLimits, Key, DefaultGuardType} from '../types.js'
40+
* @import {MatchHelper, PatternKit} from './types.js'
41+
*/
4242

4343
const { entries, values } = Object;
4444
const { ownKeys } = Reflect;
4545

46-
/** @type {WeakSet<import('../types.js').Pattern>} */
46+
/** @type {WeakSet<Pattern>} */
4747
const patternMemo = new WeakSet();
4848

4949
// /////////////////////// Match Helpers Helpers /////////////////////////////
@@ -78,13 +78,11 @@ export const defaultLimits = harden({
7878
* Thus, the result only needs to support destructuring. The current
7979
* implementation uses inheritance as a cheap hack.
8080
*
81-
* @param {import('../types.js').Limits} [limits]
82-
* @returns {import('../types.js').AllLimits}
81+
* @param {Limits} [limits]
82+
* @returns {AllLimits}
8383
*/
8484
const limit = (limits = {}) =>
85-
/** @type {import('../types.js').AllLimits} */ (
86-
harden({ __proto__: defaultLimits, ...limits })
87-
);
85+
/** @type {AllLimits} */ (harden({ __proto__: defaultLimits, ...limits }));
8886

8987
const checkIsWellFormedWithLimit = (
9088
payload,
@@ -149,15 +147,15 @@ const checkDecimalDigitsLimit = (specimen, decimalDigitsLimit, check) => {
149147
};
150148

151149
/**
152-
* @returns {import('./types.js').PatternKit}
150+
* @returns {PatternKit}
153151
*/
154152
const makePatternKit = () => {
155153
/**
156154
* If this is a recognized match tag, return the MatchHelper.
157155
* Otherwise result undefined.
158156
*
159157
* @param {string} tag
160-
* @returns {import('./types.js').MatchHelper | undefined}
158+
* @returns {MatchHelper | undefined}
161159
*/
162160
const maybeMatchHelper = tag =>
163161
// eslint-disable-next-line no-use-before-define
@@ -301,7 +299,7 @@ const makePatternKit = () => {
301299

302300
/**
303301
* @param {Passable} specimen
304-
* @param {import('../types.js').Key} keyAsPattern
302+
* @param {Key} keyAsPattern
305303
* @param {Checker} check
306304
* @returns {boolean}
307305
*/
@@ -1697,7 +1695,7 @@ const makePatternKit = () => {
16971695
split: (base, rest = undefined) => {
16981696
if (passStyleOf(harden(base)) === 'copyArray') {
16991697
// TODO at-ts-expect-error works locally but not from @endo/exo
1700-
// @ts-ignore We know it should be an array
1698+
// @ts-expect-error We know it should be an array
17011699
return M.splitArray(base, rest && [], rest);
17021700
} else {
17031701
return M.splitRecord(base, rest && {}, rest);
@@ -1706,7 +1704,7 @@ const makePatternKit = () => {
17061704
partial: (base, rest = undefined) => {
17071705
if (passStyleOf(harden(base)) === 'copyArray') {
17081706
// TODO at-ts-expect-error works locally but not from @endo/exo
1709-
// @ts-ignore We know it should be an array
1707+
// @ts-expect-error We know it should be an array
17101708
return M.splitArray([], base, rest);
17111709
} else {
17121710
return M.splitRecord({}, base, rest);
@@ -1933,7 +1931,7 @@ harden(assertInterfaceGuard);
19331931
* @template {Record<PropertyKey, MethodGuard>} [M = Record<PropertyKey, MethodGuard>]
19341932
* @param {string} interfaceName
19351933
* @param {M} methodGuards
1936-
* @param {{ sloppy?: boolean, defaultGuards?: import('../types.js').DefaultGuardType }} [options]
1934+
* @param {{ sloppy?: boolean, defaultGuards?: DefaultGuardType }} [options]
19371935
* @returns {InterfaceGuard<M>}
19381936
*/
19391937
const makeInterfaceGuard = (interfaceName, methodGuards, options = {}) => {

‎packages/patterns/src/patterns/types.js

+3-19
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,9 @@
22

33
export {};
44

5-
/** @import {Passable} from '@endo/pass-style' */
6-
/** @import {PassStyle} from '@endo/pass-style' */
7-
/** @import {Checker} from '@endo/pass-style' */
8-
/** @import {MethodGuard} from '../types.js' */
9-
10-
/** @import {MatcherNamespace} from '../types' */
11-
/** @import {Pattern} from '../types' */
12-
/** @import {GetRankCover} from '../types' */
13-
145
/**
15-
* @typedef {Exclude<PassStyle, 'tagged'> |
16-
* 'copySet' | 'copyBag' | 'copyMap' |
17-
* `match:${any}` | `guard:${any}`
18-
* } Kind
19-
* It is either a PassStyle other than 'tagged', or, if the underlying
20-
* PassStyle is 'tagged', then the `getTag` value for tags that are
21-
* recognized at the @endo/patterns level of abstraction. For each of those
22-
* tags, a tagged record only has that kind if it satisfies the invariants
23-
* that the @endo/patterns level associates with that kind.
6+
* @import {Passable, Checker} from '@endo/pass-style'
7+
* @import {MatcherNamespace, Pattern, GetRankCover, Kind} from '../types.js'
248
*/
259

2610
/**
@@ -42,7 +26,7 @@ export {};
4226
* Assuming validity of `matcherPayload` as the payload of a Matcher corresponding
4327
* with this MatchHelper, reports whether `specimen` is matched by that Matcher.
4428
*
45-
* @property {import('../types').GetRankCover} getRankCover
29+
* @property {GetRankCover} getRankCover
4630
* Assumes this is the payload of a CopyTagged with the corresponding
4731
* matchTag. Return a RankCover to bound from below and above,
4832
* in rank order, all possible Passables that would match this Matcher.

‎packages/patterns/src/types.js

+16-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,10 @@
22

33
export {};
44

5-
/** @import {Checker, CopyArray, CopyRecord, CopyTagged, Passable} from '@endo/pass-style' */
6-
/** @import {PassStyle} from '@endo/pass-style' */
7-
/** @import {RankCompare, RankCover} from '@endo/marshal' */
5+
/**
6+
* @import {CopyArray, CopyRecord, CopyTagged, Passable, PassStyle, Checker} from '@endo/pass-style'
7+
* @import {RankCompare, RankCover} from '@endo/marshal'
8+
*/
89

910
/**
1011
* @typedef {Passable} Key
@@ -218,6 +219,18 @@ export {};
218219
* @typedef {Partial<AllLimits>} Limits
219220
*/
220221

222+
/**
223+
* @typedef {Exclude<PassStyle, 'tagged'> |
224+
* 'copySet' | 'copyBag' | 'copyMap' |
225+
* `match:${any}` | `guard:${any}`
226+
* } Kind
227+
* It is either a PassStyle other than 'tagged', or, if the underlying
228+
* PassStyle is 'tagged', then the `getTag` value for tags that are
229+
* recognized at the @endo/patterns level of abstraction. For each of those
230+
* tags, a tagged record only has that kind if it satisfies the invariants
231+
* that the @endo/patterns level associates with that kind.
232+
*/
233+
221234
/**
222235
* @typedef {object} PatternMatchers
223236
*

‎packages/patterns/test/test-pattern-limits.js

+5-3
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,13 @@ import {
88
defaultLimits,
99
} from '../src/patterns/patternMatchers.js';
1010

11-
/** @import {Passable} from '@endo/marshal' */
12-
/** @import {Pattern} from '../src/types.js' */
11+
/**
12+
* @import {Passable} from '@endo/marshal'
13+
* @import {Pattern} from '../src/types.js'
14+
*/
1315

1416
/**
15-
* @typedef MatchTest
17+
* @typedef {object} MatchTest
1618
* @property {Passable} specimen
1719
* @property {Pattern[]} yesPatterns
1820
* @property {[Pattern, RegExp|string][]} noPatterns

‎packages/ses/src/error/assert.js

+1-8
Original file line numberDiff line numberDiff line change
@@ -47,14 +47,7 @@ import './internal-types.js';
4747
import { makeNoteLogArgsArrayKit } from './note-log-args.js';
4848

4949
/**
50-
* @import {BaseAssert,
51-
* Assert,
52-
* AssertionFunctions,
53-
* AssertionUtilities,
54-
* StringablePayload,
55-
* DetailsToken,
56-
* MakeAssert,
57-
* } from '../../types.js'
50+
* @import {BaseAssert, Assert, AssertionFunctions, AssertionUtilities, StringablePayload, DetailsToken, MakeAssert} from '../../types.js'
5851
*/
5952

6053
// For our internal debugging purposes, uncomment

0 commit comments

Comments
 (0)