feat(types): ScalarKey

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,22 +48,22 @@ 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);
 };
 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);

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

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);
+  }
+}