feat: checked cast with TypedMatcher

packages/internal/src/typeCheck.js

@@ -0,0 +1,12 @@
+import { mustMatch } from '@endo/patterns';
+
+/**
+ * @template {import('./types.js').TypedMatcher} M
+ * @param {unknown} specimen
+ * @param {M} shape
+ * @returns {import('./types.js').MatcherType<M>}
+ */
+export const cast = (specimen, shape) => {
+  mustMatch(specimen, shape);
+  return specimen;
+};

packages/internal/src/types.d.ts

@@ -1,4 +1,6 @@
 /* eslint-disable max-classes-per-file */
+import type { Matcher } from '@endo/patterns';
+
 export declare class Callback<I extends (...args: unknown[]) => any> {
   private iface: I;
 
@@ -18,3 +20,11 @@ export declare class SyncCallback<
 
   public isSync: true;
 }
+
+declare const type: unique symbol;
+export declare type TypedMatcher<T = unknown> = Matcher & {
+  readonly [type]: T;
+};
+export declare type MatcherType<M> = M extends TypedMatcher<infer T>
+  ? T
+  : never;

packages/internal/test/test-typeCheck.js

@@ -0,0 +1,19 @@
+// @ts-check
+import test from 'ava';
+
+import { M } from '@endo/patterns';
+import { cast } from '../src/typeCheck.js';
+
+const Mstring = /** @type {import('../src/types.js').TypedMatcher<string>} */ (
+  M.string()
+);
+
+const unnknownString = /** @type {unknown} */ ('');
+
+test('cast', t => {
+  // @ts-expect-error unknown type
+  unnknownString.length;
+  // @ts-expect-error not any
+  cast(unnknownString, Mstring).missing;
+  cast(unnknownString, Mstring).length;
+});