Skip to main content

Interface: EventServiceClient#

This interface specifies the functionality that this SDK offers for interacting with the ActyxOS Event Service.

Properties#

offsets#

offsets: (opts: OffsetsOpts) => void

This function allows you to get all known offsets from the ActyxOS Event Service. Please refer to the OffsetsOpts docs for more details about how to configure your call to this function.

Example usage

client.eventService.offsets({
// This callback will be called when the API has returned the offsets
onOffsets: offsets => {
console.log(`Got offsets: ${JSON.stringify(offsets, null, 2)}`)
},
// This callback will be called if an error occurs whilst trying to get
// the offsets
onError: error => {
console.error(`error getting offsets: ${error}`)
},
})

param Options for the publish (see PublishOpts).

Type declaration:#

▸ (opts: OffsetsOpts): void

Parameters:#

NameType
optsOffsetsOpts

Returns: void


offsetsPromise#

offsetsPromise: () => Promise<OffsetMap>

This function allows you to get all known offsets from the ActyxOS Event Service. Please refer to the OffsetsOpts docs for more details about how to configure your call to this function.

Example usage

const offsets = await client.eventService.offsetsPromise()
// now use them e.g. for a .queryStream() as upperBound

returns A promise that will be fulfilled with the currently known offsets.

Type declaration:#

▸ (): Promise<OffsetMap>

Returns: Promise<OffsetMap>


publish#

publish: (opts: PublishOpts) => void

This function allows you to publish events using the ActyxOS Event Service. Please refer to the PublishOpts docs for more details about how to configure your call to this function.

Example usage

client.eventService.publish({
// Pass in one or more event drafts that you want to publish
eventDrafts: EventDraft.make('testSemantics', 'testName', { foo: 'bar' }),
// This is callback that will be called when the provided event draft(s)
// have been published to the Event Service
onDone: () => {
console.log(`Published`)
},
// This function will be called if an error occurs during the publishing
// operation
onError: error => {
console.error(`error publishing: ${error}`)
},
})

param Options for the publish (see PublishOpts).

Type declaration:#

▸ (opts: PublishOpts): void

Parameters:#

NameType
optsPublishOpts

Returns: void


publishPromise#

publishPromise: (opts: PublishPromiseOpts) => Promise<void>

This function allows you to publish events using the ActyxOS Event Service. Please refer to the PublishOpts docs for more details about how to configure your call to this function.

Example usage

await client.eventService.publishPromise({
// Pass in one or more event drafts that you want to publish
eventDrafts: EventDraft.make('testSemantics', 'testName', { foo: 'bar' }),
})

param Options for the publish (see PublishOpts).

Type declaration:#

▸ (opts: PublishPromiseOpts): Promise<void>

Parameters:#

NameType
optsPublishPromiseOpts

Returns: Promise<void>


query#

query: (opts: QueryOpts) => void

This function allows you to query the ActyxOS Event Service. As opposed to subscriptions, a query will always end. Please refer to the QueryOpts docs for more details about how to configure your query.

Example usage

client.eventService.query({
// Define an upper bound for the query
upperBound: toOffsets,
// Order the events using their lamport timestamp
ordering: Ordering.Lamport,
// Specify the streams you would like to query by their semantics and
// name
subscriptions: Subscription.distributed('machineState', 'machine1'),
// This is the callback that will be called for every event that the query
// returns
onEvent: event => {
console.log(`query returned event: ${JSON.stringify(event)}`)
},
// This callback will be called when the query end, i.e. when the last
// event that it returned has been passed to the [OnEvent](../modules.md#onevent) callback
onDone: () => {
console.log('query completed')
},
// This callback will be called if there is any error in the executing
// the query
onError: error => {
console.error(`error querying: ${error}`)
},
})

param Options for the query (see QueryOpts).

Type declaration:#

▸ (opts: QueryOpts): void

Parameters:#

NameType
optsQueryOpts

Returns: void


queryStream#

queryStream: (opts: QueryStreamOpts) => Promise<EventStream>

This function allows you to query the ActyxOS Event Service. As opposed to subscriptions, a query will always end. Please refer to the QueryOpts docs for more details about how to configure your query.

Example usage

const subscription = await client.eventService.queryStream({
// Specify a lower bound of offsets; we will not get events below that
// offset
lowerBound: offsets,
// Define an upper bound for the query
upperBound: toOffsets,
// Order the events using their lamport timestamp
ordering: Ordering.Lamport,
// Define a subscription to all events in all event streams
subscriptions: Subscription.everything(),
})
for await (const event of subscription) {
console.log('Event:')
console.log(JSON.stringify(event, null, 2))
// in case you don’t need further events:
if (isDone(event)) {
break
// this will also terminate the subscription and release resources
}
}

If you want to stop the subscription based on an external event, you can do so by using the .cancel() method of the returned subscription:

const subscription = await client.eventService.queryStream(opts)
// Later
subscription.cancel()

This is not needed when using for await (...) and breaking or finishing the loop, in which case the loop itself will handle stream cancellation.

param Options for the query (see QueryStreamOpts).

returns An async iterable that also contains a callback for terminating the stream if you need to do that unrelated to the for-await-loop.

Type declaration:#

▸ (opts: QueryStreamOpts): Promise<EventStream>

Parameters:#

NameType
optsQueryStreamOpts

Returns: Promise<EventStream>


subscribe#

subscribe: (opts: SubscribeOpts) => () => void

This function allows you to perform a subscription to the ActyxOS Event Service. Please refer to the SubscribeOpts docs for more details about how to configure your subscription.

Example usage

const stopSubscription = client.eventService.subscribe({
// Specify a lower bound of offsets; we will not get events below that
// offset
lowerBound: offsets,
// Define a subscription to all events in all event streams
subscriptions: Subscription.everything(),
// Provide a callback that will be called for every event that is
// returned by the subscription
onEvent: event => {
console.log('Event:')
console.log(JSON.stringify(event, null, 2))
},
// This callback will be called if you manually abort the subscription
// using the function returned by this function
onDone: () => {
console.log(`Subscription done!`)
},
// This callback will be called if any error occurs during the execution
// of the subscription
onError: error => {
console.error(`error during subscription: ${error}`)
},
})

If you want to stop the subscription at some point, you could do so by using the function returned by this function:

const stopSubscription = client.eventService.subscribe(opts)
// Later
stopSubscription()

param Options for the subscription (see SubscribeOpts).

returns Callback for aborting the subscription. Calling the returned function will stop the subscription. If you have provided an OnDone callback in the SubscribeOpts, it will be called when the subscription ends.

Type declaration:#

▸ (opts: SubscribeOpts): function

Parameters:#

NameType
optsSubscribeOpts

Returns: () => void


subscribeStream#

subscribeStream: (opts: SubscribeStreamOpts) => Promise<EventStream>

This function allows you to perform a subscription to the ActyxOS Event Service. Please refer to the SubscribeStreamOpts docs for more details about how to configure your subscription.

Example usage

const subscription = await client.eventService.subscribeStream({
// Specify a lower bound of offsets; we will not get events below that
// offset
lowerBound: offsets,
// Define a subscription to all events in all event streams
subscriptions: Subscription.everything(),
})
for await (const event of subscription) {
console.log('Event:')
console.log(JSON.stringify(event, null, 2))
// in case you don’t need further events:
if (isDone(event)) {
break
// this will also terminate the subscription and release resources
}
}

If you want to stop the subscription based on an external event, you can do so by using the .cancel() method of the returned subscription:

const subscription = await client.eventService.subscribeStream(opts)
// Later
subscription.cancel()

This is not needed when using for await (...) and breaking or finishing the loop, in which case the loop itself will handle stream cancellation.

param Options for the subscription (see SubscribeStreamOpts).

returns An async iterable that also contains a callback for terminating the stream if you need to do that unrelated to the for-await-loop.

Type declaration:#

▸ (opts: SubscribeStreamOpts): Promise<EventStream>

Parameters:#

NameType
optsSubscribeStreamOpts

Returns: Promise<EventStream>