Struct ywasm::YTransaction

pub struct YTransaction(_);

A transaction that serves as a proxy to document block store. Ywasm shared data types execute their operations in a context of a given transaction. Each document can have only one active transaction at the time - subsequent attempts will cause exception to be thrown.

Transactions started with doc.beginTransaction can be released using transaction.free method.

Example:

import YDoc from 'ywasm'

// helper function used to simplify transaction
// create/release cycle
YDoc.prototype.transact = callback => {
    const txn = this.beginTransaction()
    try {
        return callback(txn)
    } finally {
        txn.free()
    }
}

const doc = new YDoc()
const text = doc.getText('name')
doc.transact(txn => text.insert(txn, 0, 'hello world'))

Implementations

impl YTransaction

pub fn get_text(&mut self, name: &str) -> YText

Returns a YText shared data type, that’s accessible for subsequent accesses using given name.

If there was no instance with this name before, it will be created and then returned.

If there was an instance with this name, but it was of different type, it will be projected onto YText instance.

pub fn get_array(&mut self, name: &str) -> YArray

Returns a YArray shared data type, that’s accessible for subsequent accesses using given name.

If there was no instance with this name before, it will be created and then returned.

If there was an instance with this name, but it was of different type, it will be projected onto YArray instance.

pub fn get_map(&mut self, name: &str) -> YMap

Returns a YMap shared data type, that’s accessible for subsequent accesses using given name.

If there was no instance with this name before, it will be created and then returned.

If there was an instance with this name, but it was of different type, it will be projected onto YMap instance.

pub fn get_xml_element(&mut self, name: &str) -> YXmlElement

Returns a YXmlElement shared data type, that’s accessible for subsequent accesses using given name.

If there was no instance with this name before, it will be created and then returned.

If there was an instance with this name, but it was of different type, it will be projected onto YXmlElement instance.

pub fn get_xml_text(&mut self, name: &str) -> YXmlText

Returns a YXmlText shared data type, that’s accessible for subsequent accesses using given name.

If there was no instance with this name before, it will be created and then returned.

If there was an instance with this name, but it was of different type, it will be projected onto YXmlText instance.

pub fn commit(&mut self)

Triggers a post-update series of operations without freeing the transaction. This includes compaction and optimization of internal representation of updates, triggering events etc. ywasm transactions are auto-committed when they are freed.

pub fn state_vector_v1(&self) -> Uint8Array

Encodes a state vector of a given transaction document into its binary representation using lib0 v1 encoding. State vector is a compact representation of updates performed on a given document and can be used by encode_state_as_update on remote peer to generate a delta update payload to synchronize changes between peers.

Example:

import YDoc from 'ywasm'

/// document on machine A
const localDoc = new YDoc()
const localTxn = localDoc.beginTransaction()

// document on machine B
const remoteDoc = new YDoc()
const remoteTxn = localDoc.beginTransaction()

try {
    const localSV = localTxn.stateVectorV1()
    const remoteDelta = remoteTxn.diffV1(localSv)
    localTxn.applyV1(remoteDelta)
} finally {
    localTxn.free()
    remoteTxn.free()
}

pub fn diff_v1(&self, vector: Option<Uint8Array>) -> Uint8Array

Encodes all updates that have happened since a given version vector into a compact delta representation using lib0 v1 encoding. If vector parameter has not been provided, generated delta payload will contain all changes of a current ywasm document, working effectively as its state snapshot.

Example:

import YDoc from 'ywasm'

/// document on machine A
const localDoc = new YDoc()
const localTxn = localDoc.beginTransaction()

// document on machine B
const remoteDoc = new YDoc()
const remoteTxn = localDoc.beginTransaction()

try {
    const localSV = localTxn.stateVectorV1()
    const remoteDelta = remoteTxn.diffV1(localSv)
    localTxn.applyV1(remoteDelta)
} finally {
    localTxn.free()
    remoteTxn.free()
}

pub fn apply_v1(&mut self, diff: Uint8Array)

Applies delta update generated by the remote document replica to a current transaction’s document. This method assumes that a payload maintains lib0 v1 encoding format.

Example:

import YDoc from 'ywasm'

/// document on machine A
const localDoc = new YDoc()
const localTxn = localDoc.beginTransaction()

// document on machine B
const remoteDoc = new YDoc()
const remoteTxn = localDoc.beginTransaction()

try {
    const localSV = localTxn.stateVectorV1()
    const remoteDelta = remoteTxn.diffV1(localSv)
    localTxn.applyV1(remoteDelta)
} finally {
    localTxn.free()
    remoteTxn.free()
}

Methods from Deref<Target = Transaction<'static>>

pub fn state_vector(&self) -> StateVector

Returns state vector describing current state of the updates.

pub fn encode_diff<E>(&self, state_vector: &StateVector, encoder: &mut E) where
    E: Encoder, 

Encodes the difference between remove peer state given its state_vector and the state of a current local peer

pub fn get_text(&mut self, name: &str) -> Text

Returns a Text data structure stored under a given name. Text structures are used for collaborative text editing: they expose operations to append and remove chunks of text, which are free to execute concurrently by multiple peers over remote boundaries.

If not structure under defined name existed before, it will be created and returned instead.

If a structure under defined name already existed, but its type was different it will be reinterpreted as a text (in such case a sequence component of complex data type will be interpreted as a list of text chunks).

pub fn get_map(&mut self, name: &str) -> Map

Returns a Map data structure stored under a given name. Maps are used to store key-value pairs associated together. These values can be primitive data (similar but not limited to a JavaScript Object Notation) as well as other shared types (Yrs maps, arrays, text structures etc.), enabling to construct a complex recursive tree structures.

If not structure under defined name existed before, it will be created and returned instead.

If a structure under defined name already existed, but its type was different it will be reinterpreted as a map (in such case a map component of complex data type will be interpreted as native map).

pub fn get_array(&mut self, name: &str) -> Array

Returns an Array data structure stored under a given name. Array structures are used for storing a sequences of elements in ordered manner, positioning given element accordingly to its index.

If not structure under defined name existed before, it will be created and returned instead.

If a structure under defined name already existed, but its type was different it will be reinterpreted as an array (in such case a sequence component of complex data type will be interpreted as a list of inserted values).

pub fn get_xml_element(&mut self, name: &str) -> XmlElement

Returns a XmlElement data structure stored under a given name. XML elements represent nodes of XML document. They can contain attributes (key-value pairs, both of string type) as well as other nested XML elements or text values, which are stored in their insertion order.

If not structure under defined name existed before, it will be created and returned instead.

If a structure under defined name already existed, but its type was different it will be reinterpreted as a XML element (in such case a map component of complex data type will be interpreted as map of its attributes, while a sequence component - as a list of its child XML nodes).

pub fn get_xml_text(&mut self, name: &str) -> XmlText

Returns a XmlText data structure stored under a given name. Text structures are used for collaborative text editing: they expose operations to append and remove chunks of text, which are free to execute concurrently by multiple peers over remote boundaries.

If not structure under defined name existed before, it will be created and returned instead.

If a structure under defined name already existed, but its type was different it will be reinterpreted as a text (in such case a sequence component of complex data type will be interpreted as a list of text chunks).

pub fn encode_update_v1(&self) -> Vec<u8, Global>

Encodes the document state to a binary format.

Document updates are idempotent and commutative. Caveats:

• It doesn’t matter in which order document updates are applied.
• As long as all clients receive the same document updates, all clients end up with the same content.
• Even if an update contains known information, the unknown information is extracted and integrated into the document structure.

pub fn apply_update(&mut self, update: Update)

pub fn commit(&mut self)

Commits current transaction. This step involves cleaning up and optimizing changes performed during lifetime of a transaction. Such changes include squashing delete sets data or squashing blocks that have been appended one after another to preserve memory.

This step is performed automatically when a transaction is about to be dropped (its life scope comes to an end).

Trait Implementations

impl Deref for YTransaction

type Target = Transaction<'static>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for YTransaction

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for YTransaction

fn drop(&mut self)

Executes the destructor for this type.

impl From<YTransaction> for JsValue

fn from(value: YTransaction) -> Self

Performs the conversion.

impl FromWasmAbi for YTransaction

type Abi = u32

The wasm ABI type that this converts from when coming back out from the ABI boundary.

unsafe fn from_abi(js: u32) -> Self

Recover a Self from Self::Abi.

impl IntoWasmAbi for YTransaction

type Abi = u32

The wasm ABI type that this converts into when crossing the ABI boundary.

fn into_abi(self) -> u32

Convert self into Self::Abi so that it can be sent across the wasm ABI boundary.

impl OptionFromWasmAbi for YTransaction

fn is_none(abi: &Self::Abi) -> bool

Tests whether the argument is a “none” instance. If so it will be deserialized as None, and otherwise it will be passed to FromWasmAbi.

impl OptionIntoWasmAbi for YTransaction

fn none() -> Self::Abi

Returns an ABI instance indicating “none”, which JS will interpret as the None branch of this option.

impl RefFromWasmAbi for YTransaction

type Abi = u32

The wasm ABI type references to Self are recovered from.

type Anchor = Ref<'static, YTransaction>

The type that holds the reference to Self for the duration of the invocation of the function that has an &Self parameter. This is required to ensure that the lifetimes don’t persist beyond one function call, and so that they remain anonymous.

unsafe fn ref_from_abi(js: Self::Abi) -> Self::Anchor

Recover a Self::Anchor from Self::Abi.

impl RefMutFromWasmAbi for YTransaction

type Abi = u32

Same as RefFromWasmAbi::Abi

type Anchor = RefMut<'static, YTransaction>

Same as RefFromWasmAbi::Anchor

unsafe fn ref_mut_from_abi(js: Self::Abi) -> Self::Anchor

Same as RefFromWasmAbi::ref_from_abi

impl WasmDescribe for YTransaction

fn describe()