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 cache is managed automatically through mutation responses — when your server returns { invalidate: [...] }, the affected paths are marked stale and re-fetched on next access. These three methods let you inspect and control the cache explicitly when you need finer-grained control.

​
$refresh()

Manually mark a path as stale and trigger a re-fetch on next access. Signature: $refresh() → Promise<Proxy> When called on an object-valued path, dragonJSON replaces the cached entry with a { __next: true } stub — the lightweight sentinel that signals “needs fetching”. When called on a primitive-valued path, it immediately re-fetches and overwrites the cached value. In both cases, $on listeners registered at the path are fired with initiator: "refresh". $refresh returns a Proxy to the refreshed path so you can chain directly into a read if needed. 
// Force a re-fetch next time posts is accessed
await server.posts.$refresh();
const posts = await server.posts; // fresh data from server

​
$loaded()

Check whether a path is fully present in the local cache without making any network request. Signature: $loaded() → Promise<boolean> $loaded walks rootData along the full path. It returns:
  • true — every segment exists in the cache and none is a __next placeholder stub
  • false — any segment is missing, undefined, or is still a __next stub
No network call is ever made by $loaded. 
if (await server.posts.page1.$loaded()) {
  // instant, from cache
  const title = await server.posts.page1.title;
} else {
  // will fetch from server
  const title = await server.posts.page1.title;
}
Use $loaded() in performance-sensitive render paths to avoid triggering network requests during UI rendering. Fetch eagerly with $prefetch on mount.

​
$exists()

Check whether a path exists on the server, fetching it if not already cached. Signature: $exists() → Promise<boolean> Unlike $loaded, $exists will make a network request if the path is not cached. It resolves to:
  • true — the path fetched successfully and returned a value
  • false — the fetch threw an error or the path resolved to undefined
$exists never throws — the promise always resolves to a boolean. 
const userExists = await server.users["alice"].$exists();
This is especially useful for open-ended collections where the server returns __more: true, meaning child keys are not known in advance and each key must be probed individually.

​
control.debug.getCache()

Dump the entire in-memory rootData cache tree to the console. When debug: true is active, control.debug.getCache() passes the full rootData object to logFunc (defaulting to console.log). This lets you inspect exactly what dragonJSON has cached at any point without adding your own instrumentation. 
const [server, control] = dragonJSON(url, { debug: true });

// ...after some fetches...
control.debug.getCache(); // logs the full rootData tree
control.debug.getCache() only produces output when debug: true is active. If debug mode is off, the call is a no-op.

Build docs developers (and LLMs) love

Get started for freeTalk to us