Automerge Repo - v2.5.2-alpha.5
    Preparing search index...

    Interface Ref<TValue>Experimental

    A reference to a location in an Automerge document.

    This API is experimental and may change in future versions.

    // Create a ref via DocHandle
    const titleRef = handle.ref('todos', 0, 'title');
    titleRef.value();           // string | undefined
    titleRef.change(s => s.toUpperCase());
    titleRef.onChange(() => console.log('changed!'));

    // Use in function signatures
    function doubleIt(ref: Ref<number>) {
      ref.change(n => n * 2);
    }
    interface Ref<TValue = unknown> {
        docHandle: DocHandle<any>;
        path: PathSegment[];
        range?: CursorRange;
        rangePositions: undefined | [number, number];
        url: RefUrl;
        change(fnOrValue: TValue | RefChangeFn<TValue>): void;
        contains(other: Ref<unknown>): boolean;
        doc(): Automerge.Doc<any>;
        equals(other: Ref<unknown>): boolean;
        isChildOf(parent: Ref<unknown>): boolean;
        isEquivalent(other: Ref<unknown>): boolean;
        onChange(
            callback: (
                value: undefined | TValue,
                payload: DocHandleChangePayload<any>,
            ) => void,
        ): () => void;
        overlaps(other: Ref<unknown>): boolean;
        remove(): void;
        toString(): string;
        value(): undefined | TValue;
        valueOf(): string;
        viewAt(heads: Automerge.Heads): Ref<TValue>;
    }

    Type Parameters

    • TValue = unknown

      The type of value this ref points to (defaults to unknown)

    Index

    Properties

    docHandle path range? rangePositions url

    Methods

    change contains doc equals isChildOf isEquivalent onChange overlaps remove toString value valueOf viewAt

    Properties

    docHandle: DocHandle<any>

    The document handle this ref belongs to

    path: PathSegment[]

    The resolved path segments

    range?: CursorRange

    The cursor range, if this ref points to a text range

    rangePositions: undefined | [number, number]

    The numeric positions of the range, if this is a range ref

    url: RefUrl

    The URL representation of this ref

    Methods

    • Experimental

      Update the value at this ref's path.

      For primitives, you can pass either:

      • A function that receives the current value and returns the new value
      • A direct value (shorthand for primitives)

      For objects and arrays, mutate them in place within the function (same semantics as Automerge). Returning new object/array instances will trigger a warning as it loses granular change tracking.

      Parameters

      Returns void

      Error if the ref is on a read-only handle (time-traveled view)

      Error if the path cannot be resolved

      // Function form (works for all types)
      counterRef.change(n => n + 1);
      themeRef.change(t => t === 'dark' ? 'light' : 'dark');

      // Shorthand for primitives
      themeRef.change('dark');
      counterRef.change(42);

      // Objects/arrays: mutate in place
      todoRef.change(todo => { todo.done = true; });
    • Experimental

      Check if this ref contains another ref (other is a descendant of this).

      Parameters

      • other: Ref<unknown>

      Returns boolean

      const todoRef = handle.ref('todos', 0);
      const titleRef = handle.ref('todos', 0, 'title');
      todoRef.contains(titleRef); // true
      titleRef.contains(todoRef); // false
    • Experimental

      Check if this ref is equal to another ref. Two refs are equal if they have the same URL (document, path, and heads).

      Parameters

      • other: Ref<unknown>

      Returns boolean

    • Experimental

      Check if this ref is a child of another ref.

      For arrays: only direct array elements are considered children (path must be exactly one segment longer).

      For text: sub-ranges within the text are considered children (same path with a range, or one segment deeper).

      Parameters

      • parent: Ref<unknown>

      Returns boolean

      // Array children
      const arrayRef = handle.ref('items');
      const itemRef = handle.ref('items', 0);
      itemRef.isChildOf(arrayRef); // true

      // Text range children
      const textRef = handle.ref('content');
      const rangeRef = handle.ref('content', cursor(0, 10));
      rangeRef.isChildOf(textRef); // true
    • Experimental

      Check if this ref is equivalent to another ref. Two refs are equivalent if they point to the same value in the document, even if they use different addressing schemes (e.g., index vs pattern).

      This is useful when you have refs created with different path types (e.g., by array index vs by object pattern match) and need to check if they resolve to the same location.

      Short-circuits for fast rejection when refs are obviously different.

      Parameters

      • other: Ref<unknown>

      Returns boolean

      const byIndex = handle.ref('todos', 0);
      const byId = handle.ref('todos', { id: 'abc' });
      // If todos[0].id === 'abc', these are equivalent
      byIndex.isEquivalent(byId); // true
    • Experimental

      Subscribe to changes that affect this ref's value.

      The callback is invoked whenever a change affects the value at this ref's path. It receives the new value and the change payload.

      Parameters

      Returns () => void

      An unsubscribe function to stop listening

      const unsubscribe = titleRef.onChange((value, payload) => {
        console.log('Title changed to:', value);
      });

      // Later, stop listening
      unsubscribe();
    • Experimental

      Check if this ref overlaps with another ref (for text/range refs). Two refs overlap if they refer to the same parent location and their cursor ranges overlap.

      Parameters

      • other: Ref<unknown>

      Returns boolean

      const range1 = handle.ref('content', cursor(0, 10));
      const range2 = handle.ref('content', cursor(5, 15));
      range1.overlaps(range2); // true (overlap at positions 5-10)
    • Experimental

      Remove the value this ref points to from its parent container.

      • For object properties: deletes the key from the object
      • For array elements: removes the item from the array (splice)
      • For text ranges: deletes the text within the range

      Returns void

      Error if the ref points to the root document

      Error if the ref is on a read-only handle

      Error if the path cannot be resolved

      // Remove a property from an object
      const nameRef = handle.ref('user', 'name');
      nameRef.remove(); // deletes handle.doc().user.name

      // Remove an item from an array
      const todoRef = handle.ref('todos', 0);
      todoRef.remove(); // removes first todo from array

      // Remove text within a range
      const rangeRef = handle.ref('text', cursor(0, 5));
      rangeRef.remove(); // deletes first 5 characters
    • Experimental

      Get the current value at this ref's path.

      Returns undefined | TValue

      The value, or undefined if the path can't be resolved

      const titleRef = handle.ref('todos', 0, 'title');
      titleRef.value(); // "Buy milk" or undefined
    • Experimental

      Create a new ref viewing the document at specific heads (time-travel). Returns a new Ref instance on a read-only view handle at the specified heads.

      Parameters

      • heads: Automerge.Heads

        The document heads to view (hex-encoded, from Automerge.getHeads)

      Returns Ref<TValue>

      A new Ref instance pointing to the same path but at the specified heads

      // Get current heads before making changes
      const heads = Automerge.getHeads(handle.doc());

      // Make changes
      handle.change(d => { d.value = 'new' });

      // View the old state
      const pastRef = handle.ref('value').viewAt(heads);
      pastRef.value(); // returns old value

    Settings

    Member Visibility

    On This Page

    Properties
    Methods