@cuboapp/crdt 1.0.13 → 1.0.15

package/package.json

@@ -1,30 +1,35 @@
 {
   "name": "@cuboapp/crdt",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "CRDT for CUBO",
   "main": "src/index.ts",
-  "repository": "git@github.com:cuboapp/crdt.git",
+  "repository": {
+    "type": "git",
+    "url": "git@cuboapp.gitlab.yandexcloud.net:cubo/crdt.git"
+  },
   "author": "CuboSoft",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "src"
+  ],
   "dependencies": {
-    "@cuboapp/types": "^2.0.13",
-    "@cuboapp/utils": "1.0.10",
-    "@cuboapp/ws": "1.0.7",
-    "ws": "^8.19.0",
+    "@cuboapp/types": "^2.0.14",
+    "@cuboapp/utils": "1.0.12",
+    "@cuboapp/ws": "1.0.9",
     "y-protocols": "^1.0.7",
-    "yjs": "^13.6.30"
+    "yjs": "^13.6.31"
   },
   "peerDependencies": {
-    "vue": "^3.5.30",
-    "vue-router": "^5.0.2"
+    "vue": "^3.5.38",
+    "vue-router": "^5.1.0"
   },
   "devDependencies": {
-    "@types/node": "^24.10.1",
+    "@types/node": "^26.0.0",
     "@types/ws": "^8.18.1",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   }
 }

package/src/client/index.ts

@@ -1,4 +1,5 @@
 import { keyBy, pick, uuid } from '@cuboapp/utils'
+import { WsClientEvent } from '@cuboapp/ws'
 import { computed, reactive } from 'vue'
 import { applyAwarenessUpdate, Awareness, encodeAwarenessUpdate, removeAwarenessStates } from 'y-protocols/awareness'
 import { applyUpdate, Doc } from 'yjs'
@@ -25,6 +26,12 @@ export class CuboCrdtClient<M> {
   public store: CuboCrdtClientStore<M> = {}
 
   private listeners: Map<string, Map<string, (ctx: CuboCrdtClientSubscribeEvent) => void | Promise<void>>> = new Map()
+
+  // реестр активных подписок — нужен, чтобы переподписаться после реконнекта
+  private subscriptions = new Map<string, { entity: string; filters?: Record<string, any>; awareness?: boolean }>()
+  private connectedOnce = false
+  private onReconnect = () => this.resubscribeAll()
+
   private eventQueue = new AsyncSerialQueue({
     errorMode: 'continue',
     onError: (e) => console.error('[CRDT] inbound queue task failed', e),
@@ -36,6 +43,13 @@ export class CuboCrdtClient<M> {
   }
 
   async start() {
+    // если сокет уже подключён к моменту старта — считаем текущий коннект «первым»,
+    // чтобы первое же событие CONNECTED (после обрыва) сработало как переподписка
+    this.connectedOnce = this.ws.connected
+
+    // переподписываемся на все документы при (ре)коннекте сокета
+    this.ws.ee.on(WsClientEvent.CONNECTED, this.onReconnect)
+
     this.ws.registerHandler(CUBO_CRDT_EVENT.EVENT, ({ message }) => {
       this.eventQueue
         .enqueue(async () => {
@@ -68,9 +82,45 @@ export class CuboCrdtClient<M> {
   }
 
   async stop() {
+    this.ws.ee.off(WsClientEvent.CONNECTED, this.onReconnect)
+
     this.ws.deleteHandler(CUBO_CRDT_EVENT.EVENT)
 
     this.listeners.clear()
+    this.subscriptions.clear()
+    this.connectedOnce = false
+  }
+
+  /**
+   * Переподписка на все активные подписки после реконнекта.
+   *
+   * При обрыве сокета бэкенд удаляет клиента вместе со всеми его подписками
+   * (removeClient -> cleanSubscribe), а после реконнекта сокету выдаётся новый id.
+   * Локальные слушатели (this.listeners) и yjs-документы при этом сохраняются,
+   * поэтому достаточно заново отправить SUBSCRIBE по реестру — заново
+   * навешивать слушатели не нужно.
+   */
+  private resubscribeAll() {
+    // первый коннект — useList() уже сам отправил SUBSCRIBE, дублировать не нужно
+    if (!this.connectedOnce) {
+      this.connectedOnce = true
+      return
+    }
+
+    if (this.debug) {
+      console.log('[CRDT] reconnected, resubscribing', { count: this.subscriptions.size })
+    }
+
+    for (const [subscribe_id, sub] of this.subscriptions) {
+      try {
+        this.ws.request({
+          method: CUBO_CRDT_EVENT.SUBSCRIBE,
+          data: { subscribe_id, entity: sub.entity, filters: sub.filters, awareness: sub.awareness }
+        })
+      } catch (e) {
+        console.error('[CRDT] resubscribe failed', subscribe_id, e)
+      }
+    }
   }
 
   public useComputedList<K extends Extract<keyof M, string>>(entity: K) {
@@ -138,8 +188,17 @@ export class CuboCrdtClient<M> {
         })
       })
 
-      // подписываемся на бэке
-      this.ws.request({ method: CUBO_CRDT_EVENT.SUBSCRIBE, data: { subscribe_id, entity, filters, awareness: opts?.awareness } })
+      // регистрируем подписку, чтобы переподписаться после реконнекта
+      this.subscriptions.set(subscribe_id, { entity: `${entity}`, filters, awareness: opts?.awareness })
+
+      // подписываемся на бэке (если сокет ещё не подключён — переподпишемся по событию CONNECTED)
+      try {
+        this.ws.request({ method: CUBO_CRDT_EVENT.SUBSCRIBE, data: { subscribe_id, entity, filters, awareness: opts?.awareness } })
+      } catch (e) {
+        if (this.debug) {
+          console.warn('[CRDT] subscribe deferred until reconnect', subscribe_id, e)
+        }
+      }
     }
 
     // отписка
@@ -148,8 +207,17 @@ export class CuboCrdtClient<M> {
         console.log('[CRDT] unsubscribe', { entity, opts, filters })
       }
 
+      // снимаем подписку из реестра переподписки
+      this.subscriptions.delete(subscribe_id)
+
       // отписываемся на бэке
-      this.ws.request({ method: CUBO_CRDT_EVENT.UNSUBSCRIBE, data: { subscribe_id } })
+      try {
+        this.ws.request({ method: CUBO_CRDT_EVENT.UNSUBSCRIBE, data: { subscribe_id } })
+      } catch (e) {
+        if (this.debug) {
+          console.warn('[CRDT] unsubscribe request failed (socket down)', subscribe_id, e)
+        }
+      }
 
       // отписываемся на фронте
       this.listeners.get(entity)?.delete(subscribe_id)
@@ -281,17 +349,48 @@ export class CuboCrdtClient<M> {
   }
 
   public upgrade(subscribe_id: string, filters?: Record<string, any>) {
+    // держим реестр в актуальном состоянии, чтобы переподписка после реконнекта
+    // использовала уже обновлённые фильтры
+    const sub = this.subscriptions.get(subscribe_id)
+    if (sub) {
+      sub.filters = filters
+    }
+
     this.ws.request({ method: CUBO_CRDT_EVENT.UPGRADE, data: { subscribe_id, filters } })
   }
 
-  private async onDocumentCreate(ctx: CuboCrdtClientSubscribeEvent, opts: CuboCrdtClientDocUpdateOptions) {
-    let doc = this.store[opts.storeKey]?.docs.get(ctx.entity_id)
-    if (doc) {
-      console.warn('[CRDT] onDocumentCreate: doc already exists', { ctx, opts })
+  // апсертит строку в реактивное хранилище из текущего состояния yjs-документа
+  private applyRowJson(storeKey: string, entity_id: number, doc: Doc) {
+    const json: any = doc.getMap().toJSON()
+    const rows = this.store[storeKey]?.state.rows
+    if (!rows) {
       return
+    }
+
+    const index = rows.findIndex((r: any) => r.id === entity_id)
+    if (index >= 0) {
+      rows[index] = json
     } else {
-      doc = new Doc()
+      rows.push(json)
     }
+  }
+
+  private async onDocumentCreate(ctx: CuboCrdtClientSubscribeEvent, opts: CuboCrdtClientDocUpdateOptions) {
+    const existing = this.store[opts.storeKey]?.docs.get(ctx.entity_id)
+    if (existing) {
+      // документ уже есть локально (типичный кейс — повторный SUBSCRIBE после реконнекта).
+      // вместо игнорирования вмёрживаем входящее состояние в существующий yjs-документ
+      // (CRDT-merge), сохраняя локальные слушатели и awareness.
+      if (this.debug) {
+        console.log('[CRDT] onDocumentCreate: doc already exists, merging state', { ctx, opts })
+      }
+
+      applyUpdate(existing, new Uint8Array(ctx.data as any), { react: false })
+      this.applyRowJson(opts.storeKey, ctx.entity_id, existing)
+      return
+    }
+
+    const doc = new Doc()
 
     const update = new Uint8Array(ctx.data as any)
 
@@ -314,6 +413,10 @@ export class CuboCrdtClient<M> {
           entity_id: ctx.entity_id,
           data: Array.from(update),
           origin: {
+            // по умолчанию 'other' — исходную подписку исключаем (её yjs-документ уже
+            // применил изменение локально). Без этого апдейты от TipTap/y-prosemirror
+            // приходят без expose и сервер эхом шлёт их обратно самому автору.
+            expose: 'other',
             ...pick(origin || {}, ['store', 'keys', 'expose']),
             subscribe_id: opts?.subscribe_id
           }
@@ -369,7 +472,8 @@ export class CuboCrdtClient<M> {
               entity: ctx.entity,
               entity_id: ctx.entity_id,
               data: Array.from(update),
-              origin: { subscribe_id: opts.subscribe_id }
+              // 'other' — не шлём свой же курсор обратно исходной подписке
+              origin: { expose: 'other', subscribe_id: opts.subscribe_id }
             }
           })
         })
@@ -399,17 +503,7 @@ export class CuboCrdtClient<M> {
     applyUpdate(doc, update, { react: false })
 
     // обновляем документ в реактивном хранилище
-    const json: any = doc.getMap().toJSON()
-    const index = this.store[opts.storeKey]?.state.rows.findIndex((r: any) => r.id === ctx.entity_id)
-    if (index !== undefined && index >= 0) {
-      this.store[opts.storeKey]!.state.rows[index] = json
-    } else {
-      if (this.debug) {
-        console.warn('[CRDT] onDocumentUpdate - row not exists: "' + ctx.entity_id + '"', { ctx, opts })
-      }
-
-      this.store[opts.storeKey]!.state.rows.push(json)
-    }
+    this.applyRowJson(opts.storeKey, ctx.entity_id, doc)
 
     if (opts?.onAfterUpdate) {
       await opts.onAfterUpdate(doc, update, ctx, opts)

package/src/server/document/index.ts

@@ -60,7 +60,7 @@ export class CuboCrdtServerDocument {
         const row = this.getJson()
         const body = pick(row, origin.keys ?? Object.keys(row))
 
-        if (Object.keys(body)) {
+        if (Object.keys(body).length) {
           this.debounceStore(body, origin)
         }
       }
@@ -94,8 +94,18 @@ export class CuboCrdtServerDocument {
   async write(dto: object, origin?: CuboCrdtServerDocumentOrigin) {
     const map = this.getMap()
 
+    // Пропускаем скалярные ключи с тем же значением: Y.Map.set всегда создаёт новый Item и
+    // тумбстонит старый (безостановочный рост документа + лишний update-эвент), даже если
+    // значение не изменилось. Сравнение по ссылке — дёшево и не трогает объекты (для них
+    // set выполняется как и раньше, без лишней сериализации на горячем пути).
+    const entries = Object.entries(dto).filter(([key, value]) => map.get(key) !== value)
+
+    if (!entries.length) {
+      return
+    }
+
     this.ydoc.transact(() => {
-      Object.entries(dto).forEach(([key, value]) => {
+      entries.forEach(([key, value]) => {
         map.set(key, value)
       })
     }, origin)

package/src/server/index.ts

@@ -36,6 +36,9 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
   private documents = new Map<string, CuboCrdtServerDocument>()
   private subscribesByDocument = new Map<string, Set<string>>()
+  // обратный индекс: подписка -> имена документов, к которым она привязана.
+  // Нужен, чтобы отписка/очистка не сканировала ВСЕ документы сервера (O(subs x docs)).
+  private documentsBySubscribe = new Map<string, Set<string>>()
 
   public async init() {
     this.entities.forEach((e) => this.subscribesByEntity.set(e, new Set()))
@@ -163,12 +166,17 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
   }
 
   public removeClient(client: WsServerSocket) {
-    // удаляем все подписки по клиенту
-    this.subscribesByClient.get(client.id)?.forEach((subscribe_id) => this.cleanSubscribe(subscribe_id))
+    // удаляем все подписки по клиенту (но только те, что всё ещё принадлежат ЭТОМУ сокету —
+    // подписка могла быть переподвязана к новому сокету при reconnect с тем же subscribe_id)
+    this.subscribesByClient.get(client.id)?.forEach((subscribe_id) => this.cleanSubscribe(subscribe_id, client.id))
 
     // удаляем мапу подписок по клиенту
     this.subscribesByClient.delete(client.id)
 
+    // снимаем запланированный флаш очереди (чтобы не слать в закрытый сокет)
+    clearTimeout(this.sendTimeouts.get(client.id))
+    this.sendTimeouts.delete(client.id)
+
     // удаляем очередь под клиента
     this.queue.delete(client.id)
 
@@ -176,25 +184,35 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     this.clients.delete(client.id)
   }
 
+  private get batchMaxSize() {
+    return this.options.batch?.maxSize ?? 50
+  }
+
+  private get batchDebounce() {
+    return this.options.batch?.debounce ?? 100
+  }
+
   private sendQueueToClient(client: CuboCrdtSocketClient<A>) {
+    // снимаем запланированный флаш — мы отправляем прямо сейчас
+    clearTimeout(this.sendTimeouts.get(client.id))
+    this.sendTimeouts.delete(client.id)
+
     const queue = this.queue.get(client.id)
-    if (!queue) {
+    if (!queue || queue.size === 0) {
       return
     }
 
-    // const data = Array.from(queue)
-    const data = [...new Map((Array.from(queue) || []).map((item) => [JSON.stringify(item), item])).values()]
+    // Дедупликация побайтово идентичных событий внутри батча + сборка кадра за ОДИН проход
+    // сериализации: сериализуем каждый элемент один раз (он же служит ключом дедупа) и
+    // склеиваем готовые JSON-строки, а не сериализуем весь массив повторно.
+    const items = new Set<string>()
+    for (const item of queue) {
+      items.add(JSON.stringify(item))
+    }
 
     queue.clear()
 
-    client.send(
-      JSON.stringify({
-        method: CUBO_CRDT_EVENT.EVENT,
-        data
-      })
-    )
-
-    queue.clear()
+    client.send(`{"method":${JSON.stringify(CUBO_CRDT_EVENT.EVENT)},"data":[${Array.from(items).join(',')}]}`)
   }
 
   public sendToClient(client_id: string, data: any) {
@@ -203,25 +221,53 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       return
     }
 
-    // сбрасываем таймаут если он есть
-    clearTimeout(this.sendTimeouts.get(client_id))
+    const queue = this.queue.get(client_id)
+    if (!queue) {
+      return
+    }
 
     // добавляем в очередь
-    this.queue.get(client_id).add(data)
+    queue.add(data)
 
-    // если очередь >10 то сразу отправляем
-    if (this.queue.size > 10) {
+    // если у ЭТОГО клиента в очереди накопилось много событий — отправляем сразу
+    if (queue.size >= this.batchMaxSize) {
       this.sendQueueToClient(client)
+      return
     }
-    // если нет - ставим таймаут
-    else {
+
+    // иначе — дебаунсим отправку, но НЕ сбрасываем уже запланированный флаш,
+    // иначе при непрерывном потоке апдейтов очередь никогда не отправится
+    if (!this.sendTimeouts.has(client_id)) {
       this.sendTimeouts.set(
         client_id,
-        setTimeout(() => this.sendQueueToClient(client), 100)
+        setTimeout(() => this.sendQueueToClient(client), this.batchDebounce)
       )
     }
   }
 
+  // привязываем подписку к документу (в обоих индексах)
+  private linkSubscribeToDocument(subscribe_id: string, docName: string) {
+    let byDoc = this.subscribesByDocument.get(docName)
+    if (!byDoc) {
+      byDoc = new Set()
+      this.subscribesByDocument.set(docName, byDoc)
+    }
+    byDoc.add(subscribe_id)
+
+    let bySub = this.documentsBySubscribe.get(subscribe_id)
+    if (!bySub) {
+      bySub = new Set()
+      this.documentsBySubscribe.set(subscribe_id, bySub)
+    }
+    bySub.add(docName)
+  }
+
+  // отвязываем подписку от документа (в обоих индексах)
+  private unlinkSubscribeFromDocument(subscribe_id: string, docName: string) {
+    this.subscribesByDocument.get(docName)?.delete(subscribe_id)
+    this.documentsBySubscribe.get(subscribe_id)?.delete(docName)
+  }
+
   // если у документа нет подписок - сносим его
   private checkDocumentNeedRemove(name: string) {
     if (!this.subscribesByDocument.get(name)?.size) {
@@ -231,55 +277,62 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
       this.documents.get(name)?.destroy()
       this.documents.delete(name)
+      // не оставляем пустой Set в индексе (иначе — медленная утечка записей мапы);
+      // getOrCreateDocument пересоздаст его при повторном появлении документа
+      this.subscribesByDocument.delete(name)
     }
   }
 
-  // очистка подписки (при отписке клиента - через emit-метод или options-хук)
-  private cleanSubscribe(subscribe_id: string) {
+  // очистка подписки (при отписке клиента - через emit-метод или options-хук).
+  // ownerClientId (опционально): при отключении сокета передаётся id этого сокета —
+  // если подписка уже переподвязана к НОВОМУ клиенту (reconnect с тем же subscribe_id),
+  // старый close-хендлер не должен её сносить.
+  private cleanSubscribe(subscribe_id: string, ownerClientId?: string) {
     const subscribe = this.subscribes.get(subscribe_id)
-    if (subscribe) {
+    if (!subscribe) {
+      return
+    }
+
+    // подписка была переподвязана к другому (более новому) клиенту — не трогаем
+    if (ownerClientId !== undefined && subscribe.client_id !== ownerClientId) {
       if (this.debug) {
-        console.log('[CRDT] unsubscribe', subscribe.entity, subscribe.filters)
+        console.log('[CRDT] cleanSubscribe skipped (rebound to newer client)', subscribe_id)
       }
+      return
+    }
 
-      if (subscribe.awareness) {
-        //убираем аварнесс стейт при отписке
-        this.subscribesByDocument.forEach((subs, docName) => {
-          if (!subs.has(subscribe_id)) {
-            return
-          }
+    if (this.debug) {
+      console.log('[CRDT] unsubscribe', subscribe.entity, subscribe.filters)
+    }
 
-          const doc = this.documents.get(docName)
-          if (!doc?.awareness) {
-            return
-          }
+    // документы этой подписки берём из обратного индекса, а не сканируем все
+    const docNames = this.documentsBySubscribe.get(subscribe_id)
 
-          const ids = Array.from(doc.awarenessBySubscribe.get(subscribe_id) || [])
-          if (!ids.length) {
-            return
+    if (docNames) {
+      for (const docName of docNames) {
+        if (subscribe.awareness) {
+          //убираем аварнесс стейт при отписке
+          const doc = this.documents.get(docName)
+          const ids = doc?.awareness ? Array.from(doc.awarenessBySubscribe.get(subscribe_id) || []) : []
+          if (doc?.awareness && ids.length) {
+            removeAwarenessStates(doc.awareness, ids, { subscribe_id, expose: 'all' })
+            doc.awarenessBySubscribe.delete(subscribe_id)
           }
+        }
 
-          removeAwarenessStates(doc.awareness, ids, { subscribe_id, expose: 'all' })
-
-          doc.awarenessBySubscribe.delete(subscribe_id)
-        })
+        // отписываем документ от подписки (только по одной стороне индекса — другую чистим ниже)
+        this.subscribesByDocument.get(docName)?.delete(subscribe_id)
+        this.checkDocumentNeedRemove(docName)
       }
+    }
 
-      // удаляем подписку по сущности
-      this.subscribesByEntity.get(subscribe.entity as E)?.delete(subscribe.id)
-
-      // отписываем все документы от подписки
-      this.subscribesByDocument.forEach((subscribes, docName) => {
-        subscribes.delete(subscribe_id)
-
-        this.checkDocumentNeedRemove(docName)
-      })
+    // удаляем обратный индекс
+    this.documentsBySubscribe.delete(subscribe_id)
 
-      // удаляем подписки
-      this.subscribes.delete(subscribe_id)
-      this.subscribesByClient.get(subscribe.client_id)?.delete(subscribe_id)
-      this.subscribesByEntity.get(subscribe.entity as E)?.delete(subscribe_id)
-    }
+    // удаляем подписки
+    this.subscribes.delete(subscribe_id)
+    this.subscribesByClient.get(subscribe.client_id)?.delete(subscribe_id)
+    this.subscribesByEntity.get(subscribe.entity as E)?.delete(subscribe_id)
   }
 
   public getDocument(entity: string, entity_id: number) {
@@ -287,74 +340,112 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
   }
 
   public getSutableSubscribes(entity: string, row: any) {
-    return Array.from(this.subscribesByEntity.get(entity as E) || [])
-      .filter((m) => {
-        const subscribe = this.subscribes.get(m[1])
+    return Array.from(this.subscribesByEntity.get(entity as E) || []).filter((subscribe_id) => {
+      const subscribe = this.subscribes.get(subscribe_id)
+      if (!subscribe) {
+        return false
+      }
 
-        let state = subscribe && checkRowIsSutable(row, subscribe)
-        if (this.options.checkRowIsSutable) {
-          state = this.options.checkRowIsSutable(state, { entity: entity as any, subscribe, row })
-        }
+      let state = checkRowIsSutable(row, subscribe.filters || {})
+      if (this.options.checkRowIsSutable) {
+        state = this.options.checkRowIsSutable(state, { entity: entity as any, subscribe, row })
+      }
 
-        return state
-      })
-      .map((m) => m[1])
+      return state
+    })
   }
 
-  public ensureDocument(entity: E, row: any, awareness?: boolean) {
-    // todo: врапнуть всё это в Promise
+  // создаёт (или возвращает существующий) серверный документ БЕЗ рассылки подписчикам.
+  // Используется как для рассылочного пути (ensureDocument), так и для точечной
+  // доставки на init подписки (pushSubscribeDocuments).
+  private getOrCreateDocument(entity: E, row: any, awareness?: boolean): CuboCrdtServerDocument {
     const entity_id = row.id
     const documentName = `${entity}:${entity_id}`
 
-    // проверяем документ
     let document = this.documents.get(documentName)
-    if (!document) {
-      document = new CuboCrdtServerDocument({
-        name: documentName,
-        initialState: row,
-        awareness: awareness,
-        onUpdate: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => {
-          // пушим обновление документа
-          // console.log('push document update', document.name)
-
-          this.pushDocumentAction('update', entity, document!, data, origin)
-        },
-        onAwarenessUpdate: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => {
-          // пушим обновление документа
-          // console.log('push document update', document.name)
-
-          this.pushDocumentAction('awareness', entity, document!, data, origin)
-        },
-        onStore: (item: object, origin: CuboCrdtServerDocumentOrigin) => {
-          const subscribe = origin.subscribe_id && this.subscribes.get(origin.subscribe_id)
-          const client = subscribe && this.clients.get(subscribe.client_id)
+    if (document) {
+      return document
+    }
 
-          if (client) {
-            return this.options?.storeRow?.(entity as any, entity_id, item as any, { document, client, origin })
-          }
+    document = new CuboCrdtServerDocument({
+      name: documentName,
+      initialState: row,
+      awareness: awareness,
+      onUpdate: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => {
+        this.pushDocumentAction('update', entity, document!, data, origin)
+      },
+      onAwarenessUpdate: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => {
+        this.pushDocumentAction('awareness', entity, document!, data, origin)
+      },
+      onStore: (item: object, origin: CuboCrdtServerDocumentOrigin) => {
+        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 })
         }
-      })
-
-      // создаём документ
-      this.documents.set(documentName, document)
+      }
+    })
 
-      // создаём пул подписок по документу
+    this.documents.set(documentName, document)
+    if (!this.subscribesByDocument.has(documentName)) {
       this.subscribesByDocument.set(documentName, new Set())
+    }
 
-      // пушим создание документа
-      this.pushDocumentAction('create', entity, document, document.stateAsUpdate)
+    return document
+  }
 
-      // console.log('create document', documentName)
-    } else {
-      // console.log('update document', documentName)
+  // Рассылочный путь (хук onAfterCreate/onAfterUpdate из бэка): создаёт документ и
+  // раскатывает 'create'/'upsert' по ВСЕМ подходящим подпискам сущности.
+  public ensureDocument(entity: E, row: any, awareness?: boolean) {
+    if (row?.id == null) {
+      if (this.debug) {
+        console.warn('[CRDT] ensureDocument: row without id', entity, row)
+      }
+      return
+    }
+
+    const documentName = `${entity}:${row.id}`
+    const existed = this.documents.has(documentName)
+    const document = this.getOrCreateDocument(entity, row, awareness)
 
-      // пушим обновление документа
+    if (!existed) {
+      this.pushDocumentAction('create', entity, document, document.stateAsUpdate)
+    } else {
       this.pushDocumentAction('upsert', entity, document, document.stateAsUpdate)
     }
 
     return document
   }
 
+  // Точечная доставка документа ТОЛЬКО инициирующей подписке (init/upgrade/resubscribe).
+  // Раньше это шло через ensureDocument -> pushDocumentAction('upsert') с полным сканом
+  // всех подписок сущности — на каждый ряд из fetchRows. Теперь — один send на подписку.
+  private sendDocumentToSubscribe(subscribe: CuboCrdtServerSubscribe, document: CuboCrdtServerDocument, entity_id: number) {
+    this.linkSubscribeToDocument(subscribe.id, document.name)
+
+    this.sendToClient(subscribe.client_id, {
+      action: 'create',
+      entity: subscribe.entity,
+      entity_id,
+      data: Array.from(document.stateAsUpdate),
+      subscribe_id: subscribe.id
+    })
+
+    if (subscribe.awareness && document.awareness) {
+      const ids = Array.from(document.awareness.getStates().keys())
+      if (ids.length) {
+        this.sendToClient(subscribe.client_id, {
+          action: 'awareness',
+          entity: subscribe.entity,
+          entity_id,
+          data: Array.from(encodeAwarenessUpdate(document.awareness, ids)),
+          subscribe_id: subscribe.id
+        })
+      }
+    }
+  }
+
   public deleteDocument(entity: E, row: any, origin?: CuboCrdtClientDocOrigin) {
     if (this.debug) {
       console.log('[CRDT] delete document', entity, row.id, origin)
@@ -367,6 +458,15 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       // сначала пушим удаление документа
       this.pushDocumentAction('delete', entity, document, null, origin)
 
+      // чистим обратный индекс: убираем документ из documentsBySubscribe у всех его подписок
+      const subs = this.subscribesByDocument.get(documentName)
+      if (subs) {
+        for (const subscribe_id of subs) {
+          this.documentsBySubscribe.get(subscribe_id)?.delete(documentName)
+        }
+      }
+      this.subscribesByDocument.delete(documentName)
+
       // удаляем документ
       this.documents.delete(documentName)
 
@@ -382,11 +482,19 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
   private onDocumentExternalUpdate(update: Uint8Array, action: CuboCrdtServerDocumentIncomingAction) {
     let document = this.getDocument(action.entity, action.entity_id)
     if (!document) {
+      // документ мог быть вытеснен (эвикция при отключении всех подписчиков), пока
+      // клиент ещё шлёт апдейты. Пересоздаём под ПРАВИЛЬНЫМ ключом ({ id }, а не число),
+      // без рассылки пустого 'create'. Раньше сюда передавался entity_id как row ->
+      // row.id === undefined -> общий документ-призрак `entity:undefined`.
+      if (action.entity_id == null) {
+        return
+      }
+
       if (this.debug) {
         console.warn('[CRDT] onDocumentExternalUpdate - document not found, creating:', action.entity, action.entity_id)
       }
 
-      document = this.ensureDocument(action.entity as E, action.entity_id, true)
+      document = this.getOrCreateDocument(action.entity as E, { id: action.entity_id }, true)
     }
 
     document.applyUpdate(new Uint8Array(update), action.origin)
@@ -445,9 +553,18 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     const row = document.getJson()
 
     // берём все подписки по сущности
-    const sutableSubscribes = Array.from(this.subscribesByEntity.get(entity))
+    const sutableSubscribes = Array.from(this.subscribesByEntity.get(entity) || [])
       .map((subscribe_id) => {
         const subscribe = this.subscribes.get(subscribe_id)
+        if (!subscribe) {
+          return null
+        }
+
+        // аварнесс-события (курсоры/выделения) раскатываем ТОЛЬКО подпискам с awareness,
+        // а не всем спискам сущности, которым awareness не нужен
+        if (action === 'awareness' && !subscribe.awareness) {
+          return null
+        }
 
         const subscribeSutable = this.checkSubscribeIsSutable(origin, subscribe)
         const documentExistsInSubscribe = this.subscribesByDocument.get(document.name)?.has(subscribe.id)
@@ -514,8 +631,6 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       .filter((i) => !!i) as { subscribe: CuboCrdtServerSubscribe; action: CuboCrdtAction; data: undefined | number[] }[]
 
     if (sutableSubscribes.length) {
-      const documentSubscribes = this.subscribesByDocument.get(document.name)
-
       sutableSubscribes.forEach(({ subscribe, action, data }) => {
         this.sendToClient(subscribe.client_id, {
           action,
@@ -529,10 +644,10 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
           case 'create':
           case 'upsert':
           case 'update':
-            documentSubscribes.add(subscribe.id)
+            this.linkSubscribeToDocument(subscribe.id, document.name)
             break
           case 'delete':
-            documentSubscribes.delete(subscribe.id)
+            this.unlinkSubscribeFromDocument(subscribe.id, document.name)
             this.checkDocumentNeedRemove(document.name)
             break
         }
@@ -557,13 +672,21 @@ 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)
 
-    // пушим их в сокеты
+    // Доставляем документы ТОЧЕЧНО инициирующей подписке. Раньше это шло через
+    // ensureDocument -> pushDocumentAction('upsert') с полным сканом всех подписок сущности
+    // НА КАЖДУЮ строку из fetchRows (до 10k) — главный усилитель нагрузки при (ре)подписке.
+    // Строки уже отфильтрованы под фильтры подписки в fetchRows, поэтому повторная
+    // проверка/рассылка остальным не нужна: живые create/update придут через onAfterCreate.
     for (const row of rows || []) {
-      // this.ensureDocument(subscribe.entity as E, row, { subscribes_ids: [subscribe.id] })
-      this.ensureDocument(subscribe.entity as E, row, subscribe.awareness)
+      if ((row as any)?.id == null) {
+        continue
+      }
+
+      const document = this.getOrCreateDocument(subscribe.entity as E, row, subscribe.awareness)
+      this.sendDocumentToSubscribe(subscribe, document, (row as any).id)
     }
   }
 

package/src/server/types/index.ts

@@ -10,6 +10,15 @@ export type CuboCrdtServerOptions<M, A, E extends Extract<keyof M, string>> = {
   ws: WsServer
   entities: E[]
   debug?: boolean
+  /**
+   * Параметры батчинга исходящих событий (защита от перегрузки бэка).
+   * - maxSize: при достижении такого размера очереди клиента батч отправляется сразу
+   * - debounce: задержка перед отправкой неполного батча (мс)
+   */
+  batch?: {
+    maxSize?: number
+    debounce?: number
+  }
   fetchRows?: (client: WsServerSocket, subscribe: CuboCrdtServerSubscribe) => Promise<M[E][]>
   checkRowIsSutable?: (baseState: boolean, ctx: { entity: E; subscribe: CuboCrdtServerSubscribe; row: any }) => boolean
   storeRow?: <K extends E>(

package/.prettierrc

@@ -1,8 +0,0 @@
-{
-  "trailingComma": "none",
-  "tabWidth": 2,
-  "semi": false,
-  "singleQuote": true,
-  "eslintIntegration": true,
-  "printWidth": 140
-}

package/tsconfig.build.json

@@ -1,4 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
-}

package/tsconfig.json

@@ -1,22 +0,0 @@
-{
-  "compilerOptions": {
-    "module": "commonjs",
-    "declaration": true,
-    "removeComments": true,
-    "emitDecoratorMetadata": true,
-    "experimentalDecorators": true,
-    "allowSyntheticDefaultImports": true,
-    "target": "ES2021",
-    "sourceMap": true,
-    "outDir": "./dist",
-    "strict": false,
-    "rootDir": "./",
-    "incremental": true,
-    "skipLibCheck": true,
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}