teamplay 0.1.16 → 0.2.0

package/README.md

@@ -17,210 +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
-
-### Introduction to teamplay ORM
-
-teamplay is a powerful and easy-to-use ORM (Object-Relational Mapping) that allows you to work with your data in a natural, dot-notation style. It's designed to make data management in your app seamless and intuitive.
-
-#### The Big Idea: Deep Signals
-
-At the heart of teamplay is the concept of "deep signals." Think of your entire data structure as a big tree. With teamplay, you can navigate this tree using simple dot notation, just like you would access properties in a JavaScript object.
-
-For example, to access a user's name, you might write:
-
-```javascript
-$.users[userId].name
-```
-
-This creates a "signal" pointing to that specific piece of data. Signals are smart pointers that know how to get and set data, and they automatically update your app when the data changes.
-
-#### Public and Private Collections
-
-In teamplay, data is organized into collections. There are two types:
-
-1. **Public Collections**: These are shared across all users of your app. They typically start with a lowercase letter (e.g., `users`, `posts`).
-
-2. **Private Collections**: These are specific to each user or session. They start with an underscore or dollar sign (e.g., `_session`, `$page`).
-
-### Basic Operations on Signals
-
-Every signal in teamplay comes with a set of useful methods:
-
-- `.get()`: Retrieves the current value of the signal.
-- `.set(value)`: Updates the value of the signal.
-- `.del()`: Deletes the value (or removes an item from an array).
-
-Example:
-
-```javascript
-// Get a user's name
-const name = $.users[userId].name.get()
-
-// Update a user's name
-$.users[userId].name.set('Alice')
-
-// Delete a user's profile picture
-$.users[userId].profilePicture.del()
-```
-
-### The `$()` Function: Creating Local Signals
-
-The `$()` function is a powerful tool for creating local, reactive values:
-
-1. Creating a simple value:
-
-```javascript
-const $count = $(0)
-console.log($count.get()) // Outputs: 0
-$count.set(5)
-console.log($count.get()) // Outputs: 5
-```
-
-2. Creating a computed value (similar to a calculated spreadsheet cell):
-
-```javascript
-const $firstName = $('John')
-const $lastName = $('Doe')
-const $fullName = $(() => $firstName.get() + ' ' + $lastName.get())
-
-console.log($fullName.get()) // Outputs: "John Doe"
-$firstName.set('Jane')
-console.log($fullName.get()) // Outputs: "Jane Doe"
-```
-
-### The `sub()` Function: Subscribing to Data
-
-The `sub()` function is used to subscribe to data from the server:
-
-1. Subscribing to a single document:
-
-```javascript
-const $user = await sub($.users[userId])
-console.log($user.name.get())
-```
-
-2. Subscribing to a query (multiple documents):
-
-```javascript
-const $activeUsers = await sub($.users, { status: 'active' })
-```
-
-#### Working with Query Signals
-
-Query signals are special. They behave like a collection signal, but they're also iterable:
-
-```javascript
-// Iterate over active users
-for (const $user of $activeUsers) {
-  console.log($user.name.get())
-}
-
-// Or use array methods
-const names = $activeUsers.map($user => $user.name.get())
-```
-
-Each `$user` in the loop is a scoped signal for that specific user document.
-
-### Reactivity: Keeping Your App in Sync
-
-teamplay's reactivity system ensures that whenever data changes, any part of your app using that data updates automatically. This happens behind the scenes, so you don't have to manually track and update data dependencies.
-
-For example, if you're displaying a user's name in your app and that name changes in the database, teamplay will automatically update your app's UI to reflect the new name.
-
-This reactivity works for both public and private collections, local signals created with `$()`, and subscribed data from `sub()`.
-
-By using these tools and concepts, you can build powerful, real-time applications with ease using teamplay!
-
-## 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

@@ -18,7 +18,7 @@ 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({

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.16",
+  "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.16",
-    "@teamplay/cache": "^0.1.16",
-    "@teamplay/channel": "^0.1.16",
-    "@teamplay/debug": "^0.1.16",
-    "@teamplay/schema": "^0.1.16",
-    "@teamplay/utils": "^0.1.16",
+    "@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": "f6a404f330ec3b88d498fa08fbcdc65cb80e8bb4"
+  "gitHead": "34435bba6654d480cac0e809defc15e1d15bd543"
 }

package/react/useSub.js

@@ -1,13 +1,38 @@
-import { useRef } from 'react'
+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 (...args) {
-  const promiseOrSignal = sub(...args)
+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) throw promiseOrSignal
+  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
+}