@agoric/swingset-liveslots 0.10.3-dev-9f8a76e.0 → 0.10.3-dev-e68f280.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/swingset-liveslots",
-  "version": "0.10.3-dev-9f8a76e.0+9f8a76e",
+  "version": "0.10.3-dev-e68f280.0+e68f280",
   "description": "SwingSet ocap support layer",
   "type": "module",
   "main": "src/index.js",
@@ -17,10 +17,9 @@
     "lint:eslint": "eslint ."
   },
   "dependencies": {
-    "@agoric/assert": "0.6.1-dev-9f8a76e.0+9f8a76e",
-    "@agoric/internal": "0.3.3-dev-9f8a76e.0+9f8a76e",
-    "@agoric/store": "0.9.3-dev-9f8a76e.0+9f8a76e",
-    "@agoric/vat-data": "0.5.3-dev-9f8a76e.0+9f8a76e",
+    "@agoric/assert": "0.6.1-dev-e68f280.0+e68f280",
+    "@agoric/internal": "0.3.3-dev-e68f280.0+e68f280",
+    "@agoric/store": "0.9.3-dev-e68f280.0+e68f280",
     "@endo/eventual-send": "^0.17.3",
     "@endo/exo": "^0.2.3",
     "@endo/far": "^0.2.19",
@@ -61,5 +60,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9f8a76ee66bd74f028158b689c4b437921613f63"
+  "gitHead": "e68f2805dde79871d1421e50c60f08e854e1851d"
 }

package/src/index.js

@@ -1,3 +1,4 @@
+/* eslint-disable import/export -- types files have no named runtime exports */
 export { makeLiveSlots, makeMarshaller } from './liveslots.js';
 
 export {
@@ -8,5 +9,5 @@ export {
   insistVatSyscallResult,
 } from './message.js';
 
-// eslint-disable-next-line import/export -- no named exports
 export * from './types.js';
+export * from './vatDataTypes.js';

package/src/vatDataTypes.d.ts

@@ -0,0 +1,203 @@
+/**
+ * @file Types for vat-data
+ *
+ * Facet is a single object with methods.
+ * Behavior is a description when defining a kind of what facets it will have.
+ * For the non-multi defineKind, there is just one facet so it doesn't have a key.
+ */
+import type {
+  InterfaceGuard,
+  MapStore,
+  Pattern,
+  SetStore,
+  StoreOptions,
+  WeakMapStore,
+  WeakSetStore,
+} from '@agoric/store';
+
+export type { MapStore, Pattern };
+
+export type Baggage = MapStore<string, unknown>;
+
+type Tail<T extends any[]> = T extends [head: any, ...rest: infer Rest]
+  ? Rest
+  : [];
+
+type MinusContext<
+  F extends (context, ...rest: any[]) => any,
+  P extends any[] = Parameters<F>, // P: are the parameters of F
+  R = ReturnType<F>, // R: the return type of F
+> = (...args: Tail<P>) => R;
+
+export type KindFacet<O> = { [K in keyof O]: MinusContext<O[K]> };
+
+export type KindFacets<B> = {
+  [FacetKey in keyof B]: KindFacet<B[FacetKey]>;
+};
+
+export type KindContext<S, F> = { state: S; self: KindFacet<F> };
+export type MultiKindContext<S, B> = { state: S; facets: KindFacets<B> };
+
+export type PlusContext<C, M> = (c: C, ...args: Parameters<M>) => ReturnType<M>;
+export type FunctionsPlusContext<C, O> = {
+  [K in keyof O]: PlusContext<C, O[K]>;
+};
+
+declare class DurableKindHandleClass {
+  private descriptionTag: string;
+}
+export type DurableKindHandle = DurableKindHandleClass;
+
+/**
+ * Grab bag of options that can be provided to `defineDurableKind` and its
+ * siblings. Not all options are meaningful in all contexts. See the
+ * doc-comments on each option.
+ */
+export type DefineKindOptions<C> = {
+  /**
+   * If provided, the `finish` function will be called after the instance is
+   * made and internally registered, but before it is returned. The finish
+   * function is to do any post-intantiation initialization that should be
+   * done before exposing the object to its clients.
+   */
+  finish?: (context: C) => void;
+
+  /**
+   * Meaningful to `makeScalarBigMapStore` and its siblings. These maker
+   * fuctions will make either virtual or durable stores, depending on
+   * this flag. Defaults to off, making virtual but not durable collections.
+   *
+   * Generally, durable collections are provided with `provideDurableMapStore`
+   * and its sibling, which use this flag internally. If you do not make
+   * durable collections by other means, you can consider this as
+   * intended for internal use only.
+   */
+  durable?: boolean;
+
+  /**
+   * If provided, it describes the shape of all state records of instances
+   * of this kind.
+   */
+  stateShape?: { [name: string]: Pattern };
+
+  /**
+   * Intended for internal use only.
+   * Should the raw methods receive their `context` argument as their first
+   * argument or as their `this` binding? For `defineDurableKind` and its
+   * siblings (including `prepareSingleton`), this defaults to off, meaning that
+   * their behavior methods receive `context` as their first argument.
+   * `prepareExoClass` and its siblings (including `prepareExo`) use
+   * this flag internally to indicate that their methods receive `context`
+   * as their `this` binding.
+   */
+  thisfulMethods?: boolean;
+
+  /**
+   * Intended for internal use only.
+   * If an `interfaceGuard` is provided, then the raw methods passed alongside
+   * it are wrapped by a function that first checks that this method's guard
+   * pattern is satisfied before calling the raw method.
+   *
+   * In `defineDurableKind` and its siblings, this defaults to off.
+   * `prepareExoClass` use this internally to protect their raw class methods
+   * using the provided interface.
+   */
+  interfaceGuard?: InterfaceGuard<unknown>;
+};
+
+export type VatData = {
+  // virtual kinds
+  /** @deprecated Use defineVirtualExoClass instead */
+  defineKind: <P, S, F>(
+    tag: string,
+    init: (...args: P) => S,
+    facet: F,
+    options?: DefineKindOptions<KindContext<S, F>>,
+  ) => (...args: P) => KindFacet<F>;
+
+  /** @deprecated Use defineVirtualExoClassKit instead */
+  defineKindMulti: <P, S, B>(
+    tag: string,
+    init: (...args: P) => S,
+    behavior: B,
+    options?: DefineKindOptions<MultiKindContext<S, B>>,
+  ) => (...args: P) => KindFacets<B>;
+
+  // durable kinds
+  makeKindHandle: (descriptionTag: string) => DurableKindHandle;
+
+  /** @deprecated Use defineDurableExoClass instead */
+  defineDurableKind: <P, S, F>(
+    kindHandle: DurableKindHandle,
+    init: (...args: P) => S,
+    facet: F,
+    options?: DefineKindOptions<KindContext<S, F>>,
+  ) => (...args: P) => KindFacet<F>;
+
+  /** @deprecated Use defineDurableExoClassKit instead */
+  defineDurableKindMulti: <P, S, B>(
+    kindHandle: DurableKindHandle,
+    init: (...args: P) => S,
+    behavior: B,
+    options?: DefineKindOptions<MultiKindContext<S, B>>,
+  ) => (...args: P) => KindFacets<B>;
+
+  providePromiseWatcher: unknown;
+  watchPromise: unknown;
+
+  makeScalarBigMapStore: <K, V>(
+    label: string,
+    options?: StoreOptions,
+  ) => MapStore<K, V>;
+  makeScalarBigWeakMapStore: <K, V>(
+    label: string,
+    options?: StoreOptions,
+  ) => WeakMapStore<K, V>;
+
+  makeScalarBigSetStore: <K>(
+    label: string,
+    options?: StoreOptions,
+  ) => SetStore<K>;
+  makeScalarBigWeakSetStore: <K>(
+    label: string,
+    options?: StoreOptions,
+  ) => WeakSetStore<K>;
+  canBeDurable: (specimen: unknown) => boolean;
+};
+
+// The JSDoc is repeated here and at the function definition so it appears
+// in IDEs where it's used, regardless of type resolution.
+export interface PickFacet {
+  /**
+   * When making a multi-facet kind, it's common to pick one facet to
+   * expose. E.g.,
+   *
+   *     const makeFoo = (a, b, c, d) => makeFooBase(a, b, c, d).self;
+   *
+   * This helper reduces the duplication:
+   *
+   *     const makeFoo = pickFacet(makeFooBase, 'self');
+   */
+  <M extends (...args: any[]) => any, F extends keyof ReturnType<M>>(
+    maker: M,
+    facetName: F,
+  ): (...args: Parameters<M>) => ReturnType<M>[F];
+}
+
+/** @deprecated Use prepareExoClass instead */
+export type PrepareKind = <P, S, F>(
+  baggage: Baggage,
+  tag: string,
+  init: (...args: P) => S,
+  facet: F,
+  options?: DefineKindOptions<KindContext<S, F>>,
+) => (...args: P) => KindFacet<F>;
+
+/** @deprecated Use prepareExoClassKit instead */
+export type PrepareKindMulti = <P, S, B>(
+  baggage: Baggage,
+  tag: string,
+  init: (...args: P) => S,
+  behavior: B,
+  options?: DefineKindOptions<MultiKindContext<S, B>>,
+) => (...args: P) => KindFacets<B>;

package/src/vatDataTypes.js

@@ -0,0 +1,2 @@
+// Empty JS file to correspond with vatDataTypes.d.ts
+export {};

package/tools/prepare-test-env.js

@@ -0,0 +1,14 @@
+/**
+ * Prepare Agoric SwingSet vat global environment for testing.
+ *
+ * Installs Hardened JS (and does lockdown), plus adds mocks for virtual objects
+ * and stores.
+ */
+
+import '@endo/init/pre.js';
+
+import '@agoric/internal/src/install-ses-debug.js';
+import { reincarnate } from './setup-vat-data.js';
+
+// Install the VatData globals.
+reincarnate();

package/tools/setup-vat-data.js

@@ -0,0 +1,54 @@
+// @ts-check
+/* global globalThis */
+// This file produces the globalThis.VatData property outside of a running
+// SwingSet so that it can be used by '@agoric/vat-data' (which only *consumes*
+// `globalThis.VatData`) in code under test.
+import { makeFakeVirtualStuff } from './fakeVirtualSupport.js';
+
+const { WeakMap, WeakSet } = globalThis;
+
+/** @type {ReturnType<makeFakeVirtualStuff>} */
+let fakeVomKit;
+
+globalThis.VatData = harden({
+  defineKind: (...args) => fakeVomKit.vom.defineKind(...args),
+  defineKindMulti: (...args) => fakeVomKit.vom.defineKindMulti(...args),
+  defineDurableKind: (...args) => fakeVomKit.vom.defineDurableKind(...args),
+  defineDurableKindMulti: (...args) =>
+    fakeVomKit.vom.defineDurableKindMulti(...args),
+  makeKindHandle: (...args) => fakeVomKit.vom.makeKindHandle(...args),
+  canBeDurable: (...args) => fakeVomKit.vom.canBeDurable(...args),
+  providePromiseWatcher: (...args) =>
+    fakeVomKit.wpm.providePromiseWatcher(...args),
+  watchPromise: (...args) => fakeVomKit.wpm.watchPromise(...args),
+  makeScalarBigMapStore: (...args) =>
+    fakeVomKit.cm.makeScalarBigMapStore(...args),
+  makeScalarBigWeakMapStore: (...args) =>
+    fakeVomKit.cm.makeScalarBigWeakMapStore(...args),
+  makeScalarBigSetStore: (...args) =>
+    fakeVomKit.cm.makeScalarBigSetStore(...args),
+  makeScalarBigWeakSetStore: (...args) =>
+    fakeVomKit.cm.makeScalarBigWeakSetStore(...args),
+});
+
+export const reincarnate = (options = {}) => {
+  const { fakeStore = new Map(), fakeVomKit: fvk } = options;
+
+  if (options.fakeVomKit) {
+    fvk.vom.flushStateCache();
+    fvk.cm.flushSchemaCache();
+    fvk.vrm.flushIDCounters();
+  }
+
+  fakeVomKit = makeFakeVirtualStuff({
+    ...options,
+    fakeStore,
+    WeakMap,
+    WeakSet,
+  });
+
+  globalThis.WeakMap = fakeVomKit.vom.VirtualObjectAwareWeakMap;
+  globalThis.WeakSet = fakeVomKit.vom.VirtualObjectAwareWeakSet;
+
+  return { ...options, fakeStore, fakeVomKit };
+};