@risingwave/wavelet-server 0.1.4 → 0.2.4

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@risingwave/wavelet-server",
-  "version": "0.1.4",
+  "version": "0.2.4",
   "description": "Wavelet server - WebSocket fanout layer for RisingWave",
+  "homepage": "https://github.com/risingwavelabs/wavelet",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/risingwavelabs/wavelet.git",
+    "directory": "packages/server"
+  },
+  "bugs": {
+    "url": "https://github.com/risingwavelabs/wavelet/issues"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
@@ -13,7 +22,7 @@
     "pg": "^8.13.0",
     "ws": "^8.18.0",
     "jose": "^6.0.0",
-    "@risingwave/wavelet": "0.1.4"
+    "@risingwave/wavelet": "0.2.4"
   },
   "devDependencies": {
     "@types/pg": "^8.11.0",

package/src/__tests__/http-api.test.ts

@@ -36,15 +36,15 @@ function request(server: http.Server, method: string, path: string, body?: unkno
 }
 
 describe('HttpApi', () => {
-  const streams = {
-    events: { columns: { user_id: 'string' as const, value: 'int' as const } },
+  const events = {
+    game_events: { columns: { user_id: 'string' as const, value: 'int' as const } },
   }
-  const views = {
+  const queries = {
     leaderboard: { _tag: 'sql' as const, text: 'SELECT 1' },
   }
 
   it('returns health check', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
       const res = await request(server, 'GET', '/v1/health')
@@ -55,32 +55,32 @@ describe('HttpApi', () => {
     }
   })
 
-  it('lists available views', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+  it('lists available queries', async () => {
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'GET', '/v1/views')
+      const res = await request(server, 'GET', '/v1/queries')
       expect(res.status).toBe(200)
-      expect(res.data).toEqual({ views: ['leaderboard'] })
+      expect(res.data).toEqual({ queries: ['leaderboard'] })
     } finally {
       server.close()
     }
   })
 
-  it('lists available streams', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+  it('lists available events', async () => {
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'GET', '/v1/streams')
+      const res = await request(server, 'GET', '/v1/events')
       expect(res.status).toBe(200)
-      expect(res.data).toEqual({ streams: ['events'] })
+      expect(res.data).toEqual({ events: ['game_events'] })
     } finally {
       server.close()
     }
   })
 
   it('returns 404 for unknown routes with helpful message', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
       const res = await request(server, 'GET', '/v1/nonexistent')
@@ -94,35 +94,35 @@ describe('HttpApi', () => {
   })
 
   it('handles CORS preflight', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'OPTIONS', '/v1/views')
+      const res = await request(server, 'OPTIONS', '/v1/queries')
       expect(res.status).toBe(204)
     } finally {
       server.close()
     }
   })
 
-  it('returns 404 for unknown stream', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+  it('returns 404 for unknown event', async () => {
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'POST', '/v1/streams/nonexistent', { x: 1 })
+      const res = await request(server, 'POST', '/v1/events/nonexistent', { x: 1 })
       expect(res.status).toBe(404)
-      expect(res.data.available_streams).toEqual(['events'])
+      expect(res.data.available_events).toEqual(['game_events'])
     } finally {
       server.close()
     }
   })
 
-  it('returns 404 for unknown view', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+  it('returns 404 for unknown query', async () => {
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'GET', '/v1/views/nonexistent')
+      const res = await request(server, 'GET', '/v1/queries/nonexistent')
       expect(res.status).toBe(404)
-      expect(res.data.available_views).toEqual(['leaderboard'])
+      expect(res.data.available_queries).toEqual(['leaderboard'])
     } finally {
       server.close()
     }

package/src/__tests__/integration.test.ts

@@ -36,7 +36,7 @@ const SUB_NAME = `wavelet_sub_${VIEW_NAME}`
 
 const testConfig: WaveletConfig = {
   database: DATABASE_URL,
-  streams: {
+  events: {
     [STREAM_NAME]: {
       columns: {
         user_id: 'string',
@@ -44,7 +44,7 @@ const testConfig: WaveletConfig = {
       },
     },
   },
-  views: {
+  queries: {
     [VIEW_NAME]: sql`
       SELECT user_id, SUM(value) AS total_value, COUNT(*) AS event_count
       FROM ${STREAM_NAME}
@@ -75,17 +75,17 @@ describe.runIf(process.env.WAVELET_INTEGRATION === '1')('Integration: DDL Manage
     await ddl.close()
   })
 
-  it('creates tables, views, and subscriptions', async () => {
+  it('creates tables, materialized views, and subscriptions', async () => {
     const actions = await ddl.sync(testConfig)
 
     const creates = actions.filter(a => a.type === 'create')
-    expect(creates.length).toBeGreaterThanOrEqual(3) // stream + view + subscription
+    expect(creates.length).toBeGreaterThanOrEqual(3) // event + query + subscription
 
-    const streamAction = creates.find(a => a.resource === 'stream' && a.name === STREAM_NAME)
-    expect(streamAction).toBeDefined()
+    const eventAction = creates.find(a => a.resource === 'event' && a.name === STREAM_NAME)
+    expect(eventAction).toBeDefined()
 
-    const viewAction = creates.find(a => a.resource === 'view' && a.name === VIEW_NAME)
-    expect(viewAction).toBeDefined()
+    const queryAction = creates.find(a => a.resource === 'query' && a.name === VIEW_NAME)
+    expect(queryAction).toBeDefined()
 
     const subAction = creates.find(a => a.resource === 'subscription' && a.name === SUB_NAME)
     expect(subAction).toBeDefined()
@@ -162,15 +162,15 @@ describe.runIf(process.env.WAVELET_INTEGRATION === '1')('Integration: Full Serve
     expect(data.status).toBe('ok')
   })
 
-  it('lists views', async () => {
-    const res = await fetch(`http://localhost:${port}/v1/views`)
+  it('lists queries', async () => {
+    const res = await fetch(`http://localhost:${port}/v1/queries`)
     const data = await res.json()
-    expect(data.views).toContain(VIEW_NAME)
+    expect(data.queries).toContain(VIEW_NAME)
   })
 
-  it('writes events via HTTP and reads view', async () => {
+  it('writes events via HTTP and reads query', async () => {
     // Write events
-    await fetch(`http://localhost:${port}/v1/streams/${STREAM_NAME}`, {
+    await fetch(`http://localhost:${port}/v1/events/${STREAM_NAME}`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ user_id: 'integration_test', value: 42 }),
@@ -179,8 +179,8 @@ describe.runIf(process.env.WAVELET_INTEGRATION === '1')('Integration: Full Serve
     // Wait for MV update
     await new Promise(r => setTimeout(r, 2000))
 
-    // Read view
-    const res = await fetch(`http://localhost:${port}/v1/views/${VIEW_NAME}`)
+    // Read query
+    const res = await fetch(`http://localhost:${port}/v1/queries/${VIEW_NAME}`)
     const data = await res.json()
     expect(data.rows.length).toBeGreaterThan(0)
   })
@@ -188,18 +188,21 @@ describe.runIf(process.env.WAVELET_INTEGRATION === '1')('Integration: Full Serve
   it('pushes diffs via WebSocket', async () => {
     const diff = await new Promise<any>((resolve, reject) => {
       const ws = new WebSocket(`ws://localhost:${port}/subscribe/${VIEW_NAME}`)
+      let sawSnapshot = false
 
       ws.on('message', (data: Buffer) => {
         const msg = JSON.parse(data.toString())
-        if (msg.type === 'connected') {
+        if (msg.type === 'snapshot') {
+          sawSnapshot = true
           // Write event to trigger diff
-          fetch(`http://localhost:${port}/v1/streams/${STREAM_NAME}`, {
+          fetch(`http://localhost:${port}/v1/events/${STREAM_NAME}`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ user_id: 'ws_test_user', value: 7 }),
           })
         }
         if (msg.type === 'diff') {
+          expect(sawSnapshot).toBe(true)
           ws.close()
           resolve(msg)
         }
@@ -214,4 +217,33 @@ describe.runIf(process.env.WAVELET_INTEGRATION === '1')('Integration: Full Serve
     // Should have at least one insert or update
     expect(diff.inserted.length + diff.updated.length).toBeGreaterThan(0)
   }, 20000)
+
+  it('pushes a snapshot immediately on connect', async () => {
+    await fetch(`http://localhost:${port}/v1/events/${STREAM_NAME}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ user_id: 'snapshot_user', value: 11 }),
+    })
+
+    await new Promise(r => setTimeout(r, 2000))
+
+    const snapshot = await new Promise<any>((resolve, reject) => {
+      const ws = new WebSocket(`ws://localhost:${port}/subscribe/${VIEW_NAME}`)
+
+      ws.on('message', (data: Buffer) => {
+        const msg = JSON.parse(data.toString())
+        if (msg.type === 'snapshot') {
+          ws.close()
+          resolve(msg)
+        }
+      })
+
+      ws.on('error', reject)
+      setTimeout(() => { ws.close(); reject(new Error('WebSocket snapshot timeout')) }, 15000)
+    })
+
+    expect(snapshot.type).toBe('snapshot')
+    expect(Array.isArray(snapshot.rows)).toBe(true)
+    expect(snapshot.rows.some((row: any) => row.user_id === 'snapshot_user')).toBe(true)
+  }, 20000)
 })

package/src/__tests__/ws-fanout.test.ts

@@ -0,0 +1,143 @@
+import { EventEmitter } from 'node:events'
+import { describe, it, expect, vi } from 'vitest'
+import { WebSocket } from 'ws'
+import { WebSocketFanout } from '../ws-fanout.js'
+import type { BootstrapResult, ViewDiff } from '../cursor-manager.js'
+
+class MockSocket extends EventEmitter {
+  readyState: number = WebSocket.OPEN
+  sent: string[] = []
+
+  send(message: string): void {
+    this.sent.push(message)
+  }
+
+  ping(): void {}
+
+  close(): void {
+    this.readyState = WebSocket.CLOSED
+    this.emit('close')
+  }
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+describe('WebSocketFanout', () => {
+  it('drops queued shared diffs that are already covered by bootstrap', async () => {
+    const bootstrapDeferred = deferred<BootstrapResult>()
+    const cursorManager = {
+      bootstrap: vi.fn().mockReturnValue(bootstrapDeferred.promise),
+    } as any
+    const jwt = {
+      isConfigured: () => false,
+    } as any
+
+    const fanout = new WebSocketFanout(cursorManager, jwt, {
+      leaderboard: {} as any,
+    })
+
+    const ws = new MockSocket()
+    const req = {
+      url: '/subscribe/leaderboard',
+      headers: { host: 'localhost' },
+    } as any
+
+    const connectionPromise = (fanout as any).handleConnection(ws, req)
+
+    fanout.broadcast('leaderboard', {
+      cursor: '150',
+      inserted: [{ player_id: 'alice', score: 10 }],
+      updated: [],
+      deleted: [],
+    })
+    fanout.broadcast('leaderboard', {
+      cursor: '300',
+      inserted: [{ player_id: 'bob', score: 20 }],
+      updated: [],
+      deleted: [],
+    })
+
+    bootstrapDeferred.resolve({
+      snapshotRows: [{ player_id: 'alice', score: 10 }],
+      diffs: [{
+        cursor: '200',
+        inserted: [],
+        updated: [{ player_id: 'alice', score: 15 }],
+        deleted: [],
+      }],
+      lastCursor: '200',
+    })
+
+    await connectionPromise
+
+    const messages = ws.sent.map((message) => JSON.parse(message))
+    expect(messages).toEqual([
+      { type: 'connected', query: 'leaderboard' },
+      {
+        type: 'snapshot',
+        query: 'leaderboard',
+        rows: [{ player_id: 'alice', score: 10 }],
+      },
+      {
+        type: 'diff',
+        query: 'leaderboard',
+        cursor: '200',
+        inserted: [],
+        updated: [{ player_id: 'alice', score: 15 }],
+        deleted: [],
+      },
+      {
+        type: 'diff',
+        query: 'leaderboard',
+        cursor: '300',
+        inserted: [{ player_id: 'bob', score: 20 }],
+        updated: [],
+        deleted: [],
+      },
+    ])
+  })
+
+  it('filters snapshot rows with the same claim rule as diffs', async () => {
+    const cursorManager = {
+      bootstrap: vi.fn().mockResolvedValue({
+        snapshotRows: [
+          { user_id: 'u1', total: 10 },
+          { user_id: 'u2', total: 20 },
+        ],
+        diffs: [] as ViewDiff[],
+        lastCursor: null,
+      }),
+    } as any
+    const jwt = {
+      isConfigured: () => true,
+      verify: vi.fn().mockResolvedValue({ user_id: 'u1' }),
+    } as any
+
+    const fanout = new WebSocketFanout(cursorManager, jwt, {
+      totals: { filterBy: 'user_id' } as any,
+    })
+
+    const ws = new MockSocket()
+    const req = {
+      url: '/subscribe/totals?token=test-token',
+      headers: { host: 'localhost' },
+    } as any
+
+    await (fanout as any).handleConnection(ws, req)
+
+    const snapshotMessage = JSON.parse(ws.sent[1])
+    expect(snapshotMessage).toEqual({
+      type: 'snapshot',
+      query: 'totals',
+      rows: [{ user_id: 'u1', total: 10 }],
+    })
+  })
+})

package/src/cursor-manager.ts

@@ -1,5 +1,5 @@
 import pg from 'pg'
-import type { SqlFragment, ViewDef } from '@risingwave/wavelet'
+import type { SqlFragment, QueryDef } from '@risingwave/wavelet'
 
 const { Client } = pg
 
@@ -16,12 +16,18 @@ export interface ViewDiff {
   deleted: Record<string, unknown>[]
 }
 
-type DiffCallback = (viewName: string, diff: ViewDiff) => void
+export interface BootstrapResult {
+  snapshotRows: Record<string, unknown>[]
+  diffs: ViewDiff[]
+  lastCursor: string | null
+}
+
+type DiffCallback = (queryName: string, diff: ViewDiff) => void
 
 /**
  * Manages persistent subscription cursors against RisingWave.
  *
- * Each view gets its own dedicated pg connection and a persistent cursor.
+ * Each query gets its own dedicated pg connection and a persistent cursor.
  * Uses blocking FETCH (WITH timeout) so there is no polling interval -
  * diffs are dispatched as soon as RisingWave produces them.
  */
@@ -29,15 +35,15 @@ export class CursorManager {
   // Shared connection for DDL (CREATE SUBSCRIPTION) and ad-hoc queries
   private client: InstanceType<typeof Client> | null = null
 
-  // Per-view dedicated connections for blocking FETCH
-  private viewConnections: Map<string, InstanceType<typeof Client>> = new Map()
+  // Per-query dedicated connections for blocking FETCH
+  private queryConnections: Map<string, InstanceType<typeof Client>> = new Map()
   private cursorNames: Map<string, string> = new Map()
   private subscriptions: Map<string, string> = new Map()
   private running = false
 
   constructor(
     private connectionString: string,
-    private views: Record<string, ViewDef | SqlFragment>
+    private queries: Record<string, QueryDef | SqlFragment>
   ) {}
 
   async initialize(): Promise<void> {
@@ -45,13 +51,13 @@ export class CursorManager {
     await this.client.connect()
     console.log('Connected to RisingWave')
 
-    for (const [viewName] of Object.entries(this.views)) {
-      const subName = `wavelet_sub_${viewName}`
+    for (const [queryName] of Object.entries(this.queries)) {
+      const subName = `wavelet_sub_${queryName}`
 
       // Create subscription if not exists (idempotent)
       try {
         await this.client.query(
-          `CREATE SUBSCRIPTION ${subName} FROM ${viewName} WITH (retention = '24h')`
+          `CREATE SUBSCRIPTION ${subName} FROM ${queryName} WITH (retention = '24h')`
         )
         console.log(`Created subscription: ${subName}`)
       } catch (err: any) {
@@ -62,31 +68,31 @@ export class CursorManager {
         }
       }
 
-      this.subscriptions.set(viewName, subName)
+      this.subscriptions.set(queryName, subName)
 
-      // Create dedicated connection and persistent cursor for this view
+      // Create dedicated connection and persistent cursor for this query
       const conn = new Client({ connectionString: this.connectionString })
       await conn.connect()
 
-      const cursorName = `wavelet_cur_${viewName}`
+      const cursorName = `wavelet_cur_${queryName}`
       await conn.query(`DECLARE ${cursorName} SUBSCRIPTION CURSOR FOR ${subName}`)
       console.log(`Opened persistent cursor: ${cursorName}`)
 
-      this.viewConnections.set(viewName, conn)
-      this.cursorNames.set(viewName, cursorName)
+      this.queryConnections.set(queryName, conn)
+      this.cursorNames.set(queryName, cursorName)
     }
   }
 
   /**
-   * Start listening for diffs on all views.
-   * Each view runs its own async loop with blocking FETCH.
+   * Start listening for diffs on all queries.
+   * Each query runs its own async loop with blocking FETCH.
    * No polling interval - FETCH blocks until data arrives or timeout.
    */
   startPolling(callback: DiffCallback): void {
     this.running = true
 
-    for (const [viewName] of this.subscriptions.entries()) {
-      this.listenLoop(viewName, callback)
+    for (const [queryName] of this.subscriptions.entries()) {
+      this.listenLoop(queryName, callback)
     }
   }
 
@@ -94,9 +100,9 @@ export class CursorManager {
     this.running = false
   }
 
-  private async listenLoop(viewName: string, callback: DiffCallback): Promise<void> {
-    const conn = this.viewConnections.get(viewName)
-    const cursorName = this.cursorNames.get(viewName)
+  private async listenLoop(queryName: string, callback: DiffCallback): Promise<void> {
+    const conn = this.queryConnections.get(queryName)
+    const cursorName = this.cursorNames.get(queryName)
     if (!conn || !cursorName) return
 
     while (this.running) {
@@ -108,12 +114,12 @@ export class CursorManager {
 
         if (result.rows.length === 0) continue
 
-        // Got at least one row. Drain any remaining rows without blocking.
+        // Got at least one row. Drain any remaining rows with timeout.
         const allRows = [...result.rows]
         let more = true
         while (more) {
           const batch = await conn.query(
-            `FETCH 100 FROM ${cursorName}`
+            `FETCH 100 FROM ${cursorName} WITH (timeout = '1s')`
           )
           if (batch.rows.length > 0) {
             allRows.push(...batch.rows)
@@ -122,14 +128,17 @@ export class CursorManager {
           }
         }
 
-        const diff = this.parseDiffs(allRows)
+        const diffs = this.parseDiffBatches(allRows)
 
-        if (diff.inserted.length > 0 || diff.updated.length > 0 || diff.deleted.length > 0) {
-          callback(viewName, diff)
+        for (const diff of diffs) {
+          if (diff.inserted.length === 0 && diff.updated.length === 0 && diff.deleted.length === 0) {
+            continue
+          }
+          callback(queryName, diff)
         }
       } catch (err: any) {
         if (!this.running) return
-        console.error(`[cursor-manager] Error fetching ${viewName}:`, err.message)
+        console.error(`[cursor-manager] Error fetching ${queryName}:`, err.message)
         // Back off on error, then retry
         await new Promise(r => setTimeout(r, 1000))
       }
@@ -173,6 +182,88 @@ export class CursorManager {
     return diff
   }
 
+  parseDiffBatches(rows: any[]): ViewDiff[] {
+    const diffs: ViewDiff[] = []
+    let currentRows: any[] = []
+    let currentCursor: string | null = null
+
+    for (const row of rows) {
+      const cursor = this.normalizeCursor(row.rw_timestamp)
+      if (!cursor) continue
+
+      if (currentCursor !== null && cursor !== currentCursor) {
+        diffs.push(this.parseDiffs(currentRows))
+        currentRows = []
+      }
+
+      currentCursor = cursor
+      currentRows.push(row)
+    }
+
+    if (currentRows.length > 0) {
+      diffs.push(this.parseDiffs(currentRows))
+    }
+
+    return diffs
+  }
+
+  async bootstrap(queryName: string): Promise<BootstrapResult> {
+    const subName = this.subscriptions.get(queryName)
+    if (!subName) {
+      throw new Error(
+        `Subscription for query '${queryName}' is not initialized. Start the server before accepting WebSocket clients.`
+      )
+    }
+
+    const conn = new Client({ connectionString: this.connectionString })
+    await conn.connect()
+
+    const cursorName = `wavelet_boot_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+
+    try {
+      await conn.query(`DECLARE ${cursorName} SUBSCRIPTION CURSOR FOR ${subName} FULL`)
+
+      const snapshotRows: Record<string, unknown>[] = []
+      const incrementalRows: any[] = []
+      let readingSnapshot = true
+
+      while (readingSnapshot) {
+        const result = await conn.query(`FETCH 1000 FROM ${cursorName}`)
+        if (result.rows.length === 0) break
+
+        let firstIncrementalIndex = result.rows.findIndex((row) => this.normalizeCursor(row.rw_timestamp) !== null)
+        if (firstIncrementalIndex === -1) firstIncrementalIndex = result.rows.length
+
+        for (const row of result.rows.slice(0, firstIncrementalIndex)) {
+          snapshotRows.push(this.stripSubscriptionMetadata(row))
+        }
+
+        if (firstIncrementalIndex < result.rows.length) {
+          incrementalRows.push(...result.rows.slice(firstIncrementalIndex))
+          readingSnapshot = false
+        }
+      }
+
+      while (true) {
+        const result = await conn.query(`FETCH 1000 FROM ${cursorName}`)
+        if (result.rows.length === 0) break
+        incrementalRows.push(...result.rows)
+      }
+
+      const diffs = this.parseDiffBatches(incrementalRows)
+      const lastCursor = diffs.length > 0 ? diffs[diffs.length - 1].cursor : null
+
+      return { snapshotRows, diffs, lastCursor }
+    } finally {
+      try {
+        await conn.query(`CLOSE ${cursorName}`)
+      } catch {}
+      try {
+        await conn.end()
+      } catch {}
+    }
+  }
+
   async query(sql: string): Promise<any[]> {
     if (!this.client) throw new Error('Not connected')
     const result = await this.client.query(sql)
@@ -187,9 +278,9 @@ export class CursorManager {
   async close(): Promise<void> {
     this.running = false
 
-    // Close per-view connections
-    for (const [viewName, conn] of this.viewConnections) {
-      const cursorName = this.cursorNames.get(viewName)
+    // Close per-query connections
+    for (const [queryName, conn] of this.queryConnections) {
+      const cursorName = this.cursorNames.get(queryName)
       try {
         if (cursorName) await conn.query(`CLOSE ${cursorName}`)
       } catch {}
@@ -197,7 +288,7 @@ export class CursorManager {
         await conn.end()
       } catch {}
     }
-    this.viewConnections.clear()
+    this.queryConnections.clear()
     this.cursorNames.clear()
 
     // Close shared connection
@@ -206,4 +297,15 @@ export class CursorManager {
     } catch {}
     this.client = null
   }
+
+  private stripSubscriptionMetadata(row: Record<string, unknown>): Record<string, unknown> {
+    const { op: _op, rw_timestamp: _rwTimestamp, ...data } = row
+    return data
+  }
+
+  private normalizeCursor(value: unknown): string | null {
+    if (value === null || value === undefined) return null
+    const cursor = String(value).trim()
+    return cursor === '' ? null : cursor
+  }
 }