Skip to content

Commit b77b6f7

Browse files
erightserights
committed
feat(patterns): pattern-based compression
1 parent 7f1f331 commit b77b6f7

File tree

8 files changed

+1327
-171
lines changed

8 files changed

+1327
-171
lines changed

‎packages/patterns/index.js

+2
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ export {
6464
assertInterfaceGuard,
6565
} from './src/patterns/patternMatchers.js';
6666

67+
export { mustCompress, mustDecompress } from './src/patterns/compress.js';
68+
6769
// ////////////////// Temporary, until these find their proper home ////////////
6870

6971
export { listDifference, objectMap } from './src/utils.js';

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -575,7 +575,7 @@ const checkKeyInternal = (val, check) => {
575575
}
576576
case 'error':
577577
case 'promise': {
578-
return check(false, X`A ${q(passStyle)} cannot be a key`);
578+
return check(false, X`A ${q(passStyle)} cannot be a key: ${val}`);
579579
}
580580
default: {
581581
// Unexpected tags are just non-keys, but an unexpected passStyle

‎packages/patterns/src/patterns/compress.js

+292
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
// @ts-check
2+
import { assertChecker, makeTagged, passStyleOf } from '@endo/marshal';
3+
import { recordNames, recordValues } from '@endo/marshal/src/encodePassable.js';
4+
5+
import {
6+
kindOf,
7+
assertPattern,
8+
maybeMatchHelper,
9+
matches,
10+
checkMatches,
11+
mustMatch,
12+
} from './patternMatchers.js';
13+
import { isKey } from '../keys/checkKey.js';
14+
import { keyEQ } from '../keys/compareKeys.js';
15+
16+
/** @typedef {import('@endo/pass-style').Passable} Passable */
17+
/** @typedef {import('../types.js').Compress} Compress */
18+
/** @typedef {import('../types.js').MustCompress} MustCompress */
19+
/** @typedef {import('../types.js').Decompress} Decompress */
20+
/** @typedef {import('../types.js').MustDecompress} MustDecompress */
21+
/** @typedef {import('../types.js').Pattern} Pattern */
22+
23+
const { fromEntries } = Object;
24+
const { Fail, quote: q } = assert;
25+
26+
const isNonCompressingMatcher = pattern => {
27+
const patternKind = kindOf(pattern);
28+
if (patternKind === undefined) {
29+
return false;
30+
}
31+
const matchHelper = maybeMatchHelper(patternKind);
32+
return matchHelper && matchHelper.compress === undefined;
33+
};
34+
35+
/**
36+
* When, for example, all the specimens in a given store match a
37+
* specific pattern, then each of those specimens must contain the same
38+
* literal superstructure as their one shared pattern. Therefore, storing
39+
* that literal superstructure would be redumdant. If `specimen` does
40+
* match `pattern`, then `compress(specimen, pattern)` will return a bindings
41+
* array which is hopefully more compact than `specimen` as a whole, but
42+
* carries all the information from specimen that cannot be derived just
43+
* from knowledge that it matches this `pattern`.
44+
*
45+
* @type {Compress}
46+
*/
47+
const compress = (specimen, pattern) => {
48+
if (isNonCompressingMatcher(pattern)) {
49+
if (matches(specimen, pattern)) {
50+
return harden({ compressed: specimen });
51+
}
52+
return undefined;
53+
}
54+
55+
// Not yet frozen! Used to accumulate bindings
56+
const bindings = [];
57+
const emitBinding = binding => {
58+
bindings.push(binding);
59+
};
60+
harden(emitBinding);
61+
62+
/**
63+
* @param {Passable} innerSpecimen
64+
* @param {Pattern} innerPattern
65+
* @returns {boolean}
66+
*/
67+
const compressRecur = (innerSpecimen, innerPattern) => {
68+
assertPattern(innerPattern);
69+
if (isKey(innerPattern)) {
70+
return keyEQ(innerSpecimen, innerPattern);
71+
}
72+
const patternKind = kindOf(innerPattern);
73+
const specimenKind = kindOf(innerSpecimen);
74+
switch (patternKind) {
75+
case undefined: {
76+
return false;
77+
}
78+
case 'copyArray': {
79+
if (
80+
specimenKind !== 'copyArray' ||
81+
innerSpecimen.length !== innerPattern.length
82+
) {
83+
return false;
84+
}
85+
return innerPattern.every((p, i) => compressRecur(innerSpecimen[i], p));
86+
}
87+
case 'copyRecord': {
88+
if (specimenKind !== 'copyRecord') {
89+
return false;
90+
}
91+
const specimenNames = recordNames(innerSpecimen);
92+
const pattNames = recordNames(innerPattern);
93+
94+
if (specimenNames.length !== pattNames.length) {
95+
return false;
96+
}
97+
const specimenValues = recordValues(innerSpecimen, specimenNames);
98+
const pattValues = recordValues(innerPattern, pattNames);
99+
100+
return pattNames.every(
101+
(name, i) =>
102+
specimenNames[i] === name &&
103+
compressRecur(specimenValues[i], pattValues[i]),
104+
);
105+
}
106+
case 'copyMap': {
107+
if (specimenKind !== 'copyMap') {
108+
return false;
109+
}
110+
const {
111+
payload: { keys: pattKeys, values: valuePatts },
112+
} = innerPattern;
113+
const {
114+
payload: { keys: specimenKeys, values: specimenValues },
115+
} = innerSpecimen;
116+
// TODO BUG: this assumes that the keys appear in the
117+
// same order, so we can compare values in that order.
118+
// However, we're only guaranteed that they appear in
119+
// the same rankOrder. Thus we must search one of these
120+
// in the other's rankOrder.
121+
if (!keyEQ(specimenKeys, pattKeys)) {
122+
return false;
123+
}
124+
return compressRecur(specimenValues, valuePatts);
125+
}
126+
default:
127+
{
128+
const matchHelper = maybeMatchHelper(patternKind);
129+
if (matchHelper) {
130+
if (matchHelper.compress) {
131+
const subCompressedRecord = matchHelper.compress(
132+
innerSpecimen,
133+
innerPattern.payload,
134+
compress,
135+
);
136+
if (subCompressedRecord === undefined) {
137+
return false;
138+
} else {
139+
emitBinding(subCompressedRecord.compressed);
140+
return true;
141+
}
142+
} else if (matches(innerSpecimen, innerPattern)) {
143+
assert(isNonCompressingMatcher(innerPattern));
144+
emitBinding(innerSpecimen);
145+
return true;
146+
} else {
147+
return false;
148+
}
149+
}
150+
}
151+
throw Fail`unrecognized kind: ${q(patternKind)}`;
152+
}
153+
};
154+
155+
if (compressRecur(specimen, pattern)) {
156+
return harden({ compressed: bindings });
157+
} else {
158+
return undefined;
159+
}
160+
};
161+
harden(compress);
162+
163+
/**
164+
* `mustCompress` is to `compress` approximately as `fit` is to `matches`.
165+
* Where `compress` indicates pattern match failure by returning `undefined`,
166+
* `mustCompress` indicates pattern match failure by throwing an error
167+
* with a good pattern-match-failure diagnostic. Thus, like `fit`,
168+
* `mustCompress` has an additional optional `label` parameter to be used on
169+
* the outside of that diagnostic if needed. If `mustCompress` does return
170+
* normally, then the pattern match succeeded and `mustCompress` returns a
171+
* valid compressed value.
172+
*
173+
* @type {MustCompress}
174+
*/
175+
export const mustCompress = (specimen, pattern, label = undefined) => {
176+
const compressedRecord = compress(specimen, pattern);
177+
if (compressedRecord !== undefined) {
178+
return compressedRecord.compressed;
179+
}
180+
// `compress` is validating, so we don't need to redo all of `mustMatch`.
181+
// We use it only to generate the error.
182+
// Should only throw
183+
checkMatches(specimen, pattern, assertChecker, label);
184+
throw Fail`internal: ${label}: inconsistent pattern match: ${q(pattern)}`;
185+
};
186+
harden(mustCompress);
187+
188+
/**
189+
* `decompress` reverses the compression performed by `compress`
190+
* or `mustCompress`, in order to recover the equivalent
191+
* of the original specimen from the `bindings` array and the `pattern`.
192+
*
193+
* @type {Decompress}
194+
*/
195+
const decompress = (compressed, pattern) => {
196+
if (isNonCompressingMatcher(pattern)) {
197+
return compressed;
198+
}
199+
200+
assert(Array.isArray(compressed));
201+
passStyleOf(compressed) === 'copyArray' ||
202+
Fail`Pattern ${pattern} expected bindings array: ${compressed}`;
203+
let i = 0;
204+
const takeBinding = () => {
205+
i < compressed.length ||
206+
Fail`Pattern ${q(pattern)} expects more than ${q(
207+
compressed.length,
208+
)} bindings: ${compressed}`;
209+
const binding = compressed[i];
210+
i += 1;
211+
return binding;
212+
};
213+
harden(takeBinding);
214+
215+
const decompressRecur = innerPattern => {
216+
assertPattern(innerPattern);
217+
if (isKey(innerPattern)) {
218+
return innerPattern;
219+
}
220+
const patternKind = kindOf(innerPattern);
221+
switch (patternKind) {
222+
case undefined: {
223+
throw Fail`decompress expected a pattern: ${q(innerPattern)}`;
224+
}
225+
case 'copyArray': {
226+
return harden(innerPattern.map(p => decompressRecur(p)));
227+
}
228+
case 'copyRecord': {
229+
const pattNames = recordNames(innerPattern);
230+
const pattValues = recordValues(innerPattern, pattNames);
231+
const entries = pattNames.map((name, j) => [
232+
name,
233+
decompressRecur(pattValues[j]),
234+
]);
235+
// Reverse so printed form looks less surprising,
236+
// with ascenting rather than descending property names.
237+
return harden(fromEntries(entries.reverse()));
238+
}
239+
case 'copyMap': {
240+
const {
241+
payload: { keys: pattKeys, values: valuePatts },
242+
} = innerPattern;
243+
return makeTagged(
244+
'copyMap',
245+
harden({
246+
keys: pattKeys,
247+
values: valuePatts.map(p => decompressRecur(p)),
248+
}),
249+
);
250+
}
251+
default:
252+
{
253+
const matchHelper = maybeMatchHelper(patternKind);
254+
if (matchHelper) {
255+
if (matchHelper.decompress) {
256+
const subCompressed = takeBinding();
257+
return matchHelper.decompress(
258+
subCompressed,
259+
innerPattern.payload,
260+
decompress,
261+
);
262+
} else {
263+
assert(isNonCompressingMatcher(innerPattern));
264+
return takeBinding();
265+
}
266+
}
267+
}
268+
throw Fail`unrecognized pattern kind: ${q(patternKind)} ${q(
269+
innerPattern,
270+
)}`;
271+
}
272+
};
273+
274+
return decompressRecur(pattern);
275+
};
276+
harden(decompress);
277+
278+
/**
279+
* `decompress` reverses the compression performed by `compress`
280+
* or `mustCompress`, in order to recover the equivalent
281+
* of the original specimen from `compressed` and `pattern`.
282+
*
283+
* @type {MustDecompress}
284+
*/
285+
export const mustDecompress = (compressed, pattern, label = undefined) => {
286+
const value = decompress(compressed, pattern);
287+
// `decompress` does some checking, but is not validating, so we
288+
// need to do the full `mustMatch` here to validate as well as to generate
289+
// the error if invalid.
290+
mustMatch(value, pattern, label);
291+
return value;
292+
};

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

+38-6
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
/// <reference types="ses"/>
22

3-
/** @typedef {import('@endo/marshal').Passable} Passable */
4-
/** @typedef {import('@endo/marshal').PassStyle} PassStyle */
5-
/** @typedef {import('@endo/marshal').CopyTagged} CopyTagged */
6-
/** @template T @typedef {import('@endo/marshal').CopyRecord<T>} CopyRecord */
7-
/** @template T @typedef {import('@endo/marshal').CopyArray<T>} CopyArray */
8-
/** @typedef {import('@endo/marshal').Checker} Checker */
3+
/** @typedef {import('@endo/pass-style').Passable} Passable */
4+
/** @typedef {import('@endo/pass-style').PassStyle} PassStyle */
5+
/** @typedef {import('@endo/pass-style').CopyTagged} CopyTagged */
6+
/** @template T @typedef {import('@endo/pass-style').CopyRecord<T>} CopyRecord */
7+
/** @template T @typedef {import('@endo/pass-style').CopyArray<T>} CopyArray */
8+
/** @typedef {import('@endo/pass-style').Checker} Checker */
99
/** @typedef {import('@endo/marshal').RankCompare} RankCompare */
1010
/** @typedef {import('@endo/marshal').RankCover} RankCover */
1111

@@ -15,6 +15,7 @@
1515
/** @typedef {import('../types.js').InterfaceGuard} InterfaceGuard */
1616
/** @typedef {import('../types.js').MethodGuardMaker0} MethodGuardMaker0 */
1717

18+
/** @typedef {import('../types.js').Kind} Kind */
1819
/** @typedef {import('../types').MatcherNamespace} MatcherNamespace */
1920
/** @typedef {import('../types').Key} Key */
2021
/** @typedef {import('../types').Pattern} Pattern */
@@ -23,12 +24,20 @@
2324
/** @typedef {import('../types').AllLimits} AllLimits */
2425
/** @typedef {import('../types').GetRankCover} GetRankCover */
2526

27+
/** @typedef {import('../types.js').CompressedRecord} CompressedRecord */
28+
/** @typedef {import('../types.js').Compress} Compress */
29+
/** @typedef {import('../types.js').MustCompress} MustCompress */
30+
/** @typedef {import('../types.js').Decompress} Decompress */
31+
/** @typedef {import('../types.js').MustDecompress} MustDecompress */
32+
2633
/**
2734
* @typedef {object} MatchHelper
2835
* This factors out only the parts specific to each kind of Matcher. It is
2936
* encapsulated, and its methods can make the stated unchecked assumptions
3037
* enforced by the common calling logic.
3138
*
39+
* @property {string} tag
40+
*
3241
* @property {(allegedPayload: Passable,
3342
* check: Checker
3443
* ) => boolean} checkIsWellFormed
@@ -42,6 +51,27 @@
4251
* Assuming validity of `matcherPayload` as the payload of a Matcher corresponding
4352
* with this MatchHelper, reports whether `specimen` is matched by that Matcher.
4453
*
54+
* @property {(specimen: Passable,
55+
* matcherPayload: Passable,
56+
* compress: Compress
57+
* ) => (CompressedRecord | undefined)} [compress]
58+
* Assuming a valid Matcher of this type with `matcherPayload` as its
59+
* payload, if this specimen matches this matcher, then return a
60+
* CompressedRecord that represents this specimen,
61+
* perhaps more compactly, given the knowledge that it matches this matcher.
62+
* If the specimen does not match the matcher, return undefined.
63+
* If this matcher has a `compress` method, then it must have a matching
64+
* `decompress` method.
65+
*
66+
* @property {(compressed: Passable,
67+
* matcherPayload: Passable,
68+
* decompress: Decompress
69+
* ) => Passable} [decompress]
70+
* If `compressed` is the result of a successful `compress` with this matcher,
71+
* then `decompress` must return a Passable equivalent to the original specimen.
72+
* If this matcher has an `decompress` method, then it must have a matching
73+
* `compress` method.
74+
*
4575
* @property {import('../types').GetRankCover} getRankCover
4676
* Assumes this is the payload of a CopyTagged with the corresponding
4777
* matchTag. Return a RankCover to bound from below and above,
@@ -63,5 +93,7 @@
6393
* @property {(patt: Pattern) => void} assertPattern
6494
* @property {(patt: Passable) => boolean} isPattern
6595
* @property {GetRankCover} getRankCover
96+
* @property {(passable: Passable, check?: Checker) => (Kind | undefined)} kindOf
97+
* @property {(tag: string) => (MatchHelper | undefined)} maybeMatchHelper
6698
* @property {MatcherNamespace} M
6799
*/

0 commit comments

Comments
 (0)