API documentation of Agoric SDK / Exports / @agoric/notifier
Module: @agoric/notifier
Table of contents
Interfaces
Type Aliases
Variables
Functions
- forEachPublicationRecord
- makeAsyncIterableFromNotifier
- makeNotifier
- makeNotifierFromAsyncIterable
- makeNotifierFromSubscriber
- makeNotifierKit
- makePinnedHistoryTopic
- makePublishKit
- makeStoredNotifier
- makeStoredPublishKit
- makeStoredPublisherKit
- makeStoredSubscriber
- makeStoredSubscription
- makeSubscription
- makeSubscriptionKit
- observeIteration
- observeIterator
- observeNotifier
- prepareDurablePublishKit
- subscribeEach
- subscribeLatest
Type Aliases
StoredNotifier
Ƭ StoredNotifier<T>: BaseNotifier<T> & Omit<StoredFacet, "getStoreKey">
Type parameters
| Name |
|---|
T |
Defined in
packages/notifier/src/stored-notifier.js:10
Variables
ForkableAsyncIterableIteratorShape
• Const ForkableAsyncIterableIteratorShape: InterfaceGuard<{ [asyncIterator]: MethodGuard ; fork: MethodGuard ; next: MethodGuard }>
Defined in
packages/notifier/src/publish-kit.js:39
IterableEachTopicI
• Const IterableEachTopicI: InterfaceGuard<{ [asyncIterator]: MethodGuard ; subscribeAfter: MethodGuard }>
Defined in
packages/notifier/src/publish-kit.js:48
IterableLatestTopicI
• Const IterableLatestTopicI: InterfaceGuard<{ [asyncIterator]: MethodGuard ; getUpdateSince: MethodGuard }>
Defined in
packages/notifier/src/publish-kit.js:56
SubscriberShape
• Const SubscriberShape: Matcher
Defined in
packages/notifier/src/publish-kit.js:480
Functions
forEachPublicationRecord
▸ forEachPublicationRecord<T>(subscriber, consumeValue): Promise<void>
NB: does not yet survive upgrade https://github.com/Agoric/agoric-sdk/issues/6893
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
subscriber | Subscriber<T> |
consumeValue | (v: T) => void |
Returns
Promise<void>
Defined in
packages/notifier/src/storesub.js:18
makeAsyncIterableFromNotifier
▸ makeAsyncIterableFromNotifier<T>(topic): { [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> } & RemotableBrand<{}, { [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> }>
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
topic | ERef<LatestTopic<T>> |
Returns
{ [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> } & RemotableBrand<{}, { [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> }>
Deprecated
Use subscribeLatest from @agoric/notifier/subscribe.js instead.
Adaptor from a notifierP to an async iterable. The notifierP can be any object that has an eventually invocable getUpdateSince method that behaves according to the notifier spec. This can be a notifier, a promise for a local or remote notifier, or a presence of a remote notifier.
It is also used internally by notifier.js so that a notifier itself is an async iterable.
An async iterable is an object with a [Symbol.asyncIterator]() method that returns an async iterator. The async iterator we return here has only a next() method, without the optional return and throw methods. The omitted methods, if present, would be used by the for/await/of loop to inform the iterator of early termination. But this adaptor would not do anything useful in reaction to this notification.
An async iterator's next() method returns a promise for an iteration result. An iteration result is a record with value and done properties.
The purpose of building on the notifier protocol is to have a lossy adaptor, where intermediate results can be missed in favor of more recent results which are therefore less stale. See https://github.com/Agoric/documentation/blob/HEAD/main/guides/js-programming/notifiers.md
Defined in
packages/notifier/src/asyncIterableAdaptor.js:39
makeNotifier
▸ makeNotifier<T>(sharableInternalsP): Notifier<T>
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
sharableInternalsP | ERef<LatestTopic<T>> |
Returns
Notifier<T>
Defined in
packages/notifier/src/notifier.js:15
makeNotifierFromAsyncIterable
▸ makeNotifierFromAsyncIterable<T>(asyncIterableP): Notifier<T>
Adaptor from async iterable to notifier.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
asyncIterableP | ERef<AsyncIterable<T>> |
Returns
Notifier<T>
Deprecated
The resulting notifier is lossless, which is not desirable. Prefer makeNotifierFromSubscriber, and refer to https://github.com/Agoric/agoric-sdk/issues/5413 and https://github.com/Agoric/agoric-sdk/pull/5695 for context.
Defined in
packages/notifier/src/notifier.js:113
makeNotifierFromSubscriber
▸ makeNotifierFromSubscriber<T>(subscriber): Notifier<T>
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
subscriber | ERef<Subscriber<T>> |
Returns
Notifier<T>
Defined in
packages/notifier/src/notifier.js:44
makeNotifierKit
▸ makeNotifierKit<T>(...initialStateArr): NotifierRecord<T>
Produces a pair of objects, which allow a service to produce a stream of update promises.
The initial state argument has to be truly optional even though it can be any first class value including undefined. We need to distinguish the presence vs the absence of it, which we cannot do with the optional argument syntax. Rather we use the arity of the initialStateArr array.
If no initial state is provided to makeNotifierKit, then it starts without an initial state. Its initial state will instead be the state of the first update.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type | Description |
|---|---|---|
...initialStateArr | [] | [T] | the first state to be returned (typed as rest array to permit undefined) |
Returns
NotifierRecord<T>
the notifier and updater
Defined in
packages/notifier/src/notifier.js:79
makePinnedHistoryTopic
▸ makePinnedHistoryTopic<T>(topic): EachTopic<T> & LatestTopic<T>
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type | Description |
|---|---|---|
topic | EachTopic<T> & LatestTopic<T> | needs to be near in order to preserve subscription timings. TODO: drop LatestTopic<T> requirement |
Returns
EachTopic<T> & LatestTopic<T>
Deprecated
A pinned-history topic preserves all of its published values in memory. Use a prefix-lossy makePublishKit instead.
Defined in
packages/notifier/src/topic.js:15
makePublishKit
▸ makePublishKit<T>(): PublishKit<T>
Makes a { publisher, subscriber } pair for doing efficient distributed pub/sub supporting both "each" and "latest" iteration of published values.
Type parameters
| Name |
|---|
T |
Returns
PublishKit<T>
Defined in
packages/notifier/src/publish-kit.js:109
makeStoredNotifier
▸ makeStoredNotifier<T>(notifier, storageNode, marshaller): StoredNotifier<T>
Begin iterating the source, storing serialized iteration values. If the storageNode's setValue operation rejects, no further writes to it will be attempted (but results will remain available from the subscriber).
Returns a StoredNotifier that can be used by a client to directly follow the iteration themselves, or obtain information to subscribe to the stored data out-of-band.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
notifier | ERef<Notifier<T>> |
storageNode | ERef<StorageNode> |
marshaller | ERef<Marshaller<unknown>> |
Returns
Defined in
packages/notifier/src/stored-notifier.js:28
makeStoredPublishKit
▸ makeStoredPublishKit<T>(storageNode, marshaller): StoredPublishKit<T>
Type parameters
| Name | Type |
|---|---|
T | unknown |
Parameters
| Name | Type |
|---|---|
storageNode | ERef<StorageNode> |
marshaller | ERef<Marshaller<unknown>> |
Returns
StoredPublishKit<T>
Deprecated
incompatible with durability; instead handle vstorage ephemerally on a durable PublishKit
Like makePublishKit this makes a { publisher, subscriber } pair for doing efficient distributed pub/sub supporting both "each" and "latest" iteration of published values.
What's different is subscriber tees records, writing out to storageNode.
Defined in
packages/notifier/src/storesub.js:213
makeStoredPublisherKit
▸ makeStoredPublisherKit<T>(storageNode?, marshaller?, childPath?): StoredPublisherKit<T>
Type parameters
| Name | Type |
|---|---|
T | unknown |
Parameters
| Name | Type |
|---|---|
storageNode? | ERef<StorageNode> |
marshaller? | ERef<Marshaller<unknown>> |
childPath? | string |
Returns
Deprecated
incompatible with durability; instead handle vstorage ephemerally on a durable PublishKit
Defined in
packages/notifier/src/storesub.js:179
makeStoredSubscriber
▸ makeStoredSubscriber<T>(subscriber, storageNode, marshaller): StoredSubscriber<T>
Begin iterating the source, storing serialized iteration values. If the storageNode's setValue operation rejects, no further writes to it will be attempted (but results will remain available from the subscriber).
Returns a StoredSubscriber that can be used by a client to directly follow the iteration themselves, or obtain information to subscribe to the stored data out-of-band.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
subscriber | Subscriber<T> |
storageNode | ERef<StorageNode> |
marshaller | ERef<{ fromCapData: FromCapData<unknown> ; serialize: ToCapData<unknown> ; toCapData: ToCapData<unknown> ; unserialize: FromCapData<unknown> }> |
Returns
StoredSubscriber<T>
Defined in
packages/notifier/src/storesub.js:47
makeStoredSubscription
▸ makeStoredSubscription<T>(subscription, storageNode?, marshaller?): StoredSubscription<T>
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
subscription | Subscription<T> |
storageNode? | ERef<StorageNode> |
marshaller? | ERef<{ fromCapData: FromCapData<unknown> ; serialize: ToCapData<unknown> ; toCapData: ToCapData<unknown> ; unserialize: FromCapData<unknown> }> |
Returns
StoredSubscription<T>
Deprecated
use makeStoredSubscriber
Begin iterating the source, storing serialized iteration values. If the storageNode's setValue operation rejects, the iteration will be terminated.
Returns a StoredSubscription that can be used by a client to directly follow the iteration themselves, or obtain information to subscribe to the stored data out-of-band.
Defined in
packages/notifier/src/storesub.js:92
makeSubscription
▸ makeSubscription<T>(topic): Subscription<T>
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
topic | ERef<EachTopic<T>> |
Returns
Subscription<T>
Defined in
packages/notifier/src/subscriber.js:18
makeSubscriptionKit
▸ makeSubscriptionKit<T>(): SubscriptionRecord<T>
Type parameters
| Name |
|---|
T |
Returns
SubscriptionRecord<T>
Deprecated
Producers should use
const { publisher, subscriber } = makePublishKit();
const topic = makePinnedHistoryTopic(subscriber);instead, which makes it clearer that all the subscriber's history is retained, preventing GC. Potentially remote consumers use
for await (const value of subscribeEach(topic)) { ... }Makes a { publication, subscription } for doing lossless efficient distributed pub/sub.
Defined in
packages/notifier/src/subscriber.js:56
observeIteration
▸ observeIteration<T>(asyncIterableP, iterationObserver): Promise<undefined>
This reads from asyncIterableP updating iterationObserver with each successive value. The iterationObserver may only be interested in certain occurrences (updateState, finish, fail), so for convenience, observeIteration feature tests for those methods before calling them.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
asyncIterableP | ERef<AsyncIterable<T>> |
iterationObserver | Partial<IterationObserver<T>> |
Returns
Promise<undefined>
Defined in
packages/notifier/src/asyncIterableAdaptor.js:88
observeIterator
▸ observeIterator<T>(asyncIteratorP, iterationObserver): Promise<undefined>
This advances asyncIteratorP updating iterationObserver with each successive value. The iterationObserver may only be interested in certain occurrences (updateState, finish, fail), so for convenience, observeIterator feature tests for those methods before calling them.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
asyncIteratorP | ERef<AsyncIterator<T, any, undefined>> |
iterationObserver | Partial<IterationObserver<T>> |
Returns
Promise<undefined>
Defined in
packages/notifier/src/asyncIterableAdaptor.js:52
observeNotifier
▸ observeNotifier<T>(notifierP, iterationObserver): Promise<undefined>
As updates come in from the possibly remote notifierP, update the local updater. Since the updates come from a notifier, they are lossy, i.e., once a more recent state can be reported, less recent states are assumed irrelevant and dropped.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
notifierP | ERef<LatestTopic<T>> |
iterationObserver | Partial<IterationObserver<T>> |
Returns
Promise<undefined>
Defined in
packages/notifier/src/asyncIterableAdaptor.js:104
prepareDurablePublishKit
▸ prepareDurablePublishKit(baggage, kindName): (...args: [options: Object]) => GuardedKit<{ publisher: { fail: (reason: any) => void ; finish: (finalValue: any) => void ; publish: (value: any) => void } ; subscriber: { getUpdateSince: (updateCount: any) => any ; subscribeAfter: (publishCount: bigint) => Promise<any> } }>
Parameters
| Name | Type |
|---|---|
baggage | MapStore<string, any> |
kindName | string |
Returns
fn
▸ (...args): GuardedKit<{ publisher: { fail: (reason: any) => void ; finish: (finalValue: any) => void ; publish: (value: any) => void } ; subscriber: { getUpdateSince: (updateCount: any) => any ; subscribeAfter: (publishCount: bigint) => Promise<any> } }>
Parameters
| Name | Type |
|---|---|
...args | [options: Object] |
Returns
GuardedKit<{ publisher: { fail: (reason: any) => void ; finish: (finalValue: any) => void ; publish: (value: any) => void } ; subscriber: { getUpdateSince: (updateCount: any) => any ; subscribeAfter: (publishCount: bigint) => Promise<any> } }>
Defined in
packages/notifier/src/publish-kit.js:404
subscribeEach
▸ subscribeEach<T>(topic): { [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> } & RemotableBrand<{}, { [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> }>
Given a local or remote subscriber, returns a local AsyncIterable which provides "prefix lossy" iterations of the underlying PublicationList. By "prefix lossy", we mean that you may miss everything published before you ask the returned iterable for an iterator. But the returned iterator will enumerate each thing published from that iterator's starting point up to a disconnection result indicating upgrade of the producer (which breaks the gap-free guarantee and therefore terminates any active iterator while still supporting creation of new iterators).
If the underlying PublicationList is terminated, that terminal value will be reported losslessly.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
topic | ERef<EachTopic<T>> |
Returns
{ [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> } & RemotableBrand<{}, { [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> }>
Defined in
packages/notifier/src/subscribe.js:148
subscribeLatest
▸ subscribeLatest<T>(topic): { [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> } & RemotableBrand<{}, { [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> }>
Given a local or remote subscriber, returns a local AsyncIterable which provides "lossy" iterations of the underlying PublicationList. By "lossy", we mean that you may miss any published state if a more recent published state can be reported instead.
If the underlying PublicationList is terminated by upgrade of the producer, it will be re-requested. All other terminal values will be losslessly propagated.
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
topic | ERef<LatestTopic<T>> |
Returns
{ [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> } & RemotableBrand<{}, { [asyncIterator]: () => ForkableAsyncIterableIterator<T, T, undefined> }>