@endo/eventual-send 0.14.7 → 0.15.1

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+### [0.15.1](https://github.com/endojs/endo/compare/@endo/eventual-send@0.15.0...@endo/eventual-send@0.15.1) (2022-04-13)
+
+
+### Bug Fixes
+
+* Revert dud release ([c8a7101](https://github.com/endojs/endo/commit/c8a71017d8d7af10a97909c9da9c5c7e59aed939))
+
+
+
+## [0.15.0](https://github.com/endojs/endo/compare/@endo/eventual-send@0.14.8...@endo/eventual-send@0.15.0) (2022-04-12)
+
+
+### ⚠ BREAKING CHANGES
+
+* **far:** rename `Remote` to `FarRef`
+
+### Features
+
+* **far:** rename `Remote` to `FarRef` ([7bde2bf](https://github.com/endojs/endo/commit/7bde2bf28e88935606564cebd1b8d284cd70e4ef))
+
+
+### Bug Fixes
+
+* **eventual-send:** evolve types based on marshal requirements ([ff388fa](https://github.com/endojs/endo/commit/ff388fa2f81446c1ae02618b78771dc17ce5c74b))
+* **eventual-send:** unwrap promises more fully ([6ba799f](https://github.com/endojs/endo/commit/6ba799f77e8d55530ecd7617c3ccad22324bade2))
+
+
+
+### [0.14.8](https://github.com/endojs/endo/compare/@endo/eventual-send@0.14.7...@endo/eventual-send@0.14.8) (2022-03-07)
+
+
+### Features
+
+* **eventual-send:** provide typing for `Remote<Primary, Local>` ([4d28509](https://github.com/endojs/endo/commit/4d285095a6ea1a78f1a3a4696bc822f5e4dfd43f))
+
+
+### Bug Fixes
+
+* **eventual-send:** properly declare `E` to be type `EProxy` ([3bdfdf7](https://github.com/endojs/endo/commit/3bdfdf77440f9ddea9bac1e783aaf015e9bcfa62))
+
+
+
 ### [0.14.7](https://github.com/endojs/endo/compare/@endo/eventual-send@0.14.6...@endo/eventual-send@0.14.7) (2022-03-02)
 
 **Note:** Version bump only for package @endo/eventual-send

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endo/eventual-send",
-  "version": "0.14.7",
+  "version": "0.15.1",
   "description": "Extend a Promise class to implement the eventual-send API",
   "type": "module",
   "main": "src/no-shim.js",
@@ -13,7 +13,7 @@
     "lint-fix": "yarn lint:eslint --fix && yarn lint:types",
     "lint-check": "yarn lint",
     "lint": "yarn lint:types && yarn lint:eslint",
-    "lint:types": "tsc -p jsconfig.json",
+    "lint:types": "tsc",
     "lint:eslint": "eslint '**/*.js'"
   },
   "repository": {
@@ -27,10 +27,11 @@
   },
   "homepage": "https://github.com/endojs/endo#readme",
   "devDependencies": {
-    "@endo/lockdown": "^0.1.8",
-    "@endo/ses-ava": "^0.2.20",
+    "@endo/lockdown": "^0.1.11",
+    "@endo/ses-ava": "^0.2.23",
     "ava": "^3.12.1",
-    "c8": "^7.7.3"
+    "c8": "^7.7.3",
+    "tsd": "^0.19.1"
   },
   "keywords": [
     "eventual send",
@@ -61,5 +62,5 @@
     ],
     "timeout": "2m"
   },
-  "gitHead": "08973d4fc6358a58d733251b051b2812bb4c651a"
+  "gitHead": "ada5203fd64e6828dca74895fd74588e08925d97"
 }

package/src/E.js

@@ -23,7 +23,7 @@ const baseFreezableProxyHandler = {
  * A Proxy handler for E(x).
  *
  * @param {*} x Any value passed to E(x)
- * @param {*} HandledPromise
+ * @param {import('./index').HandledPromiseConstructor} HandledPromise
  * @returns {ProxyHandler} the Proxy handler
  */
 function EProxyHandler(x, HandledPromise) {
@@ -47,7 +47,7 @@ function EProxyHandler(x, HandledPromise) {
  * It is a variant on the E(x) Proxy handler.
  *
  * @param {*} x Any value passed to E.sendOnly(x)
- * @param {*} HandledPromise
+ * @param {import('./index').HandledPromiseConstructor} HandledPromise
  * @returns {ProxyHandler} the Proxy handler
  */
 function EsendOnlyProxyHandler(x, HandledPromise) {
@@ -70,6 +70,10 @@ function EsendOnlyProxyHandler(x, HandledPromise) {
   });
 }
 
+/**
+ * @param {import('./index').HandledPromiseConstructor} HandledPromise
+ * @returns {import('./index').EProxy}
+ */
 export default function makeE(HandledPromise) {
   function E(x) {
     const handler = EProxyHandler(x, HandledPromise);
@@ -94,7 +98,7 @@ export default function makeE(HandledPromise) {
     return harden(new Proxy(() => {}, handler));
   };
 
-  E.when = (x, onfulfilled = undefined, onrejected = undefined) => {
+  E.when = (x, onfulfilled, onrejected) => {
     const [onsuccess, onfailure] = trackTurns([onfulfilled, onrejected]);
     return HandledPromise.resolve(x).then(onsuccess, onfailure);
   };

package/src/handled-promise.js

@@ -393,7 +393,7 @@ export const makeHandledPromise = () => {
     );
   };
 
-  /** @type {import('.').HandledPromiseStaticMethods} */
+  /** @type {import('.').HandledPromiseStaticMethods & Pick<PromiseConstructor, 'resolve'>} */
   const staticMethods = {
     get(target, prop) {
       prop = coerceToObjectProperty(prop);

package/src/index.d.ts

@@ -1,16 +1,41 @@
-/* eslint-disable no-shadow,no-use-before-define,no-var,vars-on-top */
 // Type definitions for eventual-send
-// TODO: Add jsdocs.
 
-type Property = string | number | symbol;
+/**
+ * @file Type definitions for @agoric/eventual-send
+ *
+ * Some useful background knowledge:
+ *
+ * `Omit<T, U>` means to return a record type `T2` which has none of the properties whose keys are part of `U`.
+ * `Omit<{a: 1, b: 2, c: 3}, 'b'>` is the type `{a: 1, c: 3}`.
+ *
+ * `Pick<T, U>` means to return a record type `T2` which has only the properties whose keys are part of `U`.
+ * `Pick<{a: 1, b: 2, c: 3}, 'b'>` is the type `{b: 2}`.
+ *
+ * `PromiseLike<T>` is a thenable which resolves to `T`.
+ *
+ * `Promise<PromiseLike<T>>` doesn't handle recursion and is distinct from `T`.
+ *
+ * `Unpromise<PromiseLike<T>>` strips off just one layer and is just `T`.  `Unpromise<PromiseLike<PromiseLIke<T>>` is `PromiseLike<T>`.
+ *
+ * `Awaited<PromiseLike<T>>` recurses, and is just `T`.
+ * `Awaited<PromiseLike<PromiseLike<T>>>` is just `T` as well.
+ *
+ * @see {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#handbook-content}
+ * @see {@link https://www.typescriptlang.org/docs/handbook/2/conditional-types.html}
+ */
 
-type ERef<T> = PromiseLike<T> | T;
+export type Callable = (...args: any[]) => any;
+
+// Same as https://github.com/microsoft/TypeScript/issues/31394
+export type ERef<T> = PromiseLike<T> | T;
+
+export declare const EmptyObj: {};
 
 // Type for an object that must only be invoked with E.  It supports a given
 // interface but declares all the functions as asyncable.
 export type EOnly<T> = T extends (...args: infer P) => infer R
-  ? (...args: P) => ERef<R> | EOnly<R>
-  : T extends Record<string | number | symbol, Function>
+  ? (...args: P) => ERef<Awaited<R>> | EOnly<Awaited<R>>
+  : T extends Record<PropertyKey, Callable>
   ? ERef<
       {
         [K in keyof T]: EOnly<T[K]>;
@@ -18,30 +43,99 @@ export type EOnly<T> = T extends (...args: infer P) => infer R
     >
   : ERef<T>;
 
-type Unpromise<T> = T extends ERef<infer U> ? U : T;
+/**
+ * Return a union of property names/symbols/numbers P for which the record element T[P]'s type extends U.
+ *
+ * Given const x = { a: 123, b: 'hello', c: 42, 49: () => {}, 53: 67 },
+ *
+ * FilteredKeys<typeof x, number> is the type 'a' | 'c' | 53.
+ * FilteredKeys<typeof x, string> is the type 'b'.
+ * FilteredKeys<typeof x, 42 | 67> is the type 'c' | 53.
+ * FilteredKeys<typeof x, boolean> is the type never.
+ */
+export type FilteredKeys<T, U> = {
+  [P in keyof T]: T[P] extends U ? P : never;
+}[keyof T];
+
+/**
+ * `DataOnly<T>` means to return a record type `T2` consisting only of properties that are *not* functions.
+ */
+export type DataOnly<T> = Omit<T, FilteredKeys<T, Callable>>;
 
-type Parameters<T> = T extends (...args: infer T) => any ? T : any;
-type ReturnType<T> = T extends (...args: any[]) => infer T ? T : any;
+// Nominal type to carry the local and remote interfaces of a Remotable.
+export declare class RemotableBrand<L, R> {
+  // The local properties of the object.
+  private localProperties: L;
+
+  // The type of all the remotely-callable functions.
+  private remoteCallable: R;
+}
 
-interface EHandler<T> {
-  get?: (p: T, name: Property, returnedP?: Promise<unknown>) => any;
-  getSendOnly?: (p: T, name: Property) => void;
-  applyFunction?: (p: T, args: unknown[], returnedP?: Promise<unknown>) => any;
+/**
+ * Creates a type that accepts both near and marshalled references that were
+ * returned from `Remotable` or `Far`, and also promises for such references.
+ */
+export type FarRef<Primary, Local = DataOnly<Primary>> = ERef<
+  Local & RemotableBrand<Local, Primary>
+>;
+
+/**
+ * `PickCallable<T>` means to return a single root callable or a record type
+ * consisting only of properties that are functions.
+ */
+export type PickCallable<T> = T extends Callable
+  ? (...args: Parameters<T>) => ReturnType<T> // a root callable, no methods
+  : Pick<T, FilteredKeys<T, Callable>>; // any callable methods
+
+/**
+ * `RemoteFunctions<T>` means to return the functions and properties that are remotely callable.
+ */
+export type RemoteFunctions<T> = T extends RemotableBrand<infer L, infer R> // if a given T is some remote interface R
+  ? PickCallable<R> // then use the function properties of R
+  : Awaited<T> extends RemotableBrand<infer L, infer R> // otherwise, if the final resolution of T is some remote interface R
+  ? PickCallable<R> // then use the function properties of R
+  : T extends PromiseLike<infer U>
+  ? Awaited<T> // otherwise, use the final resolution of that T
+  : T;
+
+export type LocalRecord<T> = T extends RemotableBrand<infer L, infer R>
+  ? L
+  : Awaited<T> extends RemotableBrand<infer L, infer R>
+  ? L
+  : T extends PromiseLike<infer U>
+  ? Awaited<T>
+  : T;
+export interface EHandler<T> {
+  get?: (p: T, name: PropertyKey, returnedP?: Promise<unknown>) => unknown;
+  getSendOnly?: (p: T, name: PropertyKey) => void;
+  applyFunction?: (
+    p: T,
+    args: unknown[],
+    returnedP?: Promise<unknown>,
+  ) => unknown;
   applyFunctionSendOnly?: (p: T, args: unknown[]) => void;
   applyMethod?: (
     p: T,
-    name: Property | undefined,
+    name: PropertyKey | undefined,
     args: unknown[],
     returnedP?: Promise<unknown>,
-  ) => any;
+  ) => unknown;
   applyMethodSendOnly?: (
     p: T,
-    name: Property | undefined,
+    name: PropertyKey | undefined,
     args: unknown[],
   ) => void;
 }
 
-type HandledExecutor<R> = (
+export type ResolveWithPresenceOptionsBag<T extends Object> = {
+  proxy?: {
+    handler: ProxyHandler<T>;
+    target: unknown;
+    revokerCallback?: (revoker: () => void) => void;
+  };
+};
+
+export type HandledExecutor<R> = (
   resolveHandled: (value?: R) => void,
   rejectHandled: (reason?: unknown) => void,
   resolveWithPresence: (
@@ -50,30 +144,24 @@ type HandledExecutor<R> = (
   ) => object,
 ) => void;
 
-type ResolveWithPresenceOptionsBag<T extends Object> = {
-  proxy?: {
-    handler: ProxyHandler<T>;
-    target: unknown;
-    revokerCallback?: (revoker: () => void) => void;
-  };
-};
-
 declare interface HandledPromiseStaticMethods {
-  resolve<T>(x: T): Promise<Unpromise<T>>;
-  resolve(): Promise<undefined>;
   applyFunction(target: unknown, args: unknown[]): Promise<unknown>;
   applyFunctionSendOnly(target: unknown, args: unknown[]): void;
   applyMethod(
     target: unknown,
-    prop: Property | undefined,
+    prop: PropertyKey | undefined,
     args: unknown[],
   ): Promise<unknown>;
-  applyMethodSendOnly(target: unknown, prop: Property, args: unknown[]): void;
-  get(target: unknown, prop: Property): Promise<unknown>;
-  getSendOnly(target: unknown, prop: Property): void;
+  applyMethodSendOnly(
+    target: unknown,
+    prop: PropertyKey,
+    args: unknown[],
+  ): void;
+  get(target: unknown, prop: PropertyKey): Promise<unknown>;
+  getSendOnly(target: unknown, prop: PropertyKey): void;
 }
 
-declare interface HandledPromiseConstructor
+export interface HandledPromiseConstructor
   extends PromiseConstructor,
     HandledPromiseStaticMethods {
   new <R>(
@@ -83,43 +171,59 @@ declare interface HandledPromiseConstructor
   prototype: Promise<unknown>;
 }
 
-declare var HandledPromise: HandledPromiseConstructor;
-
 declare namespace global {
+  // eslint-disable-next-line vars-on-top,no-var
   var HandledPromise: HandledPromiseConstructor;
 }
 
-declare function makeHandledPromise(): HandledPromiseConstructor;
+export declare const HandledPromise: HandledPromiseConstructor;
+
+/**
+ * "E" short for "Eventual", what we call something that has to return a promise.
+ */
+type ECallable<T extends Callable> = ReturnType<T> extends PromiseLike<infer U>
+  ? T // function already returns a promise
+  : (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>; // make it return a promise
 
 /* Types for E proxy calls. */
-type ESingleMethod<T> = {
-  readonly [P in keyof T]: (
-    ...args: Parameters<T[P]>
-  ) => Promise<Unpromise<ReturnType<T[P]>>>;
+
+/**
+ * Transform each function in T to return a promise
+ */
+type EMethods<T> = {
+  readonly [P in keyof T]: T[P] extends Callable ? ECallable<T[P]> : never;
 };
-type ESingleCall<T> = T extends Function
-  ? ((...args: Parameters<T>) => Promise<Unpromise<ReturnType<T>>>) &
-      ESingleMethod<Required<T>>
-  : ESingleMethod<Required<T>>;
-type ESingleGet<T> = {
-  readonly [P in keyof T]: Promise<Unpromise<T[P]>>;
+
+type ECallableOrMethods<T> = T extends Callable
+  ? ECallable<T> & EMethods<Required<T>>
+  : EMethods<Required<T>>;
+
+type EGetters<T> = {
+  readonly [P in keyof T]: T[P] extends PromiseLike<infer U>
+    ? T[P]
+    : Promise<Awaited<T[P]>>;
 };
 
 /* Same types for send-only. */
-type ESingleMethodOnly<T> = {
-  readonly [P in keyof T]: (...args: Parameters<T[P]>) => void;
-};
-type ESingleCallOnly<T> = T extends Function
-  ? ((...args: Parameters<T>) => void) & ESingleMethodOnly<T>
-  : ESingleMethodOnly<T>;
-type ESingleGetOnly<T> = {
-  readonly [P in keyof T]: void;
+type ESendOnlyCallable<T extends Callable> = (
+  ...args: Parameters<T>
+) => Promise<void>;
+
+type ESendOnlyMethods<T> = {
+  readonly [P in keyof T]: T[P] extends Callable
+    ? ESendOnlyCallable<T[P]>
+    : never;
 };
 
+type ESendOnlyCallableOrMethods<T> = T extends Callable
+  ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>>
+  : ESendOnlyMethods<Required<T>>;
+
 interface ESendOnly {
-  <T>(x: T): ESingleCallOnly<Unpromise<T>>;
+  <T>(x: T): ESendOnlyCallableOrMethods<RemoteFunctions<T>>;
 }
 
+// Generic on the proxy target {T}
 interface EProxy {
   /**
    * E(x) returns a proxy on which you can call arbitrary methods. Each of
@@ -127,10 +231,10 @@ interface EProxy {
    * whatever 'x' designates (or resolves to) in a future turn, not this
    * one.
    *
-   * @param {*} x target for method/function call
-   * @returns {ESingleCall} method/function call proxy
+   * @param x target for method/function call
+   * @returns method/function call proxy
    */
-  <T>(x: T): ESingleCall<Unpromise<T>>;
+  <T>(x: T): ECallableOrMethods<RemoteFunctions<T>>;
 
   /**
    * E.get(x) returns a proxy on which you can get arbitrary properties.
@@ -138,16 +242,16 @@ interface EProxy {
    * value will be the property fetched from whatever 'x' designates (or
    * resolves to) in a future turn, not this one.
    *
-   * @param {*} x target for property get
-   * @returns {ESingleGet} property get proxy
+   * @param x target for property get
+   * @returns property get proxy
    */
-  readonly get: <T>(x: T) => ESingleGet<Unpromise<T>>;
+  readonly get: <T>(x: T) => EGetters<LocalRecord<T>>;
 
   /**
    * E.resolve(x) converts x to a handled promise. It is
    * shorthand for HandledPromise.resolve(x)
    */
-  readonly resolve: <T>(x: T) => Promise<Unpromise<T>>;
+  readonly resolve: <T>(x: T) => Promise<Awaited<T>>;
 
   /**
    * E.when(x, res, rej) is equivalent to
@@ -155,7 +259,7 @@ interface EProxy {
    */
   readonly when: <T, U>(
     x: T,
-    onfulfilled?: (value: Unpromise<T>) => ERef<U>,
+    onfulfilled?: (value: Awaited<T>) => ERef<U>,
     onrejected?: (reason: any) => ERef<U>,
   ) => Promise<U>;
 

package/src/index.test-d.ts

@@ -0,0 +1,48 @@
+/* eslint-disable @endo/no-polymorphic-call, import/no-extraneous-dependencies, no-restricted-globals, prettier/prettier */
+import { expectType } from 'tsd';
+import { E } from '../test/get-hp.js';
+import { DataOnly, ERef } from './index.js';
+
+type FarRef<
+  Primary,
+  Local = DataOnly<Primary>
+> = import('@endo/eventual-send').FarRef<Primary, Local>;
+
+// Check the legacy ERef type
+const foo = async (a: ERef<{ bar(): string; baz: number }>) => {
+  const { baz } = await a;
+
+  expectType<Promise<string>>(E(a).bar());
+
+  // Should be type error, but isn't.
+  (await a).bar();
+
+  expectType<Promise<number>>(E.get(a).baz);
+
+  // Should be type error, but isn't.
+  expectType<Promise<() => string>>(E.get(a).bar);
+
+  // @ts-expect-error - calling a directly is not typed, but works.
+  a.bar();
+};
+
+// FarRef<T>
+const foo2 = async (a: FarRef<{ bar(): string; baz: number }>) => {
+  const { baz } = await a;
+  expectType<number>(baz);
+
+  expectType<Promise<string>>(E(a).bar());
+
+  // @ts-expect-error - awaiting remotes cannot get functions
+  (await a).bar;
+
+  expectType<Promise<number>>(E.get(a).baz);
+
+  // @ts-expect-error - E.get cannot obtain remote functions
+  E.get(a).bar;
+
+  expectType<number>((await a).baz);
+
+  // @ts-expect-error - calling directly is valid but not yet in the typedef
+  a.bar;
+};