Cursor Pagination and Infinite Scroll with Convex and Svelte

┌─────────────────────────────────────────────┐
│              Virtual List                    │
│  ┌───────────────────────────────────────┐  │
│  │  Live Data (WebSocket subscription)   │  │
│  │  → First page, real-time updates      │  │
│  └───────────────────────────────────────┘  │
│  ┌───────────────────────────────────────┐  │
│  │  Paginated Data (cursor queries)      │  │
│  │  → Loaded on scroll, stable history   │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

// convex/items.ts
import { query } from './_generated/server'
import { v } from 'convex/values'

export const listRecent = query({
    args: { limit: v.optional(v.number()) },
    handler: async (ctx, args) => {
        const limit = args.limit ?? 50
        return await ctx.db.query('items').order('desc').take(limit)
    }
})

// convex/items.ts
export const listPaginated = query({
    args: {
        cursor: v.optional(v.number()),
        limit: v.optional(v.number())
    },
    handler: async (ctx, args) => {
        const limit = args.limit ?? 50
        const cursor = args.cursor

        let queryBuilder = ctx.db.query('items')

        if (cursor !== undefined) {
            queryBuilder = queryBuilder.filter((q) => q.lt(q.field('_creationTime'), cursor))
        }

        const items = await queryBuilder.order('desc').take(limit + 1)

        const hasMore = items.length > limit
        const pageItems = hasMore ? items.slice(0, limit) : items

        return {
            items: pageItems,
            hasMore,
            nextCursor: pageItems.length > 0 ? pageItems[pageItems.length - 1]._creationTime : null
        }
    }
})

<script lang="ts">
    import { useQuery, useConvexClient } from 'convex-svelte'
    import { api } from '$lib/convex/api'
    import VirtualList from '@humanspeak/svelte-virtual-list'

    type Item = {
        _id: string
        _creationTime: number
        name: string
    }

    let { data } = $props()

    // Live layer: real-time subscription for newest items
    const liveQuery = useQuery(api.items.listRecent, { limit: 50 }, { initialData: data.items })

    const client = useConvexClient()

    // Pagination state
    let olderItems = $state<Item[]>([])
    let cursor = $state<number | null>(null)
    let hasMore = $state(true)

    // Merge live + paginated data
    const items = $derived.by(() => {
        const live = (liveQuery.data ?? data.items) as Item[]
        return [...live, ...olderItems]
    })

    // Track cursor from live data
    $effect(() => {
        const live = liveQuery.data as Item[] | undefined
        if (live && live.length > 0) {
            cursor = live[live.length - 1]._creationTime
        }
    })

    // Infinite scroll handler
    async function loadMore() {
        if (!hasMore || !cursor || !client) return

        const result = await client.query(api.items.listPaginated, { cursor, limit: 50 })

        olderItems = [...olderItems, ...result.items]
        cursor = result.nextCursor
        hasMore = result.hasMore
    }
</script>

<VirtualList {items} defaultEstimatedItemHeight={60} onLoadMore={loadMore} {hasMore}>
    {#snippet renderItem(item: Item)}
        <div class="item">{item.name}</div>
    {/snippet}
</VirtualList>

// convex/schema.ts
import { defineSchema, defineTable } from 'convex/server'
import { v } from 'convex/values'

export default defineSchema({
    messages: defineTable({
        conversation: v.id('conversations'),
        content: v.string(),
        isDeleted: v.optional(v.number()),
        createdAt: v.number(),
        updatedAt: v.number()
    }).index('by_conversation', ['conversation', 'isDeleted'])
})

<script lang="ts">
    import { useQuery, useConvexClient } from 'convex-svelte'
    import { api } from '$lib/convex/api'
    import VirtualList from '@humanspeak/svelte-virtual-list'

    type Message = {
        _id: string
        _creationTime: number
        conversation: string
        content: string
        nonce?: string
    }

    let { conversationId } = $props()

    const liveQuery = useQuery(api.messages.listByConversation, {
        conversation: conversationId,
        limit: 50
    })

    const client = useConvexClient()

    let optimisticMessages = $state<Message[]>([])
    let olderMessages = $state<Message[]>([])
    let cursor = $state<number | null>(null)
    let hasMore = $state(true)

    // Reset pagination when conversation changes
    $effect(() => {
        void conversationId
        olderMessages = []
        cursor = null
        hasMore = true
    })

    const serverMessages = $derived(liveQuery.data ?? [])

    $effect(() => {
        if (serverMessages.length > 0) {
            cursor = serverMessages[serverMessages.length - 1]._creationTime
        }
    })

    // Three-layer merge: optimistic + live + historical
    const messages = $derived.by(() => {
        const serverNonces = new Set(serverMessages.filter((m) => m.nonce).map((m) => m.nonce))
        const pending = optimisticMessages.filter((om) => !serverNonces.has(om._id))
        return [...pending, ...serverMessages, ...olderMessages]
    })

    async function loadMore() {
        if (!hasMore || !cursor || !client) return

        const result = await client.query(api.messages.listByConversationPaginated, {
            conversation: conversationId,
            cursor,
            limit: 50
        })

        if (!result) return
        olderMessages = [...olderMessages, ...result.items]
        cursor = result.nextCursor
        hasMore = result.hasMore
    }

    function sendMessage(content: string) {
        const nonce = crypto.randomUUID()
        const now = Date.now()

        optimisticMessages = [
            { _id: nonce, _creationTime: now, conversation: conversationId, content, nonce },
            ...optimisticMessages
        ]
    }
</script>

<VirtualList
    items={messages}
    mode="bottomToTop"
    defaultEstimatedItemHeight={60}
    onLoadMore={loadMore}
    {hasMore}
>
    {#snippet renderItem(message: Message)}
        <div class="message">{message.content}</div>
    {/snippet}
</VirtualList>

<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let { content, isStreaming } = $props()
</script>

<SvelteMarkdown source={content} streaming={isStreaming} />

$effect(() => {
    void conversationId // reactive dependency
    olderMessages = []
    cursor = null
    hasMore = true
})

// +page.server.ts
import { ConvexHttpClient } from 'convex/browser'

export const load = async () => {
    const client = new ConvexHttpClient(env.PUBLIC_CONVEX_URL!)
    const items = await client.query(api.items.listRecent, { limit: 50 })
    return { items }
}