teamplay 0.4.0-alpha.32 → 0.4.0-alpha.34

package/index.d.ts

@@ -94,6 +94,8 @@ export function useDidUpdate (fn: () => EffectCleanup, deps?: any[]): void
 export function useOnce (condition: any, fn: () => EffectCleanup): void
 export function useSyncEffect (fn: () => EffectCleanup, deps?: any[]): void
 export { connection, setConnection, getConnection, fetchOnly, setFetchOnly, publicOnly, setPublicOnly } from './orm/connection.js'
+export function getSubscriptionGcDelay (): number
+export function setSubscriptionGcDelay (ms?: number | null): number
 export { useId, useNow, useScheduleUpdate, useTriggerUpdate } from './react/helpers.js'
 export { GUID_PATTERN, hasMany, hasOne, hasManyFlags, belongsTo, pickFormFields } from '@teamplay/schema'
 export { aggregation, aggregationHeader as __aggregationHeader } from '@teamplay/utils/aggregation'

package/index.js

@@ -66,6 +66,7 @@ export {
   useSyncEffect
 } from './react/helpers.js'
 export { connection, setConnection, getConnection, fetchOnly, setFetchOnly, 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'
 export { aggregation, aggregationHeader as __aggregationHeader } from '@teamplay/utils/aggregation'

package/orm/Compat/README.md

@@ -370,6 +370,25 @@ Compatibility mode intentionally aligns mutators with Racer. This differs from c
 Migration note: compat behavior is intentionally Racer-aligned and may differ from core mutators.
 Composite compat mutators (`setEach`, `setDiffDeep`) apply updates atomically for Teamplay-scheduled observers via the runtime batch scheduler.
 
+### Subscription GC Delay (Compat)
+
+To reduce UI blink on rapid `unsub -> sub` cycles, compat uses an unload grace period for docs/queries.
+
+- Default in compat: `300ms`
+- Default in non-compat: `0ms` (immediate cleanup)
+
+You can tune it globally:
+
+```js
+import { getSubscriptionGcDelay, setSubscriptionGcDelay } from 'teamplay'
+
+setSubscriptionGcDelay(500)
+console.log(getSubscriptionGcDelay()) // 500
+```
+
+When refCount drops to `0`, unsubscribe/destroy is scheduled after this delay.
+If a new subscribe arrives before timeout, pending destroy is cancelled and the same doc/query instance is reused.
+
 ### set(value) and set(path, value)
 
 `SignalCompat` accepts both:
@@ -571,7 +590,8 @@ General notes:
 - Hooks should be used inside `observer()` components to get reactive updates.
 - Sync hooks (`useDoc`, `useQuery`) use Suspense by default (via `useSub`).
 - Async hooks (`useAsyncDoc`, `useAsyncQuery`) never throw; they return `undefined` until ready.
-- Batch hooks are **aliases**, no batching is implemented.
+- Batch hooks use a Suspense batch barrier (`useBatch`) and wait for both
+  subscribe promises and DataTree materialization readiness.
 
 ### Events
 
@@ -744,10 +764,12 @@ if (!user) return 'Loading...'
 
 Returns `undefined` until subscription resolves.
 
-#### Batch aliases
+#### Batch variants
 
-`useBatchDoc` / `useBatchDoc$` are aliases to `useDoc` / `useDoc$`.
-Batching is not implemented in Teamplay.
+`useBatchDoc` / `useBatchDoc$` participate in batch Suspense flow:
+- they register subscribe promises for `useBatch()`;
+- they also register a **materialization readiness check**:
+  doc is considered ready only when it is visible in DataTree (or explicitly missing).
 
 ### Query Hooks
 
@@ -784,9 +806,13 @@ if (!users) return 'Loading...'
 
 Async variant: no Suspense, returns `undefined` until ready.
 
-#### Batch aliases
+#### Batch variants
 
-`useBatchQuery` / `useBatchQuery$` are aliases to `useQuery` / `useQuery$`.
+`useBatchQuery` / `useBatchQuery$` participate in batch Suspense flow:
+- they register subscribe promises for `useBatch()`;
+- 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).
 
 ### Query Helpers
 
@@ -800,7 +826,7 @@ const [users] = useQueryIds('users', ['b', 'a'])
 Options:
 - `reverse: true` — reverse order of IDs before mapping.
 
-`useBatchQueryIds` and `useAsyncQueryIds` are alias/async variants.
+`useBatchQueryIds` and `useAsyncQueryIds` are batch/async variants.
 
 #### `useQueryDoc`
 
@@ -815,16 +841,20 @@ Implementation details:
 - Adds default `$sort: { createdAt: -1 }` if `$sort` is missing
 
 `useQueryDoc$` returns only the doc signal (or `undefined`).
-`useBatchQueryDoc` / `useAsyncQueryDoc` are alias/async variants.
+`useBatchQueryDoc` / `useAsyncQueryDoc` are batch/async variants.
 
-### Batching Placeholder
+### Batch Barrier
 
-`useBatch()` is a no-op placeholder.  
-All batch hooks are **aliases** to their non-batch versions.
+`useBatch()` is a Suspense barrier for batch hooks.
 
-```js
-useBatch() // does nothing in Teamplay
-```
+It throws while:
+- batch subscribe promises are pending;
+- or subscribe promises are resolved but requested docs/queries are not yet
+  materialized in DataTree.
+
+After `useBatch()` stops throwing in compat mode, immediate reads via
+`useLocal(...).get(...)` for already requested batch entities should not produce
+transient `undefined` caused by materialization races.
 
 ## Examples
 

package/orm/Compat/hooksCompat.js

@@ -2,6 +2,10 @@ 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'
+import { getRaw } from '../dataTree.js'
+import { getConnection } from '../connection.js'
+import { isCompatEnv } from '../compatEnv.js'
+import { hashQuery, QUERIES } from '../Query.js'
 
 const $root = getRootSignal({ rootId: GLOBAL_ROOT_ID, rootFunction: universal$ })
 
@@ -97,6 +101,7 @@ export function useBatchDoc (collection, id, options) {
 
 export function useBatchDoc$ (collection, id, _options) {
   const $doc = getDocSignal(collection, id, 'useBatchDoc')
+  registerBatchDocReadinessCheck(collection, getDocIdFromSignal($doc))
   const options = _options ? { ..._options, ...BATCH_SUB_OPTIONS } : BATCH_SUB_OPTIONS
   return useSub($doc, undefined, options)
 }
@@ -140,9 +145,11 @@ export function useAsyncQuery (collection, query, options) {
 }
 
 export function useBatchQuery$ (collection, query, _options) {
+  const normalizedQuery = normalizeQuery(query, 'useBatchQuery')
   const $collection = getCollectionSignal(collection, query, 'useBatchQuery')
+  registerBatchQueryReadinessCheck(collection, normalizedQuery)
   const options = _options ? { ..._options, ...BATCH_SUB_OPTIONS } : BATCH_SUB_OPTIONS
-  return useSub($collection, normalizeQuery(query, 'useBatchQuery'), options)
+  return useSub($collection, normalizedQuery, options)
 }
 
 export function useBatchQuery (collection, query, options) {
@@ -316,3 +323,84 @@ const BATCH_SUB_OPTIONS = Object.freeze({
   // on route transitions and cause immediate reads from stale/empty local nodes.
   defer: false
 })
+
+function getDocIdFromSignal ($doc) {
+  const path = typeof $doc?.path === 'function' ? $doc.path() : ''
+  const segments = path ? path.split('.').filter(Boolean) : []
+  return segments[segments.length - 1]
+}
+
+function registerBatchDocReadinessCheck (collection, id) {
+  if (!isCompatEnv()) return
+  if (!collection || id == null) return
+  const docSegments = [collection, id]
+  promiseBatcher.addCheck({
+    key: `doc:${collection}.${id}`,
+    type: 'doc',
+    details: `${collection}.${id}`,
+    isReady: () => isDocReady(docSegments),
+    getState: () => {
+      const shareDoc = getShareDoc(collection, id)
+      return {
+        raw: getRaw(docSegments),
+        shareDoc: shareDoc
+          ? {
+              type: shareDoc.type,
+              data: shareDoc.data
+            }
+          : undefined
+      }
+    }
+  })
+}
+
+function registerBatchQueryReadinessCheck (collection, query) {
+  if (!isCompatEnv()) return
+  if (!collection || !query || typeof query !== 'object') return
+  const hash = hashQuery(collection, query)
+  const idsSegments = [QUERIES, hash, 'ids']
+  promiseBatcher.addCheck({
+    key: `query:${hash}`,
+    type: 'query',
+    details: { collection, hash, query },
+    isReady: () => isQueryReady(collection, idsSegments),
+    getState: () => {
+      const ids = getRaw(idsSegments)
+      return {
+        ids,
+        docs: Array.isArray(ids)
+          ? ids.map(id => ({
+            id,
+            raw: getRaw([collection, id])
+          }))
+          : ids
+      }
+    }
+  })
+}
+
+function isQueryReady (collection, idsSegments) {
+  const ids = getRaw(idsSegments)
+  if (!Array.isArray(ids)) return false
+  for (const id of ids) {
+    if (!isDocReady([collection, id])) return false
+  }
+  return true
+}
+
+function isDocReady (segments) {
+  const rawDoc = getRaw(segments)
+  if (rawDoc !== undefined) return true
+  const [collection, id] = segments
+  const shareDoc = getShareDoc(collection, id)
+  // Missing docs should not block the batch barrier forever.
+  return !!(shareDoc && shareDoc.type === null && shareDoc.data == null)
+}
+
+function getShareDoc (collection, id) {
+  try {
+    return getConnection().get(collection, id)
+  } catch {
+    return undefined
+  }
+}

package/orm/Doc.js

@@ -6,6 +6,7 @@ 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'
 
 const ERROR_ON_EXCESSIVE_UNSUBSCRIBES = false
 
@@ -103,11 +104,13 @@ class Doc {
   }
 }
 
-class DocSubscriptions {
-  constructor () {
+export class DocSubscriptions {
+  constructor (DocClass = Doc) {
+    this.DocClass = DocClass
     this.subCount = new Map()
     this.docs = new Map()
-    this.fr = new FinalizationRegistry(segments => this.destroy(segments))
+    this.pendingDestroyTimers = new Map()
+    this.fr = new FinalizationRegistry(segments => this.scheduleDestroy(segments, { force: true }))
   }
 
   init ($doc) {
@@ -118,7 +121,7 @@ class DocSubscriptions {
       if (doc.initialized) return
       doc.init()
     } else {
-      doc = new Doc(...segments)
+      doc = new this.DocClass(...segments)
       this.docs.set(hash, doc)
       this.fr.register($doc, segments, $doc)
       doc.init()
@@ -128,10 +131,17 @@ class DocSubscriptions {
   subscribe ($doc) {
     const segments = [...$doc[SEGMENTS]]
     const hash = hashDoc(segments)
+    this.cancelDestroy(hash)
     let count = this.subCount.get(hash) || 0
     count += 1
     this.subCount.set(hash, count)
-    if (count > 1) return this.docs.get(hash)._subscribing
+    if (count > 1) {
+      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)
+    }
 
     this.init($doc)
     const doc = this.docs.get(hash)
@@ -152,19 +162,83 @@ class DocSubscriptions {
       this.subCount.set(hash, count)
       return
     }
+    this.subCount.set(hash, 0)
     this.fr.unregister($doc)
-    await this.destroy(segments)
+    await this.scheduleDestroy(segments)
   }
 
   async destroy (segments) {
     const hash = hashDoc(segments)
+    await this.destroyByHash(hash, { force: true })
+  }
+
+  async clear () {
+    for (const entry of this.pendingDestroyTimers.values()) {
+      clearTimeout(entry.timer)
+    }
+    this.pendingDestroyTimers.clear()
+    const hashes = Array.from(this.docs.keys())
+    for (const hash of hashes) {
+      await this.destroyByHash(hash, { force: true })
+    }
+    this.subCount.clear()
+  }
+
+  async flushPendingDestroys () {
+    const entries = Array.from(this.pendingDestroyTimers.entries())
+    for (const [hash, entry] of entries) {
+      clearTimeout(entry.timer)
+      this.pendingDestroyTimers.delete(hash)
+      await this.destroyByHash(hash, { force: entry.force })
+    }
+  }
+
+  async scheduleDestroy (segments, options = {}) {
+    const hash = hashDoc(segments)
+    const delay = getSubscriptionGcDelay()
+    if (delay <= 0) {
+      await this.destroyByHash(hash, options)
+      return
+    }
+    const existing = this.pendingDestroyTimers.get(hash)
+    if (existing) {
+      if (options.force) existing.force = true
+      return
+    }
+    const timer = setTimeout(() => {
+      const entry = this.pendingDestroyTimers.get(hash)
+      if (!entry) return
+      this.pendingDestroyTimers.delete(hash)
+      this.destroyByHash(hash, { force: entry.force }).catch(ignoreDestroyError)
+    }, delay)
+    this.pendingDestroyTimers.set(hash, {
+      timer,
+      force: !!options.force
+    })
+  }
+
+  cancelDestroy (hash) {
+    const entry = this.pendingDestroyTimers.get(hash)
+    if (!entry) return
+    clearTimeout(entry.timer)
+    this.pendingDestroyTimers.delete(hash)
+  }
+
+  async destroyByHash (hash, options = {}) {
+    this.cancelDestroy(hash)
+    const count = this.subCount.get(hash) || 0
+    if (!options.force && count > 0) return
     const doc = this.docs.get(hash)
-    if (!doc) return
+    if (!doc) {
+      this.subCount.delete(hash)
+      return
+    }
     this.subCount.delete(hash)
     // Always call unsubscribe() - if doc is in SUBSCRIBING state, the state machine
     // will queue a pending unsubscribe to execute after subscribe completes
     await doc.unsubscribe()
     if (doc.subscribed) return // Subscribed again while unsubscribing
+    if ((this.subCount.get(hash) || 0) > 0) return
     this.docs.delete(hash)
   }
 }
@@ -175,6 +249,8 @@ function hashDoc (segments) {
   return JSON.stringify(segments)
 }
 
+function ignoreDestroyError () {}
+
 function emitDocOp (collection, docId, op) {
   if (!isModelEventsEnabled()) return
   const ops = Array.isArray(op) ? op : [op]

package/orm/Query.js

@@ -8,6 +8,7 @@ import { docSubscriptions } from './Doc.js'
 import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
 import SubscriptionState from './SubscriptionState.js'
 import { getIdFieldsForSegments, injectIdFields, isPlainObject } from './idFields.js'
+import { getSubscriptionGcDelay } from './subscriptionGcDelay.js'
 
 const ERROR_ON_EXCESSIVE_UNSUBSCRIBES = false
 export const COLLECTION_NAME = Symbol('query collection name')
@@ -211,13 +212,17 @@ export class QuerySubscriptions {
     this.QueryClass = QueryClass
     this.subCount = new Map()
     this.queries = new Map()
-    this.fr = new FinalizationRegistry(({ collectionName, params }) => this.destroy(collectionName, params))
+    this.pendingDestroyTimers = new Map()
+    this.fr = new FinalizationRegistry(({ collectionName, params }) => {
+      this.scheduleDestroy(collectionName, params, undefined, { force: true })
+    })
   }
 
   subscribe ($query) {
     const collectionName = $query[COLLECTION_NAME]
     const params = JSON.parse(JSON.stringify($query[PARAMS]))
     const hash = $query[HASH]
+    this.cancelDestroy(hash)
     let count = this.subCount.get(hash) || 0
     count += 1
     this.subCount.set(hash, count)
@@ -252,22 +257,89 @@ export class QuerySubscriptions {
       this.subCount.set(hash, count)
       return
     }
-    this.subCount.delete(hash)
+    this.subCount.set(hash, 0)
     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)
+    await this.scheduleDestroy($query[COLLECTION_NAME], $query[PARAMS], hash)
   }
 
-  async destroy (collectionName, params) {
+  async destroy (collectionName, params, options = {}) {
     const hash = hashQuery(collectionName, params)
+    await this.destroyByHash(hash, {
+      collectionName,
+      params,
+      force: options.force ?? true
+    })
+  }
+
+  async clear () {
+    for (const entry of this.pendingDestroyTimers.values()) {
+      clearTimeout(entry.timer)
+    }
+    this.pendingDestroyTimers.clear()
+    const hashes = Array.from(this.queries.keys())
+    for (const hash of hashes) {
+      const { collectionName, params } = parseQueryHash(hash)
+      await this.destroyByHash(hash, {
+        collectionName,
+        params,
+        force: true
+      })
+    }
+    this.subCount.clear()
+  }
+
+  async flushPendingDestroys () {
+    const entries = Array.from(this.pendingDestroyTimers.entries())
+    for (const [hash, entry] of entries) {
+      clearTimeout(entry.timer)
+      this.pendingDestroyTimers.delete(hash)
+      await this.destroyByHash(hash, { force: entry.force })
+    }
+  }
+
+  async scheduleDestroy (collectionName, params, hash = hashQuery(collectionName, params), options = {}) {
+    const delay = getSubscriptionGcDelay()
+    if (delay <= 0) {
+      await this.destroyByHash(hash, { collectionName, params, force: !!options.force })
+      return
+    }
+    const existing = this.pendingDestroyTimers.get(hash)
+    if (existing) {
+      if (options.force) existing.force = true
+      return
+    }
+    const timer = setTimeout(() => {
+      const entry = this.pendingDestroyTimers.get(hash)
+      if (!entry) return
+      this.pendingDestroyTimers.delete(hash)
+      this.destroyByHash(hash, { collectionName, params, force: entry.force }).catch(ignoreDestroyError)
+    }, delay)
+    this.pendingDestroyTimers.set(hash, {
+      timer,
+      force: !!options.force
+    })
+  }
+
+  cancelDestroy (hash) {
+    const entry = this.pendingDestroyTimers.get(hash)
+    if (!entry) return
+    clearTimeout(entry.timer)
+    this.pendingDestroyTimers.delete(hash)
+  }
+
+  async destroyByHash (hash, options = {}) {
+    this.cancelDestroy(hash)
+    const count = this.subCount.get(hash) || 0
+    if (!options.force && count > 0) return
     const query = this.queries.get(hash)
-    if (!query) return
+    if (!query) {
+      this.subCount.delete(hash)
+      return
+    }
     this.subCount.delete(hash)
     await query.unsubscribe()
     if (query.subscribed) return // if we subscribed again while waiting for unsubscribe, we don't delete the doc
+    if ((this.subCount.get(hash) || 0) > 0) return
     this.queries.delete(hash)
   }
 }
@@ -322,3 +394,5 @@ const ERRORS = {
       Params: ${$query[PARAMS]}
   `
 }
+
+function ignoreDestroyError () {}

package/orm/subscriptionGcDelay.js

@@ -0,0 +1,32 @@
+import { isCompatEnv } from './compatEnv.js'
+
+const DEFAULT_COMPAT_SUBSCRIPTION_GC_DELAY = 300
+const DEFAULT_SUBSCRIPTION_GC_DELAY = 0
+
+let subscriptionGcDelay = getDefaultSubscriptionGcDelay()
+
+export function getSubscriptionGcDelay () {
+  return subscriptionGcDelay
+}
+
+export function setSubscriptionGcDelay (ms) {
+  if (ms == null) {
+    subscriptionGcDelay = getDefaultSubscriptionGcDelay()
+    return subscriptionGcDelay
+  }
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) {
+    throw Error('setSubscriptionGcDelay() expects a non-negative finite number')
+  }
+  subscriptionGcDelay = ms
+  return subscriptionGcDelay
+}
+
+export function getDefaultSubscriptionGcDelay () {
+  return isCompatEnv()
+    ? DEFAULT_COMPAT_SUBSCRIPTION_GC_DELAY
+    : DEFAULT_SUBSCRIPTION_GC_DELAY
+}
+
+export function __resetSubscriptionGcDelayForTests () {
+  subscriptionGcDelay = getDefaultSubscriptionGcDelay()
+}

package/package.json

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

package/react/promiseBatcher.js

@@ -1,5 +1,9 @@
 let active = false
 let promises = []
+let checks = new Map()
+
+const READINESS_POLL_INTERVAL_MS = 16
+const READINESS_WARN_AFTER_MS = 1000
 
 export function activate () {
   active = true
@@ -10,9 +14,22 @@ export function add (promise) {
   promises.push(promise)
 }
 
+export function addCheck (check) {
+  if (!check || typeof check.isReady !== 'function') return
+  const key = check.key ?? Symbol('batch-check')
+  checks.set(key, { ...check, key })
+}
+
 export function getPromiseAll () {
-  const hasPromises = promises.length > 0
-  const result = hasPromises ? Promise.all(promises) : null
+  const pendingPromises = promises
+  const pendingChecks = Array.from(checks.values())
+  const hasPromises = pendingPromises.length > 0
+  const hasChecks = pendingChecks.length > 0
+  const result = !hasPromises && !hasChecks
+    ? null
+    : hasPromises || !areChecksReady(pendingChecks)
+      ? waitForBatchReady(pendingPromises, pendingChecks)
+      : null
   reset()
   return result
 }
@@ -24,4 +41,80 @@ export function isActive () {
 export function reset () {
   active = false
   promises = []
+  checks = new Map()
+}
+
+async function waitForBatchReady (pendingPromises, pendingChecks) {
+  if (pendingPromises.length > 0) await Promise.all(pendingPromises)
+  // Let microtasks flush after subscription promises resolve so tree writes become visible.
+  await Promise.resolve()
+  await waitForChecksReady(pendingChecks)
+}
+
+async function waitForChecksReady (pendingChecks) {
+  if (pendingChecks.length === 0) return
+  let warned = false
+  const startedAt = Date.now()
+  while (true) {
+    const notReadyChecks = getNotReadyChecks(pendingChecks)
+    if (notReadyChecks.length === 0) return
+    if (!warned && isDevMode() && Date.now() - startedAt >= READINESS_WARN_AFTER_MS) {
+      warned = true
+      warnAboutChecksDelay(notReadyChecks)
+    }
+    await delay(READINESS_POLL_INTERVAL_MS)
+  }
+}
+
+function areChecksReady (pendingChecks) {
+  if (pendingChecks.length === 0) return true
+  return getNotReadyChecks(pendingChecks).length === 0
+}
+
+function getNotReadyChecks (pendingChecks) {
+  const notReady = []
+  for (const check of pendingChecks) {
+    if (!isCheckReady(check)) notReady.push(check)
+  }
+  return notReady
+}
+
+function isCheckReady (check) {
+  try {
+    return !!check.isReady()
+  } catch (err) {
+    if (isThenable(err)) return false
+    throw err
+  }
+}
+
+function warnAboutChecksDelay (checks) {
+  const details = checks.map(check => {
+    let state
+    try {
+      state = typeof check.getState === 'function' ? check.getState() : undefined
+    } catch (err) {
+      state = isThenable(err) ? 'suspended' : `state-error: ${err?.message || err}`
+    }
+    return {
+      type: check.type || 'unknown',
+      key: String(check.key),
+      details: check.details,
+      state
+    }
+  })
+  console.warn('[teamplay] useBatch() is waiting for data materialization checks.', details)
+}
+
+function isDevMode () {
+  if (typeof process === 'undefined' || !process?.env) return true
+  return process.env.NODE_ENV !== 'production'
+}
+
+function isThenable (value) {
+  return !!value && typeof value.then === 'function'
+}
+
+function delay (ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
 }