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,
} 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>

<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): {
  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>
}

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

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

If you need to confirm the row was actually persisted (e.g., before navigating away), use createConfirmed instead - it awaits server acknowledgment:

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

Do not spread the existing record:

// ❌ 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)

There is no soft-delete primitive at the records layer. For chat messages, use [useMessages().softDelete](/sdk-reference/client/messaging#usemessages) which sets a tombstone flag instead.

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

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

Plain create resolves as soon as the local store is updated, which is usually before the server confirms. If the server then rejects the write (e.g., RBAC denial), the optimistic update [rolls back](/concepts/realtime-sync#the-optimistic-mutation-pipeline).

useUsers()#

Returns the users collection with role-management helpers.

type RoomUser = {
  id: string
  email: string
  name: string
  imageUrl?: string
  role: string
  createdAt: string
  lastSeenAt: string
}

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

useUserLookup()#

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

type UserInfo = {
  id: string
  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.

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.