Document synchronization

Purpose

Synchronizes JSON documents from multiple sources using Conflict-free Replicated Data Types.

Installation

npm install @erebos/doc-sync

The various feed list classes must be injected a BzzFeed instance, so @erebos/bzz-feed must also be installed alongside.

Usage

import { DocSynchronizer, DocWriter } from '@erebos/doc-sync'

// simplified for brievity
const [alice, bob, chloe] = await Promise.all([
  DocWriter.init({ ... doc: { alice: 'hello' } }),
  DocWriter.init({ ... doc: { bob: 'hello' } }),
])

const chloe = await DocSynchronizer.init({
  ... // simplified for brievity
  doc: { chloe: 'hello' },
  sources: [alice.metaFeed, bob.metaFeed],
})
chloe.subscribe(doc => {
  // doc will change over time to become
  // { alice: 'one', bob: 'two', chloe: 'three' }
})

alice.change(doc => {
  doc.alice = 'one'
})
bob.change(doc => {
  doc.bob = 'two'
})
await Promise.all([alice.push(), bob.push()])

chloe.change(doc => {
  doc.chloe = 'three'
})

Interfaces and types

Change

Change interface exported by Automerge

Doc

Doc interface exported by Automerge

Bzz

Alias type using the BzzFeed class

type Bzz = BzzFeed<any, Response>

FeedFactoryParams

interface FeedFactoryParams {
  user: string
  topic?: string
}

DataContent

Uses Change

interface DataContent {
  changes: Array<Change>
}

MetaSnapshot

interface MetaSnapshot {
  hash: string
  time: number
}

MetaContent

Uses FeedParams and MetaSnapshot

interface MetaContent {
  dataFeed: FeedParams
  snapshot?: MetaSnapshot | undefined
}

ProtocolContent

interface ProtocolContent {
  protocol: string
  version: string
}

DataPayload

Extends DataContent and ProtocolContent

interface DataPayload extends DataContent, ProtocolContent {}

MetaPayload

Extends MetaContent and ProtocolContent

interface MetaPayload extends MetaContent, ProtocolContent {}

DocFeeds

Uses FeedParams

interface DocFeeds {
  data: FeedParams
  meta: FeedParams
}

DocSerialized

Uses FeedParams

interface DocSerialized {
  docString: string
  dataFeed: FeedParams
  metaFeed: FeedParams
}

LoadDocReaderParams

Uses FeedParams and Bzz

interface LoadDocReaderParams<B extends Bzz = Bzz> {
  bzz: B
  feed: FeedParams // params for meta feed
}

FromJSONDocReaderParams

Extends DocSerialized

Uses Bzz

interface FromJSONDocReaderParams<B extends Bzz = Bzz> extends DocSerialized {
  bzz: B
}

DocReaderParams

Uses FeedParams, DataListReader class, Bzz, Doc and DataPayload

interface DocReaderParams<T, B extends Bzz = Bzz> {
  bzz: B
  doc: Doc<T>
  feed: FeedParams
  list: DataListReader<DataPayload, B>
  time: number
}

DocSubscriberParams

Extends DocReaderParams

Uses Bzz

interface DocSubscriberParams<T, B extends Bzz = Bzz>
  extends DocReaderParams<T, B> {
  pullInterval: number
}

FromJSONDocSubscriberParams

Extends FromJSONDocReaderParams

Uses Bzz

interface FromJSONDocSubscriberParams<B extends Bzz = Bzz>
  extends FromJSONDocReaderParams<B> {
  pullInterval: number
}

LoadDocSubscriberParams

Extends LoadDocReaderParams

Uses Bzz

interface LoadDocSubscriberParams<B extends Bzz = Bzz>
  extends LoadDocReaderParams<B> {
  pullInterval: number
}

CreateDocWriterParams

Uses Bzz and FeedFactoryParams

interface CreateDocWriterParams<B extends Bzz = Bzz> {
  bzz: B
  feed: FeedFactoryParams
  snapshotFrequency?: number
}

InitDocWriterParams

Extends CreateDocWriterParams

Uses Bzz

interface InitDocWriterParams<T, B extends Bzz = Bzz>
  extends CreateDocWriterParams<B> {
  doc: T
}

FromJSONDocWriterParams

Extends FromJSONDocReaderParams

Uses Bzz

interface FromJSONDocWriterParams<B extends Bzz = Bzz>
  extends FromJSONDocReaderParams<B> {
  snapshotFrequency?: number
}

LoadDocWriterParams

Extends LoadDocReaderParams

Uses Bzz

interface LoadDocWriterParams<B extends Bzz = Bzz>
  extends LoadDocReaderParams<B> {
  snapshotFrequency?: number
}

DocWriterParams

Uses FeedParams, DataListWriter class, Bzz, Doc and DataPayload

interface DocWriterParams<T, B extends Bzz = Bzz> {
  bzz: B
  doc: Doc<T>
  feed: FeedParams
  list: DataListWriter<DataPayload, B>
  snapshotFrequency?: number
}

InitDocSynchronizerParams

Extends InitDocWriterParams

Uses FeedParams and Bzz

interface InitDocSynchronizerParams<T, B extends Bzz = Bzz>
  extends InitDocWriterParams<T, B> {
  pullInterval: number
  pushInterval?: number
  sources?: Array<FeedParams>
}

FromJSONSynchronizerParams

Extends FromJSONDocWriterParams

Uses Bzz and DocSerialized

interface FromJSONDocSynchronizerParams<B extends Bzz = Bzz>
  extends FromJSONDocWriterParams<B> {
  pullInterval: number
  pushInterval?: number
  sources?: Array<DocSerialized>
}

LoadDocSynchronizerParams

Extends LoadDocWriterParams

Uses FeedParams and Bzz

interface LoadDocSynchronizerParams<B extends Bzz = Bzz>
  extends LoadDocWriterParams<B> {
  pullInterval: number
  pushInterval?: number
  sources?: Array<FeedParams>
}

DocSynchronizerParams

Extends DocWriterParams

Uses Bzz and DocSubscriber

interface DocSynchronizerParams<T, B extends Bzz = Bzz>
  extends DocWriterParams<T, B> {
  pushInterval?: number
  sources?: Array<DocSubscriber<T, B>>
}

DocSynchronizerSerialized

Extends and uses DocSerialized

interface DocSynchronizerSerialized extends DocSerialized {
  sources: Array<DocSerialized>
}

DocReader class

Extends BehaviorSubject<Doc<T>>

Types

T = any: the type of the document data

new DocReader()

Arguments

params: DocReaderParams

DocReader.fromJSON()

Creates a DocReader instance using a serialized document

Arguments

params: DocReaderFromJSONParams

Returns DocReader

DocReader.load()

Creates a DocReader instance loading the remote document

Arguments

params: DocReaderLoadParams

Returns Promise<DocReader>

.metaFeed

Returns FeedParams

.pull()

Returns Promise<boolean> whether the document has changed or not

.toJSON()

Returns DocSerialized

DocSubscriber class

Extends DocReader<T>

Types

T = any: the type of the document data

new DocSubscriber()

Arguments

params: DocSubscriberParams

DocSubscriber.fromJSON()

Creates a DocSubscriber instance using a serialized document

Arguments

params: DocSubscriberFromJSONParams

Returns DocSubscriber

DocSubscriber.load()

Creates a DocSubscriber instance loading the remote document

Arguments

params: DocSubscriberLoadParams

Returns Promise<DocSubscriber>

.start()

Start polling changes

Returns void

.stop()

Stop polling changes

Returns void

DocWriter class

Extends DocReader<T>

Types

T = any: the type of the document data

new DocWriter()

Arguments

params: DocWriterParams

DocWriter.create()

Creates a new DocWriter instance with an empty document

Arguments

params: DocWriterCreateParams

Returns DocWriter

DocWriter.init()

Creates a new DocWriter instance with a provided document and push it remotely

Arguments

params: DocWriterInitParams

Returns Promise<DocWriter>

DocWriter.fromJSON()

Creates a DocWriter instance using a serialized document

Arguments

params: DocWriterFromJSONParams

Returns DocWriter

DocWriter.load()

Creates a DocWriter instance loading the remote document

Arguments

params: DocWriterLoadParams

Returns Promise<DocWriter>

.length

Returns number the number of changes that have been published

.change()

Arguments

updater: (doc: T) => void the function mutating the document data

Returns boolean whether the document has changed or not

.merge()

Arguments

other: Doc<T> the other document to merge with

Returns boolean whether the document has changed or not

.push()

Pushes the changes to the remote feed. If there is no change to push, it will return null, otherwise it will return the Swarm hash where the updated metadata has been uploaded.

Returns Promise<string | null>