feat(types): parameterizes CapTP slots

Author: turadg

.changeset/ocapn-captp-slot-types.md

@@ -0,0 +1,5 @@
+---
+'@endo/ocapn': minor
+---
+
+Parameterize CapTP slot types and improve TypeScript 6 conformance across the OCapN client surface. Compile-time type changes only; no runtime behavior changes.

packages/ocapn/src/captp/pairwise.js

@@ -4,8 +4,11 @@ import { makeRefCounter } from './refcount.js';
 
 /**
  * @typedef {import('@endo/eventual-send').Settler} Settler
- * @typedef {import('./types.js').Slot} Slot
  * @typedef {import('./types.js').SlotType} SlotType
+ */
+/**
+ * @template {SlotType} [T=SlotType]
+ * @typedef {import('./types.js').Slot<T>} Slot
  * @typedef {import('./finalize.js').FinalizingMap<Slot, object>} ExportTable
  * @typedef {import('./finalize.js').FinalizingMap<Slot, object>} ImportTable
  *
@@ -26,22 +29,23 @@ import { makeRefCounter } from './refcount.js';
  */
 
 /**
- * @param {SlotType} type
+ * @template {SlotType} T
+ * @param {T} type
  * @param {boolean} isLocal
  * @param {bigint} position
- * @returns {Slot}
+ * @returns {Slot<T>}
  */
 export const makeSlot = (type, isLocal, position) => {
-  // @ts-expect-error - we're returning a branded type.
-  return `${type}${isLocal ? '+' : '-'}${position}`;
+  return /** @type {Slot<T>} */ (`${type}${isLocal ? '+' : '-'}${position}`);
 };
 
 /**
- * @param {Slot} slot
- * @returns {{ type: SlotType, isLocal: boolean, position: bigint }}
+ * @template {SlotType} T
+ * @param {Slot<T>} slot
+ * @returns {{ type: T, isLocal: boolean, position: bigint }}
  */
 export const parseSlot = slot => {
-  const type = slot[0];
+  const type = /** @type {T} */ (slot[0]);
   if (type !== 'a' && type !== 'p' && type !== 'o') {
     throw new Error(`Invalid slot type: ${type}`);
   }

packages/ocapn/src/captp/types.js

@@ -1,6 +1,15 @@
 export {};
 
 /**
- * @typedef {string & { _brand: "captp-slot" }} Slot
  * @typedef {'a' | 'p' | 'o'} SlotType
  */
+
+/**
+ * @template {SlotType} [T=SlotType]
+ * @typedef {`${T}${'+' | '-'}${string}` & { _brand: "captp-slot" }} Slot
+ * A slot is a branded string of the form (type)(+|-)(position),
+ * where `+` means local (exported) and `-` means remote (imported).
+ * The type parameter carries the slot-type letter so that callers which
+ * build slots with a known literal (e.g. makeSlot('p', ...)) can recover
+ * that information through parseSlot and table lookups.
+ */

packages/ocapn/src/client/ocapn.js

@@ -670,7 +670,7 @@ const makeBootstrapObject = (
  * @typedef {object} Ocapn
  * @property {((reason?: Error) => void)} abort
  * @property {((data: Uint8Array) => void)} dispatchMessageData
- * @property {() => object} getRemoteBootstrap
+ * @property {() => any} getRemoteBootstrap
  * @property {ReferenceKit} referenceKit
  * @property {(message: any) => Uint8Array} writeOcapnMessage
  * @property {OcapnDebug} [_debug] - **EXPERIMENTAL**: Internal APIs for testing. Only present when `debugMode` is true.

packages/ocapn/test/captp/pairwise.test.js

@@ -916,10 +916,10 @@ test('makePairwiseTable - getSlotForValue returns undefined for primitives', t =
   const table = makeTestTable();
 
   // Primitives can't be used as WeakMap keys, so should return undefined
-  t.is(table.getSlotForValue(42), undefined);
-  t.is(table.getSlotForValue('string'), undefined);
-  t.is(table.getSlotForValue(null), undefined);
-  t.is(table.getSlotForValue(undefined), undefined);
+  t.is(table.getSlotForValue(/** @type {any} */ (42)), undefined);
+  t.is(table.getSlotForValue(/** @type {any} */ ('string')), undefined);
+  t.is(table.getSlotForValue(/** @type {any} */ (null)), undefined);
+  t.is(table.getSlotForValue(/** @type {any} */ (undefined)), undefined);
 });
 
 test('makePairwiseTable - refcount accumulates across multiple commit cycles', t => {

packages/ocapn/test/client.test.js

@@ -1519,9 +1519,11 @@ test('local answer promise on B is not rejected on connection close', async t =>
 
     // Debug: Check B's slots
     const ocapnTableB = getOcapnDebug(ocapnB).ocapnTable;
-    const slotOnB = ocapnTableB.getSlotForValue(capturedLocalAnswerPromise);
+    const slotOnB = ocapnTableB.getSlotForValue(
+      /** @type {any} */ (capturedLocalAnswerPromise),
+    );
     const answerPosition = ocapnTableB.getLocalAnswerToPosition(
-      capturedLocalAnswerPromise,
+      /** @type {any} */ (capturedLocalAnswerPromise),
     );
     console.log('B: slot for capturedLocalAnswerPromise:', slotOnB);
     console.log('B: getLocalAnswerToPosition result:', answerPosition);
@@ -1668,7 +1670,7 @@ test('E() sends op:deliver with answer tracking', async t => {
     const unsubscribe = getOcapnDebug(ocapnA).subscribeMessages(
       (direction, message) => {
         if (direction === 'send') {
-          sentMessages.push(message);
+          sentMessages.push(/** @type {{type: string}} */ (message));
         }
       },
     );
@@ -1733,7 +1735,7 @@ test('E.sendOnly() sends op:deliver-only without answer tracking', async t => {
     const unsubscribe = getOcapnDebug(ocapnA).subscribeMessages(
       (direction, message) => {
         if (direction === 'send') {
-          sentMessages.push(message);
+          sentMessages.push(/** @type {{type: string}} */ (message));
         }
       },
     );
@@ -1804,7 +1806,7 @@ test('E.sendOnly() on function call sends op:deliver-only', async t => {
     const unsubscribe = getOcapnDebug(ocapnA).subscribeMessages(
       (direction, message) => {
         if (direction === 'send') {
-          sentMessages.push(message);
+          sentMessages.push(/** @type {{type: string}} */ (message));
         }
       },
     );
@@ -1878,7 +1880,7 @@ test('resolver callbacks use op:deliver-only', async t => {
     const unsubscribe = getOcapnDebug(ocapnB).subscribeMessages(
       (direction, message) => {
         if (direction === 'send') {
-          messagesSentByB.push(message);
+          messagesSentByB.push(/** @type {{type: string}} */ (message));
         }
       },
     );

packages/ocapn/test/codecs/passable.test.js

@@ -186,7 +186,12 @@ const table = [
     name: 'tagged with reference (local object)',
     makeValue: testKit => makeTagged('myTag', testKit.makeLocalObject(100n)),
     makeExpectedValue: testKit =>
-      makeTagged('myTag', testKit.referenceKit.provideRemoteObjectValue(100n)),
+      makeTagged(
+        'myTag',
+        /** @type {any} */ (
+          testKit.referenceKit.provideRemoteObjectValue(100n)
+        ),
+      ),
   },
   {
     name: 'tagged with reference (local promise)',
@@ -205,7 +210,9 @@ const table = [
     makeExpectedValue: testKit =>
       makeTagged(
         'listTag',
-        harden([testKit.referenceKit.provideRemoteObjectValue(102n), 'hello']),
+        /** @type {any} */ (
+          harden([testKit.referenceKit.provideRemoteObjectValue(102n), 'hello'])
+        ),
       ),
   },
   {