Live Queries

Real-time data synchronization with automatic updates using LiveData and TanStack Query. Available since modelence@0.15.1 and @modelence/react-query@1.2.1.

Live Queries in Modelence provide real-time data synchronization between your server and client. When underlying data changes, connected clients automatically receive updated data without manual polling or refetching.

Version Requirements

Live Queries are available with the following minimum package versions:

• modelence >= 0.15.1 (requires Store.watch(), introduced in 0.15.1)
• @modelence/react-query >= 1.2.1

Overview

The live query system consists of three parts:

1. Server-side LiveData - Defines how to fetch data and watch for changes
2. ModelenceQueryProvider (or connectModelenceQueryClient) - Connects Modelence’s live query system to TanStack Query
3. modelenceLiveQuery - Creates live query options for useQuery

Client Setup

1. Provide a connected QueryClient

modelenceLiveQuery needs a TanStack Query QueryClient connected to Modelence’s live-query layer. The simplest way is to let renderApp handle it: if you don’t mount your own provider, renderApp automatically wraps your app in ModelenceQueryProvider, which creates a QueryClient and connects it for you.

// src/client/index.tsx
import { renderApp } from 'modelence/client';
import routes from './routes';

renderApp({
  loadingElement: <div>Loading…</div>,
  routesElement: routes,
});
// No provider wiring needed — renderApp injects ModelenceQueryProvider.

If you need your own QueryClient (for example, to configure defaults or share it with other libraries), connect it yourself with connectModelenceQueryClient and mount your own QueryClientProvider. renderApp detects the already-connected client and will not inject a second provider.

// src/client/index.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { connectModelenceQueryClient, renderApp } from 'modelence/client';
import routes from './routes';

const queryClient = new QueryClient();
connectModelenceQueryClient(queryClient);

renderApp({
  loadingElement: <div>Loading…</div>,
  routesElement: (
    <QueryClientProvider client={queryClient}>{routes}</QueryClientProvider>
  ),
});

If you mount your own QueryClientProvider but never call connectModelenceQueryClient(queryClient), modelenceLiveQuery throws: Modelence: connect a QueryClient before using modelenceLiveQuery(). Mount <ModelenceQueryProvider> or call connectModelenceQueryClient().

2. Use modelenceLiveQuery in Components

Use modelenceLiveQuery with TanStack Query’s useQuery hook. It works just like modelenceQuery, but data updates automatically when the server detects changes:

import { useQuery } from '@tanstack/react-query';
import { modelenceLiveQuery } from 'modelence/client';

function TodoList({ userId }: { userId: string }) {
  const { data: todos, isLoading } = useQuery(
    modelenceLiveQuery('todo.getAll', { userId })
  );

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {todos?.map(todo => (
        <li key={todo._id}>{todo.title}</li>
      ))}
    </ul>
  );
}

Server Setup

Returning LiveData from Query Handlers

Live query handlers must return a LiveData object, not plain data. LiveData tells Modelence how to fetch the data and how to watch for changes.

import { Module, LiveData } from 'modelence/server';
import { dbTodos } from './db';

export default new Module('todo', {
  stores: [dbTodos],

  queries: {
    // Standard query - returns data directly
    getById: async ({ id }) => {
      return await dbTodos.findById(id);
    },

    // Live query - returns LiveData
    getAll: async ({ userId }) => {
      return new LiveData({
        fetch: async () => await dbTodos.fetch({ userId }),
        watch: ({ publish }) => {
          const changeStream = dbTodos.watch();
          changeStream.on('change', () => publish());
          return () => changeStream.close();
        },
      });
    },
  },
});

If a live query handler returns plain data instead of a LiveData object, the server will throw: Live query handler for 'X' must return a LiveData object with fetch and watch functions.

LiveData Configuration

LiveData accepts two functions:

Property	Type	Description
fetch	() => Promise<T> | T	Fetches the current data. Called on initial subscription and whenever publish() is called.
watch	({ publish }) => (() => void) | void	Sets up real-time monitoring. Call publish() to trigger a re-fetch. Return a cleanup function to unsubscribe when the client disconnects.

Using MongoDB Change Streams

The most common pattern for the watch function is MongoDB change streams, which notify you when documents in a collection are inserted, updated, or deleted:

import { LiveData } from 'modelence/server';
import { dbTodos } from './db';

// Watch all changes to a collection
queries: {
  getAll: async ({ userId }) => {
    return new LiveData({
      fetch: async () => await dbTodos.fetch({ userId }),
      watch: ({ publish }) => {
        const changeStream = dbTodos.watch();
        changeStream.on('change', () => publish());
        return () => changeStream.close();
      },
    });
  },
}

You can also use a pipeline to filter which changes trigger updates:

// Only watch for changes to a specific user's todos
queries: {
  getAll: async ({ userId }) => {
    return new LiveData({
      fetch: async () => await dbTodos.fetch({ userId }),
      watch: ({ publish }) => {
        const pipeline = [
          { $match: { 'fullDocument.userId': userId } },
        ];
        const changeStream = dbTodos.watch(pipeline);
        changeStream.on('change', () => publish());
        return () => changeStream.close();
      },
    });
  },
}

MongoDB change streams require a replica set or sharded cluster. If you’re using MongoDB Atlas, this is enabled by default. For local development, you need to configure a replica set.

Complete Example

Here’s a full example of a live todo list:

Server

// src/server/db.ts
import { Store, schema } from 'modelence/server';

export const dbTodos = new Store('todos', {
  schema: {
    title: schema.string(),
    isCompleted: schema.boolean(),
    userId: schema.userId(),
    createdAt: schema.date(),
  },
  indexes: [
    { key: { userId: 1 } },
  ],
});

// src/server/module.ts
import { Module, LiveData } from 'modelence/server';
import { z } from 'zod';
import { dbTodos } from './db';

export default new Module('todo', {
  stores: [dbTodos],

  queries: {
    getAll: async ({ userId }) => {
      return new LiveData({
        fetch: async () => await dbTodos.fetch(
          { userId },
          { sort: { createdAt: -1 } }
        ),
        watch: ({ publish }) => {
          const changeStream = dbTodos.watch();
          changeStream.on('change', () => publish());
          return () => changeStream.close();
        },
      });
    },
  },

  mutations: {
    create: async (args, { user }) => {
      const { title } = z.object({ title: z.string() }).parse(args);
      await dbTodos.insertOne({
        title,
        isCompleted: false,
        userId: user.id,
        createdAt: new Date(),
      });
    },

    toggleComplete: async (args) => {
      const { id, isCompleted } = z.object({
        id: z.string(),
        isCompleted: z.boolean(),
      }).parse(args);
      await dbTodos.updateOne(id, { $set: { isCompleted } });
    },
  },
});

Client

// src/client/index.tsx
import { renderApp } from 'modelence/client';
import TodoList from './pages/TodoList';

// renderApp injects ModelenceQueryProvider automatically — no manual wiring.
renderApp({
  loadingElement: <div>Loading…</div>,
  routesElement: <TodoList />,
});

// src/client/pages/TodoList.tsx
import { useQuery, useMutation } from '@tanstack/react-query';
import { modelenceLiveQuery, modelenceMutation } from 'modelence/client';
import { useSession } from 'modelence/client';

export default function TodoList() {
  const { user } = useSession();

  // Live query - automatically updates when todos change
  const { data: todos, isLoading } = useQuery(
    modelenceLiveQuery('todo.getAll', { userId: user?.id })
  );

  const { mutate: createTodo } = useMutation(
    modelenceMutation('todo.create')
  );

  const { mutate: toggleComplete } = useMutation(
    modelenceMutation('todo.toggleComplete')
  );

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <button onClick={() => createTodo({ title: 'New Todo' })}>
        Add Todo
      </button>

      <ul>
        {todos?.map(todo => (
          <li key={todo._id}>
            <input
              type="checkbox"
              checked={todo.isCompleted}
              onChange={() => toggleComplete({
                id: todo._id,
                isCompleted: !todo.isCompleted,
              })}
            />
            {todo.title}
          </li>
        ))}
      </ul>
    </div>
  );
}

With this setup, when any client creates or updates a todo, all connected clients see the changes immediately.

Live Queries vs WebSockets

Feature	Live Queries	WebSockets
Use case	Automatic data sync with TanStack Query	Custom real-time messaging
Data flow	Server watches data, pushes updates	Bidirectional messaging
Client API	useQuery(modelenceLiveQuery(...))	ClientChannel + joinChannel
Server API	LiveData with fetch + watch	ServerChannel + broadcast
Best for	Lists, dashboards, any data-driven UI	Chat, notifications, collaborative editing

Live queries are built on top of WebSockets internally, but provide a higher-level abstraction for the common pattern of keeping query data in sync.

Common Pitfalls

Missing QueryClient connection

If you see Modelence: connect a QueryClient before using modelenceLiveQuery(), you mounted your own QueryClientProvider without connecting it. Either drop your custom provider and let renderApp inject ModelenceQueryProvider, or connect your client explicitly:

import { connectModelenceQueryClient } from 'modelence/client';

const queryClient = new QueryClient();
connectModelenceQueryClient(queryClient);

Returning plain data instead of LiveData

If you see Live query handler for 'X' must return a LiveData object, your query handler is returning data directly. Wrap it in LiveData:

// Wrong
getAll: async () => {
  return await dbItems.fetch({});
},

// Correct
getAll: async () => {
  return new LiveData({
    fetch: async () => await dbItems.fetch({}),
    watch: ({ publish }) => {
      const changeStream = dbItems.watch();
      changeStream.on('change', () => publish());
      return () => changeStream.close();
    },
  });
},

Forgetting to close change streams

Always return a cleanup function from watch to close change streams. Without this, streams accumulate and may exhaust database connections:

watch: ({ publish }) => {
  const changeStream = dbTodos.watch();
  changeStream.on('change', () => publish());
  return () => changeStream.close(); // Don't forget this!
},

Migrating from @modelence/react-query

Since modelence@0.15.0, the query helpers live in modelence/client, and renderApp connects a QueryClient for you. Existing apps using @modelence/react-query keep working — this migration is optional — but new code should use the core imports.

1. Swap the import source. The helpers are drop-in identical:

- import { modelenceQuery, modelenceLiveQuery, modelenceMutation } from '@modelence/react-query';
+ import { modelenceQuery, modelenceLiveQuery, modelenceMutation } from 'modelence/client';

2. Drop the manual provider wiring (optional). If you connected the client only to satisfy live queries, you can let renderApp inject ModelenceQueryProvider and remove the boilerplate:

- import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
- import { ModelenceQueryClient } from '@modelence/react-query';
  import { renderApp } from 'modelence/client';

- const queryClient = new QueryClient();
- new ModelenceQueryClient().connect(queryClient);

  renderApp({
-   routesElement: (
-     <QueryClientProvider client={queryClient}>{routes}</QueryClientProvider>
-   ),
+   loadingElement: <div>Loading…</div>,
+   routesElement: routes,
  });

If you still need your own QueryClient, replace new ModelenceQueryClient().connect(queryClient) with connectModelenceQueryClient(queryClient) (the ModelenceQueryClient class is deprecated but still exported for compatibility).

API Reference

• modelenceQuery - Standard (non-live) query helper
• modelenceLiveQuery - Live query helper
• ModelenceQueryProvider - Auto-connecting provider
• Store - Database store with watch() support