teamplay 0.4.0-alpha.81 → 0.4.0-alpha.83

package/index.js

@@ -65,7 +65,15 @@ export {
   useOnce,
   useSyncEffect
 } from './react/helpers.js'
-export { connection, setConnection, getConnection, fetchOnly, setFetchOnly, publicOnly, setPublicOnly } from './orm/connection.js'
+export {
+  connection,
+  setConnection,
+  getConnection,
+  getDefaultFetchOnly,
+  setDefaultFetchOnly,
+  publicOnly,
+  setPublicOnly
+} from './orm/connection.js'
 export { getSubscriptionGcDelay, setSubscriptionGcDelay } from './orm/subscriptionGcDelay.js'
 export { useId, useNow, useScheduleUpdate, useTriggerUpdate } from './react/helpers.js'
 export { GUID_PATTERN, hasMany, hasOne, hasManyFlags, belongsTo, pickFormFields } from '@teamplay/schema'

package/orm/Compat/SignalCompat.js

@@ -9,7 +9,7 @@ import {
   isPublicDocumentSignal
 } from '../SignalBase.js'
 import { getRoot, ROOT, ROOT_ID, getRootSignal, GLOBAL_ROOT_ID, unregisterRootFinalizer } from '../Root.js'
-import { publicOnly, fetchOnly, setFetchOnly } from '../connection.js'
+import { isPrivateMutationForbidden } from '../connection.js'
 import { docSubscriptions } from '../Doc.js'
 import { IS_QUERY, getQuerySignal, querySubscriptions } from '../Query.js'
 import { IS_AGGREGATION, aggregationSubscriptions, getAggregationSignal } from '../Aggregation.js'
@@ -123,15 +123,13 @@ class SignalCompat extends Signal {
   }
 
   fetch (...items) {
-    return withFetchOnly(() => {
-      if (items.length > 0) return subscribeMany(items, 'subscribe')
-      return subscribeSelf(this)
-    })
+    if (items.length > 0) return subscribeMany(items, 'subscribe', 'fetch')
+    return subscribeSelf(this, 'fetch')
   }
 
   unfetch (...items) {
-    if (items.length > 0) return subscribeMany(items, 'unsubscribe')
-    return unsubscribeSelf(this)
+    if (items.length > 0) return subscribeMany(items, 'unsubscribe', 'fetch')
+    return unsubscribeSelf(this, 'fetch')
   }
 
   getExtra () {
@@ -1108,7 +1106,7 @@ async function setReplaceOnSignal ($signal, value) {
     mirrorRefMutationFromTarget(segments, value)
     return result
   }
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   const result = setReplacePrivateData(getOwningRootId($signal), segments, value)
   mirrorRefMutationFromTarget(segments, value)
   return result
@@ -1128,7 +1126,7 @@ async function incrementOnSignal ($signal, byNumber) {
     await _incrementPublic(segments, byNumber)
     return currentValue + byNumber
   }
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   setReplacePrivateData(getOwningRootId($signal), segments, currentValue + byNumber)
   return currentValue + byNumber
 }
@@ -1161,7 +1159,7 @@ async function arrayPushOnSignal ($signal, value) {
   const idFields = getIdFieldsForSegments(segments)
   if (isIdFieldPath(segments, idFields)) return
   if (isPublicCollection(segments[0])) return _arrayPushPublic(segments, value)
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   return arrayPushPrivateData(getOwningRootId($signal), segments, value)
 }
 
@@ -1170,7 +1168,7 @@ async function arrayUnshiftOnSignal ($signal, value) {
   const idFields = getIdFieldsForSegments(segments)
   if (isIdFieldPath(segments, idFields)) return
   if (isPublicCollection(segments[0])) return _arrayUnshiftPublic(segments, value)
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   return arrayUnshiftPrivateData(getOwningRootId($signal), segments, value)
 }
 
@@ -1179,7 +1177,7 @@ async function arrayInsertOnSignal ($signal, index, values) {
   const idFields = getIdFieldsForSegments(segments)
   if (isIdFieldPath(segments, idFields)) return
   if (isPublicCollection(segments[0])) return _arrayInsertPublic(segments, index, values)
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   return arrayInsertPrivateData(getOwningRootId($signal), segments, index, values)
 }
 
@@ -1188,7 +1186,7 @@ async function arrayPopOnSignal ($signal) {
   const idFields = getIdFieldsForSegments(segments)
   if (isIdFieldPath(segments, idFields)) return
   if (isPublicCollection(segments[0])) return _arrayPopPublic(segments)
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   return arrayPopPrivateData(getOwningRootId($signal), segments)
 }
 
@@ -1197,7 +1195,7 @@ async function arrayShiftOnSignal ($signal) {
   const idFields = getIdFieldsForSegments(segments)
   if (isIdFieldPath(segments, idFields)) return
   if (isPublicCollection(segments[0])) return _arrayShiftPublic(segments)
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   return arrayShiftPrivateData(getOwningRootId($signal), segments)
 }
 
@@ -1206,7 +1204,7 @@ async function arrayRemoveOnSignal ($signal, index, howMany) {
   const idFields = getIdFieldsForSegments(segments)
   if (isIdFieldPath(segments, idFields)) return
   if (isPublicCollection(segments[0])) return _arrayRemovePublic(segments, index, howMany)
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   return arrayRemovePrivateData(getOwningRootId($signal), segments, index, howMany)
 }
 
@@ -1215,7 +1213,7 @@ async function arrayMoveOnSignal ($signal, from, to, howMany) {
   const idFields = getIdFieldsForSegments(segments)
   if (isIdFieldPath(segments, idFields)) return
   if (isPublicCollection(segments[0])) return _arrayMovePublic(segments, from, to, howMany)
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   return arrayMovePrivateData(getOwningRootId($signal), segments, from, to, howMany)
 }
 
@@ -1224,7 +1222,7 @@ async function stringInsertOnSignal ($signal, index, text) {
   const idFields = getIdFieldsForSegments(segments)
   if (isIdFieldPath(segments, idFields)) return
   if (isPublicCollection(segments[0])) return _stringInsertPublic(segments, index, text)
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   return stringInsertPrivateData(getOwningRootId($signal), segments, index, text)
 }
 
@@ -1233,7 +1231,7 @@ async function stringRemoveOnSignal ($signal, index, howMany) {
   const idFields = getIdFieldsForSegments(segments)
   if (isIdFieldPath(segments, idFields)) return
   if (isPublicCollection(segments[0])) return _stringRemovePublic(segments, index, howMany)
-  if (publicOnly) throw Error(ERRORS.publicOnly)
+  if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
   return stringRemovePrivateData(getOwningRootId($signal), segments, index, howMany)
 }
 
@@ -1297,17 +1295,7 @@ function withQueryScopeOptions (options, $root) {
   return nextOptions
 }
 
-function withFetchOnly (fn) {
-  const prevFetchOnly = fetchOnly
-  setFetchOnly(true)
-  try {
-    return fn()
-  } finally {
-    setFetchOnly(prevFetchOnly)
-  }
-}
-
-function subscribeMany (items, action) {
+function subscribeMany (items, action, intent = 'subscribe') {
   const targets = flattenItems(items)
   const promises = []
   for (const target of targets) {
@@ -1316,8 +1304,8 @@ function subscribeMany (items, action) {
       throw Error(`Signal.${action}() accepts only Signal instances. Got: ${target}`)
     }
     const result = action === 'subscribe'
-      ? subscribeSelf(target)
-      : unsubscribeSelf(target)
+      ? subscribeSelf(target, intent)
+      : unsubscribeSelf(target, intent)
     if (result?.then) promises.push(result)
   }
   if (promises.length) return Promise.all(promises)
@@ -1335,20 +1323,20 @@ function flattenItems (items, result = []) {
   return result
 }
 
-function subscribeSelf ($signal) {
+function subscribeSelf ($signal, intent = 'subscribe') {
   if ($signal[IS_QUERY]) {
     return (async () => {
-      await querySubscriptions.subscribe($signal)
+      await querySubscriptions.subscribe($signal, { intent })
       await waitForImperativeQueryReady($signal)
     })()
   }
   if ($signal[IS_AGGREGATION]) {
     return (async () => {
-      await aggregationSubscriptions.subscribe($signal)
+      await aggregationSubscriptions.subscribe($signal, { intent })
       await waitForImperativeQueryReady($signal)
     })()
   }
-  if (isPublicDocumentSignal($signal)) return docSubscriptions.subscribe($signal)
+  if (isPublicDocumentSignal($signal)) return docSubscriptions.subscribe($signal, { intent })
   if (isPublicCollectionSignal($signal)) {
     throw Error('Signal.subscribe() expects a query signal. Use .query() for collections.')
   }
@@ -1358,10 +1346,10 @@ function subscribeSelf ($signal) {
   throw Error('Signal.subscribe() expects a document or query signal')
 }
 
-function unsubscribeSelf ($signal) {
-  if ($signal[IS_QUERY]) return querySubscriptions.unsubscribe($signal)
-  if ($signal[IS_AGGREGATION]) return aggregationSubscriptions.unsubscribe($signal)
-  if (isPublicDocumentSignal($signal)) return docSubscriptions.unsubscribe($signal)
+function unsubscribeSelf ($signal, intent = 'subscribe') {
+  if ($signal[IS_QUERY]) return querySubscriptions.unsubscribe($signal, { intent })
+  if ($signal[IS_AGGREGATION]) return aggregationSubscriptions.unsubscribe($signal, { intent })
+  if (isPublicDocumentSignal($signal)) return docSubscriptions.unsubscribe($signal, { intent })
   if (isPublicCollectionSignal($signal)) {
     throw Error('Signal.unsubscribe() expects a query signal. Use .query() for collections.')
   }

package/orm/Doc.js

@@ -1,14 +1,14 @@
 import { isObservable, observable, raw } from '@nx-js/observer-util'
 import { set as _set, del as _del, getRaw as _getRaw } from './dataTree.js'
 import { SEGMENTS } from './Signal.js'
-import { getConnection, fetchOnly } from './connection.js'
+import { getConnection } from './connection.js'
 import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
 import SubscriptionState from './SubscriptionState.js'
 import { getIdFieldsForSegments, injectIdFields, isPlainObject } from './idFields.js'
 import { emitModelChange, isModelEventsEnabled } from './Compat/modelEvents.js'
 import { getSubscriptionGcDelay } from './subscriptionGcDelay.js'
 import { isMissingShareDoc } from './missingDoc.js'
-import { getRoot, ROOT_ID, GLOBAL_ROOT_ID } from './Root.js'
+import { getRoot, ROOT_ID, GLOBAL_ROOT_ID, getRootTransportMode } from './Root.js'
 import {
   registerRootOwnedDirectDocSubscription,
   unregisterRootOwnedDirectDocSubscription,
@@ -45,6 +45,8 @@ class Doc {
       onSubscribe: () => this._subscribe(),
       onUnsubscribe: () => this._unsubscribe()
     })
+    this.requestedTransportMode = 'subscribe'
+    this.activeTransportMode = 'idle'
     this.init()
   }
 
@@ -58,7 +60,8 @@ class Doc {
     this._initData()
   }
 
-  async subscribe () {
+  async subscribe ({ mode } = {}) {
+    if (mode) this.requestedTransportMode = mode
     await this.lifecycle.subscribe()
     this.init()
   }
@@ -69,10 +72,12 @@ class Doc {
 
   async _subscribe () {
     const doc = getConnection().get(this.collection, this.docId)
+    const mode = this.requestedTransportMode
     await new Promise((resolve, reject) => {
-      const method = fetchOnly ? 'fetch' : 'subscribe'
+      const method = mode === 'fetch' ? 'fetch' : 'subscribe'
       doc[method](err => {
         if (err) return reject(err)
+        this.activeTransportMode = mode
         resolve()
       })
     })
@@ -81,8 +86,12 @@ class Doc {
   async _unsubscribe () {
     const doc = getConnection().get(this.collection, this.docId)
     await new Promise((resolve, reject) => {
-      doc.unsubscribe(err => {
+      const method = this.activeTransportMode === 'fetch' && typeof doc.unfetch === 'function'
+        ? 'unfetch'
+        : 'unsubscribe'
+      doc[method](err => {
         if (err) return reject(err)
+        this.activeTransportMode = 'idle'
         resolve()
       })
     })
@@ -167,10 +176,15 @@ class Doc {
 export class DocSubscriptions {
   constructor (DocClass = Doc) {
     this.DocClass = DocClass
-    this.subCount = new Map()
+    this.subCount = new Map() // transportHash -> total ref count (owners + retained docs)
+    this.ownerFetchCount = new Map() // ownerKey -> fetch intent count
+    this.ownerSubscribeCount = new Map() // ownerKey -> subscribe intent count
+    this.ownerMeta = new Map() // ownerKey -> { hash, segments, rootId }
+    this.ownerKeysByHash = new Map() // transportHash -> Set(ownerKey)
     this.docs = new Map()
     this.pendingDestroyTimers = new Map()
-    this.fr = new FinalizationRegistry(segments => this.scheduleDestroy(segments, { force: true }))
+    this.transportTasks = new Map()
+    this.fr = new FinalizationRegistry(({ hash, ownerKey }) => this.destroyByOwnerKey(ownerKey, { hash, force: true }))
   }
 
   init ($doc) {
@@ -183,34 +197,36 @@ export class DocSubscriptions {
     } else {
       doc = new this.DocClass(...segments)
       this.docs.set(hash, doc)
-      this.fr.register($doc, segments, getDocFinalizationToken($doc))
       doc.init()
     }
   }
 
-  subscribe ($doc) {
+  subscribe ($doc, { intent = 'subscribe' } = {}) {
     const segments = [...$doc[SEGMENTS]]
     const hash = hashDoc(segments)
     const rootId = getOwningRootId($doc)
+    const ownerKey = getDocOwnerKey(rootId, hash)
+    const token = getDocFinalizationToken($doc)
+    const previousCount = this.subCount.get(hash) || 0
     this.cancelDestroy(hash)
-    let count = this.subCount.get(hash) || 0
-    count += 1
-    this.subCount.set(hash, count)
+    this.incrementOwnerIntent(ownerKey, intent)
+    this.addOwnerMeta(ownerKey, hash, segments, rootId)
+    this.subCount.set(hash, previousCount + 1)
     if (rootId) {
-      registerRootOwnedDirectDocSubscription(rootId, hash, segments, getDocFinalizationToken($doc))
-    }
-    if (count > 1) {
-      const existingDoc = this.docs.get(hash)
-      if (existingDoc) return existingDoc._subscribing
-      // Recover from stale ref-count state when doc entry was already cleaned up.
-      count = 1
-      this.subCount.set(hash, count)
+      registerRootOwnedDirectDocSubscription(rootId, hash, segments, token)
     }
+    this.fr.register($doc, { hash, ownerKey }, token)
 
     this.init($doc)
     const doc = this.docs.get(hash)
-    doc._subscribing = doc.subscribe().then(() => { doc._subscribing = undefined })
-    return doc._subscribing
+    if (
+      previousCount > 0 &&
+      doc &&
+      !doc._subscribing &&
+      !this.transportTasks.get(hash) &&
+      this.getDesiredTransportMode(hash) === doc.activeTransportMode
+    ) return
+    return this.reconcileTransport(hash)
   }
 
   retain ($doc) {
@@ -222,26 +238,33 @@ export class DocSubscriptions {
     this.init($doc)
   }
 
-  async unsubscribe ($doc) {
+  async unsubscribe ($doc, { intent = 'subscribe' } = {}) {
     const segments = [...$doc[SEGMENTS]]
     const hash = hashDoc(segments)
     const rootId = getOwningRootId($doc)
-    let count = this.subCount.get(hash) || 0
-    count -= 1
-    if (count < 0) {
+    const ownerKey = getDocOwnerKey(rootId, hash)
+    const token = getDocFinalizationToken($doc)
+    const currentIntentCount = this.getOwnerIntentCount(ownerKey, intent)
+    if (currentIntentCount <= 0) {
       if (ERROR_ON_EXCESSIVE_UNSUBSCRIBES) throw ERRORS.notSubscribed($doc)
       return
     }
-    if (count > 0) {
-      this.subCount.set(hash, count)
-      return
-    }
-    this.subCount.set(hash, 0)
-    this.fr.unregister(getDocFinalizationToken($doc))
+    this.setOwnerIntentCount(ownerKey, intent, currentIntentCount - 1)
+    const nextOwnerCount = this.getOwnerTotalCount(ownerKey)
+    const count = Math.max((this.subCount.get(hash) || 0) - 1, 0)
+    if (count > 0) this.subCount.set(hash, count)
+    else this.subCount.set(hash, 0)
     if (rootId) {
-      unregisterRootOwnedDirectDocSubscription(rootId, hash, getDocFinalizationToken($doc))
+      unregisterRootOwnedDirectDocSubscription(rootId, hash, token)
     }
-    await this.scheduleDestroy(segments)
+    if (nextOwnerCount === 0) {
+      this.fr.unregister(token)
+      this.removeOwnerMeta(ownerKey, hash)
+    }
+    const destroyPromise = count === 0 ? this.scheduleDestroy(segments) : undefined
+    await this.reconcileTransport(hash)
+    if (count > 0) return
+    await destroyPromise
   }
 
   async release ($doc) {
@@ -275,6 +298,10 @@ export class DocSubscriptions {
       await this.destroyByHash(hash, { force: true })
     }
     this.subCount.clear()
+    this.ownerFetchCount.clear()
+    this.ownerSubscribeCount.clear()
+    this.ownerMeta.clear()
+    this.ownerKeysByHash.clear()
   }
 
   async releaseRootOwnedSubscriptions (rootId) {
@@ -284,14 +311,7 @@ export class DocSubscriptions {
       for (const token of entry.tokenCounts.keys()) {
         this.fr.unregister(token)
       }
-      const currentCount = this.subCount.get(hash) || 0
-      const nextCount = Math.max(currentCount - entry.count, 0)
-      if (nextCount > 0) {
-        this.subCount.set(hash, nextCount)
-        continue
-      }
-      this.subCount.set(hash, 0)
-      await this.destroyByHash(hash, { force: true })
+      await this.destroyByOwnerKey(getDocOwnerKey(rootId, hash), { hash, force: true })
     }
     clearRootOwnedDirectDocSubscriptions(rootId)
   }
@@ -330,6 +350,40 @@ export class DocSubscriptions {
     entry.resolve()
   }
 
+  async reconcileTransport (hash) {
+    const previous = this.transportTasks.get(hash) || Promise.resolve()
+    const next = previous
+      .catch(ignoreDestroyError)
+      .then(() => this.reconcileTransportNow(hash))
+    this.transportTasks.set(hash, next)
+    try {
+      await next
+    } finally {
+      if (this.transportTasks.get(hash) === next) this.transportTasks.delete(hash)
+    }
+  }
+
+  async reconcileTransportNow (hash) {
+    const doc = this.docs.get(hash)
+    if (!doc) return
+    while (true) {
+      const desiredMode = this.getDesiredTransportMode(hash)
+      const currentMode = doc.activeTransportMode
+      if (desiredMode === currentMode) return
+      if (desiredMode === 'idle') {
+        if (currentMode === 'idle') return
+        await doc.unsubscribe()
+        continue
+      }
+      if (currentMode !== 'idle') {
+        await doc.unsubscribe()
+        continue
+      }
+      doc._subscribing = doc.subscribe({ mode: desiredMode }).then(() => { doc._subscribing = undefined })
+      await doc._subscribing
+    }
+  }
+
   async destroyByHash (hash, options = {}) {
     let pendingDestroy = options._pendingDestroy
     if (pendingDestroy) this.takePendingDestroy(hash, pendingDestroy)
@@ -354,12 +408,13 @@ export class DocSubscriptions {
         settlePending()
         return
       }
-      // 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) {
+      await this.reconcileTransport(hash)
+      if (!options.force && (this.subCount.get(hash) || 0) > 0) {
         settlePending()
-        return // Subscribed again while unsubscribing
+        return
+      }
+      if (doc.activeTransportMode !== 'idle') {
+        await doc.unsubscribe()
       }
       if (!options.force && (this.subCount.get(hash) || 0) > 0) {
         settlePending()
@@ -381,6 +436,7 @@ export class DocSubscriptions {
       if (typeof doc.dispose === 'function') doc.dispose()
       this.docs.delete(hash)
       this.subCount.delete(hash)
+      this.ownerKeysByHash.delete(hash)
       settlePending()
     } catch (err) {
       settlePending(err)
@@ -396,6 +452,83 @@ export class DocSubscriptions {
     this.pendingDestroyTimers.delete(hash)
     return entry
   }
+
+  getOwnerIntentCount (ownerKey, intent) {
+    const store = intent === 'fetch' ? this.ownerFetchCount : this.ownerSubscribeCount
+    return store.get(ownerKey) || 0
+  }
+
+  setOwnerIntentCount (ownerKey, intent, count) {
+    const store = intent === 'fetch' ? this.ownerFetchCount : this.ownerSubscribeCount
+    if (count > 0) store.set(ownerKey, count)
+    else store.delete(ownerKey)
+  }
+
+  incrementOwnerIntent (ownerKey, intent) {
+    this.setOwnerIntentCount(ownerKey, intent, this.getOwnerIntentCount(ownerKey, intent) + 1)
+  }
+
+  getOwnerTotalCount (ownerKey) {
+    return (this.ownerFetchCount.get(ownerKey) || 0) + (this.ownerSubscribeCount.get(ownerKey) || 0)
+  }
+
+  addOwnerMeta (ownerKey, hash, segments, rootId) {
+    if (this.ownerMeta.has(ownerKey)) return
+    this.ownerMeta.set(ownerKey, { hash, segments: [...segments], rootId })
+    let ownerKeys = this.ownerKeysByHash.get(hash)
+    if (!ownerKeys) {
+      ownerKeys = new Set()
+      this.ownerKeysByHash.set(hash, ownerKeys)
+    }
+    ownerKeys.add(ownerKey)
+  }
+
+  removeOwnerMeta (ownerKey, hash) {
+    const meta = this.ownerMeta.get(ownerKey)
+    const knownHash = hash ?? meta?.hash
+    this.ownerMeta.delete(ownerKey)
+    this.ownerFetchCount.delete(ownerKey)
+    this.ownerSubscribeCount.delete(ownerKey)
+    if (!knownHash) return
+    const ownerKeys = this.ownerKeysByHash.get(knownHash)
+    if (!ownerKeys) return
+    ownerKeys.delete(ownerKey)
+    if (ownerKeys.size === 0) this.ownerKeysByHash.delete(knownHash)
+  }
+
+  getDesiredTransportMode (hash) {
+    const ownerKeys = this.ownerKeysByHash.get(hash)
+    if (!ownerKeys || ownerKeys.size === 0) return 'idle'
+    let hasFetchBackedOwner = false
+    for (const ownerKey of ownerKeys) {
+      const subscribeCount = this.ownerSubscribeCount.get(ownerKey) || 0
+      const fetchCount = this.ownerFetchCount.get(ownerKey) || 0
+      const rootId = this.ownerMeta.get(ownerKey)?.rootId
+      const subscribeMode = getRootTransportMode(rootId, 'subscribe')
+      if (subscribeCount > 0 && subscribeMode === 'subscribe') return 'subscribe'
+      if (fetchCount > 0 || (subscribeCount > 0 && subscribeMode === 'fetch')) {
+        hasFetchBackedOwner = true
+      }
+    }
+    return hasFetchBackedOwner ? 'fetch' : 'idle'
+  }
+
+  async destroyByOwnerKey (ownerKey, options = {}) {
+    const meta = this.ownerMeta.get(ownerKey)
+    if (!meta) return
+    const { hash, segments } = meta
+    const ownerCount = this.getOwnerTotalCount(ownerKey)
+    if (!options.force && ownerCount > 0) return
+
+    const currentCount = this.subCount.get(hash) || 0
+    const nextCount = Math.max(currentCount - ownerCount, 0)
+    if (nextCount > 0) this.subCount.set(hash, nextCount)
+    else this.subCount.set(hash, 0)
+    this.removeOwnerMeta(ownerKey, hash)
+    await this.reconcileTransport(hash)
+    if (nextCount > 0) return
+    await this.scheduleDestroy(segments, { force: !!options.force })
+  }
 }
 
 export const docSubscriptions = new DocSubscriptions()
@@ -404,6 +537,10 @@ function hashDoc (segments) {
   return JSON.stringify(segments)
 }
 
+function getDocOwnerKey (rootId, hash) {
+  return JSON.stringify({ owner: [rootId, hash] })
+}
+
 function ignoreDestroyError () {}
 
 function createPendingDestroyEntry () {

package/orm/Query.js

@@ -1,7 +1,7 @@
 import { raw } from '@nx-js/observer-util'
 import { set as _set, getRaw } from './dataTree.js'
 import getSignal from './getSignal.js'
-import { getConnection, fetchOnly } from './connection.js'
+import { getConnection } from './connection.js'
 import { emitModelChange, isModelEventsEnabled } from './Compat/modelEvents.js'
 import { isCompatEnv } from './compatEnv.js'
 import { docSubscriptions } from './Doc.js'
@@ -10,7 +10,7 @@ import SubscriptionState from './SubscriptionState.js'
 import { getIdFieldsForSegments, injectIdFields, isPlainObject } from './idFields.js'
 import { getSubscriptionGcDelay } from './subscriptionGcDelay.js'
 import { getScopedSignalHash } from './rootScope.js'
-import { getRoot, ROOT_ID } from './Root.js'
+import { getRoot, ROOT_ID, getRootTransportMode } from './Root.js'
 import { registerRootOwnedRuntime, unregisterRootOwnedRuntime } from './rootContext.js'
 import {
   delPrivateData,
@@ -39,10 +39,12 @@ export class Query {
       onSubscribe: () => this._subscribe(),
       onUnsubscribe: () => this._unsubscribe()
     })
+    this.requestedTransportMode = 'subscribe'
+    this.activeTransportMode = 'idle'
   }
 
   get subscribed () {
-    return this.lifecycle.subscribed
+    return this.activeTransportMode !== 'idle' || this.lifecycle.subscribed
   }
 
   init () {
@@ -51,7 +53,8 @@ export class Query {
     this._initData()
   }
 
-  async subscribe () {
+  async subscribe ({ mode } = {}) {
+    if (mode) this.requestedTransportMode = mode
     await this.lifecycle.subscribe()
     this.init()
   }
@@ -60,7 +63,7 @@ export class Query {
     await this.lifecycle.unsubscribe()
     if (!this.subscribed) {
       this.initialized = undefined
-      this._removeData()
+      this._detachTransportData({ keepRoots: false })
     }
   }
 
@@ -78,10 +81,12 @@ export class Query {
   }
 
   async _subscribe () {
+    const mode = this.requestedTransportMode
     await new Promise((resolve, reject) => {
-      const method = fetchOnly ? 'createFetchQuery' : 'createSubscribeQuery'
+      const method = mode === 'fetch' ? 'createFetchQuery' : 'createSubscribeQuery'
       this.shareQuery = getConnection()[method](this.collectionName, this.params, {}, err => {
         if (err) return reject(err)
+        this.activeTransportMode = mode
         resolve()
       })
     })
@@ -92,6 +97,7 @@ export class Query {
     await new Promise((resolve, reject) => {
       this.shareQuery.destroy(err => {
         if (err) return reject(err)
+        this.activeTransportMode = 'idle'
         resolve()
       })
       this.shareQuery = undefined
@@ -250,13 +256,17 @@ export class Query {
     })
   }
 
-  _removeData () {
+  _detachTransportData ({ keepRoots = true } = {}) {
     for (const $doc of this.docSignals) {
       docSubscriptions.release($doc).catch(ignoreDestroyError)
     }
     this.docSignals.clear()
     this._forEachRoot(rootId => this._removeRootData(rootId))
-    this.rootIds.clear()
+    if (!keepRoots) this.rootIds.clear()
+  }
+
+  _removeData () {
+    this._detachTransportData({ keepRoots: false })
   }
 }
 
@@ -264,39 +274,44 @@ export class QuerySubscriptions {
   constructor (QueryClass = Query) {
     this.QueryClass = QueryClass
     this.runtimeKind = 'query'
-    this.subCount = new Map() // ownerKey -> count
-    this.transportSubCount = new Map() // transportHash -> attached roots count
+    this.subCount = new Map() // ownerKey -> total ref count
+    this.transportSubCount = new Map() // transportHash -> attached owner count
+    this.ownerFetchCount = new Map() // ownerKey -> fetch intent count
+    this.ownerSubscribeCount = new Map() // ownerKey -> subscribe intent count
     this.queries = new Map()
     this.ownerToTransport = new Map() // ownerKey -> transportHash
     this.ownerMeta = new Map() // ownerKey -> { collectionName, params, transportHash, rootId }
     this.ownerKeysByTransport = new Map() // transportHash -> Set(ownerKey)
     this.pendingDestroyTimers = new Map()
+    this.transportTasks = new Map()
     this.fr = new FinalizationRegistry(({ collectionName, params, ownerKey }) => {
       this.scheduleDestroy(collectionName, params, ownerKey, { force: true })
     })
   }
 
-  subscribe ($query) {
+  subscribe ($query, { intent = 'subscribe' } = {}) {
     const collectionName = $query[COLLECTION_NAME]
     const params = cloneQueryParams($query[PARAMS])
     const transportHash = $query[HASH]
     const rootId = getOwningRootId($query)
     const ownerKey = getQueryOwnerKey(rootId, transportHash)
     this.cancelDestroy(ownerKey)
-    let count = this.subCount.get(ownerKey) || 0
-    count += 1
-    this.subCount.set(ownerKey, count)
-    if (count > 1) {
-      const existingQuery = this.queries.get(transportHash)
-      if (existingQuery) return existingQuery._subscribing
-      // Recover from stale ref-count state when query was already cleaned up.
-      count = 1
-      this.subCount.set(ownerKey, count)
+
+    let query = this.queries.get(transportHash)
+    let previousCount = this.subCount.get(ownerKey) || 0
+    if (previousCount > 0 && !query) {
+      this.subCount.delete(ownerKey)
+      this.ownerFetchCount.delete(ownerKey)
+      this.ownerSubscribeCount.delete(ownerKey)
+      const staleTransportHash = this.ownerToTransport.get(ownerKey)
+      if (staleTransportHash) this.removeOwnerMeta(ownerKey, staleTransportHash)
+      previousCount = 0
     }
 
+    this.incrementOwnerIntent(ownerKey, intent)
+    this.subCount.set(ownerKey, previousCount + 1)
     this.fr.register($query, { collectionName, params, ownerKey }, $query)
 
-    let query = this.queries.get(transportHash)
     if (!query) {
       query = new this.QueryClass(collectionName, params, { hash: transportHash })
       this.queries.set(transportHash, query)
@@ -320,29 +335,66 @@ export class QuerySubscriptions {
 
       const transportCount = (this.transportSubCount.get(transportHash) || 0) + 1
       this.transportSubCount.set(transportHash, transportCount)
-      if (transportCount === 1) {
-        query._subscribing = query.subscribe().then(() => { query._subscribing = undefined })
-      }
     }
 
-    return query._subscribing
+    if (
+      previousCount > 0 &&
+      query &&
+      !query._subscribing &&
+      !this.transportTasks.get(transportHash) &&
+      this.getDesiredTransportMode(transportHash) === query.activeTransportMode
+    ) return
+
+    return this.reconcileTransport(transportHash)
   }
 
-  async unsubscribe ($query) {
+  async unsubscribe ($query, { intent = 'subscribe' } = {}) {
     const ownerKey = getQueryOwnerKey(getOwningRootId($query), $query[HASH])
-    let count = this.subCount.get(ownerKey) || 0
-    count -= 1
-    if (count < 0) {
+    const currentIntentCount = this.getOwnerIntentCount(ownerKey, intent)
+    if (currentIntentCount <= 0) {
+      if ((this.subCount.get(ownerKey) || 0) > 0 && !this.queries.get($query[HASH])) {
+        this.subCount.delete(ownerKey)
+        this.ownerFetchCount.delete(ownerKey)
+        this.ownerSubscribeCount.delete(ownerKey)
+        this.removeOwnerMeta(ownerKey)
+      }
       if (ERROR_ON_EXCESSIVE_UNSUBSCRIBES) throw Error(ERRORS.notSubscribed($query))
       return
     }
+
+    const meta = this.ownerMeta.get(ownerKey)
+    const transportHash = meta?.transportHash ?? $query[HASH]
+
+    this.setOwnerIntentCount(ownerKey, intent, currentIntentCount - 1)
+
+    const count = Math.max((this.subCount.get(ownerKey) || 0) - 1, 0)
     if (count > 0) {
       this.subCount.set(ownerKey, count)
-      return
+    } else {
+      this.subCount.set(ownerKey, 0)
     }
-    this.subCount.set(ownerKey, 0)
-    this.fr.unregister($query)
-    await this.scheduleDestroy($query[COLLECTION_NAME], $query[PARAMS], ownerKey)
+
+    if (count === 0) {
+      this.fr.unregister($query)
+      if (meta) {
+        const query = this.queries.get(transportHash)
+        this.removeOwnerMeta(ownerKey, transportHash)
+        detachQueryRoot(query, meta.rootId)
+        unregisterRootOwnedRuntime(meta.rootId, this.runtimeKind, transportHash)
+
+        const nextTransportCount = Math.max((this.transportSubCount.get(transportHash) || 0) - 1, 0)
+        if (nextTransportCount > 0) this.transportSubCount.set(transportHash, nextTransportCount)
+        else this.transportSubCount.set(transportHash, 0)
+      }
+    }
+
+    const destroyPromise = count === 0
+      ? this.scheduleDestroy($query[COLLECTION_NAME], $query[PARAMS], ownerKey)
+      : undefined
+
+    await this.reconcileTransport(transportHash)
+    if (count > 0) return
+    await destroyPromise
   }
 
   async destroy (collectionName, params, options = {}) {
@@ -367,9 +419,12 @@ export class QuerySubscriptions {
     }
     this.subCount.clear()
     this.transportSubCount.clear()
+    this.ownerFetchCount.clear()
+    this.ownerSubscribeCount.clear()
     this.ownerToTransport.clear()
     this.ownerMeta.clear()
     this.ownerKeysByTransport.clear()
+    this.transportTasks.clear()
   }
 
   async flushPendingDestroys () {
@@ -393,6 +448,8 @@ export class QuerySubscriptions {
     }
     const entry = createPendingDestroyEntry()
     if (options.force) entry.force = true
+    entry.collectionName = collectionName
+    entry.params = params
     entry.timer = setTimeout(() => {
       this.destroyByOwnerKey(fallbackOwnerKey, { collectionName, params, force: entry.force })
         .catch(ignoreDestroyError)
@@ -407,9 +464,80 @@ export class QuerySubscriptions {
     entry.resolve()
   }
 
+  async reconcileTransport (transportHash) {
+    const previous = this.transportTasks.get(transportHash) || Promise.resolve()
+    const next = previous
+      .catch(ignoreDestroyError)
+      .then(() => this.reconcileTransportNow(transportHash))
+    this.transportTasks.set(transportHash, next)
+    try {
+      await next
+    } finally {
+      if (this.transportTasks.get(transportHash) === next) this.transportTasks.delete(transportHash)
+    }
+  }
+
+  async reconcileTransportNow (transportHash) {
+    const query = this.queries.get(transportHash)
+    if (!query) return
+    while (true) {
+      const desiredMode = this.getDesiredTransportMode(transportHash)
+      const currentMode = query.activeTransportMode
+      if (desiredMode === currentMode) return
+      if (desiredMode === 'idle') {
+        if (currentMode === 'idle') return
+        await unsubscribeQueryTransport(query, { keepRoots: true })
+        continue
+      }
+      if (currentMode !== 'idle') {
+        await unsubscribeQueryTransport(query, { keepRoots: true })
+        continue
+      }
+      await subscribeQueryTransport(query, desiredMode)
+    }
+  }
+
+  getOwnerIntentCount (ownerKey, intent) {
+    const store = intent === 'fetch' ? this.ownerFetchCount : this.ownerSubscribeCount
+    return store.get(ownerKey) || 0
+  }
+
+  setOwnerIntentCount (ownerKey, intent, count) {
+    const store = intent === 'fetch' ? this.ownerFetchCount : this.ownerSubscribeCount
+    if (count > 0) store.set(ownerKey, count)
+    else store.delete(ownerKey)
+  }
+
+  incrementOwnerIntent (ownerKey, intent) {
+    this.setOwnerIntentCount(ownerKey, intent, this.getOwnerIntentCount(ownerKey, intent) + 1)
+  }
+
+  getDesiredTransportMode (transportHash) {
+    const ownerKeys = this.ownerKeysByTransport.get(transportHash)
+    if (!ownerKeys || ownerKeys.size === 0) return 'idle'
+    let hasFetchBackedOwner = false
+    for (const ownerKey of ownerKeys) {
+      const subscribeCount = this.ownerSubscribeCount.get(ownerKey) || 0
+      const fetchCount = this.ownerFetchCount.get(ownerKey) || 0
+      const rootId = this.ownerMeta.get(ownerKey)?.rootId
+      const subscribeMode = getRootTransportMode(rootId, 'subscribe')
+      if (subscribeCount > 0 && subscribeMode === 'subscribe') return 'subscribe'
+      if (fetchCount > 0 || (subscribeCount > 0 && subscribeMode === 'fetch')) {
+        hasFetchBackedOwner = true
+      }
+    }
+    return hasFetchBackedOwner ? 'fetch' : 'idle'
+  }
+
   async destroyByOwnerKey (ownerKey, options = {}) {
     const pendingDestroy = this.takePendingDestroy(ownerKey)
     if (pendingDestroy?.force) options.force = true
+    if (options.collectionName == null && pendingDestroy?.collectionName != null) {
+      options.collectionName = pendingDestroy.collectionName
+    }
+    if (options.params == null && pendingDestroy?.params != null) {
+      options.params = pendingDestroy.params
+    }
 
     const settlePending = err => {
       if (!pendingDestroy) return
@@ -425,43 +553,59 @@ export class QuerySubscriptions {
       }
       const meta = this.ownerMeta.get(ownerKey)
       if (!meta) {
+        const transportHash = options.collectionName && options.params
+          ? hashQuery(options.collectionName, options.params)
+          : this.ownerToTransport.get(ownerKey)
         this.subCount.delete(ownerKey)
+        this.ownerFetchCount.delete(ownerKey)
+        this.ownerSubscribeCount.delete(ownerKey)
+        this.ownerToTransport.delete(ownerKey)
+        if (!transportHash) {
+          settlePending()
+          return
+        }
+        const query = this.queries.get(transportHash)
+        await this.reconcileTransport(transportHash)
+        if ((this.transportSubCount.get(transportHash) || 0) <= 0) {
+          if (query?.activeTransportMode !== 'idle') await unsubscribeQueryTransport(query, { keepRoots: true })
+          query?._detachTransportData?.({ keepRoots: false })
+          this.transportSubCount.delete(transportHash)
+          this.ownerKeysByTransport.delete(transportHash)
+          this.queries.delete(transportHash)
+        }
         settlePending()
         return
       }
       const { transportHash, rootId } = meta
       const query = this.queries.get(transportHash)
-      if (!query) {
-        this.subCount.delete(ownerKey)
-        this.removeOwnerMeta(ownerKey, transportHash)
-        unregisterRootOwnedRuntime(rootId, this.runtimeKind, transportHash)
-        const nextTransportCount = Math.max((this.transportSubCount.get(transportHash) || 0) - 1, 0)
-        if (nextTransportCount > 0) this.transportSubCount.set(transportHash, nextTransportCount)
-        else this.transportSubCount.delete(transportHash)
-        settlePending()
-        return
-      }
+
       this.subCount.delete(ownerKey)
       this.removeOwnerMeta(ownerKey, transportHash)
       detachQueryRoot(query, rootId)
       unregisterRootOwnedRuntime(rootId, this.runtimeKind, transportHash)
 
       const nextTransportCount = Math.max((this.transportSubCount.get(transportHash) || 0) - 1, 0)
-      this.transportSubCount.set(transportHash, nextTransportCount)
-      if (nextTransportCount > 0) {
+      if (nextTransportCount > 0) this.transportSubCount.set(transportHash, nextTransportCount)
+      else this.transportSubCount.set(transportHash, 0)
+
+      await this.reconcileTransport(transportHash)
+      if ((this.transportSubCount.get(transportHash) || 0) > 0) {
         settlePending()
         return
       }
-      await query.unsubscribe()
-      if (query.subscribed) {
+      if (!query) {
+        this.transportSubCount.delete(transportHash)
         settlePending()
-        return // if we subscribed again while waiting for unsubscribe, we don't delete the query
+        return
       }
+      if (query.activeTransportMode !== 'idle') await unsubscribeQueryTransport(query, { keepRoots: true })
+      query._detachTransportData({ keepRoots: false })
       if ((this.transportSubCount.get(transportHash) || 0) > 0) {
         settlePending()
         return
       }
       this.transportSubCount.delete(transportHash)
+      this.ownerKeysByTransport.delete(transportHash)
       this.queries.delete(transportHash)
       settlePending()
     } catch (err) {
@@ -625,8 +769,45 @@ function createPendingDestroyEntry () {
   return {
     timer: undefined,
     force: false,
+    collectionName: undefined,
+    params: undefined,
     promise,
     resolve: resolvePending,
     reject: rejectPending
   }
 }
+
+async function subscribeQueryTransport (query, mode) {
+  query.requestedTransportMode = mode
+  if (typeof query._subscribe === 'function') {
+    query._subscribing = query._subscribe()
+      .then(() => {
+        query._subscribing = undefined
+        query.initialized = undefined
+        query.init?.()
+      }, err => {
+        query._subscribing = undefined
+        throw err
+      })
+    await query._subscribing
+    return
+  }
+  await query.subscribe({ mode })
+  if (query.activeTransportMode == null || query.activeTransportMode === 'idle') {
+    query.activeTransportMode = mode
+  }
+  if (query.initialized !== true) query.init?.()
+}
+
+async function unsubscribeQueryTransport (query, { keepRoots = true } = {}) {
+  if (query.initialized) {
+    query.initialized = undefined
+    query._detachTransportData?.({ keepRoots })
+  }
+  if (typeof query._unsubscribe === 'function') {
+    await query._unsubscribe()
+    return
+  }
+  await query.unsubscribe?.()
+  query.activeTransportMode = 'idle'
+}

package/orm/Root.js

@@ -1,6 +1,6 @@
 import getSignal from './getSignal.js'
 import disposeRootContext from './disposeRootContext.js'
-import { reviveRootContext } from './rootContext.js'
+import { getRootContext, reviveRootContext } from './rootContext.js'
 import { isGlobalRootId, normalizeRootId } from './rootScope.js'
 import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
 
@@ -22,11 +22,13 @@ const REGISTERED_ROOT_SIGNALS = new WeakSet()
 // TODO: create a separate local root for private collections
 export function getRootSignal ({
   rootFunction,
+  fetchOnly,
   // connection,
   rootId = '_' + createRandomString(8),
   ...options
 }) {
   reviveRootContext(rootId)
+  getRootContext(rootId, true, { fetchOnly })
   const $root = getSignal(undefined, [], {
     rootId,
     ...options
@@ -39,11 +41,28 @@ export function getRootSignal ({
 }
 
 export function getRoot (signal) {
+  if (!signal) return undefined
   if (signal[ROOT]) return signal[ROOT]
   else if (signal[ROOT_ID]) return signal
   else return undefined
 }
 
+export function getRootFetchOnly (rootOrRootId) {
+  const $root = typeof rootOrRootId === 'string'
+    ? undefined
+    : (getRoot(rootOrRootId) || rootOrRootId)
+  const rootId = typeof rootOrRootId === 'string'
+    ? rootOrRootId
+    : $root?.[ROOT_ID]
+  const context = getRootContext(rootId, false)
+  return context?.getFetchOnly() ?? false
+}
+
+export function getRootTransportMode (rootOrRootId, intent = 'subscribe') {
+  if (intent === 'fetch') return 'fetch'
+  return getRootFetchOnly(rootOrRootId) ? 'fetch' : 'subscribe'
+}
+
 export function registerRootFinalizer ($root) {
   if (!$root?.[ROOT_ID]) return
   if (REGISTERED_ROOT_SIGNALS.has($root)) return

package/orm/SignalBase.js

@@ -34,7 +34,7 @@ import { docSubscriptions } from './Doc.js'
 import { IS_QUERY, HASH, QUERIES } from './Query.js'
 import { AGGREGATIONS, IS_AGGREGATION, getAggregationCollectionName, getAggregationDocId } from './Aggregation.js'
 import { ROOT_FUNCTION, ROOT_ID, getRoot } from './Root.js'
-import { publicOnly } from './connection.js'
+import { isPrivateMutationForbidden } from './connection.js'
 import {
   DEFAULT_ID_FIELDS,
   getIdFieldsForSegments,
@@ -300,7 +300,7 @@ export class Signal extends Function {
     if (isPublicCollection(this[SEGMENTS][0])) {
       await _setPublicDoc(this[SEGMENTS], value)
     } else {
-      if (publicOnly) throw Error(ERRORS.publicOnly)
+      if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
       setPrivateData(getOwningRootId(this), this[SEGMENTS], value)
     }
   }
@@ -330,7 +330,7 @@ export class Signal extends Function {
     const idFields = getIdFieldsForSegments(segments)
     if (isIdFieldPath(segments, idFields)) return
     if (isPublicCollection(segments[0])) return _arrayPushPublic(segments, value)
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     return arrayPushPrivateData(getOwningRootId(this), segments, value)
   }
 
@@ -340,7 +340,7 @@ export class Signal extends Function {
     const idFields = getIdFieldsForSegments(segments)
     if (isIdFieldPath(segments, idFields)) return
     if (isPublicCollection(segments[0])) return _arrayPopPublic(segments)
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     return arrayPopPrivateData(getOwningRootId(this), segments)
   }
 
@@ -350,7 +350,7 @@ export class Signal extends Function {
     const idFields = getIdFieldsForSegments(segments)
     if (isIdFieldPath(segments, idFields)) return
     if (isPublicCollection(segments[0])) return _arrayUnshiftPublic(segments, value)
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     return arrayUnshiftPrivateData(getOwningRootId(this), segments, value)
   }
 
@@ -360,7 +360,7 @@ export class Signal extends Function {
     const idFields = getIdFieldsForSegments(segments)
     if (isIdFieldPath(segments, idFields)) return
     if (isPublicCollection(segments[0])) return _arrayShiftPublic(segments)
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     return arrayShiftPrivateData(getOwningRootId(this), segments)
   }
 
@@ -374,7 +374,7 @@ export class Signal extends Function {
     const idFields = getIdFieldsForSegments(segments)
     if (isIdFieldPath(segments, idFields)) return
     if (isPublicCollection(segments[0])) return _arrayInsertPublic(segments, index, values)
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     return arrayInsertPrivateData(getOwningRootId(this), segments, index, values)
   }
 
@@ -388,7 +388,7 @@ export class Signal extends Function {
     const idFields = getIdFieldsForSegments(segments)
     if (isIdFieldPath(segments, idFields)) return
     if (isPublicCollection(segments[0])) return _arrayRemovePublic(segments, index, howMany)
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     return arrayRemovePrivateData(getOwningRootId(this), segments, index, howMany)
   }
 
@@ -402,7 +402,7 @@ export class Signal extends Function {
     const idFields = getIdFieldsForSegments(segments)
     if (isIdFieldPath(segments, idFields)) return
     if (isPublicCollection(segments[0])) return _arrayMovePublic(segments, from, to, howMany)
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     return arrayMovePrivateData(getOwningRootId(this), segments, from, to, howMany)
   }
 
@@ -416,7 +416,7 @@ export class Signal extends Function {
     const idFields = getIdFieldsForSegments(segments)
     if (isIdFieldPath(segments, idFields)) return
     if (isPublicCollection(segments[0])) return _stringInsertPublic(segments, index, text)
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     return stringInsertPrivateData(getOwningRootId(this), segments, index, text)
   }
 
@@ -430,7 +430,7 @@ export class Signal extends Function {
     const idFields = getIdFieldsForSegments(segments)
     if (isIdFieldPath(segments, idFields)) return
     if (isPublicCollection(segments[0])) return _stringRemovePublic(segments, index, howMany)
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     return stringRemovePrivateData(getOwningRootId(this), segments, index, howMany)
   }
 
@@ -449,7 +449,7 @@ export class Signal extends Function {
       await _incrementPublic(segments, value)
       return currentValue + value
     }
-    if (publicOnly) throw Error(ERRORS.publicOnly)
+    if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
     setReplacePrivateData(getOwningRootId(this), segments, currentValue + value)
     return currentValue + value
   }
@@ -471,7 +471,7 @@ export class Signal extends Function {
       if (this[SEGMENTS].length === 1) throw Error('Can\'t delete the whole collection')
       await _setPublicDoc(this[SEGMENTS], undefined, true)
     } else {
-      if (publicOnly) throw Error(ERRORS.publicOnly)
+      if (isPrivateMutationForbidden()) throw Error(ERRORS.publicOnly)
       delPrivateData(getOwningRootId(this), this[SEGMENTS])
     }
   }

package/orm/connection.js

@@ -1,5 +1,7 @@
+import { isCompatEnv } from './compatEnv.js'
+
 export let connection
-export let fetchOnly
+let defaultFetchOnly
 export let publicOnly
 
 export function setConnection (_connection) {
@@ -11,14 +13,27 @@ export function getConnection () {
   return connection
 }
 
+export function setDefaultFetchOnly (_fetchOnly) {
+  defaultFetchOnly = !!_fetchOnly
+}
+
+export function getDefaultFetchOnly () {
+  return !!defaultFetchOnly
+}
+
+// Deprecated alias kept for internal transition.
 export function setFetchOnly (_fetchOnly) {
-  fetchOnly = _fetchOnly
+  setDefaultFetchOnly(_fetchOnly)
 }
 
 export function setPublicOnly (_publicOnly) {
   publicOnly = _publicOnly
 }
 
+export function isPrivateMutationForbidden () {
+  return !!publicOnly && !isCompatEnv()
+}
+
 const ERRORS = {
   notSet: `
     Connection is not set.

package/orm/rootContext.js

@@ -1,5 +1,6 @@
 import { observable } from '@nx-js/observer-util'
 import { normalizeRootId } from './rootScope.js'
+import { getDefaultFetchOnly } from './connection.js'
 
 const ROOT_CONTEXTS = new Map()
 const CLOSED_ROOT_CONTEXTS = new Set()
@@ -9,8 +10,9 @@ const RUNTIME_KIND_QUERY = 'query'
 const RUNTIME_KIND_AGGREGATION = 'aggregation'
 
 export default class RootContext {
-  constructor (rootId) {
+  constructor (rootId, { fetchOnly } = {}) {
     this.rootId = normalizeRootId(rootId)
+    this.fetchOnly = fetchOnly == null ? getDefaultFetchOnly() : !!fetchOnly
     this.privateDataRaw = {}
     this.privateData = observable(this.privateDataRaw)
     this.refLinks = new Map()
@@ -34,6 +36,14 @@ export default class RootContext {
     return store
   }
 
+  getFetchOnly () {
+    return !!this.fetchOnly
+  }
+
+  setFetchOnly (value) {
+    this.fetchOnly = !!value
+  }
+
   getPrivateDataRoot () {
     return this.privateData
   }
@@ -164,12 +174,12 @@ export default class RootContext {
   }
 }
 
-export function getRootContext (rootId, create = true) {
+export function getRootContext (rootId, create = true, options = {}) {
   const normalizedRootId = normalizeRootId(rootId)
   if (create && CLOSED_ROOT_CONTEXTS.has(normalizedRootId)) return undefined
   let context = ROOT_CONTEXTS.get(normalizedRootId)
   if (!context && create) {
-    context = new RootContext(normalizedRootId)
+    context = new RootContext(normalizedRootId, options)
     ROOT_CONTEXTS.set(normalizedRootId, context)
   }
   return context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.4.0-alpha.81",
+  "version": "0.4.0-alpha.83",
   "description": "Full-stack signals ORM with multiplayer",
   "type": "module",
   "main": "index.js",
@@ -83,5 +83,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "5e534aeafebd1147d3fb9939a3017a2a4a70a0b8"
+  "gitHead": "cf9710fd110129aafbfc8f0e7260ec3186795cb2"
 }

package/server.js

@@ -1,5 +1,5 @@
 import createChannel from '@teamplay/channel/server'
-import { connection, setConnection, setFetchOnly, setPublicOnly } from './orm/connection.js'
+import { connection, setConnection, setDefaultFetchOnly, setPublicOnly } from './orm/connection.js'
 
 export { default as ShareDB } from 'sharedb'
 export {
@@ -25,7 +25,7 @@ export function initConnection (backend, {
   if (!backend) throw Error('backend is required')
   if (connection) throw Error('Connection already exists')
   setConnection(backend.connect())
-  setFetchOnly(fetchOnly)
+  setDefaultFetchOnly(fetchOnly)
   setPublicOnly(publicOnly)
   return createChannel(backend, options)
 }