@cuboapp/crdt 1.0.20 → 1.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuboapp/crdt",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "CRDT for CUBO",
   "main": "src/index.ts",
   "repository": {

package/src/client/index.ts

@@ -1,6 +1,6 @@
 import { keyBy, pick, uuid } from '@cuboapp/utils'
 import { WsClientEvent } from '@cuboapp/ws'
-import { computed, reactive } from 'vue'
+import { computed, reactive, shallowReactive } from 'vue'
 import { applyAwarenessUpdate, Awareness, encodeAwarenessUpdate, removeAwarenessStates } from 'y-protocols/awareness'
 import { applyUpdate, Doc } from 'yjs'
 
@@ -234,8 +234,8 @@ export class CuboCrdtClient<M> {
 
       this.store[storeKey] = {
         state,
-        docs: new Map(),
-        awarenesses: new Map()
+        docs: shallowReactive(new Map()),
+        awarenesses: shallowReactive(new Map())
       }
     }
 
@@ -450,47 +450,51 @@ export class CuboCrdtClient<M> {
     dto: K extends Extract<keyof M, string> ? Partial<M[K]> : object,
     opts?: CuboCrdtClientDocOrigin
   ) {
-    const cardRow = this.store[`${entity}:${entity_id}`]?.state.rows?.[0]
-    const listRow = this.store[entity]?.state?.rows.find((r: any) => r.id === entity_id)
-    const cardDoc = this.store[`${entity}:${entity_id}`]?.docs.get(entity_id)
-    const listDoc = this.store[entity]?.docs.get(entity_id)
-
-    // обновляем документы
-    for (const doc of [cardDoc, listDoc]) {
-      if (doc) {
-        const map = doc.getMap()
-
-        const row = (cardRow || listRow) as any
-        const toUpdate = Object.fromEntries(Object.entries(dto).filter(([key, value]) => row[key] !== value))
-
-        if (Object.keys(toUpdate).length) {
-          const origin: CuboCrdtClientDocOrigin = {
-            store: opts?.store ?? true,
-            expose: opts?.expose ?? 'other',
-            keys: opts?.keys ?? Object.keys(toUpdate),
-            react: true // отправляем на бэк
-          }
+    const entityStores = [...new Set(
+      [...this.subscriptions.values()]
+        .filter((subscription) => subscription.entity === entity)
+        .map((subscription) => this.store[subscription.storeKey])
+    )]
+    const fallbackStores = [this.store[entity], this.store[`${entity}:${entity_id}`]]
+    const store = [...entityStores, ...fallbackStores]
+      .find((candidate) => candidate?.docs.has(entity_id))
+    const document = store?.docs.get(entity_id)
+
+    if (!store || !document) {
+      return
+    }
 
-          doc.transact(() => {
-            Object.entries(toUpdate).forEach(([key, value]) => {
-              map.set(key, value)
-            })
-          }, origin)
-        }
-      }
+    const map = document.getMap()
+    const toUpdate = Object.fromEntries(
+      Object.entries(dto).filter(([key, value]) => map.get(key) !== value)
+    )
+
+    if (!Object.keys(toUpdate).length) {
+      return
     }
 
-    // обновляем реактивку
-    for (const row of [cardRow, listRow]) {
-      if (row) {
-        const toUpdate = Object.fromEntries(Object.entries(dto).filter(([key, value]) => row[key as keyof typeof row] !== value))
+    const origin: CuboCrdtClientDocOrigin = {
+      store: opts?.store ?? true,
+      expose: opts?.expose ?? 'other',
+      keys: opts?.keys ?? Object.keys(toUpdate),
+      react: true
+    }
 
-        if (Object.keys(toUpdate).length) {
-          Object.entries(toUpdate).forEach(([key, value]) => {
-            row[key as keyof typeof row] = value
-          })
-        }
-      }
+    // Одна сущность может присутствовать в нескольких подписках с разными
+    // storeKey. Мутацию отправляем только из одного документа: остальные
+    // подписки получат подтверждённый update через обычную CRDT-рассылку.
+    document.transact(() => {
+      Object.entries(toUpdate).forEach(([key, value]) => {
+        map.set(key, value)
+      })
+    }, origin)
+
+    const row = store.state.rows.find((item: any) => Number(item.id) === Number(entity_id))
+
+    if (row) {
+      Object.entries(toUpdate).forEach(([key, value]) => {
+        row[key] = value
+      })
     }
   }
 
@@ -551,6 +555,47 @@ export class CuboCrdtClient<M> {
     }
   }
 
+  private ensureDocumentAwareness(
+    ctx: CuboCrdtClientSubscribeEvent,
+    opts: CuboCrdtClientDocUpdateOptions,
+    doc: Doc,
+    entity_id: number
+  ) {
+    if (!opts.awareness) {
+      return
+    }
+
+    let awareness = this.store[opts.storeKey]?.awarenesses.get(entity_id)
+
+    if (awareness) {
+      return
+    }
+
+    awareness = new Awareness(doc)
+
+    awareness.on('update', ({ added, updated, removed }, origin) => {
+      if (origin === 'remote') {
+        return
+      }
+
+      const changed = added.concat(updated).concat(removed)
+      const update = encodeAwarenessUpdate(awareness!, changed)
+
+      this.ws.request({
+        method: CUBO_CRDT_EVENT.EVENT,
+        data: {
+          action: 'awareness',
+          entity: ctx.entity,
+          entity_id,
+          data: Array.from(update),
+          origin: { expose: 'other', subscribe_id: opts.subscribe_id }
+        }
+      })
+    })
+
+    this.store[opts.storeKey]?.awarenesses.set(entity_id, awareness)
+  }
+
   private async onDocumentCreate(ctx: CuboCrdtClientSubscribeEvent, opts: CuboCrdtClientDocUpdateOptions) {
     const entity_id = ctx.entity_id
     if (entity_id === undefined) {
@@ -568,6 +613,7 @@ export class CuboCrdtClient<M> {
 
       applyUpdate(existing, new Uint8Array(ctx.data as any), { react: false })
       this.applyRowJson(opts.storeKey, entity_id, existing)
+      this.ensureDocumentAwareness(ctx, opts, existing, entity_id)
       return
     }
 
@@ -630,38 +676,7 @@ export class CuboCrdtClient<M> {
       await opts.onAfterCreate(doc, update, ctx, opts)
     }
 
-    if (opts?.awareness) {
-      let awareness = this.store[opts.storeKey]?.awarenesses.get(entity_id)
-
-      if (!awareness) {
-        awareness = new Awareness(doc)
-
-        awareness.on('update', ({ added, updated, removed }, origin) => {
-          // console.log('[CRDT] awarness update', origin)
-
-          if (origin === 'remote') {
-            return
-          }
-
-          const changed = added.concat(updated).concat(removed)
-          const update = encodeAwarenessUpdate(awareness, changed)
-
-          this.ws.request({
-            method: CUBO_CRDT_EVENT.EVENT,
-            data: {
-              action: 'awareness',
-              entity: ctx.entity,
-              entity_id,
-              data: Array.from(update),
-              // 'other' — не шлём свой же курсор обратно исходной подписке
-              origin: { expose: 'other', subscribe_id: opts.subscribe_id }
-            }
-          })
-        })
-
-        this.store[opts.storeKey]?.awarenesses.set(entity_id, awareness)
-      }
-    }
+    this.ensureDocumentAwareness(ctx, opts, doc, entity_id)
   }
 
   private async onDocumentUpdate(ctx: CuboCrdtClientSubscribeEvent, opts: CuboCrdtClientDocUpdateOptions) {

package/src/server/document/index.ts

@@ -1,12 +1,23 @@
-import { cloneDeep, debounce, pick } from '@cuboapp/utils'
+import { cloneDeep, pick } from '@cuboapp/utils'
 import { applyUpdate, Doc, encodeStateAsUpdate } from 'yjs'
 import { Awareness, encodeAwarenessUpdate } from 'y-protocols/awareness'
 
-import { CuboCrdtServerDocumentOptions, CuboCrdtServerDocumentOrigin } from '../types'
+import {
+  CuboCrdtServerDocumentOptions,
+  CuboCrdtServerDocumentOrigin,
+  CuboCrdtServerDocumentPendingStore
+} from '../types'
+import { getCrdtStoreChangeKey } from '../utils'
+
+const STORE_DEBOUNCE_MS = 300
 
 export class CuboCrdtServerDocument {
   private ydoc: Doc
   private persistedState: object = {}
+  private observedState: object = {}
+  private storeQueue: Promise<void> = Promise.resolve()
+  private pendingStore?: CuboCrdtServerDocumentPendingStore
+  private storeTimeout?: ReturnType<typeof setTimeout>
   public awareness: Awareness
   public awarenessBySubscribe = new Map<string, Set<number>>()
 
@@ -19,31 +30,11 @@ export class CuboCrdtServerDocument {
     })
 
     if (opts.awareness) {
-      this.awareness = new Awareness(this.ydoc)
-      this.awareness.setLocalState(null)
-
-      this.awareness.on('update', ({ added, updated, removed }, origin: CuboCrdtServerDocumentOrigin) => {
-        const subId = origin?.subscribe_id
-
-        if (subId) {
-          let set = this.awarenessBySubscribe.get(subId)
-          if (!set) {
-            set = new Set()
-            this.awarenessBySubscribe.set(subId, set)
-          }
-
-          added.concat(updated).forEach((id) => set!.add(id))
-          removed.forEach((id) => set!.delete(id))
-        }
-
-        const changed = added.concat(updated).concat(removed)
-        const update = encodeAwarenessUpdate(this.awareness!, changed)
-
-        this.opts?.onAwarenessUpdate?.(update, origin)
-      })
+      this.enableAwareness()
     }
 
     this.persistedState = cloneDeep(opts.initialState ?? {})
+    this.observedState = cloneDeep(opts.initialState ?? {})
 
     // записываем исходное состояние
     this.write(opts.initialState ?? {})
@@ -58,7 +49,8 @@ export class CuboCrdtServerDocument {
       this.opts?.onUpdate?.(data, origin)
       // }
 
-      // если нужно сохранять стейт документа - вызываем store по дебаунсу
+      // Состояние отслеживается синхронно с Y.Doc. Для клиентских изменений
+      // debounceStore сам обновит observedState после вычисления leaf-diff.
       if (origin?.store) {
         const row = this.getJson()
         const body = pick(row, origin.keys ?? Object.keys(row))
@@ -68,10 +60,41 @@ export class CuboCrdtServerDocument {
             console.error('[CRDT] store document', this.name, error)
           })
         }
+      } else {
+        this.observedState = cloneDeep(this.getJson())
       }
     })
   }
 
+  public enableAwareness() {
+    if (this.awareness) {
+      return
+    }
+
+    this.awareness = new Awareness(this.ydoc)
+    this.awareness.setLocalState(null)
+
+    this.awareness.on('update', ({ added, updated, removed }, origin: CuboCrdtServerDocumentOrigin) => {
+      const subId = origin?.subscribe_id
+
+      if (subId) {
+        let set = this.awarenessBySubscribe.get(subId)
+        if (!set) {
+          set = new Set()
+          this.awarenessBySubscribe.set(subId, set)
+        }
+
+        added.concat(updated).forEach((id) => set!.add(id))
+        removed.forEach((id) => set!.delete(id))
+      }
+
+      const changed = added.concat(updated).concat(removed)
+      const update = encodeAwarenessUpdate(this.awareness!, changed)
+
+      this.opts?.onAwarenessUpdate?.(update, origin)
+    })
+  }
+
   public get name() {
     return this.opts.name
   }
@@ -129,17 +152,117 @@ export class CuboCrdtServerDocument {
   }
 
   destroy() {
+    this.flushPendingStore()
     this.awareness?.destroy()
     this.ydoc.destroy()
   }
 
-  public async store(body: object, origin: CuboCrdtServerDocumentOrigin) {
-    const previousRow = this.getPersistedState()
-    const row = this.getJson()
+  public store(body: object, origin: CuboCrdtServerDocumentOrigin, row = this.getJson()) {
+    const queuedBody = cloneDeep(body)
+    const queuedRow = cloneDeep(row)
+
+    // debounce ограничивает частоту вызовов, но не сериализует async store.
+    // Без очереди следующий PATCH мог завершиться раньше предыдущего и затем
+    // быть затёрт старым полным снимком составного поля (например case.extra).
+    const current = this.storeQueue
+      .catch(() => undefined)
+      .then(async () => {
+        const previousRow = this.getPersistedState()
+
+        await this.opts?.onStore?.(queuedBody, origin, {
+          previousRow,
+          row: queuedRow
+        })
+        this.setPersistedState(queuedRow)
+      })
+
+    this.storeQueue = current
+    return current
+  }
+
+  /**
+   * Схлопывает только соседние изменения одного origin и одного набора
+   * leaf-путей. Смена пользователя или поля немедленно фиксирует предыдущий
+   * пакет, сохраняя фактический порядок collaborative-обновлений.
+   */
+  public debounceStore(body: object, origin: CuboCrdtServerDocumentOrigin) {
+    const row = cloneDeep(this.getJson())
+    const bodyKeys = Object.keys(body)
+    const previousBody = pick(this.observedState, bodyKeys)
+    const changeKey = getCrdtStoreChangeKey(previousBody, body)
+    const originKey = `${origin.client_id || ''}:${origin.subscribe_id || ''}`
+
+    this.observedState = cloneDeep(row)
+
+    if (!changeKey) {
+      return Promise.resolve()
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      const sameBatch = this.pendingStore?.originKey === originKey &&
+        this.pendingStore.changeKey === changeKey
+
+      if (this.pendingStore && !sameBatch) {
+        this.flushPendingStore()
+      }
+
+      if (!this.pendingStore) {
+        this.pendingStore = {
+          body: cloneDeep(body),
+          changeKey,
+          origin: cloneDeep(origin),
+          originKey,
+          row,
+          waiters: []
+        }
+      } else {
+        const keys = new Set([
+          ...(this.pendingStore.origin.keys || []),
+          ...(origin.keys || [])
+        ])
+
+        this.pendingStore.body = {
+          ...this.pendingStore.body,
+          ...cloneDeep(body)
+        }
+        this.pendingStore.origin = {
+          ...cloneDeep(origin),
+          keys: [...keys]
+        }
+        this.pendingStore.row = row
+      }
 
-    await this.opts?.onStore?.(body, origin, { previousRow, row })
-    this.setPersistedState(row)
+      this.pendingStore.waiters.push({ resolve, reject })
+      this.schedulePendingStore()
+    })
   }
 
-  public debounceStore = debounce(this.store.bind(this), 300)
+  /** Перезапускает trailing debounce для текущего однородного пакета. */
+  private schedulePendingStore() {
+    if (this.storeTimeout) {
+      clearTimeout(this.storeTimeout)
+    }
+
+    this.storeTimeout = setTimeout(() => this.flushPendingStore(), STORE_DEBOUNCE_MS)
+  }
+
+  /** Передаёт накопленный пакет в общую последовательную очередь записи. */
+  private flushPendingStore() {
+    if (!this.pendingStore) {
+      return
+    }
+
+    if (this.storeTimeout) {
+      clearTimeout(this.storeTimeout)
+      this.storeTimeout = undefined
+    }
+
+    const pending = this.pendingStore
+    this.pendingStore = undefined
+
+    this.store(pending.body, pending.origin, pending.row).then(
+      () => pending.waiters.forEach(({ resolve }) => resolve()),
+      (error) => pending.waiters.forEach(({ reject }) => reject(error))
+    )
+  }
 }

package/src/server/index.ts

@@ -605,6 +605,10 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
     let document = this.documents.get(documentName)
     if (document) {
+      if (awareness) {
+        document.enableAwareness()
+      }
+
       // Освежаем существующий документ строкой из БД.
       //
       // Раньше документ возвращался как есть, а подписка отправляла клиенту его

package/src/server/types/document.ts

@@ -5,6 +5,20 @@ export type CuboCrdtServerDocumentStoreContext = {
   row: object
 }
 
+export type CuboCrdtServerDocumentStoreWaiter = {
+  resolve: () => void
+  reject: (reason?: unknown) => void
+}
+
+export type CuboCrdtServerDocumentPendingStore = {
+  body: object
+  changeKey: string
+  origin: CuboCrdtServerDocumentOrigin
+  originKey: string
+  row: object
+  waiters: CuboCrdtServerDocumentStoreWaiter[]
+}
+
 export type CuboCrdtServerDocumentOptions = {
   name: string
   onStore?: (

package/src/server/utils/index.ts

@@ -0,0 +1,41 @@
+const isObject = (value: unknown): value is Record<string, unknown> => {
+  return value !== null && typeof value === 'object'
+}
+
+const collectChangedPaths = (
+  previous: unknown,
+  current: unknown,
+  path: string,
+  result: string[]
+) => {
+  if (Object.is(previous, current)) {
+    return
+  }
+
+  if (!isObject(previous) || !isObject(current)) {
+    result.push(path || '$')
+    return
+  }
+
+  const keys = new Set([
+    ...Object.keys(previous),
+    ...Object.keys(current)
+  ])
+
+  for (const key of [...keys].sort()) {
+    const nextPath = Array.isArray(previous) || Array.isArray(current)
+      ? `${path}[${key}]`
+      : path ? `${path}.${key}` : key
+
+    collectChangedPaths(previous[key], current[key], nextPath, result)
+  }
+}
+
+/** Возвращает стабильный ключ фактически изменённых leaf-путей объекта. */
+export const getCrdtStoreChangeKey = (previous: object, current: object) => {
+  const paths: string[] = []
+
+  collectChangedPaths(previous, current, '', paths)
+
+  return paths.join('|')
+}