Options
All
  • Public
  • Public/Protected
  • All
Menu

Hierarchy

Implements

Index

Constructors

  • Uses the given InitToken to register this Collab with its parent, thus attaching it to the tree of Collabs.

    Parameters

    Returns CText

Properties

name: string

The Collab's name, which distinguishes it among its siblings in the tree of Collabs.

parent: CollabParent

The Collab's parent in the tree of Collabs.

The ambient Runtime.

Accessors

  • get length(): number
  • The length of the list.

    Returns number

Methods

  • [iterator](): IterableIterator<string>
  • Returns IterableIterator<string>

  • canGC(): boolean
  • If this Collab is in its initial, post-constructor state, then this method may (but is not required to) return true; otherwise, it returns false.

    When canGC() is true and there are no non-weak references to this Collab, users of this Collab may safely delete it from memory ("garbage collection"), recreating it using the same constructor arguments if needed later. That reduces the state space of some Collab collections (in particular, LazyMutCMap).

    Returns boolean

  • charAt(index: number): string
  • Parameters

    • index: number

    Returns string

  • clear(): void
  • Returns void

  • delete(startIndex: number, count?: number): void
  • Delete count characters starting at startIndex, i.e., characters [startIndex, startIndex + count - 1).

    Characters at >= startIndex + count are shifted count spots to the left.

    Parameters

    • startIndex: number
    • Optional count: number

    Returns void

  • Emits an event, which notifies all registered event handlers. After emitting event, an "Any" event with the same event.meta is emitted, unless it is already an "Any" event. (Usually, Collabs should not emit an "Any" event directly, instead emitting a more specific, custom event.)

    event is forced to implement CollabEvent, to indirectly express the requirement that all event types in the CollabEventsRecord implement CollabEvent.

    See Events for advice on what events to emit.

    Type Parameters

    Parameters

    • eventName: K

      Name of the event.

    • event: CTextEventsRecord[K] & CollabEvent

      Event object to pass to the event handlers.

    • Optional emitAnyEvent: boolean

      = true if true (default) and the event is not an "Any" event, an "Any" event is emitted immediately after event.

    Returns void

  • findPosition(position: string): [geIndex: number, isPresent: boolean]
  • Parameters

    • position: string

    Returns [geIndex: number, isPresent: boolean]

    [The index where the position would be if it were present (equivalently, the first index greater than or equal to it), whether it is currently present].

  • getContext(key: symbol): unknown
  • Returns context for the given key as supplied by some ancestor, or undefined if not supplied.

    Keys are queried by Collab.getContext in a call chain (like in object inheritance): first, the Collab calls getAddedContext(key) on the parent; if that returns undefined, it calls on the grandparent, etc., ending with the Runtime.

    As in object inheritance, a key present in one Collab overshadows its ancestors' values for that key, but that Collab may choose to consult the next higher up value, accessed through its own Collab.getContext method.

    The returned context may be a value or a function. The value case is analogous to a property, while the function case is analogous to a method.

    Typically, context values are local to this replica and should not be consulted when receiving messages. Otherwise, the received message may be processed inconsistently on different replicas. Context necessary for a message should instead be included in that message, either directly or as a field on its MessageMeta.

    Parameters

    • key: symbol

    Returns unknown

  • Returns the descendant of this Collab at the given name path, or undefined if it no longer exists.

    If namePath is [], this is returned.

    This method should not be called before load has completed. Otherwise, its behavior is unspecified.

    See also: CollabID.

    Parameters

    • namePath: string[]

    Returns undefined | Collab<CollabEventsRecord>

    The descendant at the given name path, or undefined if it no longer exists.

  • Returns the "name path" from descendant to this, i.e., the list of names on that path in the tree of Collabs.

    I.e., it is [descendent.name, descendant.parent.name, descendant.parent.parent.name, ...] continuing until this is reached, excluding this.name.

    getDescendant does the reverse procedure. getNamePath and getDescendant together allow one to make a serializable reference to a Collab that is comprehensible across replicas.

    See also: CollabID.

    throws

    if descendant is not a descendant of this in the tree of Collabs.

    Parameters

    Returns string[]

  • getPosition(index: number): string
  • Parameters

    • index: number

    Returns string

    The position currently at index.

  • insert(index: number, values: string): void
  • Insert the given substring starting at index.

    Existing characters at >= index are shifted values.length spots to the right.

    Parameters

    • index: number
    • values: string

    Returns void

  • load(saveData: Optional<Uint8Array>): void
  • Loads this newly-initialized Collab and its descendants from saveData output by save on a previous replica of this Collab (wrapped in an Optional), or if saveData is an empty Optional, indicates that loading is skipped (no prior save data).

    See save for detailed info on saving and loading usage.

    This may only be called on a newly initialized Collab, and it must be called (exactly once) before this Collab can be used to perform operations or receive messages. Behavior is undefined if that condition is violated.

    Parameters

    Returns void

  • Returns a promise that will be resolved exactly once, next time the event is emitted. If the event never happens, the promise is neither resolved nor rejected.

    Type Parameters

    Parameters

    • eventName: K

      Name of the event to listen to

    Returns Promise<CTextEventsRecord[K]>

  • Registers an event handler that is triggered when the event happens.

    Type Parameters

    Parameters

    Returns Unsubscribe

    An "off" function that removes the event handler when called

  • Do not override this method; instead override sendPrimitive.

    If you need to override this method instead of sendPrimitive, consider extending Collab directly instead of this class.

    Parameters

    Returns void

  • save(): Uint8Array
  • Returns save data describing the current state of this Collab and its descendants, sufficient to restore the state on a new replica by calling load(Optional.of(saveData)).

    The usage pattern of save and load is:

    1. save is called on one replica, returning save data.
    2. A new replica of this Collab is created using the same class and same constructor arguments (the usual Initialization requirements for replicas).
    3. load(saveData) is called on that replica. This is expected to give an identical state to that when save was called, except that replica is different (in particular, Runtime.replicaID is different).
    4. The replica proceeds normally, receiving any messages that had not yet been received before the save call.

    Before load is called, this Collab and its descendants must not be used to perform operations or receive messages. Behavior is undefined if that condition is violated.

    A special case of the usage pattern is when an app is created without any prior save data. In that case, load(Optional.empty()) is called instead, to indicate that loading has been skipped and that the Collab can start being used.

    save may be called multiple times throughout an app's lifecycle, and it should not affect the user-visible state. save may not be called in the middle of an operation or transaction (either being sent or received), to ensure that this Collab is in a reasonable, stable, user-facing state.

    Returns Uint8Array

    save data

  • Sends the given message.

    In general, messagePath will be then be delivered to Collab.receive on each replica of this. However, ancestors may choose to modify the message before delivery, including possibly delivering extra messages or none at all.

    Parameters

    • messagePath: Message[]

      An array of messages to be delivered to replicas' receive method. Typically this takes the form of a child Collab's sent messagePath, with an extra message sent by this Collab appended to the end. Note that the array may be modified in-place by ancestors.

    Returns void

  • sendPrimitive(message: Message): void
  • toString(): string
  • Returns string

    the text as an ordinary string

  • values(): IterableIterator<string>
  • Returns IterableIterator<string>

Generated using TypeDoc