Improve eventual types (#2849)

Refs: Agoric/agoric-sdk#11454

## Description

Narrows some eventual-send types. In particular, ensure that the result
of an eventual call is a promise.

Add an `EResult` type which in the future can represent the return type
of an eventual send call where remotables are mapped as necessary to
their "brand" type only to avoid the caller from relying on what may
otherwise look like a local remotable instead of a presence.

This mapping is implemented in the `EAwaitedResult` type for explicit
usages, but not yet used in the type of `EResult` itself as it breaks
too many consumers of `E` that rely on the currently "incorrect" typing.

### Security Considerations

None

### Scaling Considerations

None

### Documentation Considerations

TBD

### Testing Considerations

Integration tested in agoric-sdk:
Agoric/agoric-sdk#12065
In a perfect world, I'd like to add some type tests of cases I've
encountered.

### Compatibility Considerations

None

### Upgrade Considerations

Type only changes, which we usually don't consider breaking.

Author: mhofman

packages/captp/src/loopback.js

@@ -5,7 +5,7 @@ import { makeFinalizingMap } from './finalize.js';
 
 export { E };
 
-/** @import {ERef} from '@endo/eventual-send' */
+/** @import {ERef, EResult} from '@endo/eventual-send' */
 
 /**
  * Create an async-isolated channel to an object.
@@ -14,9 +14,9 @@ export { E };
  * @param {import('./captp.js').CapTPOptions} [nearOptions]
  * @param {import('./captp.js').CapTPOptions} [farOptions]
  * @returns {{
- *   makeFar<T>(x: T): ERef<T>,
- *   makeNear<T>(x: T): ERef<T>,
- *   makeTrapHandler<T>(x: T): T,
+ *   makeFar<T>(x: T): Promise<EResult<T>>,
+ *   makeNear<T>(x: T): Promise<EResult<T>>,
+ *   makeTrapHandler<T>(name: string, x: T): T,
  *   isOnlyNear(x: any): boolean,
  *   isOnlyFar(x: any): boolean,
  *   getNearStats(): any,
@@ -92,13 +92,14 @@ export const makeLoopback = (ourId, nearOptions, farOptions) => {
     refGetter =>
     /**
      * @param {T} x
-     * @returns {Promise<T>}
+     * @returns {Promise<EResult<T>>}
      */
     async x => {
       lastNonce += 1;
       const myNonce = lastNonce;
       const val = await x;
       nonceToRef.set(myNonce, harden(val));
+      // @ts-expect-error Type 'T | Awaited<T>' is not assignable to type 'EResult<T>'
       return E(refGetter).getRef(myNonce);
     };
 

packages/daemon/src/networks/tcp-netstring.js

@@ -16,7 +16,7 @@ const protocol = 'tcp+netstring+json+captp0';
 export const make = async (powers, context) => {
   const { servePort, connectPort } = makeSocketPowers({ net });
 
-  const cancelled = E(context).whenCancelled();
+  const cancelled = /** @type {Promise<never>} */ (E(context).whenCancelled());
   const cancelServer = error => E(context).cancel(error);
 
   /** @type {Array<string>} */
@@ -122,7 +122,9 @@ export const make = async (powers, context) => {
     const { port: portname, hostname: host } = new URL(address);
     const port = Number(portname);
 
-    const connectionCancelled = E(connectionContext).whenCancelled();
+    const connectionCancelled = /** @type {Promise<never>} */ (
+      E(connectionContext).whenCancelled()
+    );
     const cancelConnection = () => E(connectionContext).cancel();
 
     const {

packages/eventual-send/src/E.js

@@ -5,7 +5,7 @@ const { details: X, quote: q, Fail, error: makeError } = assert;
 const { assign, freeze } = Object;
 
 /**
- * @import { HandledPromiseConstructor } from './types.js';
+ * @import { HandledPromiseConstructor, RemotableBrand, Callable, Settler } from './types.js';
  */
 
 const onSend = makeMessageBreakpointTester('ENDO_SEND_BREAKPOINTS');
@@ -282,15 +282,15 @@ export default makeE;
  *
  * @template Primary The type of the primary reference.
  * @template [Local=DataOnly<Primary>] The local properties of the object.
- * @typedef {ERef<Local & import('./types.js').RemotableBrand<Local, Primary>>} FarRef
+ * @typedef {ERef<Local & RemotableBrand<Local, Primary>>} FarRef
  */
 
 /**
  * `DataOnly<T>` means to return a record type `T2` consisting only of
  * properties that are *not* functions.
  *
  * @template T The type to be filtered.
- * @typedef {Omit<T, FilteredKeys<T, import('./types.js').Callable>>} DataOnly
+ * @typedef {Omit<T, FilteredKeys<T, Callable>>} DataOnly
  */
 
 /**
@@ -304,24 +304,69 @@ export default makeE;
 
 /**
  * The awaited return type of a function.
+ * For the eventual result of an E call, @see {EResult} or @see {ECallableReturn}
  *
  * @template {(...args: any[]) => any} T
  * @typedef {T extends (...args: any[]) => infer R ? Awaited<R> : never} EReturn
  */
 
 /**
- * @template {import('./types.js').Callable} T
+ * An eventual value where remotable objects are recursively mapped to Remote types
+ *
+ * @template T
+ * @typedef {Awaited<T>} EResult
+ */
+
+/**
+ * Experimental type mapping remotable objects to Remote types
+ *
+ * @template T
  * @typedef {(
- *   ReturnType<T> extends PromiseLike<infer U>                       // if function returns a promise
- *     ? T                                                            // return the function
- *     : (...args: Parameters<T>) => Promise<EReturn<T>>  // make it return a promise
+ *   0 extends (1 & T)                                        // If T is any
+ *     ? T                                                    // Propagate the any type through the result
+ *     : T extends RemotableBrand<infer L, infer P>           // If we have a Remotable
+ *       ? (P | RemotableBrand<L, P>)                         // map it to its "maybe remote" form (primary behavior or remotable presence)
+ *       : T extends PromiseLike<infer U>                     // If T is a promise
+ *         ? Promise<EAwaitedResult<Awaited<T>>>              // map its resolution
+ *         : T extends (null | undefined | string | number | boolean | symbol | bigint | Callable) // Intersections of these types with objects are not mapped
+ *           ? T                                              // primitives and non-remotable functions are passed-through
+ *           : T extends object                               //
+ *             ? { [P in keyof T]: EAwaitedResult<T[P]>; }    // other objects are considered copy data and properties mapped
+ *             : T                                            // in case anything wasn't covered, fallback to pass-through
+ * )} EAwaitedResult
+ */
+
+/**
+ * The @see {EResult} return type of a remote function.
+ *
+ * @template {(...args: any[]) => any} T
+ * @typedef {(
+ *   0 extends (1 & T)                          // If T is any
+ *     ? any                                    // Propagate the any type through the result
+ *     : T extends (...args: any[]) => infer R  // Else infer the return type
+ *       ? EResult<R>                           // In the future, map the eventual result
+ *       : never
+ * )} ECallableReturn
+ */
+
+// TODO: Figure out a way to map generic callable return types, or at least better detect them.
+// See https://github.com/microsoft/TypeScript/issues/61838. Without that, `E(startGovernedUpgradable)`
+// in agoric-sdk doesn't propagate the start function type.
+/**
+ * Maps a callable to its remotely called type
+ *
+ * @template {Callable} T
+ * @typedef {(
+ *    ReturnType<T> extends PromiseLike<infer U>                  // Check if callable returns a promise
+ *      ? T                                                       // Bypass mapping to maintain any generic
+ *      : (...args: Parameters<T>) => Promise<ECallableReturn<T>> // Map it anyway to ensure promise return type
  * )} ECallable
  */
 
 /**
  * @template T
  * @typedef {{
- *   readonly [P in keyof T]: T[P] extends import('./types.js').Callable
+ *   readonly [P in keyof T]: T[P] extends Callable
  *     ? ECallable<T[P]>
  *     : never;
  * }} EMethods
@@ -337,14 +382,14 @@ export default makeE;
  */
 
 /**
- * @template {import('./types.js').Callable} T
+ * @template {Callable} T
  * @typedef {(...args: Parameters<T>) => Promise<void>} ESendOnlyCallable
  */
 
 /**
  * @template T
  * @typedef {{
- *   readonly [P in keyof T]: T[P] extends import('./types.js').Callable
+ *   readonly [P in keyof T]: T[P] extends Callable
  *     ? ESendOnlyCallable<T[P]>
  *     : never;
  * }} ESendOnlyMethods
@@ -353,18 +398,22 @@ export default makeE;
 /**
  * @template T
  * @typedef {(
- *   T extends import('./types.js').Callable
+ *   T extends Callable
  *     ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>>
- *     : ESendOnlyMethods<Required<T>>
+ *     : 0 extends (1 & T)
+ *       ? never
+ *       : ESendOnlyMethods<Required<T>>
  * )} ESendOnlyCallableOrMethods
  */
 
 /**
  * @template T
  * @typedef {(
- *   T extends import('./types.js').Callable
+ *   T extends Callable
  *     ? ECallable<T> & EMethods<Required<T>>
- *     : EMethods<Required<T>>
+ *     : 0 extends (1 & T)
+ *       ? never
+ *       : EMethods<Required<T>>
  * )} ECallableOrMethods
  */
 
@@ -389,9 +438,9 @@ export default makeE;
  *
  * @template T
  * @typedef {(
- *   T extends import('./types.js').Callable
+ *   T extends Callable
  *     ? (...args: Parameters<T>) => ReturnType<T>                     // a root callable, no methods
- *     : Pick<T, FilteredKeys<T, import('./types.js').Callable>>          // any callable methods
+ *     : Pick<T, FilteredKeys<T, Callable>>          // any callable methods
  * )} PickCallable
  */
 
@@ -400,25 +449,21 @@ export default makeE;
  *
  * @template T
  * @typedef {(
- *   T extends import('./types.js').RemotableBrand<infer L, infer R>     // if a given T is some remote interface R
- *     ? PickCallable<R>                                              // then return the callable properties of R
- *     : Awaited<T> extends import('./types.js').RemotableBrand<infer L, infer R> // otherwise, if the final resolution of T is some remote interface R
- *     ? PickCallable<R>                                              // then return the callable properties of R
- *     : T extends PromiseLike<infer U>                               // otherwise, if T is a promise
- *     ? Awaited<T>                                                   // then return resolved value T
- *     : T                                                            // otherwise, return T
+ *   T extends RemotableBrand<infer L, infer R>   // if a given T is some remote interface R
+ *     ? PickCallable<R>                          // then return the callable properties of R
+ *     : T extends PromiseLike<infer U>           // otherwise, if T is a promise
+ *       ? RemoteFunctions<U>                     // recurse on the resolved value of T
+ *       : T                                      // otherwise, return T
  * )} RemoteFunctions
  */
 
 /**
  * @template T
  * @typedef {(
- *   T extends import('./types.js').RemotableBrand<infer L, infer R>
- *     ? L
- *     : Awaited<T> extends import('./types.js').RemotableBrand<infer L, infer R>
+ *   T extends RemotableBrand<infer L, infer R>
  *     ? L
  *     : T extends PromiseLike<infer U>
- *     ? Awaited<T>
+ *     ? LocalRecord<U>
  *     : T
  * )} LocalRecord
  */
@@ -427,7 +472,7 @@ export default makeE;
  * @template [R = unknown]
  * @typedef {{
  *   promise: Promise<R>;
- *   settler: import('./types.js').Settler<R>;
+ *   settler: Settler<R>;
  * }} EPromiseKit
  */
 
@@ -438,11 +483,11 @@ export default makeE;
  *
  * @template T
  * @typedef {(
- *   T extends import('./types.js').Callable
+ *   T extends Callable
  *     ? (...args: Parameters<T>) => ERef<Awaited<EOnly<ReturnType<T>>>>
- *     : T extends Record<PropertyKey, import('./types.js').Callable>
+ *     : T extends Record<PropertyKey, Callable>
  *     ? {
- *         [K in keyof T]: T[K] extends import('./types.js').Callable
+ *         [K in keyof T]: T[K] extends Callable
  *           ? (...args: Parameters<T[K]>) => ERef<Awaited<EOnly<ReturnType<T[K]>>>>
  *           : T[K];
  *       }

packages/eventual-send/src/exports.d.ts

@@ -13,6 +13,8 @@ export type {
   EProxy,
   EOnly,
   EReturn,
+  EResult,
+  ECallableReturn,
   RemoteFunctions,
   LocalRecord,
   FilteredKeys,

packages/far/src/exports.d.ts

@@ -1 +1 @@
-export { FarRef, ERef, EOnly, EReturn } from '@endo/eventual-send';
+export { FarRef, ERef, EOnly, EReturn, EResult } from '@endo/eventual-send';