feat(core): add Map and Set reactivity to the store

senrecep · claude · senrecep · commit d8d078d1f953 · 2026-04-07T11:41:11.000+03:00
Map and Set instances stored in the reactive store are now fully
reactive. Mutations via .set(), .delete(), .clear() (Map) and .add(),
.delete(), .clear() (Set) trigger observers correctly.

- Add module-level _createMapProxy() and _createSetProxy() functions
  adapted to the WeakMap-based private state pattern
- Intercept Map/Set in Store.rootGetValue (top-level props) and
  _createProxy get handler (nested props)
- Map keys must be strings or numbers; object keys throw TypeError to
  prevent silent observer path collisions
- Proxy references are stable via topLevelProxies / proxyCache caches
- 16 new unit tests for Map/Set reactivity
- 9 new component tests showing Map/Set usage in component context

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/map-set-reactivity.md b/.changeset/map-set-reactivity.md
@@ -0,0 +1,8 @@
+---
+"@geajs/core": minor
+"@geajs/vite-plugin": minor
+---
+
+### @geajs/core (minor)
+
+- **Map/Set reactivity**: `Map` and `Set` instances stored in the reactive store are now fully reactive. Mutations via `.set()`, `.delete()`, `.clear()` (Map) and `.add()`, `.delete()`, `.clear()` (Set) trigger observers correctly. Both top-level and nested Map/Set properties are supported.
diff --git a/packages/gea/src/lib/store.ts b/packages/gea/src/lib/store.ts
@@ -841,6 +841,130 @@ function _makePathCache(base: string[]): (prop: string) => string[] {
   }
 }
 
+/**
+ * Creates a reactive Proxy for a Map instance.
+ *
+ * Keys MUST be strings or numbers. Object keys are rejected with a TypeError
+ * because non-string keys would be silently serialized to "[object Object]"
+ * when stored in StoreChange.property and pathParts, causing observer path
+ * collisions and unreachable change events.
+ */
+function _createMapProxy(
+  store: Store,
+  map: Map<any, any>,
+  _basePath: string,
+  baseParts: string[],
+  p: StoreInstancePrivate,
+): any {
+  const proxy = new Proxy(map, {
+    get(target, prop) {
+      if (prop === 'set') {
+        return (key: any, value: any) => {
+          if (typeof key !== 'string' && typeof key !== 'number') {
+            throw new TypeError(
+              `[gea] Reactive Map keys must be strings or numbers, got: ${typeof key}`,
+            )
+          }
+          const keyStr = String(key)
+          const oldValue = target.get(key)
+          target.set(key, value)
+          if (oldValue !== value) {
+            _pushAndSchedule(
+              store,
+              [{ type: 'set', property: keyStr, target, pathParts: appendPathParts(baseParts, keyStr), newValue: value, previousValue: oldValue }],
+              p,
+            )
+          }
+          return proxy
+        }
+      }
+      if (prop === 'delete') {
+        return (key: any) => {
+          if (typeof key !== 'string' && typeof key !== 'number') {
+            throw new TypeError(
+              `[gea] Reactive Map keys must be strings or numbers, got: ${typeof key}`,
+            )
+          }
+          const keyStr = String(key)
+          const existed = target.has(key)
+          const oldValue = target.get(key)
+          target.delete(key)
+          if (existed) {
+            _pushAndSchedule(
+              store,
+              [{ type: 'delete', property: keyStr, target, pathParts: appendPathParts(baseParts, keyStr), previousValue: oldValue }],
+              p,
+            )
+          }
+          return existed
+        }
+      }
+      if (prop === 'clear') {
+        return () => {
+          if (target.size > 0) {
+            target.clear()
+            _pushAndSchedule(store, [{ type: 'set', property: '', target, pathParts: baseParts }], p)
+          }
+        }
+      }
+      const value = Reflect.get(target, prop, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+  return proxy
+}
+
+function _createSetProxy(
+  store: Store,
+  set: Set<any>,
+  _basePath: string,
+  baseParts: string[],
+  p: StoreInstancePrivate,
+): any {
+  const proxy = new Proxy(set, {
+    get(target, prop) {
+      if (prop === 'add') {
+        return (value: any) => {
+          if (!target.has(value)) {
+            target.add(value)
+            _pushAndSchedule(
+              store,
+              [{ type: 'set', property: String(value), target, pathParts: appendPathParts(baseParts, String(value)), newValue: value }],
+              p,
+            )
+          }
+          return proxy
+        }
+      }
+      if (prop === 'delete') {
+        return (value: any) => {
+          const existed = target.has(value)
+          target.delete(value)
+          if (existed) {
+            _pushAndSchedule(
+              store,
+              [{ type: 'delete', property: String(value), target, pathParts: appendPathParts(baseParts, String(value)), previousValue: value }],
+              p,
+            )
+          }
+          return existed
+        }
+      }
+      if (prop === 'clear') {
+        return () => {
+          if (target.size > 0) {
+            target.clear()
+            _pushAndSchedule(store, [{ type: 'set', property: '', target, pathParts: baseParts }], p)
+          }
+        }
+      }
+      const v = Reflect.get(target, prop, target)
+      return typeof v === 'function' ? v.bind(target) : v
+    },
+  })
+  return proxy
+}
+
 function _createProxy(
   store: Store,
   target: any,
@@ -914,6 +1038,18 @@ function _createProxy(
         const cached = _p.proxyCache.get(value)
         if (cached) return cached
       }
+      if (value instanceof Map) {
+        const currentPath = joinPath(basePath, prop as string)
+        const mapProxy = _createMapProxy(store, value, currentPath, getCachedPathParts(prop as string), _p)
+        _p.proxyCache.set(value, mapProxy)
+        return mapProxy
+      }
+      if (value instanceof Set) {
+        const currentPath = joinPath(basePath, prop as string)
+        const setProxy = _createSetProxy(store, value, currentPath, getCachedPathParts(prop as string), _p)
+        _p.proxyCache.set(value, setProxy)
+        return setProxy
+      }
       if (!_isPlain(value)) return value
       if (isArrIdx) {
         let indexCache = _p.arrayIndexProxyCache.get(obj)
@@ -1080,6 +1216,22 @@ export class Store {
     const value = (t as any)[prop]
     if (typeof value === 'function') return value
     if (value != null && typeof value === 'object') {
+      if (value instanceof Map) {
+        const p = storeInstancePrivate.get(t)!
+        const entry = p.topLevelProxies.get(prop)
+        if (entry && entry[0] === value) return entry[1]
+        const mapProxy = _createMapProxy(t, value, prop, _rootPathPartsCache(p, prop), p)
+        p.topLevelProxies.set(prop, [value, mapProxy])
+        return mapProxy
+      }
+      if (value instanceof Set) {
+        const p = storeInstancePrivate.get(t)!
+        const entry = p.topLevelProxies.get(prop)
+        if (entry && entry[0] === value) return entry[1]
+        const setProxy = _createSetProxy(t, value, prop, _rootPathPartsCache(p, prop), p)
+        p.topLevelProxies.set(prop, [value, setProxy])
+        return setProxy
+      }
       if (!_isPlain(value)) return value
       if (shouldSkipReactiveWrapForPath(prop)) return value
       const p = storeInstancePrivate.get(t)!
diff --git a/packages/gea/tests/component.test.ts b/packages/gea/tests/component.test.ts
@@ -389,4 +389,154 @@ describe('Component', () => {
       assert.deepEqual(values, [5])
     })
   })
+
+  describe('Map and Set reactivity in components', () => {
+    it('component with Map property fires observer on Map.set()', async () => {
+      class MapComp extends Component {
+        data = new Map<string, number>()
+        template() {
+          return '<div></div>'
+        }
+      }
+      const comp = new MapComp()
+      const changes: any[][] = []
+      comp.observe('data', (_v: any, c: any) => changes.push(c))
+      ;(comp.data as Map<string, number>).set('count', 42)
+      await flush()
+      assert.equal(changes.length, 1)
+      assert.equal(changes[0][0].type, 'set')
+      assert.equal(changes[0][0].property, 'count')
+      assert.equal(changes[0][0].newValue, 42)
+    })
+
+    it('component with Map property fires observer on Map.delete()', async () => {
+      class MapComp extends Component {
+        data = new Map<string, number>([['x', 1]])
+        template() {
+          return '<div></div>'
+        }
+      }
+      const comp = new MapComp()
+      const changes: any[][] = []
+      comp.observe('data', (_v: any, c: any) => changes.push(c))
+      ;(comp.data as Map<string, number>).delete('x')
+      await flush()
+      assert.equal(changes.length, 1)
+      assert.equal(changes[0][0].type, 'delete')
+      assert.equal(changes[0][0].property, 'x')
+    })
+
+    it('component with Map property does not fire observer when setting same value', async () => {
+      class MapComp extends Component {
+        data = new Map<string, number>([['a', 1]])
+        template() {
+          return '<div></div>'
+        }
+      }
+      const comp = new MapComp()
+      const changes: any[][] = []
+      comp.observe('data', (_v: any, c: any) => changes.push(c))
+      ;(comp.data as Map<string, number>).set('a', 1)
+      await flush()
+      assert.equal(changes.length, 0)
+    })
+
+    it('component Map proxy returns stable reference', () => {
+      class MapComp extends Component {
+        counters = new Map<string, number>()
+        template() {
+          return '<div></div>'
+        }
+      }
+      const comp = new MapComp()
+      assert.equal(comp.counters, comp.counters)
+    })
+
+    it('component with Set property fires observer on Set.add()', async () => {
+      class TagComp extends Component {
+        tags = new Set<string>()
+        template() {
+          return '<div></div>'
+        }
+      }
+      const comp = new TagComp()
+      const changes: any[][] = []
+      comp.observe('tags', (_v: any, c: any) => changes.push(c))
+      ;(comp.tags as Set<string>).add('react')
+      await flush()
+      assert.equal(changes.length, 1)
+      assert.equal(changes[0][0].type, 'set')
+      assert.equal(changes[0][0].property, 'react')
+      assert.equal(changes[0][0].newValue, 'react')
+    })
+
+    it('component with Set property fires observer on Set.delete()', async () => {
+      class TagComp extends Component {
+        tags = new Set<string>(['foo', 'bar'])
+        template() {
+          return '<div></div>'
+        }
+      }
+      const comp = new TagComp()
+      const changes: any[][] = []
+      comp.observe('tags', (_v: any, c: any) => changes.push(c))
+      ;(comp.tags as Set<string>).delete('foo')
+      await flush()
+      assert.equal(changes.length, 1)
+      assert.equal(changes[0][0].type, 'delete')
+      assert.equal(changes[0][0].property, 'foo')
+    })
+
+    it('component Set proxy returns stable reference', () => {
+      class SetComp extends Component {
+        ids = new Set<number>()
+        template() {
+          return '<div></div>'
+        }
+      }
+      const comp = new SetComp()
+      assert.equal(comp.ids, comp.ids)
+    })
+
+    it('component renders Map-based content and observer tracks key change', async () => {
+      class DictComp extends Component {
+        dict = new Map<string, string>([['greeting', 'Hello']])
+        getGreeting() {
+          return (this.dict as Map<string, string>).get('greeting') ?? ''
+        }
+        template() {
+          return `<div>${this.getGreeting()}</div>`
+        }
+      }
+      const comp = new DictComp()
+      const container = document.createElement('div')
+      document.body.appendChild(container)
+      comp.render(container)
+      assert.ok(container.textContent?.includes('Hello'))
+      const changes: any[][] = []
+      comp.observe('dict', (_v: any, c: any) => changes.push(c))
+      ;(comp.dict as Map<string, string>).set('greeting', 'Hi')
+      await flush()
+      assert.equal(changes.length, 1)
+      assert.equal(changes[0][0].newValue, 'Hi')
+    })
+
+    it('component with Set fires observer on Set.clear() only when non-empty', async () => {
+      class FlagComp extends Component {
+        flags = new Set<string>(['active', 'visible'])
+        template() {
+          return '<div></div>'
+        }
+      }
+      const comp = new FlagComp()
+      const changes: any[][] = []
+      comp.observe('flags', (_v: any, c: any) => changes.push(c))
+      ;(comp.flags as Set<string>).clear()
+      await flush()
+      assert.equal(changes.length, 1)
+      ;(comp.flags as Set<string>).clear()
+      await flush()
+      assert.equal(changes.length, 1, 'clear on empty set must not fire again')
+    })
+  })
 })
diff --git a/packages/gea/tests/store.test.ts b/packages/gea/tests/store.test.ts
