teamplay 0.4.0-alpha.21 → 0.4.0-alpha.23

package/orm/Compat/README.md

@@ -174,6 +174,46 @@ $alias.get() === $user.get()       // false
 - No event emissions specific to refs.
 - No support for racer-style ref meta/options beyond the basic signature.
 
+### start(targetPath, ...deps, getter)
+
+Legacy computed binding API from Racer/StartupJS.
+Creates a reactive computation and writes its result into `targetPath`.
+Source of truth is root API (`$root.start(...)`), but non-root calls are supported as sugar:
+- `$scope.start('a.b', ...deps, getter)` → `$root.start('<scopePath>.a.b', ...deps, getter)`
+
+- `targetPath`: string path where computed value is written.
+- `deps`: dependencies used by `getter`.
+- `getter`: function called as `getter(...resolvedDeps)`.
+
+Dependency resolution:
+- Signal-like dep (`$doc`, `$session.user`) → `dep.get()`.
+- String dep (`'settings.theme'`) → `$root.get(dep)`.
+- Any other dep → passed as-is.
+
+```js
+$root.start('_virtual.lesson', $.lessons[lessonId], '_session.userId', (lesson, userId) => {
+  if (!lesson) return undefined
+  return { stageIds: lesson.stageIds, userId }
+})
+```
+
+Behavior:
+- Calling `start()` again for the same `targetPath` replaces previous reaction.
+- `undefined` / `null` result clears target path via normal `set` semantics.
+- Returns target signal.
+
+### stop(targetPath)
+
+Stops a computation created with `start(targetPath, ...)`.
+No-op if there is no active computation for the path.
+Source of truth is root API (`$root.stop(...)`), but non-root calls are supported as sugar:
+- `$scope.stop('a.b')` → `$root.stop('<scopePath>.a.b')`
+- `$scope.stop()` → `$root.stop('<scopePath>')`
+
+```js
+$root.stop('_virtual.lesson')
+```
+
 ### query(collection, query, options?)
 
 Creates a query signal **without** subscribing. Supports shorthand params:

package/orm/Compat/hooksCompat.js

@@ -97,7 +97,8 @@ export function useBatchDoc (collection, id, options) {
 
 export function useBatchDoc$ (collection, id, _options) {
   const $doc = getDocSignal(collection, id, 'useBatchDoc')
-  return useSub($doc, undefined, { async: false, batch: true })
+  const options = _options ? { ..._options, ...BATCH_SUB_OPTIONS } : BATCH_SUB_OPTIONS
+  return useSub($doc, undefined, options)
 }
 
 export function useAsyncDoc$ (collection, id, options) {
@@ -140,7 +141,8 @@ export function useAsyncQuery (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 })
+  const options = _options ? { ..._options, ...BATCH_SUB_OPTIONS } : BATCH_SUB_OPTIONS
+  return useSub($collection, normalizeQuery(query, 'useBatchQuery'), options)
 }
 
 export function useBatchQuery (collection, query, options) {
@@ -306,3 +308,11 @@ function normalizeQuery (query, hookName) {
   }
   return query
 }
+
+const BATCH_SUB_OPTIONS = Object.freeze({
+  async: false,
+  batch: true,
+  // Batch hooks are a hard suspense barrier. Deferred params can skip the barrier
+  // on route transitions and cause immediate reads from stale/empty local nodes.
+  defer: false
+})

package/orm/Compat/startStopCompat.js

@@ -0,0 +1,85 @@
+import { observe, unobserve } from '@nx-js/observer-util'
+import { getRoot } from '../Root.js'
+
+const START_REACTIONS = Symbol('compat start reactions')
+
+export function compatStartOnRoot ($root, targetPath, ...depsAndGetter) {
+  if (!isRootSignal($root)) throw Error('Signal.start() is only available on root signal')
+  if (typeof targetPath !== 'string') throw Error('Signal.start() expects targetPath to be a string')
+  if (depsAndGetter.length < 1) {
+    throw Error('Signal.start() expects targetPath, dependencies, and a getter function')
+  }
+  const getter = depsAndGetter[depsAndGetter.length - 1]
+  if (typeof getter !== 'function') {
+    throw Error('Signal.start() expects the last argument to be a getter function')
+  }
+  const deps = depsAndGetter.slice(0, -1)
+  const targetSegments = parsePathSegments(targetPath)
+  const $target = resolveSignal($root, targetSegments)
+  const targetKey = $target.path()
+
+  const store = getStartStore($root)
+  const existing = store.get(targetKey)
+  if (existing) existing.stop()
+
+  const reaction = observe(() => {
+    const resolvedDeps = deps.map(dep => resolveStartDep(dep, $root))
+    const nextValue = getter(...resolvedDeps)
+    const maybePromise = $target.set(nextValue)
+    if (maybePromise?.catch) maybePromise.catch(ignorePromiseRejection)
+  })
+  store.set(targetKey, { stop: () => unobserve(reaction) })
+  return $target
+}
+
+export function compatStopOnRoot ($root, targetPath) {
+  if (!isRootSignal($root)) throw Error('Signal.stop() is only available on root signal')
+  if (typeof targetPath !== 'string') throw Error('Signal.stop() expects targetPath to be a string')
+  const targetSegments = parsePathSegments(targetPath)
+  const $target = resolveSignal($root, targetSegments)
+  const targetKey = $target.path()
+  const store = getStartStore($root)
+  const existing = store.get(targetKey)
+  if (!existing) return
+  existing.stop()
+  store.delete(targetKey)
+}
+
+export function joinScopePath (scopePath, relativePath) {
+  if (typeof scopePath !== 'string') scopePath = ''
+  const segments = []
+  if (scopePath) segments.push(...parsePathSegments(scopePath))
+  if (relativePath) segments.push(...parsePathSegments(relativePath))
+  return segments.join('.')
+}
+
+function getStartStore ($root) {
+  $root[START_REACTIONS] ??= new Map()
+  return $root[START_REACTIONS]
+}
+
+function resolveStartDep (dep, $root) {
+  if (isSignalLike(dep)) return dep.get()
+  if (typeof dep === 'string') return resolveSignal($root, parsePathSegments(dep)).get()
+  return dep
+}
+
+function isSignalLike (value) {
+  return value && typeof value.path === 'function' && typeof value.get === 'function'
+}
+
+function parsePathSegments (path) {
+  return path.split('.').filter(Boolean)
+}
+
+function resolveSignal ($base, segments) {
+  let $cursor = $base
+  for (const segment of segments) $cursor = $cursor[segment]
+  return $cursor
+}
+
+function isRootSignal ($signal) {
+  return getRoot($signal) === $signal
+}
+
+function ignorePromiseRejection () {}

package/orm/SignalBase.js

@@ -48,6 +48,7 @@ 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'
+import { compatStartOnRoot, compatStopOnRoot, joinScopePath } from './Compat/startStopCompat.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')
@@ -522,6 +523,22 @@ export const extremelyLateBindings = {
           }
         }
       }
+
+      if (key === 'start') {
+        const [relativePath, ...depsAndGetter] = argumentsList
+        if (typeof relativePath !== 'string') throw Error('Signal.start() expects targetPath to be a string')
+        const absolutePath = joinScopePath($parent.path(), relativePath)
+        return compatStartOnRoot(getRoot($parent) || $parent, absolutePath, ...depsAndGetter)
+      }
+      if (key === 'stop') {
+        if (argumentsList.length > 1) throw Error('Signal.stop() expects zero or one argument')
+        const relativePath = argumentsList.length === 0 ? '' : argumentsList[0]
+        if (relativePath != null && typeof relativePath !== 'string') {
+          throw Error('Signal.stop() expects targetPath to be a string')
+        }
+        const absolutePath = joinScopePath($parent.path(), relativePath || '')
+        return compatStopOnRoot(getRoot($parent) || $parent, absolutePath)
+      }
     }
 
     throw Error(ERRORS.noSignalKey($parent, key))

package/package.json

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