teamplay 0.3.35 → 0.4.0-alpha.0

package/orm/Doc.js

@@ -3,21 +3,27 @@ import { set as _set, del as _del } from './dataTree.js'
 import { SEGMENTS } from './Signal.js'
 import { getConnection, fetchOnly } from './connection.js'
 import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
+import SubscriptionState from './SubscriptionState.js'
 
 const ERROR_ON_EXCESSIVE_UNSUBSCRIBES = false
 
 class Doc {
-  subscribing
-  unsubscribing
-  subscribed
   initialized
 
   constructor (collection, docId) {
     this.collection = collection
     this.docId = docId
+    this.lifecycle = new SubscriptionState({
+      onSubscribe: () => this._subscribe(),
+      onUnsubscribe: () => this._unsubscribe()
+    })
     this.init()
   }
 
+  get subscribed () {
+    return this.lifecycle.subscribed
+  }
+
   init () {
     if (this.initialized) return
     this.initialized = true
@@ -25,47 +31,16 @@ class Doc {
   }
 
   async subscribe () {
-    if (this.subscribed) throw Error('trying to subscribe while already subscribed')
-    this.subscribed = true
-    // if we are in the middle of unsubscribing, just wait for it to finish and then resubscribe
-    if (this.unsubscribing) {
-      try {
-        await this.unsubscribing
-      } catch (err) {
-        // if error happened during unsubscribing, it means that we are still subscribed
-        // so we don't need to do anything
-        return
-      }
-    }
-    if (this.subscribing) {
-      try {
-        await this.subscribing
-        // if we are already subscribing from the previous time, delegate logic to that
-        // and if it finished successfully, we are done.
-        return
-      } catch (err) {
-        // if error happened during subscribing, we'll just try subscribing again
-        // so we just ignore the error and proceed with subscribing
-        this.subscribed = true
-      }
-    }
+    await this.lifecycle.subscribe()
+    this.init()
+  }
 
-    if (!this.subscribed) return // cancel if we initiated unsubscribe while waiting
-
-    this.subscribing = (async () => {
-      try {
-        this.subscribing = this._subscribe()
-        await this.subscribing
-        this.init()
-      } catch (err) {
-        console.log('subscription error', [this.collection, this.docId], err)
-        this.subscribed = undefined
-        throw err
-      } finally {
-        this.subscribing = undefined
-      }
-    })()
-    await this.subscribing
+  async unsubscribe () {
+    await this.lifecycle.unsubscribe()
+    if (!this.subscribed) {
+      this.initialized = undefined
+      this._removeData()
+    }
   }
 
   async _subscribe () {
@@ -79,66 +54,26 @@ class Doc {
     })
   }
 
-  async unsubscribe () {
-    if (!this.subscribed) {
-      throw Error('trying to unsubscribe while not subscribed. Doc: ' + [this.collection, this.docId])
-    }
-    this.subscribed = undefined
-    // if we are still handling the subscription, just wait for it to finish and then unsubscribe
-    if (this.subscribing) {
-      try {
-        await this.subscribing
-      } catch (err) {
-        // if error happened during subscribing, it means that we are still unsubscribed
-        // so we don't need to do anything
-        return
-      }
-    }
-    // if we are already unsubscribing from the previous time, delegate logic to that
-    if (this.unsubscribing) {
-      try {
-        await this.unsubscribing
-        return
-      } catch (err) {
-        // if error happened during unsubscribing, we'll just try unsubscribing again
-        this.subscribed = undefined
-      }
-    }
-
-    if (this.subscribed) return // cancel if we initiated subscribe while waiting
-
-    this.unsubscribing = (async () => {
-      try {
-        await this._unsubscribe()
-        this.initialized = undefined
-        this._removeData()
-      } catch (err) {
-        console.log('error unsubscribing', [this.collection, this.docId], err)
-        this.subscribed = true
-        throw err
-      } finally {
-        this.unsubscribing = undefined
-      }
-    })()
-    await this.unsubscribing
-  }
-
   async _unsubscribe () {
     const doc = getConnection().get(this.collection, this.docId)
     await new Promise((resolve, reject) => {
-      doc.destroy(err => {
+      // First unsubscribe cleanly, then destroy to remove from connection.collections.
+      // We can't call destroy() directly because it has a race condition: if connection.get()
+      // is called before destroy completes (e.g. rapid unsub/resub), it resets _wantsDestroy
+      // creating a corrupted state ("Cannot read properties of null (reading 'callback')").
+      // By unsubscribing first and destroying in the callback, the doc is in a clean state.
+      doc.unsubscribe(err => {
         if (err) return reject(err)
-        resolve()
+        doc.destroy(err => {
+          if (err) return reject(err)
+          resolve()
+        })
       })
     })
   }
 
   _initData () {
     const doc = getConnection().get(this.collection, this.docId)
-    // TODO: JSON does not have `undefined`, so we'll be receiving `null`.
-    //       Handle this by converting all `null` to `undefined` in the doc's data tree.
-    //       To do this we'll probably need to in the `op` event update the data tree
-    //       and have a clone of the doc in our local data tree.
     this._refData()
     doc.on('load', () => this._refData())
     doc.on('create', () => this._refData())
@@ -186,11 +121,12 @@ class DocSubscriptions {
     let count = this.subCount.get(hash) || 0
     count += 1
     this.subCount.set(hash, count)
-    if (count > 1) return this.docs.get(hash).subscribing
+    if (count > 1) return this.docs.get(hash)._subscribing
 
     this.init($doc)
     const doc = this.docs.get(hash)
-    return doc.subscribe()
+    doc._subscribing = doc.subscribe().then(() => { doc._subscribing = undefined })
+    return doc._subscribing
   }
 
   async unsubscribe ($doc) {
@@ -207,17 +143,18 @@ class DocSubscriptions {
       return
     }
     this.fr.unregister($doc)
-    this.destroy(segments)
+    await this.destroy(segments)
   }
 
   async destroy (segments) {
     const hash = hashDoc(segments)
     const doc = this.docs.get(hash)
     if (!doc) return
-    // Wait until after unsubscribe to delete subCount and docs
-    if (doc.subscribed) await doc.unsubscribe()
-    if (doc.subscribed) return // Subscribed again while unsubscribing
     this.subCount.delete(hash)
+    // Always call unsubscribe() - if doc is in SUBSCRIBING state, the state machine
+    // will queue a pending unsubscribe to execute after subscribe completes
+    await doc.unsubscribe()
+    if (doc.subscribed) return // Subscribed again while unsubscribing
     this.docs.delete(hash)
   }
 }

package/orm/Query.js

@@ -4,6 +4,7 @@ import getSignal from './getSignal.js'
 import { getConnection, fetchOnly } from './connection.js'
 import { docSubscriptions } from './Doc.js'
 import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
+import SubscriptionState from './SubscriptionState.js'
 
 const ERROR_ON_EXCESSIVE_UNSUBSCRIBES = false
 export const COLLECTION_NAME = Symbol('query collection name')
@@ -13,9 +14,6 @@ export const IS_QUERY = Symbol('is query signal')
 export const QUERIES = '$queries'
 
 export class Query {
-  subscribing
-  unsubscribing
-  subscribed
   initialized
   shareQuery
 
@@ -24,6 +22,14 @@ export class Query {
     this.params = params
     this.hash = hashQuery(this.collectionName, this.params)
     this.docSignals = new Set()
+    this.lifecycle = new SubscriptionState({
+      onSubscribe: () => this._subscribe(),
+      onUnsubscribe: () => this._unsubscribe()
+    })
+  }
+
+  get subscribed () {
+    return this.lifecycle.subscribed
   }
 
   init () {
@@ -33,47 +39,16 @@ export class Query {
   }
 
   async subscribe () {
-    if (this.subscribed) throw Error('trying to subscribe while already subscribed')
-    this.subscribed = true
-    // if we are in the middle of unsubscribing, just wait for it to finish and then resubscribe
-    if (this.unsubscribing) {
-      try {
-        await this.unsubscribing
-      } catch (err) {
-        // if error happened during unsubscribing, it means that we are still subscribed
-        // so we don't need to do anything
-        return
-      }
-    }
-    if (this.subscribing) {
-      try {
-        await this.subscribing
-        // if we are already subscribing from the previous time, delegate logic to that
-        // and if it finished successfully, we are done.
-        return
-      } catch (err) {
-        // if error happened during subscribing, we'll just try subscribing again
-        // so we just ignore the error and proceed with subscribing
-        this.subscribed = true
-      }
-    }
-
-    if (!this.subscribed) return // cancel if we initiated unsubscribe while waiting
+    await this.lifecycle.subscribe()
+    this.init()
+  }
 
-    this.subscribing = (async () => {
-      try {
-        this.subscribing = this._subscribe()
-        await this.subscribing
-        this.init()
-      } catch (err) {
-        console.log('subscription error', [this.collectionName, this.params], err)
-        this.subscribed = undefined
-        throw err
-      } finally {
-        this.subscribing = undefined
-      }
-    })()
-    await this.subscribing
+  async unsubscribe () {
+    await this.lifecycle.unsubscribe()
+    if (!this.subscribed) {
+      this.initialized = undefined
+      this._removeData()
+    }
   }
 
   async _subscribe () {
@@ -86,50 +61,6 @@ export class Query {
     })
   }
 
-  async unsubscribe () {
-    if (!this.subscribed) {
-      throw Error('trying to unsubscribe while not subscribed. Query: ' + [this.collectionName, this.params])
-    }
-    this.subscribed = undefined
-    // if we are still handling the subscription, just wait for it to finish and then unsubscribe
-    if (this.subscribing) {
-      try {
-        await this.subscribing
-      } catch (err) {
-        // if error happened during subscribing, it means that we are still unsubscribed
-        // so we don't need to do anything
-        return
-      }
-    }
-    // if we are already unsubscribing from the previous time, delegate logic to that
-    if (this.unsubscribing) {
-      try {
-        await this.unsubscribing
-        return
-      } catch (err) {
-        // if error happened during unsubscribing, we'll just try unsubscribing again
-        this.subscribed = undefined
-      }
-    }
-
-    if (this.subscribed) return // cancel if we initiated subscribe while waiting
-
-    this.unsubscribing = (async () => {
-      try {
-        await this._unsubscribe()
-        this.initialized = undefined
-        this._removeData()
-      } catch (err) {
-        console.log('error unsubscribing', [this.collectionName, this.params], err)
-        this.subscribed = true
-        throw err
-      } finally {
-        this.unsubscribing = undefined
-      }
-    })()
-    await this.unsubscribing
-  }
-
   async _unsubscribe () {
     if (!this.shareQuery) throw Error('this.shareQuery is not defined. This should never happen')
     await new Promise((resolve, reject) => {
@@ -220,7 +151,7 @@ export class QuerySubscriptions {
     let count = this.subCount.get(hash) || 0
     count += 1
     this.subCount.set(hash, count)
-    if (count > 1) return this.queries.get(hash).subscribing
+    if (count > 1) return this.queries.get(hash)._subscribing
 
     this.fr.register($query, { collectionName, params }, $query)
 
@@ -229,7 +160,8 @@ export class QuerySubscriptions {
       query = new this.QueryClass(collectionName, params)
       this.queries.set(hash, query)
     }
-    return query.subscribe()
+    query._subscribing = query.subscribe().then(() => { query._subscribing = undefined })
+    return query._subscribing
   }
 
   async unsubscribe ($query) {

package/orm/SubscriptionState.js

@@ -0,0 +1,138 @@
+// State machine for managing subscribe/unsubscribe lifecycle.
+//
+// States: IDLE, SUBSCRIBING, SUBSCRIBED, UNSUBSCRIBING
+//
+// Valid transitions:
+//   IDLE -> SUBSCRIBING (subscribe called)
+//   SUBSCRIBING -> SUBSCRIBED (subscribe succeeded)
+//   SUBSCRIBING -> IDLE (subscribe failed)
+//   SUBSCRIBED -> UNSUBSCRIBING (unsubscribe called)
+//   UNSUBSCRIBING -> IDLE (unsubscribe succeeded)
+//   UNSUBSCRIBING -> SUBSCRIBED (unsubscribe failed, rollback)
+//
+// Rapid sub/unsub handling:
+//   If subscribe() is called during UNSUBSCRIBING, we queue a resubscribe.
+//   If unsubscribe() is called during SUBSCRIBING, we queue an unsubscribe.
+//   Only the latest intent matters - intermediate intents are collapsed.
+
+export const STATE = {
+  IDLE: 'IDLE',
+  SUBSCRIBING: 'SUBSCRIBING',
+  SUBSCRIBED: 'SUBSCRIBED',
+  UNSUBSCRIBING: 'UNSUBSCRIBING'
+}
+
+export default class SubscriptionState {
+  #state = STATE.IDLE
+  #pendingAction = undefined // 'subscribe' | 'unsubscribe' | undefined
+  #activePromise = undefined
+  #onSubscribe // async () => void
+  #onUnsubscribe // async () => void
+
+  constructor ({ onSubscribe, onUnsubscribe }) {
+    this.#onSubscribe = onSubscribe
+    this.#onUnsubscribe = onUnsubscribe
+  }
+
+  get state () {
+    return this.#state
+  }
+
+  get subscribed () {
+    return this.#state === STATE.SUBSCRIBED
+  }
+
+  async subscribe () {
+    // Already subscribed - nothing to do
+    if (this.#state === STATE.SUBSCRIBED) return
+
+    // Already subscribing - if there was a pending unsubscribe, cancel it
+    if (this.#state === STATE.SUBSCRIBING) {
+      this.#pendingAction = undefined
+      return this.#activePromise
+    }
+
+    // Currently unsubscribing - queue a resubscribe after it finishes
+    if (this.#state === STATE.UNSUBSCRIBING) {
+      this.#pendingAction = 'subscribe'
+      return this.#activePromise
+    }
+
+    // IDLE - start subscribing
+    return this.#doSubscribe()
+  }
+
+  async unsubscribe () {
+    // Already idle - nothing to do
+    if (this.#state === STATE.IDLE) return
+
+    // Already unsubscribing - if there was a pending subscribe, cancel it
+    if (this.#state === STATE.UNSUBSCRIBING) {
+      this.#pendingAction = undefined
+      return this.#activePromise
+    }
+
+    // Currently subscribing - queue an unsubscribe after it finishes
+    if (this.#state === STATE.SUBSCRIBING) {
+      this.#pendingAction = 'unsubscribe'
+      return this.#activePromise
+    }
+
+    // SUBSCRIBED - start unsubscribing
+    return this.#doUnsubscribe()
+  }
+
+  async #doSubscribe () {
+    this.#state = STATE.SUBSCRIBING
+    this.#pendingAction = undefined
+
+    this.#activePromise = (async () => {
+      try {
+        await this.#onSubscribe()
+        this.#state = STATE.SUBSCRIBED
+      } catch (err) {
+        this.#state = STATE.IDLE
+        this.#pendingAction = undefined
+        throw err
+      } finally {
+        this.#activePromise = undefined
+      }
+      await this.#processPending()
+    })()
+
+    return this.#activePromise
+  }
+
+  async #doUnsubscribe () {
+    this.#state = STATE.UNSUBSCRIBING
+    this.#pendingAction = undefined
+
+    this.#activePromise = (async () => {
+      try {
+        await this.#onUnsubscribe()
+        this.#state = STATE.IDLE
+      } catch (err) {
+        this.#state = STATE.SUBSCRIBED
+        this.#pendingAction = undefined
+        throw err
+      } finally {
+        this.#activePromise = undefined
+      }
+      await this.#processPending()
+    })()
+
+    return this.#activePromise
+  }
+
+  async #processPending () {
+    const action = this.#pendingAction
+    this.#pendingAction = undefined
+
+    if (action === 'subscribe' && this.#state === STATE.IDLE) {
+      return this.#doSubscribe()
+    }
+    if (action === 'unsubscribe' && this.#state === STATE.SUBSCRIBED) {
+      return this.#doUnsubscribe()
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.3.35",
+  "version": "0.4.0-alpha.0",
   "description": "Full-stack signals ORM with multiplayer",
   "type": "module",
   "main": "index.js",
@@ -23,17 +23,20 @@
     "test": "npm run test-server && npm run test-client",
     "test-server": "NODE_OPTIONS=\"--expose-gc\" mocha 'test/[!_]*.js'",
     "test-server-only": "NODE_OPTIONS=\"--expose-gc\" mocha --grep '@only' 'test/[!_]*.js'",
-    "test-client": "NODE_OPTIONS=\"$NODE_OPTIONS --expose-gc --experimental-vm-modules\" jest"
+    "test-client": "NODE_OPTIONS=\"$NODE_OPTIONS --expose-gc --experimental-vm-modules\" jest",
+    "coverage-server": "NODE_OPTIONS=\"--expose-gc\" c8 --include 'orm/**' --include 'react/**' --include 'utils/**' mocha 'test/[!_]*.js'",
+    "coverage-client": "NODE_OPTIONS=\"$NODE_OPTIONS --expose-gc --experimental-vm-modules\" jest --coverage --coverageDirectory=coverage-client",
+    "coverage": "npm run coverage-server && npm run coverage-client"
   },
   "dependencies": {
     "@nx-js/observer-util": "^4.1.3",
     "@startupjs/sharedb-mingo-memory": "^4.0.0-2",
-    "@teamplay/backend": "^0.3.35",
-    "@teamplay/cache": "^0.3.34",
-    "@teamplay/channel": "^0.3.34",
-    "@teamplay/debug": "^0.3.34",
-    "@teamplay/schema": "^0.3.34",
-    "@teamplay/utils": "^0.3.34",
+    "@teamplay/backend": "^0.4.0-alpha.0",
+    "@teamplay/cache": "^0.4.0-alpha.0",
+    "@teamplay/channel": "^0.4.0-alpha.0",
+    "@teamplay/debug": "^0.4.0-alpha.0",
+    "@teamplay/schema": "^0.4.0-alpha.0",
+    "@teamplay/utils": "^0.4.0-alpha.0",
     "diff-match-patch": "^1.0.5",
     "events": "^3.3.0",
     "json0-ot-diff": "^1.1.2",
@@ -45,6 +48,7 @@
   "devDependencies": {
     "@jest/globals": "^29.7.0",
     "@testing-library/react": "^15.0.7",
+    "c8": "^10.1.3",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "mocha": "^11.0.1",
@@ -74,5 +78,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "9c51c8f0d4ee739896466a7574b8a206c4d5d463"
+  "gitHead": "fb723714f5c425d763b1a7b45e75adb990a39707"
 }