Class LoroList<T>

constructor

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

  Create a new detached LoroList (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 LoroList<T>

constructor

• new LoroList(): LoroList<T>

  Returns LoroList<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.getList("list");
   list.insert(0, 100);
   console.log(list.get(0));  // 100
   console.log(list.get(1));  // undefined
  Copy

getAttached

• getAttached(): LoroList<T>

  Returns LoroList<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>

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.getList("list");
  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

getIdAt

• getIdAt(pos: number): { counter: number; peer: `${number}` }

  Parameters

  • pos: number

  Returns { counter: number; peer: `${number}` }

getShallowValue

• getShallowValue(): Value[]

  Get the shallow value of the 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.getList("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.getList("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.getList("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(): "List"

  "List"

  Returns "List"

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

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.getList("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