graphql-eventstore-subscriptions

graphql-eventstore-subscriptions implements the PubSubEngine interface from the graphql-subscriptions package.

Unlike other databases, Google's Firestore comes across with real time updates. Therefore, it is not required to publish events to a queue or a pub-sub. However, there is still something to do to get the data to the clients. In graphql-eventstore-subscriptions those tasks are called handlers. They are subscribing a specific topic and broadcast whatever you want over an AsyncIterator which is compatible with graphql-subscriptions.

Usage

First of all, you have to install the graphql-eventstore-subscriptions package using yarn or npm by calling either yarn add graphql-eventstore-subscriptions or npm i --save graphql-eventstore-subscriptions.

Create a new graphql-eventstore-subscription instance

import PubSub from 'graphql-eventstore-subscriptions';

const ps = new PubSub();

Full example

import PubSub from 'graphql-eventstore-subscriptions';
import db from '../path/to/firestore/connection';

enum Topic {
  NEW_COMMENT = 'NEW_COMMENT',
}
eventstore
const ps = new PubSub();

ps.registerHandler(Topic.NEW_COMMENT, broadcast =>
  // Note, that `onSnapshot` returns a unsubscribe function which
  // returns void.
  db.collection('comments').onSnapshot(snapshot => {
    snapshot
      .docChanges()
      .filter(change => change.type === 'added')
      .map(item => broadcast(item.doc.data()));
  })
);

const iterator = ps.asyncIterator(Topic.NEW_COMMENT);
const addedComment = await iterator.next();

// ...

With apollo-server-graphql

Define a GraphQL schema with a Subscription type.

schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

type Subscription {
  newComment: Comment
}

type Comment {
  message: String
}

Now, implement the resolver:

export const resolvers = {
  Subscription: {
    newComment: {
      subscribe: () => ps.asyncIterator(Topic.NEW_COMMENT),
    },
  },
};

Calling asyncIterator(topics: string | string[]) will subscribe to the given topics and will return an AsyncIterator bound to the PubSubEngine of graphql-eventstore-subscriptions. Everytime, a handler calls the obtained broadcast-function, the PubSubEngine of graphql-eventstore-subscriptions will publish the event.

API

createFallThroughHandler

function createFallThroughHandler(
  fs: Firestore,
  overwriteOptions: FallThroughHandlerOptions
): [string, Handler];

Options

| Name | Type | Description | | -------------- | ----------------------------------------------------- | ------------------------------------------------------------- | | topic* | string | - | | collection* | string | The firebase collection | | transform | TransformStrategy | (change: DocumentChange) => any | Called to transform the broadcast-payload | | filter | (change: DocumentChange) => boolean | Called to filter document changes before they are broadcasted |

* required

createFallThroughHandlerFromMap

function createFallThroughHandlerFromMap(
  fs: Firestore,
  options: FallThroughHandlerFromMapOptions
): [string, Handler][];

Options

| Name | Type | Description | | ----- | ------------------------- | ------------------------------------------------------------ | | topic | [topic: string]: Object | See createFallThroughHandler#Options for a complete overview |

Contribute

Something is broken? The documentation is incorrect? You're missing a feature? ...and you wanna help? That's great.

The following steps are describing the way from an idea / bug / ... to a pull-request.

1. Fork this repository
2. Apply the changes
3. Write tests (you can execute the current tests by calling npm run test:unit OR npm run test:unit:watch)
4. If necessary, update the documentation
5. Open a pull-request
6. :tada: