Options
All
  • Public
  • Public/Protected
  • All
Menu

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.

ActyxOS

For more information about ActyxOS, please check out our developer documentation at https://developer.actyx.com/.

Examples

Event Service

Subscribe to event streams

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)
}

Publish events

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' }),
})

Console Service

Simple logging

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

Advanced (custom) logging

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 */ })

Usage

Installation

Install via npm using

npm install @actyx/os-sdk

Documentation

You can access the Typedoc documentation at https://developer.actyx.com/@actyx/os-sdk/.

Getting help

If you have questions about or issues with the ActyxOS SDK, join our Discord chat or email us at developer@actyx.io.

Advanced

Overriding the default client options

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)

Development

  • Build with npm run build
  • Run tests with npm run test
  • Run test including integration tests with RUN_INTEGRATION_TESTS=1 npm run test
  • Run lint / lint fix with npm run lint and npm run lint:fix
  • Publish with npm publish

Index

Type aliases

LogEntryDraft

LogEntryDraft: { additionalData?: unknown; labels?: undefined | {}; logName: string; message: string; producer: { name: string; version: string }; severity: LogSeverity; timestamp?: Date }

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',
}

Type declaration

  • Optional additionalData?: unknown

    Additional data you would like to add to the log entry. Note: this is data that complements the log message (e.g. additional parsing errors).

  • Optional labels?: undefined | {}

    Any labels you would like to add to the log entry.

    Note that labels are always of type string: string.

  • logName: string

    Name of the log you want to post the entry to.

  • message: string

    The actual log message.

  • producer: { name: string; version: string }

    Details about who produced the log message. This should be your app's name and version number.

    • name: string
    • version: string
  • severity: LogSeverity

    Severity of the log entry (debug, warn, info or error).

  • Optional timestamp?: Date

    Timestamp of the log entry.

    Note: ActyxOS automatically adds this, so you should almost never have to set this yourself.

LogOpts

LogOpts: { entry: LogEntryDraft; onError?: OnError; onLogged?: OnResult<void> }

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.

Type declaration

  • entry: LogEntryDraft

    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.

  • Optional onError?: OnError

    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.

  • Optional onLogged?: OnResult<void>

    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.

OffsetsOpts

OffsetsOpts: { onError?: OnError; onOffsets: OnResult<OffsetMap> }

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.

Type declaration

  • Optional onError?: OnError

    This is a callback that will be called if any errors occur whilst getting offsets from the Event Service.

  • onOffsets: OnResult<OffsetMap>

    This is a callback that will be called with the offsets once they have been received from the Event Service.

OnDone

OnDone: () => void

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).

Type declaration

    • (): void
    • Returns void

OnError

OnError: (error: string) => void

This is a callback function type that is used for notifying users that an error has occured.

Type declaration

    • (error: string): void
    • Parameters

      • error: string

      Returns void

OnEvent

OnEvent: (event: Event) => void

This is a callback function type that is used for subscribing to event streams or querying the ActyxOS Event Service (see SubscribeOpts or QueryOpts).

Type declaration

    • Parameters

      Returns void

OnResult

OnResult<T>: (result: T) => void

This is a callback function type that is used for return the result of an asynchronous operation to the user.

Type parameters

  • T

    the type of the result that will be provided to the callback.

Type declaration

    • (result: T): void
    • Parameters

      • result: T

      Returns void

PublishOpts

PublishOpts: { eventDrafts: EventDraft | EventDraft[]; onDone?: OnDone; onError?: OnError }

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.

Type declaration

  • eventDrafts: EventDraft | EventDraft[]

    The event drafts to be published (and thus turned into events).

  • Optional onDone?: OnDone

    This is a callback that will be called after the event(s) have been successfully published.

  • Optional onError?: OnError

    This is a callback that will be called if any errors occur during the publication process.

PublishPromiseOpts

PublishPromiseOpts: Omit<PublishOpts, "onDone" | "onError">

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.

QueryOpts

QueryOpts: { lowerBound?: OffsetMap; onDone?: OnDone; onError?: OnError; onEvent: OnEvent; ordering: Ordering; subscriptions: Subscription | Subscription[]; upperBound: OffsetMap }

Configuration of a query to the ActyxOS Event Service. Please refer to the individual properties for more information about what each of them do.

Type declaration

  • Optional lowerBound?: OffsetMap

    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.

  • Optional onDone?: OnDone

    This is a callback that will be called after the query has ended.

  • Optional onError?: OnError

    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.

  • onEvent: OnEvent

    This is a callback that will be called for each event returned by the query.

  • ordering: Ordering

    The order in which you want the query to return results. Please refer to the ActyxOS Event Service API documentation for more details.

  • subscriptions: Subscription | Subscription[]

    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'),
    ]
  • upperBound: OffsetMap

    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.

QueryStreamOpts

QueryStreamOpts: Omit<QueryOpts, "onEvent" | "onDone" | "onError">

SimpleLoggerOpts

SimpleLoggerOpts: { logName: string; onError?: undefined | ((error: string) => void); producerName: string; producerVersion: string }

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.

Type declaration

  • logName: string
  • Optional onError?: undefined | ((error: string) => void)
  • producerName: string
  • producerVersion: string

SubscribeOpts

SubscribeOpts: { lowerBound?: OffsetMap; onDone?: OnDone; onError?: OnError; onEvent: OnEvent; subscriptions: Subscription | Subscription[] }

Configuration of a subscription to the ActyxOS Event Service. Please refer to the individual properties for more information about what each of them do.

Type declaration

  • Optional lowerBound?: OffsetMap

    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.

  • Optional onDone?: OnDone

    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).

  • Optional onError?: OnError

    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.

  • onEvent: OnEvent

    This is a callback that will be called for each event returned by the subscription.

  • subscriptions: Subscription | 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'),
    ]

SubscribeStreamOpts

SubscribeStreamOpts: Omit<SubscribeOpts, "onEvent" | "onDone" | "onError">

Subscription

Subscription: { source?: string | undefined; streamName?: string | undefined; streamSemantics?: string | undefined }

Describes a subscription

Type declaration

  • Optional source?: string | undefined
  • Optional streamName?: string | undefined
  • Optional streamSemantics?: string | undefined

Functions

Const Client

  • 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
      }
    })

    Parameters

    Returns ApiClient

Const DefaultClientOpts

  • This function returns the default client options

    Returns ApiClientOpts

Const lineToEvent

  • lineToEvent(line: string): EventT[]
  • Parameters

    • line: string

    Returns EventT[]

Const queryStream

  • Parameters

    Returns (Anonymous function)

streamToEvents

  • streamToEvents(input: AsyncIterable<Buffer>): AsyncGenerator<EventT, void, undefined>
  • Parameters

    • input: AsyncIterable<Buffer>

    Returns AsyncGenerator<EventT, void, undefined>

Object literals

Const EventDraft

EventDraft: object

make

  • make(streamSemantics: string, streamName: string, payload: unknown): EventDraft
  • Helper function for creating an EventDraft using the provided semantics, name and payload.

    Parameters

    • streamSemantics: string

      Semantics of the stream the event should be published to

    • streamName: string

      Name of the stream the event should be published to

    • payload: unknown

      The event payload.

    Returns EventDraft

    An event draft that can be passed to the EventServiceClient's publish function.

Const Subscription

Subscription: object

This object provides useful constructors for creating subscription definitions.

distributed

  • distributed(streamSemantics: string, streamName: string): Subscription
  • This creates a subscription to all events with the specified semantics and the specified name.

    Parameters

    • streamSemantics: string
    • streamName: string

    Returns Subscription

everything

  • This creates a subscription to all events known to the ActyxOS Event Service.

    Returns Subscription

local

  • local(streamSemantics: string, streamName: string, source: string): Subscription
  • This creates a subscription to all events with the specified semantics and the specified name, and from the specified source.

    Parameters

    • streamSemantics: string
    • streamName: string
    • source: string

    Returns Subscription

wildcard

  • This creates a subscription to all events with the specified semantics.

    Parameters

    • streamSemantics: string

    Returns Subscription

Legend

  • Property

Generated using TypeDoc