Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/michael-tiger-2010/dragonjson/llms.txt

Use this file to discover all available pages before exploring further.

The dragonJSON event system lets you subscribe to mutations at any path in the server proxy tree — listeners are fired automatically after every local mutation and, when liveInvalidation is configured, after relay messages received from other clients.

​
$on(type, key, callback, mode?)

Register a listener on the current proxy path.
​
type
string
required
The mutation type to listen for. One of:
  • "add" — fires when a child key is created via $add
  • "remove" — fires when a path is deleted via $remove
  • "set" — fires when a value is updated via $set
  • "*" — fires on any of the above, plus "refresh" events from $refresh
​
key
string
required
The specific child key to match, or "*" to match any key (including when the mutation targets the node itself).
​
callback
function
required
Called with a single event object whenever a matching mutation fires. See the Event Object section below for the full shape.Signature: (event: object) => void
​
mode
string
default:"direct"
Controls which paths can trigger this listener. One of:
  • "direct" (default) — fires only when the mutation originates at exactly this path
  • "bubble" — fires when the mutation originates at this path or any descendant, similar to DOM event bubbling

​
$off(type, key, callback, mode?)

Remove a previously registered listener. All four arguments must match exactly the values used when calling $on.
​
type
string
required
Must match the type passed to $on.
​
key
string
required
Must match the key passed to $on.
​
callback
function
required
Must be the same function reference passed to $on.
​
mode
string
default:"direct"
Must match the mode passed to $on. Defaults to "direct".

​
Event Object

The object passed to every listener callback.
​
initiator
string
The operation that triggered the event. One of "add", "remove", "set", "*", or "refresh".
​
key
string
The child key that was affected. "*" when the key is unknown or the mutation targets the node itself.
​
path
string[]
Array of path segments identifying the origin of the mutation (e.g. ["posts", "page1"]).
​
data
Proxy
A lazy proxy rooted at the affected path. Await it to retrieve the current (post-mutation) value from the cache or server.
​
invalidate
string[]
The array of dot-separated path strings the server returned in its invalidate field for this mutation.

​
Examples

// Listen for any add under posts
server.posts.$on("add", "*", async (e) => {
  console.log("Added key:", e.key);
  const newPost = await e.data;
  console.log("New post:", newPost);
});

// Listen only when posts.page1 is removed
function onRemoved(e) { console.log("page1 removed"); }
server.posts.$on("remove", "page1", onRemoved);
server.posts.$off("remove", "page1", onRemoved);

// Bubble: any mutation anywhere under server fires this handler
server.$on("*", "*", (e) => console.log(e.initiator, e.path), "bubble");
Listeners are deduplicated by reference. Registering the same func / type / key combination twice has no effect — the second call is silently ignored.

Build docs developers (and LLMs) love

Get started for freeTalk to us