teamplay 0.4.0-alpha.2 → 0.4.0-alpha.21

package/orm/Compat/README.md

@@ -94,9 +94,11 @@ $.users.user1.name.parent(2)   // $.users
 Legacy path navigation. Accepts:
 - string with dot path (`'a.b.c'`)
 - integer index for arrays (`0`)
+- multiple path segments (`'a', 'b', 0`)
 
 ```js
 $.users.user1.at('profile.name')
+$.users.user1.at('profile', 'name')
 $.items.at(0)
 ```
 
@@ -106,6 +108,7 @@ Resolve a path from root, ignoring the current signal path.
 
 ```js
 $.users.user1.scope('users.user2')
+$.users.user1.scope('users', 'user2')
 ```
 
 ### ref(target) / ref(subpath, target)
@@ -228,20 +231,25 @@ await $$agg.subscribe()
 const rows = $$agg.getExtra()
 ```
 
-### get()
+### get(subpath?)
 
 Returns the current value and tracks reactivity.
 
 ```js
 const name = $.users.user1.name.get()
+$root.get('$render.url')
+$user.get('profile.name')
+$user.get('profile', 'name')
 ```
 
-### peek()
+### peek(subpath?)
 
 Returns the current value **without** tracking reactivity.
 
 ```js
 const name = $.users.user1.name.peek()
+$user.peek('profile.name')
+$user.peek('profile', 'name')
 ```
 
 ### getCopy(subpath)
@@ -669,10 +677,12 @@ This matches StartupJS and makes updates easy:
 $users[userId].name.set('New Name')
 ```
 
-`useQuery$` returns the collection signal as well:
+`useQuery$` returns the **query signal**:
 
 ```js
-const $users = useQuery$('users', { active: true })
+const $query = useQuery$('users', { active: true })
+const ids = $query.getIds()
+const docs = $query.get()
 ```
 
 If `query == null`, a warning is logged and `{ _id: '__NON_EXISTENT__' }` is used.
@@ -755,6 +765,8 @@ const Component = observer(() => {
 ```js
 const Component = observer(() => {
   const [users, $users] = useQuery('users', { active: true })
+  const $query = useQuery$('users', { active: true })
+  const ids = $query.getIds()
   return (
     <>
       {users.map(u => <div key={u._id}>{u.name}</div>)}

package/orm/Compat/SignalCompat.js

@@ -40,11 +40,16 @@ import {
 import { on as onCustomEvent, removeListener as removeCustomEventListener } from './eventsCompat.js'
 import { normalizePattern, onModelEvent, removeModelListener } from './modelEvents.js'
 import { setRefLink, removeRefLink } from './refRegistry.js'
+import { REF_TARGET, resolveRefSignalSafe } from './refFallback.js'
 
 class SignalCompat extends Signal {
   static ID_FIELDS = ['_id', 'id']
   static [GETTERS] = [...DEFAULT_GETTERS, 'getCopy', 'getDeepCopy']
 
+  get root () {
+    return this.scope()
+  }
+
   path (subpath) {
     if (arguments.length > 1) throw Error('Signal.path() expects a single argument')
     if (arguments.length === 0) return super.path()
@@ -54,8 +59,9 @@ class SignalCompat extends Signal {
   }
 
   at (subpath) {
-    if (arguments.length > 1) throw Error('Signal.at() expects a single argument')
-    const segments = parseAtSubpath(subpath, arguments.length, 'Signal.at()')
+    const segments = arguments.length > 1
+      ? parseAtSegments(arguments, 'Signal.at()')
+      : parseAtSubpath(subpath, arguments.length, 'Signal.at()')
     if (segments.length === 0) return this
     let $cursor = this
     for (const segment of segments) {
@@ -118,12 +124,46 @@ class SignalCompat extends Signal {
   }
 
   get () {
+    if (arguments.length > 1) {
+      const segments = parseAtSegments(arguments, 'Signal.get()')
+      const $base = resolveRefSignal(this)
+      const $target = resolveSignal($base, segments)
+      return Signal.prototype.get.call($target)
+    }
+    if (arguments.length === 1) {
+      if (arguments[0] == null) {
+        const $target = resolveRefSignal(this)
+        if ($target !== this) return Signal.prototype.get.apply($target, [])
+        return Signal.prototype.get.apply(this, [])
+      }
+      const segments = parseAtSubpath(arguments[0], 1, 'Signal.get()')
+      const $base = resolveRefSignal(this)
+      const $target = resolveSignal($base, segments)
+      return Signal.prototype.get.call($target)
+    }
     const $target = resolveRefSignal(this)
     if ($target !== this) return Signal.prototype.get.apply($target, arguments)
     return Signal.prototype.get.apply(this, arguments)
   }
 
   peek () {
+    if (arguments.length > 1) {
+      const segments = parseAtSegments(arguments, 'Signal.peek()')
+      const $base = resolveRefSignal(this)
+      const $target = resolveSignal($base, segments)
+      return Signal.prototype.peek.call($target)
+    }
+    if (arguments.length === 1) {
+      if (arguments[0] == null) {
+        const $target = resolveRefSignal(this)
+        if ($target !== this) return Signal.prototype.peek.apply($target, [])
+        return Signal.prototype.peek.apply(this, [])
+      }
+      const segments = parseAtSubpath(arguments[0], 1, 'Signal.peek()')
+      const $base = resolveRefSignal(this)
+      const $target = resolveSignal($base, segments)
+      return Signal.prototype.peek.call($target)
+    }
     const $target = resolveRefSignal(this)
     if ($target !== this) return Signal.prototype.peek.apply($target, arguments)
     return Signal.prototype.peek.apply(this, arguments)
@@ -143,6 +183,22 @@ class SignalCompat extends Signal {
     return Signal.prototype.set.call($target, value)
   }
 
+  async add (collectionOrValue, value) {
+    const isRoot = this[SEGMENTS].length === 0
+    const isRootCollectionCall = isRoot && typeof collectionOrValue === 'string'
+
+    if (isRootCollectionCall) {
+      if (arguments.length !== 2) throw Error('Signal.add() expects (collection, object)')
+      if (!value || typeof value !== 'object') throw Error('Signal.add() expects an object argument')
+      const $root = getRoot(this) || this
+      const $collection = resolveSignal($root, [collectionOrValue])
+      return $collection.add(value)
+    }
+
+    if (arguments.length > 1) throw Error('Signal.add() expects a single argument')
+    return Signal.prototype.add.call(this, collectionOrValue)
+  }
+
   async setNull (path, value) {
     const forwarded = forwardRef(this, 'setNull', arguments)
     if (forwarded) return forwarded
@@ -495,11 +551,11 @@ class SignalCompat extends Signal {
   }
 
   scope (path) {
-    if (arguments.length > 1) throw Error('Signal.scope() expects a single argument')
     const $root = getRoot(this) || this
     if (arguments.length === 0) return $root
-    if (typeof path !== 'string') throw Error('Signal.scope() expects a string argument')
-    const segments = path.split('.').filter(Boolean)
+    const segments = arguments.length > 1
+      ? parseAtSegments(arguments, 'Signal.scope()')
+      : parseAtSubpath(path, arguments.length, 'Signal.scope()')
     if (segments.length === 0) return $root
     let $cursor = $root
     for (const segment of segments) {
@@ -510,7 +566,6 @@ class SignalCompat extends Signal {
 }
 
 const REFS = Symbol('compat refs')
-const REF_TARGET = Symbol('compat ref target')
 
 function getRefStore ($signal) {
   const $root = getRoot($signal) || $signal
@@ -545,14 +600,7 @@ function trackDeep (value, seen = new Set()) {
 }
 
 function resolveRefSignal ($signal) {
-  let current = $signal
-  const seen = new Set()
-  while (current && current[REF_TARGET]) {
-    if (seen.has(current)) break
-    seen.add(current)
-    current = current[REF_TARGET]
-  }
-  return current
+  return resolveRefSignalSafe($signal) || $signal
 }
 
 function forwardRef ($signal, methodName, args) {
@@ -586,6 +634,23 @@ function parseAtSubpath (subpath, argsLength, methodName) {
   throw Error(`${methodName} expects a string or integer argument`)
 }
 
+function parseAtSegments (args, methodName) {
+  const segments = []
+  for (const arg of Array.from(args)) {
+    if (typeof arg === 'string') {
+      const parts = arg.split('.').filter(Boolean)
+      segments.push(...parts)
+      continue
+    }
+    if (typeof arg === 'number' && Number.isFinite(arg) && Number.isInteger(arg)) {
+      segments.push(arg)
+      continue
+    }
+    throw Error(`${methodName} expects string or integer path segments`)
+  }
+  return segments
+}
+
 function resolveSignal ($signal, segments) {
   let $cursor = $signal
   for (const segment of segments) {

package/orm/Compat/hooksCompat.js

@@ -1,6 +1,7 @@
 import { getRootSignal, GLOBAL_ROOT_ID } from '../Root.js'
 import useSub, { useAsyncSub } from '../../react/useSub.js'
 import universal$ from '../../react/universal$.js'
+import * as promiseBatcher from '../../react/promiseBatcher.js'
 
 const $root = getRootSignal({ rootId: GLOBAL_ROOT_ID, rootFunction: universal$ })
 
@@ -72,8 +73,10 @@ export function usePage (path) {
   return useLocal(prefixLocalPath('_page', path))
 }
 
-// Placeholder for startupjs batching API. No-op in teamplay.
-export function useBatch () {}
+export function useBatch () {
+  const promise = promiseBatcher.getPromiseAll()
+  if (promise) throw promise
+}
 
 export function useDoc$ (collection, id, options) {
   const $doc = getDocSignal(collection, id, 'useDoc')
@@ -86,13 +89,15 @@ export function useDoc (collection, id, options) {
   return [$doc.get(), $doc]
 }
 
-// Batch variants are aliases to non-batch versions (no batching in teamplay).
 export function useBatchDoc (collection, id, options) {
-  return useDoc(collection, id, options)
+  const $doc = useBatchDoc$(collection, id, options)
+  if (!$doc) return [undefined, undefined]
+  return [$doc.get(), $doc]
 }
 
-export function useBatchDoc$ (collection, id, options) {
-  return useDoc$(collection, id, options)
+export function useBatchDoc$ (collection, id, _options) {
+  const $doc = getDocSignal(collection, id, 'useBatchDoc')
+  return useSub($doc, undefined, { async: false, batch: true })
 }
 
 export function useAsyncDoc$ (collection, id, options) {
@@ -109,8 +114,8 @@ export function useAsyncDoc (collection, id, options) {
 export function useQuery$ (collection, query, options) {
   const $collection = getCollectionSignal(collection, query, 'useQuery')
   const normalizedOptions = options ? { ...options, async: false } : options
-  useSub($collection, normalizeQuery(query, 'useQuery'), normalizedOptions)
-  return $collection
+  const $query = useSub($collection, normalizeQuery(query, 'useQuery'), normalizedOptions)
+  return $query
 }
 
 export function useQuery (collection, query, options) {
@@ -122,8 +127,8 @@ export function useQuery (collection, query, options) {
 
 export function useAsyncQuery$ (collection, query, options) {
   const $collection = getCollectionSignal(collection, query, 'useAsyncQuery')
-  useAsyncSub($collection, normalizeQuery(query, 'useAsyncQuery'), options)
-  return $collection
+  const $query = useAsyncSub($collection, normalizeQuery(query, 'useAsyncQuery'), options)
+  return $query
 }
 
 export function useAsyncQuery (collection, query, options) {
@@ -133,13 +138,16 @@ export function useAsyncQuery (collection, query, options) {
   return [$query.get(), $collection]
 }
 
-// Batch variants are aliases to non-batch versions (no batching in teamplay).
-export function useBatchQuery$ (collection, query, options) {
-  return useQuery$(collection, query, options)
+export function useBatchQuery$ (collection, query, _options) {
+  const $collection = getCollectionSignal(collection, query, 'useBatchQuery')
+  return useSub($collection, normalizeQuery(query, 'useBatchQuery'), { async: false, batch: true })
 }
 
 export function useBatchQuery (collection, query, options) {
-  return useQuery(collection, query, options)
+  const $collection = getCollectionSignal(collection, query, 'useBatchQuery')
+  const $query = useBatchQuery$(collection, query, options)
+  if (!$query) return [undefined, $collection]
+  return [$query.get(), $collection]
 }
 
 export function useQueryIds (collection, ids = [], options = {}) {
@@ -157,7 +165,17 @@ export function useQueryIds (collection, ids = [], options = {}) {
 }
 
 export function useBatchQueryIds (collection, ids = [], options = {}) {
-  return useQueryIds(collection, ids, options)
+  const list = Array.isArray(ids) ? ids.slice() : []
+  if (options?.reverse) list.reverse()
+  const [docs, $collection] = useBatchQuery(collection, { _id: { $in: list } }, options)
+  if (!docs) return [docs, $collection]
+  const docsById = new Map()
+  for (const doc of docs) {
+    const id = doc?._id ?? doc?.id
+    if (id != null) docsById.set(id, doc)
+  }
+  const items = list.map(id => docsById.get(id)).filter(Boolean)
+  return [items, $collection]
 }
 
 export function useAsyncQueryIds (collection, ids = [], options = {}) {
@@ -194,11 +212,23 @@ export function useQueryDoc$ (collection, query, options) {
 }
 
 export function useBatchQueryDoc (collection, query, options) {
-  return useQueryDoc(collection, query, options)
+  const normalized = normalizeQuery(query, 'useBatchQueryDoc')
+  const queryDoc = {
+    ...normalized,
+    $limit: 1,
+    $sort: normalized.$sort || { createdAt: -1 }
+  }
+  const [docs, $collection] = useBatchQuery(collection, queryDoc, options)
+  if (!docs) return [undefined, undefined]
+  const doc = docs && docs[0]
+  const docId = doc?._id ?? doc?.id
+  const $doc = docId != null ? $collection[docId] : undefined
+  return [doc, $doc]
 }
 
 export function useBatchQueryDoc$ (collection, query, options) {
-  return useQueryDoc$(collection, query, options)
+  const [, $doc] = useBatchQueryDoc(collection, query, options)
+  return $doc
 }
 
 export function useAsyncQueryDoc (collection, query, options) {

package/orm/Compat/modelEvents.js

@@ -1,4 +1,5 @@
 import { getRefLinks } from './refRegistry.js'
+import { isCompatEnv } from '../compatEnv.js'
 
 const modelListeners = {
   change: new Map(),
@@ -6,10 +7,7 @@ const modelListeners = {
 }
 
 export function isModelEventsEnabled () {
-  return (
-    globalThis?.teamplayCompatibilityMode ??
-    (typeof process !== 'undefined' && process?.env?.TEAMPLAY_COMPAT === '1')
-  )
+  return isCompatEnv()
 }
 
 export function normalizePattern (pattern, methodName) {

package/orm/Compat/refFallback.js

@@ -0,0 +1,60 @@
+import { getRefLinks } from './refRegistry.js'
+
+export const REF_TARGET = Symbol.for('teamplay.compat.refTarget')
+
+export function resolveRefSignalSafe ($signal, maxDepth = 32) {
+  let current = $signal
+  const seen = new Set()
+  for (let i = 0; i < maxDepth; i++) {
+    if (!current) return undefined
+    const next = current[REF_TARGET]
+    if (!next) return current
+    if (seen.has(current)) return undefined
+    seen.add(current)
+    current = next
+  }
+  return undefined
+}
+
+export function resolveRefSegmentsSafe (segments, maxDepth = 32) {
+  if (!Array.isArray(segments) || segments.length === 0) return undefined
+  let current = [...segments]
+  const visited = new Set([toPathKey(current)])
+  let changed = false
+
+  for (let i = 0; i < maxDepth; i++) {
+    const link = findBestMatchingLink(current)
+    if (!link) return changed ? current : undefined
+    const suffix = current.slice(link.fromSegments.length)
+    const next = link.toSegments.concat(suffix)
+    const key = toPathKey(next)
+    if (visited.has(key)) return undefined
+    visited.add(key)
+    current = next
+    changed = true
+  }
+  return undefined
+}
+
+function findBestMatchingLink (segments) {
+  let best
+  for (const link of getRefLinks().values()) {
+    if (!isPathPrefix(link.fromSegments, segments)) continue
+    if (!best || link.fromSegments.length > best.fromSegments.length) {
+      best = link
+    }
+  }
+  return best
+}
+
+function isPathPrefix (prefixSegments, fullSegments) {
+  if (prefixSegments.length > fullSegments.length) return false
+  for (let i = 0; i < prefixSegments.length; i++) {
+    if (prefixSegments[i] !== String(fullSegments[i])) return false
+  }
+  return true
+}
+
+function toPathKey (segments) {
+  return segments.map(segment => String(segment)).join('.')
+}

package/orm/Doc.js

@@ -1,4 +1,4 @@
-import { isObservable, observable } from '@nx-js/observer-util'
+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'
@@ -90,9 +90,12 @@ class Doc {
     if (doc.data == null) return
     const idFields = getIdFieldsForSegments([this.collection, this.docId])
     if (isPlainObject(doc.data)) injectIdFields(doc.data, idFields, this.docId)
-    if (isObservable(doc.data)) return
-    _set([this.collection, this.docId], doc.data)
-    doc.data = observable(doc.data)
+    const hasRaw = _getRaw([this.collection, this.docId]) != null
+    if (!hasRaw) {
+      const data = isObservable(doc.data) ? raw(doc.data) : doc.data
+      _set([this.collection, this.docId], data)
+    }
+    if (!isObservable(doc.data)) doc.data = observable(doc.data)
   }
 
   _removeData () {

package/orm/Query.js

@@ -1,8 +1,9 @@
 import { raw } from '@nx-js/observer-util'
-import { get as _get, set as _set, del as _del } from './dataTree.js'
+import { get as _get, set as _set, del as _del, getRaw } from './dataTree.js'
 import getSignal from './getSignal.js'
 import { getConnection, fetchOnly } from './connection.js'
 import { emitModelChange, isModelEventsEnabled } from './Compat/modelEvents.js'
+import { isCompatEnv } from './compatEnv.js'
 import { docSubscriptions } from './Doc.js'
 import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
 import SubscriptionState from './SubscriptionState.js'
@@ -76,6 +77,7 @@ export class Query {
 
   _initData () {
     { // reference the fetched docs
+      maybeMaterializeQueryDocsToCollection(this.collectionName, this.shareQuery.results)
       const docs = this.shareQuery.results.map(doc => {
         const idFields = getIdFieldsForSegments([this.collectionName, doc.id])
         if (isPlainObject(doc.data)) injectIdFields(doc.data, idFields, doc.id)
@@ -98,6 +100,7 @@ export class Query {
     }
 
     this.shareQuery.on('insert', (shareDocs, index) => {
+      maybeMaterializeQueryDocsToCollection(this.collectionName, shareDocs)
       const newDocs = shareDocs.map(doc => {
         const idFields = getIdFieldsForSegments([this.collectionName, doc.id])
         if (isPlainObject(doc.data)) injectIdFields(doc.data, idFields, doc.id)
@@ -218,7 +221,13 @@ 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) {
+      const existingQuery = this.queries.get(hash)
+      if (existingQuery) return existingQuery._subscribing
+      // Recover from stale ref-count state when query was already cleaned up.
+      count = 1
+      this.subCount.set(hash, count)
+    }
 
     this.fr.register($query, { collectionName, params }, $query)
 
@@ -246,6 +255,7 @@ export class QuerySubscriptions {
     this.subCount.delete(hash)
     this.fr.unregister($query)
     const query = this.queries.get(hash)
+    if (!query) return
     await query.unsubscribe()
     if (query.subscribed) return // if we subscribed again while waiting for unsubscribe, we don't delete the doc
     this.queries.delete(hash)
@@ -264,6 +274,18 @@ export class QuerySubscriptions {
 
 export const querySubscriptions = new QuerySubscriptions()
 
+function maybeMaterializeQueryDocsToCollection (collectionName, shareDocs) {
+  if (!isCompatEnv()) return
+  for (const doc of shareDocs) {
+    if (!doc?.id || doc.data == null) continue
+    const existing = getRaw([collectionName, doc.id])
+    if (existing != null) continue
+    const idFields = getIdFieldsForSegments([collectionName, doc.id])
+    if (isPlainObject(doc.data)) injectIdFields(doc.data, idFields, doc.id)
+    _set([collectionName, doc.id], raw(doc.data))
+  }
+}
+
 export function hashQuery (collectionName, params) {
   // TODO: probably makes sense to use fast-stable-json-stringify for this because of the params
   return JSON.stringify({ query: [collectionName, params] })

package/orm/Signal.js

@@ -1,5 +1,6 @@
 import { Signal } from './SignalBase.js'
 import SignalCompat from './Compat/SignalCompat.js'
+import { isCompatEnv } from './compatEnv.js'
 
 export {
   Signal,
@@ -18,8 +19,4 @@ export {
 
 export { SignalCompat }
 
-const compatEnv =
-  globalThis?.teamplayCompatibilityMode ??
-  (typeof process !== 'undefined' && process?.env?.TEAMPLAY_COMPAT === '1')
-
-export default compatEnv ? SignalCompat : Signal
+export default isCompatEnv() ? SignalCompat : Signal

package/orm/SignalBase.js

@@ -46,6 +46,8 @@ import { AGGREGATIONS, IS_AGGREGATION, getAggregationCollectionName, getAggregat
 import { ROOT_FUNCTION, getRoot } from './Root.js'
 import { publicOnly } from './connection.js'
 import { DEFAULT_ID_FIELDS, getIdFieldsForSegments, isIdFieldPath, normalizeIdFields } from './idFields.js'
+import { isCompatEnv } from './compatEnv.js'
+import { resolveRefSegmentsSafe, resolveRefSignalSafe } from './Compat/refFallback.js'
 
 export const SEGMENTS = Symbol('path segments targeting the particular node in the data tree')
 export const ARRAY_METHOD = Symbol('run array method on the signal')
@@ -501,8 +503,28 @@ export const extremelyLateBindings = {
     }
     const $parent = getSignal(getRoot(signal), segments)
     const rawParent = rawSignal($parent)
-    if (!(key in rawParent)) throw Error(ERRORS.noSignalKey($parent, key))
-    return Reflect.apply(rawParent[key], $parent, argumentsList)
+    if (key in rawParent) return Reflect.apply(rawParent[key], $parent, argumentsList)
+
+    if (isCompatEnv()) {
+      const $resolvedParent = resolveRefSignalSafe($parent)
+      if ($resolvedParent && $resolvedParent !== $parent) {
+        const rawResolvedParent = rawSignal($resolvedParent)
+        if (rawResolvedParent && key in rawResolvedParent) {
+          return Reflect.apply(rawResolvedParent[key], $resolvedParent, argumentsList)
+        }
+      } else {
+        const resolvedSegments = resolveRefSegmentsSafe(segments)
+        if (resolvedSegments) {
+          const $resolvedByPath = getSignal(getRoot(signal), resolvedSegments)
+          const rawResolvedByPath = rawSignal($resolvedByPath)
+          if (rawResolvedByPath && key in rawResolvedByPath) {
+            return Reflect.apply(rawResolvedByPath[key], $resolvedByPath, argumentsList)
+          }
+        }
+      }
+    }
+
+    throw Error(ERRORS.noSignalKey($parent, key))
   },
   get (signal, key, receiver) {
     if (typeof key === 'symbol') return Reflect.get(signal, key, receiver)

package/orm/compatEnv.js

@@ -0,0 +1,4 @@
+export function isCompatEnv () {
+  return globalThis?.teamplayCompatibilityMode ??
+    (typeof process !== 'undefined' && process?.env?.TEAMPLAY_COMPAT === '1')
+}

package/orm/dataTree.js

@@ -186,7 +186,12 @@ export async function setPublicDoc (segments, value, deleteValue = false) {
     })
   } else {
     // > modify existing doc. Partial doc modification
-    const oldDoc = getRaw([collection, docId])
+    let oldDoc = getRaw([collection, docId])
+    if (oldDoc == null) {
+      const docData = getConnection().get(collection, docId).data
+      oldDoc = docData == null ? {} : raw(docData)
+      if (docData != null) set([collection, docId], oldDoc)
+    }
     const newDoc = JSON.parse(JSON.stringify(oldDoc))
     if (deleteValue) {
       del(segments.slice(2), newDoc)

package/orm/getSignal.js

@@ -1,10 +1,13 @@
 import Cache from './Cache.js'
-import Signal, { regularBindings, extremelyLateBindings, isPublicCollection, isPrivateCollection } from './Signal.js'
+import Signal, { SEGMENTS, regularBindings, extremelyLateBindings, isPublicCollection, isPrivateCollection } from './Signal.js'
 import { findModel } from './addModel.js'
 import { LOCAL } from './$.js'
 import { ROOT, ROOT_ID, GLOBAL_ROOT_ID } from './Root.js'
 import { QUERIES } from './Query.js'
 import { AGGREGATIONS } from './Aggregation.js'
+import { isCompatEnv } from './compatEnv.js'
+import { getConnection } from './connection.js'
+import { resolveRefSegmentsSafe } from './Compat/refFallback.js'
 
 const PROXIES_CACHE = new Cache()
 const PROXY_TO_SIGNAL = new WeakMap()
@@ -48,6 +51,9 @@ export default function getSignal ($root, segments = [], {
       //       but without it calling the methods of root signal like $.get() doesn't work
       proxy[ROOT] = $root || getSignal(undefined, [], { rootId: GLOBAL_ROOT_ID })
     }
+    signal[ROOT] = proxy[ROOT]
+  } else {
+    signal[ROOT] = proxy
   }
   PROXY_TO_SIGNAL.set(proxy, signal)
   const dependencies = []
@@ -69,7 +75,22 @@ export default function getSignal ($root, segments = [], {
 }
 
 function getDefaultProxyHandlers ({ useExtremelyLateBindings } = {}) {
-  return useExtremelyLateBindings ? extremelyLateBindings : regularBindings
+  const baseHandlers = useExtremelyLateBindings ? extremelyLateBindings : regularBindings
+  if (!isCompatEnv() || baseHandlers !== extremelyLateBindings) return baseHandlers
+  return {
+    ...baseHandlers,
+    get (signal, key, receiver) {
+      if (key === 'connection' && signal[SEGMENTS].length === 0) {
+        try {
+          return getConnection()
+        } catch {
+          return undefined
+        }
+      }
+      if (key === 'root') return Reflect.get(signal, key, receiver)
+      return baseHandlers.get(signal, key, receiver)
+    }
+  }
 }
 
 function hashSegments (segments, rootId) {
@@ -85,7 +106,15 @@ function hashSegments (segments, rootId) {
 }
 
 export function getSignalClass (segments) {
-  return findModel(segments) ?? Signal
+  let Model = findModel(segments)
+  if (Model) return Model
+  if (!isCompatEnv()) return Signal
+  const dereferencedSegments = resolveRefSegmentsSafe(segments)
+  if (dereferencedSegments) {
+    Model = findModel(dereferencedSegments)
+    if (Model) return Model
+  }
+  return Signal
 }
 
 export function rawSignal (proxy) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.4.0-alpha.2",
+  "version": "0.4.0-alpha.21",
   "description": "Full-stack signals ORM with multiplayer",
   "type": "module",
   "main": "index.js",
@@ -34,12 +34,12 @@
   "dependencies": {
     "@nx-js/observer-util": "^4.1.3",
     "@startupjs/sharedb-mingo-memory": "^4.0.0-2",
-    "@teamplay/backend": "^0.4.0-alpha.1",
-    "@teamplay/cache": "^0.4.0-alpha.1",
-    "@teamplay/channel": "^0.4.0-alpha.1",
-    "@teamplay/debug": "^0.4.0-alpha.1",
-    "@teamplay/schema": "^0.4.0-alpha.1",
-    "@teamplay/utils": "^0.4.0-alpha.1",
+    "@teamplay/backend": "^0.4.0-alpha.9",
+    "@teamplay/cache": "^0.4.0-alpha.9",
+    "@teamplay/channel": "^0.4.0-alpha.9",
+    "@teamplay/debug": "^0.4.0-alpha.9",
+    "@teamplay/schema": "^0.4.0-alpha.9",
+    "@teamplay/utils": "^0.4.0-alpha.9",
     "diff-match-patch": "^1.0.5",
     "events": "^3.3.0",
     "json0-ot-diff": "^1.1.2",
@@ -81,5 +81,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "ad790a31ac628c9ea5ac851572533620ac0b7602"
+  "gitHead": "5b440dc6e2e114f2cfaac81d4757b710f153ff5d"
 }

package/react/promiseBatcher.js

@@ -0,0 +1,27 @@
+let active = false
+let promises = []
+
+export function activate () {
+  active = true
+}
+
+export function add (promise) {
+  if (!promise || typeof promise.then !== 'function') return
+  promises.push(promise)
+}
+
+export function getPromiseAll () {
+  const hasPromises = promises.length > 0
+  const result = hasPromises ? Promise.all(promises) : null
+  reset()
+  return result
+}
+
+export function isActive () {
+  return active
+}
+
+export function reset () {
+  active = false
+  promises = []
+}

package/react/trapRender.js

@@ -1,6 +1,7 @@
 // trap render function (functional component) to block observer updates and activate cache
 // during synchronous rendering
 import executionContextTracker from './executionContextTracker.js'
+import * as promiseBatcher from './promiseBatcher.js'
 
 export default function trapRender ({ render, cache, destroy, componentId }) {
   return (...args) => {
@@ -9,13 +10,14 @@ export default function trapRender ({ render, cache, destroy, componentId }) {
     let destroyed
     try {
       // destroyer.reset() // TODO: this one is for any destructuring logic which might be needed
-      // promiseBatcher.reset() // TODO: this is to support useBatch* hooks
+      promiseBatcher.reset()
       const res = render(...args)
-      // if (promiseBatcher.isActive()) {
-      //   throw Error('[react-sharedb] useBatch* hooks were used without a closing useBatch() call.')
-      // }
+      if (isDevMode() && promiseBatcher.isActive()) {
+        throw Error('[teamplay] useBatch* hooks were used without a closing useBatch() call.')
+      }
       return res
     } catch (err) {
+      promiseBatcher.reset()
       // TODO: this might only be needed only if promise is thrown
       //       (check if useUnmount in convertToObserver is called if a regular error is thrown)
       destroy('trapRender.js')
@@ -37,3 +39,8 @@ export default function trapRender ({ render, cache, destroy, componentId }) {
     }
   }
 }
+
+function isDevMode () {
+  if (typeof process === 'undefined' || !process?.env) return true
+  return process.env.NODE_ENV !== 'production'
+}

package/react/useSub.js

@@ -2,6 +2,7 @@ import { useRef, useDeferredValue } from 'react'
 import sub from '../orm/sub.js'
 import { useScheduleUpdate, useCache, useDefer } from './helpers.js'
 import executionContextTracker from './executionContextTracker.js'
+import * as promiseBatcher from './promiseBatcher.js'
 
 let TEST_THROTTLING = false
 
@@ -24,10 +25,11 @@ export default function useSub (signal, params, options) {
 }
 
 // version of sub() which works as a react hook and throws promise for Suspense
-export function useSubDeferred (signal, params, { async = false, defer } = {}) {
+export function useSubDeferred (signal, params, { async = false, defer, batch = false } = {}) {
   const $signalRef = useRef() // eslint-disable-line react-hooks/rules-of-hooks
   const scheduleUpdate = useScheduleUpdate()
   const observerDefer = useDefer()
+  if (batch) promiseBatcher.activate()
   defer ??= observerDefer ?? DEFAULT_DEFER
   if (defer) {
     signal = useDeferredValue(signal) // eslint-disable-line react-hooks/rules-of-hooks
@@ -38,6 +40,11 @@ export function useSubDeferred (signal, params, { async = false, defer } = {}) {
   // 1. if it's a promise, throw it so that Suspense can catch it and wait for subscription to finish
   if (promiseOrSignal.then) {
     const promise = maybeThrottle(promiseOrSignal)
+    if (batch) {
+      promiseBatcher.add(promise)
+      if (async) scheduleUpdate(promise)
+      return $signalRef.current
+    }
     if (async) {
       scheduleUpdate(promise)
       return
@@ -53,15 +60,22 @@ export function useSubDeferred (signal, params, { async = false, defer } = {}) {
 
 // classic version which initially throws promise for Suspense
 // but if we get a promise second time, we return the last signal and wait for promise to resolve
-export function useSubClassic (signal, params, { async = false } = {}) {
+export function useSubClassic (signal, params, { async = false, batch = false } = {}) {
   const id = executionContextTracker.newHookId()
   const cache = useCache()
   const activePromiseRef = useRef()
   const scheduleUpdate = useScheduleUpdate()
+  if (batch) promiseBatcher.activate()
   const promiseOrSignal = params != null ? sub(signal, params) : sub(signal)
   // 1. if it's a promise, throw it so that Suspense can catch it and wait for subscription to finish
   if (promiseOrSignal.then) {
     const promise = maybeThrottle(promiseOrSignal)
+    if (batch) {
+      promiseBatcher.add(promise)
+      if (async) scheduleUpdate(promise)
+      if (cache.has(id)) return cache.get(id)
+      return
+    }
     // first time we just throw the promise to be caught by Suspense
     if (!cache.has(id)) {
       // if we are in async mode, we just return nothing and let the user

package/react/wrapIntoSuspense.js

@@ -52,7 +52,7 @@ export default function wrapIntoSuspense ({
           // to avoid updating during the subscribe/render phase
           if (adm.hasPendingUpdate) {
             adm.hasPendingUpdate = false
-            queueMicrotask(() => adm.onStoreChange())
+            queueMicrotask(() => adm.onStoreChange?.())
           }
           return () => destroyAdm(adm)
         },

package/utils/setDiffDeep.js

@@ -1,5 +1,9 @@
 import isPlainObject from 'lodash/isPlainObject.js'
 
+function isReactLike (value) {
+  return !!(value && typeof value === 'object' && typeof value.$$typeof === 'symbol')
+}
+
 export default function setDiffDeep (existing, updated) {
   // Handle primitive types, null, and type mismatches
   if (existing === null || updated === null ||
@@ -21,6 +25,9 @@ export default function setDiffDeep (existing, updated) {
     return existing
   }
 
+  // React elements are plain objects but must be treated as non-plain
+  if (isReactLike(updated)) return updated
+
   // Handle non-plain objects - just return them as-is to fully overwrite
   // and don't try to update an old object in-place
   if (!isPlainObject(updated)) return updated

package/orm/Compat/REF.md

@@ -1,315 +0,0 @@
-# SignalCompat `ref` / `removeRef` — Compatibility Draft
-
-This document captures a **draft** implementation of StartupJS/Racer-style `ref` behavior for Teamplay’s `SignalCompat`.
-
-It is **not active in code** right now. The goal is to discuss and decide whether we want to bring it back, and in what form.
-
----
-
-## 1) Why we need this
-
-In LMS there are a few **real usages** of model refs (not React DOM refs):
-
-- `components/Media/index.js`
-  ```js
-  if ($fullscreen) $localFullscreen.ref($fullscreen)
-  ```
-- `main/components/FilterV2/index.js`
-  ```js
-  if (!isMultiSelect) $localValue.ref($value)
-  ```
-- `main/Layout/Tutoring/index.js` and `v5/apps/main/Layout/Tutoring/index.js`
-  ```js
-  $session.ref('tutoringSession', $tutoringSession)
-  $session.removeRef('tutoringSession')
-  ```
-
-These use the **Racer model ref**, which effectively makes one path behave like another path (alias). Teamplay doesn’t have this concept, so we explored a minimal compat layer.
-
----
-
-## 2) Target API (minimal subset)
-
-We only target what LMS actually uses:
-
-### `ref(target)`
-
-```js
-$local.ref($.users.user1)
-```
-
-This means `$local` mirrors `$users.user1` and mutating `$local` mutates `$users.user1`.
-
-### `ref(subpath, target)`
-
-```js
-$session.ref('tutoringSession', $tutoringSession)
-```
-
-This means `$session.tutoringSession` acts as an alias to `$tutoringSession`.
-
-### `removeRef(path?)`
-
-```js
-$local.removeRef()
-$session.removeRef('tutoringSession')
-```
-
-Stops syncing.
-
----
-
-## 3) Semantics vs Racer
-
-Racer refs are deep and complicated (they respond to all model events, including array insert/remove/move, etc).
-
-This draft **only covers**:
-- Signal-level aliasing (one signal proxies another).
-- No `refList`, `refExtra`, `refMap`.
-- No automatic path-patching for list inserts/moves.
-
-It should be enough for current LMS usages.
-
----
-
-## 4) Draft Implementation Strategy
-
-### 4.1 Keep a ref store on root
-
-We store refs on root signal:
-
-```js
-const REFS = Symbol('compat refs')
-$root[REFS] = new Map()
-```
-
-Each entry is keyed by `fromPath` and stores `{ stop }` cleanup.
-
-### 4.2 One-way reactive sync (target → alias)
-
-We use `@nx-js/observer-util` `observe()` to track target changes and push them into alias:
-
-```js
-const toReaction = observe(() => {
-  const value = $to.get()
-  trackDeep(value)
-  setDiffDeepBypassRef($from, deepCopy(value))
-}, { lazy: true })
-
-toReaction()
-```
-
-Why deep copy?
-- Without it, `setDiffDeep` can re-use same object references and skip updates.
-- Deep copy ensures the diffing path detects change.
-
-### 4.3 Forward all mutations from alias → target
-
-To avoid two reactions and feedback loops, we forward all mutator calls:
-
-- `set`, `setNull`, `setDiffDeep`, `setEach`
-- `del`
-- `increment`
-- `push`, `unshift`, `insert`, `pop`, `shift`, `remove`, `move`
-- `stringInsert`, `stringRemove`
-- `assign`
-
-Forwarding uses a hidden `REF_TARGET` symbol on the alias signal.
-
-### 4.4 Mutator forward mechanism
-
-On each mutator:
-
-```js
-const forwarded = forwardRef(this, 'set', arguments)
-if (forwarded) return forwarded
-```
-
-`forwardRef()` resolves to a target signal if present and applies the same method there.
-
----
-
-## 5) Draft Code (for later restoration)
-
-Below is the exact code we removed from `SignalCompat.js`. It can be re-applied as-is.
-
-### 5.1 Imports (add back)
-
-```js
-import { raw, observe, unobserve } from '@nx-js/observer-util'
-```
-
-### 5.2 Symbols and helpers (add near other helpers)
-
-```js
-const REFS = Symbol('compat refs')
-const REF_TARGET = Symbol('compat ref target')
-
-function getRefStore ($signal) {
-  const $root = getRoot($signal) || $signal
-  $root[REFS] ??= new Map()
-  return $root[REFS]
-}
-
-function createRefLink ($from, $to) {
-  const toReaction = observe(() => {
-    const value = $to.get()
-    trackDeep(value)
-    setDiffDeepBypassRef($from, deepCopy(value))
-  }, { lazy: true })
-
-  // Prime sync and start tracking.
-  toReaction()
-  return () => {
-    unobserve(toReaction)
-  }
-}
-
-function trackDeep (value, seen = new Set()) {
-  if (!value || typeof value !== 'object') return
-  if (seen.has(value)) return
-  seen.add(value)
-  if (Array.isArray(value)) {
-    for (const item of value) trackDeep(item, seen)
-  } else {
-    for (const key in value) {
-      if (Object.prototype.hasOwnProperty.call(value, key)) {
-        trackDeep(value[key], seen)
-      }
-    }
-  }
-}
-
-function resolveRefSignal ($signal) {
-  let current = $signal
-  const seen = new Set()
-  while (current && current[REF_TARGET]) {
-    if (seen.has(current)) break
-    seen.add(current)
-    current = current[REF_TARGET]
-  }
-  return current
-}
-
-function forwardRef ($signal, methodName, args) {
-  const $target = resolveRefSignal($signal)
-  if ($target === $signal) return null
-  return SignalCompat.prototype[methodName].apply($target, args)
-}
-
-function setDiffDeepBypassRef ($signal, value) {
-  return Signal.prototype.set.call($signal, value)
-}
-```
-
-### 5.3 `ref()` / `removeRef()` methods (add to `SignalCompat`)
-
-```js
-ref (path, target, options) {
-  if (arguments.length > 3) throw Error('Signal.ref() expects one to three arguments')
-  let $from = this
-  let $to
-  if (arguments.length === 1) {
-    $to = resolveRefTarget(this, path, 'Signal.ref()')
-  } else if (arguments.length === 2) {
-    if (isSignalLike(target) || typeof target === 'string') {
-      const segments = parseAtSubpath(path, 1, 'Signal.ref()')
-      $from = resolveSignal(this, segments)
-      $to = resolveRefTarget(this, target, 'Signal.ref()')
-    } else {
-      $to = resolveRefTarget(this, path, 'Signal.ref()')
-      options = target
-    }
-  } else {
-    const segments = parseAtSubpath(path, 1, 'Signal.ref()')
-    $from = resolveSignal(this, segments)
-    $to = resolveRefTarget(this, target, 'Signal.ref()')
-  }
-  if (!$to) throw Error('Signal.ref() expects a target path or signal')
-  if ($from === $to) return $from
-  const store = getRefStore($from)
-  const fromPath = $from.path()
-  const existing = store.get(fromPath)
-  if (existing) existing.stop()
-  const stop = createRefLink($from, $to, options)
-  store.set(fromPath, { stop })
-  $from[REF_TARGET] = $to
-  return $from
-}
-
-removeRef (path) {
-  if (arguments.length > 1) throw Error('Signal.removeRef() expects a single argument')
-  let $from = this
-  if (arguments.length === 1) {
-    const segments = parseAtSubpath(path, 1, 'Signal.removeRef()')
-    $from = resolveSignal(this, segments)
-  }
-  const store = getRefStore($from)
-  const fromPath = $from.path()
-  const existing = store.get(fromPath)
-  if (existing) {
-    existing.stop()
-    store.delete(fromPath)
-  }
-  if ($from[REF_TARGET]) delete $from[REF_TARGET]
-}
-```
-
-### 5.4 Forwarding mutations (add to each mutator)
-
-Example for `set()`:
-
-```js
-async set (path, value) {
-  const forwarded = forwardRef(this, 'set', arguments)
-  if (forwarded) return forwarded
-  // ...existing body
-}
-```
-
-Same pattern for:
-- `setNull`, `setDiffDeep`, `setEach`
-- `del`
-- `increment`
-- `push`, `unshift`, `insert`, `pop`, `shift`, `remove`, `move`
-- `stringInsert`, `stringRemove`
-- `assign`
-
-### 5.5 Supporting helpers (only needed with ref)
-
-```js
-function isSignalLike (value) {
-  return value && typeof value.path === 'function' && typeof value.get === 'function'
-}
-
-function resolveRefTarget ($signal, target, methodName) {
-  if (isSignalLike(target)) return target
-  if (typeof target === 'string') {
-    const segments = parseAtSubpath(target, 1, methodName)
-    const $root = getRoot($signal) || $signal
-    return resolveSignal($root, segments)
-  }
-  return undefined
-}
-```
-
----
-
-## 6) Draft tests (removed)
-
-We also had tests in `packages/teamplay/test/signalCompat.js`. They can be restored if needed:
-
-- `syncs values both ways for direct signals`
-- `supports subpath refs from root`
-- `removeRef stops syncing`
-
----
-
-## 7) Risks and limitations
-
-- This is **not a full racer ref** implementation.
-- No support for `refList`, `refExtra`, `refMap`.
-- No array index patching when list changes.
-- Might not handle exotic cases with cyclic refs.
-
-That said, it’s deliberately scoped to known LMS usage patterns and should be “good enough” for those.