Class DocHandle<T>

A DocHandle is a wrapper around a single Automerge document that lets us listen for changes and notify the network and storage of new changes.

Remarks

A DocHandle represents a document which is being managed by a Repo. You shouldn't ever instantiate this yourself. To obtain DocHandle use Repo.find or Repo.create.

To modify the underlying document use either DocHandle.change or DocHandle.changeAt. These methods will notify the Repo that some change has occured and the Repo will save any new changes to the attached StorageAdapter and send sync messages to connected peers.

Type Parameters

Hierarchy

EventEmitter<DocHandleEvents<T>>
- DocHandle

Properties

documentId

documentId: DocumentId

inState

inState: (states: HandleState[]) => boolean

Type declaration

- (states: HandleState[]): boolean
- Parameters
  - states: HandleState[]
  Returns boolean
  true if the handle is in one of the given states.

Deprecated

Will be removed in the next major.

isDeleted

isDeleted: () => boolean

Type declaration

- (): boolean
- Returns boolean
  true if the document has been marked as deleted.

isReady

isReady: () => boolean

Type declaration

- (): boolean
- Returns boolean
  true if the document has not been deleted. Repo only hands out handles that already have data, so this is true from construction unless delete() is called.

isUnavailable

isUnavailable: () => boolean

Type declaration

- (): boolean
- Returns boolean
  true if the document is currently unavailable.

Deprecated

Always returns false — find() rejects on unavailable docs rather than returning a handle. Will be removed in the next major.

isUnloaded

isUnloaded: () => boolean

Type declaration

- (): boolean
- Returns boolean
  true if the document has been unloaded.

`Static`prefixed

prefixed: string | boolean

Accessors

url

get url(): AutomergeUrl
Our documentId in Automerge URL form.

Returns AutomergeUrl
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:30

Methods

addListener

addListener<T extends keyof DocHandleEvents<T>>(
    event: T,
    fn: (
        ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
            T,
            keyof DocHandleEvents<T>,
        >],
    ) => void,
    context?: any,
): this
Type Parameters
- T extends keyof DocHandleEvents<T>
Parameters
- event: T
- fn: (
      ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
          T,
          keyof DocHandleEvents<T>,
      >],
  ) => void
- Optionalcontext: any
Returns this
Inherited from EventEmitter.addListener
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:45

broadcast

broadcast(message: unknown): void
Sends an arbitrary ephemeral message out to all reachable peers who would receive sync messages from you. It has no guarantee of delivery, and is not persisted to the underlying automerge doc in any way. Messages will have a sending PeerId but this is not a useful user identifier (a user could have multiple tabs open and would appear as multiple PeerIds). Every message source must have a unique PeerId.
Parameters
- message: unknown
Returns void
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:228

change

change(
callback: Automerge.ChangeFn<T>,
options?: Automerge.ChangeOptions<T>,
): void
All changes to an Automerge document should be made through this method. Inside the callback, the document should be treated as mutable: all edits will be recorded using a Proxy and translated into operations as part of a single recorded "change".

Note that assignment via ES6 spread operators will result in replacing the object instead of mutating it which will prevent clean merges. This may be what you want, but doc.foo = { ...doc.foo, bar: "baz" } is not equivalent to doc.foo.bar = "baz".

Local changes will be stored (by the StorageSubsystem) and synchronized (by the DocSynchronizer) to any peers you are sharing it with.
Parameters
- callback: Automerge.ChangeFn<T>
  A function that takes the current document and mutates it.
- Optionaloptions: Automerge.ChangeOptions<T>
Returns void
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:176

changeAt

changeAt(
    heads: UrlHeads,
    callback: Automerge.ChangeFn<T>,
    options?: Automerge.ChangeOptions<T>,
): undefined | UrlHeads
Makes a change as if the document were at heads.
Parameters
- heads: UrlHeads
- callback: Automerge.ChangeFn<T>
- Optionaloptions: Automerge.ChangeOptions<T>
Returns undefined | UrlHeads
A set of heads representing the concurrent change that was made.
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:182

delete

delete(): void
Called by the repo when the document is deleted.

Returns void
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:220

diff

diff(first: DocHandle<T> | UrlHeads, second?: UrlHeads): Automerge.Patch[]
Returns a set of Patch operations that will move a materialized document from one state to another if applied.
Parameters
- first: DocHandle<T> | UrlHeads
- Optionalsecond: UrlHeads
Returns Automerge.Patch[]
Automerge patches that go from one document state to the other
Remarks
We allow specifying either:
- Two sets of heads to compare directly
- A single set of heads to compare against our current heads
- Another DocHandle to compare against (which must share history with this document)
Throws
Error if the documents don't share history or if either document is not ready
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:126

doc

doc(): Automerge.Doc<T>
Returns the current state of the Automerge document this handle manages.

Returns Automerge.Doc<T>
the current document

Throws
on deleted and unavailable documents
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:73

docSync

docSync(): Automerge.Doc<T>
Returns Automerge.Doc<T>
Deprecated
Use doc() instead.
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:77

emit

emit<T extends keyof DocHandleEvents<T>>(
    event: T,
    ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
        T,
        keyof DocHandleEvents<T>,
    >],
): boolean
Calls each of the listeners registered for a given event.
Type Parameters
- T extends keyof DocHandleEvents<T>
Parameters
- event: T
- ...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]
Returns boolean
Inherited from EventEmitter.emit
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:32

eventNames

eventNames(): (keyof DocHandleEvents<T>)[]
Return an array listing the events for which the emitter has registered listeners.

Returns (keyof DocHandleEvents<T>)[]
Inherited from EventEmitter.eventNames
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:15

getRemoteHeads

getRemoteHeads(storageId: StorageId): undefined | UrlHeads
Returns the latest known heads for the given peer's storageId, or undefined if we have not received sync info from that peer.
Parameters
- storageId: StorageId
Returns undefined | UrlHeads
Deprecated
Use DocHandle.getSyncInfo instead. Will be removed in the next major.
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:158

getSyncInfo

getSyncInfo(storageId: StorageId): undefined | SyncInfo
Returns the heads and the timestamp of the last update for the storageId.
Parameters
- storageId: StorageId
Returns undefined | SyncInfo
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:160

heads

heads(): UrlHeads
Returns the current "heads" of the document, akin to a git commit. This precisely defines the state of a document.

Returns UrlHeads
the current document's heads, or undefined if the document is not ready
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:83

history

history(): UrlHeads[]
Returns an array of all past "heads" for the document in topological order.

Returns UrlHeads[]
UrlHeads[] - The individual heads for every change in the document. Each item is a tagged string[1].

Remarks
A point-in-time in an automerge document is an array of heads since there may be concurrent edits. This API just returns a topologically sorted history of all edits so every previous entry will be (in some sense) before later ones, but the set of all possible history views would be quite large under concurrency (every thing in each branch against each other). There might be a clever way to think about this, but we haven't found it yet, so for now at least we present a single traversable view which excludes concurrency.
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:98

isReadOnly

isReadOnly(): boolean
Check if the document can be change()ed. Currently, documents can be edited unless we are viewing a particular point in time.

Returns boolean
boolean indicating whether changes are possible

Remarks
It is technically possible to back-date changes using changeAt(), but we block it for usability reasons when viewing a particular point in time. To make changes in the past, use the primary document handle with no heads set.
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:193

listenerCount

listenerCount(event: keyof DocHandleEvents<T>): number
Return the number of listeners listening to a given event.
Parameters
- event: keyof DocHandleEvents<T>
Returns number
Inherited from EventEmitter.listenerCount
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:27

listeners

listeners<T extends keyof DocHandleEvents<T>>(
    event: T,
): (
    (
        ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
            T,
            keyof DocHandleEvents<T>,
        >],
    ) => void
)[]
Return the listeners registered for a given event.
Type Parameters
- T extends keyof DocHandleEvents<T>
Parameters
- event: T
Returns (
    (
        ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
            T,
            keyof DocHandleEvents<T>,
        >],
    ) => void
)[]
Inherited from EventEmitter.listeners
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:20

merge

merge(otherHandle: DocHandle<T>): void
Merges another document into this document. Any peers we are sharing changes with will be notified of the changes resulting from the merge.
Parameters
- otherHandle: DocHandle<T>
  the handle of the document to merge into this one
Returns void
the merged document.

Throws
if either document is not ready or if otherHandle is unavailable.
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:202

metrics

metrics(): { numChanges: number; numOps: number }
Returns { numChanges: number; numOps: number }
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:229

off

off<T extends keyof DocHandleEvents<T>>(
    event: T,
    fn?: (
        ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
            T,
            keyof DocHandleEvents<T>,
        >],
    ) => void,
    context?: any,
    once?: boolean,
): this
Type Parameters
- T extends keyof DocHandleEvents<T>
Parameters
- event: T
- Optionalfn: (
      ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
          T,
          keyof DocHandleEvents<T>,
      >],
  ) => void
- Optionalcontext: any
- Optionalonce: boolean
Returns this
Inherited from EventEmitter.off
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:69

on

on<T extends keyof DocHandleEvents<T>>(
    event: T,
    fn: (
        ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
            T,
            keyof DocHandleEvents<T>,
        >],
    ) => void,
    context?: any,
): this
Add a listener for a given event.
Type Parameters
- T extends keyof DocHandleEvents<T>
Parameters
- event: T
- fn: (
      ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
          T,
          keyof DocHandleEvents<T>,
      >],
  ) => void
- Optionalcontext: any
Returns this
Inherited from EventEmitter.on
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:40

once

once<T extends keyof DocHandleEvents<T>>(
    event: T,
    fn: (
        ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
            T,
            keyof DocHandleEvents<T>,
        >],
    ) => void,
    context?: any,
): this
Add a one-time listener for a given event.
Type Parameters
- T extends keyof DocHandleEvents<T>
Parameters
- event: T
- fn: (
      ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
          T,
          keyof DocHandleEvents<T>,
      >],
  ) => void
- Optionalcontext: any
Returns this
Inherited from EventEmitter.once
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:54

ref

ref<TPath extends readonly PathInput[]>(
...segments: [...TPath[]],
): Ref<InferRefType<T, TPath>>
Experimental
Create a ref to a location in this document.

Returns the same ref instance for the same path, ensuring referential equality.

This API is experimental and may change in future versions.
Type Parameters
- TPath extends readonly PathInput[]
Parameters
- ...segments: [...TPath[]]
Returns Ref<InferRefType<T, TPath>>
Example
```
const titleRef = handle.ref('todos', 0, 'title');
titleRef.value(); // string | undefined

// Same ref instance is returned for same path
const sameRef = handle.ref('todos', 0, 'title');
titleRef === sameRef; // true
```
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:250

reload

reload(): void
Called by the repo to reuse an unloaded handle.

Returns void
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:218

removeAllListeners

removeAllListeners(event?: keyof DocHandleEvents<T>): this
Remove all listeners, or those of the specified event.
Parameters
- Optionalevent: keyof DocHandleEvents<T>
Returns this
Inherited from EventEmitter.removeAllListeners
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:79

removeListener

removeListener<T extends keyof DocHandleEvents<T>>(
    event: T,
    fn?: (
        ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
            T,
            keyof DocHandleEvents<T>,
        >],
    ) => void,
    context?: any,
    once?: boolean,
): this
Remove the listeners of a given event.
Type Parameters
- T extends keyof DocHandleEvents<T>
Parameters
- event: T
- Optionalfn: (
      ...args: ArgumentMap<DocHandleEvents<T>>[Extract<
          T,
          keyof DocHandleEvents<T>,
      >],
  ) => void
- Optionalcontext: any
- Optionalonce: boolean
Returns this
Inherited from EventEmitter.removeListener
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:63

unload

unload(): void
Called by the repo to free memory used by the document.

Returns void
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:216

view

view(heads: UrlHeads): DocHandle<T>
Creates a fixed "view" of an automerge document at the given point in time represented by the heads passed in. The return value is the same type as doc() and will return undefined if the object hasn't finished loading.
Parameters
- heads: UrlHeads
Returns DocHandle<T>
DocHandle at the time of heads

Remarks
Note that our Typescript types do not consider change over time and the current version of Automerge doesn't check types at runtime, so if you go back to an old set of heads that doesn't match the heads here, Typescript will not save you.

Argument
heads - The heads to view the document at. See history().
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:112

whenReady

whenReady(awaitStates?: HandleState[]): Promise<void>
Returns a promise that resolves when the handle is in one of the given states (default ["ready"]).
Parameters
- OptionalawaitStates: HandleState[]
Returns Promise<void>
Deprecated
Handles are always ready when handed out by Repo.find / Repo.create. Will be removed in the next major.
- Defined in packages/automerge-repo/dist/DocHandle.d.ts:65

Class DocHandle<T>

Remarks

Type Parameters

Hierarchy

Index

Properties

Accessors

Methods

Properties

documentId

inState

Type declaration

Parameters

Returns boolean

Deprecated

isDeleted

Type declaration

Returns boolean

isReady

Type declaration

Returns boolean

isUnavailable

Type declaration

Returns boolean

Deprecated

isUnloaded

Type declaration

Returns boolean

Staticprefixed

Accessors

url

Returns AutomergeUrl

Methods

addListener

Type Parameters

Parameters

Returns this

broadcast

Parameters

Returns void

change

Parameters

Returns void

changeAt

Parameters

Returns undefined | UrlHeads

delete

Returns void

diff

Parameters

Returns Automerge.Patch[]

Remarks

Throws

doc

Returns Automerge.Doc<T>

Throws

docSync

Returns Automerge.Doc<T>

Deprecated

emit

Type Parameters

Parameters

Returns boolean

eventNames

Returns (keyof DocHandleEvents<T>)[]

getRemoteHeads

Parameters

Returns undefined | UrlHeads

Deprecated

getSyncInfo

Parameters

Returns undefined | SyncInfo

heads

Returns UrlHeads

history

Returns UrlHeads[]

Remarks

isReadOnly

Returns boolean

Remarks

`Static`prefixed

Returns (
(
...args: ArgumentMap<DocHandleEvents<T>>[Extract<
T,
keyof DocHandleEvents<T>,
>],
) => void
)[]