StoreQueries • tldraw Docs

Table of contents

Methods
- exec
- filterHistory
- ids
- index
- record
- records

A class that provides reactive querying capabilities for a record store. Offers methods to create indexes, filter records, and perform efficient lookups with automatic cache management. All queries are reactive and will automatically update when the underlying store data changes.

class StoreQueries<R extends UnknownRecord> {}

Example

// Create a store with books
const store = new Store({
  schema: StoreSchema.create({ book: Book, author: Author }),
})

// Get reactive queries for books
const booksByAuthor = store.query.index('book', 'authorId')
const inStockBooks = store.query.records('book', () => ({
  inStock: { eq: true },
}))

Methods

exec( )

Executes a one-time query against the current store state and returns matching records. This is a non-reactive query that returns results immediately without creating a computed value. Use this when you need a snapshot of data at a specific point in time.

exec<TypeName extends R['typeName']>(
  typeName: TypeName,
  query: QueryExpression<
    Extract<
      R,
      {
        typeName: TypeName
      }
    >
  >
): Array<
  Extract<
    R,
    {
      typeName: TypeName
    }
  >
>

Example

// Get current in-stock books (non-reactive)
const currentInStockBooks = store.query.exec('book', { inStock: { eq: true } })
console.log(currentInStockBooks) // Book[]

// Unlike records(), this won't update when the data changes
const staticBookList = store.query.exec('book', {
  authorId: { eq: 'author:leguin' },
})

Parameters

Name	Description
`typeName`	`TypeName` The type name of records to query
`query`	`QueryExpression< Extract< R, { typeName: TypeName } > >` The query expression object to match against

Returns

Array<
  Extract<
    R,
    {
      typeName: TypeName
    }
  >
>

An array of records that match the query at the current moment

filterHistory( )

Creates a reactive computed that tracks the change history for records of a specific type. The returned computed provides incremental diffs showing what records of the given type have been added, updated, or removed.

filterHistory<TypeName extends R['typeName']>(
  typeName: TypeName
): Computed<
  number,
  RecordsDiff<
    Extract<
      R,
      {
        typeName: TypeName
      }
    >
  >
>

Example

// Track changes to book records only
const bookHistory = store.query.filterHistory('book')

// React to book changes
react('book-changes', () => {
  const currentEpoch = bookHistory.get()
  console.log('Books updated at epoch:', currentEpoch)
})

Parameters

Name	Description
`typeName`	`TypeName` The type name to filter the history by

Returns

Computed<
  number,
  RecordsDiff<
    Extract<
      R,
      {
        typeName: TypeName
      }
    >
  >
>

A computed value containing the current epoch and diffs of changes for the specified type

ids( )

Creates a reactive query that returns a set of record IDs matching the given query criteria. This is more efficient than records() when you only need the IDs and not the full record objects. The set automatically updates with collection diffs when records change.

ids<TypeName extends R['typeName']>(
  typeName: TypeName,
  queryCreator?: () => QueryExpression<
    Extract<
      R,
      {
        typeName: TypeName
      }
    >
  >,
  name?: string
): Computed<
  Set<
    IdOf<
      Extract<
        R,
        {
          typeName: TypeName
        }
      >
    >
  >,
  CollectionDiff<
    IdOf<
      Extract<
        R,
        {
          typeName: TypeName
        }
      >
    >
  >
>

Example

// Get IDs of all books in stock
const inStockBookIds = store.query.ids('book', () => ({
  inStock: { eq: true },
}))
console.log(inStockBookIds.get()) // Set<RecordId<Book>>

// Get all book IDs (no filter)
const allBookIds = store.query.ids('book')

// Use with other queries for efficient lookups
const authorBookIds = store.query.ids('book', () => ({
  authorId: { eq: 'author:leguin' },
}))

Parameters

Name	Description
`typeName`	`TypeName` The type name of records to query
`queryCreator`	`() => QueryExpression< Extract< R, { typeName: TypeName } > >` Function that returns the query expression object to match against
`name`	`string` Optional name for the query computation (used for debugging)

Returns

Computed<
  Set<
    IdOf<
      Extract<
        R,
        {
          typeName: TypeName
        }
      >
    >
  >,
  CollectionDiff<
    IdOf<
      Extract<
        R,
        {
          typeName: TypeName
        }
      >
    >
  >
>

A computed value containing a set of matching record IDs with collection diffs

index( )

Creates a reactive index that maps property values to sets of record IDs for efficient lookups. The index automatically updates when records are added, updated, or removed, and results are cached for performance.

index<
  TypeName extends R['typeName'],
  Property extends string &
    keyof Extract<
      R,
      {
        typeName: TypeName
      }
    >,
>(
  typeName: TypeName,
  property: Property
): RSIndex<
  Extract<
    R,
    {
      typeName: TypeName
    }
  >,
  Property
>

Example

// Create an index of books by author ID
const booksByAuthor = store.query.index('book', 'authorId')

// Get all books by a specific author
const authorBooks = booksByAuthor.get().get('author:leguin')
console.log(authorBooks) // Set<RecordId<Book>>

// Index by title for quick title lookups
const booksByTitle = store.query.index('book', 'title')
const booksLatheOfHeaven = booksByTitle.get().get('The Lathe of Heaven')

Parameters

Name	Description
`typeName`	`TypeName` The type name of records to index
`property`	`Property` The property name to index by

Returns

RSIndex<
  Extract<
    R,
    {
      typeName: TypeName
    }
  >,
  Property
>

A reactive computed containing the index map with change diffs

record( )

Creates a reactive query that returns the first record matching the given query criteria. Returns undefined if no matching record is found. The query automatically updates when records change.

record<TypeName extends R['typeName']>(
  typeName: TypeName,
  queryCreator?: () => QueryExpression<
    Extract<
      R,
      {
        typeName: TypeName
      }
    >
  >,
  name?: string
): Computed<
  | Extract<
      R,
      {
        typeName: TypeName
      }
    >
  | undefined
>

Example

// Find the first book with a specific title
const bookLatheOfHeaven = store.query.record('book', () => ({
  title: { eq: 'The Lathe of Heaven' },
}))
console.log(bookLatheOfHeaven.get()?.title) // 'The Lathe of Heaven' or undefined

// Find any book in stock
const anyInStockBook = store.query.record('book', () => ({
  inStock: { eq: true },
}))

Parameters

Name	Description
`typeName`	`TypeName` The type name of records to query
`queryCreator`	`() => QueryExpression< Extract< R, { typeName: TypeName } > >` Function that returns the query expression object to match against
`name`	`string` Optional name for the query computation (used for debugging)

Returns

Computed<
  | Extract<
      R,
      {
        typeName: TypeName
      }
    >
  | undefined
>

A computed value containing the first matching record or undefined

records( )

Creates a reactive query that returns an array of all records matching the given query criteria. The array automatically updates when records are added, updated, or removed.

records<TypeName extends R['typeName']>(
  typeName: TypeName,
  queryCreator?: () => QueryExpression<
    Extract<
      R,
      {
        typeName: TypeName
      }
    >
  >,
  name?: string
): Computed<
  Array<
    Extract<
      R,
      {
        typeName: TypeName
      }
    >
  >
>

Example

// Get all books in stock
const inStockBooks = store.query.records('book', () => ({
  inStock: { eq: true },
}))
console.log(inStockBooks.get()) // Book[]

// Get all books by a specific author
const leguinBooks = store.query.records('book', () => ({
  authorId: { eq: 'author:leguin' },
}))

// Get all books (no filter)
const allBooks = store.query.records('book')

Parameters

Name	Description
`typeName`	`TypeName` The type name of records to query
`queryCreator`	`() => QueryExpression< Extract< R, { typeName: TypeName } > >` Function that returns the query expression object to match against
`name`	`string` Optional name for the query computation (used for debugging)

Returns

Computed<
  Array<
    Extract<
      R,
      {
        typeName: TypeName
      }
    >
  >
>

A computed value containing an array of all matching records