feat(patterns): M.has(el,n) to support want patterns

Author: erights

packages/pass-style/src/makeTagged.js

@@ -4,14 +4,18 @@ import { Fail } from '@endo/errors';
 import { PASS_STYLE } from './passStyle-helpers.js';
 import { assertPassable } from './passStyleOf.js';
 
+/**
+ * @import {Passable,CopyTagged} from './types.js'
+ */
+
 const { create, prototype: objectPrototype } = Object;
 
 /**
  * @template {string} T
- * @template {import('./types.js').Passable} P
+ * @template {Passable} P
  * @param {T} tag
  * @param {P} payload
- * @returns {import('./types.js').CopyTagged<T,P>}
+ * @returns {CopyTagged<T,P>}
  */
 export const makeTagged = (tag, payload) => {
   typeof tag === 'string' ||

packages/patterns/index.js

@@ -65,6 +65,8 @@ export {
   assertMethodGuard,
   assertInterfaceGuard,
   kindOf,
+  elementsHasSplit,
+  pairsHasSplit,
 } from './src/patterns/patternMatchers.js';
 
 export {

packages/patterns/src/patterns/patternMatchers.js

@@ -1,3 +1,4 @@
+/* eslint-disable @endo/no-optional-chaining */
 // @ts-nocheck So many errors that the suppressions hamper readability.
 // TODO parameterize MatchHelper which will solve most of them
 import {
@@ -37,8 +38,8 @@ import {
 import { generateCollectionPairEntries } from '../keys/keycollection-operators.js';
 
 /**
- * @import {Checker, CopyRecord, CopyTagged, Passable} from '@endo/pass-style'
- * @import {ArgGuard, AwaitArgGuard, CheckPattern, GetRankCover, InterfaceGuard, MatcherNamespace, MethodGuard, MethodGuardMaker, Pattern, RawGuard, SyncValueGuard, Kind, Limits, AllLimits, Key, DefaultGuardType} from '../types.js'
+ * @import {Checker, CopyArray, CopyRecord, CopyTagged, Passable} from '@endo/pass-style'
+ * @import {CopySet, CopyBag, ArgGuard, AwaitArgGuard, CheckPattern, GetRankCover, InterfaceGuard, MatcherNamespace, MethodGuard, MethodGuardMaker, Pattern, RawGuard, SyncValueGuard, Kind, Limits, AllLimits, Key, DefaultGuardType} from '../types.js'
  * @import {MatchHelper, PatternKit} from './types.js'
  */
 
@@ -1258,6 +1259,177 @@ const makePatternKit = () => {
     getRankCover: () => getPassStyleCover('tagged'),
   });
 
+  /**
+   * @param {CopyArray} elements
+   * @param {Pattern} elementPatt
+   * @param {bigint} bound Must be >= 1n
+   * @param {CopyArray} [inResults]
+   * @param {CopyArray} [outResults]
+   * @param {Checker} [check]
+   * @returns {boolean}
+   */
+  const elementsHasSplit = (
+    elements,
+    elementPatt,
+    bound,
+    inResults = undefined,
+    outResults = undefined,
+    check = identChecker,
+  ) => {
+    let count = 0n;
+    // Since this feature is motivated by ERTP's use on
+    // non-fungible (`set`, `copySet`) amounts,
+    // their arrays store their elements in decending lexicographic order.
+    // But this function has to make some choice amoung equally good minimal
+    // results. It is more intuitive for the choice to be the first `bound`
+    // matching elements in ascending lexicigraphic order, rather than
+    // decending. Thus we iterate `elements` in reverse order.
+    for (let i = elements.length - 1; i >= 0; i -= 1) {
+      const element = elements[i];
+      if (count < bound) {
+        if (matches(element, elementPatt)) {
+          count += 1n;
+          inResults?.push(element);
+        } else {
+          outResults?.push(element);
+        }
+      } else if (outResults === undefined) {
+        break;
+      } else {
+        outResults.push(element);
+      }
+    }
+    return check(
+      count >= bound,
+      X`Has only ${q(count)} matches, but needs ${q(bound)}`,
+    );
+  };
+
+  /**
+   * @param {CopyArray<[Key, bigint]>} pairs
+   * @param {Pattern} elementPatt
+   * @param {bigint} bound Must be >= 1n
+   * @param {CopyArray<[Key, bigint]>} [inResults]
+   * @param {CopyArray<[Key, bigint]>} [outResults]
+   * @returns {boolean}
+   * @param {Checker} [check]
+   */
+  const pairsHasSplit = (
+    pairs,
+    elementPatt,
+    bound,
+    inResults = undefined,
+    outResults = undefined,
+    check = identChecker,
+  ) => {
+    let count = 0n;
+    // Since this feature is motivated by ERTP's use on
+    // semi-fungible (`copyBag`) amounts,
+    // their arrays store their elements in decending lexicographic order.
+    // But this function has to make some choice amoung equally good minimal
+    // results. It is more intuitive for the choice to be the first `bound`
+    // matching elements in ascending lexicigraphic order, rather than
+    // decending. Thus we iterate `pairs` in reverse order.
+    for (let i = pairs.length - 1; i >= 0n; i -= 1) {
+      const [element, num] = pairs[i];
+      const numRest = bound - count;
+      if (numRest >= 1n) {
+        if (matches(element, elementPatt)) {
+          if (num <= numRest) {
+            count += num;
+            inResults?.push([element, num]);
+          } else {
+            const numIn = num - numRest;
+            count += numIn;
+            inResults?.push([element, numIn]);
+            outResults?.push([element, numRest]);
+          }
+        } else {
+          outResults?.push([element, num]);
+        }
+      } else if (outResults === undefined) {
+        break;
+      } else {
+        outResults.push([element, num]);
+      }
+    }
+    return check(
+      count >= bound,
+      X`Has only ${q(count)} matches, but needs ${q(bound)}`,
+    );
+  };
+
+  /** @type {MatchHelper} */
+  const matchHasHelper = Far('match:has helper', {
+    /**
+     * @param {CopyArray | CopySet | CopyBag} specimen
+     * @param {[Pattern, bigint, Limits?]} payload
+     * @param {Checker} check
+     */
+    checkMatches: (
+      specimen,
+      [elementPatt, bound, limits = undefined],
+      check,
+    ) => {
+      const kind = kindOf(specimen, check);
+      const { decimalDigitsLimit } = limit(limits);
+      if (
+        !applyLabelingError(
+          checkDecimalDigitsLimit,
+          [bound, decimalDigitsLimit, check],
+          `${kind} matches`,
+        )
+      ) {
+        return false;
+      }
+      switch (kind) {
+        case 'copyArray': {
+          return elementsHasSplit(
+            specimen,
+            elementPatt,
+            bound,
+            undefined,
+            undefined,
+            check,
+          );
+        }
+        case 'copySet': {
+          return elementsHasSplit(
+            specimen.payload,
+            elementPatt,
+            bound,
+            undefined,
+            undefined,
+            check,
+          );
+        }
+        case 'copyBag': {
+          return pairsHasSplit(
+            specimen.payload,
+            elementPatt,
+            bound,
+            undefined,
+            undefined,
+            check,
+          );
+        }
+        default: {
+          return check(false, X`unexpected ${q(kind)}`);
+        }
+      }
+    },
+
+    checkIsWellFormed: (payload, check) =>
+      checkIsWellFormedWithLimit(
+        payload,
+        harden([MM.pattern(), MM.gte(1n)]),
+        check,
+        'match:has payload',
+      ),
+
+    getRankCover: () => getPassStyleCover('tagged'),
+  });
+
   /** @type {MatchHelper} */
   const matchMapOfHelper = Far('match:mapOf helper', {
     checkMatches: (
@@ -1548,6 +1720,7 @@ const makePatternKit = () => {
     'match:recordOf': matchRecordOfHelper,
     'match:setOf': matchSetOfHelper,
     'match:bagOf': matchBagOfHelper,
+    'match:has': matchHasHelper,
     'match:mapOf': matchMapOfHelper,
     'match:splitArray': matchSplitArrayHelper,
     'match:splitRecord': matchSplitRecordHelper,
@@ -1702,6 +1875,8 @@ const makePatternKit = () => {
       makeLimitsMatcher('match:setOf', [keyPatt, limits]),
     bagOf: (keyPatt = M.any(), countPatt = M.any(), limits = undefined) =>
       makeLimitsMatcher('match:bagOf', [keyPatt, countPatt, limits]),
+    has: (elementPatt = M.any(), countPatt = 1n, limits = undefined) =>
+      makeLimitsMatcher('match:has', [elementPatt, countPatt, limits]),
     mapOf: (keyPatt = M.any(), valuePatt = M.any(), limits = undefined) =>
       makeLimitsMatcher('match:mapOf', [keyPatt, valuePatt, limits]),
     splitArray: (base, optional = undefined, rest = undefined) =>
@@ -1763,6 +1938,8 @@ const makePatternKit = () => {
     getRankCover,
     M,
     kindOf,
+    elementsHasSplit,
+    pairsHasSplit,
   });
 };
 
@@ -1781,6 +1958,8 @@ export const {
   getRankCover,
   M,
   kindOf,
+  elementsHasSplit,
+  pairsHasSplit,
 } = makePatternKit();
 
 MM = M;

packages/patterns/src/types.js

@@ -380,6 +380,13 @@ export {};
  * `countPatt` is expected to rarely be useful,
  * but is provided to minimize surprise.
  *
+ * @property {(elementPatt?: Pattern,
+ *             bound?: bigint,
+ *             limits?: Limits
+ * ) => Matcher} has
+ * Matches any array, CopySet, or CopyBag in which the bigint number of
+ * elements that match `elementPatt` is >= `bound` (which defaults to `1n`).
+ *
  * @property {(keyPatt?: Pattern,
  *             valuePatt?: Pattern,
  *             limits?: Limits

packages/patterns/test/patterns.test.js

@@ -199,6 +199,10 @@ const runTests = (t, successCase, failCase) => {
 
     successCase(specimen, M.arrayOf(M.number()));
 
+    successCase(specimen, M.has(3));
+    successCase(specimen, M.has(3, 1n));
+    successCase(specimen, M.has(M.number(), 2n));
+
     failCase(specimen, [4, 3], '[3,4] - Must be: [4,3]');
     failCase(specimen, [3], '[3,4] - Must be: [3]');
     failCase(
@@ -227,6 +231,8 @@ const runTests = (t, successCase, failCase) => {
       M.arrayOf(M.string()),
       '[0]: number 3 - Must be a string',
     );
+
+    failCase(specimen, M.has('c'), 'Has only "[0n]" matches, but needs "[1n]"');
   }
   {
     const specimen = { foo: 3, bar: 4 };
@@ -419,6 +425,10 @@ const runTests = (t, successCase, failCase) => {
     successCase(specimen, M.lte(makeCopySet([3, 4, 5])));
     successCase(specimen, M.setOf(M.number()));
 
+    successCase(specimen, M.has(3));
+    successCase(specimen, M.has(3, 1n));
+    successCase(specimen, M.has(M.number(), 2n));
+
     failCase(specimen, makeCopySet([]), '"[copySet]" - Must be: "[copySet]"');
     failCase(
       specimen,
@@ -440,6 +450,8 @@ const runTests = (t, successCase, failCase) => {
       M.setOf(M.string()),
       'set elements[0]: number 4 - Must be a string',
     );
+
+    failCase(specimen, M.has('c'), 'Has only "[0n]" matches, but needs "[1n]"');
   }
   {
     const specimen = makeCopyBag([
@@ -472,6 +484,13 @@ const runTests = (t, successCase, failCase) => {
     );
     successCase(specimen, M.bagOf(M.string()));
     successCase(specimen, M.bagOf(M.string(), M.lt(5n)));
+    successCase(specimen, M.bagOf(M.string(), M.gte(2n)));
+
+    successCase(specimen, M.has('a'));
+    successCase(specimen, M.has('a', 2n));
+    successCase(specimen, M.has(M.string(), 5n));
+    successCase(specimen, M.has('a', 1n));
+    successCase(specimen, M.has('a'));
 
     failCase(
       specimen,
@@ -499,16 +518,8 @@ const runTests = (t, successCase, failCase) => {
       'bag keys[0]: string "b" - Must be a boolean',
     );
     failCase(specimen, M.bagOf('b'), 'bag keys[1]: "a" - Must be: "b"');
-    failCase(
-      specimen,
-      M.bagOf(M.any(), M.gt(5n)),
-      'bag counts[0]: "[3n]" - Must be > "[5n]"',
-    );
-    failCase(
-      specimen,
-      M.bagOf(M.any(), M.gt(2n)),
-      'bag counts[1]: "[2n]" - Must be > "[2n]"',
-    );
+
+    failCase(specimen, M.has('c'), 'Has only "[0n]" matches, but needs "[1n]"');
   }
   {
     const specimen = makeCopyMap([
@@ -867,4 +878,17 @@ test('well formed patterns', t => {
   t.throws(() => M.remotable(88), {
     message: 'match:remotable payload: label: number 88 - Must be a string',
   });
+
+  t.throws(() => M.has('c', 0n), {
+    message: 'match:has payload: [1]: "[0n]" - Must be >= "[1n]"',
+  });
+  // @ts-expect-error purposeful type violation for testing
+  t.throws(() => M.has('c', M.nat()), {
+    message:
+      'match:has payload: [1]: A passable tagged "match:nat" is not a key: "[match:nat]"',
+  });
+  // @ts-expect-error purposeful type violation for testing
+  t.throws(() => M.has(3, 1), {
+    message: 'match:has payload: [1]: 1 - Must be >= "[1n]"',
+  });
 });