pub struct Doc(/* private fields */);
Expand description
A ywasm document type. Documents are most important units of collaborative resources management. All shared collections live within a scope of their corresponding documents. All updates are generated on per-document basis (rather than individual shared type). All operations on shared collections happen via YTransaction, which lifetime is also bound to a document.
Document manages so-called root types, which are top-level shared types definitions (as opposed to recursively nested types).
A basic workflow sample:
import YDoc from 'ywasm'
const doc = new YDoc()
const txn = doc.beginTransaction()
try {
const text = txn.getText('name')
text.push(txn, 'hello world')
const output = text.toString(txn)
console.log(output)
} finally {
txn.free()
}
Implementations§
source§impl YDoc
impl YDoc
sourcepub fn new(options: &JsValue) -> Result<YDoc, JsValue>
pub fn new(options: &JsValue) -> Result<YDoc, JsValue>
Creates a new ywasm document. If id
parameter was passed it will be used as this document
globally unique identifier (it’s up to caller to ensure that requirement). Otherwise it will
be assigned a randomly generated number.
pub fn get_type(&self) -> u8
sourcepub fn prelim(&self) -> bool
pub fn prelim(&self) -> bool
Checks if a document is a preliminary type. It returns false, if current document is already a sub-document of another document.
sourcepub fn parent_doc(&self) -> Option<YDoc>
pub fn parent_doc(&self) -> Option<YDoc>
Returns a parent document of this document or null if current document is not sub-document.
pub fn should_load(&self) -> bool
pub fn auto_load(&self) -> bool
sourcepub fn transaction(&self, origin: JsValue) -> YTransaction
pub fn transaction(&self, origin: JsValue) -> YTransaction
Returns a new transaction for this document. 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.transaction()
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'))
sourcepub fn get_text(&self, name: &str) -> YText
pub fn get_text(&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.
sourcepub fn get_array(&self, name: &str) -> YArray
pub fn get_array(&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.
sourcepub fn get_map(&self, name: &str) -> YMap
pub fn get_map(&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.
sourcepub fn get_xml_fragment(&self, name: &str) -> YXmlFragment
pub fn get_xml_fragment(&self, name: &str) -> YXmlFragment
Returns a YXmlFragment
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 YXmlFragment
instance.
sourcepub fn on_update(&self, f: Function) -> Result<Observer, JsValue>
pub fn on_update(&self, f: Function) -> Result<Observer, JsValue>
Subscribes given function to be called any time, a remote update is being applied to this
document. Function takes an Uint8Array
as a parameter which contains a lib0 v1 encoded
update.
Returns an observer, which can be freed in order to unsubscribe this callback.
sourcepub fn on_update_v2(&self, f: Function) -> Result<Observer, JsValue>
pub fn on_update_v2(&self, f: Function) -> Result<Observer, JsValue>
Subscribes given function to be called any time, a remote update is being applied to this
document. Function takes an Uint8Array
as a parameter which contains a lib0 v2 encoded
update.
Returns an observer, which can be freed in order to unsubscribe this callback.
sourcepub fn on_after_transaction(&self, f: Function) -> Result<Observer, JsValue>
pub fn on_after_transaction(&self, f: Function) -> Result<Observer, JsValue>
Subscribes given function to be called, whenever a transaction created by this document is being committed.
Returns an observer, which can be freed in order to unsubscribe this callback.
sourcepub fn on_subdocs(&self, f: Function) -> Result<Observer, JsValue>
pub fn on_subdocs(&self, f: Function) -> Result<Observer, JsValue>
Subscribes given function to be called, whenever a subdocuments are being added, removed or loaded as children of a current document.
Returns an observer, which can be freed in order to unsubscribe this callback.
sourcepub fn on_destroy(&self, f: Function) -> Result<Observer, JsValue>
pub fn on_destroy(&self, f: Function) -> Result<Observer, JsValue>
Subscribes given function to be called, whenever current document is being destroyed.
Returns an observer, which can be freed in order to unsubscribe this callback.
sourcepub fn load(&self, parent_txn: &ImplicitTransaction) -> Result<(), JsValue>
pub fn load(&self, parent_txn: &ImplicitTransaction) -> Result<(), JsValue>
Notify the parent document that you request to load data into this subdocument (if it is a subdocument).
sourcepub fn destroy(&self, parent_txn: &ImplicitTransaction) -> Result<(), JsValue>
pub fn destroy(&self, parent_txn: &ImplicitTransaction) -> Result<(), JsValue>
Emit onDestroy
event and unregister all event handlers.
sourcepub fn subdocs(&self, txn: &ImplicitTransaction) -> Result<Array, JsValue>
pub fn subdocs(&self, txn: &ImplicitTransaction) -> Result<Array, JsValue>
Returns a list of sub-documents existings within the scope of this document.
sourcepub fn subdoc_guids(&self, txn: &ImplicitTransaction) -> Result<Set, JsValue>
pub fn subdoc_guids(&self, txn: &ImplicitTransaction) -> Result<Set, JsValue>
Returns a list of unique identifiers of the sub-documents existings within the scope of this document.
sourcepub fn roots(&self, txn: &ImplicitTransaction) -> Result<Array, JsValue>
pub fn roots(&self, txn: &ImplicitTransaction) -> Result<Array, JsValue>
Returns a list of all root-level replicated collections, together with their types.
These collections can then be accessed via getMap
/getText
etc. methods.
Example:
import * as Y from 'ywasm'
const doc = new Y.YDoc()
const ymap = doc.getMap('a')
const yarray = doc.getArray('b')
const ytext = doc.getText('c')
const yxml = doc.getXmlFragment('d')
const roots = doc.roots() // [['a',ymap], ['b',yarray], ['c',ytext], ['d',yxml]]
Methods from Deref<Target = Doc>§
sourcepub fn client_id(&self) -> u64
pub fn client_id(&self) -> u64
A unique client identifier, that’s also a unique identifier of current document replica and it’s subdocuments.
sourcepub fn guid(&self) -> &Arc<str>
pub fn guid(&self) -> &Arc<str>
A globally unique identifier, that’s also a unique identifier of current document replica, and unlike Doc::client_id it’s not shared with its subdocuments.
sourcepub fn get_or_insert_text<N>(&self, name: N) -> TextRef
pub fn get_or_insert_text<N>(&self, name: N) -> TextRef
Returns a TextRef 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 no 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).
§Panics
This method requires exclusive access to an underlying document store. If there is another transaction in process, it will panic. It’s advised to define all root shared types during the document creation.
sourcepub fn get_or_insert_map<N>(&self, name: N) -> MapRef
pub fn get_or_insert_map<N>(&self, name: N) -> MapRef
Returns a MapRef data structure stored under a given name
. Maps are used to store key-value
pairs associated. 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 no 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).
§Panics
This method requires exclusive access to an underlying document store. If there is another transaction in process, it will panic. It’s advised to define all root shared types during the document creation.
sourcepub fn get_or_insert_array<N>(&self, name: N) -> ArrayRef
pub fn get_or_insert_array<N>(&self, name: N) -> ArrayRef
Returns an ArrayRef 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 no 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).
§Panics
This method requires exclusive access to an underlying document store. If there is another transaction in process, it will panic. It’s advised to define all root shared types during the document creation.
sourcepub fn get_or_insert_xml_fragment<N>(&self, name: N) -> XmlFragmentRef
pub fn get_or_insert_xml_fragment<N>(&self, name: N) -> XmlFragmentRef
Returns a XmlFragmentRef 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)
and other nested XML elements or text values, which are stored in their insertion
order.
If no 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).
§Panics
This method requires exclusive access to an underlying document store. If there is another transaction in process, it will panic. It’s advised to define all root shared types during the document creation.
sourcepub fn observe_update_v1<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
pub fn observe_update_v1<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
Subscribe callback function for any changes performed within transaction scope. These changes are encoded using lib0 v1 encoding and can be decoded using [Update::decode_v1] if necessary or passed to remote peers right away. This callback is triggered on function commit.
Returns a subscription, which will unsubscribe function when dropped.
sourcepub fn observe_update_v2<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
pub fn observe_update_v2<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
Subscribe callback function for any changes performed within transaction scope. These changes are encoded using lib0 v2 encoding and can be decoded using [Update::decode_v2] if necessary or passed to remote peers right away. This callback is triggered on function commit.
Returns a subscription, which will unsubscribe function when dropped.
sourcepub fn observe_transaction_cleanup<F>(
&self,
f: F
) -> Result<Subscription, BorrowMutError>
pub fn observe_transaction_cleanup<F>( &self, f: F ) -> Result<Subscription, BorrowMutError>
Subscribe callback function to updates on the Doc
. The callback will receive state updates and
deletions when a document transaction is committed.
pub fn observe_after_transaction<F>(
&self,
f: F
) -> Result<Subscription, BorrowMutError>where
F: Fn(&mut TransactionMut<'_>) + 'static,
sourcepub fn observe_subdocs<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
pub fn observe_subdocs<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
Subscribe callback function, that will be called whenever a subdocuments inserted in this Doc will request a load.
sourcepub fn observe_destroy<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
pub fn observe_destroy<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
Subscribe callback function, that will be called whenever a [DocRef::destroy] has been called.
sourcepub fn load<T>(&self, parent_txn: &mut T)where
T: WriteTxn,
pub fn load<T>(&self, parent_txn: &mut T)where
T: WriteTxn,
Sends a load request to a parent document. Works only if current document is a sub-document of an another document.
sourcepub fn destroy<T>(&self, parent_txn: &mut T)where
T: WriteTxn,
pub fn destroy<T>(&self, parent_txn: &mut T)where
T: WriteTxn,
Starts destroy procedure for a current document, triggering an “destroy” callback and invalidating all event callback subscriptions.
sourcepub fn parent_doc(&self) -> Option<Doc>
pub fn parent_doc(&self) -> Option<Doc>
If current document has been inserted as a sub-document, returns a reference to a parent document, which contains it.
pub fn branch_id(&self) -> Option<BranchID>
Trait Implementations§
source§impl FromWasmAbi for YDoc
impl FromWasmAbi for YDoc
source§impl IntoWasmAbi for YDoc
impl IntoWasmAbi for YDoc
source§impl LongRefFromWasmAbi for YDoc
impl LongRefFromWasmAbi for YDoc
source§impl OptionFromWasmAbi for YDoc
impl OptionFromWasmAbi for YDoc
source§impl OptionIntoWasmAbi for YDoc
impl OptionIntoWasmAbi for YDoc
source§impl RefFromWasmAbi for YDoc
impl RefFromWasmAbi for YDoc
source§impl RefMutFromWasmAbi for YDoc
impl RefMutFromWasmAbi for YDoc
source§impl TryFromJsValue for YDoc
impl TryFromJsValue for YDoc
source§impl VectorFromWasmAbi for YDoc
impl VectorFromWasmAbi for YDoc
source§impl VectorIntoWasmAbi for YDoc
impl VectorIntoWasmAbi for YDoc
Auto Trait Implementations§
impl Freeze for YDoc
impl !RefUnwindSafe for YDoc
impl Send for YDoc
impl Sync for YDoc
impl Unpin for YDoc
impl !UnwindSafe for YDoc
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> ReturnWasmAbi for Twhere
T: IntoWasmAbi,
impl<T> ReturnWasmAbi for Twhere
T: IntoWasmAbi,
§type Abi = <T as IntoWasmAbi>::Abi
type Abi = <T as IntoWasmAbi>::Abi
IntoWasmAbi::Abi
source§fn return_abi(self) -> <T as ReturnWasmAbi>::Abi
fn return_abi(self) -> <T as ReturnWasmAbi>::Abi
IntoWasmAbi::into_abi
, except that it may throw and never
return in the case of Err
.