This is a JavaScript and TypeScript SDK for building ActyxOS apps. Currently, it wraps the ActyxOS Event Service and Console Service APIs in a simple client that can be used from within JavaScript and TypeScript apps.
For more information about ActyxOS, please check out our developer documentation at https://developer.actyx.com/.
import { Client, Subscription } from '@actyx/os-sdk'
const ActyxOS = Client()
// callback style
ActyxOS.eventService.subscribe({
subscriptions: Subscription.everything(),
onEvent: event => {
console.log('got event', event)
}
})
// stream style
const eventStream = ActyxOS.eventService.subscribeStream({
subscriptions: Subscription.everything(),
})
for await (const event of eventStream) {
console.log('got event', event)
}import { Client, EventDraft } from '@actyx/os-sdk'
const ActyxOS = Client()
// callback style
ActyxOS.eventService.publish({
eventDrafts: EventDraft.make('mySemantics', 'myName', { foo: 'bar' }),
onDone: () => {
console.log(`Published`)
}
})
// promise style
await ActyxOS.eventService.publishPromise({
eventDrafts: EventDraft.make('mySemantics', 'myName', { foo: 'bar' }),
})For simple logging needs, use the SimpleLogger which you can configure once
and then use to log messages and, optionally, additional data:
import { Client } from '@actyx/os-sdk'
const ActyxOS = Client()
const logger: SimpleLogger = ActyxOS.consoleService.SimpleLogger({
logName: 'myLogger',
producerName: 'com.example.app1',
producerVersion: '1.0.0'
})
logger.debug('this is a DEBUG message')
logger.warn('this is a WARNING message')
logger.info('this is an INFO message')
logger.error('this is an ERROR message')
logger.debug('This is a message with additional data', {foo: 'bar'})For more advanced, custom logging needs, use the log function directly:
import { Client } from '@actyx/os-sdk'
const ActyxOS = Client()
ActyxOS.consoleService.log({
entry: {
logName: 'myCustomLogger',
message: 'this is a WARNING message',
severity: LogSeverity.WARN,
producer: {
name: 'com.example.app1',
version: '1.0.0'
},
additionalData: {
foo: 'bar',
bar: {
foo: true,
}
},
labels: {
'com.example.app1.auth.username': 'john.doe',
'com.example.app1.model.events': '10000',
}
},
// Callback on successful logging
onLogged: () => {
// Do something
},
// Callback on error logging
onError: err => {
console.error(`error logging: ${err}`)
}
})There also is a corresponding version that returns a Promise:
import { Client } from '@actyx/os-sdk'
const ActyxOS = Client()
await ActyxOS.consoleService.logPromise({ /* log entry */ })Install via npm using
npm install @actyx/os-sdkYou can access the Typedoc documentation at https://developer.actyx.com/@actyx/os-sdk/.
If you have questions about or issues with the ActyxOS SDK, join our Discord chat or email us at developer@actyx.io.
You can override the default client options by passing options (ApiClientOpts) when creating the client. If you only want to override specific options, use the default options (DefaultClientOpts) as shown in the following example:
import { Client, DefaultClientOpts } from '@actyx/os-sdk'
const clientOpts = DefaultClientOpts()
clientOpts.Endpoints.EventService.BaseUrl = 'http://10.2.3.23:4454/api'
const CustomActyxOS = Client(clientOpts)npm run buildnpm run testRUN_INTEGRATION_TESTS=1 npm run testnpm run lint and npm run lint:fixnpm publishAdditional data you would like to add to the log entry. Note: this is data that complements the log message (e.g. additional parsing errors).
Any labels you would like to add to the log entry.
Note that labels are always of type string: string.
Name of the log you want to post the entry to.
The actual log message.
Details about who produced the log message. This should be your app's name and version number.
Severity of the log entry (debug, warn, info or error).
Timestamp of the log entry.
Note: ActyxOS automatically adds this, so you should almost never have to set this yourself.
Configuration of a request to post a log entry to the ActyxOS Console Service. Please refer to the individual properties for more information about what each of them do.
This property defines the draft log entry you want to post to the Console Service. The log entry has a number of required and a number of optional properties. Please refer to LogEntryDraft for more information and a couple of examples.
This property allows you to provide a callback that will be called if an error occurs whilst the SDK tried to post the log entry.
Note: this should not happen unless there are problems with the ActyxOS node so if anything you might throw an exception here.
This property allows you to provide a callback that will be called when the log entry has been successfully posted.
Note: in most cases you can simply fire-and-forget and thus don't need to provide this callback.
Configuration of a request for offsets to the ActyxOS Event Service. Please refer to the individual properties for more information about what each of them do.
This is a callback function type that is used for notifying users that an operation has completed. This type of callback is used for operations that return results via other means (e.g. OnEvent).
This is a callback function type that is used for notifying users that an error has occured.
This is a callback function type that is used for subscribing to event streams or querying the ActyxOS Event Service (see SubscribeOpts or QueryOpts).
This is a callback function type that is used for return the result of an asynchronous operation to the user.
the type of the result that will be provided to the callback.
Configuration of a publishing request to the ActyxOS Event Service. Please refer to the individual properties for more information about what each of them do.
The event drafts to be published (and thus turned into events).
This is a callback that will be called after the event(s) have been successfully published.
This is a callback that will be called if any errors occur during the publication process.
Configuration of a publishing request to the ActyxOS Event Service. Please refer to the individual properties for more information about what each of them do.
Configuration of a query to the ActyxOS Event Service. Please refer to the individual properties for more information about what each of them do.
You can provide an OffsetMap specifying the lower bound of your query. Please refer to the ActyxOS Event Service documentation for more information about how the API handles lower and upper bounds.
Note: not providing a lower bound means that you will receive all events known to the ActyxOS node's since it was first created.
This is a callback that will be called after the query has ended.
This is a callback that will be called if an error occurs during the query.
Note that a query is immediately destroyed if an error occurs.
This is a callback that will be called for each event returned by the query.
The order in which you want the query to return results. Please refer to the ActyxOS Event Service API documentation for more details.
This property defines the stream subscriptions to be made as part of this query. You can query not only one ActyxOS event stream, but many streams at the same time. You can do this by providing multiple subscriptions at a time and by using constructors defined in Subscription.
Here are a couple of examples.
Create a subscription to everything
const subscription = Subscription.everything()Create a subscription for all events with a certain semantic
const subscription = Subscription.wildcard('temperatureValue')Create a subscription for all events related to a distributed state
const subscription = Subscription.distributed('machineState', 'machine1')Creating multiple subscriptions
const subscriptions = [
Subscription.wildcard('temperatureValue')
Subscription.distributed('machineState', 'machine1'),
]You must provide an OffsetMap specifying the upper bound of your subscription. Please refer to the ActyxOS Event Service documentation for more information about how the API handles lower and upper bounds.
Configuration parameters for creating a SimpleLogger. You must specify
the producer name and version (e.g. myapp and 1.0.0) and a name for the
log you want to post to (e.g. myLogger). You may also add a default error
callback that will be called whenever an error occurs whilst trying to post
a log entry.
Configuration of a subscription to the ActyxOS Event Service. Please refer to the individual properties for more information about what each of them do.
You can provide an OffsetMap specifying the lower bound of your subscription. Please refer to the ActyxOS Event Service documentation for more information about how the API handles lower and upper bounds.
This is a callback that will be called after the subscription has ended. Since subscriptions don't naturally end, this only happens if the subscription is aborted using the provided callback (see EventServiceClient.subscribe).
This is a callback that will be called if an error occurs during the subscription.
Note that a subscription is immediately destroyed if an error occurs.
This is a callback that will be called for each event returned by the subscription.
This property defines the stream subscriptions to be made as part of this subscription. You can subscribe to not only one ActyxOS event stream, but to many streams at the same time. You can do this by providing multiple subscriptions at a time and by using constructors defined in Subscription.
Here are a couple of examples.
Create a subscription to everything
const subscription = Subscription.everything()Create a subscription for all events with a certain semantic
const subscription = Subscription.wildcard('temperatureValue')Create a subscription for all events related to a distributed state
const subscription = Subscription.distributed('machineState', 'machine1')Creating multiple subscriptions
const subscriptions = [
Subscription.wildcard('temperatureValue')
Subscription.distributed('machineState', 'machine1'),
]Describes a subscription
This function allows you to create a client. In almost all cases you do not need to provide options since the defaults will work.
Example
import { Client } from '@actyx/os-sdk'
const ActyxOS = Client()In the rare case that you might in fact have to override clients options you could do so as follows:
import { DefaultClientOpts } from '@actyx/os-sdk'
const customClient = Client({
...DefaultClientOpts,
Ports: {
EventService: 5555
}
})This function returns the default client options
Helper function for creating an EventDraft using the provided semantics, name and payload.
Semantics of the stream the event should be published to
Name of the stream the event should be published to
The event payload.
An event draft that can be passed to the EventServiceClient's publish function.
This object provides useful constructors for creating subscription definitions.
This creates a subscription to all events with the specified semantics and the specified name.
This creates a subscription to all events known to the ActyxOS Event Service.
This creates a subscription to all events with the specified semantics and the specified name, and from the specified source.
This creates a subscription to all events with the specified semantics.
Generated using TypeDoc
This data type specifies the content of a log entry that must/can be provided by your application. This is not exactly equivalent to the actual log entry stored by ActyxOS since the Console Service automatically adds additional data points such as the node's ID or display name. The Console Service also adds the timestamp unless you have specifically provided it.
Have a look at the Console Service's API documentation for more details, including how ActyxOS stores log entries internally.
The most basic LogEntryDraft would look as follows:
const minimalEntry: LogEntryDraft = { logName: 'myLogger', severity: LogSeverity.INFO, producer: { name: 'myapp', version: '1.0.0', }, message: 'my log message', }