From a02734a45cae94e24d991adaf061059b72623cb6 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Tue, 7 May 2024 10:48:37 -0700
Subject: [PATCH] feat(types): ScalarKey

---
 packages/patterns/src/keys/checkKey.js | 14 +++++++-------
 packages/patterns/src/types.js         |  6 +++++-
 packages/patterns/test/types.test-d.ts | 22 ++++++++++++++++------
 3 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/packages/patterns/src/keys/checkKey.js b/packages/patterns/src/keys/checkKey.js
index 5a2bad79c4..0ef9622b71 100644
--- a/packages/patterns/src/keys/checkKey.js
+++ b/packages/patterns/src/keys/checkKey.js
@@ -21,9 +21,9 @@ import { checkBagEntries, makeBagOfEntries } from './copyBag.js';
 const { ownKeys } = Reflect;
 
 /**
- * @import {Passable} from '@endo/pass-style'
+ * @import {Passable, Primitive} from '@endo/pass-style'
  * @import {Checker} from '@endo/marshal'
- * @import {CopyBag, CopyMap, CopySet, Key} from '../types.js'
+ * @import {CopyBag, CopyMap, CopySet, Key, ScalarKey} from '../types.js'
  */
 
 // ////////////////// Primitive and Scalar keys ////////////////////////////////
@@ -48,14 +48,14 @@ const checkPrimitiveKey = (val, check) => {
 
 /**
  * @param {any} val
- * @returns {boolean}
+ * @returns {val is Primitive}
  */
 export const isPrimitiveKey = val => checkPrimitiveKey(val, identChecker);
 harden(isPrimitiveKey);
 
 /**
  * @param {Passable} val
- * @returns {void}
+ * @returns {asserts val is Primitive}
  */
 export const assertPrimitiveKey = val => {
   checkPrimitiveKey(val, assertChecker);
@@ -63,7 +63,7 @@ export const assertPrimitiveKey = val => {
 harden(assertPrimitiveKey);
 
 /**
- * @param {Passable} val
+ * @param {any} val
  * @param {Checker} check
  * @returns {boolean}
  */
@@ -80,14 +80,14 @@ export const checkScalarKey = (val, check) => {
 
 /**
  * @param {any} val
- * @returns {boolean}
+ * @returns {val is ScalarKey}
  */
 export const isScalarKey = val => checkScalarKey(val, identChecker);
 harden(isScalarKey);
 
 /**
  * @param {Passable} val
- * @returns {void}
+ * @returns {asserts val is ScalarKey}
  */
 export const assertScalarKey = val => {
   checkScalarKey(val, assertChecker);
diff --git a/packages/patterns/src/types.js b/packages/patterns/src/types.js
index 52f930731a..cbb4b6fa19 100644
--- a/packages/patterns/src/types.js
+++ b/packages/patterns/src/types.js
@@ -4,7 +4,7 @@ export {};
 
 // NB: as of TS 5.5 nightly, TS thinks RankCover and Checker "is declared but never read" but they are
 /**
- * @import {Checker, CopyArray, CopyRecord, CopyTagged, Passable, PassStyle, RemotableObject} from '@endo/pass-style';
+ * @import {Checker, CopyArray, CopyRecord, CopyTagged, Passable, PassStyle, Primitive, RemotableObject} from '@endo/pass-style';
  * @import {RankCompare, RankCover} from '@endo/marshal';
  */
 
@@ -34,6 +34,10 @@ export {};
  * key distributed equality semantics.)
  */
 
+/**
+ * @typedef {Primitive | RemotableObject} ScalarKey
+ */
+
 /**
  * @callback GetRankCover
  * @param {Passable} payload
diff --git a/packages/patterns/test/types.test-d.ts b/packages/patterns/test/types.test-d.ts
index 5641af3b6d..ec4ce94181 100644
--- a/packages/patterns/test/types.test-d.ts
+++ b/packages/patterns/test/types.test-d.ts
@@ -1,21 +1,21 @@
 import type { Passable } from '@endo/pass-style';
 import { expectNotType, expectType } from 'tsd';
-import { isKey } from '../src/keys/checkKey.js';
+import { isKey, isScalarKey } from '../src/keys/checkKey.js';
 import { M } from '../src/patterns/patternMatchers.js';
-import type { Key } from '../src/types.js';
+import type { Key, ScalarKey } from '../src/types.js';
 
 // @ts-expect-error M.any missing parens
 M.arrayOf(M.any);
 M.arrayOf(M.any());
 
+const passable: Passable = null as any;
 {
-  const maybeKey: Passable = 'key';
-  const result = isKey(maybeKey);
+  const result = isKey(passable);
   expectType<boolean>(result);
   if (result) {
-    expectType<Key>(maybeKey);
+    expectType<Key>(passable);
   } else {
-    expectNotType<Key>(maybeKey);
+    expectNotType<Key>(passable);
   }
 }
 {
@@ -34,3 +34,13 @@ M.arrayOf(M.any());
     someAny.foo;
   }
 }
+
+{
+  const result = isScalarKey(passable);
+  expectType<boolean>(result);
+  if (result) {
+    expectType<ScalarKey>(passable);
+  } else {
+    expectNotType<ScalarKey>(passable);
+  }
+}