@firesync/client

The FireSync client can be installed with:

$ npm install --save @firesync/client

and included in your application with:

import FireSync from '@firesync/client'

Classes

FireSync

FireSyncMonacoBinding

Typedefs

FireSyncOptions : object

Parameters used to configure a new instance of a FireSync client.

SubscribeYDocOptions : object

Options for firesync.subscribeYDoc

SubscribeAwarenessOptions : object

Options for firesync.subscribeAwareness

FireSyncMonacoBindingOptions : object

Options for FireSyncMonacoBinding

FireSync

Kind: global class

• FireSync
  • new FireSync(options)
  • .connected ⇒ boolean
  • .connect()
  • .disconnect()
  • .subscribeYDoc(docKey, options) ⇒ Y.Doc
  • .unsubscribe(docKey)
  • .subscribeAwareness(docKey, [awareness]) ⇒ Awareness

new FireSync(options)

Create a new instance of a FireSync client. You will typically need one instance per client in your application.

Param	Type
options	FireSyncOptions

Example

import FireSync from '@firesync/client'
const firesync = new FireSync({
  // If using FireSync cloud:
  projectName: 'acme-dev',
  // Or if using a local firesync-server:
  // baseUrl: 'http://localhost:5000',

  // A JWT token signed with your project secret
  token: 'my-token',

  // Whether to connect to the server immediately
  connect: true
})

firesync.connected ⇒ boolean

Returns true if the client is connected to the server, and false otherwise

Kind: instance property of FireSync
Read only: true

firesync.connect()

Attempt to connect to the server.

The FireSync client will attempt to connect to the server when first initialized, although this default behaviour can be overriden by passing connect: false when initializing.

Kind: instance method of FireSync
Example

const firesync = new FireSync({
  // ...
  connect: false
})
// Connect manually later
firesync.connect()

firesync.disconnect()

Disconnect from the server.

Kind: instance method of FireSync
Example

firesync.disconnect()

firesync.subscribeYDoc(docKey, options) ⇒ Y.Doc

Subscribe to changes to the given document and return the a Yjs Y.Doc which is kept in sync with the FireSync backend.

Any changes made locally to the Y.Doc will be sent to other subscribed clients, and the Y.Doc will received any changes made by other clients.

If the doc has been previously unsubscribed then it will be resubscribed.

Kind: instance method of FireSync

Param	Type	Description
docKey	string	The key that identifies the document in the FireSync backend
options	SubscribeYDocOptions

Example

const doc = firesync.subscribeYDoc('foo')
doc.on('update', () => {
  // Will recieve local changes and changes from
  // other subscribed clients
  console.log('Doc was updated')
})
doc.getMap('user').set('name', 'Bob')

firesync.unsubscribe(docKey)

Unsubscribe from the given document. The doc will no longer recieve changes made by other clients or send changes made locally to the server.

Kind: instance method of FireSync

Param	Type	Description
docKey	string	The key that identifies the document in the FireSync backend

Example

firesync.unsubscribe('foo')

firesync.subscribeAwareness(docKey, [awareness]) ⇒ Awareness

Returns an Awareness instance which is synced with the FireSync backend and will send any awareness updates to other clients and receive awareness updates from other clients.

Kind: instance method of FireSync

Param	Type	Description
docKey	string	The key that identified the document in the FireSync backend
[awareness]	Awareness	An optional Awareness instance to use rather than returning a new instance

FireSyncMonacoBinding

Kind: global class

• FireSyncMonacoBinding
  • new FireSyncMonacoBinding(firesync, docKey, editor, [options])
  • .destroy()

new FireSyncMonacoBinding(firesync, docKey, editor, [options])

Create a new instance of FireSyncMonacoBinding to connect a Monaco editor instance to a document that is synced via FireSync.

Param	Type	Description
firesync	FireSync	A FireSync instance
docKey	string	The key of the document to bind the Monaco editor to
editor	IStandaloneCodeEditor	A Monaco editor instance
[options]	FireSyncMonacoBindingOptions	Configuration options

Example

import { FireSyncMonacoBinding } from '@firesync/client/monaco'

const editor = monaco.editor.create(document.getElementById('monaco-editor'), {
  value: '', // Gets overwritten when FireSync doc syncs
  language: "javascript"
})
const binding = new FireSyncMonacoBinding(firesync, 'my-doc-key', editor)

binding.destroy()

Remove the connection between the Monaco editor and the FireSync document

Kind: instance method of FireSyncMonacoBinding

FireSyncOptions : object

Parameters used to configure a new instance of a FireSync client.

Kind: global typedef

Param	Type	Default	Description
token	string		A JWT signed with your project secret with a list of docs that the client can access. See Authentication for more information
[baseUrl]	string		The URL of your own firesync-server.
[projectName]	string		The name of your project in FireSync Cloud.
[connect]	boolean	true	Whether FireSync should immediately connect to the server. Defaults to true if not provided.
[CustomWebSocket]	WebSocket	window.WebSocket	Can be used to pass in a custom WebSocket implementation. This is useful for using a FireSync client instance on the server, where can pass in the WebSocket implementation from the ws library.

Example

new FireSync({
  // If using FireSync cloud:
  projectName: 'acme-dev',
  // Or if using a local firesync-server:
  // baseUrl: 'http://localhost:5000',

  // A JWT token signed with your project secret
  token: 'my-token',

  // Whether to connect to the server immediately
  connect: true
})

SubscribeYDocOptions : object

Options for firesync.subscribeYDoc

Kind: global typedef

Param	Type	Description
[ydoc]	Y.Doc	An optional existing Y.Doc to use rather than returning a new instance
[initialize]	function	A method which is called with the ydoc to set some initial content. This is only called after the ydoc is synced to the server and if there is no existing data in it. Any updates are done with clientID 0, so that if multiple clients set the same content, there is no conflict. This must always be called with the same content on different clients otherwise the doc could be inconsistent if two clients try to initialize different content concurrently.

Example

firesync.subscribeYDoc('my-doc', {
  ydoc: new Y.Doc(),
  initialize: (ydoc) => {
    ydoc.getText('foo').insert(0, 'Initial content')
    ydoc.getMap('bar').set('hello', 'world')
  }
})

SubscribeAwarenessOptions : object

Options for firesync.subscribeAwareness

Kind: global typedef

Param	Type	Description
[awareness]	Awareness	An optional existing Awareness instance to use rather than returning a new instance

Example

firesync.subscribeAwareness('my-doc', {
  awareness: new Awareness()
})

FireSyncMonacoBindingOptions : object

Options for FireSyncMonacoBinding

Kind: global typedef

Param	Type	Default	Description
[cursors]	boolean	true	Show cursors and names of other connected clients. The name and color can be set with firesync.setUserDisplayName and firesync.setUserColor on each client
[textKey]	string	"default"	The key to use to get a Y.Text instance from the Y.Doc. The Monaco editor is synced to the Y.Text instance at ydoc.getText(textKey)
[ytext]	Y.Text		A Y.Text instance to bind to the Monaco editor. This is useful for Y.Text instances that are nested within your Y.Doc.
[awareness]	Awareness		An existing Awareness instance to use for sharing cursor location and names between connected clients.
[initialValue]	string		An initial value to set on the Y.Text instance. See the initialize function in SubscribeYDocOptions for more information.

Example

// Example with custom Y.Text instance nested with Y.Doc:
const ydoc = firesync.subscribeYDoc('my-doc-key')
const ytext = new Y.Text()
// Y.Text instance must be part of doc
ydoc.getMap('foo').set('bar', ytext)
new FireSyncMonacoBinding(firesync, 'my-doc-key', editor, {
  ytext: ytext,
  initialValue: 'Hello world',
  cursors: false
})