teamplay 0.2.5 → 0.3.0

package/index.js

@@ -14,7 +14,7 @@ export { GLOBAL_ROOT_ID } from './orm/Root.js'
 export const $ = _getRootSignal({ rootId: GLOBAL_ROOT_ID, rootFunction: universal$ })
 export default $
 export { default as sub } from './orm/sub.js'
-export { default as useSub } from './react/useSub.js'
+export { default as useSub, setUseDeferredValue as __setUseDeferredValue } 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'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.2.5",
+  "version": "0.3.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.2.5",
-    "@teamplay/cache": "^0.2.5",
-    "@teamplay/channel": "^0.2.5",
-    "@teamplay/debug": "^0.2.5",
-    "@teamplay/schema": "^0.2.5",
-    "@teamplay/utils": "^0.2.5",
+    "@teamplay/backend": "^0.3.0",
+    "@teamplay/cache": "^0.3.0",
+    "@teamplay/channel": "^0.3.0",
+    "@teamplay/debug": "^0.3.0",
+    "@teamplay/schema": "^0.3.0",
+    "@teamplay/utils": "^0.3.0",
     "diff-match-patch": "^1.0.5",
     "events": "^3.3.0",
     "json0-ot-diff": "^1.1.2",
@@ -63,5 +63,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "e4ea7de3c12214a24928af14b882651b3aeb5599"
+  "gitHead": "1cc50389c3f1aa7b75d727cb6f0b1f61627a6b22"
 }

package/react/convertToObserver.js

@@ -1,13 +1,10 @@
-// TODO: rewrite to use useSyncExternalStore like in mobx. This will also help with handling Suspense abandonment better
-//       to cleanup the observer() reaction when the component is unmounted or was abandoned and unmounts will never trigger.
-//       ref: https://github.com/mobxjs/mobx/blob/94bc4997c14152ff5aefcaac64d982d5c21ba51a/packages/mobx-react-lite/src/useObserver.ts
-import { forwardRef as _forwardRef, useRef, useSyncExternalStore } from 'react'
+import { forwardRef as _forwardRef, useRef } from 'react'
 import { observe, unobserve } from '@nx-js/observer-util'
 import _throttle from 'lodash/throttle.js'
 import { createCaches, getDummyCache } from '@teamplay/cache'
 import { __increment, __decrement } from '@teamplay/debug'
 import executionContextTracker from './executionContextTracker.js'
-import { pipeComponentMeta, useUnmount, useId } from './helpers.js'
+import { pipeComponentMeta, useUnmount, useId, useTriggerUpdate } from './helpers.js'
 import trapRender from './trapRender.js'
 
 const DEFAULT_THROTTLE_TIMEOUT = 100
@@ -28,30 +25,7 @@ export default function convertToObserver (BaseComponent, {
   let Component = (...args) => {
     const [cache, destroyCache] = useCreateCacheRef(enableCache)
     const componentId = useId()
-
-    const admRef = useRef()
-    if (!admRef.current) {
-      const adm = {
-        stateVersion: Symbol(), // eslint-disable-line symbol-description
-        onStoreChange: undefined,
-        subscribe (onStoreChange) {
-          adm.onStoreChange = () => {
-            adm.stateVersion = Symbol() // eslint-disable-line symbol-description
-            onStoreChange()
-          }
-          return () => {
-            adm.onStoreChange = undefined
-          }
-        },
-        getSnapshot () {
-          return adm.stateVersion
-        }
-      }
-      admRef.current = adm
-    }
-    const adm = admRef.current
-
-    useSyncExternalStore(adm.subscribe, adm.getSnapshot, adm.getSnapshot)
+    const triggerUpdate = useTriggerUpdate()
 
     // wrap the BaseComponent into an observe decorator once.
     // This way it will track any observable changes and will trigger rerender
@@ -61,7 +35,7 @@ export default function convertToObserver (BaseComponent, {
       let update = () => {
         // It's important to block updates caused by rendering itself
         // (when the sync rendering is in progress).
-        if (!executionContextTracker.isActive()) adm.onStoreChange?.()
+        if (!executionContextTracker.isActive()) triggerUpdate()
       }
       if (throttle) update = _throttle(update, throttle)
       destroyRef.current = (where) => {

package/react/helpers.js

@@ -23,8 +23,21 @@ export function pipeComponentMeta (SourceComponent, TargetComponent, suffix = ''
 }
 
 export function useId () {
-  const { componentId } = useContext(ComponentMetaContext)
-  return componentId
+  const context = useContext(ComponentMetaContext)
+  if (!context) throw Error(ERRORS.useId)
+  return context.componentId
+}
+
+export function useTriggerUpdate () {
+  const context = useContext(ComponentMetaContext)
+  if (!context) throw Error(ERRORS.useTriggerUpdate)
+  return context.triggerUpdate
+}
+
+export function useScheduleUpdate () {
+  const context = useContext(ComponentMetaContext)
+  if (!context) throw Error(ERRORS.useScheduleUpdate)
+  return context.scheduleUpdate
 }
 
 export function useUnmount (fn) {
@@ -37,3 +50,18 @@ export function useUnmount (fn) {
     []
   )
 }
+
+const ERRORS = {
+  useTriggerUpdate: `
+    useTriggerUpdate() can only be used inside a component wrapped with observer().
+    You have probably forgot to wrap your component with observer().
+  `,
+  useScheduleUpdate: `
+    useScheduleUpdate() can only be used inside a component wrapped with observer().
+    You have probably forgot to wrap your component with observer().
+  `,
+  useId: `
+    useId() can only be used inside a component wrapped with observer().
+    You have probably forgot to wrap your component with observer().
+  `
+}

package/react/useSub.js

@@ -1,14 +1,27 @@
 import { useRef, useDeferredValue } from 'react'
 import sub from '../orm/sub.js'
+import { useScheduleUpdate } from './helpers.js'
 
 let TEST_THROTTLING = false
 
-// version of sub() which works as a react hook and throws promise for Suspense
+// experimental feature to leverage useDeferredValue() to handle re-subscriptions.
+// Currently it does lead to issues with extra rerenders and requires further investigation
+let USE_DEFERRED_VALUE = false
+
 export default function useSub (signal, params) {
+  if (USE_DEFERRED_VALUE) {
+    return useSubDeferred(signal, params) // eslint-disable-line react-hooks/rules-of-hooks
+  } else {
+    return useSubClassic(signal, params) // eslint-disable-line react-hooks/rules-of-hooks
+  }
+}
+
+// version of sub() which works as a react hook and throws promise for Suspense
+export function useSubDeferred (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)
+  params = params != null ? JSON.parse(params) : undefined
+  const promiseOrSignal = params != null ? 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) {
     if (TEST_THROTTLING) {
@@ -27,6 +40,40 @@ export default function useSub (signal, params) {
   return promiseOrSignal
 }
 
+// classic version which initially throws promise for Suspense
+// but if we get a promise second time, we return the last signal and wait for promise to resolve
+export function useSubClassic (signal, params) {
+  const $signalRef = useRef()
+  const activePromiseRef = useRef()
+  const scheduleUpdate = useScheduleUpdate()
+  const promiseOrSignal = params != null ? 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) {
+    let promise
+    if (TEST_THROTTLING) {
+      // simulate slow network
+      promise = new Promise((resolve, reject) => {
+        setTimeout(() => {
+          promiseOrSignal.then(resolve, reject)
+        }, TEST_THROTTLING)
+      })
+    } else {
+      promise = promiseOrSignal
+    }
+    // first time we just throw the promise to be caught by Suspense
+    if (!$signalRef.current) throw promise
+    // if we already have a previous signal, we return it and wait for new promise to resolve
+    scheduleUpdate(promise)
+    return $signalRef.current
+  }
+  // 2. if it's a signal, we save it into ref to make sure it's not garbage collected while component exists
+  if ($signalRef.current !== promiseOrSignal) {
+    activePromiseRef.current = undefined
+    $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')
@@ -36,3 +83,6 @@ export function setTestThrottling (ms) {
 export function resetTestThrottling () {
   TEST_THROTTLING = false
 }
+export function setUseDeferredValue (value) {
+  USE_DEFERRED_VALUE = value
+}

package/react/wrapIntoSuspense.js

@@ -1,4 +1,6 @@
-import { forwardRef as _forwardRef, memo, createElement as el, Suspense, useId, useRef } from 'react'
+// useSyncExternalStore is used to trigger an update same as in MobX
+// ref: https://github.com/mobxjs/mobx/blob/94bc4997c14152ff5aefcaac64d982d5c21ba51a/packages/mobx-react-lite/src/useObserver.ts
+import { useSyncExternalStore, forwardRef as _forwardRef, memo, createElement as el, Suspense, useId, useRef } from 'react'
 import { pipeComponentMeta, pipeComponentDisplayName, ComponentMetaContext } from './helpers.js'
 
 export default function wrapIntoSuspense ({
@@ -11,10 +13,49 @@ export default function wrapIntoSuspense ({
   let SuspenseWrapper = (props, ref) => {
     const componentId = useId()
     const componentMetaRef = useRef()
+    const admRef = useRef()
+    if (!admRef.current) {
+      const adm = {
+        stateVersion: Symbol(), // eslint-disable-line symbol-description
+        onStoreChange: undefined,
+        scheduledUpdatePromise: undefined,
+        subscribe (onStoreChange) {
+          adm.onStoreChange = () => {
+            adm.stateVersion = Symbol() // eslint-disable-line symbol-description
+            onStoreChange()
+          }
+          adm.scheduleUpdate = promise => {
+            if (!promise?.then) throw Error('scheduleUpdate() expects a promise')
+            if (adm.scheduledUpdatePromise === promise) return
+            adm.scheduledUpdatePromise = promise
+            promise.then(() => {
+              if (adm.scheduledUpdatePromise !== promise) return
+              adm.scheduledUpdatePromise = undefined
+              adm.onStoreChange?.()
+            })
+          }
+          return () => {
+            adm.onStoreChange = undefined
+            adm.scheduledUpdatePromise = undefined
+            adm.scheduleUpdate = undefined
+          }
+        },
+        getSnapshot () {
+          return adm.stateVersion
+        }
+      }
+      admRef.current = adm
+    }
+    const adm = admRef.current
+
+    useSyncExternalStore(adm.subscribe, adm.getSnapshot, adm.getSnapshot)
+
     if (!componentMetaRef.current) {
       componentMetaRef.current = {
         componentId,
-        createdAt: Date.now()
+        createdAt: Date.now(),
+        triggerUpdate: () => adm.onStoreChange?.(),
+        scheduleUpdate: promise => adm.scheduleUpdate?.(promise)
       }
     }