plushie

pusher-js wrapper to simplify auth, subscriptions, & events

plushie makes working with Pusher channels easy:

• Authentication: Immediately connects to a private-connections channel to authenticate your session for use with private-* and presence-* channels
• Subscriptions: Subscribe and bind to events in the same step
• Client events: Trigger events that are passed through a pausable queue that keeps you under Pusher's rate limits.

Installation

yarn add @replygirl/plushie

Usage

import Plushie from '@replygirl/plushie'

// Create a Plushie
const plushie = new Plushie({
  // REQUIRED: Your app's public key
  key: 'myKey',

  // OPTIONAL:
  // - Required for private & presence channels
  // - Required to trigger events
  authEndpoint: '/my-auth-endpoint'
})

// Bind to events on a channel
const channel = plushie.subscribe({
  channelName: 'my-channel-name',
  bindings: [
    {
      eventName: 'my-event-name',
      callback: data => console.info(data)
    }
  ]
})

// Add more event bindings later
channel.bind([
  {
    eventName: 'my-other-event-name',
    callback: data => console.info(data)
  }
])

// Trigger a client event
channel.trigger([
  {
    eventName: 'my-event-name',
    data: 'Hello world'
  }
])

// Let it go
channel.unsubscribe()

Controlling the queue

Your Plushie's event queue will automatically start & stop as you subscribe & unsubscribe, but you can intervene too:

// Stop triggering events
plushie.eventQueue.pause()

// Resume triggering events
plushie.eventQueue.play()

Tearing down

plushie.unsubscribeAll()

Advanced features

This doc keeps it simple, but a lot of Plushie's internal logic is exposed to give you more options. Explore the definition files or source code to figure out some neat tricks.

New in v2.x

• The event queue will only run when you're subscribed to a channel
• Full typing
  • Channels are now PlushieChannels
  • Event bindings are now PlushieEventBindings
  • Events are now PlushieEvents
• Generics: new Plushie<T, U>
  • T is the base type of your event data
  • U is the base return type of your event callbacks
• Bind an array of events with Plushie.bind
• Get the name of a channel with PlushieChannel.name
• Get the Plushie instance a channel belongs to with PlushieChannel.plushie

Migrating from v1.x

Unless you were using undocumented capabilities, the only breaking change is how you use Plushie.subscribe:

// Before
plushie.subscribe('my-channel-name', {
  'my-event-name': data => console.info(data)
})

// After
plushie.subscribe({
  channelName: 'my-channel-name',
  bindings: [
    {
      eventName: 'my-event-name',
      callback: data => console.info(data)
    }
  ]
})

License

ISC (c) 2020 replygirl