teamplay 0.4.0-alpha.8 → 0.4.0-alpha.80

package/README.md

@@ -19,6 +19,18 @@ Features:
 
 For installation and documentation see [teamplay.dev](https://teamplay.dev)
 
+## ORM Compat Helpers
+
+For legacy Racer-style model mixins (for example versioning libraries which call
+`getAssociations()`), use ORM compat helpers from the `teamplay/orm` subpath:
+
+```js
+import BaseModel, { hasMany, hasOne, belongsTo } from 'teamplay/orm'
+```
+
+These helpers attach class-level associations and expose them through
+`$doc.getAssociations()` on model signals.
+
 ## License
 
 MIT

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

@@ -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)
@@ -113,6 +116,8 @@ $.users.user1.scope('users.user2')
 Creates a lightweight alias between signals (minimal Racer-style ref).
 Mutations on the alias are forwarded to the target. The alias mirrors target updates.
 Reads (`get`/`peek`) are forwarded to the target while the ref is active.
+Ref mirroring is scheduled through Teamplay runtime scheduler, so updates remain batch-friendly
+and do not leak intermediate ref states during a single batched cycle.
 
 ```js
 const $local = $.local.value
@@ -164,13 +169,85 @@ $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.
 
+### 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` result applies compat delete semantics at target path.
+- `null` result is stored as `null`.
+- Returns target signal.
+- If any dependency temporarily suspends (throws a Promise/thenable), compat skips the whole tick (getter is not called and target is not written).
+- If `getter` throws a Promise, compat skips that tick and retries on next reactive update.
+
+### 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:
@@ -202,6 +279,19 @@ await $.subscribe($user, $$active)
 $.unsubscribe($user, $$active)
 ```
 
+### close(callback?)
+
+Compatibility shim for legacy `model.close()` calls.
+
+- In Teamplay, `$`/`model` is a global root signal (not a per-request Racer model instance).
+- Therefore `close()` is intentionally a no-op.
+- Optional callback is supported and called immediately.
+
+```js
+model.close()
+model.close(() => console.log('closed'))
+```
+
 ### fetch(...signals) / unfetch(...signals)
 
 Fetch-only variants of `subscribe` / `unsubscribe`. They load data once without a live subscription.
@@ -236,6 +326,7 @@ Returns the current value and tracks reactivity.
 const name = $.users.user1.name.get()
 $root.get('$render.url')
 $user.get('profile.name')
+$user.get('profile', 'name')
 ```
 
 ### peek(subpath?)
@@ -245,6 +336,7 @@ Returns the current value **without** tracking reactivity.
 ```js
 const name = $.users.user1.name.peek()
 $user.peek('profile.name')
+$user.peek('profile', 'name')
 ```
 
 ### getCopy(subpath)
@@ -306,6 +398,44 @@ for (const $doc of $query) {
 }
 ```
 
+### Mutator Semantics (Core vs Compat)
+
+Compatibility mode intentionally aligns mutators with Racer. This differs from core `Signal` behavior.
+
+| API | Core (`Signal`) | Compat (`SignalCompat`) |
+| --- | --- | --- |
+| `set` | Uses deep-diff path (`dataTree.set` + internal `setDiffDeep`). | Path-targeted replace semantics, Racer-like. `undefined` keeps delete semantics. |
+| `setEach` | Not a special API in core mutators. | Per-key compat `set` (not `assign` merge/delete behavior). |
+| `setDiffDeep` | Deep-diff engine (`utils/setDiffDeep.js`). | Recursive Racer-like diff implemented via compat mutators (`set` / `del`) on nested paths. |
+| `setDiff` | N/A as compat shim. | Alias to compat `set` for both signatures: `setDiff(value)` and `setDiff(path, value)`. |
+
+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.
+
+Compat queries also retain lifecycle ownership of docs they materialize into DataTree.
+This means a doc that arrived through `useQuery` / `useBatchQuery` will stay available
+for immediate `useLocal` / `useModel` reads while that query remains subscribed, even if
+some unrelated `useDoc` subscriber for the same `collection.id` unmounts.
+
 ### set(value) and set(path, value)
 
 `SignalCompat` accepts both:
@@ -315,7 +445,14 @@ $.users.user1.name.set('Alice')
 $.users.user1.set('profile.name', 'Alice')
 ```
 
-In compat mode, `set` replaces values at the target path.
+In compat mode, `set` replaces the value at the target path.
+- `set(path, null)` stores `null`.
+- `set(path, undefined)` applies current delete semantics.
+
+```js
+await $.users.user1.set('profile', { name: 'Ann', role: 'student' })
+await $.users.user1.set('profile', { name: 'Kate' }) // role is removed
+```
 
 ### setNull(path?, value)
 
@@ -327,26 +464,47 @@ $.config.setNull('theme', 'light')
 
 ### setDiffDeep(path?, value)
 
-Applies a diff-deep update (uses base `Signal.set` internally).
+Applies a recursive Racer-like diff using compat mutators (`set` / `del`) on subpaths.
+This is intentionally a compat implementation detail and differs from core deep-diff internals.
 
 ```js
-$.users.user1.setDiffDeep({ profile: { name: 'Alice' } })
+await $.users.user1.set({ profile: { name: 'Ann', role: 'student' } })
+await $.users.user1.setDiffDeep({ profile: { name: 'Kate' } }) // deep-diff path
 ```
 
 ### setDiff(path?, value)
 
-Alias for `set()` in compat. Accepts the same arguments and semantics.
+Alias for compat `set` in both forms:
+- `setDiff(value)` -> same as `set(value)`
+- `setDiff(path, value)` -> same as `set(path, value)`
 
 ```js
-$.users.user1.setDiff({ profile: { name: 'Alice' } })
+await $.users.user1.setDiff({ profile: { name: 'Kate' } })
+await $.users.user1.setDiff('profile', { name: 'Bob' })
 ```
 
 ### setEach(path?, object)
 
-Shorthand for assign. Sets or deletes fields from an object.
+Racer-like per-key set. `setEach` iterates keys and applies compat `set` for each key.
+- `setEach({ k: null })` stores `null`.
+- `setEach({ k: undefined })` applies current delete semantics.
+
+```js
+await $.users.user1.setEach({ name: 'Bob', age: null })
+```
+
+### Null / Undefined Matrix (Compat)
+
+| Call | Result |
+| --- | --- |
+| `set(path, null)` | stores `null` at `path` |
+| `set(path, undefined)` | applies delete semantics at `path` |
+| `setEach({ k: null })` | stores `null` for `k` |
+| `setEach({ k: undefined })` | applies delete semantics for `k` |
 
 ```js
-$.users.user1.setEach({ name: 'Bob', age: 30 })
+await $.users.user1.set('status', null) // status === null
+await $.users.user1.setEach({ status: undefined }) // status deleted
 ```
 
 ### assign(object)
@@ -360,6 +518,8 @@ $.users.user1.assign({ name: 'Bob', age: null })
 ### del(path?)
 
 Deletes a value. Can be used with a subpath.
+In compat mode, deleting a non-existing **public** document (or its subpath) is a no-op
+to match legacy racer behavior.
 
 ```js
 $.users.user1.del('profile.name')
@@ -478,8 +638,12 @@ 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 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
 
@@ -652,10 +816,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
 
@@ -672,10 +838,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.
@@ -690,9 +858,18 @@ 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).
+- 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
 
@@ -706,7 +883,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`
 
@@ -721,16 +898,33 @@ 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.
+
+### Missing ShareDB Docs
+
+Compat now mirrors Racer behavior for **missing public docs** (`type === null`,
+`version === 0`) after subscribe/fetch:
+
+- `connection.get(collection, id).data` becomes a truthy empty observable object;
+- but the compat/model path still stays unresolved, so `$.collection[id].get()`
+  continues to return `undefined` until the document is actually created.
+
+This matters for legacy consumers which read `shareDoc.data` directly (for
+example readonly rich-text paths) while still expecting normal public-doc
+creation semantics from model mutators.
 
 ## Examples
 
@@ -758,6 +952,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>)}