teamplay 0.1.4 → 0.1.6

package/README.md

@@ -30,14 +30,37 @@ 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:
+On the server you need to create the teamplay's backend and then create a connection handler for WebSockets:
 
 ```js
-import { initConnection } from 'teamplay/server'
-const { upgrade } = initConnection(backend) // ShareDB's Backend instance
+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
@@ -45,16 +68,17 @@ 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'
-import { createRoot } from 'react-dom/client'
-import { createElement as el } from 'react'
 
 connect()
 
@@ -62,14 +86,12 @@ 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 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(
-  el(App, { userId: '_1' })
-)
+createRoot(container).render(<App userId='_1' />)
 ```
 
 On the server we create the ShareDB backend and initialize the WebSocket connections handler:
@@ -77,21 +99,19 @@ On the server we create the ShareDB backend and initialize the WebSocket connect
 ```js
 // server.js
 import http from 'http'
-import { ShareDB, initConnection } from 'teamplay/server'
+import { createBackend, initConnection } from 'teamplay/server'
 
 const server = http.createServer() // you can pass expressApp here if needed
-const backend = new ShareDB()
+const backend = createBackend()
 const { upgrade } = initConnection(backend)
 
 server.on('upgrade', upgrade)
 
-server.listen(3000)
+server.listen(3000, () => {
+  console.log('Server started. Open http://localhost:3000 in your browser')
+})
 ```
 
-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/index.js

@@ -16,9 +16,8 @@ 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 { GUID_PATTERN, hasMany, hasOne, hasManyFlags, belongsTo, pickFormFields } from '@teamplay/schema'
+export { aggregation, aggregationHeader } from '@teamplay/utils/aggregation'
 
 export function getRootSignal (options) {
   return _getRootSignal({

package/orm/Cache.js

@@ -1,3 +1,6 @@
+import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
+import WeakRef, { destroyMockWeakRef } from '../utils/MockWeakRef.js'
+
 export default class Cache {
   constructor () {
     this.cache = new Map()
@@ -20,6 +23,7 @@ export default class Cache {
   }
 
   delete (key) {
+    destroyMockWeakRef(this.cache.get(key)) // TODO: remove this when WeakRef is available in RN
     this.cache.delete(key)
   }
 

package/orm/Doc.js

@@ -2,6 +2,7 @@ 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'
+import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
 
 const ERROR_ON_EXCESSIVE_UNSUBSCRIBES = false
 

package/orm/Query.js

@@ -4,6 +4,7 @@ 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 PARAMS = Symbol('query params')

package/orm/Reaction.js

@@ -2,6 +2,7 @@ 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'
+import FinalizationRegistry from '../utils/MockFinalizationRegistry.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

package/orm/Value.js

@@ -1,5 +1,6 @@
 import { SEGMENTS } from './Signal.js'
 import { set as _set, del as _del } from './dataTree.js'
+import FinalizationRegistry from '../utils/MockFinalizationRegistry.js'
 
 export const LOCAL = '$local'
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Full-stack signals ORM with multiplayer",
   "type": "module",
   "main": "index.js",
@@ -9,7 +9,8 @@
     "./connect": "./connect/index.js",
     "./server": "./server.js",
     "./connect-test": "./connect/test.js",
-    "./cache": "./cache.js"
+    "./cache": "./cache.js",
+    "./schema": "./schema.js"
   },
   "publishConfig": {
     "access": "public"
@@ -22,9 +23,12 @@
   },
   "dependencies": {
     "@nx-js/observer-util": "^4.1.3",
-    "@teamplay/cache": "^0.1.4",
-    "@teamplay/channel": "^0.1.4",
-    "@teamplay/debug": "^0.1.4",
+    "@teamplay/backend": "^0.1.6",
+    "@teamplay/cache": "^0.1.6",
+    "@teamplay/channel": "^0.1.6",
+    "@teamplay/debug": "^0.1.6",
+    "@teamplay/schema": "^0.1.6",
+    "@teamplay/utils": "^0.1.6",
     "diff-match-patch": "^1.0.5",
     "events": "^3.3.0",
     "json0-ot-diff": "^1.1.2",
@@ -37,6 +41,8 @@
     "@testing-library/react": "^15.0.7",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "sharedb-mingo-memory": "^3.0.1"
   },
   "peerDependencies": {
@@ -58,5 +64,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "3c6c4f6dd9fcfaa4e2a7f28c5ce989e6f7c4b133"
+  "gitHead": "97787add00d5543476304ab577a3550da916debe"
 }

package/schema.js

@@ -0,0 +1 @@
+export * from '@teamplay/schema'

package/server.js

@@ -2,11 +2,18 @@ import createChannel from '@teamplay/channel/server'
 import { connection, setConnection, setFetchOnly } from './orm/connection.js'
 
 export { default as ShareDB } from 'sharedb'
+export {
+  default as createBackend,
+  mongo, mongoClient, createMongoIndex, redis, redlock, sqlite
+} from '@teamplay/backend'
 
-export default function initConnection (backend, options) {
+export function initConnection (backend, {
+  fetchOnly = true,
+  ...options
+} = {}) {
   if (!backend) throw Error('backend is required')
   if (connection) throw Error('Connection already exists')
   setConnection(backend.connect())
-  setFetchOnly(true)
+  setFetchOnly(fetchOnly)
   return createChannel(backend, options)
 }

package/utils/MockFinalizationRegistry.js

@@ -0,0 +1,66 @@
+export const REGISTRY_FINALIZE_AFTER = 10_000
+export const REGISTRY_SWEEP_INTERVAL = 10_000
+
+// This is a mock implementation of FinalizationRegistry that uses setTimeout to
+// schedule the sweep of outdated objects.
+// It is used in environments where FinalizationRegistry is not available.
+// For now we permanently keep the values in the registry until they are
+// manually unregistered since we don't have a way to know when the object is
+// no longer needed. In the future we might add the control logic to properly
+// invalidate the objects.
+export let PERMANENT = true
+export function setPermanent (permanent) { PERMANENT = permanent }
+
+export class TimerBasedFinalizationRegistry {
+  registrations = new Map()
+  sweepTimeout
+
+  constructor (finalize) {
+    this.finalize = finalize
+  }
+
+  // Token is actually required with this impl
+  register (target, value, token) {
+    this.registrations.set(token, {
+      value,
+      registeredAt: Date.now()
+    })
+    if (!PERMANENT) this.scheduleSweep()
+  }
+
+  unregister (token) {
+    this.registrations.delete(token)
+  }
+
+  // Bound so it can be used directly as setTimeout callback.
+  sweep = (maxAge = REGISTRY_FINALIZE_AFTER) => {
+    // cancel timeout so we can force sweep anytime
+    clearTimeout(this.sweepTimeout)
+    this.sweepTimeout = undefined
+
+    const now = Date.now()
+    this.registrations.forEach((registration, token) => {
+      if (now - registration.registeredAt >= maxAge) {
+        this.finalize(registration.value)
+        this.registrations.delete(token)
+      }
+    })
+
+    if (this.registrations.size > 0) {
+      this.scheduleSweep()
+    }
+  }
+
+  // Bound so it can be exported directly as clearTimers test utility.
+  finalizeAllImmediately = () => {
+    this.sweep(0)
+  }
+
+  scheduleSweep () {
+    if (this.sweepTimeout === undefined) {
+      this.sweepTimeout = setTimeout(this.sweep, REGISTRY_SWEEP_INTERVAL)
+    }
+  }
+}
+
+export default (typeof FinalizationRegistry !== 'undefined' ? FinalizationRegistry : TimerBasedFinalizationRegistry)

package/utils/MockWeakRef.js

@@ -0,0 +1,16 @@
+export class MockWeakRef {
+  constructor (value) {
+    this.value = value
+  }
+
+  deref () {
+    return this.value
+  }
+}
+
+export function destroyMockWeakRef (weakRef) {
+  if (!(weakRef instanceof MockWeakRef)) return
+  weakRef.value = undefined
+}
+
+export default (typeof WeakRef !== 'undefined' ? WeakRef : MockWeakRef)

package/CHANGELOG.md

@@ -1,45 +0,0 @@
-# v0.1.4 (Thu May 23 2024)
-
-#### 🐛 Bug Fix
-
-- fix: rename old references to startupjs packages into teamplay packages ([@cray0000](https://github.com/cray0000))
-
-#### Authors: 1
-
-- Pavel Zhukov ([@cray0000](https://github.com/cray0000))
-
----
-
-# v0.1.3 (Thu May 23 2024)
-
-#### 🐛 Bug Fix
-
-- fix: add 'events' since sharedb client requires it to work correctly ([@cray0000](https://github.com/cray0000))
-
-#### Authors: 1
-
-- Pavel Zhukov ([@cray0000](https://github.com/cray0000))
-
----
-
-# v0.1.2 (Thu May 23 2024)
-
-#### 🐛 Bug Fix
-
-- fix: re-export cache as 'teamplay/cache' ([@cray0000](https://github.com/cray0000))
-
-#### Authors: 1
-
-- Pavel Zhukov ([@cray0000](https://github.com/cray0000))
-
----
-
-# v0.1.1 (Thu May 23 2024)
-
-#### 🐛 Bug Fix
-
-- fix: dummy. trigger version bump ([@cray0000](https://github.com/cray0000))
-
-#### Authors: 1
-
-- Pavel Zhukov ([@cray0000](https://github.com/cray0000))

package/schema/GUID_PATTERN.js

@@ -1 +0,0 @@
-export default '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'

package/schema/associations.js

@@ -1,51 +0,0 @@
-import GUID_PATTERN from './GUID_PATTERN.js'
-
-export function belongsTo (collectionName) {
-  return {
-    type: 'string',
-    pattern: GUID_PATTERN,
-    $association: {
-      type: 'belongsTo',
-      collection: collectionName
-    }
-  }
-}
-
-export function hasMany (collectionName) {
-  return {
-    type: 'array',
-    items: {
-      type: 'string',
-      pattern: GUID_PATTERN
-    },
-    $association: {
-      type: 'hasMany',
-      collection: collectionName
-    }
-  }
-}
-
-export function hasManyFlags (collectionName) {
-  return {
-    type: 'object',
-    patternProperties: {
-      [GUID_PATTERN]: { type: 'boolean' }
-    },
-    additionalProperties: false,
-    $association: {
-      type: 'hasManyFlags',
-      collection: collectionName
-    }
-  }
-}
-
-export function hasOne (collectionName) {
-  return {
-    type: 'string',
-    pattern: GUID_PATTERN,
-    $association: {
-      type: 'hasOne',
-      collection: collectionName
-    }
-  }
-}

package/schema/pickFormFields.js

@@ -1,104 +0,0 @@
-/**
- * Pick properties from json-schema to be used in a form.
- * Supports simplified schema (just the properties object) and full schema.
- * Performs extra transformations like auto-generating `label`.
- * `createdAt`, `updatedAt`, `id`, `_id` fields are excluded by default.
- * @param {Object} schema
- * @param {Object|Array} options - exclude or include fields. If array, it's the same as passing { include: [...] }
- * @param {Array} options.include - list of fields to pick (default: all)
- * @param {Array} options.exclude - list of fields to exclude (default: none)
- * @param {Boolean} options.freeze - whether to deep freeze the result (default: true)
- */
-export default function pickFormFields (schema, options) {
-  try {
-    let include, exclude, freeze
-    if (Array.isArray(options)) {
-      include = options
-    } else {
-      ;({ include, exclude, freeze = true } = options || {})
-    }
-    exclude ??= []
-    if (!schema) throw Error('pickFormFields: schema is required')
-    schema = JSON.parse(JSON.stringify(schema))
-    if (schema.type === 'object') {
-      schema = schema.properties
-    }
-    for (const key in schema) {
-      if (shouldIncludeField(key, schema[key], { include, exclude })) {
-        const field = schema[key]
-        if (!field.label) field.label = camelCaseToLabel(key)
-      } else {
-        delete schema[key]
-      }
-    }
-    if (freeze) return new Proxy(schema, deepFreezeHandler)
-    return schema
-  } catch (err) {
-    throw Error(`
-      pickFormFields: ${err.message}
-      schema:\n${JSON.stringify(schema, null, 2)}
-    `)
-  }
-}
-
-// Proxy handlers to deep freeze schema to prevent accidental mutations.
-// For this, when we .get() a property, we also return the same recursive Proxy handler if it's an object.
-const deepFreezeHandler = {
-  get (target, prop) {
-    const value = target[prop]
-    if (typeof value === 'object' && value !== null) {
-      return new Proxy(value, deepFreezeHandler)
-    }
-    return value
-  },
-  set () {
-    throw Error(ERRORS.schemaIsFrozen)
-  }
-}
-
-function shouldIncludeField (key, field, { include, exclude = [] } = {}) {
-  if (!field) throw Error(`field "${key}" does not have a schema definition`)
-  if (include?.includes(key)) return true
-  if (exclude.includes(key)) return false
-  // if field has 'input' specified then it's an explicit indicator that it can be used in forms,
-  // so the default exclusion rules don't apply
-  if (!field.input) {
-    // exclude some meta fields by default
-    if (DEFAULT_EXCLUDE_FORM_FIELDS.includes(key)) return false
-    // exclude foreign keys by default
-    // Foreign keys have a custom `$association` property set by belongsTo/hasMany/hasOne helpers
-    if (field.$association) return false
-  }
-  // if include array is not explicitly set, include all fields by default
-  if (!include) return true
-  return false
-}
-
-const DEFAULT_EXCLUDE_FORM_FIELDS = ['id', '_id', 'createdAt', 'updatedAt']
-
-// split into words, capitalize first word, make others lowercase
-function camelCaseToLabel (str) {
-  return str
-    .replace(/([A-Z])/g, ' $1')
-    .toLowerCase()
-    .replace(/^./, (s) => s.toUpperCase())
-}
-
-const ERRORS = {
-  schemaIsFrozen: `
-    Form fields are immutable.
-    If you want to change them, clone them with \`JSON.parse(JSON.stringify(FORM_FIELDS))\`.
-
-    If you want to do it inside react component, you can use this pattern for the most effective cloning:
-
-    \`\`\`
-        const $fields = useValue$(useMemo(() => JSON.parse(JSON.stringify(FORM_FIELDS)), []))
-    \`\`\`
-
-    and then pass $fields to the Form component like this:
-
-    \`\`\`
-        <Form $fields={$fields} $value={$value} />
-    \`\`\`
-  `
-}