feat: checked cast with TypedMatcher

.prettierrc.json5

@@ -11,6 +11,7 @@
         'packages/store/**/*.js',
         'packages/smart-wallet/**/*.js',
         'packages/vats/**/*.js',
+        'packages/vat-data/**/*.js',
       ],
       options: {
         plugins: ['prettier-plugin-jsdoc'],

packages/ERTP/package.json

@@ -86,6 +86,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 91.22
+    "atLeast": 91.23
   }
 }

packages/ERTP/src/paymentLedger.js

@@ -15,13 +15,15 @@ import { BrandI, makeIssuerInterfaces } from './typeGuards.js';
 /**
  * @import {Amount, AssetKind, DisplayInfo, PaymentLedger, Payment, Brand, RecoverySetsOption, Purse, Issuer, Mint} from './types.js'
  * @import {ShutdownWithFailure} from '@agoric/swingset-vat'
- * @import {Key} from '@endo/patterns';
+ * @import {TypedPattern} from '@agoric/internal';
  */
 
 /**
+ * @template {AssetKind} K
  * @param {Brand} brand
- * @param {AssetKind} assetKind
+ * @param {K} assetKind
  * @param {Pattern} elementShape
+ * @returns {TypedPattern<Amount<K>>}
  */
 const amountShapeFromElementShape = (brand, assetKind, elementShape) => {
   let valueShape;

packages/SwingSet/package.json

@@ -100,6 +100,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 75.02
+    "atLeast": 75.1
   }
 }

packages/agoric-cli/package.json

@@ -99,6 +99,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 76.99
+    "atLeast": 77.3
   }
 }

packages/async-flow/package.json

@@ -61,6 +61,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 77.32
+    "atLeast": 76.95
   }
 }

packages/base-zone/package.json

@@ -57,6 +57,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 91.11
+    "atLeast": 91.4
   }
 }

packages/boot/package.json

@@ -90,6 +90,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 87.28
+    "atLeast": 86.66
   }
 }

packages/builders/package.json

@@ -79,6 +79,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 74.36
+    "atLeast": 76.03
   }
 }

packages/casting/package.json

@@ -60,6 +60,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 88.94
+    "atLeast": 88.92
   }
 }

packages/cosmic-swingset/package.json

@@ -68,6 +68,6 @@
     "timeout": "20m"
   },
   "typeCoverage": {
-    "atLeast": 80.49
+    "atLeast": 80.6
   }
 }

packages/deploy-script-support/package.json

@@ -72,6 +72,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 81.63
+    "atLeast": 82.44
   }
 }

packages/governance/package.json

@@ -76,6 +76,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 89.31
+    "atLeast": 89.35
   }
 }

packages/inter-protocol/src/auction/auctionBook.js

@@ -31,6 +31,7 @@ import {
 /**
  * @import {Baggage} from '@agoric/vat-data';
  * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ * @import {TypedPattern} from '@agoric/internal';
  */
 
 const { makeEmpty } = AmountMath;
@@ -172,9 +173,7 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
 
       const bookDataKit = makeRecorderKit(
         node,
-        /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedPattern<BookDataNotification>} */ (
-          M.any()
-        ),
+        /** @type {TypedPattern<BookDataNotification>} */ (M.any()),
       );
 
       return {

packages/inter-protocol/src/auction/auctioneer.js

@@ -36,6 +36,7 @@ import { makeScheduler } from './scheduler.js';
 import { AuctionState } from './util.js';
 
 /**
+ * @import {TypedPattern} from '@agoric/internal';
  * @import {Baggage} from '@agoric/vat-data';
  * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
  */
@@ -440,9 +441,7 @@ export const start = async (zcf, privateArgs, baggage) => {
   const scheduleKit = makeERecorderKit(
     E(privateArgs.storageNode).makeChildNode('schedule'),
     /**
-     * @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedPattern<
-     *     import('./scheduler.js').ScheduleNotification
-     *   >}
+     * @type {TypedPattern<import('./scheduler.js').ScheduleNotification>}
      */ (M.any()),
   );
 

packages/inter-protocol/src/price/fluxAggregatorKit.js

@@ -18,7 +18,10 @@ import { Far } from '@endo/marshal';
 import { prepareOracleAdminKit } from './priceOracleKit.js';
 import { prepareRoundsManagerKit } from './roundsManager.js';
 
-/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+/**
+ * @import {TypedPattern} from '@agoric/internal';
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
 
 const trace = makeTracer('FlxAgg', true);
 
@@ -144,18 +147,14 @@ export const prepareFluxAggregatorKit = async (
     priceKit: () =>
       makeRecorderKit(
         storageNode,
-        /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedPattern<PriceDescription>} */ (
-          M.any()
-        ),
+        /** @type {TypedPattern<PriceDescription>} */ (M.any()),
       ),
     latestRoundKit: () =>
       E.when(E(storageNode).makeChildNode('latestRound'), node =>
         makeRecorderKit(
           node,
           /**
-           * @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedPattern<
-           *     import('./roundsManager.js').LatestRound
-           *   >}
+           * @type {TypedPattern<import('./roundsManager.js').LatestRound>}
            */ (M.any()),
         ),
       ),

packages/inter-protocol/src/psm/psm.js

@@ -59,7 +59,10 @@ import { makeNatAmountShape } from '../contractSupport.js';
  *   given by this contract
  */
 
-/** @import {Baggage} from '@agoric/vat-data' */
+/**
+ * @import {TypedPattern} from '@agoric/internal';
+ * @import {Baggage} from '@agoric/vat-data'
+ */
 
 /** @type {ContractMeta} */
 export const meta = {
@@ -174,9 +177,7 @@ export const start = async (zcf, privateArgs, baggage) => {
       E.when(E(privateArgs.storageNode).makeChildNode('metrics'), node =>
         makeRecorderKit(
           node,
-          /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedPattern<MetricsNotification>} */ (
-            M.any()
-          ),
+          /** @type {TypedPattern<MetricsNotification>} */ (M.any()),
         ),
       ),
   });

packages/inter-protocol/src/reserve/assetReserveKit.js

@@ -13,6 +13,10 @@ import { UnguardedHelperI } from '@agoric/internal/src/typeGuards.js';
 
 const trace = makeTracer('ReserveKit', true);
 
+/**
+ * @import {TypedPattern} from '@agoric/internal';
+ */
+
 /**
  * @typedef {object} MetricsNotification
  * @property {AmountKeywordRecord} allocations
@@ -88,9 +92,7 @@ export const prepareAssetReserveKit = async (
         keywordForBrand,
         metricsKit: makeRecorderKit(
           metricsNode,
-          /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedPattern<MetricsNotification>} */ (
-            M.any()
-          ),
+          /** @type {TypedPattern<MetricsNotification>} */ (M.any()),
         ),
         totalFeeMinted: emptyAmount,
         totalFeeBurned: emptyAmount,

packages/inter-protocol/src/vaultFactory/vaultDirector.js

@@ -40,6 +40,10 @@ import {
   provideAndStartVaultManagerKits,
 } from './vaultManager.js';
 
+/**
+ * @import {TypedPattern} from '@agoric/internal';
+ */
+
 const trace = makeTracer('VD', true);
 
 /**
@@ -131,9 +135,7 @@ const prepareVaultDirector = (
 
   const metricsKit = makeERecorderKit(
     metricsNode,
-    /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedPattern<MetricsNotification>} */ (
-      M.any()
-    ),
+    /** @type {TypedPattern<MetricsNotification>} */ (M.any()),
   );
 
   const managersNode = E(storageNode).makeChildNode('managers');

packages/internal/package.json

@@ -34,6 +34,7 @@
     "jessie.js": "^0.3.4"
   },
   "devDependencies": {
+    "@endo/exo": "^1.5.0",
     "@endo/init": "^1.1.2",
     "ava": "^5.3.0",
     "tsd": "^0.31.1"
@@ -56,6 +57,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 93.89
+    "atLeast": 93.78
   }
 }

packages/internal/src/index.js

@@ -7,6 +7,7 @@ export * from './debug.js';
 export * from './errors.js';
 export * from './utils.js';
 export * from './method-tools.js';
+export * from './typeCheck.js';
 export * from './typeGuards.js';
 
 // eslint-disable-next-line import/export -- just types

packages/internal/src/typeCheck.js

@@ -0,0 +1,23 @@
+// @ts-check
+import { mustMatch as typelessMustMatch } from '@endo/patterns';
+
+/**
+ * @import {MustMatch, PatternType, TypedPattern} from './types.js';
+ */
+
+/** @type {MustMatch} */
+export const mustMatch = typelessMustMatch;
+
+/**
+ * @template M
+ * @param {unknown} specimen
+ * @param {TypedPattern<M>} patt
+ * @returns {M}
+ */
+export const cast = (specimen, patt) => {
+  // mustMatch throws if they don't, which means that `cast` also narrows the
+  // type but a function can't both narrow and return a type. That is by design:
+  // https://github.com/microsoft/TypeScript/issues/34636#issuecomment-545025916
+  mustMatch(specimen, patt);
+  return specimen;
+};

packages/internal/src/types.d.ts

@@ -64,3 +64,33 @@ export type Remote<Primary, Local = DataOnly<Primary>> =
 export type FarRef<Primary, Local = DataOnly<Primary>> = ERef<
   Remote<Primary, Local>
 >;
+
+/*
+ * Stop-gap until https://github.com/Agoric/agoric-sdk/issues/6160
+ * explictly specify the type that the Pattern will verify through a match.
+ *
+ * TODO move all this pattern typing stuff to @endo/patterns
+ */
+declare const validatedType: unique symbol;
+/**
+ * Tag a pattern with the static type it represents.
+ */
+export type TypedPattern<T> = Pattern & { [validatedType]?: T };
+
+export declare type PatternType<TM extends TypedPattern<any>> =
+  TM extends TypedPattern<infer T> ? T : never;
+
+// TODO make Endo's mustMatch do this
+/**
+ * Returning normally indicates success. Match failure is indicated by
+ * throwing.
+ *
+ * Note: remotables can only be matched as "remotable", not the specific kind.
+ *
+ * @see {import('@endo/patterns').mustMatch} for the implementation. This one has a type annotation to narrow if the pattern is a TypedPattern.
+ */
+export declare type MustMatch = <P extends Pattern>(
+  specimen: unknown,
+  pattern: P,
+  label?: string | number,
+) => asserts specimen is P extends TypedPattern<any> ? PatternType<P> : unknown;

packages/internal/test/typeCheck.test.js

@@ -0,0 +1,55 @@
+// @ts-check
+import test from 'ava';
+
+import { makeExo } from '@endo/exo';
+import { M } from '@endo/patterns';
+import { cast, mustMatch } from '../src/typeCheck.js';
+
+/**
+ * @import {TypedPattern} from '@agoric/internal';
+ * @import {RemotableObject} from '@endo/marshal';
+ */
+
+const Mstring = /** @type {TypedPattern<string>} */ (M.string());
+const MremotableFoo = /** @type {TypedPattern<RemotableObject<'Foo'>>} */ (
+  M.remotable('Foo')
+);
+const MremotableBar = /** @type {TypedPattern<RemotableObject<'Bar'>>} */ (
+  M.remotable('Bar')
+);
+
+const unknownString = /** @type {unknown} */ ('');
+
+test('cast', t => {
+  // @ts-expect-error unknown type
+  unknownString.length;
+  // @ts-expect-error not any
+  cast(unknownString, Mstring).missing;
+  cast(unknownString, Mstring).length;
+  t.pass();
+});
+
+test('mustMatch', t => {
+  // @ts-expect-error unknown type
+  unknownString.length;
+  mustMatch(unknownString, Mstring);
+  unknownString.length;
+  t.pass();
+});
+
+test('remotable', t => {
+  const maybeFoo = makeExo(`Remotable1`, undefined, {});
+  mustMatch(maybeFoo, MremotableFoo);
+  maybeFoo; // narrowed to Foo
+
+  const maybeBar = makeExo(`Remotable2`, undefined, {});
+  mustMatch(maybeBar, MremotableBar);
+  maybeBar; // narrowed to Bar
+
+  mustMatch(maybeFoo, MremotableBar);
+  maybeFoo; // further narrowed to never
+  mustMatch(maybeBar, MremotableFoo);
+  maybeBar; // further narrowed to never
+
+  t.pass();
+});

packages/network/package.json

@@ -66,6 +66,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 89.7
+    "atLeast": 90.69
   }
 }