@sphinx-software/station NPM

Station

@sphinx-software/station

Version Issues License

Abstraction Layer for realtime messaging & push notification

yarn

yarn add @sphinx-software/station

npm

npm i -S @sphinx-software/station

This package is server implementation. For client-side implementation, please check @sphinx-software/antenna

Getting Started

💡 Station is an abstract layer for realtime messaging, staying on top of well-known Firebase services.

Realtime Messaging

Minimal example

We support realtime messaging via Messenger service.

import { Messenger, transports } from '@sphinx-software/station'

const messenger = new Messenger(transports.log(console))

messenger.send(
  {
    type: 'greeting',
    payload: {
      hello: 'world',
    },
  },
  'the-world',
)

Run the above script, you should see the bellow output in your console

{
  message: { type: 'greeting', payload: { hello: 'world' } },
  channels: [ 'world-channel' ]
} Messenger.Transport.Log#send

That's it! You've sent a greeting message to the world-channel.

💡
A message must have 2 fields: type accepts a string describing the message type and payload which is data the message carrying
The send() method is returning a Promise<void> value
The example above is using the log transport. It will do nothing but log the message to the console output, which will be come handy for testing / debugging. For the real world application, please check the firestore transport.

Sending a message to a subscriber

In real world application, we usually cooperate an entity with a channel.

For example:

class User {
  // ... your code here
}

We can instruct the messenger that User is a Subscriber, which can receive a message

class User implements Subscriber {
  uid(): string {
    return this.id.toString()
  }

  inbound(): string {
    return `users-${this.uid()}`
  }
}

💡
Each subscriber can have unique identity specified in uid() method, and one inbound channel specified in inbound() method.

Now we can send a message to the user:

/// Your code to get the user entity
const joe = new User()

///
messenger.send(
  {
    type: 'greeting',
    payload: {
      content: 'Hello',
    },
  },
  joe,
)

`MessagShape` interface

We can also model our message by implementing the MessageShape interface.

class FriendRequest implements MessageShape<{ sender: User }> {
  get type() {
    return 'FriendRequest'
  }

  get payload() {
    return {
      sender: this.sender,
    }
  }

  constructor(private sender: User) {}
}

Then send the message as usual

//

messenger.send(new FriendRequest(joe), jane)

Messaging via topics

Another messaging mechanism is broadcasting messages via topics. Subscribers subscribing to the topic can receive the messages.

We can send a message to a topic using broadcast method:

messenger.broadcast(
  {
    type: 'highscore.new',
    payload: {
      score: 999,
    },
  },
  'highscore',
)

We can also implement Topic interface for a topic model:

import { Topic } from '@sphinx-software/station'

// A post that can also become a topic.
// So subscribers can listen for new comment for this post.
class Post implements Topic {
  topicName() {
    return `post-${this.id}`
  }
}

// When a new comment was made for this post
// we can broadcast the message to the post topic
// so subscribers can get updated
messenger.broadcast(
  {
    type: 'comment.added',
    payload: {
      commentId: comment.id,
    },
  },
  post,
)