teamplay 0.1.15 → 0.2.0

package/README.md

@@ -17,100 +17,7 @@ Features:
 
 ## Installation
 
-### Client-only mode
-
-If you just want a client-only mode without any data being synced to the server, then you don't need to setup anything and can jump directly to [Usage](#usage).
-
-### Synchronization of data with server
-
-Enable the connection on client somewhere early in your client app:
-
-```js
-import connect from 'teamplay/connect'
-connect()
-```
-
-On the server you need to create the teamplay's backend and then create a connection handler for WebSockets:
-
-```js
-import { createBackend, initConnection } from 'teamplay/server'
-const backend = createBackend()
-const { upgrade } = initConnection(backend)
-server.on('upgrade', upgrade) // Node's 'http' server instance
-```
-
-- for production use it's recommended to use MongoDB. It's gonna be automatically used if you set the env var `MONGO_URL`
-- when deploying to a cluster with multiple instances you also have to set the env var `REDIS_URL` (Redis)
-
-Without setting `MONGO_URL` the alternative `mingo` mock is used instead which persists data into an SQLite file `local.db` in the root of your project.
-
-> [!NOTE]
-> teamplay's `createBackend()` is a wrapper around creating a [ShareDB's backend](https://share.github.io/sharedb/api/backend).
-> You can instead manually create a ShareDB backend yourself and pass it to `initConnection()`.
-> `ShareDB` is re-exported from `teamplay/server`, you can get it as `import { ShareDB } from 'teamplay/server'`
-
-## `initConnection(backend, options)`
-
-**`backend`** - ShareDB backend instance
-
-**`options`**:
-
-### `fetchOnly` (default: `true`)
-
-By default all subscriptions on the server are not reactive. This is strongly recommended.
-
-If you need the subscriptions to reactively update data whenever it changes (the same way as they work on client-side), pass `{ fetchOnly: false }`.
-
-## Usage
-
-TBD
-...
-
-## Examples
-
-For a simple working react app see [/example](/example)
-
-### Simplest example with server synchronization
-
-On the client we `connect()` to the server, and we have to wrap each React component into `observer()`:
-
-```js
-// client.js
-import { createRoot } from 'react-dom/client'
-import connect from 'teamplay/connect'
-import { observer, $, sub } from 'teamplay'
-
-connect()
-
-const App = observer(({ userId }) => {
-  const $user = sub($.users[userId])
-  if (!$user.get()) throw $user.set({ points: 0 })
-  const { $points } = $user
-  const increment = () => $points.set($points.get() + 1)
-  return <button onClick={increment}>Points: {$points.get()}</button>
-})
-
-const container = document.body.appendChild(document.createElement('div'))
-createRoot(container).render(<App userId='_1' />)
-```
-
-On the server we create the ShareDB backend and initialize the WebSocket connections handler:
-
-```js
-// server.js
-import http from 'http'
-import { createBackend, initConnection } from 'teamplay/server'
-
-const server = http.createServer() // you can pass expressApp here if needed
-const backend = createBackend()
-const { upgrade } = initConnection(backend)
-
-server.on('upgrade', upgrade)
-
-server.listen(3000, () => {
-  console.log('Server started. Open http://localhost:3000 in your browser')
-})
-```
+For installation and documentation see [teamplay.dev](https://teamplay.dev)
 
 ## License
 

package/index.js

@@ -13,11 +13,12 @@ export { default as signal } from './orm/getSignal.js'
 export { GLOBAL_ROOT_ID } from './orm/Root.js'
 export const $ = _getRootSignal({ rootId: GLOBAL_ROOT_ID, rootFunction: universal$ })
 export default $
-export { default as sub } from './react/universalSub.js'
+export { default as sub } from './orm/sub.js'
+export { default as useSub } from './react/useSub.js'
 export { default as observer } from './react/observer.js'
 export { connection, setConnection, getConnection, fetchOnly, setFetchOnly, publicOnly, setPublicOnly } from './orm/connection.js'
 export { GUID_PATTERN, hasMany, hasOne, hasManyFlags, belongsTo, pickFormFields } from '@teamplay/schema'
-export { aggregation, aggregationHeader } from '@teamplay/utils/aggregation'
+export { aggregation, aggregationHeader as __aggregationHeader } from '@teamplay/utils/aggregation'
 
 export function getRootSignal (options) {
   return _getRootSignal({
@@ -25,19 +26,3 @@ export function getRootSignal (options) {
     ...options
   })
 }
-
-// the following are react-specific hook alternatives to $() and sub() functions.
-// In future we might want to expose them, but at the current time they are not needed
-// and instead just the regular $() and sub() functions are used since they are universal
-//
-// export function use$ (value) {
-//   // TODO: maybe replace all non-letter/digit characters with underscores
-//   const id = useId() // eslint-disable-line react-hooks/rules-of-hooks
-//   return $(value, id)
-// }
-
-// export function useSub (...args) {
-//   const promiseOrSignal = sub(...args)
-//   if (promiseOrSignal.then) throw promiseOrSignal
-//   return promiseOrSignal
-// }

package/orm/Aggregation.js

@@ -0,0 +1,68 @@
+import { raw } from '@nx-js/observer-util'
+import { set as _set, del as _del, getRaw } from './dataTree.js'
+import getSignal from './getSignal.js'
+import { QuerySubscriptions, hashQuery, Query, HASH, PARAMS, COLLECTION_NAME, parseQueryHash } from './Query.js'
+import Signal, { SEGMENTS } from './Signal.js'
+
+export const IS_AGGREGATION = Symbol('is aggregation signal')
+export const AGGREGATIONS = '$aggregations'
+
+class Aggregation extends Query {
+  _initData () {
+    {
+      const extra = raw(this.shareQuery.extra)
+      _set([AGGREGATIONS, this.hash], extra)
+    }
+
+    this.shareQuery.on('extra', extra => {
+      extra = raw(extra)
+      _set([AGGREGATIONS, this.hash], extra)
+    })
+  }
+
+  _removeData () {
+    _del([AGGREGATIONS, this.hash])
+  }
+}
+
+export const aggregationSubscriptions = new QuerySubscriptions(Aggregation)
+
+export function getAggregationSignal (collectionName, params, options) {
+  params = JSON.parse(JSON.stringify(params))
+  const hash = hashQuery(collectionName, params)
+
+  const $aggregation = getSignal(undefined, [AGGREGATIONS, hash], options)
+  $aggregation[IS_AGGREGATION] ??= true
+  $aggregation[COLLECTION_NAME] ??= collectionName
+  $aggregation[PARAMS] ??= params
+  $aggregation[HASH] ??= hash
+  return $aggregation
+}
+
+// example: ['$aggregations', '{"active":true}']
+export function isAggregationSignal ($signal) {
+  if (!($signal instanceof Signal)) return
+  const segments = $signal[SEGMENTS]
+  if (!(segments.length === 2)) return
+  if (!(segments[0] === AGGREGATIONS)) return
+  return true
+}
+
+// example: ['$aggregations', '{"active":true}', 42]
+//          AND only if it also has either '_id' or 'id' field inside
+export function getAggregationDocId (segments) {
+  if (!(segments.length >= 3)) return
+  if (!(segments[0] === AGGREGATIONS)) return
+  if (!(typeof segments[2] === 'number')) return
+  const doc = getRaw(segments)
+  const docId = doc?._id || doc?.id
+  return docId
+}
+
+export function getAggregationCollectionName (segments) {
+  if (!(segments.length >= 2)) return
+  if (!(segments[0] === AGGREGATIONS)) return
+  const hash = segments[1]
+  const { collectionName } = parseQueryHash(hash)
+  return collectionName
+}

package/orm/Query.js

@@ -1,28 +1,28 @@
 import { raw } from '@nx-js/observer-util'
 import { get as _get, set as _set, del as _del } from './dataTree.js'
-import { SEGMENTS } from './Signal.js'
 import getSignal from './getSignal.js'
 import { getConnection, fetchOnly } from './connection.js'
 import { docSubscriptions } from './Doc.js'
 import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
 
 const ERROR_ON_EXCESSIVE_UNSUBSCRIBES = false
+export const COLLECTION_NAME = Symbol('query collection name')
 export const PARAMS = Symbol('query params')
 export const HASH = Symbol('query hash')
 export const IS_QUERY = Symbol('is query signal')
 export const QUERIES = '$queries'
 
-class Query {
+export class Query {
   subscribing
   unsubscribing
   subscribed
   initialized
   shareQuery
 
-  constructor (collection, params) {
-    this.collection = collection
+  constructor (collectionName, params) {
+    this.collectionName = collectionName
     this.params = params
-    this.hash = hashQuery([this.collection], this.params)
+    this.hash = hashQuery(this.collectionName, this.params)
     this.docSignals = new Set()
   }
 
@@ -66,7 +66,7 @@ class Query {
         await this.subscribing
         this.init()
       } catch (err) {
-        console.log('subscription error', [this.collection, this.params], err)
+        console.log('subscription error', [this.collectionName, this.params], err)
         this.subscribed = undefined
         throw err
       } finally {
@@ -79,7 +79,7 @@ class Query {
   async _subscribe () {
     await new Promise((resolve, reject) => {
       const method = fetchOnly ? 'createFetchQuery' : 'createSubscribeQuery'
-      this.shareQuery = getConnection()[method](this.collection, this.params, {}, err => {
+      this.shareQuery = getConnection()[method](this.collectionName, this.params, {}, err => {
         if (err) return reject(err)
         resolve()
       })
@@ -88,7 +88,7 @@ class Query {
 
   async unsubscribe () {
     if (!this.subscribed) {
-      throw Error('trying to unsubscribe while not subscribed. Query: ' + [this.collection, this.params])
+      throw Error('trying to unsubscribe while not subscribed. Query: ' + [this.collectionName, this.params])
     }
     this.subscribed = undefined
     // if we are still handling the subscription, just wait for it to finish and then unsubscribe
@@ -120,7 +120,7 @@ class Query {
         this.initialized = undefined
         this._removeData()
       } catch (err) {
-        console.log('error unsubscribing', [this.collection, this.params], err)
+        console.log('error unsubscribing', [this.collectionName, this.params], err)
         this.subscribed = true
         throw err
       } finally {
@@ -148,7 +148,7 @@ class Query {
 
       const ids = this.shareQuery.results.map(doc => doc.id)
       for (const docId of ids) {
-        const $doc = getSignal(undefined, [this.collection, docId])
+        const $doc = getSignal(undefined, [this.collectionName, docId])
         docSubscriptions.init($doc)
         this.docSignals.add($doc)
       }
@@ -161,7 +161,7 @@ class Query {
 
       const ids = shareDocs.map(doc => doc.id)
       for (const docId of ids) {
-        const $doc = getSignal(undefined, [this.collection, docId])
+        const $doc = getSignal(undefined, [this.collectionName, docId])
         docSubscriptions.init($doc)
         this.docSignals.add($doc)
       }
@@ -182,7 +182,7 @@ class Query {
 
       const docIds = shareDocs.map(doc => doc.id)
       for (const docId of docIds) {
-        const $doc = getSignal(undefined, [this.collection, docId])
+        const $doc = getSignal(undefined, [this.collectionName, docId])
         this.docSignals.delete($doc)
       }
       const ids = _get([QUERIES, this.hash, 'ids'])
@@ -196,36 +196,35 @@ class Query {
   }
 }
 
-class QuerySubscriptions {
-  constructor () {
+export class QuerySubscriptions {
+  constructor (QueryClass = Query) {
+    this.QueryClass = QueryClass
     this.subCount = new Map()
     this.queries = new Map()
-    this.fr = new FinalizationRegistry(({ segments, params }) => this.destroy(segments, params))
+    this.fr = new FinalizationRegistry(({ collectionName, params }) => this.destroy(collectionName, params))
   }
 
   subscribe ($query) {
-    const segments = [...$query[SEGMENTS]]
+    const collectionName = $query[COLLECTION_NAME]
     const params = JSON.parse(JSON.stringify($query[PARAMS]))
-    const hash = hashQuery(segments, params)
+    const hash = $query[HASH]
     let count = this.subCount.get(hash) || 0
     count += 1
     this.subCount.set(hash, count)
     if (count > 1) return this.queries.get(hash).subscribing
 
-    this.fr.register($query, { segments, params }, $query)
+    this.fr.register($query, { collectionName, params }, $query)
 
     let query = this.queries.get(hash)
     if (!query) {
-      query = new Query(segments[0], params)
+      query = new this.QueryClass(collectionName, params)
       this.queries.set(hash, query)
     }
     return query.subscribe()
   }
 
   async unsubscribe ($query) {
-    const segments = [...$query[SEGMENTS]]
-    const params = JSON.parse(JSON.stringify($query[PARAMS]))
-    const hash = hashQuery(segments, params)
+    const hash = $query[HASH]
     let count = this.subCount.get(hash) || 0
     count -= 1
     if (count < 0) {
@@ -244,8 +243,8 @@ class QuerySubscriptions {
     this.queries.delete(hash)
   }
 
-  async destroy (segments, params) {
-    const hash = hashQuery(segments, params)
+  async destroy (collectionName, params) {
+    const hash = hashQuery(collectionName, params)
     const query = this.queries.get(hash)
     if (!query) return
     this.subCount.delete(hash)
@@ -257,20 +256,30 @@ class QuerySubscriptions {
 
 export const querySubscriptions = new QuerySubscriptions()
 
-export function hashQuery (segments, params) {
+export function hashQuery (collectionName, params) {
   // TODO: probably makes sense to use fast-stable-json-stringify for this because of the params
-  return JSON.stringify({ query: [segments[0], params] })
+  return JSON.stringify({ query: [collectionName, params] })
+}
+
+export function parseQueryHash (hash) {
+  try {
+    const { query: [collectionName, params] } = JSON.parse(hash)
+    return { collectionName, params }
+  } catch (err) {
+    return {}
+  }
 }
 
-export function getQuerySignal (segments, params, options) {
+export function getQuerySignal (collectionName, params, options) {
   params = JSON.parse(JSON.stringify(params))
-  const hash = hashQuery(segments, params)
+  const hash = hashQuery(collectionName, params)
 
-  const $query = getSignal(undefined, segments, {
+  const $query = getSignal(undefined, [collectionName], {
     signalHash: hash,
     ...options
   })
   $query[IS_QUERY] ??= true
+  $query[COLLECTION_NAME] ??= collectionName
   $query[PARAMS] ??= params
   $query[HASH] ??= hash
   return $query
@@ -278,7 +287,8 @@ export function getQuerySignal (segments, params, options) {
 
 const ERRORS = {
   notSubscribed: $query => `
-    trying to unsubscribe when not subscribed. Query:
-    ${[$query[SEGMENTS], $query[PARAMS]]}
+    Trying to unsubscribe from Query when not subscribed.
+      Collection: ${$query[COLLECTION_NAME]}
+      Params: ${$query[PARAMS]}
   `
 }

package/orm/Signal.js

@@ -14,15 +14,21 @@
 import uuid from '@teamplay/utils/uuid'
 import { get as _get, set as _set, del as _del, setPublicDoc as _setPublicDoc, getRaw } from './dataTree.js'
 import getSignal, { rawSignal } from './getSignal.js'
+import { docSubscriptions } from './Doc.js'
 import { IS_QUERY, HASH, QUERIES } from './Query.js'
+import { AGGREGATIONS, getAggregationCollectionName, getAggregationDocId } from './Aggregation.js'
 import { ROOT_FUNCTION, getRoot } from './Root.js'
 import { publicOnly } from './connection.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')
 export const GET = Symbol('get the value of the signal - either observed or raw')
+export const GETTERS = Symbol('get the list of this signal\'s getters')
+const DEFAULT_GETTERS = ['path', 'id', 'get', 'peek', 'getId', 'map', 'reduce', 'find']
 
 export default class Signal extends Function {
+  static [GETTERS] = DEFAULT_GETTERS
+
   constructor (segments) {
     if (!Array.isArray(segments)) throw Error('Signal constructor expects an array of segments')
     super()
@@ -218,11 +224,40 @@ export const extremelyLateBindings = {
       return signal[ROOT_FUNCTION].call(thisArg, signal, ...argumentsList)
     }
     const key = signal[SEGMENTS][signal[SEGMENTS].length - 1]
-    const $parent = getSignal(getRoot(signal), signal[SEGMENTS].slice(0, -1))
-    const rawParent = rawSignal($parent)
-    if (!(key in rawParent)) {
-      throw Error(`Method "${key}" does not exist on signal "${$parent[SEGMENTS].join('.')}"`)
+    const segments = signal[SEGMENTS].slice(0, -1)
+    if (segments[0] === AGGREGATIONS) {
+      const aggregationDocId = getAggregationDocId(segments)
+      if (aggregationDocId) {
+        if (segments.length === 3 && key === 'set') throw Error(ERRORS.setAggregationDoc(segments, key))
+        const collectionName = getAggregationCollectionName(segments)
+        const subDocSegments = segments.slice(3)
+        const $original = getSignal(getRoot(signal), [collectionName, aggregationDocId, ...subDocSegments])
+        const rawOriginal = rawSignal($original)
+        if (!(key in rawOriginal)) throw Error(ERRORS.noSignalKey($original, key))
+        const fn = rawOriginal[key]
+        const getters = rawOriginal.constructor[GETTERS]
+        // for getters run the method on the aggregation data itself
+        if (getters.includes(key)) {
+          const $parent = getSignal(getRoot(signal), segments)
+          return Reflect.apply(fn, $parent, argumentsList)
+        // for async methods (setters) subscribe to the original doc and run the method on its relative signal
+        } else {
+          const $doc = getSignal(getRoot(signal), [collectionName, aggregationDocId])
+          const promise = docSubscriptions.subscribe($doc)
+          if (!promise) return Reflect.apply(fn, $original, argumentsList)
+          return new Promise(resolve => {
+            promise.then(() => {
+              resolve(Reflect.apply(fn, $original, argumentsList))
+            })
+          })
+        }
+      } else if (!DEFAULT_GETTERS.includes(key)) {
+        throw Error(ERRORS.aggregationSetter(segments, key))
+      }
     }
+    const $parent = getSignal(getRoot(signal), segments)
+    const rawParent = rawSignal($parent)
+    if (!(key in rawParent)) throw Error(ERRORS.noSignalKey($parent, key))
     return Reflect.apply(rawParent[key], $parent, argumentsList)
   },
   get (signal, key, receiver) {
@@ -286,5 +321,25 @@ const ERRORS = {
   publicOnly: `
     Can't modify private collections data when 'publicOnly' is enabled.
     On the server you can only work with public collections.
+  `,
+  noSignalKey: ($signal, key) => `Method "${key}" does not exist on signal "${$signal[SEGMENTS].join('.')}"`,
+  aggregationSetter: (segments, key) => `
+    You can not use setters on aggregation signals.
+    It's only allowed when the aggregation result is an array of documents
+    with either '_id' or 'id' field present in them.
+
+    Path: ${segments}
+    Method: ${key}
+  `,
+  setAggregationDoc: (segments, key) => `
+    Changing a whole document using .set() from an aggregation signal is prohibited.
+    This is to prevent accidental overwriting of the whole document with incorrect aggregation results.
+    You can only change the particular fields within the document using the aggregation signal.
+
+    If you want to change the whole document, use the actual document signal explicitly
+    (and make sure to subscribe to it).
+
+    Path: ${segments}
+    Method: ${key}
   `
 }

package/orm/dataTree.js

@@ -2,6 +2,7 @@ import { observable, raw } from '@nx-js/observer-util'
 import jsonDiff from 'json0-ot-diff'
 import diffMatchPatch from 'diff-match-patch'
 import { getConnection } from './connection.js'
+import setDiffDeep from '../utils/setDiffDeep.js'
 
 const ALLOW_PARTIAL_DOC_CREATION = false
 
@@ -62,8 +63,12 @@ export function set (segments, value, tree = dataTree) {
     }
     return
   }
-  // just set the new value
-  dataNode[key] = value
+  // instead of just setting the new value `dataNode[key] = value` we want
+  // to deeply update it to prevent unnecessary reactivity triggers.
+  const newValue = setDiffDeep(dataNode[key], value)
+  // handle case when the value couldn't be updated in place and is completely new
+  // (we just set it to this value)
+  if (dataNode[key] !== newValue) dataNode[key] = newValue
 }
 
 export function del (segments, tree = dataTree) {

package/orm/getSignal.js

@@ -4,6 +4,7 @@ import { findModel } from './addModel.js'
 import { LOCAL } from './$.js'
 import { ROOT, ROOT_ID, GLOBAL_ROOT_ID } from './Root.js'
 import { QUERIES } from './Query.js'
+import { AGGREGATIONS } from './Aggregation.js'
 
 const PROXIES_CACHE = new Cache()
 const PROXY_TO_SIGNAL = new WeakMap()
@@ -22,7 +23,7 @@ export default function getSignal ($root, segments = [], {
   if (!($root instanceof Signal)) {
     if (segments.length === 0 && !rootId) throw Error(ERRORS.rootIdRequired)
     if (segments.length >= 1 && isPrivateCollection(segments[0])) {
-      if (segments[0] === QUERIES) {
+      if (segments[0] === QUERIES || segments[0] === AGGREGATIONS) {
         // TODO: this is a hack to temporarily let the queries work.
         //       '$queries' collection is always added to the global (singleton) root signal.
         //       In future it should also be part of the particular root signal.

package/orm/sub.js

@@ -1,21 +1,33 @@
+import { isAggregationHeader, isAggregationFunction } from '@teamplay/utils/aggregation'
 import Signal, { SEGMENTS, isPublicCollectionSignal, isPublicDocumentSignal } from './Signal.js'
 import { docSubscriptions } from './Doc.js'
 import { querySubscriptions, getQuerySignal } from './Query.js'
+import { aggregationSubscriptions, getAggregationSignal } from './Aggregation.js'
 
 export default function sub ($signal, params) {
-  if (Array.isArray($signal)) {
-    const res = $signal.map(args => Array.isArray(args) ? sub(...args) : sub(args))
-    if (res.some($s => $s.then)) return Promise.all(res)
-    return res
-  }
+  // TODO: temporarily disable support for multiple subscriptions
+  //       since this has to be properly cached using useDeferredSignal() in useSub()
+  // if (Array.isArray($signal)) {
+  //   const res = $signal.map(args => Array.isArray(args) ? sub(...args) : sub(args))
+  //   if (res.some($s => $s.then)) return Promise.all(res)
+  //   return res
+  // }
   if (isPublicDocumentSignal($signal)) {
     if (arguments.length > 1) throw Error(ERRORS.subDocArguments(...arguments))
     return doc$($signal)
   } else if (isPublicCollectionSignal($signal)) {
     if (arguments.length !== 2) throw Error(ERRORS.subQueryArguments(...arguments))
-    return query$($signal, params)
+    return query$($signal[SEGMENTS][0], params)
   } else if (typeof $signal === 'function' && !($signal instanceof Signal)) {
     return api$($signal, params)
+  } else if (isAggregationHeader($signal)) {
+    params = {
+      $aggregationName: $signal.name,
+      $params: sanitizeAggregationParams(params)
+    }
+    return aggregation$($signal.collection, params)
+  } else if (isAggregationFunction($signal)) {
+    throw Error(ERRORS.gotAggregationFunction($signal))
   } else {
     throw Error('Invalid args passed for sub()')
   }
@@ -27,18 +39,34 @@ function doc$ ($doc) {
   return new Promise(resolve => promise.then(() => resolve($doc)))
 }
 
-function query$ ($collection, params) {
-  if (typeof params !== 'object') throw Error(ERRORS.queryParamsObject($collection, params))
-  const $query = getQuerySignal($collection[SEGMENTS], params)
+function query$ (collectionName, params) {
+  if (typeof params !== 'object') throw Error(ERRORS.queryParamsObject(collectionName, params))
+  const $query = getQuerySignal(collectionName, params)
   const promise = querySubscriptions.subscribe($query)
   if (!promise) return $query
   return new Promise(resolve => promise.then(() => resolve($query)))
 }
 
+function aggregation$ (collectionName, params) {
+  const $aggregationQuery = getAggregationSignal(collectionName, params)
+  const promise = aggregationSubscriptions.subscribe($aggregationQuery)
+  if (!promise) return $aggregationQuery
+  return new Promise(resolve => promise.then(() => resolve($aggregationQuery)))
+}
+
 function api$ (fn, args) {
   throw Error('sub() for async functions is not implemented yet')
 }
 
+// aggregation params get transferred to the server
+// and while doing so if some value is 'undefined', it actually gets transferred as 'null'
+// which breaks logic of setting default values in the aggregation function.
+// That's why we have to explicitly remove 'undefined' values from the aggregation params.
+// This can be easily done by serializing and deserializing it to JSON.
+function sanitizeAggregationParams (params) {
+  return JSON.parse(JSON.stringify(params))
+}
+
 const ERRORS = {
   subDocArguments: ($signal, ...args) => `
     sub($doc) accepts only 1 argument - the document signal to subscribe to
@@ -52,13 +80,24 @@ const ERRORS = {
     Params: ${params}
     Got args: ${[$signal, params, ...args]}
   `,
-  queryParamsObject: ($collection, params) => `
+  queryParamsObject: (collectionName, params) => `
     sub($collection, params):
       Params must be an object.
       If you want to subscribe to all documents in a collection, pass an empty object: sub($collection, {}).
 
       Got:
-        $collection: ${$collection[SEGMENTS]}
+        collectionName: ${collectionName}
         params: ${params}
+  `,
+  gotAggregationFunction: aggregationFn => `
+    sub($$aggregation, params):
+      Got aggregation function itself instead of the aggregation header.
+      Looks like client-side code transformation did not work properly and your
+      aggregation() function was not transformed into an __aggregationHeader().
+      Make sure you only use aggregation() function inside project's 'model' folder using
+      import { aggregation } from 'startupjs'
+
+      Got:
+        ${aggregationFn.toString()}
   `
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.1.15",
+  "version": "0.2.0",
   "description": "Full-stack signals ORM with multiplayer",
   "type": "module",
   "main": "index.js",
@@ -23,12 +23,12 @@
   },
   "dependencies": {
     "@nx-js/observer-util": "^4.1.3",
-    "@teamplay/backend": "^0.1.15",
-    "@teamplay/cache": "^0.1.15",
-    "@teamplay/channel": "^0.1.15",
-    "@teamplay/debug": "^0.1.15",
-    "@teamplay/schema": "^0.1.15",
-    "@teamplay/utils": "^0.1.15",
+    "@teamplay/backend": "^0.2.0",
+    "@teamplay/cache": "^0.2.0",
+    "@teamplay/channel": "^0.2.0",
+    "@teamplay/debug": "^0.2.0",
+    "@teamplay/schema": "^0.2.0",
+    "@teamplay/utils": "^0.2.0",
     "diff-match-patch": "^1.0.5",
     "events": "^3.3.0",
     "json0-ot-diff": "^1.1.2",
@@ -63,5 +63,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "fc145854b61d07a913f27db2b604e4a2bf855fa0"
+  "gitHead": "34435bba6654d480cac0e809defc15e1d15bd543"
 }

package/react/universalSub.js

@@ -1,3 +1,7 @@
+// NOTE: this is not used currently since using an explicit useSub()
+//       hook is easier to understand in a React context.
+//       Having the same sub() function working with either await or without it
+//       is confusing. It's better to have a separate function for the hook.
 import { useRef } from 'react'
 import sub from '../orm/sub.js'
 import executionContextTracker from './executionContextTracker.js'

package/react/useSub.js

@@ -0,0 +1,38 @@
+import { useRef, useDeferredValue } from 'react'
+import sub from '../orm/sub.js'
+
+let TEST_THROTTLING = false
+
+// version of sub() which works as a react hook and throws promise for Suspense
+export default function useSub (signal, params) {
+  signal = useDeferredValue(signal)
+  params = useDeferredValue(params ? JSON.stringify(params) : undefined)
+  params = params ? JSON.parse(params) : undefined
+  const promiseOrSignal = params ? sub(signal, params) : sub(signal)
+  // 1. if it's a promise, throw it so that Suspense can catch it and wait for subscription to finish
+  if (promiseOrSignal.then) {
+    if (TEST_THROTTLING) {
+      // simulate slow network
+      throw new Promise((resolve, reject) => {
+        setTimeout(() => {
+          promiseOrSignal.then(resolve, reject)
+        }, TEST_THROTTLING)
+      })
+    }
+    throw promiseOrSignal
+  }
+  // 2. if it's a signal, we save it into ref to make sure it's not garbage collected while component exists
+  const $signalRef = useRef() // eslint-disable-line react-hooks/rules-of-hooks
+  if ($signalRef.current !== promiseOrSignal) $signalRef.current = promiseOrSignal
+  return promiseOrSignal
+}
+
+export function setTestThrottling (ms) {
+  if (typeof ms !== 'number') throw Error('setTestThrottling() accepts only a number in ms')
+  if (ms === 0) throw Error('setTestThrottling(0) is not allowed, use resetTestThrottling() instead')
+  if (ms < 0) throw Error('setTestThrottling() accepts only a positive number in ms')
+  TEST_THROTTLING = ms
+}
+export function resetTestThrottling () {
+  TEST_THROTTLING = false
+}

package/utils/setDiffDeep.js

@@ -0,0 +1,28 @@
+export default function setDiffDeep (existing, updated) {
+  // Handle primitive types, null, and type mismatches
+  if (existing === null || updated === null ||
+      typeof existing !== 'object' || typeof updated !== 'object' ||
+      Array.isArray(existing) !== Array.isArray(updated)) {
+    return updated
+  }
+
+  // Handle arrays
+  if (Array.isArray(updated)) {
+    existing.length = updated.length
+    for (let i = 0; i < updated.length; i++) {
+      existing[i] = setDiffDeep(existing[i], updated[i])
+    }
+    return existing
+  }
+
+  // Handle objects
+  for (const key in existing) {
+    if (!(key in updated)) {
+      delete existing[key]
+    }
+  }
+  for (const key in updated) {
+    existing[key] = setDiffDeep(existing[key], updated[key])
+  }
+  return existing
+}