id	useLiveQuery
title	useLiveQuery

Function: useLiveQuery()

Call Signature

function useLiveQuery<TContext>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:84

Create a live query using a query function

Type Parameters

TContext

TContext extends Context

Parameters

queryFn

(q) => QueryBuilder<TContext>

Query function that defines what data to fetch

deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

Returns

object

Object with reactive data, state, and status information

collection

collection: Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
}>;

data

data: InferResultType<TContext>;

isCleanedUp

isCleanedUp: boolean;

isEnabled

isEnabled: true;

isError

isError: boolean;

isIdle

isIdle: boolean;

isLoading

isLoading: boolean;

isReady

isReady: boolean;

state

state: Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>;

status

status: CollectionStatus;

Examples

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature

function useLiveQuery<TContext>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:101

Create a live query using a query function

Type Parameters

TContext

TContext extends Context

Parameters

queryFn

(q) => QueryBuilder<TContext> | null | undefined

Query function that defines what data to fetch

deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

Returns

object

Object with reactive data, state, and status information

collection

collection: 
  | Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
}, StandardSchemaV1<unknown, unknown>, { [K in string | number | symbol]: ResultValue<TContext>[K] }>
  | undefined;

data

data: InferResultType<TContext> | undefined;

isCleanedUp

isCleanedUp: boolean;

isEnabled

isEnabled: boolean;

isError

isError: boolean;

isIdle

isIdle: boolean;

isLoading

isLoading: boolean;

isReady

isReady: boolean;

state

state: 
  | Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>
  | undefined;

status

status: UseLiveQueryStatus;

Examples

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature

function useLiveQuery<TContext>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:120

Create a live query using a query function

Type Parameters

TContext

TContext extends Context

Parameters

queryFn

(q) => | LiveQueryCollectionConfig<TContext, RootQueryResult<TContext>> | null | undefined

Query function that defines what data to fetch

deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

Returns

object

Object with reactive data, state, and status information

collection

collection: 
  | Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
}, StandardSchemaV1<unknown, unknown>, { [K in string | number | symbol]: ResultValue<TContext>[K] }>
  | undefined;

data

data: InferResultType<TContext> | undefined;

isCleanedUp

isCleanedUp: boolean;

isEnabled

isEnabled: boolean;

isError

isError: boolean;

isIdle

isIdle: boolean;

isLoading

isLoading: boolean;

isReady

isReady: boolean;

state

state: 
  | Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>
  | undefined;

status

status: UseLiveQueryStatus;

Examples

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature

function useLiveQuery<TResult, TKey, TUtils>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:139

Create a live query using a query function

Type Parameters

TResult

TResult extends object

TKey

TKey extends string | number

TUtils

TUtils extends Record<string, any>

Parameters

queryFn

(q) => | Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> | null | undefined

Query function that defines what data to fetch

deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

Returns

object

Object with reactive data, state, and status information

collection

collection: 
  | Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>
  | undefined;

data

data: TResult[] | undefined;

isCleanedUp

isCleanedUp: boolean;

isEnabled

isEnabled: boolean;

isError

isError: boolean;

isIdle

isIdle: boolean;

isLoading

isLoading: boolean;

isReady

isReady: boolean;

state

state: Map<TKey, TResult> | undefined;

status

status: UseLiveQueryStatus;

Examples

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature

function useLiveQuery<TContext, TResult, TKey, TUtils>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:162

Create a live query using a query function

Type Parameters

TContext

TContext extends Context

TResult

TResult extends object

TKey

TKey extends string | number

TUtils

TUtils extends Record<string, any>

Parameters

queryFn

Query function that defines what data to fetch

deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

Returns

object

Object with reactive data, state, and status information

collection

collection: 
  | Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>
  | Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
}, StandardSchemaV1<unknown, unknown>, { [K in string | number | symbol]: ResultValue<TContext>[K] }>
  | undefined;

data

data: InferResultType<TContext> | TResult[] | undefined;

isCleanedUp

isCleanedUp: boolean;

isEnabled

isEnabled: boolean;

isError

isError: boolean;

isIdle

isIdle: boolean;

isLoading

isLoading: boolean;

isReady

isReady: boolean;

state

state: 
  | Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>
  | Map<TKey, TResult>
  | undefined;

status

status: UseLiveQueryStatus;

Examples

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature

function useLiveQuery<TContext>(config, deps?): object;

Defined in: useLiveQuery.ts:230

Create a live query using configuration object

Type Parameters

TContext

TContext extends Context

Parameters

config

LiveQueryCollectionConfig<TContext>

Configuration object with query and options

deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

Returns

object

Object with reactive data, state, and status information

collection

collection: Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
}>;

data

data: InferResultType<TContext>;

isCleanedUp

isCleanedUp: boolean;

isEnabled

isEnabled: true;

isError

isError: boolean;

isIdle

isIdle: boolean;

isLoading

isLoading: boolean;

isReady

isReady: boolean;

state

state: Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>;

status

status: CollectionStatus;

Examples

// Basic config object usage
const { data, status } = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60000
})

// With query builder and options
const queryBuilder = new Query()
  .from({ persons: collection })
  .where(({ persons }) => gt(persons.age, 30))
  .select(({ persons }) => ({ id: persons.id, name: persons.name }))

const { data, isReady } = useLiveQuery({ query: queryBuilder })

// Handle all states uniformly
const { data, isLoading, isReady, isError } = useLiveQuery({
  query: (q) => q.from({ items: itemCollection })
})

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Something went wrong</div>
if (!isReady) return <div>Preparing...</div>

return <div>{data.length} items loaded</div>

Call Signature

function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): object;

Defined in: useLiveQuery.ts:276

Subscribe to an existing live query collection

Type Parameters

TResult

TResult extends object

TKey

TKey extends string | number

TUtils

TUtils extends Record<string, any>

Parameters

liveQueryCollection

Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & NonSingleResult

Pre-created live query collection to subscribe to

Returns

object

Object with reactive data, state, and status information

collection

collection: Collection<TResult, TKey, TUtils>;

data

data: TResult[];

isCleanedUp

isCleanedUp: boolean;

isEnabled

isEnabled: true;

isError

isError: boolean;

isIdle

isIdle: boolean;

isLoading

isLoading: boolean;

isReady

isReady: boolean;

state

state: Map<TKey, TResult>;

status

status: CollectionStatus;

Examples

// Using pre-created live query collection
const myLiveQuery = createLiveQueryCollection((q) =>
  q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
)
const { data, collection } = useLiveQuery(myLiveQuery)

// Access collection methods directly
const { data, collection, isReady } = useLiveQuery(existingCollection)

// Use collection for mutations
const handleToggle = (id) => {
  collection.update(id, draft => { draft.completed = !draft.completed })
}

// Handle states consistently
const { data, isLoading, isError } = useLiveQuery(sharedCollection)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error loading data</div>

return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>

Call Signature

function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): object;

Defined in: useLiveQuery.ts:296

Create a live query using a query function

Type Parameters

TResult

TResult extends object

TKey

TKey extends string | number

TUtils

TUtils extends Record<string, any>

Parameters

liveQueryCollection

Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & SingleResult

Returns

object

Object with reactive data, state, and status information

collection

collection: Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & SingleResult;

data

data: TResult | undefined;

isCleanedUp

isCleanedUp: boolean;

isEnabled

isEnabled: true;

isError

isError: boolean;

isIdle

isIdle: boolean;

isLoading

isLoading: boolean;

isReady

isReady: boolean;

state

state: Map<TKey, TResult>;

status

status: CollectionStatus;

Examples

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

FilesExpand file tree

useLiveQuery.md

Latest commit

History

useLiveQuery.md

File metadata and controls

Function: useLiveQuery()

Call Signature

Type Parameters

TContext

Parameters

queryFn

deps?

Returns

collection

data

isCleanedUp

isEnabled

isError

isIdle

isLoading

isReady

state

status

Examples

Call Signature

Type Parameters

TContext

Parameters

queryFn

deps?

Returns

collection

data

isCleanedUp

isEnabled

isError

isIdle

isLoading

isReady

state

status

Examples

Call Signature

Type Parameters

TContext

Parameters

queryFn

deps?

Returns

collection

data

isCleanedUp

isEnabled

isError

isIdle

isLoading

isReady

state

status

Examples

Call Signature

Type Parameters

TResult

TKey

TUtils

Parameters

queryFn

deps?

Returns

collection

data

isCleanedUp

isEnabled

isError

isIdle

isLoading

isReady

state

status