anolilab/lunora/lunora-realtime

Lunora Realtime

Consume Lunora functions reactively from the client. Queries are live subscriptions over WebSocket — a useQuery re-renders as soon as a mutation changes the rows it reads — and mutations can paint optimistically with automatic rollback.

Choosing a Channel

Decide by what you are sending. If the client could get it by running a query, use a live query: it is typed, runs under the caller's identity, and works across shards. Reach past it only for the rest.

Live topics are typed from their declaration: each topic's key and payload are validators on the stream, and codegen emits _generated/live.ts with a typed reference per topic. Full guide: the "Choosing a data channel" docs page.

When Not to Use

• Writing the server functions themselves — that's lunora-functions.
• Initial project/provider scaffolding — that's lunora-quickstart.
• Sign-in UI and the Authenticated gates — that's lunora-setup-auth.

Provider Setup

Create the LunoraClient once at module scope; it owns the WebSocket, the optimistic cache, and the offline queue, so creating it inside a component reopens the socket on every render.

import { LunoraProvider } from "@lunora/react";
import { LunoraClient } from "lunorash/client";
const url = (import.meta.env.VITE_LUNORA_URL as string | undefined) ?? globalThis.location.origin;
const client = new LunoraClient({ url });
// <LunoraProvider client={client}>…</LunoraProvider>

The adapters differ in how they register the client and name their primitives:

The rest of this skill uses the React names; the others mirror the same semantics (usePaginatedQuery → createPaginatedQuery / paginatedQuery, useConnectionStatus → createConnectionStatus / connectionStatus, …). React Native passes storage: AsyncStorage so the offline queue survives a restart; @lunora/react-native/auth bridges a better-auth Expo session. @lunora/astro and @lunora/nuxt (Nitro) integrate Lunora into the SSR server.

Live Queries

useQuery(reference, args, options?) opens a subscription and returns the value, or undefined while it loads. References come from codegen and are typed end to end, so no cast is needed:

import { useQuery } from "@lunora/react";
import { api } from "../lunora/_generated/api";
const todos = useQuery(api.todos.list, {});
const messages = useQuery(api.messages.list, { channelId }, { shardKey: channelId, onError: report });

• undefined means loading and [] means loaded-and-empty; branch on both.
• Pass "skip" as args to disable the query (no network call, no

subscription) — e.g. until a required id is known.

• Pass onError to see a server-pushed error (an RLS denial, a query that starts

throwing). Without it the error is dropped and the value silently freezes at its last good result.

• shardKey: for a .shardBy(...) table, pin every read and write to the

shard's key ({ shardKey: channelId } on both useQuery and the mutation call). Without it the runtime has to fan out across every shard.

• The subscription re-runs only when args or the rows it read change. Keep

args narrow so unrelated writes don't re-push data (see lunora-performance-audit).

• useSubscription is the push-only variant (no initial HTTP fetch) returning

{ data, error }. For SSR, @lunora/react/server exports preloadQuery, fetchQuery, and lunoraQueryOptions; hand the result to usePreloadedQuery on the client.

• References in folders are nested: lunora/billing/invoices.ts →

api.billing.invoices.<fn>. Client code only ever imports api; internal functions are not callable from the client.

Authorization & Live Queries

Live queries are identity-aware. At the WebSocket upgrade the runtime stamps the caller's verified identity onto the socket, and every subscription re-run executes under that identity, so:

• .use(rls(...)) and ctx.auth.userId behave the same in a subscription as in

a one-shot read. Shape subscriptions AND-merge their predicate with the table's RLS read policy.

• An anonymous socket carries no identity, so an RLS/ctx.auth query fails

closed (empty or denied) rather than leaking rows.

• When the credential carries an expiry, the server sends TOKEN_EXPIRED and

closes with code 4001. LunoraClient reconnects and re-resolves identity automatically; surface it in the UI only if a re-login is required.

Use .shardBy(...) and narrow args for performance, rls() / ctx.auth for authorization. They compose.

Mutations + Optimistic Updates

useMutation(reference) returns { mutate, pending, data, error, reset }. Destructure it — the hook result itself isn't callable. mutate returns a promise that rejects on failure. Pass optimisticUpdate to paint the next state immediately; if the server rejects the call the cache rolls back.

import { useMutation } from "@lunora/react";
import { api } from "../lunora/_generated/api";
import type { Doc, Id } from "../lunora/_generated/dataModel";
const { mutate: add, pending } = useMutation(api.todos.add);
await add(
    { text },
    {
        optimisticUpdate: (store) => {
            const list = store.getQuery(api.todos.list, {}) ?? [];
            const provisional: Doc<"todos"> = {
                _id: `optimistic_${Date.now()}` as Id<"todos">,
                _creationTime: Date.now(),
                text,
                done: false,
                createdAt: Date.now(),
            };
            store.setQuery(api.todos.list, {}, [provisional, ...list]);
        },
    },
);

• optimisticUpdate names the query it patches because nothing can infer that

todos.add affects todos.list. store.getAllQueries(fn) lists every subscribed args variant of a query so you can patch each one.

• The provisional row must match the query's element shape, including

_id/_creationTime, or the UI flickers when the real row lands.

• The per-call optimistic: (current) => next shortcut only patches a

subscription under the mutation's own reference and args (a counter, a doc by id). For the add-updates-list shape above it is a silent no-op.

• pending stays true until every overlapping call from this hook settles;

use it to disable the submit button.

• Offline, mutations are queued by LunoraClient and replayed on reconnect,

keyed by client id so they aren't applied twice.

Pagination, Connection, Presence

The server query takes paginationOpts and returns .paginate(...) (see lunora-functions). The hook supplies the cursor:

const { results, status, loadMore, error } = usePaginatedQuery(api.messages.page, { channelId }, { initialNumItems: 20 });
// status: "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted"

Pages are live ranges: inserts and deletes inside a loaded page grow or shrink it in place without duplicating rows. There is no total count; subscribe to a separate count query for "42 of 1,203". useInfiniteQuery is the TanStack-style alternative.

• useConnectionStatus — live socket state for an offline/reconnecting banner.
• usePresence — who's-here with heartbeat (pairs with the presence registry

item).

• useAuth + Authenticated / Unauthenticated / AuthLoading — see

lunora-setup-auth.

Live Topics

For an event with no query behind it ("a comment was posted"), the server publishes to a declared topic and the browser follows topics over one shared SSE connection (shared when the connection options match). Declare the stream and its topics once (defineLiveStream({ id, topics: { post: { key: { postId: v.id("posts") }, payload: v.object({...}) } }, onSubscribe })); codegen mounts its connect and control routes on the worker through .build() or .buildFrameworkWorker(host). Add liveStreamRouter yourself only when you compose the host with withLunora or withFrameworkWorker; the generated .buildFrameworkWorker(host) already wraps it. Follow topics with the adapter's hook (all return { lastEvent, error }). onSubscribe receives the parsed { ctx, topic, key, raw }; do not split a string. A subscribe for an undeclared name, wrong arity or a non-canonical spelling is denied before onSubscribe runs. Codegen writes _generated/live.ts:

import { live } from "../lunora/_generated/live";
// the route comes from the client in <LunoraProvider>; lastEvent / onEvent are typed by the payload
const { lastEvent, error } = useLiveTopic(live.posts.post({ postId }), { onEvent: (payload) => refresh(payload) });

Svelte's liveTopic and Angular's liveTopic read the client when called: call them during component init (Angular: or pass client and destroyRef). Pass shardKey in the options to follow a .shardBy shard.