@agoric/base-zone 0.1.1-dev-f8c06e6.0 → 0.1.1-dev-c962ba0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/base-zone",
-  "version": "0.1.1-dev-f8c06e6.0+f8c06e6",
+  "version": "0.1.1-dev-c962ba0.0+c962ba0",
   "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-f8c06e6.0+f8c06e6",
+    "@agoric/store": "0.9.3-dev-c962ba0.0+c962ba0",
     "@endo/common": "^1.2.10",
     "@endo/errors": "^1.2.10",
     "@endo/exo": "^1.5.9",
@@ -59,5 +59,5 @@
   "typeCoverage": {
     "atLeast": 91.4
   },
-  "gitHead": "f8c06e6e6f0108a8fddcf045d8454916bd2060e8"
+  "gitHead": "c962ba0771022947027b9bd76339a3ab21406b20"
 }

package/src/prepare-attenuator.d.ts

@@ -0,0 +1,27 @@
+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 type AttenuatorThis<U = any> = {
+    self: U;
+    state: {
+        underlying: U;
+    };
+};
+export type AttenuatorOptions<U = any> = {
+    /**
+     * The `interfaceName` of the underlying interface guard.
+     * Defaults to the `uKindName`.
+     */
+    uInterfaceName?: string | undefined;
+    /**
+     * 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.
+     */
+    extraMethodGuards?: Record<string | symbol, 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;
+};
+//# sourceMappingURL=prepare-attenuator.d.ts.map

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

@@ -0,0 +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"}

package/src/prepare-attenuator.js

@@ -0,0 +1,131 @@
+import { Fail, q } from '@endo/errors';
+import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
+import { M } from '@endo/patterns';
+
+// This attenuator implementation is just a simplification of the
+// revocable kit implementation in prepare-revocable.js. The revocable kit
+// provides both attenuation and revocation, since we can have both for the
+// price of just one level of indirection. But if you don't need revocation,
+// the revocable kit has more API complexity than you need.
+//
+// We could have built `prepareAttenuatorMaker` as a trivial wrapper around
+// `prepareRevocableMakerKit`. But then we'd have the weird artifact that the
+// `extraMethods` would see a `{ state, facets: { revocable, revoker }}` context
+// rather than a `{ state, self }` context. So instead, we copied and edited it
+// down. Please co-maintain these two modules.
+
+// Because the attenuator just uses an exo class rather than a class kit,
+// it cannot support the privilege separation of a distinct revoker facet.
+// But it can still support `selfRevoke` as a separate `extraMethod`, as shown
+// in a testcase at `prepare-attenuator.test.js`
+
+/**
+ * @template [U=any]
+ * @callback MakeAttenuator
+ * @param {U} underlying
+ * @returns {U}
+ */
+
+/**
+ * @template [U=any]
+ * @typedef {object} AttenuatorThis
+ * @property {U} self
+ * @property {{ underlying: U }} state
+ */
+
+/**
+ * @template [U=any]
+ * @typedef {object} AttenuatorOptions
+ * @property {string} [uInterfaceName]
+ *   The `interfaceName` of the underlying interface guard.
+ *   Defaults to the `uKindName`.
+ * @property {Record<
+ *   string|symbol,
+ *   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,
+ *   (this: AttenuatorThis<U>, ...args: any[]) => any
+ * >} [extraMethods]
+ * Extra methods adding behavior only to the attenuator, and
+ * do not necessarily correspond to any methods of the underlying.
+ */
+
+/**
+ * Make an exo class for wrapping an underlying exo class,
+ * where the wrapper is an attenuator of the underlying.
+ *
+ * @template [U=any]
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {string} uKindName
+ *   The `kindName` of the underlying exo class
+ * @param {(string|symbol)[]} uMethodNames
+ *   The method names of the underlying exo class that should be represented
+ *   by transparently-forwarding methods of the attenuator.
+ * @param {AttenuatorOptions<U>} [options]
+ * @returns {MakeAttenuator}
+ */
+export const prepareAttenuatorMaker = (
+  zone,
+  uKindName,
+  uMethodNames,
+  options = {},
+) => {
+  const {
+    uInterfaceName = uKindName,
+    extraMethodGuards = undefined,
+    extraMethods = undefined,
+  } = options;
+  const AttenuatorI = M.interface(
+    `${uInterfaceName}_attenuator`,
+    {
+      ...extraMethodGuards,
+    },
+    {
+      defaultGuards: 'raw',
+    },
+  );
+
+  const attenuatorKindName = `${uKindName}_attenuator`;
+
+  return zone.exoClass(
+    attenuatorKindName,
+    AttenuatorI,
+    underlying => ({
+      underlying,
+    }),
+    {
+      ...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')),
+      },
+    },
+  );
+};
+harden(prepareAttenuatorMaker);

package/src/prepare-revocable.d.ts

@@ -1,4 +1,4 @@
-export function prepareRevocableMakerKit<U = any>(zone: import("@agoric/base-zone").Zone, uKindName: string, uMethodNames: (string | symbol)[], options?: RevocableKitOptions): RevocableMakerKit<U>;
+export function prepareRevocableMakerKit<U = any>(zone: import("@agoric/base-zone").Zone, uKindName: string, uMethodNames: (string | symbol)[], options?: RevocableKitOptions<U>): RevocableMakerKit<U>;
 export type RevocableMakerKit<U = any> = {
     revoke: (revocable: U) => boolean;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"prepare-revocable.d.ts","sourceRoot":"","sources":["prepare-revocable.js"],"names":[],"mappings":"AAqEO,yCAVO,CAAC,cACJ,OAAO,mBAAmB,EAAE,IAAI,aAChC,MAAM,gBAEN,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,YAGjB,mBAAmB,GACjB,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":"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"}

package/src/prepare-revocable.js

@@ -4,6 +4,12 @@ import { M } from '@endo/patterns';
 
 /** @import {Amplify} from '@endo/exo'; */
 
+// This revocable kit implementation provides for both attenuation and
+// revocation, since both can be provided at the cost of one level of
+// indirection. But if you just need attenuation without revocation, better to
+// use the attenuator implementation in prepare-attenuator.js.
+// Please co-maintain these two modules.
+
 /**
  * @template [U=any]
  * @typedef {object} RevocableMakerKit
@@ -64,7 +70,7 @@ import { M } from '@endo/patterns';
  * @param {(string|symbol)[]} uMethodNames
  *   The method names of the underlying exo class that should be represented
  *   by transparently-forwarding methods of the revocable caretaker.
- * @param {RevocableKitOptions} [options]
+ * @param {RevocableKitOptions<U>} [options]
  * @returns {RevocableMakerKit<U>}
  */
 export const prepareRevocableMakerKit = (

package/test/prepare-attenuator.test.js

@@ -0,0 +1,108 @@
+// Modeled on test-heap-classes.js
+
+import { test } from './prepare-test-env-ava.js';
+
+// eslint-disable-next-line import/order
+import { M } from '@endo/patterns';
+import { makeHeapZone } from '../src/heap.js';
+import { prepareAttenuatorMaker } from '../src/prepare-attenuator.js';
+
+const CounterI = M.interface('Counter', {
+  incr: M.call()
+    // TODO M.number() should not be needed to get a better error message
+    .optional(M.and(M.number(), M.gte(0)))
+    .returns(M.number()),
+  decr: M.call()
+    // TODO M.number() should not be needed to get a better error message
+    .optional(M.and(M.number(), M.gte(0)))
+    .returns(M.number()),
+});
+
+test('test attenuate defineVirtualExoClass', t => {
+  const zone = makeHeapZone('rootZone');
+
+  const makeUnderlyingCounter = zone.exoClass(
+    'Counter',
+    CounterI,
+    /** @param {number} [x] */
+    (x = 0) => ({ x }),
+    {
+      incr(y = 1) {
+        const { state } = this;
+        state.x += y;
+        return state.x;
+      },
+      decr(y = 1) {
+        const { state } = this;
+        state.x -= y;
+        return state.x;
+      },
+    },
+  );
+
+  const makeUpAttenuator = prepareAttenuatorMaker(zone, 'UpCounter', ['incr']);
+
+  const makeUpCounter = x => makeUpAttenuator(makeUnderlyingCounter(x));
+
+  const upCounter = makeUpCounter(3);
+  t.is(upCounter.incr(5), 8);
+  t.throws(() => upCounter.decr(1), {
+    message: 'upCounter.decr is not a function',
+  });
+});
+
+test('test revoke defineVirtualExoClassKit', t => {
+  const zone = makeHeapZone('rootZone');
+
+  const makeUnderlyingCounter = zone.exoClass(
+    'Counter',
+    CounterI,
+    /** @param {number} [x] */
+    (x = 0) => ({ x }),
+    {
+      incr(y = 1) {
+        const { state } = this;
+        state.x += y;
+        return state.x;
+      },
+      decr(y = 1) {
+        const { state } = this;
+        state.x -= y;
+        return state.x;
+      },
+    },
+  );
+
+  const makeDownAttenuator = prepareAttenuatorMaker(
+    zone,
+    'DownCounter',
+    ['decr'],
+    {
+      extraMethodGuards: {
+        selfRevoke: M.call().returns(M.boolean()),
+      },
+      extraMethods: {
+        selfRevoke() {
+          const { state } = this;
+          if (state.underlying === undefined) {
+            return false;
+          }
+          state.underlying = undefined;
+          return true;
+        },
+      },
+    },
+  );
+
+  const makeDownCounter = x => makeDownAttenuator(makeUnderlyingCounter(x));
+
+  const downCounter = makeDownCounter(3);
+  t.throws(() => downCounter.incr(1), {
+    message: 'downCounter.incr is not a function',
+  });
+  t.is(downCounter.decr(), 2);
+  t.is(downCounter.selfRevoke(), true);
+  t.throws(() => downCounter.decr(3), {
+    message: '"DownCounter_attenuator" revoked',
+  });
+});

package/tsconfig.build.tsbuildinfo

@@ -1 +1 @@
-{"root":["./heap.js","./zone-helpers.js","./src/heap.js","./src/index.js","./src/is-passable.js","./src/keys.js","./src/make-once.js","./src/prepare-revocable.js","./src/types.js","./src/watch-promise.js"],"version":"5.8.3"}
+{"root":["./heap.js","./zone-helpers.js","./src/heap.js","./src/index.js","./src/is-passable.js","./src/keys.js","./src/make-once.js","./src/prepare-attenuator.js","./src/prepare-revocable.js","./src/types.js","./src/watch-promise.js"],"version":"5.8.3"}