teamplay 0.4.0-alpha.34 → 0.4.0-alpha.36

package/orm/Compat/README.md

@@ -589,6 +589,9 @@ They are designed to behave close to StartupJS hooks, but adapted to Teamplay’
 General notes:
 - Hooks should be used inside `observer()` components to get reactive updates.
 - Sync hooks (`useDoc`, `useQuery`) use Suspense by default (via `useSub`).
+- In compatibility mode, sync hooks are strict (`defer: false`) to match racer-like
+  semantics and avoid transient `undefined` / empty snapshots during fast navigation.
+  This is enforced by compat hooks (user `defer` option is ignored for sync hooks).
 - Async hooks (`useAsyncDoc`, `useAsyncQuery`) never throw; they return `undefined` until ready.
 - Batch hooks use a Suspense batch barrier (`useBatch`) and wait for both
   subscribe promises and DataTree materialization readiness.
@@ -813,6 +816,11 @@ Async variant: no Suspense, returns `undefined` until ready.
 - they register a **query readiness check**:
   query ids must be materialized in DataTree, and each `collection.id` from ids must
   be visible in DataTree (or explicitly missing).
+- for `$aggregate` queries, readiness is query-level:
+  DataTree must have `$queries.<hash>.docs` (array, including empty), or `extra`.
+  Aggregate rows are not required to exist as `collection.<id>` docs.
+  Presence of `$queries.<hash>.ids` alone does not mark aggregate readiness.
+  For Teamplay aggregation subscriptions, `$aggregations.<hash>` also marks readiness.
 
 ### Query Helpers
 

package/orm/Compat/hooksCompat.js

@@ -6,6 +6,7 @@ import { getRaw } from '../dataTree.js'
 import { getConnection } from '../connection.js'
 import { isCompatEnv } from '../compatEnv.js'
 import { hashQuery, QUERIES } from '../Query.js'
+import { AGGREGATIONS } from '../Aggregation.js'
 
 const $root = getRootSignal({ rootId: GLOBAL_ROOT_ID, rootFunction: universal$ })
 
@@ -84,7 +85,7 @@ export function useBatch () {
 
 export function useDoc$ (collection, id, options) {
   const $doc = getDocSignal(collection, id, 'useDoc')
-  const normalizedOptions = options ? { ...options, async: false } : options
+  const normalizedOptions = normalizeSyncSubOptions(options)
   return useSub($doc, undefined, normalizedOptions)
 }
 
@@ -119,14 +120,14 @@ 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
+  const normalizedOptions = normalizeSyncSubOptions(options)
   const $query = useSub($collection, normalizeQuery(query, 'useQuery'), normalizedOptions)
   return $query
 }
 
 export function useQuery (collection, query, options) {
   const $collection = getCollectionSignal(collection, query, 'useQuery')
-  const normalizedOptions = options ? { ...options, async: false } : options
+  const normalizedOptions = normalizeSyncSubOptions(options)
   const $query = useSub($collection, normalizeQuery(query, 'useQuery'), normalizedOptions)
   return [$query.get(), $collection]
 }
@@ -324,6 +325,18 @@ const BATCH_SUB_OPTIONS = Object.freeze({
   defer: false
 })
 
+function normalizeSyncSubOptions (options) {
+  if (!isCompatEnv()) {
+    return options ? { ...options, async: false } : options
+  }
+  return {
+    ...(options || {}),
+    async: false,
+    // Compat sync hooks are strict by design: no deferred snapshots between route/tab switches.
+    defer: false
+  }
+}
+
 function getDocIdFromSignal ($doc) {
   const path = typeof $doc?.path === 'function' ? $doc.path() : ''
   const segments = path ? path.split('.').filter(Boolean) : []
@@ -359,16 +372,26 @@ function registerBatchQueryReadinessCheck (collection, query) {
   if (!collection || !query || typeof query !== 'object') return
   const hash = hashQuery(collection, query)
   const idsSegments = [QUERIES, hash, 'ids']
+  const docsSegments = [QUERIES, hash, 'docs']
+  const extraSegments = [QUERIES, hash, 'extra']
+  const aggregationSegments = [AGGREGATIONS, hash]
+  const isAggregate = Array.isArray(query.$aggregate)
   promiseBatcher.addCheck({
     key: `query:${hash}`,
     type: 'query',
-    details: { collection, hash, query },
-    isReady: () => isQueryReady(collection, idsSegments),
+    details: { collection, hash, query, isAggregate },
+    isReady: () => isQueryReady(collection, idsSegments, docsSegments, extraSegments, aggregationSegments, isAggregate),
     getState: () => {
       const ids = getRaw(idsSegments)
+      const docs = getRaw(docsSegments)
+      const extra = getRaw(extraSegments)
+      const aggregation = getRaw(aggregationSegments)
       return {
         ids,
-        docs: Array.isArray(ids)
+        queryDocs: docs,
+        extra,
+        aggregation,
+        idMaterialization: Array.isArray(ids)
           ? ids.map(id => ({
             id,
             raw: getRaw([collection, id])
@@ -379,10 +402,17 @@ function registerBatchQueryReadinessCheck (collection, query) {
   })
 }
 
-function isQueryReady (collection, idsSegments) {
+function isQueryReady (collection, idsSegments, docsSegments, extraSegments, aggregationSegments, isAggregate) {
+  if (isAggregate) {
+    const docs = getRaw(docsSegments)
+    if (Array.isArray(docs)) return true
+    if (getRaw(extraSegments) !== undefined) return true
+    return getRaw(aggregationSegments) !== undefined
+  }
   const ids = getRaw(idsSegments)
   if (!Array.isArray(ids)) return false
   for (const id of ids) {
+    if (id == null) continue
     if (!isDocReady([collection, id])) return false
   }
   return true
@@ -404,3 +434,7 @@ function getShareDoc (collection, id) {
     return undefined
   }
 }
+
+export const __COMPAT_BATCH_READY__ = {
+  isQueryReady
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.4.0-alpha.34",
+  "version": "0.4.0-alpha.36",
   "description": "Full-stack signals ORM with multiplayer",
   "type": "module",
   "main": "index.js",
@@ -81,5 +81,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "619024ea6ea3699ab461c279791a59e5a58334ab"
+  "gitHead": "0f90958b39502634ec8fefc99d7e688f0ac4c4bc"
 }