EReturn type (#2659)

incidental

## Description

Migrated from Agoric/agoric-sdk#9011

Define an `EReturn` type for the `Awaited<ReturnType<` pattern.

### Security Considerations

none
### Scaling Considerations

none

### Documentation Considerations

This will appear in TSdoc

### Testing Considerations

has tests

### Compatibility Considerations

none

### Upgrade Considerations

none

Author: turadg

packages/compartment-mapper/src/map-parser.js

@@ -18,6 +18,9 @@
  *   SyncModuleTransform,
  *   SyncModuleTransforms
  * } from './types.js';
+ * @import {
+ *   EReturn
+ * } from '@endo/eventual-send';
  */
 
 import { syncTrampoline, asyncTrampoline } from '@endo/trampoline';
@@ -82,7 +85,7 @@ const makeExtensionParser = (
    * @param {string} location
    * @param {string} packageLocation
    * @param {*} options
-   * @returns {Generator<ReturnType<ModuleTransform>|ReturnType<SyncModuleTransform>, ParseResult, Awaited<ReturnType<ModuleTransform>|ReturnType<SyncModuleTransform>>>}
+   * @returns {Generator<ReturnType<ModuleTransform>|ReturnType<SyncModuleTransform>, ParseResult, EReturn<ModuleTransform|SyncModuleTransform>>}
    */
   function* getParserGenerator(
     bytes,

packages/daemon/test/endo.test.js

@@ -28,6 +28,10 @@ import { makeCryptoPowers } from '../src/daemon-node-powers.js';
 import { formatId } from '../src/formula-identifier.js';
 import { idFromLocator, parseLocator } from '../src/locator.js';
 
+/**
+ * @import {EReturn} from '@endo/eventual-send';
+ */
+
 const cryptoPowers = makeCryptoPowers(crypto);
 
 const { raw } = String;
@@ -227,7 +231,7 @@ test.beforeEach(t => {
 
 test.afterEach.always(async t => {
   await Promise.allSettled(
-    /** @type {Awaited<ReturnType<prepareConfig>>[]} */ (t.context).flatMap(
+    /** @type {EReturn<typeof prepareConfig>[]} */ (t.context).flatMap(
       ({ cancel, cancelled, config }) => {
         cancel(Error('teardown'));
         return [cancelled, stop(config)];

packages/eventual-send/src/E.js

@@ -254,8 +254,11 @@ export default makeE;
 /** @typedef {ReturnType<makeE>} EProxy */
 
 /**
- * Creates a type that accepts both near and marshalled references that were
- * returned from `Remotable` or `Far`, and also promises for such references.
+ * Declare an object that is potentially a far reference of type Primary whose
+ * auxilliary data has type Local.  This should be used only for consumers of
+ * Far objects in arguments and declarations; the only creators of Far objects
+ * are distributed object creator components like the `Far` or `Remotable`
+ * functions.
  *
  * @template Primary The type of the primary reference.
  * @template [Local=DataOnly<Primary>] The local properties of the object.
@@ -274,14 +277,24 @@ export default makeE;
  * @see {@link https://github.com/microsoft/TypeScript/issues/31394}
  * @template T
  * @typedef {PromiseLike<T> | T} ERef
+ * Declare that `T` may or may not be a Promise.  This should be used only for
+ * consumers of arguments and declarations; return values should specifically be
+ * `Promise<T>` or `T` itself.
+ */
+
+/**
+ * The awaited return type of a function.
+ *
+ * @template {(...args: any[]) => any} T
+ * @typedef {T extends (...args: any[]) => infer R ? Awaited<R> : never} EReturn
  */
 
 /**
  * @template {import('./types.js').Callable} T
  * @typedef {(
  *   ReturnType<T> extends PromiseLike<infer U>                       // if function returns a promise
  *     ? T                                                            // return the function
- *     : (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>  // make it return a promise
+ *     : (...args: Parameters<T>) => Promise<EReturn<T>>  // make it return a promise
  * )} ECallable
  */
 
@@ -399,8 +412,9 @@ export default makeE;
  */
 
 /**
- * Type for an object that must only be invoked with E.  It supports a given
- * interface but declares all the functions as asyncable.
+ * Declare a near object that must only be invoked with E, even locally.  It
+ * supports the `T` interface but additionally permits `T`'s methods to return
+ * `PromiseLike`s even if `T` declares them as only synchronous.
  *
  * @template T
  * @typedef {(

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

@@ -12,6 +12,7 @@ export type {
   ERef,
   EProxy,
   EOnly,
+  EReturn,
   RemoteFunctions,
   LocalRecord,
   FilteredKeys,

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

@@ -1,7 +1,7 @@
 /* eslint-disable @endo/no-polymorphic-call, import/no-extraneous-dependencies, no-restricted-globals */
 import { expectType } from 'tsd';
 import { E } from '../test/_get-hp.js';
-import type { ERef, FarRef } from './exports.js';
+import type { ERef, EReturn, FarRef } from './exports.js';
 
 // Check the legacy ERef type
 const foo = async (a: ERef<{ bar(): string; baz: number }>) => {
@@ -21,6 +21,19 @@ const foo = async (a: ERef<{ bar(): string; baz: number }>) => {
   a.bar();
 };
 
+// EReturn
+{
+  const makeFoo = async () => 'foo' as const;
+  expectType<Promise<'foo'>>(makeFoo());
+  type Foo = EReturn<typeof makeFoo>;
+  expectType<Foo>('foo');
+
+  const fooP = Promise.resolve('foo' as const);
+  expectType<Promise<'foo'>>(fooP);
+  // @ts-expect-error takes only functions
+  EReturn<typeof fooP>;
+}
+
 // FarRef<T>
 const foo2 = async (a: FarRef<{ bar(): string; baz: number }>) => {
   const { baz } = await a;

packages/far/src/exports.d.ts

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

packages/far/src/exports.js

@@ -0,0 +1,2 @@
+// Just a dummy to use exports.d.ts and satisfy runtime imports.
+export {};

packages/far/src/index.js

@@ -1,30 +1,5 @@
 export { E } from '@endo/eventual-send';
 export { Far, getInterfaceOf, passStyleOf } from '@endo/pass-style';
 
-// TODO re-export from eventual-send, may require .d.ts
-/**
- * @template Primary
- * @template [Local=import('@endo/eventual-send').DataOnly<Primary>]
- * @typedef {import('@endo/eventual-send').FarRef<Primary, Local>} FarRef
- * Declare an object that is potentially a far reference of type Primary whose
- * auxilliary data has type Local.  This should be used only for consumers of
- * Far objects in arguments and declarations; the only creators of Far objects
- * are distributed object creator components like the `Far` or `Remotable`
- * functions.
- */
-
-/**
- * @template T
- * @typedef {import('@endo/eventual-send').ERef<T>} ERef
- * Declare that `T` may or may not be a Promise.  This should be used only for
- * consumers of arguments and declarations; return values should specifically be
- * `Promise<T>` or `T` itself.
- */
-
-/**
- * @template T
- * @typedef {import('@endo/eventual-send').EOnly<T>} EOnly
- * Declare a near object that must only be invoked with E, even locally.  It
- * supports the `T` interface but additionally permits `T`'s methods to return
- * `PromiseLike`s even if `T` declares them as only synchronous.
- */
+// eslint-disable-next-line import/export
+export * from './exports.js';