Class LoroMovableList<T>

constructor

• new LoroMovableList<T = unknown>(): LoroMovableList<T>

  Create a new detached LoroMovableList (not attached to any LoroDoc).

  The edits on a detached container will not be persisted. To attach the container to the document, please insert it into an attached container.

  Type Parameters

  • T = unknown

  Returns LoroMovableList<T>

constructor

• new LoroMovableList(): LoroMovableList<T>

  Returns LoroMovableList<T>

Readonlyid

Readonlylength

import { LoroDoc } from "loro-crdt";

const doc = new LoroDoc();
const list = doc.getList("list");
list.insert(0, 100);
list.insert(1, "foo");
list.insert(2, true);
console.log(list.length);  // 3
Copy

clear

• clear(): void

  Delete all elements in the list.

  Returns void

delete

• delete(pos: number, len: number): void

  Parameters

  • pos: number
  • len: number

  Returns void

• delete(index: number, len: number): void

  Delete elements from index to index + len.

  Parameters

  • index: number
  • len: number

  Returns void

  Example

  import { LoroDoc } from "loro-crdt";
  
  const doc = new LoroDoc();
  const list = doc.getList("list");
  list.insert(0, 100);
  list.delete(0, 1);
  console.log(list.value);  // []
  Copy

free

• free(): void

  Returns void

get

• get(index: number): T

  Get the value at the index. If the value is a container, the corresponding handler will be returned.

  Parameters

  • index: number

  Returns T

  Example

   import { LoroDoc } from "loro-crdt";
  
   const doc = new LoroDoc();
   const list = doc.getMovableList("list");
   list.insert(0, 100);
   console.log(list.get(0));  // 100
   console.log(list.get(1));  // undefined
  Copy

getAttached

• getAttached(): LoroMovableList<T>

  Returns LoroMovableList<T>

• getAttached(): LoroList<unknown>

  Get the attached container associated with this.

  Returns an attached Container that equals to this or created by this, otherwise undefined.

  Returns LoroList<unknown>

getCreatorAt

• getCreatorAt(pos: number): `${number}`

  Get the creator of the list item at the given position.

  Parameters

  • pos: number

  Returns `${number}`

getCursor

• getCursor(pos: number, side?: Side): Cursor

  Get the cursor position at the given pos.

  When expressing the position of a cursor, using "index" can be unstable because the cursor's position may change due to other deletions and insertions, requiring updates with each edit. To stably represent a position or range within a list structure, we can utilize the ID of each item/character on List CRDT or Text CRDT for expression.

  Loro optimizes State metadata by not storing the IDs of deleted elements. This approach complicates tracking cursors since they rely on these IDs. The solution recalculates position by replaying relevant history to update cursors accurately. To minimize the performance impact of history replay, the system updates cursor info to reference only the IDs of currently present elements, thereby reducing the need for replay.

  Parameters

  • pos: number
  • Optionalside: Side

  Returns Cursor

  Example

  
  const doc = new LoroDoc();
  const text = doc.getMovableList("text");
  text.insert(0, "1");
  const pos0 = text.getCursor(0, 0);
  {
    const ans = doc.getCursorPos(pos0!);
    expect(ans.offset).toBe(0);
  }
  text.insert(0, "1");
  {
    const ans = doc.getCursorPos(pos0!);
    expect(ans.offset).toBe(1);
  }
  Copy

getLastEditorAt

• getLastEditorAt(pos: number): `${number}`

  Get the last editor of the list item at the given position.

  Parameters

  • pos: number

  Returns `${number}`

getLastMoverAt

• getLastMoverAt(pos: number): `${number}`

  Get the last mover of the list item at the given position.

  Parameters

  • pos: number

  Returns `${number}`

getShallowValue

• getShallowValue(): Value[]

  Get the shallow value of the movable list.

  Unlike toJSON() which recursively resolves all containers to their values, getShallowValue() returns container IDs as strings for any nested containers.

  const doc = new LoroDoc();
  doc.setPeerId("1");
  const list = doc.getMovableList("list");
  list.insert(0, 1);
  list.insert(1, "two");
  const subList = list.insertContainer(2, new LoroList());
  subList.insert(0, "sub");
  list.getShallowValue(); // [1, "two", "cid:2@1:List"]
  list.toJSON(); // [1, "two", ["sub"]]
  Copy

  Returns Value[]

insert

• insert<V>(pos: number, value: Exclude<V, Container>): void

  Insert a value at index.

  Type Parameters

  • V

  Parameters

  • pos: number
  • value: Exclude<V, Container>

  Returns void

  Example

   import { LoroDoc } from "loro-crdt";
  
   const doc = new LoroDoc();
   const list = doc.getMovableList("list");
   list.insert(0, 100);
   list.insert(1, "foo");
   list.insert(2, true);
   console.log(list.value);  // [100, "foo", true];
  Copy

insertContainer

• insertContainer<C extends Container>(
      pos: number,
      child: C,
  ): T extends C ? T<T> : C

  Insert a container at the index.

  Type Parameters

  • C extends Container

  Parameters

  • pos: number
  • child: C

  Returns T extends C ? T<T> : C

  Example

   import { LoroDoc, LoroText } from "loro-crdt";
  
   const doc = new LoroDoc();
   const list = doc.getMovableList("list");
   list.insert(0, 100);
   const text = list.insertContainer(1, new LoroText());
   text.insert(0, "Hello");
   console.log(list.toJSON());  // [100, "Hello"];
  Copy

isAttached

• isAttached(): boolean

  Whether the container is attached to a document.

  If it's detached, the operations on the container will not be persisted.

  Returns boolean

isDeleted

• isDeleted(): boolean

  Check if the container is deleted

  Returns boolean

kind

• kind(): "MovableList"

  "MovableList"

  Returns "MovableList"

move

• move(from: number, to: number): void

  Move the element from from to to.

  The new position of the element will be to. Move the element from from to to.

  The new position of the element will be to. This method is optimized to prevent redundant operations that might occur with a naive remove and insert approach. Specifically, it avoids creating surplus values in the list, unlike a delete followed by an insert, which can lead to additional values in cases of concurrent edits. This ensures more efficient and accurate operations in a MovableList.

  Parameters

  • from: number
  • to: number

  Returns void

parent

• parent(): Container

  Get the parent container.

  • The parent container of the root tree is undefined.
  • The object returned is a new js object each time because it need to cross the WASM boundary.

  Returns Container

pop

• pop(): Value

  Pop a value from the end of the list.

  Returns Value

push

• push<V>(value: Exclude<V, Container>): void

  Type Parameters

  • V

  Parameters

  • value: Exclude<V, Container>

  Returns void

pushContainer

• pushContainer<C extends Container>(child: C): T extends C ? T<T> : C

  Push a container to the end of the list.

  Type Parameters

  • C extends Container

  Parameters

  • child: C

  Returns T extends C ? T<T> : C

set

• set<V>(pos: number, value: Exclude<V, Container>): void

  Set the value at the given position.

  It's different from delete + insert that it will replace the value at the position.

  For example, if you have a list [1, 2, 3], and you call set(1, 100), the list will be [1, 100, 3]. If concurrently someone call set(1, 200), the list will be [1, 200, 3] or [1, 100, 3].

  But if you use delete + insert to simulate the set operation, they may create redundant operations and the final result will be [1, 100, 200, 3] or [1, 200, 100, 3].

  Type Parameters

  • V

  Parameters

  • pos: number
  • value: Exclude<V, Container>

  Returns void

  Example

   import { LoroDoc } from "loro-crdt";
  
   const doc = new LoroDoc();
   const list = doc.getMovableList("list");
   list.insert(0, 100);
   list.insert(1, "foo");
   list.insert(2, true);
   list.set(1, "bar");
   console.log(list.value);  // [100, "bar", true];
  Copy

setContainer

• setContainer<C extends Container>(pos: number, child: C): T extends C ? T<T> : C

  Set a container at the index.

  Type Parameters

  • C extends Container

  Parameters

  • pos: number
  • child: C

  Returns T extends C ? T<T> : C

  Example

   import { LoroDoc, LoroText } from "loro-crdt";
  
   const doc = new LoroDoc();
   const list = doc.getMovableList("list");
   list.insert(0, 100);
   const text = list.setContainer(0, new LoroText());
   text.insert(0, "Hello");
   console.log(list.toJSON());  // ["Hello"];
  Copy

subscribe

• subscribe(listener: Listener): Subscription

  Parameters

  • listener: Listener

  Returns Subscription

toArray

• toArray(): T[]

  Get elements of the list. If the value is a child container, the corresponding Container will be returned.

  Returns T[]

  Example

   import { LoroDoc, LoroText } from "loro-crdt";
  
   const doc = new LoroDoc();
   const list = doc.getMovableList("list");
   list.insert(0, 100);
   list.insert(1, "foo");
   list.insert(2, true);
   list.insertContainer(3, new LoroText());
   console.log(list.value);  // [100, "foo", true, LoroText];
  Copy

toJSON

• toJSON(): any

  Get elements of the list. If the type of a element is a container, it will be resolved recursively.

  Returns any

  Example

  import { LoroDoc, LoroText } from "loro-crdt";
  
  const doc = new LoroDoc();
  const list = doc.getList("list");
  list.insert(0, 100);
  const text = list.insertContainer(1, new LoroText());
  text.insert(0, "Hello");
  console.log(list.toJSON());  // [100, "Hello"];
  Copy