@agoric/internal 0.2.2-pismo-dev-0d5327f.0 → 0.3.0

package/src/upgrade-api.js

@@ -0,0 +1,41 @@
+// @ts-check
+// @jessie-check
+import { isObject } from '@endo/marshal';
+
+/**
+ * @typedef {{ name: string, upgradeMessage: string, incarnationNumber: number }} DisconnectionObject
+ */
+
+/**
+ * Makes an Error-like object for use as the rejection value of promises
+ * abandoned by upgrade.
+ *
+ * @param {string} upgradeMessage
+ * @param {number} toIncarnationNumber
+ * @returns {DisconnectionObject}
+ */
+export const makeUpgradeDisconnection = (upgradeMessage, toIncarnationNumber) =>
+  harden({
+    name: 'vatUpgraded',
+    upgradeMessage,
+    incarnationNumber: toIncarnationNumber,
+  });
+harden(makeUpgradeDisconnection);
+
+// TODO: Simplify once we have @endo/patterns (or just export the shape).
+// const upgradeDisconnectionShape = harden({
+//   name: 'vatUpgraded',
+//   upgradeMessage: M.string(),
+//   incarnationNumber: M.number(),
+// });
+// const isUpgradeDisconnection = err => matches(err, upgradeDisconnectionShape);
+/**
+ * @param {any} err
+ * @returns {err is DisconnectionObject}
+ */
+export const isUpgradeDisconnection = err =>
+  isObject(err) &&
+  err.name === 'vatUpgraded' &&
+  typeof err.upgradeMessage === 'string' &&
+  typeof err.incarnationNumber === 'number';
+harden(isUpgradeDisconnection);

package/src/utils.d.ts

@@ -0,0 +1,67 @@
+export const BASIS_POINTS: 10000n;
+export function fromUniqueEntries<K, V>(allEntries: Iterable<[K, V]>): {};
+export function objectMap<O extends Record<string, any>, R>(original: O, mapFn: (value: O[keyof O], key: keyof O) => R): { [P in keyof O]: R; };
+export function listDifference(leftNames: Array<string | symbol>, rightNames: Array<string | symbol>): (string | symbol)[];
+export function throwLabeled(innerErr: Error, label: string | number, ErrorConstructor?: ErrorConstructor | undefined): never;
+export function applyLabelingError<A, R>(func: (...args: A[]) => R, args: A[], label?: string | number | undefined): R;
+/**
+ * @template T
+ * @typedef {{[KeyType in keyof T]: T[KeyType]} & {}} Simplify
+ * flatten the type output to improve type hints shown in editors
+ * https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+ */
+/**
+ * @typedef {(...args: any[]) => any} Callable
+ */
+/**
+ * @template {{}} T
+ * @typedef {{ [K in keyof T]: T[K] extends Callable ? T[K] : DeeplyAwaited<T[K]> }} DeeplyAwaitedObject
+ */
+/**
+ * @template T
+ * @typedef {T extends PromiseLike<any> ? Awaited<T> : T extends {} ? Simplify<DeeplyAwaitedObject<T>> : Awaited<T>} DeeplyAwaited
+ */
+/**
+ * A more constrained version of {deeplyFulfilled} for type safety until
+ * https://github.com/endojs/endo/issues/1257
+ * Useful in starting contracts that need all terms to be fulfilled
+ * in order to be durable.
+ *
+ * @type {<T extends {}>(unfulfilledTerms: T) => Promise<DeeplyAwaited<T>>}
+ */
+export const deeplyFulfilledObject: <T extends {}>(unfulfilledTerms: T) => Promise<DeeplyAwaited<T>>;
+export function makeMeasureSeconds(currentTimeMillisec: typeof import('perf_hooks').performance.now): <T>(fn: () => Promise<T>) => Promise<{
+    result: T;
+    duration: number;
+}>;
+export function makeAggregateError(errors: Error[], message?: string | undefined): Error;
+export function PromiseAllOrErrors<T>(items: readonly (T | PromiseLike<T>)[]): Promise<T[]>;
+/**
+ * @type {<T>(
+ *   trier: () => Promise<T>,
+ *  finalizer: (error?: unknown) => Promise<void>,
+ * ) => Promise<T>}
+ */ export const aggregateTryFinally: <T>(trier: () => Promise<T>, finalizer: (error?: unknown) => Promise<void>) => Promise<T>;
+export function assertAllDefined<T extends Record<string, unknown>>(obj: T): asserts obj is AllDefined<T>;
+export const forever: AsyncIterable<undefined>;
+export function whileTrue<T>(produce: () => T): AsyncIterable<Awaited<T>>;
+export function untilTrue<T>(produce: () => T): AsyncIterable<Awaited<T>>;
+/** @type { <X, Y>(xs: X[], ys: Y[]) => [X, Y][]} */
+export const zip: <X, Y>(xs: X[], ys: Y[]) => [X, Y][];
+/** @type { <T extends Record<string, ERef<any>>>(obj: T) => Promise<{ [K in keyof T]: Awaited<T[K]>}> } */
+export const allValues: <T extends Record<string, any>>(obj: T) => Promise<{ [K in keyof T]: Awaited<T[K]>; }>;
+export function synchronizedTee<T = unknown>(sourceStream: AsyncIterator<T, void, void>, readerCount: number): AsyncGenerator<T, void, void>[];
+/**
+ * <T>
+ */
+export type ERef<T> = import('@endo/eventual-send').ERef<T>;
+/**
+ * flatten the type output to improve type hints shown in editors
+ * https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+ */
+export type Simplify<T> = { [KeyType_1 in keyof T]: T[KeyType_1]; };
+export type Callable = (...args: any[]) => any;
+export type DeeplyAwaitedObject<T extends {}> = { [K in keyof T]: T[K] extends Callable ? T[K] : DeeplyAwaited<T[K]>; };
+export type DeeplyAwaited<T> = T extends PromiseLike<any> ? Awaited<T> : T extends {} ? Simplify<DeeplyAwaitedObject<T>> : Awaited<T>;
+export type AllDefined<T extends Record<string, unknown>> = { [P in keyof T]: Exclude<T[P], undefined>; };
+//# sourceMappingURL=utils.d.ts.map

package/src/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.js"],"names":[],"mappings":"AAcA,kCAAoC;AAa7B,0EAcN;AA0CM,gJAIN;AAOM,0CAHI,MAAM,MAAM,GAAG,MAAM,CAAC,cACtB,MAAM,MAAM,GAAG,MAAM,CAAC,uBAKhC;AASM,uCALI,KAAK,SACL,MAAM,GAAC,MAAM,oDAEX,KAAK,CAYjB;AAUM,uHAyBN;AAGD;;;;;GAKG;AAEH;;GAEG;AAEH;;;GAGG;AAEH;;;GAGG;AAEH;;;;;;;GAOG;AACH,qGAGE;AAUK,wDAHI,cAAc,YAAY,EAAE,WAAW,CAAC,GAAG;;cACmB,MAAM;GAW9E;AAMM,2CAHI,KAAK,EAAE,uCAcjB;AAOM,4FAeN;AAED;;;;;GAKG,CAAC,mFAFoB,OAAO,KAAK,QAAQ,IAAI,CAAC,gBAY7C;AAiBG,0GAUN;AAQD,+CAAoD;AAU7C,0EAUH;AAUG,0EAaH;AAEJ,oDAAoD;AACpD,uDAAqE;AAErE,2GAA2G;AAC3G,+GAIE;AAWK,sGAFI,MAAM,mCA4FhB;;;;sBAlbyB,OAAO,qBAAqB,EAAE,IAAI,CAAC,CAAC,CAAC;;;;;;iCAkJxC,GAAG,EAAE,KAAK,GAAG;;+BAUvB,CAAC,SAAS,YAAY,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,SAAS,oBAAoB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC"}

package/src/utils.js

@@ -1,19 +1,25 @@
 // @ts-check
-import { E } from '@endo/eventual-send';
+// @jessie-check
+
+import { E } from '@endo/far';
 import { deeplyFulfilled, isObject } from '@endo/marshal';
-import { isPromise } from '@endo/promise-kit';
+import { isPromise, makePromiseKit } from '@endo/promise-kit';
+import { makeQueue } from '@endo/stream';
+import { asyncGenerate, makeSet } from 'jessie.js';
+
+const { entries, fromEntries, keys, values } = Object;
+const { ownKeys } = Reflect;
 
-/** @typedef {import('@endo/marshal/src/types').Remotable} Remotable */
+const { details: X, quote: q, Fail } = assert;
 
-const { getPrototypeOf, create, entries, fromEntries } = Object;
-const { ownKeys, apply } = Reflect;
+export const BASIS_POINTS = 10_000n;
 
-const { details: X, quote: q } = assert;
+/** @template T @typedef {import('@endo/eventual-send').ERef<T>} ERef<T> */
 
 /**
  * Throws if multiple entries use the same property name. Otherwise acts
- * like `Object.fromEntries`. Use it to protect from property names
- * computed from user-provided data.
+ * like `Object.fromEntries` but hardens the result.
+ * Use it to protect from property names computed from user-provided data.
  *
  * @template K,V
  * @param {Iterable<[K,V]>} allEntries
@@ -21,18 +27,18 @@ const { details: X, quote: q } = assert;
  */
 export const fromUniqueEntries = allEntries => {
   const entriesArray = [...allEntries];
-  const result = fromEntries(entriesArray);
+  const result = harden(fromEntries(entriesArray));
   if (ownKeys(result).length === entriesArray.length) {
     return result;
   }
-  const names = new Set();
+  const names = makeSet();
   for (const [name, _] of entriesArray) {
     if (names.has(name)) {
-      assert.fail(X`collision on property name ${q(name)}: ${entriesArray}`);
+      Fail`collision on property name ${q(name)}: ${entriesArray}`;
     }
     names.add(name);
   }
-  assert.fail(X`internal: failed to create object from unique entries`);
+  throw Fail`internal: failed to create object from unique entries`;
 };
 harden(fromUniqueEntries);
 
@@ -82,8 +88,12 @@ export const objectMap = (original, mapFn) => {
 };
 harden(objectMap);
 
+/**
+ * @param {Array<string | symbol>} leftNames
+ * @param {Array<string | symbol>} rightNames
+ */
 export const listDifference = (leftNames, rightNames) => {
-  const rightSet = new Set(rightNames);
+  const rightSet = makeSet(rightNames);
   return leftNames.filter(name => !rightSet.has(name));
 };
 harden(listDifference);
@@ -91,7 +101,7 @@ harden(listDifference);
 /**
  * @param {Error} innerErr
  * @param {string|number} label
- * @param {ErrorConstructor=} ErrorConstructor
+ * @param {ErrorConstructor} [ErrorConstructor]
  * @returns {never}
  */
 export const throwLabeled = (innerErr, label, ErrorConstructor = undefined) => {
@@ -125,110 +135,54 @@ export const applyLabelingError = (func, args, label = undefined) => {
     throwLabeled(err, label);
   }
   if (isPromise(result)) {
-    // @ts-expect-error If result is a rejected promise, this will
-    // return a promise with a different rejection reason. But this
-    // confuses TypeScript because it types that case as `Promise<never>`
-    // which is cool for a promise that will never fulfll.
-    // But TypeScript doesn't understand that this will only happen
-    // when `result` was a rejected promise. In only this case `R`
-    // should already allow `Promise<never>` as a subtype.
-    return E.when(result, undefined, reason => throwLabeled(reason, label));
+    // If result is a rejected promise, this will return a promise with a
+    // different rejection reason. But this confuses TypeScript because it types
+    // that case as `Promise<never>` which is cool for a promise that will never
+    // fulfill.  But TypeScript doesn't understand that this will only happen
+    // when `result` was a rejected promise. In only this case `R` should
+    // already allow `Promise<never>` as a subtype.
+    /** @type {unknown} */
+    const relabeled = E.when(result, undefined, reason =>
+      throwLabeled(reason, label),
+    );
+    return /** @type {R} */ (relabeled);
   } else {
     return result;
   }
 };
 harden(applyLabelingError);
 
-const compareStringified = (left, right) => {
-  left = String(left);
-  right = String(right);
-  // eslint-disable-next-line no-nested-ternary
-  return left < right ? -1 : left > right ? 1 : 0;
-};
-
 /**
- * @param {object} obj
- * @returns {(string|symbol)[]}
+ * @template T
+ * @typedef {{[KeyType in keyof T]: T[KeyType]} & {}} Simplify
+ * flatten the type output to improve type hints shown in editors
+ * https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
  */
-export const getMethodNames = obj => {
-  const result = [];
-  while (obj !== null && obj !== Object.prototype) {
-    const mNames = ownKeys(obj).filter(name => typeof obj[name] === 'function');
-    result.push(...mNames);
-    obj = getPrototypeOf(obj);
-  }
-  result.sort(compareStringified);
-  return harden(result);
-};
-harden(getMethodNames);
 
 /**
- * TODO This function exists only to ease the
- * https://github.com/Agoric/agoric-sdk/pull/5970 transition, from all methods
- * being own properties to methods being inherited from a common prototype.
- * This transition breaks two patterns used in prior code: autobinding,
- * and enumerating methods by enumerating own properties. For both, the
- * preferred repairs are
- *    * autobinding: Replace, for example,
- *      `foo(obj.method)` with `foo(arg => `obj.method(arg))`. IOW, stop relying
- *      on expressions like `obj.method` to extract a method still bound to the
- *      state of `obj` because, for virtual and durable objects,
- *      they no longer will after #5970.
- *    * method enumeration: Replace, for example
- *      `Reflect.ownKeys(obj)` with `getMethodNames(obj)`.
- *
- * Once all problematic cases have been converted in this manner, this
- * `bindAllMethods` hack can and TODO should be deleted. However, we currently
- * have no reliable static way to track down and fix all autobinding sites.
- * For those objects that have not yet been fully repaired by the above two
- * techniques, `bindAllMethods` creates an object that acts much like the
- * pre-#5970 objects, with all their methods as instance-bound own properties.
- * It does this by making a new object inheriting from `obj` where the new
- * object has bound own methods overridding all the methods it would have
- * inherited from `obj`.
- *
- * @param {Remotable} obj
- * @returns {Remotable}
+ * @typedef {(...args: any[]) => any} Callable
  */
-export const bindAllMethods = obj =>
-  harden(
-    create(
-      obj,
-      fromEntries(
-        getMethodNames(obj).map(name => [
-          name,
-          {
-            value: (...args) => apply(obj[name], obj, args),
-            enumerable: true,
-          },
-        ]),
-      ),
-    ),
-  );
-harden(bindAllMethods);
 
 /**
  * @template {{}} T
- * @typedef {{ [K in keyof T]: DeeplyAwaited<T[K]> }} DeeplyAwaitedObject
+ * @typedef {{ [K in keyof T]: T[K] extends Callable ? T[K] : DeeplyAwaited<T[K]> }} DeeplyAwaitedObject
  */
 
 /**
- * Caveats:
- * - doesn't recur within Promise results
- * - resulting type has wrapper in its name
- *
  * @template T
- * @typedef {T extends PromiseLike ? Awaited<T> : T extends {} ? DeeplyAwaitedObject<T> : Awaited<T>} DeeplyAwaited
+ * @typedef {T extends PromiseLike<any> ? Awaited<T> : T extends {} ? Simplify<DeeplyAwaitedObject<T>> : Awaited<T>} DeeplyAwaited
  */
 
 /**
- * A more constrained version of {deeplyFulfilled} for type safety until https://github.com/endojs/endo/issues/1257
- * Useful in starting contracts that need all terms to be fulfilled in order to be durable.
+ * A more constrained version of {deeplyFulfilled} for type safety until
+ * https://github.com/endojs/endo/issues/1257
+ * Useful in starting contracts that need all terms to be fulfilled
+ * in order to be durable.
  *
- * @type {<T extends {}>(unfulfilledTerms: T) => import('@endo/eventual-send').ERef<DeeplyAwaited<T>>}
+ * @type {<T extends {}>(unfulfilledTerms: T) => Promise<DeeplyAwaited<T>>}
  */
-export const deeplyFulfilledObject = obj => {
-  assert(isObject(obj), 'param must be an object');
+export const deeplyFulfilledObject = async obj => {
+  isObject(obj) || Fail`param must be an object`;
   return deeplyFulfilled(obj);
 };
 
@@ -241,6 +195,7 @@ export const deeplyFulfilledObject = obj => {
  * @returns {<T>(fn: () => Promise<T>) => Promise<{ result: T, duration: number }>}
  */
 export const makeMeasureSeconds = currentTimeMillisec => {
+  /** @param {() => any} fn */
   const measureSeconds = async fn => {
     const t0 = currentTimeMillisec();
     const result = await fn();
@@ -255,7 +210,7 @@ export const makeMeasureSeconds = currentTimeMillisec => {
  * @param {string} [message]
  */
 export const makeAggregateError = (errors, message) => {
-  const err = new Error(message);
+  const err = Error(message);
   Object.defineProperties(err, {
     name: {
       value: 'AggregateError',
@@ -269,11 +224,11 @@ export const makeAggregateError = (errors, message) => {
 
 /**
  * @template T
- * @param {readonly (T | PromiseLike<T>)[]} values
+ * @param {readonly (T | PromiseLike<T>)[]} items
  * @returns {Promise<T[]>}
  */
-export const PromiseAllOrErrors = async values => {
-  return Promise.allSettled(values).then(results => {
+export const PromiseAllOrErrors = async items => {
+  return Promise.allSettled(items).then(results => {
     const errors = /** @type {PromiseRejectedResult[]} */ (
       results.filter(({ status }) => status === 'rejected')
     ).map(result => result.reason);
@@ -307,37 +262,190 @@ export const PromiseAllOrErrors = async values => {
   );
 
 /**
- * @param {import("fs").ReadStream | import("fs").WriteStream} stream
- * @returns {Promise<void>}
+ * @template {Record<string, unknown>} T
+ * @typedef {{[P in keyof T]: Exclude<T[P], undefined>;}} AllDefined
+ */
+
+/**
+ * Concise way to check values are available from object literal shorthand.
+ * Throws error message to specify the missing values.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} obj
+ * @throws if any value in the object entries is not defined
+ * @returns {asserts obj is AllDefined<T>}
  */
-export const fsStreamReady = stream =>
-  new Promise((resolve, reject) => {
-    if (stream.destroyed) {
-      reject(new Error('Stream already destroyed'));
-      return;
+
+export const assertAllDefined = obj => {
+  const missing = [];
+  for (const [key, val] of Object.entries(obj)) {
+    if (val === undefined) {
+      missing.push(key);
     }
+  }
+  if (missing.length > 0) {
+    Fail`missing ${q(missing)}`;
+  }
+};
+
+/** @type {IteratorResult<undefined, never>} */
+const notDone = harden({ done: false, value: undefined });
+
+/** @type {IteratorResult<never, void>} */
+const alwaysDone = harden({ done: true, value: undefined });
+
+export const forever = asyncGenerate(() => notDone);
 
-    if (!stream.pending) {
-      resolve();
-      return;
+/**
+ * @template T
+ * @param {() => T} produce
+ * The value of `await produce()` is used for its truthiness vs falsiness.
+ * IOW, it is coerced to a boolean so the caller need not bother doing this
+ * themselves.
+ * @returns {AsyncIterable<Awaited<T>>}
+ */
+export const whileTrue = produce =>
+  asyncGenerate(async () => {
+    const value = await produce();
+    if (!value) {
+      return alwaysDone;
     }
+    return harden({
+      done: false,
+      value,
+    });
+  });
 
-    const onReady = () => {
-      cleanup(); // eslint-disable-line no-use-before-define
-      resolve();
-    };
+/**
+ * @template T
+ * @param {() => T} produce
+ * The value of `await produce()` is used for its truthiness vs falsiness.
+ * IOW, it is coerced to a boolean so the caller need not bother doing this
+ * themselves.
+ * @returns {AsyncIterable<Awaited<T>>}
+ */
+export const untilTrue = produce =>
+  asyncGenerate(async () => {
+    const value = await produce();
+    if (value) {
+      return harden({
+        done: true,
+        value,
+      });
+    }
+    return harden({
+      done: false,
+      value,
+    });
+  });
 
-    /** @param {Error} err */
-    const onError = err => {
-      cleanup(); // eslint-disable-line no-use-before-define
-      reject(err);
-    };
+/** @type { <X, Y>(xs: X[], ys: Y[]) => [X, Y][]} */
+export const zip = (xs, ys) => harden(xs.map((x, i) => [x, ys[+i]]));
 
-    const cleanup = () => {
-      stream.off('ready', onReady);
-      stream.off('error', onError);
-    };
+/** @type { <T extends Record<string, ERef<any>>>(obj: T) => Promise<{ [K in keyof T]: Awaited<T[K]>}> } */
+export const allValues = async obj => {
+  const resolved = await Promise.all(values(obj));
+  // @ts-expect-error cast
+  return harden(fromEntries(zip(keys(obj), resolved)));
+};
 
-    stream.on('ready', onReady);
-    stream.on('error', onError);
+/**
+ * A tee implementation where all readers are synchronized with each other.
+ * They all consume the source stream in lockstep, and any one returning or
+ * throwing early will affect the others.
+ *
+ * @template [T=unknown]
+ * @param {AsyncIterator<T, void, void>} sourceStream
+ * @param {number} readerCount
+ */
+export const synchronizedTee = (sourceStream, readerCount) => {
+  /** @type {IteratorReturnResult<void> | undefined} */
+  let doneResult;
+
+  /** @typedef {IteratorResult<(value: PromiseLike<IteratorResult<T>>) => void>} QueuePayload */
+  /** @type {import('@endo/stream').AsyncQueue<QueuePayload>[]} */
+  const queues = [];
+
+  /** @returns {Promise<void>} */
+  const pullNext = async () => {
+    const requests = await Promise.allSettled(queues.map(queue => queue.get()));
+    const rejections = [];
+    /** @type {Array<(value: PromiseLike<IteratorResult<T>>) => void>} */
+    const resolvers = [];
+    let done = false;
+    for (const settledResult of requests) {
+      if (settledResult.status === 'rejected') {
+        rejections.push(settledResult.reason);
+      } else {
+        done ||= !!settledResult.value.done;
+        resolvers.push(settledResult.value.value);
+      }
+    }
+    /** @type {Promise<IteratorResult<T>>} */
+    let result;
+    if (doneResult) {
+      result = Promise.resolve(doneResult);
+    } else if (rejections.length) {
+      const error = assert.error(assert.details`Teed stream threw`);
+      assert.note(error, assert.details`Teed rejections: ${rejections}`);
+      result =
+        sourceStream.throw?.(error) ||
+        Promise.resolve(sourceStream.return?.()).then(() =>
+          Promise.reject(error),
+        );
+    } else if (done) {
+      result =
+        sourceStream.return?.() ||
+        Promise.resolve({ done: true, value: undefined });
+    } else {
+      result = sourceStream.next();
+    }
+    result.then(
+      r => {
+        if (r.done) {
+          doneResult = r;
+        }
+      },
+      () => {
+        doneResult = { done: true, value: undefined };
+      },
+    );
+    resolvers.forEach(resolve => resolve(result));
+    return pullNext();
+  };
+
+  const readers = Array.from({ length: readerCount }).map(() => {
+    /** @type {import('@endo/stream').AsyncQueue<QueuePayload>} */
+    const queue = makeQueue();
+    queues.push(queue);
+
+    /** @type {AsyncGenerator<T, void, void>} */
+    const reader = harden({
+      async next() {
+        /** @type {import('@endo/promise-kit').PromiseKit<IteratorResult<T>>} */
+        const { promise, resolve } = makePromiseKit();
+        queue.put({ value: resolve, done: false });
+        return promise;
+      },
+      async return() {
+        /** @type {import('@endo/promise-kit').PromiseKit<IteratorResult<T>>} */
+        const { promise, resolve } = makePromiseKit();
+        queue.put({ value: resolve, done: true });
+        return promise;
+      },
+      async throw(reason) {
+        const rejection = Promise.reject(reason);
+        queue.put(rejection);
+        return rejection;
+      },
+      // eslint-disable-next-line no-restricted-globals
+      [Symbol.asyncIterator]() {
+        return reader;
+      },
+    });
+    return reader;
   });
+
+  void pullNext();
+  return readers;
+};