@agoric/base-zone 0.1.1-dev-1f93cea.0 → 0.1.1-dev-cd45c09.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/base-zone",
-  "version": "0.1.1-dev-1f93cea.0+1f93cea",
+  "version": "0.1.1-dev-cd45c09.0+cd45c09",
   "description": "Allocation zone abstraction library and heap implementation",
   "type": "module",
   "repository": "https://github.com/Agoric/agoric-sdk",
@@ -27,7 +27,7 @@
   "author": "Agoric",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agoric/store": "0.9.3-dev-1f93cea.0+1f93cea",
+    "@agoric/store": "0.9.3-dev-cd45c09.0+cd45c09",
     "@endo/common": "^1.2.10",
     "@endo/errors": "^1.2.10",
     "@endo/exo": "^1.5.9",
@@ -59,5 +59,5 @@
   "typeCoverage": {
     "atLeast": 91.4
   },
-  "gitHead": "1f93cea5771408c025ede9abbba6138bf913db29"
+  "gitHead": "cd45c09e3b855745d1e641534f7d547bfa95ad74"
 }

package/src/prepare-attenuator.d.ts

@@ -1,7 +1,11 @@
-export function prepareAttenuatorMaker<U = any>(zone: import("@agoric/base-zone").Zone, uKindName: string, uMethodNames: (string | symbol)[], options?: AttenuatorOptions<U>): MakeAttenuator;
-export type MakeAttenuator<U = any> = (underlying: U) => U;
+export function wrapperMethods(wrapperKindName: string, uMethodNames: PropertyKey[], extraMethods?: Record<PropertyKey, (...args: any[]) => any>): {
+    [x: string]: ((...args: any[]) => any) | ((...args: any[]) => any);
+};
+export function prepareAttenuatorMaker<U = any>(zone: import("@agoric/base-zone").Zone, uKindName: string, uMethodNames: (keyof U)[], options?: AttenuatorOptions<U>): MakeAttenuator;
+export function attenuateOne<U extends unknown>(underlying: U, uMethodNames: (keyof U)[], options?: AttenuatorOptions<U>): Partial<U>;
+export type MakeAttenuator<U = any> = (underlying: U) => Partial<U>;
 export type AttenuatorThis<U = any> = {
-    self: U;
+    self: Partial<U>;
     state: {
         underlying: U;
     };
@@ -17,11 +21,11 @@ export type AttenuatorOptions<U = any> = {
      * only on the synthesized interface guard for the attenuator, and
      * do not necessarily correspond to any method of the underlying.
      */
-    extraMethodGuards?: Record<string | symbol, import("@endo/patterns").MethodGuard> | undefined;
+    extraMethodGuards?: Record<PropertyKey, import("@endo/patterns").MethodGuard> | undefined;
     /**
      * Extra methods adding behavior only to the attenuator, and
      * do not necessarily correspond to any methods of the underlying.
      */
-    extraMethods?: Record<string | symbol, (this: AttenuatorThis<U>, ...args: any[]) => any> | undefined;
+    extraMethods?: Record<PropertyKey, (this: AttenuatorThis<U>, ...args: any[]) => any> | undefined;
 };
 //# sourceMappingURL=prepare-attenuator.d.ts.map

package/src/prepare-attenuator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare-attenuator.d.ts","sourceRoot":"","sources":["prepare-attenuator.js"],"names":[],"mappings":"AAsEO,uCAVO,CAAC,cACJ,OAAO,mBAAmB,EAAE,IAAI,aAChC,MAAM,gBAEN,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,YAGjB,iBAAiB,CAAC,CAAC,CAAC,GAClB,cAAc,CA6D1B;2BA3Ga,CAAC,uBAEJ,CAAC,KACC,CAAC;2BAIA,CAAC;UAED,CAAC;WACD;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE;;8BAIjB,CAAC;;;;;;;;;;;;;;;;kDAcH,cAAc,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,GAAG"}
+{"version":3,"file":"prepare-attenuator.d.ts","sourceRoot":"","sources":["prepare-attenuator.js"],"names":[],"mappings":"AA2BO,gDAJI,MAAM,gBACN,WAAW,EAAE,iBACb,MAAM,CAAC,WAAW,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;4BAAd,GAAG,EAAE,KAAK,GAAG;EA6BlD;AAoDG,uCAVO,CAAC,cACJ,OAAO,mBAAmB,EAAE,IAAI,aAChC,MAAM,gBAEN,CAAC,MAAM,CAAC,CAAC,EAAE,YAGX,iBAAiB,CAAC,CAAC,CAAC,GAClB,cAAc,CA8B1B;AAoBM,6BANY,CAAC,8BACT,CAAC,gBACD,CAAC,MAAM,CAAC,CAAC,EAAE,YACX,iBAAiB,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,CAgBtB;2BA9Ga,CAAC,uBAEJ,CAAC,KACC,OAAO,CAAC,CAAC,CAAC;2BAIT,CAAC;UAED,OAAO,CAAC,CAAC,CAAC;WACV;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE;;8BAIjB,CAAC;;;;;;;;;;;;;;;;8CAcH,cAAc,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,GAAG"}

package/src/prepare-attenuator.js

@@ -1,6 +1,7 @@
 import { Fail, q } from '@endo/errors';
 import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
 import { M } from '@endo/patterns';
+import { makeHeapZone } from './heap.js';
 
 // This attenuator implementation is just a simplification of the
 // revocable kit implementation in prepare-revocable.js. The revocable kit
@@ -19,17 +20,52 @@ import { M } from '@endo/patterns';
 // But it can still support `selfRevoke` as a separate `extraMethod`, as shown
 // in a testcase at `prepare-attenuator.test.js`
 
+/**
+ * @param {string} wrapperKindName
+ * @param {PropertyKey[]} uMethodNames
+ * @param {Record<PropertyKey, (...args: any[]) => any>} [extraMethods]
+ */
+export const wrapperMethods = (
+  wrapperKindName,
+  uMethodNames,
+  extraMethods = {},
+) =>
+  harden({
+    ...fromUniqueEntries(
+      uMethodNames.map(name => [
+        name,
+        {
+          // Use concise method syntax for exo methods
+          [name](...args) {
+            // @ts-expect-error normal exo-this typing confusion
+            const { underlying } = this.state;
+
+            // Because attenuators still support someone adding `selfRevoke`
+            // as an `extraMethod`, this test is still useful. See the
+            // testcase in `prepare-attenuator.test.js`.
+            underlying !== undefined || Fail`${q(wrapperKindName)} revoked`;
+
+            return underlying[name](...args);
+          },
+          // @ts-expect-error using possible symbol as index type
+        }[name],
+      ]),
+    ),
+    ...extraMethods,
+  });
+harden(wrapperMethods);
+
 /**
  * @template [U=any]
  * @callback MakeAttenuator
  * @param {U} underlying
- * @returns {U}
+ * @returns {Partial<U>}
  */
 
 /**
  * @template [U=any]
  * @typedef {object} AttenuatorThis
- * @property {U} self
+ * @property {Partial<U>} self
  * @property {{ underlying: U }} state
  */
 
@@ -40,14 +76,14 @@ import { M } from '@endo/patterns';
  *   The `interfaceName` of the underlying interface guard.
  *   Defaults to the `uKindName`.
  * @property {Record<
- *   string|symbol,
+ *   PropertyKey,
  *   import('@endo/patterns').MethodGuard
  * >} [extraMethodGuards]
  * For guarding the `extraMethods`, if you include them below. These appear
  * only on the synthesized interface guard for the attenuator, and
  * do not necessarily correspond to any method of the underlying.
  * @property {Record<
- *   string|symbol,
+ *   PropertyKey,
  *   (this: AttenuatorThis<U>, ...args: any[]) => any
  * >} [extraMethods]
  * Extra methods adding behavior only to the attenuator, and
@@ -62,7 +98,7 @@ import { M } from '@endo/patterns';
  * @param {import('@agoric/base-zone').Zone} zone
  * @param {string} uKindName
  *   The `kindName` of the underlying exo class
- * @param {(string|symbol)[]} uMethodNames
+ * @param {(keyof U)[]} uMethodNames
  *   The method names of the underlying exo class that should be represented
  *   by transparently-forwarding methods of the attenuator.
  * @param {AttenuatorOptions<U>} [options]
@@ -76,17 +112,13 @@ export const prepareAttenuatorMaker = (
 ) => {
   const {
     uInterfaceName = uKindName,
-    extraMethodGuards = undefined,
-    extraMethods = undefined,
+    extraMethodGuards = {},
+    extraMethods = {},
   } = options;
   const AttenuatorI = M.interface(
     `${uInterfaceName}_attenuator`,
-    {
-      ...extraMethodGuards,
-    },
-    {
-      defaultGuards: 'raw',
-    },
+    extraMethodGuards,
+    { defaultGuards: 'raw' },
   );
 
   const attenuatorKindName = `${uKindName}_attenuator`;
@@ -94,38 +126,45 @@ export const prepareAttenuatorMaker = (
   return zone.exoClass(
     attenuatorKindName,
     AttenuatorI,
-    underlying => ({
-      underlying,
-    }),
+    underlying => ({ underlying }),
+    wrapperMethods(attenuatorKindName, uMethodNames, extraMethods),
     {
-      ...fromUniqueEntries(
-        uMethodNames.map(name => [
-          name,
-          {
-            // Use concise method syntax for exo methods
-            [name](...args) {
-              // @ts-expect-error normal exo-this typing confusion
-              const { underlying } = this.state;
-
-              // Because attenuators still support someone adding `selfRevoke`
-              // as an `extraMethod`, this test is still useful. See the
-              // testcase in `prepare-attenuator.test.js`.
-              underlying !== undefined ||
-                Fail`${q(attenuatorKindName)} revoked`;
-
-              return underlying[name](...args);
-            },
-            // @ts-expect-error using possible symbol as index type
-          }[name],
-        ]),
-      ),
-      ...extraMethods,
-    },
-    {
-      stateShape: {
-        underlying: M.opt(M.remotable('underlying')),
-      },
+      stateShape: { underlying: M.opt(M.remotable('underlying')) },
     },
   );
 };
 harden(prepareAttenuatorMaker);
+
+const PrefixedKindNameRE = /(alleged: |DebugName: )(.*)/;
+
+/**
+ * A convenience above `prepareAttenuatorMaker` for doing a singleton
+ * ephemeral attenuator, i.e., a new attenuator instance (and hidden class)
+ * that is allocated in the heap zone, and therefore ephemeral. The underlying
+ * can be durable or not, with no conflict with the attenuator being
+ * ephemeral. The price of this convenience is the allocation of the hidden
+ * class and wrapper methods per `attenuateOne` call, i.e., per attenuator
+ * instance.
+ *
+ * @template {any} U
+ * @param {U} underlying
+ * @param {(keyof U)[]} uMethodNames
+ * @param {AttenuatorOptions<U>} [options]
+ * @returns {Partial<U>}
+ */
+export const attenuateOne = (underlying, uMethodNames, options = undefined) => {
+  const heapZone = makeHeapZone();
+  let uKindName = underlying[Symbol.toStringTag] || 'Underlying';
+  const match = PrefixedKindNameRE.exec(uKindName);
+  if (match) {
+    uKindName = match[2];
+  }
+  const makeAttenuator = prepareAttenuatorMaker(
+    heapZone,
+    uKindName,
+    uMethodNames,
+    options,
+  );
+  return makeAttenuator(underlying);
+};
+harden(attenuateOne);

package/src/prepare-revocable.d.ts

@@ -1,10 +1,11 @@
-export function prepareRevocableMakerKit<U = any>(zone: import("@agoric/base-zone").Zone, uKindName: string, uMethodNames: (string | symbol)[], options?: RevocableKitOptions<U>): RevocableMakerKit<U>;
+export function prepareRevocableMakerKit<U = any>(zone: import("@agoric/base-zone").Zone, uKindName: string, uMethodNames: PropertyKey[], options?: RevocableKitOptions<U>): RevocableMakerKit<U>;
+export type MakeRevocable<U = any> = (underlying: U) => Partial<U>;
 export type RevocableMakerKit<U = any> = {
     revoke: (revocable: U) => boolean;
     /**
      *   Forwards to the underlying exo object, until revoked
      */
-    makeRevocable: (underlying: U) => U;
+    makeRevocable: MakeRevocable;
 };
 export type RevokerFacet = {
     revoke: () => boolean;
@@ -14,7 +15,7 @@ export type RevocableKit<U = any> = {
     /**
      *   Forwards to the underlying exo object, until revoked
      */
-    revocable: U;
+    revocable: Partial<U>;
 };
 export type RevocableKitThis<U = any> = {
     facets: RevocableKit<U>;
@@ -33,11 +34,11 @@ export type RevocableKitOptions<U = any> = {
      * only on the synthesized interface guard for the revocable caretaker, and
      * do not necessarily correspond to any method of the underlying.
      */
-    extraMethodGuards?: Record<string | symbol, import("@endo/patterns").MethodGuard> | undefined;
+    extraMethodGuards?: Record<PropertyKey, import("@endo/patterns").MethodGuard> | undefined;
     /**
      * Extra methods adding behavior only to the revocable caretaker, and
      * do not necessarily correspond to any methods of the underlying.
      */
-    extraMethods?: Record<string | symbol, (this: RevocableKitThis<U>, ...args: any[]) => any> | undefined;
+    extraMethods?: Record<PropertyKey, (this: RevocableKitThis<U>, ...args: any[]) => any> | undefined;
 };
 //# sourceMappingURL=prepare-revocable.d.ts.map

package/src/prepare-revocable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare-revocable.d.ts","sourceRoot":"","sources":["prepare-revocable.js"],"names":[],"mappings":"AA2EO,yCAVO,CAAC,cACJ,OAAO,mBAAmB,EAAE,IAAI,aAChC,MAAM,gBAEN,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,YAGjB,mBAAmB,CAAC,CAAC,CAAC,GACpB,iBAAiB,CAAC,CAAC,CAAC,CAyGhC;8BArKa,CAAC;YAED,CAAC,SAAS,EAAE,CAAC,KAAK,OAAO;;;;mBACzB,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC;;;YAMpB,MAAM,OAAO;;yBAIb,CAAC;aAED,YAAY;;;;eACZ,CAAC;;6BAKD,CAAC;YAED,YAAY,CAAC,CAAC,CAAC;WACf;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE;;gCAIjB,CAAC;;;;;;;;;;;;;;;;kDAcH,gBAAgB,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,GAAG"}
+{"version":3,"file":"prepare-revocable.d.ts","sourceRoot":"","sources":["prepare-revocable.js"],"names":[],"mappings":"AAiFO,yCAVO,CAAC,cACJ,OAAO,mBAAmB,EAAE,IAAI,aAChC,MAAM,gBAEN,WAAW,EAAE,YAGb,mBAAmB,CAAC,CAAC,CAAC,GACpB,iBAAiB,CAAC,CAAC,CAAC,CA0EhC;0BA7Ia,CAAC,uBAEJ,CAAC,KACC,OAAO,CAAC,CAAC,CAAC;8BAIT,CAAC;YAED,CAAC,SAAS,EAAE,CAAC,KAAK,OAAO;;;;mBACzB,aAAa;;;YAMb,MAAM,OAAO;;yBAIb,CAAC;aAED,YAAY;;;;eACZ,OAAO,CAAC,CAAC,CAAC;;6BAKV,CAAC;YAED,YAAY,CAAC,CAAC,CAAC;WACf;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE;;gCAIjB,CAAC;;;;;;;;;;;;;;;;8CAcH,gBAAgB,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,GAAG"}

package/src/prepare-revocable.js

@@ -1,6 +1,5 @@
-import { Fail, q } from '@endo/errors';
-import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
 import { M } from '@endo/patterns';
+import { wrapperMethods } from './prepare-attenuator.js';
 
 /** @import {Amplify} from '@endo/exo'; */
 
@@ -10,11 +9,18 @@ import { M } from '@endo/patterns';
 // use the attenuator implementation in prepare-attenuator.js.
 // Please co-maintain these two modules.
 
+/**
+ * @template [U=any]
+ * @callback MakeRevocable
+ * @param {U} underlying
+ * @returns {Partial<U>}
+ */
+
 /**
  * @template [U=any]
  * @typedef {object} RevocableMakerKit
  * @property {(revocable: U) => boolean} revoke
- * @property {(underlying: U) => U} makeRevocable
+ * @property {MakeRevocable} makeRevocable
  *   Forwards to the underlying exo object, until revoked
  */
 
@@ -27,7 +33,7 @@ import { M } from '@endo/patterns';
  * @template [U=any]
  * @typedef {object} RevocableKit
  * @property {RevokerFacet} revoker
- * @property {U} revocable
+ * @property {Partial<U>} revocable
  *   Forwards to the underlying exo object, until revoked
  */
 
@@ -45,14 +51,14 @@ import { M } from '@endo/patterns';
  *   The `interfaceName` of the underlying interface guard.
  *   Defaults to the `uKindName`.
  * @property {Record<
- *   string|symbol,
+ *   PropertyKey,
  *   import('@endo/patterns').MethodGuard
  * >} [extraMethodGuards]
  * For guarding the `extraMethods`, if you include them below. These appear
  * only on the synthesized interface guard for the revocable caretaker, and
  * do not necessarily correspond to any method of the underlying.
  * @property {Record<
- *   string|symbol,
+ *   PropertyKey,
  *   (this: RevocableKitThis<U>, ...args: any[]) => any
  * >} [extraMethods]
  * Extra methods adding behavior only to the revocable caretaker, and
@@ -67,7 +73,7 @@ import { M } from '@endo/patterns';
  * @param {import('@agoric/base-zone').Zone} zone
  * @param {string} uKindName
  *   The `kindName` of the underlying exo class
- * @param {(string|symbol)[]} uMethodNames
+ * @param {PropertyKey[]} uMethodNames
  *   The method names of the underlying exo class that should be represented
  *   by transparently-forwarding methods of the revocable caretaker.
  * @param {RevocableKitOptions<U>} [options]
@@ -81,22 +87,16 @@ export const prepareRevocableMakerKit = (
 ) => {
   const {
     uInterfaceName = uKindName,
-    extraMethodGuards = undefined,
-    extraMethods = undefined,
+    extraMethodGuards = {},
+    extraMethods = {},
   } = options;
   const RevocableIKit = harden({
     revoker: M.interface(`${uInterfaceName}_revoker`, {
       revoke: M.call().returns(M.boolean()),
     }),
-    revocable: M.interface(
-      `${uInterfaceName}_revocable`,
-      {
-        ...extraMethodGuards,
-      },
-      {
-        defaultGuards: 'raw',
-      },
-    ),
+    revocable: M.interface(`${uInterfaceName}_revocable`, extraMethodGuards, {
+      defaultGuards: 'raw',
+    }),
   });
 
   const revocableKindName = `${uKindName}_caretaker`;
@@ -107,9 +107,7 @@ export const prepareRevocableMakerKit = (
   const makeRevocableKit = zone.exoClassKit(
     revocableKindName,
     RevocableIKit,
-    underlying => ({
-      underlying,
-    }),
+    underlying => ({ underlying }),
     {
       revoker: {
         revoke() {
@@ -121,30 +119,10 @@ export const prepareRevocableMakerKit = (
           return true;
         },
       },
-      revocable: {
-        ...fromUniqueEntries(
-          uMethodNames.map(name => [
-            name,
-            {
-              // Use concise method syntax for exo methods
-              [name](...args) {
-                // @ts-expect-error normal exo-this typing confusion
-                const { underlying } = this.state;
-                underlying !== undefined ||
-                  Fail`${q(revocableKindName)} revoked`;
-                return underlying[name](...args);
-              },
-              // @ts-expect-error using possible symbol as index type
-            }[name],
-          ]),
-        ),
-        ...extraMethods,
-      },
+      revocable: wrapperMethods(revocableKindName, uMethodNames, extraMethods),
     },
     {
-      stateShape: {
-        underlying: M.opt(M.remotable('underlying')),
-      },
+      stateShape: { underlying: M.opt(M.remotable('underlying')) },
       receiveAmplifier: amp => {
         amplifier = amp;
       },
@@ -152,12 +130,9 @@ export const prepareRevocableMakerKit = (
   );
 
   /**
-   * @param {U} underlying
-   * @returns {U}
+   * @type {MakeRevocable}
    */
-  const makeRevocable = underlying =>
-    // @ts-expect-error some confusion about UU vs Guarded<U> I think
-    makeRevocableKit(underlying).revocable;
+  const makeRevocable = underlying => makeRevocableKit(underlying).revocable;
 
   /**
    * @param {U} revocable

package/test/prepare-attenuator.test.js

@@ -87,6 +87,8 @@ test('test revoke defineVirtualExoClassKit', t => {
           if (state.underlying === undefined) {
             return false;
           }
+          // @ts-expect-error Setting this to `undefined` is purposely outside
+          // the type system.
           state.underlying = undefined;
           return true;
         },