directus/rstore/rstore-vue

Rstore Vue

Build typed, cache-first Vue data flows with @rstore/vue, including core engine and shared contract behavior.

Documentation map

Core concepts

Quick start

import { createStore, RstorePlugin, withItemType } from '@rstore/vue'
export const todos = withItemType<Todo>().defineCollection({
  name: 'todos',
})
const store = await createStore({
  schema: [todos],
  plugins: [],
})
app.use(RstorePlugin, { store })

Task workflow

1. Define collections and relations first.
2. Create a store with createStore({ schema, plugins }).
3. Install RstorePlugin in app code or set setActiveStore(store) in tests/non-injection contexts.
4. Use collection APIs (find*, query, liveQuery) instead of custom fetch refs.
5. Use createForm/updateForm for mutation UIs and createFormObject for custom flows.
6. Move transport/data-source behavior into definePlugin hooks, not component-level code.
7. When behavior is unclear, check docs and skill references first; if docs are incomplete or wrong, fix docs before updating this skill.

Query and form guidance

Notes:

• createFormObject supports validateOnSubmit, transformData, resetOnSuccess, $changedProps, and $valid.
• Form objects expose $opLog for undo/redo and optimized form operations.
• Use $rebase, $conflicts, and $resolveConflict for collaborative editing flows.
• $save() and $onSaved() are deprecated compatibility aliases. Prefer $submit() and $onSuccess().
• Query confirmed is a readonly ref: all existing pages must have server-confirmed results for current options. Each page exposes readonly confirmed. Fetches and published pushes confirm; cache guesses do not. Option changes, cache resets and $cache.clearCollection clear it; local writes preserve it. Saved refs retain confirmation across remounts and SSR hydration. See api-query.
• Function-valued options (such as filter) do not identify a query, page or subscription: function-only changes reload pages in place and never resubscribe.
• Live-query connectors report server termination with end({ reason, retry }); accepted results renew recovery budget, while immediate kickout loops stay bounded. Plain subscribe() has no end, refresh or setResult callbacks.
• Subscription identity uses resolved reads after defaults/hooks; client-only controls do not reopen plain or live subscriptions. See references/api-subscribe.md for resolved payload, key and teardown contracts.

Modules and plugins

• defineModule(name, cb) caches module instances in store.$modulesCache.
• defineModule requires injection context or an explicit/active store.
• definePlugin({ name, category, scopeId?, setup }) is the extension point for fetch/cache/mutation/subscription/sync hooks.
• For live pagination, use liveQuery(builder, { pages: () => [current.value] }) for displayed pages or { pages: 'all' } for every existing page. Default follows the main page. Offset windows can shift relative to each other; keeping several displayed pages consistent is not supported yet.
• Connectors order snapshots with fetch meta.$resultVersion and push setResult(rows, { version }) (FieldTimestampValue, finite number or serialized HLC; setResult throws for other formats). A versioned push drops an unversioned fetch already in flight. setResult returns 'applied' when accepted (non-main pages queue it and can still drop it), 'stale' or 'inactive'; its meta excludes reserved $ fields. Older page versions are rejected; equal versions apply. Refresh retains versions; base option changes reset them. Accepted pushed rows are cloned, parsed and written through the fetch pipeline; connectors must pass raw rows without pre-writing them. No-cache pushes expose wrapped item API, computed fields and relations. Pushed cache writes release relevant absence in other queries; local computed membership changes retain ownership like fetched rows until replacement/disposal. Pass shared or per-row fieldTimestamps through setResult (array index matches row index; equal lengths required, development warning on mismatch); no-cache, stale, inactive and dropped queued pushes never write shared cache.
• realtimeReconnectEventHook should be triggered by realtime plugins only after transport recovery; liveQuery refreshes automatically when it fires.
• addCollectionDefaults(...) is the right place for shared field parsing/default behavior.
• Keep plugin behavior keyed by store/scope instead of global mutable state.

Guardrails

1. Calling useStore() without installation/active store throws.
2. defineModule outside setup without an available store throws.
3. Query no-cache and cache-* behaviors differ materially; align changes with the documented query fetch-policy behavior.
4. experimentalGarbageCollection affects query tracking behavior; use only with explicit coverage.
5. Dynamic store.$collection(name) calls throw for unknown collection names.
6. Avoid duplicating entity state outside store cache unless intentionally divergent.

References