@endo/promise-kit 0.2.42 → 0.2.43

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+### [0.2.43](https://github.com/endojs/endo/compare/@endo/promise-kit@0.2.42...@endo/promise-kit@0.2.43) (2022-06-28)
+
+
+### Features
+
+* **promise-kit:** Add non-leaky promise race helper ([505815c](https://github.com/endojs/endo/commit/505815cdb02512d2de6ba0ac73c1130626eebf77))
+* **promise-kit:** detach promise from resolvers after use ([d6e9fba](https://github.com/endojs/endo/commit/d6e9fbae05d9d42bdf7fb79c83893141b0348010))
+* **promise-kit:** Make leak-free race a fully compliant drop-in replacement ([14fbba4](https://github.com/endojs/endo/commit/14fbba496a564add617d4c151726fbfc271e1f4c))
+
+
+
 ### [0.2.42](https://github.com/endojs/endo/compare/@endo/promise-kit@0.2.41...@endo/promise-kit@0.2.42) (2022-06-11)
 
 **Note:** Version bump only for package @endo/promise-kit

package/index.js

@@ -3,37 +3,15 @@
 
 /// <reference types="ses"/>
 
-/** @type {PromiseConstructor} */
-const BestPipelinablePromise = globalThis.HandledPromise || Promise;
+import { makeReleasingExecutorKit } from './src/promise-executor-kit.js';
+import { memoRace } from './src/memo-race.js';
 
-/**
- * @template T
- * @typedef {Object} PromiseKit A reified Promise
- * @property {(value: ERef<T>) => void} resolve
- * @property {(reason: any) => void} reject
- * @property {Promise<T>} promise
- */
+export * from './src/is-promise.js';
+// eslint-disable-next-line import/export
+export * from './src/types.js';
 
-/**
- * PromiseRecord is deprecated in favor of PromiseKit.
- *
- * @template T
- * @typedef {PromiseKit<T>} PromiseRecord
- */
-
-/**
- * @template T
- * @typedef {T | PromiseLike<T>} ERef
- * A reference of some kind for to an object of type T. It may be a direct
- * reference to a local T. It may be a local presence for a remote T. It may
- * be a promise for a local or remote T. Or it may even be a thenable
- * (a promise-like non-promise with a "then" method) for a T.
- */
-
-/**
- * Needed to prevent type errors where functions are detected to be undefined.
- */
-const NOOP_INITIALIZER = harden(() => {});
+/** @type {PromiseConstructor} */
+const BestPipelinablePromise = globalThis.HandledPromise || Promise;
 
 /**
  * makePromiseKit() builds a Promise object, and returns a record
@@ -41,31 +19,33 @@ const NOOP_INITIALIZER = harden(() => {});
  * and rejecting it.
  *
  * @template T
- * @returns {PromiseKit<T>}
+ * @returns {import('./src/types.js').PromiseKit<T>}
  */
 export function makePromiseKit() {
-  /** @type {(value: ERef<T>) => void} */
-  let resolve = NOOP_INITIALIZER;
-  /** @type {(reason: unknown) => void} */
-  let reject = NOOP_INITIALIZER;
+  const { resolve, reject, executor } = makeReleasingExecutorKit();
 
-  /** @type {Promise<T>} */
-  const promise = new BestPipelinablePromise((res, rej) => {
-    resolve = res;
-    reject = rej;
-  });
+  const promise = new BestPipelinablePromise(executor);
 
   return harden({ promise, resolve, reject });
 }
 harden(makePromiseKit);
 
+// NB: Another implementation for Promise.race would be to use the releasing executor,
+// However while it would no longer leak the raced promise objects themselves, it would
+// still leak reactions on the non-resolved promises contending for the race.
+
 /**
- * Determine if the argument is a Promise.
+ * Creates a Promise that is resolved or rejected when any of the provided Promises are resolved
+ * or rejected.
  *
- * @param {any} maybePromise The value to examine
- * @returns {maybePromise is Promise} Whether it is a promise
+ * Unlike `Promise.race` it cleans up after itself so a non-resolved value doesn't hold onto
+ * the result promise.
+ *
+ * @template T
+ * @param {Iterable<T>} values An iterable of Promises.
+ * @returns {Promise<Awaited<T>>} A new Promise.
  */
-export function isPromise(maybePromise) {
-  return Promise.resolve(maybePromise) === maybePromise;
+export function racePromises(values) {
+  return harden(memoRace.call(BestPipelinablePromise, values));
 }
-harden(isPromise);
+harden(racePromises);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endo/promise-kit",
-  "version": "0.2.42",
+  "version": "0.2.43",
   "description": "Helper for making promises",
   "keywords": [
     "promise"
@@ -20,6 +20,7 @@
   "module": "./index.js",
   "exports": {
     ".": "./index.js",
+    "./shim.js": "./shim.js",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -34,11 +35,11 @@
     "test:xs": "exit 0"
   },
   "dependencies": {
-    "ses": "^0.15.16"
+    "ses": "^0.15.17"
   },
   "devDependencies": {
-    "@endo/eslint-config": "^0.5.0",
-    "@endo/ses-ava": "^0.2.26",
+    "@endo/eslint-config": "^0.5.1",
+    "@endo/ses-ava": "^0.2.27",
     "ava": "^3.12.1",
     "babel-eslint": "^10.0.3",
     "c8": "^7.7.3",
@@ -79,5 +80,5 @@
   "engines": {
     "node": ">=11.0"
   },
-  "gitHead": "7be9306df5e5eae280134cbbaf0d3886b4e51536"
+  "gitHead": "a311acb02115271fbda6953734d0b4f52aa85892"
 }

package/shim.js

@@ -0,0 +1,4 @@
+import { memoRace } from './src/memo-race.js';
+
+// Unconditionally replace with a non-leaking version
+Promise.race = memoRace;

package/src/is-promise.js

@@ -0,0 +1,12 @@
+// @ts-check
+
+/**
+ * Determine if the argument is a Promise.
+ *
+ * @param {unknown} maybePromise The value to examine
+ * @returns {maybePromise is Promise} Whether it is a promise
+ */
+export function isPromise(maybePromise) {
+  return Promise.resolve(maybePromise) === maybePromise;
+}
+harden(isPromise);

package/src/memo-race.js

@@ -0,0 +1,154 @@
+// @ts-check
+/*
+Initial version authored by Brian Kim:
+https://github.com/nodejs/node/issues/17469#issuecomment-685216777
+
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>
+*/
+
+const isObject = value => Object(value) === value;
+
+/**
+ * @template [T=any]
+ * @typedef {object} Deferred
+ * @property {(value?: import("./types.js").ERef<T> ) => void} resolve
+ * @property {(err?: any ) => void} reject
+ */
+
+/**
+ * @typedef { never
+ *  | {settled: false, deferreds: Set<Deferred>}
+ *  | {settled: true, deferreds?: undefined}
+ * } PromiseMemoRecord
+ */
+
+// Keys are the values passed to race, values are a record of data containing a
+// set of deferreds and whether the value has settled.
+/** @type {WeakMap<object, PromiseMemoRecord>} */
+const knownPromises = new WeakMap();
+
+/**
+ * @param {PromiseMemoRecord | undefined} record
+ * @returns {Set<Deferred>}
+ */
+const markSettled = record => {
+  if (!record || record.settled) {
+    return new Set();
+  }
+
+  const { deferreds } = record;
+  Object.assign(record, {
+    deferreds: undefined,
+    settled: true,
+  });
+  Object.freeze(record);
+  return deferreds;
+};
+
+/**
+ *
+ * @param {any} value
+ * @returns {PromiseMemoRecord}
+ */
+const getMemoRecord = value => {
+  if (!isObject(value)) {
+    // If the contender is a primitive, attempting to use it as a key in the
+    // weakmap would throw an error. Luckily, it is safe to call
+    // `Promise.resolve(contender).then` on a primitive value multiple times
+    // because the promise fulfills immediately. So we fake a settled record.
+    return { settled: true };
+  }
+
+  let record = knownPromises.get(value);
+
+  if (!record) {
+    record = { deferreds: new Set(), settled: false };
+    knownPromises.set(value, record);
+    // This call to `then` happens once for the lifetime of the value.
+    Promise.resolve(value).then(
+      val => {
+        for (const { resolve } of markSettled(record)) {
+          resolve(val);
+        }
+      },
+      err => {
+        for (const { reject } of markSettled(record)) {
+          reject(err);
+        }
+      },
+    );
+  }
+  return record;
+};
+
+const { race } = {
+  /**
+   * Creates a Promise that is resolved or rejected when any of the provided Promises are resolved
+   * or rejected.
+   *
+   * Unlike `Promise.race` it cleans up after itself so a non-resolved value doesn't hold onto
+   * the result promise.
+   *
+   * @template T
+   * @template {PromiseConstructor} [P=PromiseConstructor]
+   * @this {P}
+   * @param {Iterable<T>} values An iterable of Promises.
+   * @returns {Promise<Awaited<T>>} A new Promise.
+   */
+  race(values) {
+    let deferred;
+    /** @type {T[]} */
+    const cachedValues = [];
+    const C = this;
+    const result = new C((resolve, reject) => {
+      deferred = { resolve, reject };
+      for (const value of values) {
+        cachedValues.push(value);
+        const { settled, deferreds } = getMemoRecord(value);
+        if (settled) {
+          // If the contender is settled (including primitives), it is safe
+          // to call `Promise.resolve(value).then` on it.
+          C.resolve(value).then(resolve, reject);
+        } else {
+          deferreds.add(deferred);
+        }
+      }
+    });
+
+    // The finally callback executes when any value settles, preventing any of
+    // the unresolved values from retaining a reference to the resolved value.
+    return result.finally(() => {
+      for (const value of cachedValues) {
+        const { deferreds } = getMemoRecord(value);
+        if (deferreds) {
+          deferreds.delete(deferred);
+        }
+      }
+    });
+  },
+};
+
+export { race as memoRace };

package/src/promise-executor-kit.js

@@ -0,0 +1,56 @@
+// @ts-check
+
+/// <reference types="ses"/>
+
+/**
+ * @template T
+ * @callback PromiseExecutor The promise executor
+ * @param {(value: import('./types.js').ERef<T>) => void} resolve
+ * @param {(reason: any) => void} reject
+ */
+
+/**
+ * makeReleasingExecutorKit() builds resolve/reject functions which drop references
+ * to the resolve/reject functions gathered from an executor to be used with a
+ * promise constructor.
+ *
+ * @template T
+ * @returns {Pick<import('./types.js').PromiseKit<T>, 'resolve' | 'reject'> & { executor: PromiseExecutor<T>}}
+ */
+export const makeReleasingExecutorKit = () => {
+  /** @type {null | undefined | ((value: import('./types.js').ERef<T>) => void)} */
+  let internalResolve;
+  /** @type {null | undefined | ((reason: unknown) => void)} */
+  let internalReject;
+
+  /** @param {import('./types.js').ERef<T>} value */
+  const resolve = value => {
+    if (internalResolve) {
+      internalResolve(value);
+      internalResolve = null;
+      internalReject = null;
+    } else {
+      assert(internalResolve === null);
+    }
+  };
+
+  /** @param {unknown} reason */
+  const reject = reason => {
+    if (internalReject) {
+      internalReject(reason);
+      internalResolve = null;
+      internalReject = null;
+    } else {
+      assert(internalReject === null);
+    }
+  };
+
+  const executor = (res, rej) => {
+    assert(internalResolve === undefined && internalReject === undefined);
+    internalResolve = res;
+    internalReject = rej;
+  };
+
+  return { resolve, reject, executor };
+};
+harden(makeReleasingExecutorKit);

package/src/types.js

@@ -0,0 +1,25 @@
+/**
+ * @template T
+ * @typedef {object} PromiseKit A reified Promise
+ * @property {(value: ERef<T>) => void} resolve
+ * @property {(reason: any) => void} reject
+ * @property {Promise<T>} promise
+ */
+
+/**
+ * PromiseRecord is deprecated in favor of PromiseKit.
+ *
+ * @template T
+ * @typedef {PromiseKit<T>} PromiseRecord
+ */
+
+/**
+ * @template T
+ * @typedef {T | PromiseLike<T>} ERef
+ * A reference of some kind for to an object of type T. It may be a direct
+ * reference to a local T. It may be a local presence for a remote T. It may
+ * be a promise for a local or remote T. Or it may even be a thenable
+ * (a promise-like non-promise with a "then" method) for a T.
+ */
+
+export {};