teamplay 0.4.0-alpha.26 → 0.4.0-alpha.27

package/orm/Compat/README.md

@@ -353,6 +353,19 @@ for (const $doc of $query) {
 }
 ```
 
+### Mutator Semantics (Core vs Compat)
+
+Compatibility mode intentionally aligns mutators with Racer. This differs from core `Signal` behavior.
+
+| API | Core (`Signal`) | Compat (`SignalCompat`) |
+| --- | --- | --- |
+| `set` | Uses deep-diff path (`dataTree.set` + internal `setDiffDeep`). | Path-targeted replace semantics, Racer-like. `undefined` keeps delete semantics. |
+| `setEach` | Not a special API in core mutators. | Per-key compat `set` (not `assign` merge/delete behavior). |
+| `setDiffDeep` | Deep-diff engine (`utils/setDiffDeep.js`). | Explicit deep-diff mutator (`SignalCompat.setDiffDeep`) using base deep-diff path. |
+| `setDiff` | N/A as compat shim. | `setDiff(value)` -> base `Signal.set(value)` on current signal. `setDiff(path, value)` -> compat `set(path, value)`. |
+
+Migration note: compat behavior is intentionally Racer-aligned and may differ from core mutators.
+
 ### set(value) and set(path, value)
 
 `SignalCompat` accepts both:
@@ -362,7 +375,14 @@ $.users.user1.name.set('Alice')
 $.users.user1.set('profile.name', 'Alice')
 ```
 
-In compat mode, `set` replaces values at the target path.
+In compat mode, `set` replaces the value at the target path.
+- `set(path, null)` stores `null`.
+- `set(path, undefined)` applies current delete semantics.
+
+```js
+await $.users.user1.set('profile', { name: 'Ann', role: 'student' })
+await $.users.user1.set('profile', { name: 'Kate' }) // role is removed
+```
 
 ### setNull(path?, value)
 
@@ -377,23 +397,43 @@ $.config.setNull('theme', 'light')
 Applies a diff-deep update (uses base `Signal.set` internally).
 
 ```js
-$.users.user1.setDiffDeep({ profile: { name: 'Alice' } })
+await $.users.user1.set({ profile: { name: 'Ann', role: 'student' } })
+await $.users.user1.setDiffDeep({ profile: { name: 'Kate' } }) // deep-diff path
 ```
 
 ### setDiff(path?, value)
 
-Alias for `set()` in compat. Accepts the same arguments and semantics.
+`setDiff` has two branches in compat:
+- `setDiff(value)` calls base `Signal.set(value)` on current signal (deep-diff semantics).
+- `setDiff(path, value)` delegates to compat `set(path, value)`.
 
 ```js
-$.users.user1.setDiff({ profile: { name: 'Alice' } })
+await $.users.user1.setDiff({ profile: { name: 'Kate' } })
+await $.users.user1.setDiff('profile', { name: 'Bob' }) // compat set semantics
 ```
 
 ### setEach(path?, object)
 
-Shorthand for assign. Sets or deletes fields from an object.
+Racer-like per-key set. `setEach` iterates keys and applies compat `set` for each key.
+- `setEach({ k: null })` stores `null`.
+- `setEach({ k: undefined })` applies current delete semantics.
+
+```js
+await $.users.user1.setEach({ name: 'Bob', age: null })
+```
+
+### Null / Undefined Matrix (Compat)
+
+| Call | Result |
+| --- | --- |
+| `set(path, null)` | stores `null` at `path` |
+| `set(path, undefined)` | applies delete semantics at `path` |
+| `setEach({ k: null })` | stores `null` for `k` |
+| `setEach({ k: undefined })` | applies delete semantics for `k` |
 
 ```js
-$.users.user1.setEach({ name: 'Bob', age: 30 })
+await $.users.user1.set('status', null) // status === null
+await $.users.user1.setEach({ status: undefined }) // status deleted
 ```
 
 ### assign(object)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamplay",
-  "version": "0.4.0-alpha.26",
+  "version": "0.4.0-alpha.27",
   "description": "Full-stack signals ORM with multiplayer",
   "type": "module",
   "main": "index.js",
@@ -81,5 +81,5 @@
     ]
   },
   "license": "MIT",
-  "gitHead": "659791230881f0419bf28dc983f2624f6a05d076"
+  "gitHead": "f7a6412190f8b2ec9322331ad2dab7b8ac452f53"
 }

package/utils/setDiffDeep.js

@@ -4,6 +4,12 @@ function isReactLike (value) {
   return !!(value && typeof value === 'object' && typeof value.$$typeof === 'symbol')
 }
 
+function canDeepMutateObject (existing, updated) {
+  if (!isPlainObject(existing) || !isPlainObject(updated)) return false
+  if (isReactLike(existing) || isReactLike(updated)) return false
+  return true
+}
+
 export default function setDiffDeep (existing, updated) {
   // Handle primitive types, null, and type mismatches
   if (existing === null || updated === null ||
@@ -16,30 +22,37 @@ export default function setDiffDeep (existing, updated) {
   // so we just return the original reference
   if (existing === updated) return existing
 
+  if (isReactLike(existing) || isReactLike(updated)) return updated
+
   // Handle arrays
   if (Array.isArray(updated)) {
-    existing.length = updated.length
-    for (let i = 0; i < updated.length; i++) {
-      existing[i] = setDiffDeep(existing[i], updated[i])
+    try {
+      if (!Reflect.set(existing, 'length', updated.length)) return updated
+      for (let i = 0; i < updated.length; i++) {
+        const nextValue = setDiffDeep(existing[i], updated[i])
+        if (!Reflect.set(existing, i, nextValue)) return updated
+      }
+      return existing
+    } catch {
+      return updated
     }
-    return existing
   }
 
-  // React elements are plain objects but must be treated as non-plain
-  if (isReactLike(updated)) return updated
-
   // Handle non-plain objects - just return them as-is to fully overwrite
   // and don't try to update an old object in-place
-  if (!isPlainObject(updated)) return updated
+  if (!canDeepMutateObject(existing, updated)) return updated
 
   // Handle objects
-  for (const key in existing) {
-    if (!(key in updated)) {
-      delete existing[key]
+  try {
+    for (const key of Object.keys(existing)) {
+      if (!(key in updated) && !Reflect.deleteProperty(existing, key)) return updated
     }
+    for (const key of Object.keys(updated)) {
+      const nextValue = setDiffDeep(existing[key], updated[key])
+      if (!Reflect.set(existing, key, nextValue)) return updated
+    }
+    return existing
+  } catch {
+    return updated
   }
-  for (const key in updated) {
-    existing[key] = setDiffDeep(existing[key], updated[key])
-  }
-  return existing
 }