Add ability to pass meta to useLiveQuery and useLiveInfiniteQuery

[ValenCassa]

Summary

Allow passing custom metadata from query hooks (useLiveQuery, useLiveInfiniteQuery, etc.) directly to a collection's queryFn.

Proposed API

Collection definition

Define a meta type as the third generic parameter:

type Todo = { id: string; title: string; completed: boolean }

type TodoMeta = {
  showCompleted?: boolean
  category?: string
}

export const todosCollection = createCollection(
  queryCollectionOptions<Todo, string, TodoMeta>({
    queryKey: ["todos"],
    syncMode: "on-demand",
    queryFn: async ctx => {
      // Custom meta - typed as TodoMeta
      const { showCompleted, category } = ctx.meta ?? {}
      
      // Existing loadSubsetOptions unchanged
      const { limit, offset } = ctx.meta?.loadSubsetOptions ?? {}
      
      return api.getTodos({ showCompleted, category, limit, offset })
    }
  })
)

Query usage

When using the collection, the meta option is typed based on what the collection expects:

const { data } = useLiveQuery(
  q => q.from({ todo: todosCollection }).where(...),
  {
    meta: {
      showCompleted: false,
      category: "work"
    }
  },
  [deps]
)

The same applies to useLiveInfiniteQuery and other query hooks.

Example: Passing filters

A common use case is passing filters to the collection's queryFn for server-side filtering. Note that you still need to construct the where clause for client-side evaluation - meta just provides a way to send data directly to the collection:

type TaskMeta = {
  filters?: Array<{ field: string; operator: string; value: unknown }>
}

export const tasksCollection = createCollection(
  queryCollectionOptions<Task, string, TaskMeta>({
    queryKey: ["tasks"],
    syncMode: "on-demand",
    queryFn: async ctx => {
      const filters = ctx.meta?.filters ?? []
      return api.getTasks({ filters })
    }
  })
)

const { data } = useLiveQuery(
  q => q.from({ task: tasksCollection }).where(...),
  {
    meta: {
      filters: [
        { field: "status", operator: "eq", value: "active" },
        { field: "priority", operator: "gt", value: 5 }
      ]
    }
  },
  [filters]
)

[tigawanna]

I also need something like this, pretty useful for options that on the backend api cares about eg page to get that paginated response slice