添加中文文档

Author: wangc

.gitignore

@@ -1,4 +1,3 @@
 node_modules
 dist
 .vscode
-docs

docs/INTERNALS.md

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2023
+  - Kevin Jahns <kevin.jahns@protonmail.com>.
+  - Chair of Computer Science 5 (Databases & Information Systems), RWTH Aachen University, Germany
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/LICENSE

@@ -0,0 +1,95 @@
+# Yjs CRDT 算法
+
+**Yjs CRDT Algorithm**
+
+=== "中文"
+
+    *无冲突复制数据类型*（CRDT）用于协作编辑，是*操作变换*（OT）的替代方法。两者的简单区分在于，OT 尝试转换索引位置以确保收敛（所有客户端最终拥有相同内容），而 CRDT 则使用通常不涉及索引转换的数学模型，例如链表。OT 目前是文本共享编辑的事实标准。支持无中央真实来源（中央服务器）的共享编辑的 OT 方法在实际操作中需要过多的记录管理，因而不太可行。CRDT 更适合分布式系统，提供了额外的保证，确保文档可以与远程客户端同步，并且不需要中央真实来源。
+    
+    Yjs 实现了该算法的修改版，详细信息可参考 [这篇论文](https://www.researchgate.net/publication/310212186_Near_Real-Time_Peer-to-Peer_Shared_Editing_on_Extensible_Data_Types)。这篇 [文章](https://blog.kevinjahns.de/are-crdts-suitable-for-shared-editing/) 解释了 CRDT 模型的简单优化，并提供了有关 Yjs 性能特征的更多见解。关于具体实现的更多信息，请参见 [INTERNALS.md](./INTERNALS.md) 和 [Yjs 代码库的此指南](https://youtu.be/0l5XgnQ6rB4)。
+    
+    适合共享文本编辑的 CRDT 存在只能不断增长的缺陷。虽然存在不增长的 CRDT，但它们不具备对共享文本编辑有利的特性（如意图保留）。Yjs 实现了许多对原始算法的改进，减轻了文档仅增长的缺陷。我们无法在确保结构唯一顺序的同时回收已删除的结构（墓碑）。但我们可以 1. 将前面的结构合并为单个结构，以减少元信息的数量，2. 如果内容被删除，则可以从结构中删除内容，3. 如果我们不再关心结构的顺序，则可以回收墓碑（例如，如果父级被删除）。
+    
+    **示例：**
+    
+    1. 如果用户按顺序插入元素，则结构将合并为一个单一结构。例如 `text.insert(0, 'a'), text.insert(1, 'b');` 首先表示为两个结构 (`[{id: {client, clock: 0}, content: 'a'}, {id: {client, clock: 1}, content: 'b'}]`)，然后合并为一个结构：`[{id: {client, clock: 0}, content: 'ab'}]`。
+    2. 当包含内容的结构（例如 `ItemString`）被删除时，该结构将被替换为不再包含内容的 `ItemDeleted`。
+    3. 当类型被删除时，所有子元素都会转换为 `GC` 结构。`GC` 结构仅表示结构的存在及其被删除。`GC` 结构可以与其他 `GC` 结构合并，只要它们的 id 相邻。
+    
+    特别是在处理结构化内容时（例如在 ProseMirror 上进行共享编辑），这些改进在 [基准测试](https://github.com/dmonad/crdt-benchmarks) 随机文档编辑时表现出良好的结果。在实践中，它们显示出更好的效果，因为用户通常按顺序编辑文本，从而生成可以轻松合并的结构。基准测试表明，即使在用户从右到左编辑文本的最坏情况下，Yjs 对于大型文档也能保持良好的性能。
+
+=== "英文"
+
+    *Conflict-free replicated data types* (CRDT) for collaborative editing are an
+    alternative approach to *operational transformation* (OT). A very simple
+    differentiation between the two approaches is that OT attempts to transform
+    index positions to ensure convergence (all clients end up with the same
+    content), while CRDTs use mathematical models that usually do not involve index
+    transformations, like linked lists. OT is currently the de-facto standard for
+    shared editing on text. OT approaches that support shared editing without a
+    central source of truth (a central server) require too much bookkeeping to be
+    viable in practice. CRDTs are better suited for distributed systems, provide
+    additional guarantees that the document can be synced with remote clients, and
+    do not require a central source of truth.
+    
+    Yjs implements a modified version of the algorithm described in [this
+    paper](https://www.researchgate.net/publication/310212186_Near_Real-Time_Peer-to-Peer_Shared_Editing_on_Extensible_Data_Types).
+    This [article](https://blog.kevinjahns.de/are-crdts-suitable-for-shared-editing/)
+    explains a simple optimization on the CRDT model and
+    gives more insight about the performance characteristics in Yjs.
+    More information about the specific implementation is available in
+    [INTERNALS.md](./INTERNALS.md) and in
+    [this walkthrough of the Yjs codebase](https://youtu.be/0l5XgnQ6rB4).
+    
+    CRDTs that are suitable for shared text editing suffer from the fact that they
+    only grow in size. There are CRDTs that do not grow in size, but they do not
+    have the characteristics that are benificial for shared text editing (like
+    intention preservation). Yjs implements many improvements to the original
+    algorithm that diminish the trade-off that the document only grows in size. We
+    can't garbage collect deleted structs (tombstones) while ensuring a unique
+    order of the structs. But we can 1. merge preceeding structs into a single
+    struct to reduce the amount of meta information, 2. we can delete content from
+    the struct if it is deleted, and 3. we can garbage collect tombstones if we
+    don't care about the order of the structs anymore (e.g. if the parent was
+    deleted).
+    
+    **Examples:**
+    
+    1. If a user inserts elements in sequence, the struct will be merged into a
+       single struct. E.g. `text.insert(0, 'a'), text.insert(1, 'b');` is
+       first represented as two structs (`[{id: {client, clock: 0}, content: 'a'},
+       {id: {client, clock: 1}, content: 'b'}`) and then merged into a single
+       struct: `[{id: {client, clock: 0}, content: 'ab'}]`.
+    2. When a struct that contains content (e.g. `ItemString`) is deleted, the
+       struct will be replaced with an `ItemDeleted` that does not contain content
+       anymore.
+    3. When a type is deleted, all child elements are transformed to `GC` structs. A
+       `GC` struct only denotes the existence of a struct and that it is deleted.
+       `GC` structs can always be merged with other `GC` structs if the id's are
+       adjacent.
+    
+    Especially when working on structured content (e.g. shared editing on
+    ProseMirror), these improvements yield very good results when
+    [benchmarking](https://github.com/dmonad/crdt-benchmarks) random document edits.
+    In practice they show even better results, because users usually edit text in
+    sequence, resulting in structs that can easily be merged. The benchmarks show
+    that even in the worst case scenario that a user edits text from right to left,
+    Yjs achieves good performance even for huge documents.
+
+## 状态向量
+
+=== "中文"
+    
+    Yjs 能够在同步两个客户端时仅交换差异。我们使用 Lamport 时间戳来标识结构，并跟踪客户端创建它们的顺序。每个结构都有一个 `struct.id = { client: number, clock: number}`，唯一标识一个结构。我们定义每个客户端的下一个预期 `clock` 为 *状态向量*。该数据结构类似于 [版本向量](https://en.wikipedia.org/wiki/Version_vector) 数据结构。但我们使用状态向量仅用于描述本地文档的状态，以便计算远程客户端缺失的结构。我们不使用它来跟踪因果关系。
+
+=== "英文"
+
+    Yjs has the ability to exchange only the differences when syncing two clients.
+    We use lamport timestamps to identify structs and to track in which order a
+    client created them. Each struct has an `struct.id = { client: number, clock:
+    number}` that uniquely identifies a struct. We define the next expected `clock`
+    by each client as the *state vector*. This data structure is similar to the
+    [version vectors](https://en.wikipedia.org/wiki/Version_vector) data structure.
+    But we use state vectors only to describe the state of the local document, so we
+    can compute the missing struct of the remote client. We do not use it to track
+    causality.

docs/api.md

@@ -0,0 +1,196 @@
+# 入门
+
+**Getting Started**
+
+=== "中文"
+
+    使用您喜欢的包管理器安装 Yjs 和提供者：
+
+    ```sh
+    npm i yjs y-websocket
+    ```
+    
+    启动 y-websocket 服务器：
+    
+    ```sh
+    PORT=1234 node ./node_modules/y-websocket/bin/server.cjs
+    ```
+
+=== "英文"
+
+    Install Yjs and a provider with your favorite package manager:
+    
+    ```sh
+    npm i yjs y-websocket
+    ```
+    
+    Start the y-websocket server:
+    
+    ```sh
+    PORT=1234 node ./node_modules/y-websocket/bin/server.cjs
+    ```
+
+## 示例：观察类型
+
+**Example: Observe types**
+
+
+=== "中文"
+    
+    ```js
+    import * as Y from 'yjs';
+    
+    const doc = new Y.Doc();
+    const yarray = doc.getArray('my-array')
+    yarray.observe(event => {
+      console.log('yarray 被修改了')
+    })
+    // 每当本地或远程客户端修改 yarray 时，观察者都会被调用
+    yarray.insert(0, ['val']) // => "yarray 被修改了"
+    ```
+
+=== "英文"
+
+    ```js
+    import * as Y from 'yjs';
+    
+    const doc = new Y.Doc();
+    const yarray = doc.getArray('my-array')
+    yarray.observe(event => {
+      console.log('yarray was modified')
+    })
+    // every time a local or remote client modifies yarray, the observer is called
+    yarray.insert(0, ['val']) // => "yarray was modified"
+    ```
+
+## 示例：嵌套类型
+
+**Example: Nest types**
+
+=== "中文"
+
+    请记住，共享类型只是普通的数据类型。唯一的限制是共享类型在共享文档中必须只存在一次。
+    
+    ```js
+    const ymap = doc.getMap('map')
+    const foodArray = new Y.Array()
+    foodArray.insert(0, ['apple', 'banana'])
+    ymap.set('food', foodArray)
+    ymap.get('food') === foodArray // => true
+    ymap.set('fruit', foodArray) // => 错误！foodArray 已经被定义
+    ```
+    
+    现在你了解了如何在共享文档上定义类型。接下来你可以跳转到 [演示仓库](https://github.com/yjs/yjs-demos) 或继续阅读 API 文档。
+
+=== "英文"
+
+    Remember, shared types are just plain old data types. The only limitation is
+    that a shared type must exist only once in the shared document.
+    
+    ```js
+    const ymap = doc.getMap('map')
+    const foodArray = new Y.Array()
+    foodArray.insert(0, ['apple', 'banana'])
+    ymap.set('food', foodArray)
+    ymap.get('food') === foodArray // => true
+    ymap.set('fruit', foodArray) // => Error! foodArray is already defined
+    ```
+    
+    Now you understand how types are defined on a shared document. Next you can jump
+    to the [demo repository](https://github.com/yjs/yjs-demos) or continue reading
+    the API docs.
+
+## 示例：使用和组合提供者
+
+**Example: Using and combining providers**
+
+=== "中文"
+
+    任何 Yjs 提供者都可以相互组合。因此你可以通过不同的网络技术同步数据。
+    
+    在大多数情况下，你希望将网络提供者（如 y-websocket 或 y-webrtc）与持久化提供者（浏览器中的 y-indexeddb）结合使用。持久化允许你更快地加载文档，并在离线时持久化创建的数据。
+    
+    为了演示，我们将两个不同的网络提供者与一个持久化提供者结合使用。
+    
+    ```js
+    import * as Y from 'yjs'
+    import { WebrtcProvider } from 'y-webrtc'
+    import { WebsocketProvider } from 'y-websocket'
+    import { IndexeddbPersistence } from 'y-indexeddb'
+    
+    const ydoc = new Y.Doc()
+    
+    // 这允许你立即获取（缓存的）文档数据
+    const indexeddbProvider = new IndexeddbPersistence('count-demo', ydoc)
+    indexeddbProvider.whenSynced.then(() => {
+      console.log('从索引数据库加载的数据')
+    })
+    
+    // 使用 y-webrtc 提供者同步客户端。
+    const webrtcProvider = new WebrtcProvider('count-demo', ydoc)
+    
+    // 使用 y-websocket 提供者同步客户端
+    const websocketProvider = new WebsocketProvider(
+      'wss://demos.yjs.dev', 'count-demo', ydoc
+    )
+    
+    // 生成和计算总和的数字数组
+    const yarray = ydoc.getArray('count')
+    
+    // 观察总和的变化
+    yarray.observe(event => {
+      // 当数据变化时打印更新
+      console.log('新总和: ' + yarray.toArray().reduce((a,b) => a + b))
+    })
+    
+    // 将 1 加到总和中
+    yarray.push([1]) // => "新总和: 1"
+    ```
+
+=== "英文"
+    
+    Any of the Yjs providers can be combined with each other. So you can sync data
+    over different network technologies.
+    
+    In most cases you want to use a network provider (like y-websocket or y-webrtc)
+    in combination with a persistence provider (y-indexeddb in the browser).
+    Persistence allows you to load the document faster and to persist data that is
+    created while offline.
+    
+    For the sake of this demo we combine two different network providers with a
+    persistence provider.
+    
+    ```js
+    import * as Y from 'yjs'
+    import { WebrtcProvider } from 'y-webrtc'
+    import { WebsocketProvider } from 'y-websocket'
+    import { IndexeddbPersistence } from 'y-indexeddb'
+    
+    const ydoc = new Y.Doc()
+    
+    // this allows you to instantly get the (cached) documents data
+    const indexeddbProvider = new IndexeddbPersistence('count-demo', ydoc)
+    indexeddbProvider.whenSynced.then(() => {
+      console.log('loaded data from indexed db')
+    })
+    
+    // Sync clients with the y-webrtc provider.
+    const webrtcProvider = new WebrtcProvider('count-demo', ydoc)
+    
+    // Sync clients with the y-websocket provider
+    const websocketProvider = new WebsocketProvider(
+      'wss://demos.yjs.dev', 'count-demo', ydoc
+    )
+    
+    // array of numbers which produce a sum
+    const yarray = ydoc.getArray('count')
+    
+    // observe changes of the sum
+    yarray.observe(event => {
+      // print updates when the data changes
+      console.log('new sum: ' + yarray.toArray().reduce((a,b) => a + b))
+    })
+    
+    // add 1 to the sum
+    yarray.push([1]) // => "new sum: 1"
+    ```