Records reference

The records API is the primary surface for working with collections. Every hook and provider on this page is imported from deepspace.

import {
  RecordProvider, RecordScope, ScopeRegistryProvider,
  useQuery, useMutations, useUsers, useUserLookup, useRecordContext,
  RecordRoomNotReadyError, type WriteError,
} from 'deepspace'

For schemas and column types, see the worker schemas reference. For RBAC rules, see permissions.

Providers#

<RecordProvider>#

Initializes the WebSocket and in-memory record store. Required ancestor of every records hook.

<RecordProvider allowAnonymous>
  <App />
</RecordProvider>

Write errors (onWriteError)#

Optimistic mutations (create / put / remove) resolve before the server answers, so a denied or invalid write can only surface through onWriteError - it is the only surface where server-rejected optimistic writes appear. If you don't handle it, the app looks like the write worked while the server silently rejected it (the SDK's default handler logs a deduplicated console.error telling you to wire real UI).

interface WriteError {
  /** RBAC denial or data validation/other rejection. */
  kind: 'permission' | 'validation'
  /** Short human-readable summary, safe to show end users. */
  title: string
  /** Longer human-readable explanation; may be empty. */
  detail: string
}

The scaffold wires it to toasts - permission denials as warnings, everything else as errors. Keep this wiring when customizing the layout, and retrofit it into apps scaffolded before the prop existed:

const { error, warning } = useToast()   // scaffold's local toast hook

<RecordProvider
  allowAnonymous
  onWriteError={(e) =>
    e.kind === 'permission' ? warning(e.title, e.detail) : error(e.title, e.detail)
  }
>
  <App />
</RecordProvider>

When the next step depends on the write being accepted, prefer the confirmed mutation variants - they reject instead of routing through onWriteError.

<RecordScope>#

Mounts a specific scope (Durable Object instance). Nest for additional scopes.

<ScopeRegistryProvider>#

Required once near the root if your app uses shared scopes via sharedScopes. Coordinates routing between cross-app and per-app DOs.

useQuery<T>(collection, options?)#

Subscribes to a collection. Returns a reactive array of envelopes.

function useQuery<T>(
  collection: string,
  options?: {
    where?: Partial<T>
    orderBy?: string
    orderDir?: 'asc' | 'desc'
    limit?: number
  },
): {
  records: Envelope<T>[]
  status: 'loading' | 'ready' | 'error'
  error?: string
}

type Note = { title: string; body: string }

function Notes() {
  const { records, status } = useQuery<Note>('notes')

  if (status === 'loading') return <Skeleton />
  return records.map((r) => <li key={r.recordId}>{r.data.title}</li>)
}

const { records } = useQuery<Note>('notes', {
  where: { pinned: true },
})

const { records } = useQuery<Note>('notes', {
  orderBy: 'updatedAt',
  orderDir: 'desc',
  limit: 50,
})

const { records, status, error } = useQuery<Note>('notes')

if (status === 'loading') return <SkeletonList />
if (status === 'error') return <ErrorBanner message={error} />
if (records.length === 0) return <EmptyState />
return <NoteList notes={records} />

Envelope shape:

type Envelope<T> = {
  recordId: string
  data: T
  createdBy: string
  createdAt: string
  updatedAt: string
}

useMutations<T>(collection)#

Returns mutation functions for the given collection. Each mutation applies optimistically - the local store updates before the server confirms.

function useMutations<T>(collection: string): {
  /** True once the collection's RecordRoom can accept writes. */
  ready:           boolean
  create:          (data: T)                       => Promise<string>
  put:             (id: string, patch: Partial<T>) => Promise<void>
  remove:          (id: string)                    => Promise<void>
  createConfirmed: (data: T)                       => Promise<string>
  putConfirmed:    (id: string, patch: Partial<T>) => Promise<void>
  removeConfirmed: (id: string)                    => Promise<void>
}

The ready gate#

Every method throws RecordRoomNotReadyError (a Error subclass with code: 'not_ready') when called before the collection's RecordRoom connection is ready - during initial connect and after a disconnect. Disable write controls until ready so users can't trigger the throw:

const { ready, create } = useMutations<Note>('notes')

<button disabled={!ready} onClick={() => create({ title: 'Untitled', body: '', pinned: false })}>
  New note
</button>

If you do call a mutation from a code path that can run early, catch the error and check err.code === 'not_ready' to distinguish it from a server rejection.

const { create } = useMutations<Note>('notes')

const id = await create({
  title: 'Untitled',
  body: '',
  pinned: false,
})

const id = await createConfirmed({ title: 'New', body: '', pinned: false })
navigate(`/notes/${id}`)

const { put } = useMutations<Note>('notes')

await put(noteId, { pinned: true })          // only updates pinned
await put(noteId, { title: 'New title' })    // only updates title

// ❌ Wasteful - sends every field
await put(noteId, { ...note.data, pinned: true })

// ✅ Send only what changed
await put(noteId, { pinned: true })

const { remove } = useMutations<Note>('notes')

await remove(noteId)

const { createConfirmed } = useMutations<Note>('notes')

const id = await createConfirmed({ title: 'New' })
navigate(`/notes/${id}`)   // safe - server has persisted

useUsers()#

Returns the room's user directory with role-management helpers.

type RoomUser = {
  id: string
  /** Present only for admin callers. */
  email?: string
  name: string
  imageUrl?: string
  role: string
  /** Present only for admin callers. */
  createdAt?: string
  /** Present only for admin callers. */
  lastSeenAt?: string
}

function useUsers(): {
  users: RoomUser[]
  usersLoaded: boolean
  setRole: (userId: string, role: string) => void
  refresh: () => void
}

setRole accepts a free-form role string (e.g. 'admin', 'intern', or any value your schema understands) and dispatches the change without waiting for an ack. The Durable Object enforces who is allowed to call it. See permissions for how roles map onto collection RBAC rules.

The directory privacy contract#

The directory is filtered server-side, in two steps:

1. Row policy. Anonymous sockets receive no directory at all. For authenticated callers, rows first pass the app's users collection read policy for the caller's role - the fresh scaffold ships member.read: 'own', so a regular member's directory contains only their own row unless the app explicitly broadens the policy.
2. Field projection. Rows that pass are then projected to public identity for non-admin callers: { id, name, imageUrl?, role }. Admins receive the full fields (email, createdAt, lastSeenAt, plus any custom columns) - which is also why useUserLookup().getEmail only resolves emails for admin callers.

useUserLookup()#

O(1) wrapper around useUsers() for resolving userIds to display fields.

type UserInfo = {
  id: string
  /** Available to admins; ordinary members receive public identity only. */
  email?: string
  name: string
  imageUrl?: string
  role: string
}

function useUserLookup(): {
  users: RoomUser[]
  usersLoaded: boolean
  userMap: Map<string, UserInfo>
  getUser:  (userId: string) => UserInfo | null
  getEmail: (userId: string) => string | null
  getName:  (userId: string) => string | null
}

const { getName } = useUserLookup()
<p>By {getName(message.authorId) ?? 'unknown'}</p>

There is no getRole or getImageUrl - read those off getUser(id)?.role or getUser(id)?.imageUrl.

getEmail resolves an email only when the caller is an admin - non-admin callers receive the public-identity projection, which carries no email, so getEmail returns null for them. Don't build member-facing UI that depends on it.

useRecordContext()#

Low-level access to the record-store context (WebSocket send/receive primitives, ready state, user profile, etc.). Useful for building custom hooks or imperative reads outside React's render cycle. Most apps never need this.

See also#

• Data storage guide - schemas, CRUD, and patterns.
• Data model - collections, envelopes, scopes.
• Permissions - RBAC rules and the 'own' / 'shared' / 'published' shortcuts.
• Real-time sync - optimistic pipeline and consistency guarantees.
• Worker schemas reference - the CollectionSchema type and drop-in collections.