@agoric/base-zone 0.1.1-dev-7ffae88.0 → 0.1.1-orchestration-dev-096c4e8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/base-zone",
-  "version": "0.1.1-dev-7ffae88.0+7ffae88",
+  "version": "0.1.1-orchestration-dev-096c4e8.0+096c4e8",
   "description": "Allocation zone abstraction library and heap implementation",
   "type": "module",
   "repository": "https://github.com/Agoric/agoric-sdk",
@@ -19,6 +19,7 @@
   },
   "exports": {
     ".": "./src/index.js",
+    "./zone-helpers.js": "./zone-helpers.js",
     "./heap.js": "./heap.js",
     "./tools/*": "./tools/*"
   },
@@ -26,14 +27,16 @@
   "author": "Agoric",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agoric/store": "0.9.3-dev-7ffae88.0+7ffae88",
-    "@endo/exo": "^1.1.0",
-    "@endo/far": "^1.0.2",
-    "@endo/pass-style": "^1.1.0",
-    "@endo/patterns": "^1.1.0"
+    "@agoric/store": "0.9.3-orchestration-dev-096c4e8.0+096c4e8",
+    "@endo/common": "^1.1.0",
+    "@endo/exo": "^1.2.1",
+    "@endo/far": "^1.0.4",
+    "@endo/pass-style": "^1.2.0",
+    "@endo/patterns": "^1.2.0"
   },
   "devDependencies": {
-    "@endo/init": "^1.0.2",
+    "@endo/init": "^1.0.4",
+    "@endo/ses-ava": "^1.1.2",
     "ava": "^5.3.0"
   },
   "publishConfig": {
@@ -53,7 +56,7 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 88.7
+    "atLeast": 89.25
   },
-  "gitHead": "7ffae88ae37df782d5ffe3cf92261a498b0f636c"
+  "gitHead": "096c4e8fce80e9a509b0e1a30fda11736c4570e1"
 }

package/src/prepare-revocable.d.ts

@@ -0,0 +1,36 @@
+export function prepareRevocableKit<U extends unknown = any>(zone: import('@agoric/base-zone').Zone, uKindName: string, uMethodNames: (string | symbol)[], options?: RevocableKitOptions<any> | undefined): (underlying: U) => RevocableKit<U>;
+export type Revoker = {
+    revoke: () => boolean;
+};
+export type RevocableKit<U extends unknown = any> = {
+    revoker: Revoker;
+    /**
+     *   Forwards to the underlying exo object, until revoked
+     */
+    revocable: U;
+};
+export type RevocableKitThis<U = any> = {
+    facets: RevocableKit<U>;
+    state: {
+        underlying: U;
+    };
+};
+export type RevocableKitOptions<U extends unknown = 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 revocable caretaker, 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 revocable caretaker, and
+     * do not necessarily correspond to any methods of the underlying.
+     */
+    extraMethods?: Record<string | symbol, (this: RevocableKitThis<U>, ...args: any[]) => any> | undefined;
+};
+//# sourceMappingURL=prepare-revocable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepare-revocable.d.ts","sourceRoot":"","sources":["prepare-revocable.js"],"names":[],"mappings":"AA6DO,mEATI,OAAO,mBAAmB,EAAE,IAAI,aAChC,MAAM,gBAEN,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,sFAiF3B;;YAjIa,MAAM,OAAO;;;aAMb,OAAO;;;;eACP,CAAC;;;YAOD,aAAa,CAAC,CAAC;WACf;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE;;;;;;;;;;;;;;;;;;kDAkBnB,iBAAiB,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,GAAG"}

package/src/prepare-revocable.js

@@ -0,0 +1,138 @@
+import { M } from '@endo/patterns';
+import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
+
+const { Fail, quote: q } = assert;
+
+/**
+ * @typedef {object} Revoker
+ * @property {() => boolean} revoke
+ */
+
+/**
+ * @template {any} [U=any]
+ * @typedef {object} RevocableKit
+ * @property {Revoker} revoker
+ * @property {U} revocable
+ *   Forwards to the underlying exo object, until revoked
+ */
+
+/**
+ * @template [U=any]
+ * @typedef {object} RevocableKitThis
+ * @property {RevocableKit<U>} facets
+ * @property {{ underlying: U }} state
+ */
+
+/**
+ * @template {any} [U=any]
+ * @typedef {object} RevocableKitOptions
+ * @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 revocable caretaker, and
+ * do not necessarily correspond to any method of the underlying.
+ * @property {Record<
+ *   string|symbol,
+ *   (this: RevocableKitThis<U>, ...args: any[]) => any
+ * >} [extraMethods]
+ * Extra methods adding behavior only to the revocable caretaker, and
+ * do not necessarily correspond to any methods of the underlying.
+ */
+
+/**
+ * Make an exo class kit for wrapping an underlying exo class,
+ * where the wrapper is a revocable forwarder.
+ *
+ * @deprecated Change to `prepareRevocableMakerKit` once #8977 happens
+ * @template {any} [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 revocable caretaker.
+ * @param {RevocableKitOptions} [options]
+ * @returns {(underlying: U) => RevocableKit<U>}
+ */
+export const prepareRevocableKit = (
+  zone,
+  uKindName,
+  uMethodNames,
+  options = {},
+) => {
+  const {
+    uInterfaceName = uKindName,
+    extraMethodGuards = undefined,
+    extraMethods = undefined,
+  } = options;
+  const RevocableIKit = harden({
+    revoker: M.interface(`${uInterfaceName}_revoker`, {
+      revoke: M.call().returns(M.boolean()),
+    }),
+    revocable: M.interface(
+      `${uInterfaceName}_revocable`,
+      {
+        ...extraMethodGuards,
+      },
+      {
+        defaultGuards: 'raw',
+      },
+    ),
+  });
+
+  const revocableKindName = `${uKindName}_caretaker`;
+
+  const makeRevocableKit = zone.exoClassKit(
+    revocableKindName,
+    RevocableIKit,
+    underlying => ({
+      underlying,
+    }),
+    {
+      revoker: {
+        revoke() {
+          const { state } = this;
+          if (state.underlying === undefined) {
+            return false;
+          }
+          state.underlying = undefined;
+          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,
+      },
+    },
+    {
+      stateShape: {
+        underlying: M.opt(M.remotable('underlying')),
+      },
+    },
+  );
+
+  // eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
+  // @ts-ignore parameter confusion
+  return makeRevocableKit;
+};
+harden(prepareRevocableKit);

package/test/prepare-test-env-ava.js

@@ -1,5 +1,4 @@
-// eslint-disable-next-line import/no-extraneous-dependencies
+import { wrapTest } from '@endo/ses-ava';
+import rawTest from 'ava';
 
-import test from 'ava';
-
-export { test };
+export const test = wrapTest(rawTest);

package/test/test-prepare-revocable.js

@@ -0,0 +1,117 @@
+// 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 { prepareRevocableKit } from '../src/prepare-revocable.js';
+
+const UpCounterI = M.interface('UpCounter', {
+  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()),
+});
+
+const DownCounterI = M.interface('DownCounter', {
+  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 revoke defineVirtualExoClass', t => {
+  const zone = makeHeapZone('rootZone');
+
+  const makeUnderlyingUpCounter = zone.exoClass(
+    'UpCounter',
+    UpCounterI,
+    /** @param {number} [x] */
+    (x = 0) => ({ x }),
+    {
+      incr(y = 1) {
+        const { state } = this;
+        state.x += y;
+        return state.x;
+      },
+    },
+  );
+
+  const makeRevocableUpCounterKit = prepareRevocableKit(zone, 'UpCounter', [
+    'incr',
+  ]);
+
+  const makeUpCounterKit = x =>
+    makeRevocableUpCounterKit(makeUnderlyingUpCounter(x));
+
+  const { revoker, revocable: upCounter } = makeUpCounterKit(3);
+  t.is(upCounter.incr(5), 8);
+  t.is(revoker.revoke(), true);
+  t.throws(() => upCounter.incr(1), {
+    message: '"UpCounter_caretaker" revoked',
+  });
+});
+
+test('test revoke defineVirtualExoClassKit', t => {
+  const zone = makeHeapZone('rootZone');
+
+  const makeUnderlyingCounterKit = zone.exoClassKit(
+    'Counter',
+    { up: UpCounterI, down: DownCounterI },
+    /** @param {number} [x] */
+    (x = 0) => ({ x }),
+    {
+      up: {
+        incr(y = 1) {
+          const { state } = this;
+          state.x += y;
+          return state.x;
+        },
+      },
+      down: {
+        decr(y = 1) {
+          const { state } = this;
+          state.x -= y;
+          return state.x;
+        },
+      },
+    },
+  );
+
+  const makeRevocableUpCounterKit = prepareRevocableKit(
+    zone,
+    'UpCounter',
+    ['incr'],
+    {
+      extraMethodGuards: {
+        selfRevoke: M.call().returns(M.boolean()),
+      },
+      extraMethods: {
+        selfRevoke() {
+          const { revoker } = this.facets;
+          return revoker.revoke();
+        },
+      },
+    },
+  );
+
+  const makeCounterKit = x => {
+    const { up: upCounter, down: downCounter } = makeUnderlyingCounterKit(x);
+    const { revocable: revocableUpCounter } =
+      makeRevocableUpCounterKit(upCounter);
+    return harden({
+      up: revocableUpCounter,
+      down: downCounter,
+    });
+  };
+
+  const { up: upCounter, down: downCounter } = makeCounterKit(3);
+  t.is(upCounter.incr(5), 8);
+  t.is(downCounter.decr(), 7);
+  t.is(upCounter.selfRevoke(), true);
+  t.throws(() => upCounter.incr(3), {
+    message: '"UpCounter_caretaker" revoked',
+  });
+  t.is(downCounter.decr(), 6);
+});

package/zone-helpers.d.ts

@@ -0,0 +1,2 @@
+export * from "./src/prepare-revocable.js";
+//# sourceMappingURL=zone-helpers.d.ts.map

package/zone-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone-helpers.d.ts","sourceRoot":"","sources":["zone-helpers.js"],"names":[],"mappings":""}

package/zone-helpers.js

@@ -0,0 +1 @@
+export * from './src/prepare-revocable.js';