teamplay 0.4.0-alpha.1 → 0.4.0-alpha.100

package/README.md

@@ -19,6 +19,79 @@ Features:
 
 For installation and documentation see [teamplay.dev](https://teamplay.dev)
 
+## ORM Compat Helpers
+
+For legacy Racer-style model mixins (for example versioning libraries which call
+`getAssociations()`), use ORM compat helpers from the `teamplay/orm` subpath:
+
+```js
+import BaseModel, { hasMany, hasOne, belongsTo } from 'teamplay/orm'
+```
+
+These helpers attach class-level associations and expose them through
+`$doc.getAssociations()` on model signals.
+
+## React Suspense Gates
+
+If you need to throw a thenable from render, prefer `useSuspendMemo()` or
+`useSuspendMemoByKey()` over `useMemo()`.
+
+Why:
+
+- React may restart a suspended initial render.
+- `useMemo()` is not a semantic "run this suspend gate once" primitive.
+- Side-effectful async work like `join()` may accidentally start again on retry.
+
+### `useSuspendMemo(factory, deps)`
+
+Use it when the suspend gate is local to one observer component instance.
+
+```js
+import { observer, useSuspendMemo } from 'teamplay'
+
+const Component = observer(({ $stage, userId, stageUserStore }) => {
+  useSuspendMemo(() => {
+    if (!stageUserStore?.startedAt) {
+      throw $stage.join(userId)
+    }
+  }, [$stage.getId()])
+
+  return <span>Ready</span>
+})
+```
+
+This keeps the same pending thenable for the same hook slot while the component
+instance is alive.
+
+### `useSuspendMemoByKey(key, factory, deps)`
+
+Use it when the async operation must be deduped by business meaning, not just
+by component instance.
+
+```js
+import { observer, useSuspendMemoByKey } from 'teamplay'
+
+const Component = observer(({ $stage, stageId, userId, stageUserStore }) => {
+  useSuspendMemoByKey(
+    `stage.join:${stageId}:${userId}`,
+    () => {
+      if (!stageUserStore?.startedAt) {
+        throw $stage.join(userId)
+      }
+    },
+    [stageId, userId, !!stageUserStore?.startedAt]
+  )
+
+  return <span>Ready</span>
+})
+```
+
+This is the right choice when:
+
+- the component may remount while the promise is still pending;
+- two different components may trigger the same async operation;
+- the operation should behave like a single in-flight business task.
+
 ## License
 
 MIT

package/index.d.ts

@@ -42,6 +42,8 @@ export {
   setUseDeferredValue as __setUseDeferredValue,
   setDefaultDefer as __setDefaultDefer
 } from './react/useSub.js'
+export function useSuspendMemo<T = any> (factory: () => T, deps?: any[]): T
+export function useSuspendMemoByKey<T = any> (key: any, factory: () => T, deps?: any[]): T
 export function useValue (defaultValue?: any): [any, any]
 export function useValue$ (defaultValue?: any): any
 export function useModel (path?: any): any
@@ -73,6 +75,8 @@ export function useBatchQueryDoc (collection: string, query: any, options?: any)
 export function useBatchQueryDoc$ (collection: string, query: any, options?: any): any
 export function useAsyncQueryDoc (collection: string, query: any, options?: any): [any, any]
 export function useAsyncQueryDoc$ (collection: string, query: any, options?: any): any
+export function useLocalDoc (collection: string, id: any): [any, any]
+export function useLocalDoc$ (collection: string, id: any): any
 export function emit (eventName: string, ...args: any[]): void
 export function useOn (
   eventName: 'change' | 'all',
@@ -82,7 +86,18 @@ export function useOn (
 ): void
 export function useOn (eventName: string, handler: (...args: any[]) => void, deps?: any[]): void
 export function useEmit (): (eventName: string, ...args: any[]) => void
+export function batch<T = any> (fn?: () => T): T | undefined
+export function batchModel<T = any> (fn?: () => T): T | undefined
+export function clone<T = any> (value: T): T
+export function initLocalCollection (name: string): any
+export function useApi (api: (...args: any[]) => any, args?: any[], options?: { debounce?: number }): [any, boolean, any]
+type EffectCleanup = (() => void) | undefined
+export function useDidUpdate (fn: () => EffectCleanup, deps?: any[]): void
+export function useOnce (condition: any, fn: () => EffectCleanup): void
+export function useSyncEffect (fn: () => EffectCleanup, deps?: any[]): void
 export { connection, setConnection, getConnection, fetchOnly, setFetchOnly, publicOnly, setPublicOnly } from './orm/connection.js'
+export function getSubscriptionGcDelay (): number
+export function setSubscriptionGcDelay (ms?: number | null): number
 export { useId, useNow, useScheduleUpdate, useTriggerUpdate } from './react/helpers.js'
 export { GUID_PATTERN, hasMany, hasOne, hasManyFlags, belongsTo, pickFormFields } from '@teamplay/schema'
 export { aggregation, aggregationHeader as __aggregationHeader } from '@teamplay/utils/aggregation'

package/index.js

@@ -5,6 +5,7 @@
 //   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'
+import useApi from './react/useApi.js'
 
 export { default as Signal, SEGMENTS } from './orm/Signal.js'
 export { __DEBUG_SIGNALS_CACHE__, rawSignal, getSignalClass } from './orm/getSignal.js'
@@ -22,6 +23,10 @@ export {
   setUseDeferredValue as __setUseDeferredValue,
   setDefaultDefer as __setDefaultDefer
 } from './react/useSub.js'
+export {
+  default as useSuspendMemo,
+  useSuspendMemoByKey
+} from './react/useSuspendMemo.js'
 export { default as observer } from './react/observer.js'
 export {
   useValue,
@@ -29,6 +34,8 @@ export {
   useModel,
   useLocal,
   useLocal$,
+  useLocalDoc,
+  useLocalDoc$,
   useSession,
   useSession$,
   usePage,
@@ -57,12 +64,59 @@ export {
   useAsyncQueryDoc$
 } from './orm/Compat/hooksCompat.js'
 export { emit, useOn, useEmit } from './orm/Compat/eventsCompat.js'
-export { connection, setConnection, getConnection, fetchOnly, setFetchOnly, publicOnly, setPublicOnly } from './orm/connection.js'
+export {
+  useDidUpdate,
+  useOnce,
+  useSyncEffect
+} from './react/helpers.js'
+export {
+  connection,
+  setConnection,
+  getConnection,
+  getDefaultFetchOnly,
+  setDefaultFetchOnly,
+  publicOnly,
+  setPublicOnly
+} from './orm/connection.js'
+export { getSubscriptionGcDelay, setSubscriptionGcDelay } from './orm/subscriptionGcDelay.js'
 export { useId, useNow, useScheduleUpdate, useTriggerUpdate } from './react/helpers.js'
 export { GUID_PATTERN, hasMany, hasOne, hasManyFlags, belongsTo, pickFormFields } from '@teamplay/schema'
 export { aggregation, aggregationHeader as __aggregationHeader } from '@teamplay/utils/aggregation'
 export { accessControl } from '@teamplay/utils/accessControl'
 
+export function batch (fn) {
+  return $.batch(fn)
+}
+
+export function batchModel (fn) {
+  return $.batch(fn)
+}
+
+export function clone (value) {
+  if (typeof globalThis.structuredClone === 'function') {
+    try {
+      return globalThis.structuredClone(value)
+    } catch {}
+  }
+  if (value == null) return value
+  return JSON.parse(JSON.stringify(value))
+}
+
+export function initLocalCollection (name) {
+  if (typeof name !== 'string') throw Error('initLocalCollection() expects a collection name')
+  if (!name) return
+  const segments = name.split('.').filter(Boolean)
+  if (!segments.length) return
+  let $cursor = $
+  for (const segment of segments) {
+    $cursor = $cursor[segment]
+  }
+  if ($cursor.get() == null) $cursor.set({})
+  return $cursor
+}
+
+export { useApi }
+
 export function getRootSignal (options) {
   return _getRootSignal({
     rootFunction: universal$,

package/orm/Aggregation.js

@@ -1,34 +1,54 @@
 import { raw } from '@nx-js/observer-util'
-import { set as _set, del as _del, getRaw } from './dataTree.js'
+import { getRaw } from './dataTree.js'
 import getSignal from './getSignal.js'
-import { QuerySubscriptions, hashQuery, Query, HASH, PARAMS, COLLECTION_NAME, parseQueryHash } from './Query.js'
+import {
+  QuerySubscriptions,
+  hashQuery,
+  Query,
+  HASH,
+  PARAMS,
+  COLLECTION_NAME,
+  parseQueryHash
+} from './Query.js'
 import Signal, { SEGMENTS } from './Signal.js'
 import { getIdFieldsForSegments, isPlainObject } from './idFields.js'
+import { delPrivateData, getPrivateData, setPrivateData } from './privateData.js'
 
 export const IS_AGGREGATION = Symbol('is aggregation signal')
 export const AGGREGATIONS = '$aggregations'
 
 class Aggregation extends Query {
   _initData () {
-    {
-      const extra = raw(this.shareQuery.extra)
-      injectAggregationIds(extra, this.collectionName)
-      _set([AGGREGATIONS, this.hash], extra)
-    }
+    this._syncAllRootsData()
 
     this.shareQuery.on('extra', extra => {
       extra = raw(extra)
       injectAggregationIds(extra, this.collectionName)
-      _set([AGGREGATIONS, this.hash], extra)
+      this._forEachRoot(rootId => {
+        setPrivateData(rootId, [AGGREGATIONS, this.hash], extra)
+      })
     })
   }
 
+  _syncRootData (rootId) {
+    if (!this.shareQuery) return
+    const extra = raw(this.shareQuery.extra)
+    injectAggregationIds(extra, this.collectionName)
+    setPrivateData(rootId, [AGGREGATIONS, this.hash], extra)
+  }
+
+  _removeRootData (rootId) {
+    delPrivateData(rootId, [AGGREGATIONS, this.hash])
+  }
+
   _removeData () {
-    _del([AGGREGATIONS, this.hash])
+    this._forEachRoot(rootId => this._removeRootData(rootId))
+    this.rootIds.clear()
   }
 }
 
 export const aggregationSubscriptions = new QuerySubscriptions(Aggregation)
+aggregationSubscriptions.runtimeKind = 'aggregation'
 
 function injectAggregationIds (extra, collectionName) {
   if (!Array.isArray(extra)) return
@@ -44,13 +64,14 @@ function injectAggregationIds (extra, collectionName) {
 
 export function getAggregationSignal (collectionName, params, options) {
   params = JSON.parse(JSON.stringify(params))
-  const hash = hashQuery(collectionName, params)
+  const transportHash = hashQuery(collectionName, params)
+  const { root, signalOptions } = parseAggregationSignalOptions(options)
 
-  const $aggregation = getSignal(undefined, [AGGREGATIONS, hash], options)
+  const $aggregation = getSignal(root, [AGGREGATIONS, transportHash], signalOptions)
   $aggregation[IS_AGGREGATION] ??= true
   $aggregation[COLLECTION_NAME] ??= collectionName
   $aggregation[PARAMS] ??= params
-  $aggregation[HASH] ??= hash
+  $aggregation[HASH] ??= transportHash
   return $aggregation
 }
 
@@ -65,10 +86,13 @@ export function isAggregationSignal ($signal) {
 
 // example: ['$aggregations', '{"active":true}', 42]
 //          AND only if it also has either '_id' or 'id' field inside
-export function getAggregationDocId (segments, method = getRaw) {
+export function getAggregationDocId (segments, rootId, method) {
   if (!(segments.length >= 3)) return
   if (!(segments[0] === AGGREGATIONS)) return
   if (!(typeof segments[2] === 'number')) return
+  if (typeof method !== 'function') {
+    method = path => rootId == null ? getRaw(path) : getPrivateData(rootId, path)
+  }
   const docId = method([...segments.slice(0, 3), '_id']) || method([...segments.slice(0, 3), 'id'])
   return docId
 }
@@ -80,3 +104,14 @@ export function getAggregationCollectionName (segments) {
   const { collectionName } = parseQueryHash(hash)
   return collectionName
 }
+
+function parseAggregationSignalOptions (options) {
+  if (!options || typeof options !== 'object') {
+    return {
+      root: undefined,
+      signalOptions: {}
+    }
+  }
+  const { root, ...signalOptions } = options
+  return { root, signalOptions }
+}