API documentation of Agoric SDK / Exports / @agoric/vat-data

Module: @agoric/vat-data

Table of contents

Type Aliases

• Baggage
• DefineKindOptions

Variables

• M

Functions

• canBeDurable
• defineDurableExoClass
• defineDurableExoClassKit
• defineDurableKind
• defineDurableKindMulti
• defineKind
• defineKindMulti
• defineVirtualExoClass
• defineVirtualExoClassKit
• ignoreContext
• makeKindHandle
• makeScalarBigMapStore
• makeScalarBigSetStore
• makeScalarBigWeakMapStore
• makeScalarBigWeakSetStore
• makeScalarMapStore
• makeScalarSetStore
• makeScalarWeakMapStore
• makeScalarWeakSetStore
• partialAssign
• pickFacet
• prepareExo
• prepareExoClass
• prepareExoClassKit
• prepareKind
• prepareKindMulti
• prepareSingleton
• provide
• provideDurableMapStore
• provideDurableSetStore
• provideDurableWeakMapStore
• provideDurableWeakSetStore
• provideKindHandle
• providePromiseWatcher
• watchPromise

Type Aliases

Baggage

Ƭ Baggage: MapStore<string, any>

Defined in

packages/vat-data/src/index.js:49

---

DefineKindOptions

Ƭ DefineKindOptions<C>: Object

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.

Type parameters

Name
C

Type declaration

Name	Type	Description
durable?	boolean	As a kind option, intended for internal use only. 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.
finish?	(context: C) => void	-
interfaceGuard?	InterfaceGuard	Intended for internal use only. Only applicable if this is a class kind. A class kit kind should use interfaceGuardKit instead. 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 undefined. Exo classes use this internally to protect their raw class methods using the provided interface. In absence, an exo is protected anyway, while a bare kind is not (detected by !thisfulMethods),
interfaceGuardKit?	InterfaceGuardKit	Intended for internal use only. Only applicable if this is a class kit kind. A class kind should use interfaceGuard instead. If an interfaceGuardKit is provided, then each member of the interfaceGuardKit is used to guard the corresponding facet of the class kit. In defineDurableKindMulti and its siblings, this defaults to undefined. Exo class kits use this internally to protect their facets. In absence, an exo is protected anyway, while a bare kind is not (detected by !thisfulMethods),
receiveAmplifier?	ReceivePower<Amplify<F>>	If a receiveAmplifier function is provided to an exo class kit definition, it will be called with an Amplify function. If provided to the definition of a normal exo or exo class, the definition will throw, since only exo kits can be amplified. An Amplify function is a function that takes a facet instance of this class kit as an argument, in which case it will return the facets record, giving access to all the facet instances of the same cohort.
receiveInstanceTester?	ReceivePower<IsInstance>	If a receiveInstanceTester function is provided, it will be called during the definition of the exo class or exo class kit with an IsInstance function. The first argument of IsInstance is the value to be tested. When it may be a facet instance of an exo class kit, the optional second argument, if provided, is a facetName. In that case, the function tests only if the first argument is an instance of that facet of the associated exo class kit.
stateShape?	MapStore	If provided, it describes the shape of all state records of instances of this kind.
thisfulMethods?	boolean	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.

Defined in

packages/swingset-liveslots/src/vatDataTypes.d.ts:66

Variables

M

• Const M: MatcherNamespace

Defined in

node_modules/@endo/patterns/src/patterns/patternMatchers.d.ts:18

Functions

canBeDurable

▸ canBeDurable(specimen): boolean

Parameters

Name	Type
specimen	unknown

Returns

boolean

Defined in

packages/vat-data/src/vat-data-bindings.js:53

---

defineDurableExoClass

▸ defineDurableExoClass<I, T>(kindHandle, interfaceGuard, init, methods, options?): (...args: Parameters<I>) => Guarded<T>

Type parameters

Name	Type	Description
I	extends (...args: any) => any	init state function
T	extends Record<PropertyKey, CallableFunction>	methods

Parameters

Name	Type
kindHandle	DurableKindHandleClass
interfaceGuard	undefined | InterfaceGuard
init	I
methods	T & ThisType<{ self: T ; state: ReturnType<I> }>
options?	DefineKindOptions<{ self: T ; state: ReturnType<I> }>

Returns

fn

▸ (...args): Guarded<T>

Parameters

Name	Type
...args	Parameters<I>

Returns

Guarded<T>

Defined in

packages/vat-data/src/exo-utils.js:332

---

defineDurableExoClassKit

▸ defineDurableExoClassKit<I, T>(kindHandle, interfaceGuardKit, init, facets, options?): (...args: Parameters<I>) => GuardedKit<T>

Type parameters

Name	Type	Description
I	extends (...args: any) => any	init state function
T	extends Record<string, Record<PropertyKey, CallableFunction>>	facets

Parameters

Name	Type
kindHandle	DurableKindHandleClass
interfaceGuardKit	undefined | InterfaceGuardKit
init	I
facets	T & ThisType<{ facets: GuardedKit<T> ; state: ReturnType<I> }>
options?	DefineKindOptions<{ facets: T ; state: ReturnType<I> }>

Returns

fn

▸ (...args): GuardedKit<T>

Parameters

Name	Type
...args	Parameters<I>

Returns

GuardedKit<T>

Defined in

packages/vat-data/src/exo-utils.js:333

---

defineDurableKind

▸ defineDurableKind<P, S, F>(kindHandle, init, facet, options?): (...args: P) => KindFacet<F>

Type parameters

Name
P
S
F

Parameters

Name	Type
kindHandle	DurableKindHandleClass
init	(...args: P) => S
facet	F
options?	DefineKindOptions<KindContext<S, F>>

Returns

fn

▸ (...args): KindFacet<F>

Parameters

Name	Type
...args	P

Returns

KindFacet<F>

Defined in

packages/vat-data/src/vat-data-bindings.js:41

---

defineDurableKindMulti

▸ defineDurableKindMulti<P, S, B>(kindHandle, init, behavior, options?): (...args: P) => KindFacets<B>

Type parameters

Name
P
S
B

Parameters

Name	Type
kindHandle	DurableKindHandleClass
init	(...args: P) => S
behavior	B
options?	DefineKindOptions<MultiKindContext<S, B>>

Returns

fn

▸ (...args): KindFacets<B>

Parameters

Name	Type
...args	P

Returns

KindFacets<B>

Defined in

packages/vat-data/src/vat-data-bindings.js:42

---

defineKind

▸ defineKind<P, S, F>(tag, init, facet, options?): (...args: P) => KindFacet<F>

Type parameters

Name
P
S
F

Parameters

Name	Type
tag	string
init	(...args: P) => S
facet	F
options?	DefineKindOptions<KindContext<S, F>>

Returns

fn

▸ (...args): KindFacet<F>

Parameters

Name	Type
...args	P

Returns

KindFacet<F>

Defined in

packages/vat-data/src/vat-data-bindings.js:39

---

defineKindMulti

▸ defineKindMulti<P, S, B>(tag, init, behavior, options?): (...args: P) => KindFacets<B>

Type parameters

Name
P
S
B

Parameters

Name	Type
tag	string
init	(...args: P) => S
behavior	B
options?	DefineKindOptions<MultiKindContext<S, B>>

Returns

fn

▸ (...args): KindFacets<B>

Parameters

Name	Type
...args	P

Returns

KindFacets<B>

Defined in

packages/vat-data/src/vat-data-bindings.js:40

---

defineVirtualExoClass

▸ defineVirtualExoClass<I, T>(tag, interfaceGuard, init, methods, options?): (...args: Parameters<I>) => Guarded<T>

Type parameters

Name	Type	Description
I	extends (...args: any) => any	init state function
T	T	behavior

Parameters

Name	Type
tag	string
interfaceGuard	undefined | InterfaceGuard
init	I
methods	T & ThisType<{ self: T ; state: ReturnType<I> }>
options?	DefineKindOptions<{ self: T ; state: ReturnType<I> }>

Returns

fn

▸ (...args): Guarded<T>

Parameters

Name	Type
...args	Parameters<I>

Returns

Guarded<T>

Defined in

packages/vat-data/src/exo-utils.js:330

---

defineVirtualExoClassKit

▸ defineVirtualExoClassKit<I, T>(tag, interfaceGuardKit, init, facets, options?): (...args: Parameters<I>) => GuardedKit<T>

Type parameters

Name	Type	Description
I	extends (...args: any) => any	init state function
T	extends Record<string, Record<PropertyKey, CallableFunction>>	facets

Parameters

Name	Type
tag	string
interfaceGuardKit	undefined | InterfaceGuardKit
init	I
facets	T & ThisType<{ facets: GuardedKit<T> ; state: ReturnType<I> }>
options?	DefineKindOptions<{ facets: T ; state: ReturnType<I> }>

Returns

fn

▸ (...args): GuardedKit<T>

Parameters

Name	Type
...args	Parameters<I>

Returns

GuardedKit<T>

Defined in

packages/vat-data/src/exo-utils.js:331

---

ignoreContext

▸ ignoreContext<T>(fn): PlusContext<never, T>

Make a version of the argument function that takes a kind context but ignores it.

Type parameters

Name	Type
T	extends Function

Parameters

Name	Type
fn	T

Returns

PlusContext<never, T>

Defined in

packages/vat-data/src/exo-utils.js:18

---

makeKindHandle

▸ makeKindHandle(descriptionTag): DurableKindHandleClass

Parameters

Name	Type
descriptionTag	string

Returns

DurableKindHandleClass

Defined in

packages/vat-data/src/vat-data-bindings.js:46

---

makeScalarBigMapStore

▸ makeScalarBigMapStore<K, V>(label, options?): MapStore<K, V>

Type parameters

Name
K
V

Parameters

Name	Type
label	string
options?	any

Returns

MapStore<K, V>

Defined in

packages/vat-data/src/vat-data-bindings.js:49

---

makeScalarBigSetStore

▸ makeScalarBigSetStore<K>(label, options?): SetStore<K>

Type parameters

Name
K

Parameters

Name	Type
label	string
options?	any

Returns

SetStore<K>

Defined in

packages/vat-data/src/vat-data-bindings.js:51

---

makeScalarBigWeakMapStore

▸ makeScalarBigWeakMapStore<K, V>(label, options?): WeakMapStore<K, V>

Type parameters

Name
K
V

Parameters

Name	Type
label	string
options?	any

Returns

WeakMapStore<K, V>

Defined in

packages/vat-data/src/vat-data-bindings.js:50

---

makeScalarBigWeakSetStore

▸ makeScalarBigWeakSetStore<K>(label, options?): WeakSetStore<K>

Type parameters

Name
K

Parameters

Name	Type
label	string
options?	any

Returns

WeakSetStore<K>

Defined in

packages/vat-data/src/vat-data-bindings.js:52

---

makeScalarMapStore

▸ makeScalarMapStore<K, V>(tag?, options?): MapStore<K, V>

Distinguishes between adding a new key (init) and updating or referencing a key (get, set, delete).

init is only allowed if the key does not already exist. Get, set and delete are only allowed if the key does already exist.

This is a scalar map in that the keys can only be atomic values, primitives or remotables. Other storeMaps will accept, for example, copyArrays and copyRecords, as keys and look them up based on equality of their contents.

Type parameters

Name	Type
K	extends unknown
V	extends unknown

Parameters

Name	Type	Default value	Description
tag?	string	'key'	the column name for the key
options?	StoreOptions	{}	-

Returns

MapStore<K, V>

Defined in

packages/store/src/stores/scalarMapStore.js:136

---

makeScalarSetStore

▸ makeScalarSetStore<K>(tag?, options?): SetStore<K>

Distinguishes between adding a new key (init) and updating or referencing a key (get, set, delete).

init is only allowed if the key does not already exist. Get, set and delete are only allowed if the key does already exist.

This is a scalar set in that the keys can only be atomic values, primitives or remotables. Other storeSets will accept, for example, copyArrays and copyRecords, as keys and look them up based on equality of their contents.

Type parameters

Name
K

Parameters

Name	Type	Default value	Description
tag?	string	'key'	tag for debugging
options?	StoreOptions	{}	-

Returns

SetStore<K>

Defined in

packages/store/src/stores/scalarSetStore.js:92

---

makeScalarWeakMapStore

▸ makeScalarWeakMapStore<K, V>(tag?, options?): WeakMapStore<K, V>

This is a scalar mapStore in that the keys can only be atomic values: primitives or remotables. Other mapStores will accept, for example, copyArrays and copyRecords as keys and look them up based on equality of their contents.

TODO For now, this scalarWeakMap accepts only remotables, reflecting the constraints of the underlying JavaScript WeakMap it uses internally. But it should accept the primitives as well, storing them in a separate internal map. What makes it "weak" is that it provides no API for enumerating what's there. Though note that this would only enables collection of the remotables, since the other primitives may always reappear.

Type parameters

Name
K
V

Parameters

Name	Type	Default value	Description
tag?	string	'key'	tag for debugging
options?	StoreOptions	{}	-

Returns

WeakMapStore<K, V>

Defined in

packages/store/src/stores/scalarWeakMapStore.js:99

---

makeScalarWeakSetStore

▸ makeScalarWeakSetStore<K>(tag?, options?): WeakSetStore<K>

This is a scalar set in that the keys can only be atomic values, primitives or remotables. Other storeSets will accept, for example, copyArrays and copyRecords, as keys and look them up based on equality of their contents.

TODO For now, this scalarWeakSet accepts only remotables, reflecting the constraints of the underlying JavaScript WeakSet it uses internally. But it should accept the primitives as well, storing them in a separate internal set. What makes it "weak" is that it provides no API for enumerating what's there. Though note that this would only enables collection of the remotables, since the other primitives may always appear.

Type parameters

Name
K

Parameters

Name	Type	Default value	Description
tag?	string	'key'	tag for debugging
options?	StoreOptions	{}	-

Returns

WeakSetStore<K>

Defined in

packages/store/src/stores/scalarWeakSetStore.js:81

---

partialAssign

▸ partialAssign<T>(target, source): void

Assign the values of all of the enumerable own properties from the source object to their keys in the target object.

Type parameters

Name	Type
T	extends Object

Parameters

Name	Type
target	T
source	Partial<T>

Returns

void

Defined in

packages/vat-data/src/vat-data-bindings.js:81

---

pickFacet

▸ pickFacet<M, F>(maker, facetName): (...args: Parameters<M>) => ReturnType<M>[F]

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');

Type parameters

Name	Type
M	extends (...args: any[]) => any
F	extends string | number | symbol

Parameters

Name	Type
maker	M
facetName	F

Returns

fn

▸ (...args): ReturnType<M>[F]

Parameters

Name	Type
...args	Parameters<M>

Returns

ReturnType<M>[F]

Defined in

packages/vat-data/src/vat-data-bindings.js:67

---

prepareExo

▸ prepareExo<M>(baggage, kindName, interfaceGuard, methods, options?): Guarded<M>

Type parameters

Name	Type	Description
M	extends Record<PropertyKey, CallableFunction>	methods

Parameters

Name	Type	Default value
baggage	MapStore<string, any>	undefined
kindName	string	undefined
interfaceGuard	undefined | InterfaceGuard	undefined
methods	M	undefined
options?	DefineKindOptions<{ self: M }>	undefined

Returns

Guarded<M>

Defined in

packages/vat-data/src/exo-utils.js:336

---

prepareExoClass

▸ prepareExoClass<I, T>(baggage, kindName, interfaceGuard, init, methods, options?): (...args: Parameters<I>) => Guarded<T>

Type parameters

Name	Type	Description
I	extends (...args: any) => any	init state function
T	extends Record<PropertyKey, CallableFunction>	methods

Parameters

Name	Type	Default value
baggage	MapStore<string, any>	undefined
kindName	string	undefined
interfaceGuard	undefined | InterfaceGuard	undefined
init	I	undefined
methods	T & ThisType<{ self: T ; state: ReturnType<I> }>	undefined
options?	DefineKindOptions<{ self: T ; state: ReturnType<I> }>	undefined

Returns

fn

▸ (...args): Guarded<T>

Parameters

Name	Type
...args	Parameters<I>

Returns

Guarded<T>

Defined in

packages/vat-data/src/exo-utils.js:334

---

prepareExoClassKit

▸ prepareExoClassKit<I, T>(baggage, kindName, interfaceGuardKit, init, facets, options?): (...args: Parameters<I>) => GuardedKit<T>

Type parameters

Name	Type	Description
I	extends (...args: any) => any	init state function
T	extends Record<string, Record<PropertyKey, CallableFunction>>	facets

Parameters

Name	Type	Default value
baggage	MapStore<string, any>	undefined
kindName	string	undefined
interfaceGuardKit	undefined | InterfaceGuardKit	undefined
init	I	undefined
facets	T & ThisType<{ facets: GuardedKit<T> ; state: ReturnType<I> }>	undefined
options?	DefineKindOptions<{ facets: T ; state: ReturnType<I> }>	undefined

Returns

fn

▸ (...args): GuardedKit<T>

Parameters

Name	Type
...args	Parameters<I>

Returns

GuardedKit<T>

Defined in

packages/vat-data/src/exo-utils.js:335

---

prepareKind

▸ prepareKind<P, S, F>(baggage, tag, init, facet, options?): (...args: P) => KindFacet<F>

Type parameters

Name
P
S
F

Parameters

Name	Type
baggage	MapStore<string, any>
tag	string
init	(...args: P) => S
facet	F
options?	DefineKindOptions<KindContext<S, F>>

Returns

fn

▸ (...args): KindFacet<F>

Parameters

Name	Type
...args	P

Returns

KindFacet<F>

Defined in

packages/vat-data/src/exo-utils.js:343

---

prepareKindMulti

▸ prepareKindMulti<P, S, B>(baggage, tag, init, behavior, options?): (...args: P) => KindFacets<B>

Type parameters

Name
P
S
B

Parameters

Name	Type
baggage	MapStore<string, any>
tag	string
init	(...args: P) => S
behavior	B
options?	DefineKindOptions<MultiKindContext<S, B>>

Returns

fn

▸ (...args): KindFacets<B>

Parameters

Name	Type
...args	P

Returns

KindFacets<B>

Defined in

packages/vat-data/src/exo-utils.js:343

---

prepareSingleton

▸ prepareSingleton<M>(baggage, kindName, methods, options?): Guarded<M>

Type parameters

Name	Type	Description
M	extends Record<PropertyKey, CallableFunction>	methods

Parameters

Name	Type	Default value
baggage	MapStore<string, any>	undefined
kindName	string	undefined
methods	M	undefined
options?	DefineKindOptions<{ self: M }>	undefined

Returns

Guarded<M>

Deprecated

Use prepareExo instead.

Defined in

packages/vat-data/src/exo-utils.js:337

---

provide

▸ provide<K, V>(baggage, key, makeValue): V

Unlike provideLazy, provide should be called at most once within any vat incarnation with a given baggage,key pair.

provide should only to be used to populate baggage, where the total number of calls to provide must be low cardinality, since we keep the bookkeeping to detect collisions in normal language-heap memory. All the other baggage-oriented provide* and prepare* functions call provide, and so impose the same constraints. This is consistent with our expected durability patterns: What we store in baggage are

• kindHandles, which are per kind, which must be low cardinality
• data "variables" for reestablishing the lexical scope, especially of singletons
• named non-baggage collections at the leaves of the baggage tree.

What is expected to be high cardinality are the instances of the kinds, and the members of the non-bagggage collections.

TODO https://github.com/Agoric/agoric-sdk/pull/5875 : Implement development-time instrumentation to detect when provide violates the above prescription, and is called more than once in the same vat incarnation with the same baggage,key pair.

Type parameters

Name
K
V

Parameters

Name	Type
baggage	MapStore<string, any>
key	K
makeValue	(key: K) => V

Returns

V

Defined in

packages/vat-data/src/vat-data-bindings.js:141

---

provideDurableMapStore

▸ provideDurableMapStore(baggage, name, options?): MapStore<K, V>

Parameters

Name	Type
baggage	MapStore<string, any>
name	string
options	Omit<StoreOptions, "durable">

Returns

MapStore<K, V>

Defined in

packages/vat-data/src/vat-data-bindings.js:213

---

provideDurableSetStore

▸ provideDurableSetStore(baggage, name, options?): SetStore<K>

Parameters

Name	Type
baggage	MapStore<string, any>
name	string
options	Omit<StoreOptions, "durable">

Returns

SetStore<K>

Defined in

packages/vat-data/src/vat-data-bindings.js:215

---

provideDurableWeakMapStore

▸ provideDurableWeakMapStore(baggage, name, options?): WeakMapStore<K, V>

Parameters

Name	Type
baggage	MapStore<string, any>
name	string
options	Omit<StoreOptions, "durable">

Returns

WeakMapStore<K, V>

Defined in

packages/vat-data/src/vat-data-bindings.js:214

---

provideDurableWeakSetStore

▸ provideDurableWeakSetStore(baggage, name, options?): WeakSetStore<K>

Parameters

Name	Type
baggage	MapStore<string, any>
name	string
options	Omit<StoreOptions, "durable">

Returns

WeakSetStore<K>

Defined in

packages/vat-data/src/vat-data-bindings.js:216

---

provideKindHandle

▸ provideKindHandle(baggage, kindName): DurableKindHandleClass

Parameters

Name	Type
baggage	MapStore<string, any>
kindName	string

Returns

DurableKindHandleClass

Deprecated

Use Exos/ExoClasses instead of Kinds

Defined in

packages/vat-data/src/exo-utils.js:343

---

providePromiseWatcher

▸ providePromiseWatcher<V, A>(kindHandle, fulfillHandler?, rejectHandler?): PromiseWatcher<V, A>

Type parameters

Name	Type
V	V
A	extends any[]

Parameters

Name	Type
kindHandle	DurableKindHandleClass
fulfillHandler	(value: V, ...args: A) => void
rejectHandler	(reason: any, ...args: A) => void

Returns

PromiseWatcher<V, A>

Defined in

packages/vat-data/src/vat-data-bindings.js:47

---

watchPromise

▸ watchPromise<P, A>(p, watcher, ...args): void

Type parameters

Name	Type
P	extends Promise<any>
A	extends any[]

Parameters

Name	Type
p	P
watcher	PromiseWatcher<Awaited<P>, A>
...args	A

Returns

void

Defined in

packages/vat-data/src/vat-data-bindings.js:48