Awareness

Awareness は、オプショナルな機能です。 Yjs を使うにあたり、実装必須ではありません。

Awareness は、 y-protocols （https://github.com/yjs/y-protocols）に定義されており、 Provider ごと（Websocket とか WebRTC とかの接続方法ごと）に実装が異なります。

もし、独自の Provider 実装したい場合は、 Awareness CRDT プロトコルに従って実装することもできますし、独自のプロトコルを実装することで、Awareness CRDT と同じ仕組みを作ることも可能です。

Awareness CRDT

import * as awarenessProtocol from 'y-protocols/awareness.js'

Awareness プロトコルは、「誰がオンラインなのか？」といったユーザーのステータスや、カーソルの位置、ユーザー名、メールアドレスなどの情報を共有します。各クライアントは、これらの変更を listen します。

クライアントごとに Awareness の state を持ちます。Awareness の state は、Mapで保持されます。キーがクライアントのIDで、値が state になります。 state が変化すると clock という値が増加します。state は JSON オブジェクトで保持されます。

Awareness CRDT API

awareness = new awarenessProtocol.Awareness(ydoc)

// 通常、 awareness は provider によって生成・更新されます
awareness = provider.awareness

awareness = new awarenessProtocol.Awareness(ydoc: Y.Doc)

新しい Awareness インスタンスを生成します。

awareness.clientID: number

クライアントごとに異なるID

awareness.destroy()

Awareness インスタンスを破棄し、全てのイベントハンドラと状態を破棄します。

awareness.getLocalState(): Object<string, any> | null

ローカルの Awareness state を参照します

awareness.setLocalState(state: Object<string, any>)

ローカルの Awareness state を更新します。 null をセットすると、クライアントはオフラインになります。 state オブジェクトは、key-value ストアで、JSON に変換可能な値である必要があります。

awareness.setLocalStateField(string, any)

指定した key に対応するローカル Awareness state を更新します。

awareness.getStates(): Map<string, Object<string, any>>

全ての Awareness state （リモートとローカル）を取得します。Map形式で、key が clientID で、値が Awarenes state になります。

awareness.on('update', ({ added: Array, updated: Array removed: Array }, [transactionOrigin:any]) => ..)

リモートとローカルの Awareness の変更を listen します。Awareness state が変更されなくても、ユーザーのオンライン状態をチェックするために、イベントが呼ばれることがあります。Awareness state の変更を他のユーザーに通知したい場合はこの update イベントを利用します。

awareness.on('change', ({ added: Array, updated: Array removed: Array }, [transactionOrigin:any]) => ..)

リモートとローカルの Awareness state の変更を listen します。stage が追加、更新、あるいは削除された場合にのみ呼ばれます。

Awareness Protocol

Awareness プロトコルは、多くの Provider に実装されています。Awareness CRDT を使うことにより、カーソルの位置の変化などの情報を得ることができます。Awarenessプロトコルを実装するのは必須ではありませんが、Yjs を使うなら Awareness プロトコルを実装することをお勧めします。もし、自作の Provider に Awareness プロトコルを実装したいのであれば、この章を読んでください。

（CRDT に Awareness Protocol をのっけたものが Awareness CRDT っぽい）

以下略。。。基本的に Yjs から提供されているプロバイダを使えば問題ないが、独自で実装したい場合はこれを読みながら実装することになりそう。

本文を読んでください。

docs.yjs.dev