BlockSuite

Appearance

BlockSuite API Documentation / @blocksuite/sync

@blocksuite/sync ​

Enumerations ​

DocEngineStep ​

Enumeration Members ​

Stopped ​

Stopped: 0

Synced ​

Synced: 2

Syncing ​

Syncing: 1

DocPeerStep ​

Enumeration Members ​

Loaded ​

Loaded: 4.5

LoadingRootDoc ​

LoadingRootDoc: 2

LoadingSubDoc ​

LoadingSubDoc: 3

Retrying ​

Retrying: 1

Stopped ​

Stopped: 0

Synced ​

Synced: 6

Syncing ​

Syncing: 5

Classes ​

AwarenessEngine ​

Constructors ​

Constructor ​

new AwarenessEngine(awareness, sources): AwarenessEngine

Parameters ​
awareness ​

Awareness

sources ​

AwarenessSource[]

Returns ​

AwarenessEngine

Properties ​

awareness ​

readonly awareness: Awareness

sources ​

readonly sources: AwarenessSource[]

Methods ​

connect() ​

connect(): void

Returns ​

void

disconnect() ​

disconnect(): void

Returns ​

void

BlobEngine ​

BlobEngine ​

sync blobs between storages in background.

all operations priority use main, then use shadows.

Constructors ​

Constructor ​

new BlobEngine(main, shadows, logger): BlobEngine

Parameters ​
main ​

BlobSource

shadows ​

BlobSource[]

logger ​

Logger

Returns ​

BlobEngine

Properties ​

logger ​

readonly logger: Logger

main ​

readonly main: BlobSource

shadows ​

readonly shadows: BlobSource[]

Accessors ​

sources ​
Get Signature ​

get sources(): BlobSource[]

Returns ​

BlobSource[]

Methods ​

blobState$() ​

blobState$(key): Observable<BlobState> | null

Parameters ​
key ​

string

Returns ​

Observable<BlobState> | null

delete() ​

delete(_key): Promise<void>

Parameters ​
_key ​

string

Returns ​

Promise<void>

get() ​

get(key): Promise<Blob | null>

Parameters ​
key ​

string

Returns ​

Promise<Blob | null>

list() ​

list(): Promise<string[]>

Returns ​

Promise<string[]>

set() ​
Call Signature ​

set(value): Promise<string>

Parameters ​
value ​

Blob

Returns ​

Promise<string>

Call Signature ​

set(key, value): Promise<string>

Parameters ​
key ​

string

value ​

Blob

Returns ​

Promise<string>

start() ​

start(): void

Returns ​

void

stop() ​

stop(): void

Returns ​

void

sync() ​

sync(): Promise<void>

Returns ​

Promise<void>

upload() ​

upload(key): Promise<boolean> | null

Parameters ​
key ​

string

Returns ​

Promise<boolean> | null

BroadcastChannelAwarenessSource ​

Implements ​

Constructors ​

Constructor ​

new BroadcastChannelAwarenessSource(channelName): BroadcastChannelAwarenessSource

Parameters ​
channelName ​

string

Returns ​

BroadcastChannelAwarenessSource

Properties ​

awareness ​

awareness: Awareness | null = null

channel ​

channel: BroadcastChannel | null = null

channelName ​

readonly channelName: string

Methods ​

connect() ​

connect(awareness): void

Parameters ​
awareness ​

Awareness

Returns ​

void

Implementation of ​

AwarenessSource.connect

disconnect() ​

disconnect(): void

Returns ​

void

Implementation of ​

AwarenessSource.disconnect

handleAwarenessUpdate() ​

handleAwarenessUpdate(changes, origin): void

Parameters ​
changes ​

AwarenessChanges

origin ​

unknown

Returns ​

void

handleChannelMessage() ​

handleChannelMessage(event): void

Parameters ​
event ​

MessageEvent<ChannelMessage>

Returns ​

void

BroadcastChannelDocSource ​

Implements ​

Constructors ​

Constructor ​

new BroadcastChannelDocSource(channelName): BroadcastChannelDocSource

Parameters ​
channelName ​

string = 'blocksuite:doc'

Returns ​

BroadcastChannelDocSource

Properties ​

channel ​

channel: BroadcastChannel

channelName ​

readonly channelName: string = 'blocksuite:doc'

docMap ​

docMap: Map<string, Uint8Array<ArrayBufferLike>>

name ​

name: string = 'broadcast-channel'

for debug

Implementation of ​

DocSource.name

Methods ​

pull() ​

pull(docId, state): { data: Uint8Array<ArrayBufferLike>; state: Uint8Array<ArrayBufferLike>; } | null

Parameters ​
docId ​

string

state ​

Uint8Array

Returns ​

{ data: Uint8Array<ArrayBufferLike>; state: Uint8Array<ArrayBufferLike>; } | null

Implementation of ​

DocSource.pull

push() ​

push(docId, data): void

Parameters ​
docId ​

string

data ​

Uint8Array

Returns ​

void

Implementation of ​

DocSource.push

subscribe() ​

subscribe(cb): () => void

Subscribe to updates from peer

Parameters ​
cb ​

(docId, data) => void

callback to handle updates

Returns ​

unsubscribe function

(): void

Returns ​

void

Implementation of ​

DocSource.subscribe

DocEngine ​

DocEngine ​

                   ┌────────────┐
                   │  DocEngine │
                   └─────┬──────┘
                         │
                         ▼
                   ┌────────────┐
                   │   DocPeer  │
         ┌─────────┤    main    ├─────────┐
         │         └─────┬──────┘         │
         │               │                │
         ▼               ▼                ▼
  ┌────────────┐   ┌────────────┐   ┌────────────┐
  │   DocPeer  │   │   DocPeer  │   │   DocPeer  │
  │   shadow   │   │   shadow   │   │   shadow   │
  └────────────┘   └────────────┘   └────────────┘

doc engine manage doc peers

Sync steps:

  1. start main sync
  2. wait for main sync complete
  3. start shadow sync
  4. continuously sync main and shadows

Constructors ​

Constructor ​

new DocEngine(rootDoc, main, shadows, logger): DocEngine

Parameters ​
rootDoc ​

Doc

main ​

DocSource

shadows ​

DocSource[]

logger ​

Logger

Returns ​

DocEngine

Properties ​

logger ​

readonly logger: Logger

main ​

readonly main: DocSource

onStatusChange ​

readonly onStatusChange: Subject<DocEngineStatus>

priorityTarget ​

readonly priorityTarget: SharedPriorityTarget

rootDoc ​

readonly rootDoc: Doc

shadows ​

readonly shadows: DocSource[]

Accessors ​

rootDocId ​
Get Signature ​

get rootDocId(): string

Returns ​

string

status ​
Get Signature ​

get status(): DocEngineStatus

Returns ​

DocEngineStatus

Methods ​

canGracefulStop() ​

canGracefulStop(): boolean

Returns ​

boolean

forceStop() ​

forceStop(): void

Returns ​

void

setPriorityRule() ​

setPriorityRule(target): void

Parameters ​
target ​

(id) => boolean | null

Returns ​

void

start() ​

start(): void

Returns ​

void

sync() ​

sync(signal): Promise<void>

Parameters ​
signal ​

AbortSignal

Returns ​

Promise<void>

updateSyncingState() ​

updateSyncingState(local, shadows): void

Parameters ​
local ​

SyncPeer | null

shadows ​

(SyncPeer | null)[]

Returns ​

void

waitForGracefulStop() ​

waitForGracefulStop(abort?): Promise<void>

Parameters ​
abort? ​

AbortSignal

Returns ​

Promise<void>

waitForLoadedRootDoc() ​

waitForLoadedRootDoc(abort?): Promise<unknown>

Parameters ​
abort? ​

AbortSignal

Returns ​

Promise<unknown>

waitForSynced() ​

waitForSynced(abort?): Promise<unknown>

Parameters ​
abort? ​

AbortSignal

Returns ​

Promise<unknown>

IndexedDBBlobSource ​

Implements ​

Constructors ​

Constructor ​

new IndexedDBBlobSource(name): IndexedDBBlobSource

Parameters ​
name ​

string

Returns ​

IndexedDBBlobSource

Properties ​

mimeTypeStore ​

readonly mimeTypeStore: UseStore

name ​

readonly name: string

Implementation of ​

BlobSource.name

readonly ​

readonly: boolean = false

Implementation of ​

BlobSource.readonly

store ​

readonly store: UseStore

Methods ​

delete() ​

delete(key): Promise<void>

Parameters ​
key ​

string

Returns ​

Promise<void>

Implementation of ​

BlobSource.delete

get() ​

get(key): Promise<Blob | null>

Parameters ​
key ​

string

Returns ​

Promise<Blob | null>

Implementation of ​

BlobSource.get

list() ​

list(): Promise<string[]>

Returns ​

Promise<string[]>

Implementation of ​

BlobSource.list

set() ​

set(key, value): Promise<string>

Parameters ​
key ​

string

value ​

Blob

Returns ​

Promise<string>

Implementation of ​

BlobSource.set

IndexedDBDocSource ​

Implements ​

Constructors ​

Constructor ​

new IndexedDBDocSource(dbName): IndexedDBDocSource

Parameters ​
dbName ​

string = DEFAULT_DB_NAME

Returns ​

IndexedDBDocSource

Properties ​

channel ​

channel: BroadcastChannel

dbName ​

readonly dbName: string = DEFAULT_DB_NAME

dbPromise ​

dbPromise: Promise<IDBPDatabase<BlockSuiteBinaryDB>> | null = null

mergeCount ​

mergeCount: number = 1

name ​

name: string = 'indexeddb'

for debug

Implementation of ​

DocSource.name

Methods ​

getDb() ​

getDb(): Promise<IDBPDatabase<BlockSuiteBinaryDB>>

Returns ​

Promise<IDBPDatabase<BlockSuiteBinaryDB>>

pull() ​

pull(docId, state): Promise<{ data: Uint8Array; state?: Uint8Array<ArrayBufferLike>; } | null>

Parameters ​
docId ​

string

state ​

Uint8Array

Returns ​

Promise<{ data: Uint8Array; state?: Uint8Array<ArrayBufferLike>; } | null>

Implementation of ​

DocSource.pull

push() ​

push(docId, data): Promise<void>

Parameters ​
docId ​

string

data ​

Uint8Array

Returns ​

Promise<void>

Implementation of ​

DocSource.push

subscribe() ​

subscribe(cb): () => void

Subscribe to updates from peer

Parameters ​
cb ​

(docId, data) => void

callback to handle updates

Returns ​

unsubscribe function

(): void

Returns ​

void

Implementation of ​

DocSource.subscribe

MemoryBlobSource ​

Implements ​

Constructors ​

Constructor ​

new MemoryBlobSource(): MemoryBlobSource

Returns ​

MemoryBlobSource

Properties ​

map ​

readonly map: Map<string, Blob>

name ​

name: string = 'memory'

Implementation of ​

BlobSource.name

readonly ​

readonly: boolean = false

Implementation of ​

BlobSource.readonly

Methods ​

delete() ​

delete(key): Promise<void>

Parameters ​
key ​

string

Returns ​

Promise<void>

Implementation of ​

BlobSource.delete

get() ​

get(key): Promise<Blob | null>

Parameters ​
key ​

string

Returns ​

Promise<Blob | null>

Implementation of ​

BlobSource.get

list() ​

list(): Promise<string[]>

Returns ​

Promise<string[]>

Implementation of ​

BlobSource.list

set() ​

set(key, value): Promise<string>

Parameters ​
key ​

string

value ​

Blob

Returns ​

Promise<string>

Implementation of ​

BlobSource.set

NoopDocSource ​

Implements ​

Constructors ​

Constructor ​

new NoopDocSource(): NoopDocSource

Returns ​

NoopDocSource

Properties ​

name ​

name: string = 'noop'

for debug

Implementation of ​

DocSource.name

Methods ​

pull() ​

pull(_docId, _data): null

Parameters ​
_docId ​

string

_data ​

Uint8Array

Returns ​

null

Implementation of ​

DocSource.pull

push() ​

push(_docId, _data): void

Parameters ​
_docId ​

string

_data ​

Uint8Array

Returns ​

void

Implementation of ​

DocSource.push

subscribe() ​

subscribe(_cb, _disconnect): () => void

Subscribe to updates from peer

Parameters ​
_cb ​

(docId, data) => void

callback to handle updates

_disconnect ​

(reason) => void

callback to handle disconnect, reason can be something like 'network-error'

Returns ​

unsubscribe function

(): void

Returns ​

void

Implementation of ​

DocSource.subscribe

SyncPeer ​

DocPeer ​

A DocPeer is responsible for syncing one Storage with one Y.Doc and its subdocs.

                   ┌─────┐
                   │Start│
                   └──┬──┘
                      │
   ┌──────┐     ┌─────▼──────┐        ┌────┐
   │listen◄─────┤pull rootdoc│        │peer│
   └──┬───┘     └─────┬──────┘        └──┬─┘
      │               │ onLoad()         │
   ┌──▼───┐     ┌─────▼──────┐      ┌────▼────┐
   │listen◄─────┤pull subdocs│      │subscribe│
   └──┬───┘     └─────┬──────┘      └────┬────┘
      │               │ onReady()        │
   ┌──▼──┐      ┌─────▼───────┐       ┌──▼──┐
   │queue├──────►apply updates◄───────┤queue│
   └─────┘      └─────────────┘       └─────┘

listen: listen for updates from ydoc, typically from user modifications. subscribe: listen for updates from storage, typically from other users.

Constructors ​

Constructor ​

new SyncPeer(rootDoc, source, priorityTarget, logger): SyncPeer

Parameters ​
rootDoc ​

Doc

source ​

DocSource

priorityTarget ​

SharedPriorityTarget = ...

logger ​

Logger

Returns ​

SyncPeer

Properties ​

abort ​

readonly abort: AbortController

logger ​

readonly logger: Logger

onStatusChange ​

readonly onStatusChange: Subject<DocPeerStatus>

priorityTarget ​

readonly priorityTarget: SharedPriorityTarget

rootDoc ​

readonly rootDoc: Doc

source ​

readonly source: DocSource

state ​

readonly state: object

connectedDocs ​

connectedDocs: Map<string, Doc>

pullUpdatesQueue ​

pullUpdatesQueue: PriorityAsyncQueue<{ data: Uint8Array; id: string; }>

pushingUpdate ​

pushingUpdate: boolean

pushUpdatesQueue ​

pushUpdatesQueue: PriorityAsyncQueue<{ data: Uint8Array<ArrayBufferLike>[]; id: string; }>

subdocLoading ​

subdocLoading: boolean

subdocsLoadQueue ​

subdocsLoadQueue: PriorityAsyncQueue<{ doc: Doc; id: string; }>

Accessors ​

name ​
Get Signature ​

get name(): string

Returns ​

string

Methods ​

connectDoc() ​

connectDoc(doc, abort): Promise<void>

Parameters ​
doc ​

Doc

abort ​

AbortSignal

Returns ​

Promise<void>

disconnectDoc() ​

disconnectDoc(doc): void

Parameters ​
doc ​

Doc

Returns ​

void

handleStorageUpdates() ​

handleStorageUpdates(id, data): void

Parameters ​
id ​

string

data ​

Uint8Array

Returns ​

void

handleSubdocsUpdate() ​

handleSubdocsUpdate(__namedParameters): void

Parameters ​
__namedParameters ​
added ​

Set<Doc>

removed ​

Set<Doc>

Returns ​

void

handleYDocUpdates() ​

handleYDocUpdates(update, origin, doc): void

Parameters ​
update ​

Uint8Array

origin ​

string

doc ​

Doc

Returns ​

void

initState() ​

initState(): void

Returns ​

void

stop() ​

stop(): void

stop sync

DocPeer is one-time use, this peer should be discarded after call stop().

Returns ​

void

sync() ​

sync(abortOuter): Promise<void>

main synchronization logic

Parameters ​
abortOuter ​

AbortSignal

Returns ​

Promise<void>

syncRetryLoop() ​

syncRetryLoop(abort): Promise<void>

auto retry after 5 seconds if sync failed

Parameters ​
abort ​

AbortSignal

Returns ​

Promise<void>

updateSyncStatus() ​

updateSyncStatus(): void

Returns ​

void

waitForLoaded() ​

waitForLoaded(abort?): Promise<void>

Parameters ​
abort? ​

AbortSignal

Returns ​

Promise<void>

waitForSynced() ​

waitForSynced(abort?): Promise<void>

Parameters ​
abort? ​

AbortSignal

Returns ​

Promise<void>

Interfaces ​

AwarenessSource ​

Methods ​

connect() ​

connect(awareness): void

Parameters ​
awareness ​

Awareness

Returns ​

void

disconnect() ​

disconnect(): void

Returns ​

void

BlobSource ​

Properties ​

blobState$()? ​

optional blobState$: (key) => Observable<BlobState> | null

Parameters ​
key ​

string

Returns ​

Observable<BlobState> | null

delete() ​

delete: (key) => Promise<void>

Parameters ​
key ​

string

Returns ​

Promise<void>

get() ​

get: (key) => Promise<Blob | null>

Parameters ​
key ​

string

Returns ​

Promise<Blob | null>

list() ​

list: () => Promise<string[]>

Returns ​

Promise<string[]>

name ​

name: string

readonly ​

readonly: boolean

set() ​

set: (key, value) => Promise<string>

Parameters ​
key ​

string

value ​

Blob

Returns ​

Promise<string>

upload()? ​

optional upload: (key) => Promise<boolean>

Parameters ​
key ​

string

Returns ​

Promise<boolean>

BlobState ​

Properties ​

downloading ​

downloading: boolean

errorMessage? ​

optional errorMessage: string | null

needDownload ​

needDownload: boolean

needUpload ​

needUpload: boolean

overSize ​

overSize: boolean

uploading ​

uploading: boolean

BlobStatus ​

Properties ​

isStorageOverCapacity ​

isStorageOverCapacity: boolean

DocEngineStatus ​

Properties ​

main ​

main: DocPeerStatus | null

retrying ​

retrying: boolean

shadows ​

shadows: (DocPeerStatus | null)[]

step ​

step: DocEngineStep

DocPeerStatus ​

Properties ​

loadedDocs ​

loadedDocs: number

pendingPullUpdates ​

pendingPullUpdates: number

pendingPushUpdates ​

pendingPushUpdates: number

step ​

step: DocPeerStep

totalDocs ​

totalDocs: number

DocSource ​

Properties ​

name ​

name: string

for debug

Methods ​

pull() ​

pull(docId, state): Promise<{ data: Uint8Array; state?: Uint8Array<ArrayBufferLike>; } | null> | { data: Uint8Array; state?: Uint8Array<ArrayBufferLike>; } | null

Parameters ​
docId ​

string

state ​

Uint8Array

Returns ​

Promise<{ data: Uint8Array; state?: Uint8Array<ArrayBufferLike>; } | null> | { data: Uint8Array; state?: Uint8Array<ArrayBufferLike>; } | null

push() ​

push(docId, data): void | Promise<void>

Parameters ​
docId ​

string

data ​

Uint8Array

Returns ​

void | Promise<void>

subscribe() ​

subscribe(cb, disconnect): Promise<() => void> | () => void

Subscribe to updates from peer

Parameters ​
cb ​

(docId, data) => void

callback to handle updates

disconnect ​

(reason) => void

callback to handle disconnect, reason can be something like 'network-error'

Returns ​

Promise<() => void> | () => void

unsubscribe function

Variables ​

dbVersion ​

const dbVersion: 1 = 1

DEFAULT_DB_NAME ​

const DEFAULT_DB_NAME: "blocksuite-local" = 'blocksuite-local'

Functions ​

upgradeDB() ​

upgradeDB(db): void

Parameters ​

db ​

IDBPDatabase<BlockSuiteBinaryDB>

Returns ​

void

Copyright © 2022-present Toeverything