teamplay 0.0.1

package/orm/Query.js

@@ -0,0 +1,278 @@
+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'
+
+const ERROR_ON_EXCESSIVE_UNSUBSCRIBES = false
+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 {
+  subscribing
+  unsubscribing
+  subscribed
+  initialized
+  shareQuery
+
+  constructor (collection, params) {
+    this.collection = collection
+    this.params = params
+    this.hash = hashQuery([this.collection], this.params)
+    this.docSignals = new Set()
+  }
+
+  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.params], err)
+        this.subscribed = undefined
+        throw err
+      } finally {
+        this.subscribing = undefined
+      }
+    })()
+    await this.subscribing
+  }
+
+  async _subscribe () {
+    await new Promise((resolve, reject) => {
+      const method = fetchOnly ? 'createFetchQuery' : 'createSubscribeQuery'
+      this.shareQuery = getConnection()[method](this.collection, this.params, {}, 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.params], err)
+        this.subscribed = true
+        throw err
+      } finally {
+        this.unsubscribing = undefined
+      }
+    })()
+    await this.unsubscribing
+  }
+
+  async _unsubscribe () {
+    if (!this.shareQuery) throw Error('this.shareQuery is not defined. This should never happen')
+    await new Promise((resolve, reject) => {
+      this.shareQuery.destroy(err => {
+        if (err) return reject(err)
+        resolve()
+      })
+      this.shareQuery = undefined
+    })
+  }
+
+  _initData () {
+    { // reference the fetched docs
+      const docs = this.shareQuery.results.map(doc => raw(doc.data))
+      _set([QUERIES, this.hash, 'docs'], docs)
+
+      const ids = this.shareQuery.results.map(doc => doc.id)
+      for (const docId of ids) {
+        const $doc = getSignal(undefined, [this.collection, docId])
+        docSubscriptions.init($doc)
+        this.docSignals.add($doc)
+      }
+      _set([QUERIES, this.hash, 'ids'], ids)
+    }
+
+    this.shareQuery.on('insert', (shareDocs, index) => {
+      const newDocs = shareDocs.map(doc => raw(doc.data))
+      _get([QUERIES, this.hash, 'docs']).splice(index, 0, ...newDocs)
+
+      const ids = shareDocs.map(doc => doc.id)
+      for (const docId of ids) {
+        const $doc = getSignal(undefined, [this.collection, docId])
+        docSubscriptions.init($doc)
+        this.docSignals.add($doc)
+      }
+      _get([QUERIES, this.hash, 'ids']).splice(index, 0, ...ids)
+    })
+    this.shareQuery.on('move', (shareDocs, from, to) => {
+      const docs = _get([QUERIES, this.hash, 'docs'])
+      docs.splice(from, shareDocs.length)
+      docs.splice(to, 0, ...shareDocs.map(doc => raw(doc.data)))
+
+      const ids = _get([QUERIES, this.hash, 'ids'])
+      ids.splice(from, shareDocs.length)
+      ids.splice(to, 0, ...shareDocs.map(doc => doc.id))
+    })
+    this.shareQuery.on('remove', (shareDocs, index) => {
+      const docs = _get([QUERIES, this.hash, 'docs'])
+      docs.splice(index, shareDocs.length)
+
+      const docIds = shareDocs.map(doc => doc.id)
+      for (const docId of docIds) {
+        const $doc = getSignal(undefined, [this.collection, docId])
+        this.docSignals.delete($doc)
+      }
+      const ids = _get([QUERIES, this.hash, 'ids'])
+      ids.splice(index, docIds.length)
+    })
+  }
+
+  _removeData () {
+    this.docSignals.clear()
+    _del([QUERIES, this.hash])
+  }
+}
+
+class QuerySubscriptions {
+  constructor () {
+    this.subCount = new Map()
+    this.queries = new Map()
+    this.fr = new FinalizationRegistry(({ segments, params }) => this.destroy(segments, params))
+  }
+
+  subscribe ($query) {
+    const segments = [...$query[SEGMENTS]]
+    const params = JSON.parse(JSON.stringify($query[PARAMS]))
+    const hash = hashQuery(segments, params)
+    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)
+
+    let query = this.queries.get(hash)
+    if (!query) {
+      query = new Query(segments[0], 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)
+    let count = this.subCount.get(hash) || 0
+    count -= 1
+    if (count < 0) {
+      if (ERROR_ON_EXCESSIVE_UNSUBSCRIBES) throw ERRORS.notSubscribed($query)
+      return
+    }
+    if (count > 0) {
+      this.subCount.set(hash, count)
+      return
+    }
+    this.subCount.delete(hash)
+    this.fr.unregister($query)
+    const query = this.queries.get(hash)
+    await query.unsubscribe()
+    if (query.subscribed) return // if we subscribed again while waiting for unsubscribe, we don't delete the doc
+    this.queries.delete(hash)
+  }
+
+  async destroy (segments, params) {
+    const hash = hashQuery(segments, params)
+    const query = this.queries.get(hash)
+    if (!query) return
+    this.subCount.delete(hash)
+    await query.unsubscribe()
+    if (query.subscribed) return // if we subscribed again while waiting for unsubscribe, we don't delete the doc
+    this.queries.delete(hash)
+  }
+}
+
+export const querySubscriptions = new QuerySubscriptions()
+
+export function hashQuery (segments, params) {
+  // TODO: probably makes sense to use fast-stable-json-stringify for this because of the params
+  return JSON.stringify({ query: [segments[0], params] })
+}
+
+export function getQuerySignal (segments, params, options) {
+  params = JSON.parse(JSON.stringify(params))
+  const hash = hashQuery(segments, params)
+
+  const $query = getSignal(undefined, segments, {
+    signalHash: hash,
+    ...options
+  })
+  $query[IS_QUERY] ??= true
+  $query[PARAMS] ??= params
+  $query[HASH] ??= hash
+  return $query
+}
+
+const ERRORS = {
+  notSubscribed: $doc => Error('trying to unsubscribe when not subscribed. Doc: ' + $doc.path())
+}

package/orm/Reaction.js

@@ -0,0 +1,44 @@
+import { observe, unobserve } from '@nx-js/observer-util'
+import { SEGMENTS } from './Signal.js'
+import { set as _set, del as _del } from './dataTree.js'
+import { LOCAL } from './Value.js'
+
+// this is `let` to be able to directly change it if needed in tests or in the app
+export let DELETION_DELAY = 0 // eslint-disable-line prefer-const
+
+class ReactionSubscriptions {
+  constructor () {
+    this.initialized = new Map()
+    this.fr = new FinalizationRegistry(([id, reaction]) => this.destroy(id, reaction))
+  }
+
+  init ($value, fn) {
+    const id = $value[SEGMENTS][1]
+    if (this.initialized.has(id)) return
+
+    this.initialized.set(id, true)
+    const reactionScheduler = reaction => runReaction(id, reaction)
+    const reaction = observe(fn, { lazy: true, scheduler: reactionScheduler })
+    this.fr.register($value, [id, reaction])
+    runReaction(id, reaction)
+  }
+
+  destroy (id, reaction) {
+    this.initialized.delete(id)
+    unobserve(reaction)
+    // don't delete data right away to prevent dependent reactions which are also going to be GC'ed
+    // from triggering unnecessarily
+    setTimeout(() => _del([LOCAL, id]), DELETION_DELAY)
+  }
+}
+
+export const reactionSubscriptions = new ReactionSubscriptions()
+
+function runReaction (id, reaction) {
+  const newValue = reaction()
+  _set([LOCAL, id], newValue)
+}
+
+export function setDeletionDelay (delayInMs) {
+  DELETION_DELAY = delayInMs
+}

package/orm/Root.js

@@ -0,0 +1,41 @@
+import getSignal from './getSignal.js'
+
+export const ROOT_FUNCTION = Symbol('root function')
+// TODO: in future make a connection spawnable instead of a singleton
+// export const CONNECTION = Symbol('sharedb connection, used by sub() function')
+export const ROOT = Symbol('root signal')
+export const ROOT_ID = Symbol('root signal id. Used for caching')
+
+export const GLOBAL_ROOT_ID = '__global__'
+
+// TODO: create a separate local root for private collections
+export function getRootSignal ({
+  rootFunction,
+  // connection,
+  rootId = '_' + createRandomString(8),
+  ...options
+}) {
+  const $root = getSignal(undefined, [], {
+    rootId,
+    ...options
+  })
+  $root[ROOT_FUNCTION] ??= rootFunction
+  // $root[CONNECTION] ??= connection
+  $root[ROOT_ID] ??= rootId
+  return $root
+}
+
+export function getRoot (signal) {
+  if (signal[ROOT]) return signal[ROOT]
+  else if (signal[ROOT_ID]) return signal
+  else return undefined
+}
+
+function createRandomString (length) {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+  let result = ''
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length))
+  }
+  return result
+}

package/orm/Signal.js

@@ -0,0 +1,211 @@
+/**
+ * Implementation of the BaseSignal class which is used as a base class for all signals
+ * and can be extended to create custom models for a particular path pattern of the data tree.
+ *
+ * All signals in the app should be created using getSignal() function which automatically
+ * determines the correct model for the given path pattern and wraps the signal object in a Proxy.
+ *
+ * Proxy is used for the following reasons:
+ * 1. To allow accessing child signals using dot syntax
+ * 2. To be able to call the top-level signal as a `$()` function
+ * 3. If extremely late bindings are enabled, to prevent name collisions when accessing fields
+ *    in the raw data tree which have the same name as signal's methods
+ */
+import { get as _get, set as _set, del as _del, setPublicDoc as _setPublicDoc } from './dataTree.js'
+import getSignal, { rawSignal } from './getSignal.js'
+import { IS_QUERY, HASH, QUERIES } from './Query.js'
+import { ROOT_FUNCTION, getRoot } from './Root.js'
+import uuid from '../utils/uuid.cjs'
+
+export const SEGMENTS = Symbol('path segments targeting the particular node in the data tree')
+
+export default class Signal extends Function {
+  constructor (segments) {
+    if (!Array.isArray(segments)) throw Error('Signal constructor expects an array of segments')
+    super()
+    this[SEGMENTS] = segments
+  }
+
+  path () {
+    if (arguments.length > 0) throw Error('Signal.path() does not accept any arguments')
+    return this[SEGMENTS].join('.')
+  }
+
+  id () {
+    return uuid()
+  }
+
+  get () {
+    if (arguments.length > 0) throw Error('Signal.get() does not accept any arguments')
+    if (this[IS_QUERY]) {
+      const hash = this[HASH]
+      return _get([QUERIES, hash, 'docs'])
+    }
+    return _get(this[SEGMENTS])
+  }
+
+  * [Symbol.iterator] () {
+    if (this[IS_QUERY]) {
+      const ids = _get([QUERIES, this[HASH], 'ids'])
+      for (const id of ids) yield getSignal(getRoot(this), [this[SEGMENTS][0], id])
+    } else {
+      const items = _get(this[SEGMENTS])
+      if (!Array.isArray(items)) return
+      for (let i = 0; i < items.length; i++) yield getSignal(getRoot(this), [...this[SEGMENTS], i])
+    }
+  }
+
+  map (...args) {
+    if (this[IS_QUERY]) {
+      const collection = this[SEGMENTS][0]
+      const hash = this[HASH]
+      const ids = _get([QUERIES, hash, 'ids'])
+      return ids.map(id => getSignal(getRoot(this), [collection, id])).map(...args)
+    }
+    const items = _get(this[SEGMENTS])
+    if (!Array.isArray(items)) return []
+    return Array(items.length)
+      .fill()
+      .map((_, index) => getSignal(getRoot(this), [...this[SEGMENTS], index]))
+      .map(...args)
+  }
+
+  async set (value) {
+    if (arguments.length > 1) throw Error('Signal.set() expects a single argument')
+    if (this[SEGMENTS].length === 0) throw Error('Can\'t set the root signal data')
+    if (isPublicCollection(this[SEGMENTS][0])) {
+      await _setPublicDoc(this[SEGMENTS], value)
+    } else {
+      _set(this[SEGMENTS], value)
+    }
+  }
+
+  // TODO: make it use an actual increment json0 operation on public collections
+  async increment (value) {
+    if (arguments.length > 1) throw Error('Signal.increment() expects a single argument')
+    if (value === undefined) value = 1
+    if (typeof value !== 'number') throw Error('Signal.increment() expects a number argument')
+    let currentValue = this.get()
+    if (currentValue === undefined) currentValue = 0
+    if (typeof currentValue !== 'number') throw Error('Signal.increment() tried to increment a non-number value')
+    await this.set(currentValue + value)
+  }
+
+  async add (value) {
+    if (arguments.length > 1) throw Error('Signal.add() expects a single argument')
+    let id
+    if (value.id) {
+      value = JSON.parse(JSON.stringify(value))
+      id = value.id
+      delete value.id
+    }
+    id ??= uuid()
+    await this[id].set(value)
+  }
+
+  async del () {
+    if (arguments.length > 0) throw Error('Signal.del() does not accept any arguments')
+    if (this[SEGMENTS].length === 0) throw Error('Can\'t delete the root signal data')
+    if (isPublicCollection(this[SEGMENTS][0])) {
+      if (this[SEGMENTS].length === 1) throw Error('Can\'t delete the whole collection')
+      await _setPublicDoc(this[SEGMENTS], undefined, true)
+    } else {
+      _del(this[SEGMENTS])
+    }
+  }
+
+  // clone () {}
+  // async assign () {}
+  // async push () {}
+  // async pop () {}
+  // async unshift () {}
+  // async shift () {}
+  // async splice () {}
+  // async move () {}
+  // async del () {}
+}
+
+// dot syntax returns a child signal only if no such method or property exists
+export const regularBindings = {
+  apply (signal, thisArg, argumentsList) {
+    if (signal[SEGMENTS].length === 0) {
+      if (!signal[ROOT_FUNCTION]) throw Error(ERRORS.noRootFunction)
+      return signal[ROOT_FUNCTION].call(thisArg, signal, ...argumentsList)
+    }
+    throw Error('Signal can\'t be called as a function since extremely late bindings are disabled')
+  },
+  get (signal, key, receiver) {
+    if (key in signal) return Reflect.get(signal, key, receiver)
+    return Reflect.apply(extremelyLateBindings.get, this, arguments)
+  }
+}
+
+const QUERY_METHODS = ['map', 'get']
+
+// dot syntax always returns a child signal even if such method or property exists.
+// The method is only called when the signal is explicitly called as a function,
+// in which case we get the original method from the raw (non-proxied) parent signal
+export const extremelyLateBindings = {
+  apply (signal, thisArg, argumentsList) {
+    if (signal[SEGMENTS].length === 0) {
+      if (!signal[ROOT_FUNCTION]) throw Error(ERRORS.noRootFunction)
+      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('.')}"`)
+    }
+    return Reflect.apply(rawParent[key], $parent, argumentsList)
+  },
+  get (signal, key, receiver) {
+    if (typeof key === 'symbol') return Reflect.get(signal, key, receiver)
+    if (key === 'then') return undefined // handle checks for whether the symbol is a Promise
+    key = transformAlias(signal[SEGMENTS], key)
+    if (signal[IS_QUERY]) {
+      if (key === 'ids') return getSignal(getRoot(signal), [QUERIES, signal[HASH], 'ids'])
+      if (QUERY_METHODS.includes(key)) return Reflect.get(signal, key, receiver)
+    }
+    return getSignal(getRoot(signal), [...signal[SEGMENTS], key])
+  }
+}
+
+const transformAlias = (({
+  collectionsMapping = {
+    session: '_session',
+    page: '_page',
+    render: '$render',
+    system: '$system'
+  },
+  regex$ = /^\$/
+} = {}) => (segments, key) => {
+  if (regex$.test(key)) key = key.slice(1)
+  if (segments.length === 0) key = collectionsMapping[key] || key
+  return key
+})()
+
+export function isPublicCollectionSignal ($signal) {
+  return $signal instanceof Signal && $signal[SEGMENTS].length === 1 && isPublicCollection($signal[SEGMENTS][0])
+}
+
+export function isPublicDocumentSignal ($signal) {
+  return $signal instanceof Signal && $signal[SEGMENTS].length === 2 && isPublicCollection($signal[SEGMENTS][0])
+}
+
+export function isPublicCollection (collectionName) {
+  if (!collectionName) return false
+  return !isPrivateCollection(collectionName)
+}
+
+export function isPrivateCollection (collectionName) {
+  if (!collectionName) return false
+  return /^[_$]/.test(collectionName)
+}
+
+const ERRORS = {
+  noRootFunction: `
+    Root signal does not have a root function set.
+    You must use getRootSignal({ rootId, rootFunction }) to create a root signal.
+  `
+}

package/orm/Value.js

@@ -0,0 +1,27 @@
+import { SEGMENTS } from './Signal.js'
+import { set as _set, del as _del } from './dataTree.js'
+
+export const LOCAL = '$local'
+
+class ValueSubscriptions {
+  constructor () {
+    this.initialized = new Map()
+    this.fr = new FinalizationRegistry(id => this.destroy(id))
+  }
+
+  init ($value, value) {
+    const id = $value[SEGMENTS][1]
+    if (this.initialized.has(id)) return
+
+    _set([LOCAL, id], value)
+    this.initialized.set(id, true)
+    this.fr.register($value, id)
+  }
+
+  destroy (id) {
+    this.initialized.delete(id)
+    _del([LOCAL, id])
+  }
+}
+
+export const valueSubscriptions = new ValueSubscriptions()

package/orm/addModel.js

@@ -0,0 +1,31 @@
+export const MODELS = {}
+
+export default function addModel (pattern, Model) {
+  if (typeof pattern !== 'string') throw Error('Model pattern must be a string, e.g. "users.*"')
+  if (/\s/.test(pattern)) throw Error('Model pattern can not have spaces')
+  if (typeof Model !== 'function') throw Error('Model must be a class')
+  pattern = pattern.replace(/\[[^\]]+\]/g, '*') // replace `[id]` with `*`
+  if (pattern !== '' && pattern.split('.').some(segment => segment === '')) {
+    throw Error('Model pattern can not have empty segments')
+  }
+  if (MODELS[pattern]) throw Error(`Model for pattern "${pattern}" already exists`)
+  MODELS[pattern] = Model
+}
+
+export function findModel (segments) {
+  // if segments is an empty array, treat it as a top-level signal.
+  // Top-level signal class is the one that has an empty string as a pattern.
+  if (segments.length === 0) segments = ['']
+  for (const pattern in MODELS) {
+    const patternSegments = pattern.split('.')
+    if (segments.length !== patternSegments.length) continue
+    let match = true
+    for (let i = 0; i < segments.length; i++) {
+      if (patternSegments[i] !== '*' && patternSegments[i] !== segments[i]) {
+        match = false
+        break
+      }
+    }
+    if (match) return MODELS[pattern]
+  }
+}

package/orm/connection.js

@@ -0,0 +1,26 @@
+export let connection
+export let fetchOnly
+
+export function setConnection (_connection) {
+  connection = _connection
+}
+
+export function getConnection () {
+  if (!connection) throw Error(ERRORS.notSet)
+  return connection
+}
+
+export function setFetchOnly (_fetchOnly) {
+  fetchOnly = _fetchOnly
+}
+
+const ERRORS = {
+  notSet: `
+    Connection is not set.
+    You must set the initialized ShareDB connection before using subscriptions.
+    You've probably forgotten to call connect() in your app:
+
+    import connect from '@startupjs/signals-orm/connect'
+    connect({ baseUrl: 'http://localhost:3000' })
+  `
+}