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.

All mutations send an HTTP POST to the base URL with the target path as a ?path= query parameter. The server must respond with { invalidate: [...] } — an array of dot-separated path strings that dragonJSON should mark as stale. Stale entries are set to { __next: true } (objects) or deleted (primitives) in the local cache, and are re-fetched transparently on next access. After cache invalidation, any matching $on() listeners are fired automatically.
All mutation endpoints must return { invalidate: [...] }. An empty array is valid; a missing invalidate field causes dragonJSON to throw.

​
$set(dataOrKey, value?)

Update the value at the current path, or at a child key relative to the current path. Signatures:
  • $set(data: any) → Promise<void> — replace the current path’s value with data
  • $set(key: string, value: any) → Promise<void> — replace the child at <current-path>.<key> with value
HTTP: POST ?path=<target-path>, body = JSON-serialized value 
// Replace the entire posts.page1 object
await server.posts.page1.$set({ title: "Updated Title", body: "New content." });

// Replace only the title field of posts.page1 (posts.page1.title is the POST target)
await server.posts.page1.$set("title", "Updated Title");
When a key is provided as the first argument, the POST target path becomes <current-path>.<key> and the body is the JSON-serialized value. Without a key, the POST target is the current path and the body is the JSON-serialized data argument.

​
$add(objOrKey, obj?)

Add a new entry to the collection at the current path. The server assigns the final key, or you can suggest one. Signatures:
  • $add(obj: object) → Promise<void> — server picks the key
  • $add(key: string, obj: object) → Promise<void> — suggest a key; server may accept or override it
  • $add({ key: string, obj: object }) → Promise<void> — object form of the above
HTTP: POST ?path=<current-path>, body = { __op: "add", key?: string, value: any } 
// Server assigns the key
await server.posts.$add({ title: "New Post", body: "Content here." });

// Suggest a key
await server.posts.$add("page5", { title: "New Post", body: "Content here." });

// Object form
await server.posts.$add({ key: "page5", obj: { title: "New Post", body: "Content here." } });
The server typically returns { "invalidate": ["posts"] } — invalidating the parent collection so that the next access to server.posts re-fetches the full updated list. The specific keys invalidated are up to your server implementation.

​
$remove(key?)

Delete a path from the server and evict it from the local cache. Signatures:
  • $remove() → Promise<void> — remove the current path
  • $remove(key: string) → Promise<void> — remove the child at <current-path>.<key>
HTTP: POST ?path=<target-path>, body = { __op: "remove" } 
// Remove posts.page1 directly
await server.posts.page1.$remove();

// Remove posts.page1 via the parent (equivalent)
await server.posts.$remove("page1");
Unlike $set and $add, $remove deletes (rather than stubs) the affected keys from the local cache when processing the invalidate list. This ensures the removed entry is fully evicted and not served from cache.

​
Complete Mutation Cycle

// Create
await server.posts.$add({ title: "New Post", body: "Content" });

// Read back (auto re-fetches because posts was invalidated)
const posts = await server.posts;

// Update
await server.posts.page1.$set({ title: "Updated" });

// Delete
await server.posts.page1.$remove();

Build docs developers (and LLMs) love

Get started for freeTalk to us