teamplay 0.0.1

package/README.md

@@ -0,0 +1,95 @@
+# TeamPlay
+
+> Deep signals ORM for React with real-time collaboration
+
+Features:
+
+- signals __*__
+- multiplayer __**__
+- ORM
+- auto-sync data from client to DB and vice-versa __***__
+- query DB directly from client __***__
+
+> __*__ deep signals -- with support for objects and arrays\
+> __**__ concurrent changes to the same data are auto-merged using [OT](https://en.wikipedia.org/wiki/Operational_transformation)\
+> __***__ similar to Firebase but with your own MongoDB-compatible database
+
+## 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()
+```
+
+And on the server, manually create a [ShareDB's backend](https://share.github.io/sharedb/api/backend) and create a connection handler for WebSockets:
+
+```js
+import { initConnection } from 'teamplay/server'
+const { upgrade } = initConnection(backend) // ShareDB's Backend instance
+server.on('upgrade', upgrade) // Node's 'http' server instance
+```
+
+## Usage
+
+TBD
+
+## Examples
+
+### 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 connect from 'teamplay/connect'
+import { observer, $, sub } from 'teamplay'
+import { createRoot } from 'react-dom/client'
+import { createElement as el } from 'react'
+
+connect()
+
+const App = observer(({ userId }) => {
+  const $user = sub($.users[userId])
+  if (!$user.get()) throw $user.set({ points: 0 })
+  const { $points } = $user
+  const onClick = () => $points.set($points.get() + 1)
+  return el('button', { onClick }, 'Points: ' + $points.get())
+})
+
+const container = document.body.appendChild(document.createElement('div'))
+createRoot(container).render(
+  el(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 { ShareDB, initConnection } from 'teamplay/server'
+
+const server = http.createServer() // you can pass expressApp here if needed
+const backend = new ShareDB()
+const { upgrade } = initConnection(backend)
+
+server.on('upgrade', upgrade)
+
+server.listen(3000)
+```
+
+ShareDB is a re-export of [`sharedb`](https://github.com/share/sharedb) library, check its docs for more info.
+- for persistency and queries support pass [`sharedb-mongo`](https://github.com/share/sharedb-mongo) (which uses MongoDB) as `{ db }`
+- when deploying to a cluster with multiple instances you also have to provide `{ pubsub }` like [`sharedb-redis-pubsub`](https://github.com/share/sharedb-redis-pubsub) (which uses Redis)
+
+## License
+
+MIT

package/connect/index.js

@@ -0,0 +1,12 @@
+import Socket from '@startupjs/channel'
+import Connection from './sharedbConnection.cjs'
+import { connection, setConnection } from '../orm/connection.js'
+
+export default function connect ({
+  baseUrl,
+  ...options
+} = {}) {
+  if (connection) return
+  const socket = new Socket({ baseUrl, ...options })
+  setConnection(new Connection(socket))
+}

package/connect/sharedbConnection.cjs

@@ -0,0 +1,3 @@
+const ShareDB = require('sharedb/lib/client')
+
+module.exports = ShareDB.Connection

package/connect/test.js

@@ -0,0 +1,12 @@
+// mock of client connection to sharedb to use inside tests.
+// This just creates a sharedb server with in-memory database
+// and creates a server connection to it.
+import ShareBackend from 'sharedb'
+import ShareDbMingo from 'sharedb-mingo-memory'
+import { connection, setConnection } from '../orm/connection.js'
+
+export default function connect () {
+  if (connection) return
+  const backend = new ShareBackend({ db: new ShareDbMingo() })
+  setConnection(backend.connect())
+}

package/index.js

@@ -0,0 +1,44 @@
+// NOTE:
+//   $() and sub() are currently set to be universal ones which work in both
+//   plain JS and React environments. In React they are tied to the observer() HOC.
+//   This is done to simplify the API.
+//   In future, we might want to separate the plain JS and React APIs
+import { getRootSignal as _getRootSignal, GLOBAL_ROOT_ID } from './orm/Root.js'
+import universal$ from './react/universal$.js'
+
+export { default as Signal, SEGMENTS } from './orm/Signal.js'
+export { __DEBUG_SIGNALS_CACHE__, rawSignal, getSignalClass } from './orm/getSignal.js'
+export { default as addModel } from './orm/addModel.js'
+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 observer } from './react/observer.js'
+export { connection, setConnection, getConnection, fetchOnly, setFetchOnly } from './orm/connection.js'
+export * from './schema/associations.js'
+export { default as GUID_PATTERN } from './schema/GUID_PATTERN.js'
+export { default as pickFormFields } from './schema/pickFormFields.js'
+
+export function getRootSignal (options) {
+  return _getRootSignal({
+    rootFunction: universal$,
+    ...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/$.js

@@ -0,0 +1,38 @@
+// this is just the $() function implementation.
+// The actual $ exported from this package is a Proxy targeting the dataTree root,
+// and this function is an implementation of the `apply` handler for that Proxy.
+import getSignal from './getSignal.js'
+import Signal from './Signal.js'
+import { LOCAL, valueSubscriptions } from './Value.js'
+import { reactionSubscriptions } from './Reaction.js'
+
+export { LOCAL } from './Value.js'
+
+let counter = 0
+
+function newIncrementalId () {
+  const id = `_${counter}`
+  counter += 1
+  return id
+}
+
+export default function $ ($root, value, id) {
+  if (!($root instanceof Signal)) throw Error('First argument of $() should be a Root Signal')
+  if (typeof value === 'function') {
+    return reaction$($root, value, id)
+  } else {
+    return value$($root, value, id)
+  }
+}
+
+function value$ ($root, value, id = newIncrementalId()) {
+  const $value = getSignal($root, [LOCAL, id])
+  valueSubscriptions.init($value, value)
+  return $value
+}
+
+function reaction$ ($root, fn, id = newIncrementalId()) {
+  const $value = getSignal($root, [LOCAL, id])
+  reactionSubscriptions.init($value, fn)
+  return $value
+}

package/orm/Cache.js

@@ -0,0 +1,29 @@
+export default class Cache {
+  constructor () {
+    this.cache = new Map()
+    this.fr = new FinalizationRegistry(([key]) => this.delete(key))
+  }
+
+  get (key) {
+    return this.cache.get(key)?.deref()
+  }
+
+  /**
+   * @param {string} key
+   * @param {*} value
+   * @param {Array} inputs - extra inputs to register with the finalization registry
+   *                         to hold strong references to them until the value is garbage collected
+   */
+  set (key, value, inputs = []) {
+    this.cache.set(key, new WeakRef(value))
+    this.fr.register(value, [key, ...inputs])
+  }
+
+  delete (key) {
+    this.cache.delete(key)
+  }
+
+  get size () {
+    return this.cache.size
+  }
+}

package/orm/Doc.js

@@ -0,0 +1,232 @@
+import { isObservable, observable } from '@nx-js/observer-util'
+import { set as _set, del as _del } from './dataTree.js'
+import { SEGMENTS } from './Signal.js'
+import { getConnection, fetchOnly } from './connection.js'
+
+const ERROR_ON_EXCESSIVE_UNSUBSCRIBES = false
+
+class Doc {
+  subscribing
+  unsubscribing
+  subscribed
+  initialized
+
+  constructor (collection, docId) {
+    this.collection = collection
+    this.docId = docId
+    this.init()
+  }
+
+  init () {
+    if (this.initialized) return
+    this.initialized = true
+    this._initData()
+  }
+
+  async subscribe () {
+    if (this.subscribed) throw Error('trying to subscribe while already subscribed')
+    this.subscribed = true
+    // if we are in the middle of unsubscribing, just wait for it to finish and then resubscribe
+    if (this.unsubscribing) {
+      try {
+        await this.unsubscribing
+      } catch (err) {
+        // if error happened during unsubscribing, it means that we are still subscribed
+        // so we don't need to do anything
+        return
+      }
+    }
+    if (this.subscribing) {
+      try {
+        await this.subscribing
+        // if we are already subscribing from the previous time, delegate logic to that
+        // and if it finished successfully, we are done.
+        return
+      } catch (err) {
+        // if error happened during subscribing, we'll just try subscribing again
+        // so we just ignore the error and proceed with subscribing
+        this.subscribed = true
+      }
+    }
+
+    if (!this.subscribed) return // cancel if we initiated unsubscribe while waiting
+
+    this.subscribing = (async () => {
+      try {
+        this.subscribing = this._subscribe()
+        await this.subscribing
+        this.init()
+      } catch (err) {
+        console.log('subscription error', [this.collection, this.docId], err)
+        this.subscribed = undefined
+        throw err
+      } finally {
+        this.subscribing = undefined
+      }
+    })()
+    await this.subscribing
+  }
+
+  async _subscribe () {
+    const doc = getConnection().get(this.collection, this.docId)
+    await new Promise((resolve, reject) => {
+      const method = fetchOnly ? 'fetch' : 'subscribe'
+      doc[method](err => {
+        if (err) return reject(err)
+        resolve()
+      })
+    })
+  }
+
+  async unsubscribe () {
+    if (!this.subscribed) throw Error('trying to unsubscribe while not subscribed')
+    this.subscribed = undefined
+    // if we are still handling the subscription, just wait for it to finish and then unsubscribe
+    if (this.subscribing) {
+      try {
+        await this.subscribing
+      } catch (err) {
+        // if error happened during subscribing, it means that we are still unsubscribed
+        // so we don't need to do anything
+        return
+      }
+    }
+    // if we are already unsubscribing from the previous time, delegate logic to that
+    if (this.unsubscribing) {
+      try {
+        await this.unsubscribing
+        return
+      } catch (err) {
+        // if error happened during unsubscribing, we'll just try unsubscribing again
+        this.subscribed = undefined
+      }
+    }
+
+    if (this.subscribed) return // cancel if we initiated subscribe while waiting
+
+    this.unsubscribing = (async () => {
+      try {
+        await this._unsubscribe()
+        this.initialized = undefined
+        this._removeData()
+      } catch (err) {
+        console.log('error unsubscribing', [this.collection, this.docId], err)
+        this.subscribed = true
+        throw err
+      } finally {
+        this.unsubscribing = undefined
+      }
+    })()
+    await this.unsubscribing
+  }
+
+  async _unsubscribe () {
+    const doc = getConnection().get(this.collection, this.docId)
+    await new Promise((resolve, reject) => {
+      doc.destroy(err => {
+        if (err) return reject(err)
+        resolve()
+      })
+    })
+  }
+
+  _initData () {
+    const doc = getConnection().get(this.collection, this.docId)
+    // TODO: JSON does not have `undefined`, so we'll be receiving `null`.
+    //       Handle this by converting all `null` to `undefined` in the doc's data tree.
+    //       To do this we'll probably need to in the `op` event update the data tree
+    //       and have a clone of the doc in our local data tree.
+    this._refData()
+    doc.on('load', () => this._refData())
+    doc.on('create', () => this._refData())
+    doc.on('del', () => _del([this.collection, this.docId]))
+  }
+
+  _refData () {
+    const doc = getConnection().get(this.collection, this.docId)
+    if (isObservable(doc.data)) return
+    if (doc.data == null) return
+    _set([this.collection, this.docId], doc.data)
+    doc.data = observable(doc.data)
+  }
+
+  _removeData () {
+    _del([this.collection, this.docId])
+  }
+}
+
+class DocSubscriptions {
+  constructor () {
+    this.subCount = new Map()
+    this.docs = new Map()
+    this.initialized = new Map()
+    this.fr = new FinalizationRegistry(segments => this.destroy(segments))
+  }
+
+  init ($doc) {
+    const segments = [...$doc[SEGMENTS]]
+    const hash = hashDoc(segments)
+    if (this.initialized.has(hash)) return
+    this.initialized.set(hash, true)
+
+    this.fr.register($doc, segments, $doc)
+
+    let doc = this.docs.get(hash)
+    if (!doc) {
+      doc = new Doc(...segments)
+      this.docs.set(hash, doc)
+    }
+    doc.init()
+  }
+
+  subscribe ($doc) {
+    const segments = [...$doc[SEGMENTS]]
+    const hash = hashDoc(segments)
+    let count = this.subCount.get(hash) || 0
+    count += 1
+    this.subCount.set(hash, count)
+    if (count > 1) return this.docs.get(hash).subscribing
+
+    this.init($doc)
+    const doc = this.docs.get(hash)
+    return doc.subscribe()
+  }
+
+  async unsubscribe ($doc) {
+    const segments = [...$doc[SEGMENTS]]
+    const hash = hashDoc(segments)
+    let count = this.subCount.get(hash) || 0
+    count -= 1
+    if (count < 0) {
+      if (ERROR_ON_EXCESSIVE_UNSUBSCRIBES) throw ERRORS.notSubscribed($doc)
+      return
+    }
+    if (count > 0) {
+      this.subCount.set(hash, count)
+      return
+    }
+    this.fr.unregister($doc)
+    this.destroy(segments)
+  }
+
+  async destroy (segments) {
+    const hash = hashDoc(segments)
+    const doc = this.docs.get(hash)
+    if (!doc) return
+    this.subCount.delete(hash)
+    this.initialized.delete(hash)
+    await doc.unsubscribe()
+    if (doc.subscribed) return // if we subscribed again while waiting for unsubscribe, we don't delete the doc
+    this.docs.delete(hash)
+  }
+}
+
+export const docSubscriptions = new DocSubscriptions()
+
+function hashDoc (segments) {
+  return JSON.stringify(segments)
+}
+
+const ERRORS = {
+  notSubscribed: $doc => Error('trying to unsubscribe when not subscribed. Doc: ' + $doc.path())
+}