Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Issue #26 - Add support for passing a different state encoder to expo… #28

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Issue #26 - Add support for passing a different state encoder to expo… #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 58 additions & 7 deletions awareness.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,54 @@ export class Awareness extends Observable {
}
}

/**
* A state encoder that serializes state into JSON.
*
* This is the default strategy used in this package.
*/
export class DefaultAwarenessStateEncoder {
/**
* Encode an awareness state entry
* @param {encoding.Encoder} encoder
* @param {any} update
*/
static encodeState (encoder, update) {
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've moved these to static.

A different pattern we could consider here is to instead instantiate a copy of this class and store it on an exported constant. I'm happy to change to that if you'd prefer.

encoding.writeVarString(encoder, JSON.stringify(update))
}

/**
* Decode an awareness state entry
* @param {decoding.Decoder} decoder
* @returns {string}
*/
static decodeState (decoder) {
return JSON.parse(decoding.readVarString(decoder))
}
}

/**
* A state encoder that serializes state into a binary format.
*/
export class BinaryAwarenessStateEncoder {
/**
* Encode an awareness state entry
* @param {encoding.Encoder} encoder
* @param {any} update
*/
static encodeState (encoder, update) {
encoding.writeAny(encoder, update)
}

/**
* Decode an awareness state entry
* @param {decoding.Decoder} decoder
* @returns {any}
*/
static decodeState (decoder) {
return decoding.readAny(decoder)
}
}

/**
* Mark (remote) clients as inactive and remove them from the list of active peers.
* This change will be propagated to remote clients.
Expand Down Expand Up @@ -189,9 +237,10 @@ export const removeAwarenessStates = (awareness, clients, origin) => {
/**
* @param {Awareness} awareness
* @param {Array<number>} clients
* @param {typeof DefaultAwarenessStateEncoder|typeof BinaryAwarenessStateEncoder} stateEncoder The encoder to use for encoding and decoding each state entry
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't use jsdoc types a lot, but my understanding is that typeof Blah is the best way to describe a constructor.

Another way to type this would be to instead type the "interface" expected - but that would make changes to the requirements of the encoder a breaking change.

* @return {Uint8Array}
*/
export const encodeAwarenessUpdate = (awareness, clients, states = awareness.states) => {
export const encodeAwarenessUpdate = (awareness, clients, states = awareness.states, stateEncoder = DefaultAwarenessStateEncoder) => {
const len = clients.length
const encoder = encoding.createEncoder()
encoding.writeVarUint(encoder, len)
Expand All @@ -201,7 +250,7 @@ export const encodeAwarenessUpdate = (awareness, clients, states = awareness.sta
const clock = /** @type {MetaClientState} */ (awareness.meta.get(clientID)).clock
encoding.writeVarUint(encoder, clientID)
encoding.writeVarUint(encoder, clock)
encoding.writeVarString(encoder, JSON.stringify(state))
stateEncoder.encodeState(encoder, state)
}
return encoding.toUint8Array(encoder)
}
Expand All @@ -214,21 +263,22 @@ export const encodeAwarenessUpdate = (awareness, clients, states = awareness.sta
*
* @param {Uint8Array} update
* @param {function(any):any} modify
* @param {typeof DefaultAwarenessStateEncoder|typeof BinaryAwarenessStateEncoder} stateEncoder The encoder to use for encoding and decoding each state entry
* @return {Uint8Array}
*/
export const modifyAwarenessUpdate = (update, modify) => {
export const modifyAwarenessUpdate = (update, modify, stateEncoder = DefaultAwarenessStateEncoder) => {
const decoder = decoding.createDecoder(update)
const encoder = encoding.createEncoder()
const len = decoding.readVarUint(decoder)
encoding.writeVarUint(encoder, len)
for (let i = 0; i < len; i++) {
const clientID = decoding.readVarUint(decoder)
const clock = decoding.readVarUint(decoder)
const state = JSON.parse(decoding.readVarString(decoder))
const state = stateEncoder.decodeState(decoder)
const modifiedState = modify(state)
encoding.writeVarUint(encoder, clientID)
encoding.writeVarUint(encoder, clock)
encoding.writeVarString(encoder, JSON.stringify(modifiedState))
stateEncoder.encodeState(encoder, modifiedState)
}
return encoding.toUint8Array(encoder)
}
Expand All @@ -237,8 +287,9 @@ export const modifyAwarenessUpdate = (update, modify) => {
* @param {Awareness} awareness
* @param {Uint8Array} update
* @param {any} origin This will be added to the emitted change event
* @param {typeof DefaultAwarenessStateEncoder|typeof BinaryAwarenessStateEncoder} stateEncoder The encoder to use for encoding each state entry
*/
export const applyAwarenessUpdate = (awareness, update, origin) => {
export const applyAwarenessUpdate = (awareness, update, origin, stateEncoder = DefaultAwarenessStateEncoder) => {
const decoder = decoding.createDecoder(update)
const timestamp = time.getUnixTime()
const added = []
Expand All @@ -249,7 +300,7 @@ export const applyAwarenessUpdate = (awareness, update, origin) => {
for (let i = 0; i < len; i++) {
const clientID = decoding.readVarUint(decoder)
let clock = decoding.readVarUint(decoder)
const state = JSON.parse(decoding.readVarString(decoder))
const state = stateEncoder.decodeState(decoder)
const clientMeta = awareness.meta.get(clientID)
const prevState = awareness.states.get(clientID)
const currClock = clientMeta === undefined ? 0 : clientMeta.clock
Expand Down
15 changes: 11 additions & 4 deletions awareness.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,20 @@ import * as t from 'lib0/testing'
import * as awareness from './awareness'

/**
* @param {t.TestCase} tc
* @param {typeof awareness.DefaultAwarenessStateEncoder|typeof awareness.BinaryAwarenessStateEncoder} encoder
* @param {typeof awareness.DefaultAwarenessStateEncoder|typeof awareness.BinaryAwarenessStateEncoder} decoder
* @return {function(t.TestCase): void}
*/
export const testAwareness = tc => {
const testAwarenessWithEncoding = (encoder = awareness.DefaultAwarenessStateEncoder, decoder = awareness.DefaultAwarenessStateEncoder) => tc => {
const doc1 = new Y.Doc()
doc1.clientID = 0
const doc2 = new Y.Doc()
doc2.clientID = 1
const aw1 = new awareness.Awareness(doc1)
const aw2 = new awareness.Awareness(doc2)
aw1.on('update', /** @param {any} p */ ({ added, updated, removed }) => {
const enc = awareness.encodeAwarenessUpdate(aw1, added.concat(updated).concat(removed))
awareness.applyAwarenessUpdate(aw2, enc, 'custom')
const enc = awareness.encodeAwarenessUpdate(aw1, added.concat(updated).concat(removed), aw1.states, encoder)
awareness.applyAwarenessUpdate(aw2, enc, 'custom', decoder)
})
let lastChangeLocal = /** @type {any} */ (null)
aw1.on('change', /** @param {any} change */ change => {
Expand Down Expand Up @@ -51,3 +53,8 @@ export const testAwareness = tc => {
t.compare(aw1.getStates().get(0), undefined)
t.compare(lastChangeLocal, lastChange)
}

export const testAwarenessWithBinary = testAwarenessWithEncoding(awareness.BinaryAwarenessStateEncoder, awareness.BinaryAwarenessStateEncoder)
export const testAwarenessWithDefault = testAwarenessWithEncoding(awareness.DefaultAwarenessStateEncoder, awareness.DefaultAwarenessStateEncoder)
export const testAwarenessBackwardsCompatDecoder = testAwarenessWithEncoding(awareness.DefaultAwarenessStateEncoder, undefined)
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've swapped the original "default" test I had, and instead replaced it with two tests to verify that the default encoder is used if none is passed into the methods.

export const testAwarenessBackwardsCompatEncoder = testAwarenessWithEncoding(undefined, awareness.DefaultAwarenessStateEncoder)