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]

This feature would be so cool another suggestin would be queryMeta for passing extra values from a query doen into the hook like , parePage,nextCursor,totalCount... and this wuld just get over wrtten on every query where data.items is returned from the query and the reast and put in queryMeta to be accessed alongside data from the useLiveQuery

i feel like it would nuke lots of the pagination issues people are having