Merge branch 'master' into module-namespace-object

packages/common/README.md

@@ -8,7 +8,9 @@ Each of the utilities in this packages
 - sufficiently general that it would be awkward to import from a more specialized package.
 - can be explained and motivated without much external knowledge.
 
-Each utility is in its own source file, named after the main export of that utility. (This is often that file's only export.) This enables importers to bypass this package's `index.js` and just do a deep import of what they need.
+Each utility is in its own top-level source file, named after the main export of that utility. (This is often that file's only export.) The `package.json` also lists each as a distinct `"export":`. There is no `index.js` file that rolls them together. Thus, each importer must do a deep import of exactly the export it needs. Some implementations (bundlers, packagers) can thus do tree-shaking, omitted code that isn't reachable by imports.
+
+Currently there are no `src/something.js` files. The only source files that would go in `src/` are those that do not represent separately exported utilities.
 
 Generally each utility also has its own test file. (An exception is that `make-iterator.js` is indirectly but adequately tested by `test-make-array-iterator.js`).
 

packages/common/src/ident-checker.js → packages/common/ident-checker.js

@@ -1,6 +1,6 @@
 // TODO Complete migration of Checker type from @endo/pass-style to @endo/common
 // by having @endo/pass-style, and everyone else who needs it, import it from
-// @endo/common.
+// `@endo/common/ident-checker.js`.
 /**
  * @callback Checker
  * Internal to a useful pattern for writing checking logic

packages/common/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@endo/common",
   "version": "1.0.1",
-  "private": true,
   "description": "common low level utilities",
   "keywords": [],
   "author": "Endo contributors",
@@ -15,20 +14,17 @@
     "url": "https://github.com/endojs/endo/issues"
   },
   "type": "module",
-  "main": "./index.js",
-  "module": "./index.js",
   "exports": {
-    ".": "./index.js",
-    "./apply-labeling-error": "./src/apply-labeling-error.js",
-    "./from-unique-entries": "./src/from-unique-entries.js",
-    "./ident-checker": "./src/ident-checker.js",
-    "./list-difference": "./src/list-difference.js",
-    "./make-array-iterator": "./src/make-array-iterator.js",
-    "./make-iterator": "./src/make-iterator.js",
-    "./object-map": "./src/object-map.js",
-    "./object-meta-assign": "./src/object-meta-assign.js",
-    "./object-meta-map": "./src/object-meta-map.js",
-    "./throw-labeled": "./src/throw-labeled.js",
+    "./apply-labeling-error.js": "./apply-labeling-error.js",
+    "./from-unique-entries.js": "./from-unique-entries.js",
+    "./ident-checker.js": "./ident-checker.js",
+    "./list-difference.js": "./list-difference.js",
+    "./make-array-iterator.js": "./make-array-iterator.js",
+    "./make-iterator.js": "./make-iterator.js",
+    "./object-map.js": "./object-map.js",
+    "./object-meta-assign.js": "./object-meta-assign.js",
+    "./object-meta-map.js": "./object-meta-map.js",
+    "./throw-labeled.js": "./throw-labeled.js",
     "./package.json": "./package.json"
   },
   "scripts": {

packages/common/test/test-apply-labeling-error.js

@@ -1,5 +1,5 @@
 import { test } from './prepare-test-env-ava.js';
-import { applyLabelingError } from '../src/apply-labeling-error.js';
+import { applyLabelingError } from '../apply-labeling-error.js';
 
 const { Fail } = assert;
 

packages/common/test/test-from-unique-entries.js

@@ -1,5 +1,5 @@
 import { test } from './prepare-test-env-ava.js';
-import { fromUniqueEntries } from '../src/from-unique-entries.js';
+import { fromUniqueEntries } from '../from-unique-entries.js';
 
 test('test fromUniqueEntries', async t => {
   t.deepEqual(

packages/common/test/test-ident-checker.js

@@ -1,5 +1,5 @@
 import { test } from './prepare-test-env-ava.js';
-import { identChecker } from '../src/ident-checker.js';
+import { identChecker } from '../ident-checker.js';
 
 test('test identChecker', async t => {
   t.is(identChecker(true, 'x'), true);

packages/common/test/test-list-difference.js

@@ -1,5 +1,5 @@
 import { test } from './prepare-test-env-ava.js';
-import { listDifference } from '../src/list-difference.js';
+import { listDifference } from '../list-difference.js';
 
 test('test listDifference', async t => {
   t.deepEqual(listDifference(['a', 'b', 'c'], ['b', 'c', 'd']), ['a']);

packages/common/test/test-make-array-iterator.js

@@ -1,5 +1,5 @@
 import { test } from './prepare-test-env-ava.js';
-import { makeArrayIterator } from '../src/make-array-iterator.js';
+import { makeArrayIterator } from '../make-array-iterator.js';
 
 // Also serves as an adequate test of make-iterator.js
 

packages/common/test/test-object-map.js

@@ -1,5 +1,5 @@
 import { test } from './prepare-test-env-ava.js';
-import { objectMap } from '../src/object-map.js';
+import { objectMap } from '../object-map.js';
 
 test('test objectMap', async t => {
   t.deepEqual(

packages/common/test/test-object-meta-assign.js

@@ -1,5 +1,5 @@
 import { test } from './prepare-test-env-ava.js';
-import { objectMetaAssign } from '../src/object-meta-assign.js';
+import { objectMetaAssign } from '../object-meta-assign.js';
 
 test('test objectMetaAssign', async t => {
   t.deepEqual(objectMetaAssign({}, { a: 1 }, { a: 2, b: 3 }), { a: 2, b: 3 });

packages/common/test/test-object-meta-map.js

@@ -1,5 +1,5 @@
 import { test } from './prepare-test-env-ava.js';
-import { objectMetaMap } from '../src/object-meta-map.js';
+import { objectMetaMap } from '../object-meta-map.js';
 
 const { getOwnPropertyDescriptors, getPrototypeOf } = Object;
 

packages/common/test/test-throw-labeled.js

@@ -1,5 +1,5 @@
 import { test } from './prepare-test-env-ava.js';
-import { throwLabeled } from '../src/throw-labeled.js';
+import { throwLabeled } from '../throw-labeled.js';
 
 test('test throwLabeled', async t => {
   t.throws(() => throwLabeled(Error('e'), 'foo'), {

packages/exo/src/exo-makers.js

@@ -1,6 +1,6 @@
 /// <reference types="ses"/>
 import { environmentOptionsListHas } from '@endo/env-options';
-import { objectMap } from '@endo/common';
+import { objectMap } from '@endo/common/object-map.js';
 
 import { defendPrototype, defendPrototypeKit } from './exo-tools.js';
 
@@ -87,18 +87,6 @@ export const initEmpty = () => emptyRecord;
  * @typedef {(power: P) => void} ReceivePower
  */
 
-/**
- * The power to revoke a live instance of the associated exo class, or the
- * power to revoke a live facet instance of the associated exo class kit.
- * If called with such a live instance, it revokes it and returns true. Once
- * revoked, it is no longer live, and calling any of its methods throw
- * an informative diagnostic with no further effects.
- *
- * @callback Revoke
- * @param {any} exo
- * @returns {boolean}
- */
-
 /**
  * The power to amplify a live facet instance of the associated exo class kit
  * into the record of all facets of this facet instance's cohort.
@@ -136,15 +124,6 @@ export const initEmpty = () => emptyRecord;
  * enforce the `stateShape` invariant. The heap exos defined in this
  * package currently ignore `stateShape`, but will enforce this in the future.
  *
- * @property {ReceivePower<Revoke>} [receiveRevoker]
- * If a `receiveRevoker` function is provided, it will be called during
- * definition of the exo class or exo class kit with a `Revoke` function.
- * A `Revoke` function is a function of one argument. If you call the revoke
- * function with a live instance of this exo class, or a live facet instance
- * of this exo class kit, then it will "revoke" it and return true. Once
- * revoked, this instance is no longer "live": Any attempt to invoke any of
- * its methods will fail without further effect.
- *
  * @property {ReceivePower<Amplify<F>>} [receiveAmplifier]
  * If a `receiveAmplifier` function is provided, it will be called during
  * definition of the exo class kit with an `Amplify` function. If called
@@ -190,11 +169,7 @@ export const defineExoClass = (
   options = {},
 ) => {
   harden(methods);
-  const {
-    finish = undefined,
-    receiveRevoker = undefined,
-    receiveAmplifier = undefined,
-  } = options;
+  const { finish = undefined, receiveAmplifier = undefined } = options;
   receiveAmplifier === undefined ||
     Fail`Only facets of an exo class kit can be amplified ${q(tag)}`;
 
@@ -227,12 +202,6 @@ export const defineExoClass = (
     return self;
   };
 
-  if (receiveRevoker) {
-    const revoke = self => contextMap.delete(self);
-    harden(revoke);
-    receiveRevoker(revoke);
-  }
-
   return harden(makeInstance);
 };
 harden(defineExoClass);
@@ -260,11 +229,7 @@ export const defineExoClassKit = (
   options = {},
 ) => {
   harden(methodsKit);
-  const {
-    finish = undefined,
-    receiveRevoker = undefined,
-    receiveAmplifier = undefined,
-  } = options;
+  const { finish = undefined, receiveAmplifier = undefined } = options;
   const contextMapKit = objectMap(methodsKit, () => new WeakMap());
   const getContextKit = objectMap(
     contextMapKit,
@@ -302,13 +267,6 @@ export const defineExoClassKit = (
     return /** @type {GuardedKit<F>} */ (context.facets);
   };
 
-  if (receiveRevoker) {
-    const revoke = aFacet =>
-      values(contextMapKit).some(contextMap => contextMap.delete(aFacet));
-    harden(revoke);
-    receiveRevoker(revoke);
-  }
-
   if (receiveAmplifier) {
     const amplify = aFacet => {
       for (const contextMap of values(contextMapKit)) {
@@ -317,7 +275,7 @@ export const defineExoClassKit = (
           return facets;
         }
       }
-      throw Fail`Must be an unrevoked facet of ${q(tag)}: ${aFacet}`;
+      throw Fail`Must be a facet of ${q(tag)}: ${aFacet}`;
     };
     harden(amplify);
     receiveAmplifier(amplify);

packages/exo/src/exo-tools.js

@@ -11,7 +11,8 @@ import {
   getInterfaceGuardPayload,
   getCopyMapEntries,
 } from '@endo/patterns';
-import { listDifference, objectMap } from '@endo/common';
+import { listDifference } from '@endo/common/list-difference.js';
+import { objectMap } from '@endo/common/object-map.js';
 import { GET_INTERFACE_GUARD } from './get-interface.js';
 
 /** @typedef {import('@endo/patterns').Method} Method */
@@ -296,8 +297,17 @@ const defendMethod = (method, methodGuard, label) => {
  */
 
 /**
- * @typedef {(facet: any) => KitContext} KitContextProvider
- * @typedef {((representative: any) => ClassContext) | KitContextProvider} ContextProvider
+ * @typedef {(
+ *   representative: any
+ * ) => ClassContext | undefined} ClassContextProvider
+ */
+
+/**
+ * @typedef {(facet: any) => KitContext | undefined} KitContextProvider
+ */
+
+/**
+ * @typedef { ClassContextProvider | KitContextProvider } ContextProvider
  */
 
 /**

packages/exo/test/test-amplify-heap-class-kits.js

@@ -21,7 +21,7 @@ test('test amplify defineExoClass fails', t => {
       defineExoClass(
         'UpCounter',
         UpCounterI,
-        /** @param {number} x */
+        /** @param {number} [x] */
         (x = 0) => ({ x }),
         {
           incr(y = 1) {
@@ -41,12 +41,11 @@ test('test amplify defineExoClass fails', t => {
 });
 
 test('test amplify defineExoClassKit', t => {
-  let revoke;
   let amp;
   const makeCounterKit = defineExoClassKit(
     'Counter',
     { up: UpCounterI, down: DownCounterI },
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       up: {
@@ -65,9 +64,6 @@ test('test amplify defineExoClassKit', t => {
       },
     },
     {
-      receiveRevoker(r) {
-        revoke = r;
-      },
       receiveAmplifier(a) {
         amp = a;
       },
@@ -79,21 +75,8 @@ test('test amplify defineExoClassKit', t => {
   t.is(downCounter.decr(), 7);
 
   t.throws(() => amp(harden({})), {
-    message: 'Must be an unrevoked facet of "Counter": {}',
+    message: 'Must be a facet of "Counter": {}',
   });
   t.deepEqual(amp(upCounter), counterKit);
   t.deepEqual(amp(downCounter), counterKit);
-
-  t.is(revoke(upCounter), true);
-
-  t.throws(() => amp(upCounter), {
-    message: 'Must be an unrevoked facet of "Counter": "[Alleged: Counter up]"',
-  });
-  t.deepEqual(amp(downCounter), counterKit);
-  t.throws(() => upCounter.incr(3), {
-    message:
-      '"In \\"incr\\" method of (Counter up)" may only be applied to a valid instance: "[Alleged: Counter up]"',
-  });
-  t.deepEqual(amp(downCounter), counterKit);
-  t.is(downCounter.decr(), 6);
 });

packages/exo/test/test-heap-classes.js

@@ -58,7 +58,7 @@ test('test defineExoClass', t => {
   const makeUpCounter = defineExoClass(
     'UpCounter',
     UpCounterI,
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       incr(y = 1) {
@@ -105,7 +105,7 @@ test('test defineExoClassKit', t => {
   const makeCounterKit = defineExoClassKit(
     'Counter',
     { up: UpCounterI, down: DownCounterI },
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       up: {

packages/exo/test/test-label-instances.js

@@ -24,7 +24,7 @@ test('test defineExoClass', t => {
   const makeUpCounter = defineExoClass(
     'UpCounter',
     UpCounterI,
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       incr() {
@@ -49,7 +49,7 @@ test('test defineExoClassKit', t => {
   const makeCounterKit = defineExoClassKit(
     'Counter',
     { up: UpCounterI, down: DownCounterI },
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       up: {

packages/exo/test/test-non-enumerable-methods.js

@@ -81,7 +81,7 @@ test('test defineExoClass', t => {
   const makeUpCounter = defineExoClass(
     'UpCounter',
     UpCounterI,
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     denumerate({
       incr(y = 1) {