teamplay 0.1.14 → 0.1.16

package/README.md

@@ -63,8 +63,118 @@ If you need the subscriptions to reactively update data whenever it changes (the
 
 ## Usage
 
-TBD
-...
+### 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
 

package/connect/index.js

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

package/index.js

@@ -13,7 +13,8 @@ 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'
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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.14",
-    "@teamplay/cache": "^0.1.14",
-    "@teamplay/channel": "^0.1.14",
-    "@teamplay/debug": "^0.1.14",
-    "@teamplay/schema": "^0.1.14",
-    "@teamplay/utils": "^0.1.14",
+    "@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",
     "diff-match-patch": "^1.0.5",
     "events": "^3.3.0",
     "json0-ot-diff": "^1.1.2",
@@ -63,5 +63,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "edc77f39753ed2532266bbfea646cb3cb7ca6786"
+  "gitHead": "f6a404f330ec3b88d498fa08fbcdc65cb80e8bb4"
 }

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,13 @@
+import { useRef } from 'react'
+import sub from '../orm/sub.js'
+
+// version of sub() which works as a react hook and throws promise for Suspense
+export default function useSub (...args) {
+  const promiseOrSignal = sub(...args)
+  // 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
+  // 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
+}