Skip to main content

@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

new FireSync(options)

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

ParamType
optionsFireSyncOptions

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

ParamTypeDescription
docKeystring

The key that identifies the document in the FireSync backend

optionsSubscribeYDocOptions

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

ParamTypeDescription
docKeystring

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

ParamTypeDescription
docKeystring

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

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.

ParamTypeDescription
firesyncFireSync

A FireSync instance

docKeystring

The key of the document to bind the Monaco editor to

editorIStandaloneCodeEditor

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

ParamTypeDefaultDescription
tokenstring

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]booleantrue

Whether FireSync should immediately connect to the server. Defaults to true if not provided.

[CustomWebSocket]WebSocketwindow.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

ParamTypeDescription
[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

ParamTypeDescription
[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

ParamTypeDefaultDescription
[cursors]booleantrue

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