Appearance

📄 $data – Data Access & Mutation API ​

The $data API is the primary interface for communicating with the backend. It allows you to read, create, update, and delete data in a fully integrated and reactive way.

It is tightly coupled with:

  • backend routes
  • the internal store
  • caching layer
  • $socket (for real-time sync)

🧠 Core Concept ​

$data provides predefined query and mutation methods based on your backend routes.

Each call returns:

  • reactive state (data, isLoading, error)
  • a manual trigger (execute)
  • optional automatic execution (immediate)

🔧 Basic Usage ​

typescript
const { $data, [...] } = usePluginApi()
const {data, dataArr, response, query, execute, isLoading, error } = $data.example.getAll({
  params: {},
  id: false,
  options: {
    immediate: false,
    cb: (result) => {},
    notify: true | false,
    responseType: "json" | "stream",
    mode: "none" | "cors",
    useCache: true | false,
    useStore: true | false,
  },
  config: {}
})
Returns
  • data - The resultobject
  • dataArr - The resultArray
  • response - The response from the server
  • query - the query object (only in reading queries)
  • execute - an awaitable function to trigger the action call. The response and result returned from this functions are not reactive! Use dataArr or data
  • isLoading - a boolean indicator for the loading/fetch state
  • error - contains the error object if errors are catched
Props
  • id - if set this will be used instead of the query instance nanoId
  • params - The object you want to send to the backend
  • options
    • immediate - If true, the action will be executed right away, defaults to false
    • cb - A function which will get called after the action is resolved. Receives the result object
    • useStore - If false, will not write the data to the redux store. The data return will also not be available, use response instead. defaults to true
    • useCache - If false, will bypass the global query cache, important for streams of if you always want fresh data if triggered. Cachetime is 1000ms and only makes sure that several unique queries, having the exact same params are not queried multiple times but instead only once within the ttl. Defaults to true
    • notify - if false, will not write into the notification que and snackbar, defaults to true
    • responseType - only used if you want to explicitly receive a http stream. Set to stream in that case, defaults to json
    • mode - if responseType is stream, you can set mode "cors" here

📦 Available Methods ​

Depending on your backend routes:

ts
$data.<model>.<action>()

Common actions ​

  • getAll
  • get
  • create
  • update
  • delete
  • deleteHard

▶️ Manual Execution ​

typescript
  const { response, result } = await execute()
returns
  • response - The response object from either fetch or axios, depending on what you configured in options
  • result - Returns an array of the items which have been retrieved or written to the store and/or server

🔁 Typical Patterns ​

Auto-fetch on mount ​

ts
$data.tags.getAll({
  options: { immediate: true },
})

Refetch after mutation ​

ts
const { execute } = $data.todo.getAll()

const { execute: create } = $data.todo.create({
  options: { cb: () => execute() },
})

With $socket (real-time sync) ​

ts
$socket.on("todoCreated", () => {
  execute()
})

🧩 Real Usage Example ​

ts
const { $data, $socket, $eventbus } = usePluginApi()

const { data, execute } = $data.todo.getAll({
  params: { isDeleted: false },
  options: { immediate: true },
})

const { execute: createTodo } = $data.todo.create({
  options: { cb: () => execute() },
})

$socket.on("todoDeleted", () => {
  $eventbus.global.emit("ui/addToSnackbar", {
    message: "Todo deleted",
    color: "yellow",
  })

  execute()
})

🧠 Mental Model ​

  • $data → executes backend operations
  • Store → holds reactive state
  • Cache → prevents duplicate calls
  • $socket → keeps everything in sync

⚖️ When to Use $data ​

Use $data when you need to:

  • fetch data from backend
  • mutate data (CRUD)
  • manage loading and error states
  • integrate with store & caching

🚫 Important Notes ​

  • execute() is not reactive
  • caching is short-lived (1000ms)
  • useStore: false disables reactivity
  • streams require explicit config

🧠 Key Takeaway ​

$data is your single source of truth for backend interaction

👉 It handles requests, state, caching, and integration