teamplay 0.4.0-alpha.71 → 0.4.0-alpha.72

package/orm/Compat/README.md

@@ -169,10 +169,39 @@ $alias.get()                       // { name: 'Bob' }
 $alias.get() === $user.get()       // false
 ```
 
+### `ref` on query/aggregation targets (`mirror-only`)
+
+Compat supports `refExtra` / `refIds` and query/aggregation-backed refs, but with a
+different contract from plain document refs.
+
+When target is a query or aggregation signal, compat creates a **mirror-only** link:
+- Source path is updated from target changes (target -> source).
+- Source path does **not** become an alias to target path (no `REF_TARGET` forwarding).
+- Writes to source path do not forward to query/aggregation internals.
+
+Why:
+- Query/aggregation paths are hashed/synthetic and are not safe as generic alias targets.
+- Racer behavior for these cases is effectively "mirror data into page/local path",
+  not "make full bidirectional alias".
+
+Reactivity:
+- Initial sync runs immediately on `ref(...)`.
+- Further target updates are mirrored through compat model-change events.
+
+```js
+const $query = $.query('courses', { active: true })
+const $table = $._page.tables._adminCourses
+
+// mirror query.extra/docs into page model
+$query.refExtra('_page.tables._adminCourses.dataSource')
+
+// reactively mirrors target -> source
+$table.dataSource.get()
+```
+
 **Limitations vs Racer**
-- No `refList`, `refExtra`, `refMap`.
+- No `refList`, `refMap`.
 - No automatic list index patching on insert/remove/move.
-- No support for query/aggregation refs.
 - No event emissions specific to refs.
 - No support for racer-style ref meta/options beyond the basic signature.
 

package/orm/Compat/SignalCompat.js

@@ -1,4 +1,4 @@
-import { raw } from '@nx-js/observer-util'
+import { raw, observe, unobserve } from '@nx-js/observer-util'
 import {
   Signal,
   GETTERS,
@@ -601,10 +601,19 @@ class SignalCompat extends Signal {
     const fromPath = $from.path()
     const existing = store.get(fromPath)
     if (existing) existing.stop()
-    const stop = createRefLink($from, $to, options)
+    const mirrorOnly = !!($to?.[IS_QUERY] || $to?.[IS_AGGREGATION])
+    const { stop, onChange } = createRefLink($from, $to, { mirrorOnly, options })
     store.set(fromPath, { stop })
-    $from[REF_TARGET] = $to
-    setRefLink(fromPath, $to.path())
+    if (!mirrorOnly) {
+      $from[REF_TARGET] = $to
+      setRefLink(fromPath, $to.path(), $from[SEGMENTS], $to[SEGMENTS], { mirrorOnly: false })
+    } else {
+      setRefLink(fromPath, $to.path(), $from[SEGMENTS], $to[SEGMENTS], {
+        mirrorOnly: true,
+        onChange
+      })
+      if ($from[REF_TARGET]) delete $from[REF_TARGET]
+    }
     return $from
   }
 
@@ -715,23 +724,55 @@ function createSilentSignalWrapper ($signal, enabled = true) {
 }
 
 const REFS = Symbol('compat refs')
-const SKIP_REF_TICK = Symbol('compat ref skip tick')
-
 function getRefStore ($signal) {
   const $root = getRoot($signal) || $signal
   $root[REFS] ??= new Map()
   return $root[REFS]
 }
 
-function createRefLink ($from, $to) {
+function createRefLink ($from, $to, { mirrorOnly = false } = {}) {
+  let disposed = false
+  let pendingRead = null
+  let mirrorObserver
+
   const syncFromTarget = () => {
     const value = readRefValue($to)
-    if (value === SKIP_REF_TICK) return
+    if (isThenable(value)) {
+      pendingRead = value
+      value.then(() => {
+        if (disposed || pendingRead !== value) return
+        pendingRead = null
+        syncFromTarget()
+      }, () => {
+        if (pendingRead === value) pendingRead = null
+      })
+      return
+    }
+    if (value === undefined) return
     setDiffDeepBypassRef($from, deepCopy(value))
   }
+
   syncFromTarget()
-  return () => {
-    // Subsequent sync happens directly at mutation time via mirrorRefMutationFromTarget().
+  if (mirrorOnly) {
+    mirrorObserver = observe(
+      () => {
+        syncFromTarget()
+        return readRefValue($to)
+      },
+      {
+        scheduler: job => job()
+      }
+    )
+    // initialize dependency graph
+    mirrorObserver()
+  }
+  return {
+    onChange: syncFromTarget,
+    stop: () => {
+      disposed = true
+      if (mirrorObserver) unobserve(mirrorObserver)
+      // Subsequent sync happens directly at mutation time via mirrorRefMutationFromTarget().
+    }
   }
 }
 
@@ -739,7 +780,7 @@ function readRefValue ($signal) {
   try {
     return $signal.get()
   } catch (err) {
-    if (isThenable(err)) return SKIP_REF_TICK
+    if (isThenable(err)) return err
     throw err
   }
 }

package/orm/Compat/modelEvents.js

@@ -66,6 +66,9 @@ export function emitModelChange (path, value, prevValue, meta) {
 
     for (const link of getRefLinks().values()) {
       if (!isPathPrefix(link.toSegments, segments)) continue
+      if (link.mirrorOnly && typeof link.onChange === 'function') {
+        link.onChange()
+      }
       const suffix = segments.slice(link.toSegments.length)
       const nextSegments = link.fromSegments.concat(suffix)
       const nextKey = nextSegments.join('.')

package/orm/Compat/refFallback.js

@@ -39,6 +39,7 @@ export function resolveRefSegmentsSafe (segments, maxDepth = 32) {
 function findBestMatchingLink (segments) {
   let best
   for (const link of getRefLinks().values()) {
+    if (link.mirrorOnly) continue
     if (!isPathPrefix(link.fromSegments, segments)) continue
     if (!best || link.fromSegments.length > best.fromSegments.length) {
       best = link

package/orm/Compat/refRegistry.js

@@ -1,12 +1,20 @@
 const refLinks = new Map()
 
-export function setRefLink (fromPath, toPath) {
+export function setRefLink (fromPath, toPath, fromSegments, toSegments, options = {}) {
   if (typeof fromPath !== 'string' || typeof toPath !== 'string') return
+  const normalizedFromSegments = Array.isArray(fromSegments)
+    ? fromSegments.map(segment => String(segment))
+    : splitPath(fromPath)
+  const normalizedToSegments = Array.isArray(toSegments)
+    ? toSegments.map(segment => String(segment))
+    : splitPath(toPath)
   refLinks.set(fromPath, {
     fromPath,
     toPath,
-    fromSegments: splitPath(fromPath),
-    toSegments: splitPath(toPath)
+    fromSegments: normalizedFromSegments,
+    toSegments: normalizedToSegments,
+    mirrorOnly: !!options.mirrorOnly,
+    onChange: typeof options.onChange === 'function' ? options.onChange : undefined
   })
 }
 

package/package.json

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