@cuboapp/crdt 1.0.15 → 1.0.17

package/src/server/index.ts

@@ -3,8 +3,12 @@ import { WsServerSocket } from '@cuboapp/ws'
 import { applyAwarenessUpdate, encodeAwarenessUpdate, removeAwarenessStates } from 'y-protocols/awareness'
 
 import { CUBO_CRDT_EVENT } from '../constants'
-import { CuboCrdtAction } from '../types'
-import { checkRowIsSutable } from '../utils'
+import { CuboCrdtAction, CuboCrdtListSyncData, CuboCrdtMutation } from '../types'
+import {
+  areCrdtListIdsEqual,
+  areCrdtListTotalsEqual,
+  checkRowIsSutable
+} from '../utils'
 
 import { CuboCrdtClientDocOrigin } from '../client'
 import { CuboCrdtServerDocument } from './document'
@@ -14,6 +18,7 @@ import {
   CuboCrdtServerOptions,
   CuboCrdtServerSubscribe,
   CuboCrdtServerSubscribeDto,
+  CuboCrdtSubscribeRefreshState,
   CuboCrdtServerUnsubscribeDto,
   CuboCrdtSocketClient
 } from './types'
@@ -31,8 +36,8 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
   private subscribes = new Map<string, CuboCrdtServerSubscribe>()
   private subscribesByClient = new Map<string, Set<string>>()
   private subscribesByEntity = new Map<E, Set<string>>()
-  private subscribesIniting = new Map<string, Promise<void>>()
-  private subscribesUpgrading = new Map<string, Promise<void>>()
+  private subscribeRefreshStates = new Map<string, CuboCrdtSubscribeRefreshState>()
+  private subscribeGenerations = new Map<string, number>()
 
   private documents = new Map<string, CuboCrdtServerDocument>()
   private subscribesByDocument = new Map<string, Set<string>>()
@@ -44,18 +49,27 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     this.entities.forEach((e) => this.subscribesByEntity.set(e, new Set()))
 
     this.ws.registerHandler(CUBO_CRDT_EVENT.SUBSCRIBE, async ({ client, message }) => {
-      const { subscribe_id: id, entity, filters, awareness = false } = message.data as CuboCrdtServerSubscribeDto
+      const { subscribe_id: id, entity, filters, awareness = false, paginated } = message.data as CuboCrdtServerSubscribeDto
 
       if (this.debug) {
         console.log('[CRDT] subscribe', entity, filters)
       }
 
+      const existing = this.subscribes.get(id)
+      if (existing) {
+        this.cleanSubscribe(id)
+      }
+
       const subscribe = {
         id,
         client_id: client.id,
         entity,
-        filters,
-        awareness
+        filters: cloneDeep(filters || {}),
+        awareness,
+        paginated: this.resolvePaginated(filters, paginated),
+        row_ids: [],
+        totals: {},
+        revision: 0
       }
 
       this.subscribes.set(id, subscribe)
@@ -67,11 +81,13 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       this.subscribesByEntity.get(entity as E)?.add(id)
 
       // инициализируем подписку
-      this.initSubscribe(client, subscribe)
+      await this.initSubscribe(client, subscribe)
+
+      return { subscribe_id: id, revision: subscribe.revision }
     })
 
     this.ws.registerHandler(CUBO_CRDT_EVENT.UPGRADE, async ({ client, message }) => {
-      const { subscribe_id: id, entity, filters } = message.data as CuboCrdtServerSubscribeDto
+      const { subscribe_id: id, entity, filters, paginated } = message.data as CuboCrdtServerSubscribeDto
 
       if (this.debug) {
         console.log('[CRDT] upgrade', entity, filters)
@@ -83,7 +99,9 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       }
 
       // обновляем подписку
-      this.upgradeSubscribe(client, subscribe, { filters })
+      await this.upgradeSubscribe(client, subscribe, { filters, paginated })
+
+      return { subscribe_id: id, revision: subscribe.revision }
     })
 
     this.ws.registerHandler(CUBO_CRDT_EVENT.UNSUBSCRIBE, async ({ message }) => {
@@ -148,9 +166,14 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
   public async destroy() {
     this.ws.deleteHandler(CUBO_CRDT_EVENT.SUBSCRIBE)
+    this.ws.deleteHandler(CUBO_CRDT_EVENT.UPGRADE)
     this.ws.deleteHandler(CUBO_CRDT_EVENT.UNSUBSCRIBE)
     this.ws.deleteHandler(CUBO_CRDT_EVENT.EVENT)
 
+    this.subscribeRefreshStates.forEach((state) => clearTimeout(state.timer))
+    this.subscribeRefreshStates.clear()
+    this.subscribeGenerations.clear()
+
     this.subscribes.forEach((sub) => this.ws.deleteHandler(sub.id))
   }
 
@@ -192,6 +215,21 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     return this.options.batch?.debounce ?? 100
   }
 
+  private get paginationDebounce() {
+    return this.options.pagination?.debounce ?? 75
+  }
+
+  private resolvePaginated(filters?: Record<string, any>, explicit?: boolean) {
+    if (explicit !== undefined) {
+      return explicit
+    }
+
+    const page = Number(filters?.page)
+    const limit = Number(filters?.limit)
+
+    return Number.isFinite(page) && page > 0 && Number.isFinite(limit) && limit > 0
+  }
+
   private sendQueueToClient(client: CuboCrdtSocketClient<A>) {
     // снимаем запланированный флаш — мы отправляем прямо сейчас
     clearTimeout(this.sendTimeouts.get(client.id))
@@ -329,6 +367,11 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     // удаляем обратный индекс
     this.documentsBySubscribe.delete(subscribe_id)
 
+    const refreshState = this.subscribeRefreshStates.get(subscribe_id)
+    clearTimeout(refreshState?.timer)
+    this.subscribeRefreshStates.delete(subscribe_id)
+    this.subscribeGenerations.delete(subscribe_id)
+
     // удаляем подписки
     this.subscribes.delete(subscribe_id)
     this.subscribesByClient.get(subscribe.client_id)?.delete(subscribe_id)
@@ -355,6 +398,196 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     })
   }
 
+  private getSubscribeRefreshState(subscribe_id: string) {
+    let state = this.subscribeRefreshStates.get(subscribe_id)
+    if (!state) {
+      state = { dirty: false, forceSync: false }
+      this.subscribeRefreshStates.set(subscribe_id, state)
+    }
+    return state
+  }
+
+  private bumpSubscribeGeneration(subscribe_id: string) {
+    const generation = (this.subscribeGenerations.get(subscribe_id) || 0) + 1
+    this.subscribeGenerations.set(subscribe_id, generation)
+    return generation
+  }
+
+  private runSubscribeRefresh(subscribe_id: string) {
+    const state = this.getSubscribeRefreshState(subscribe_id)
+    if (state.running) {
+      return state.running
+    }
+
+    state.running = (async () => {
+      while (state.dirty) {
+        state.dirty = false
+
+        const subscribe = this.subscribes.get(subscribe_id)
+        if (!subscribe) {
+          return
+        }
+
+        const client = this.clients.get(subscribe.client_id)
+        if (!client) {
+          return
+        }
+
+        const generation = this.subscribeGenerations.get(subscribe_id) || 0
+        const forceSync = state.forceSync
+        state.forceSync = false
+        const reconciled = await this.reconcileSubscribe(
+          client,
+          subscribe,
+          generation,
+          forceSync
+        )
+        if (!reconciled && forceSync) {
+          state.forceSync = true
+        }
+      }
+    })().finally(() => {
+      state.running = undefined
+    })
+
+    return state.running
+  }
+
+  private requestSubscribeRefresh(
+    subscribe_id: string,
+    immediate = false,
+    forceSync = immediate
+  ) {
+    const state = this.getSubscribeRefreshState(subscribe_id)
+    state.dirty = true
+    state.forceSync ||= forceSync
+    this.bumpSubscribeGeneration(subscribe_id)
+
+    if (immediate) {
+      clearTimeout(state.timer)
+      state.timer = undefined
+      return this.runSubscribeRefresh(subscribe_id)
+    }
+
+    if (!state.timer && !state.running) {
+      state.timer = setTimeout(() => {
+        state.timer = undefined
+        this.runSubscribeRefresh(subscribe_id).catch((e) => {
+          if (this.debug) {
+            console.error('[CRDT] refresh subscribe', subscribe_id, e)
+          }
+        })
+      }, this.paginationDebounce)
+    }
+
+    return state.running ?? Promise.resolve()
+  }
+
+  private getSubscribeQueryKeys(filters?: Record<string, any>) {
+    const keys = new Set<string>()
+
+    Object.keys(filters || {}).forEach((key) => {
+      if (!['page', 'limit', 'sort', 'with'].includes(key)) {
+        keys.add(key)
+
+        const rangeKey = key.replace(/_(start|end)$/, '')
+        if (rangeKey !== key) {
+          keys.add(rangeKey)
+        }
+
+        if (key.endsWith('_ids')) {
+          keys.add(key.slice(0, -1))
+        }
+      }
+    })
+
+    const appendSort = (sort: unknown) => {
+      if (Array.isArray(sort)) {
+        sort.forEach(appendSort)
+        return
+      }
+      if (typeof sort !== 'string') {
+        return
+      }
+
+      sort
+        .split(',')
+        .map((item) => item.trim().replace(/^-/, '').split(':')[0])
+        .filter(Boolean)
+        .forEach((key) => keys.add(key))
+    }
+
+    appendSort(filters?.sort)
+
+    return keys
+  }
+
+  private shouldRefreshSubscribe(entity: E, subscribe: CuboCrdtServerSubscribe, mutation: CuboCrdtMutation<M[E]>) {
+    if (!subscribe.paginated) {
+      return false
+    }
+
+    if (this.options.shouldRefreshSubscribe) {
+      return this.options.shouldRefreshSubscribe({ entity, subscribe, mutation })
+    }
+
+    if (mutation.action !== 'update' || !mutation.changedKeys?.length) {
+      return true
+    }
+
+    if (mutation.previousRow) {
+      const previousSuitable = this.checkRowIsSutable(
+        mutation.previousRow,
+        subscribe,
+        entity
+      )
+      const currentSuitable = this.checkRowIsSutable(
+        mutation.row,
+        subscribe,
+        entity
+      )
+
+      if (previousSuitable !== currentSuitable) {
+        return true
+      }
+    }
+
+    if (subscribe.filters?.search) {
+      return true
+    }
+
+    const queryKeys = this.getSubscribeQueryKeys(subscribe.filters)
+    return mutation.changedKeys.some((key) => queryKeys.has(key))
+  }
+
+  /**
+   * Уведомляет пагинированные подписки о сохранённой мутации.
+   * Пересчитываются только реально открытые страницы; несколько мутаций
+   * схлопываются debounce-ом в один запрос на подписку.
+   */
+  public notifyMutation(entity: E, mutation: CuboCrdtMutation<M[E]>) {
+    for (const subscribe_id of this.subscribesByEntity.get(entity) || []) {
+      const subscribe = this.subscribes.get(subscribe_id)
+      if (subscribe && this.shouldRefreshSubscribe(entity, subscribe, mutation)) {
+        this.requestSubscribeRefresh(subscribe_id)
+      }
+    }
+  }
+
+  /**
+   * Принудительно инвалидирует все открытые пагинированные окна сущности.
+   * Используется для вычисляемых полей и зависимых сущностей, когда changedKeys
+   * исходной строки недостаточно для определения влияния на запрос.
+   */
+  public invalidate(entity: E) {
+    for (const subscribe_id of this.subscribesByEntity.get(entity) || []) {
+      const subscribe = this.subscribes.get(subscribe_id)
+      if (subscribe?.paginated) {
+        this.requestSubscribeRefresh(subscribe_id)
+      }
+    }
+  }
+
   // создаёт (или возвращает существующий) серверный документ БЕЗ рассылки подписчикам.
   // Используется как для рассылочного пути (ensureDocument), так и для точечной
   // доставки на init подписки (pushSubscribeDocuments).
@@ -364,6 +597,21 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
     let document = this.documents.get(documentName)
     if (document) {
+      // Освежаем существующий документ строкой из БД.
+      //
+      // Раньше документ возвращался как есть, а подписка отправляла клиенту его
+      // stateAsUpdate — то есть КЭШ документа, а не только что прочитанную строку.
+      // Документ, проспавший мутацию, оставался устаревшим навсегда: даже перезагрузка
+      // страницы отдавала старое значение, потому что reconcile брал его же.
+      //
+      // Стало заметно после того, как документы без подписчиков начали удаляться:
+      // документ может быть создан, остаться без подписок, пропустить мутации и
+      // «воскреснуть» на новой подписке уже неактуальным.
+      //
+      // store: false — это не правка от клиента, а синхронизация с БД, писать обратно нечего.
+      document.write(row, { expose: 'all', store: false })
+      document.setPersistedState(row)
+
       return document
     }
 
@@ -377,12 +625,18 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       onAwarenessUpdate: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => {
         this.pushDocumentAction('awareness', entity, document!, data, origin)
       },
-      onStore: (item: object, origin: CuboCrdtServerDocumentOrigin) => {
+      onStore: (item: object, origin: CuboCrdtServerDocumentOrigin, store) => {
         const subscribe = origin.subscribe_id && this.subscribes.get(origin.subscribe_id)
         const client = subscribe && this.clients.get(subscribe.client_id)
 
         if (client) {
-          return this.options?.storeRow?.(entity as any, entity_id, item as any, { document, client, origin })
+          return this.options?.storeRow?.(entity as any, entity_id, item as any, {
+            document,
+            client,
+            origin,
+            previousRow: store.previousRow as any,
+            row: store.row as any
+          })
         }
       }
     })
@@ -411,8 +665,14 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
     if (!existed) {
       this.pushDocumentAction('create', entity, document, document.stateAsUpdate)
-    } else {
-      this.pushDocumentAction('upsert', entity, document, document.stateAsUpdate)
+    }
+
+    // Для уже существующего документа освежать состояние здесь не нужно —
+    // это делает getOrCreateDocument, одинаково для всех путей (рассылка и подписка).
+    // write() сам пропускает неизменившиеся ключи, так что лишних update-эвентов нет.
+
+    if (!this.subscribesByDocument.get(documentName)?.size) {
+      this.checkDocumentNeedRemove(documentName)
     }
 
     return document
@@ -568,9 +828,13 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
         const subscribeSutable = this.checkSubscribeIsSutable(origin, subscribe)
         const documentExistsInSubscribe = this.subscribesByDocument.get(document.name)?.has(subscribe.id)
-        const rowSutable = this.checkRowIsSutable(row, subscribe, entity)
+        const rowSutable = subscribe.paginated
+          ? documentExistsInSubscribe
+          : this.checkRowIsSutable(row, subscribe, entity)
 
-        const sutable = subscribeSutable && (rowSutable || documentExistsInSubscribe)
+        const sutable = subscribeSutable && (subscribe.paginated
+          ? documentExistsInSubscribe
+          : rowSutable || documentExistsInSubscribe)
 
         if (sutable) {
           if (this.debug && !rowSutable) {
@@ -671,95 +935,123 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     }
   }
 
-  private async pushSubscribeDocuments(client: WsServerSocket, subscribe: CuboCrdtServerSubscribe) {
-    // получаем строки под фильтры ЭТОЙ подписки
-    const rows = await this.options.fetchRows?.(client, subscribe)
+  private async reconcileSubscribe(
+    client: WsServerSocket,
+    subscribe: CuboCrdtServerSubscribe,
+    generation: number,
+    forceSync: boolean
+  ) {
+    const fetched = await this.options.fetchRows?.(client, subscribe)
+    const result = Array.isArray(fetched)
+      ? { rows: fetched, totals: subscribe.totals }
+      : { rows: fetched?.rows || [], totals: fetched?.totals || subscribe.totals }
+
+    if (
+      this.subscribes.get(subscribe.id) !== subscribe ||
+      this.subscribeGenerations.get(subscribe.id) !== generation
+    ) {
+      return false
+    }
+
+    const rowsById = new Map<number, any>()
+    const nextIds: number[] = []
+
+    for (const row of result.rows) {
+      const id = Number((row as any)?.id)
+      if (!Number.isFinite(id) || rowsById.has(id)) {
+        continue
+      }
+
+      rowsById.set(id, row)
+      nextIds.push(id)
+    }
+
+    const previousIds = new Set(subscribe.row_ids)
+    const nextIdsSet = new Set(nextIds)
+
+    for (const entity_id of subscribe.row_ids) {
+      if (nextIdsSet.has(entity_id)) {
+        continue
+      }
+
+      const documentName = `${subscribe.entity}:${entity_id}`
+      this.unlinkSubscribeFromDocument(subscribe.id, documentName)
+      this.checkDocumentNeedRemove(documentName)
+    }
+
+    for (const entity_id of nextIds) {
+      const row = rowsById.get(entity_id)
+      if (!row) {
+        continue
+      }
 
-    // Доставляем документы ТОЧЕЧНО инициирующей подписке. Раньше это шло через
-    // ensureDocument -> pushDocumentAction('upsert') с полным сканом всех подписок сущности
-    // НА КАЖДУЮ строку из fetchRows (до 10k) — главный усилитель нагрузки при (ре)подписке.
-    // Строки уже отфильтрованы под фильтры подписки в fetchRows, поэтому повторная
-    // проверка/рассылка остальным не нужна: живые create/update придут через onAfterCreate.
-    for (const row of rows || []) {
-      if ((row as any)?.id == null) {
+      if (previousIds.has(entity_id)) {
+        this.linkSubscribeToDocument(subscribe.id, `${subscribe.entity}:${entity_id}`)
         continue
       }
 
       const document = this.getOrCreateDocument(subscribe.entity as E, row, subscribe.awareness)
-      this.sendDocumentToSubscribe(subscribe, document, (row as any).id)
+      this.sendDocumentToSubscribe(subscribe, document, entity_id)
     }
+
+    const idsChanged = !areCrdtListIdsEqual(subscribe.row_ids, nextIds)
+    const totalsChanged = !areCrdtListTotalsEqual(
+      subscribe.totals,
+      result.totals
+    )
+
+    subscribe.row_ids = nextIds
+    subscribe.totals = result.totals
+
+    if (!forceSync && !idsChanged && !totalsChanged) {
+      return true
+    }
+
+    subscribe.revision += 1
+    const data: CuboCrdtListSyncData = {
+      ids: nextIds,
+      totals: subscribe.totals,
+      revision: subscribe.revision
+    }
+
+    this.sendToClient(subscribe.client_id, {
+      action: 'sync',
+      entity: subscribe.entity,
+      subscribe_id: subscribe.id,
+      data
+    })
+
+    return true
   }
 
   // апгрейд подписки (фильтры поменялись например)
   private async upgradeSubscribe(
     client: WsServerSocket,
     subscribe: CuboCrdtServerSubscribe,
-    upgrade: Partial<Pick<CuboCrdtServerSubscribe, 'filters'>>
+    upgrade: Partial<Pick<CuboCrdtServerSubscribe, 'filters' | 'paginated'>>
   ) {
-    if (this.subscribesUpgrading.has(subscribe.id)) {
-      return this.subscribesUpgrading.get(subscribe.id)
+    if (this.debug) {
+      console.log('[CRDT] upgrade subscribe ' + client.id, subscribe)
     }
 
-    this.subscribesUpgrading.set(
-      subscribe.id,
-      new Promise<void>(async (resolve, reject) => {
-        try {
-          if (this.debug) {
-            console.log('[CRDT] upgrade subscribe ' + client.id, subscribe)
-          }
-
-          if (upgrade.filters) {
-            subscribe.filters = cloneDeep(upgrade.filters || {})
-          }
-
-          await this.pushSubscribeDocuments(client, subscribe)
-
-          resolve()
-        } catch (e) {
-          if (this.debug) {
-            console.error('[CRDT] upgrade subscribe', e)
-          }
-
-          reject(e)
-        } finally {
-          this.subscribesUpgrading.delete(subscribe.id)
-        }
-      })
+    if (upgrade.filters !== undefined) {
+      subscribe.filters = cloneDeep(upgrade.filters || {})
+    }
+    subscribe.paginated = this.resolvePaginated(
+      subscribe.filters,
+      upgrade.paginated
     )
 
-    return this.subscribesUpgrading.get(subscribe.id)
+    return this.requestSubscribeRefresh(subscribe.id, true)
   }
 
   // инциализация подписки
   private async initSubscribe(client: WsServerSocket, subscribe: CuboCrdtServerSubscribe) {
-    if (this.subscribesIniting.has(subscribe.id)) {
-      return this.subscribesIniting.get(subscribe.id)
+    if (this.debug) {
+      console.log('[CRDT] init subscribe ' + client.id, subscribe)
     }
 
-    this.subscribesIniting.set(
-      subscribe.id,
-      new Promise<void>(async (resolve, reject) => {
-        try {
-          if (this.debug) {
-            console.log('[CRDT] init subscribe ' + client.id, subscribe)
-          }
-
-          await this.pushSubscribeDocuments(client, subscribe)
-
-          resolve()
-        } catch (e) {
-          if (this.debug) {
-            console.error('[CRDT] init subscribe', e)
-          }
-
-          reject(e)
-        } finally {
-          this.subscribesIniting.delete(subscribe.id)
-        }
-      })
-    )
-
-    return this.subscribesIniting.get(subscribe.id)
+    return this.requestSubscribeRefresh(subscribe.id, true)
   }
 
   private get debug() {

package/src/server/types/document.ts

@@ -1,8 +1,17 @@
 import { CuboCrdtAction, CuboCrdtExposeStrategy } from '../../types'
 
+export type CuboCrdtServerDocumentStoreContext = {
+  previousRow: object
+  row: object
+}
+
 export type CuboCrdtServerDocumentOptions = {
   name: string
-  onStore?: (body: object, origin: CuboCrdtServerDocumentOrigin) => void
+  onStore?: (
+    body: object,
+    origin: CuboCrdtServerDocumentOrigin,
+    context: CuboCrdtServerDocumentStoreContext
+  ) => void | Promise<void>
   // onCreate?: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => void
   onUpdate?: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => void
   onAwarenessUpdate?: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => void

package/src/server/types/index.ts

@@ -1,4 +1,5 @@
 import { WsServer, WsServerSocket } from '@cuboapp/ws'
+import { CuboCrdtListTotals, CuboCrdtMutation } from '../../types'
 import { CuboCrdtServerDocument } from '../document'
 import { CuboCrdtServerDocumentOrigin } from './document'
 import { CuboCrdtServerSubscribe } from './subscribe'
@@ -6,6 +7,11 @@ import { CuboCrdtServerSubscribe } from './subscribe'
 export * from './document'
 export * from './subscribe'
 
+export type CuboCrdtServerFetchResult<T> = {
+  rows: T[]
+  totals?: CuboCrdtListTotals
+}
+
 export type CuboCrdtServerOptions<M, A, E extends Extract<keyof M, string>> = {
   ws: WsServer
   entities: E[]
@@ -19,8 +25,19 @@ export type CuboCrdtServerOptions<M, A, E extends Extract<keyof M, string>> = {
     maxSize?: number
     debounce?: number
   }
-  fetchRows?: (client: WsServerSocket, subscribe: CuboCrdtServerSubscribe) => Promise<M[E][]>
+  pagination?: {
+    debounce?: number
+  }
+  fetchRows?: (
+    client: WsServerSocket,
+    subscribe: CuboCrdtServerSubscribe
+  ) => Promise<M[E][] | CuboCrdtServerFetchResult<M[E]>>
   checkRowIsSutable?: (baseState: boolean, ctx: { entity: E; subscribe: CuboCrdtServerSubscribe; row: any }) => boolean
+  shouldRefreshSubscribe?: (ctx: {
+    entity: E
+    subscribe: CuboCrdtServerSubscribe
+    mutation: CuboCrdtMutation<M[E]>
+  }) => boolean
   storeRow?: <K extends E>(
     entity: K,
     entity_id: number,
@@ -29,6 +46,8 @@ export type CuboCrdtServerOptions<M, A, E extends Extract<keyof M, string>> = {
       document: CuboCrdtServerDocument
       client: CuboCrdtSocketClient<A>
       origin: CuboCrdtServerDocumentOrigin
+      previousRow: M[K]
+      row: M[K]
     }
   ) => Promise<void> | void
 }

package/src/server/types/subscribe.ts

@@ -1,3 +1,5 @@
+import type { CuboCrdtListTotals } from '../../types'
+
 export type CuboCrdtServerUnsubscribeDto = {
   subscribe_id: string
 }
@@ -7,10 +9,21 @@ export type CuboCrdtServerSubscribeDto = {
   filters: {
     [K in 'id' | string]: any
   }
-  awareness: boolean
+  awareness?: boolean
+  paginated?: boolean
 }
 
 export type CuboCrdtServerSubscribe = {
   id: string
   client_id: string
-} & Pick<CuboCrdtServerSubscribeDto, 'entity' | 'filters' | 'awareness'>
+  row_ids: number[]
+  totals: CuboCrdtListTotals
+  revision: number
+} & Pick<CuboCrdtServerSubscribeDto, 'entity' | 'filters' | 'awareness' | 'paginated'>
+
+export type CuboCrdtSubscribeRefreshState = {
+  dirty: boolean
+  forceSync: boolean
+  timer?: ReturnType<typeof setTimeout>
+  running?: Promise<void>
+}