🔖 publish: bump

Author: krispya

packages/publish/README.md

@@ -48,11 +48,18 @@ const goblin = world.spawn(Position({ x: 10, y: 10 }), Velocity, Mesh)
 Queries fetch entities sharing traits (archetypes). Use them to batch update entities efficiently.
 
 ```js
+// updateEach mutates and writes back to stores
 // Run this in a loop
 world.query(Position, Velocity).updateEach(([position, velocity]) => {
   position.x += velocity.x * delta
   position.y += velocity.y * delta
 })
+
+// For read-only operations with no mutation, use readEach
+const data = []
+world.query(Position, Velocity).readEach(([position, velocity]) => {
+  data.push({ x: position.x, y: position.y })
+})
 ```
 
 ### Use in your React components
@@ -416,6 +423,8 @@ const movingOrVisible = world.query(Or(Velocity, Renderable))
 
 The `Added` modifier tracks all entities that have added the specified traits or relations since the last time the query was run. A new instance of the modifier must be created for tracking to be unique.
 
+When multiple traits are passed to `Added` it uses logical `AND`. Only entities where **all** specified traits have been added will be returned.
+
 ```js
 import { createAdded } from 'koota'
 
@@ -427,13 +436,21 @@ const newPositions = world.query(Added(Position))
 // Track entities that added a ChildOf relation
 const newChildren = world.query(Added(ChildOf))
 
+// Track entities where BOTH Position AND Velocity were added
+const fullyAdded = world.query(Added(Position, Velocity))
+
+// Track entities where EITHER Position OR Velocity was added
+const eitherAdded = world.query(Or(Added(Position), Added(Velocity)))
+
 // After running the query, the Added modifier is reset
 ```
 
 #### Removed
 
 The `Removed` modifier tracks all entities that have removed the specified traits or relations since the last time the query was run. This includes entities that have been destroyed. A new instance of the modifier must be created for tracking to be unique.
 
+When multiple traits are passed to `Removed` it uses logical `AND`. Only entities where **all** specified traits have been removed will be returned.
+
 ```js
 import { createRemoved } from 'koota'
 
@@ -445,13 +462,21 @@ const stoppedEntities = world.query(Removed(Velocity))
 // Track entities that removed a ChildOf relation
 const orphaned = world.query(Removed(ChildOf))
 
+// Track entities where BOTH Position AND Velocity were removed
+const fullyRemoved = world.query(Removed(Position, Velocity))
+
+// Track entities where EITHER Position OR Velocity was removed
+const eitherRemoved = world.query(Or(Removed(Position), Removed(Velocity)))
+
 // After running the query, the Removed modifier is reset
 ```
 
 #### Changed
 
 The `Changed` modifier tracks all entities that have had the specified traits or relation stores change since the last time the query was run. A new instance of the modifier must be created for tracking to be unique.
 
+When multiple traits are passed to `Changed` it uses logical `AND`. Only entities where **all** specified traits have changed will be returned.
+
 ```js
 import { createChanged } from 'koota'
 
@@ -463,6 +488,12 @@ const movedEntities = world.query(Changed(Position))
 // Track entities whose ChildOf relation data has changed
 const updatedChildren = world.query(Changed(ChildOf))
 
+// Track entities where BOTH Position AND Velocity have changed
+const fullyUpdated = world.query(Changed(Position, Velocity))
+
+// Track entities where EITHER Position OR Velocity has changed
+const eitherChanged = world.query(Or(Changed(Position), Changed(Velocity)))
+
 // After running the query, the Changed modifier is reset
 ```
 

packages/publish/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koota",
-  "version": "0.6.4",
-  "description": "🌎 Performant real-time state management for React and TypeScript",
+  "version": "0.6.5",
+  "description": "🌎 Performant real-time state management for TypeScript and React",
   "license": "ISC",
   "type": "module",
   "main": "./src/index.ts",

packages/publish/tests/core/query-modifiers.test.ts

@@ -7,6 +7,7 @@ import {
     createWorld,
     getStore,
     Not,
+    Or,
     trait,
 } from '../../dist';
 
@@ -575,6 +576,98 @@ describe('Query modifiers', () => {
         expect(entity.get(Name)!.name).toBe('modified');
     });
 
+    it('should combine Or with Changed modifiers to match ANY changed trait', () => {
+        const Changed = createChanged();
+
+        const entityA = world.spawn(Position, Foo);
+        const entityB = world.spawn(Position, Foo);
+        const entityC = world.spawn(Position, Foo);
+
+        // No changes yet
+        let entities = world.query(Or(Changed(Position), Changed(Foo)));
+        expect(entities.length).toBe(0);
+
+        // Change only Position on entityA
+        entityA.changed(Position);
+        entities = world.query(Or(Changed(Position), Changed(Foo)));
+        expect(entities).toContain(entityA);
+        expect(entities.length).toBe(1);
+
+        // Change only Foo on entityB
+        entityB.changed(Foo);
+        entities = world.query(Or(Changed(Position), Changed(Foo)));
+        expect(entities).toContain(entityB);
+        expect(entities.length).toBe(1);
+
+        // Change both on entityC - should still match
+        entityC.changed(Position);
+        entityC.changed(Foo);
+        entities = world.query(Or(Changed(Position), Changed(Foo)));
+        expect(entities).toContain(entityC);
+        expect(entities.length).toBe(1);
+    });
+
+    it('should combine Or with Added modifiers to match ANY added trait', () => {
+        const Added = createAdded();
+
+        const entityA = world.spawn();
+        const entityB = world.spawn();
+        const entityC = world.spawn();
+
+        // No additions yet
+        let entities = world.query(Or(Added(Position), Added(Foo)));
+        expect(entities.length).toBe(0);
+
+        // Add only Position to entityA
+        entityA.add(Position);
+        entities = world.query(Or(Added(Position), Added(Foo)));
+        expect(entities).toContain(entityA);
+        expect(entities.length).toBe(1);
+
+        // Add only Foo to entityB
+        entityB.add(Foo);
+        entities = world.query(Or(Added(Position), Added(Foo)));
+        expect(entities).toContain(entityB);
+        expect(entities.length).toBe(1);
+
+        // Add both to entityC - should still match
+        entityC.add(Position, Foo);
+        entities = world.query(Or(Added(Position), Added(Foo)));
+        expect(entities).toContain(entityC);
+        expect(entities.length).toBe(1);
+    });
+
+    it('should combine Or with Removed modifiers to match ANY removed trait', () => {
+        const Removed = createRemoved();
+
+        const entityA = world.spawn(Position, Foo);
+        const entityB = world.spawn(Position, Foo);
+        const entityC = world.spawn(Position, Foo);
+
+        // No removals yet
+        let entities = world.query(Or(Removed(Position), Removed(Foo)));
+        expect(entities.length).toBe(0);
+
+        // Remove only Position from entityA
+        entityA.remove(Position);
+        entities = world.query(Or(Removed(Position), Removed(Foo)));
+        expect(entities).toContain(entityA);
+        expect(entities.length).toBe(1);
+
+        // Remove only Foo from entityB
+        entityB.remove(Foo);
+        entities = world.query(Or(Removed(Position), Removed(Foo)));
+        expect(entities).toContain(entityB);
+        expect(entities.length).toBe(1);
+
+        // Remove both from entityC - should still match
+        entityC.remove(Position);
+        entityC.remove(Foo);
+        entities = world.query(Or(Removed(Position), Removed(Foo)));
+        expect(entities).toContain(entityC);
+        expect(entities.length).toBe(1);
+    });
+
     // @internal Tests internal implementation edge case with generation overflow
     it('[internal] should handle Changed modifier when trait registration causes generation overflow', () => {
         // Create a fresh world to control trait registration count

packages/publish/tests/core/query.test.ts

@@ -260,6 +260,25 @@ describe('Query', () => {
         expect(cb).toHaveBeenCalledTimes(9);
     });
 
+    it('should read trait data with readEach without modifying stores', () => {
+        for (let i = 0; i < 5; i++) {
+            world.spawn(Position({ x: i, y: i * 2 }), Name({ name: `Entity${i}` }));
+        }
+
+        const results: any[] = [];
+        world.query(Position, Name).readEach(([position, name], entity, index) => {
+            results.push({
+                x: position.x,
+                name: name.name,
+                index,
+            });
+        });
+
+        expect(results).toHaveLength(5);
+        expect(results[0]).toEqual({ x: 0, name: 'Entity0', index: 0 });
+        expect(results[2]).toEqual({ x: 2, name: 'Entity2', index: 2 });
+    });
+
     it('updateEach should return values in caller parameter order regardless of cache', () => {
         // Create entity with both traits
         world.spawn(Position({ x: 10, y: 20 }), Name({ name: 'test' }));