koota 0.6.0 → 0.6.2

package/README.md

@@ -72,11 +72,7 @@ createRoot(document.getElementById('root')!).render(
 function RocketRenderer() {
     // Reactively update whenever the query updates with new entities
     const rockets = useQuery(Position, Velocity)
-    return (
-        <>
-            {rockets.map((entity) => <RocketView key={entity} entity={entity} />)}
-        </>
-    )
+    return rockets.map((entity) => <RocketView key={entity} entity={entity} />)
 }
 
 function RocketView({ entity }) {
@@ -84,7 +80,7 @@ function RocketView({ entity }) {
     const position = useTrait(entity, Position)
     return (
         <div style={{ position: 'absolute', left: position.x ?? 0, top: position.y ?? 0 }}>
-        🚀
+          🚀
         </div>
     )
 }
@@ -95,10 +91,10 @@ function RocketView({ entity }) {
 Use actions to safely modify Koota from inside of React in either effects or events.
 
 ```js
-import { createActions } from 'koota'
+import { defineActions } from 'koota'
 import { useActions } from 'koota/react'
 
-const actions = createActions((world) => ({
+const actions = defineActions((world) => ({
   spawnShip: (position) => world.spawn(Position(position), Velocity),
   destroyAllShips: () => {
     world.query(Position, Velocity).forEach((entity) => {
@@ -205,6 +201,34 @@ hero.has(Targeting(rat)) // False
 hero.has(Targeting(goblin)) // True
 ```
 
+#### Ordered relations
+
+> ⚠️ **Experimental**<br>
+> This API is experimental and may change in future versions. Please provide feedback on GitHub or Discord.
+
+Ordered relations maintain a list of related entities with bidirectional sync.
+
+```js
+import { relation, ordered } from 'koota'
+
+const ChildOf = relation()
+const OrderedChildren = ordered(ChildOf)
+
+const parent = world.spawn(OrderedChildren)
+const children = parent.get(OrderedChildren)
+
+children.push(child1) // adds ChildOf(parent) to child1
+children.splice(0, 1) // removes ChildOf(parent) from child1
+
+// Bidirectional sync works both ways
+child2.add(ChildOf(parent)) // child2 automatically added to list
+```
+
+Ordered relations support array methods like `push()`, `pop()`, `shift()`, `unshift()`, and `splice()`, plus special methods `moveTo()` and `insert()` for precise control. Changes to the list automatically sync with relations, and vice versa.
+
+> ⚠️ **Performance note**<br>
+> Ordered relations are more expensive to update than regular relations but enable faster traversal when order matters. Use them only when entity order is essential.
+
 #### Querying relations
 
 Relations can be queried with specific targets and wildcard targets using `*`.
@@ -286,6 +310,29 @@ const parent = world.spawn()
 const changedChildren = world.query(Changed(ChildOf), ChildOf(parent))
 ```
 
+#### Relation events
+
+Relations emit events per **relation pair**. This makes it easy to know exactly which target was involved.
+
+- `onAdd(Relation, (entity, target) => {})` triggers when `entity.add(Relation(target))` is called.
+- `onRemove(Relation, (entity, target) => {})` triggers when `entity.remove(Relation(target))` is called.
+- `onChange(Relation, (entity, target) => {})` triggers when relation **store data** is updated with `entity.set(Relation(target), data)` (only for relations created with a `store`).
+
+```js
+const ChildOf = relation({ store: { priority: 0 } })
+
+const unsubAdd = world.onAdd(ChildOf, (entity, target) => {})
+const unsubRemove = world.onRemove(ChildOf, (entity, target) => {})
+const unsubChange = world.onChange(ChildOf, (entity, target) => {})
+
+const parent = world.spawn()
+const child = world.spawn()
+
+child.add(ChildOf(parent)) // onAdd(child, parent)
+child.set(ChildOf(parent), { priority: 1 }) // onChange(child, parent)
+child.remove(ChildOf(parent)) // onRemove(child, parent)
+```
+
 ### Query modifiers
 
 Modifiers are used to filter query results enabling powerful patterns. All modifiers can be mixed together.
@@ -394,9 +441,14 @@ entity.set(Position, { x: 10, y: 20 })
 entity.remove(Position)
 ```
 
+When subscribing to relations, callbacks receive `(entity, target)` so you know which relation pair changed. Relation `onChange` events are triggered by `entity.set(Relation(target), data)` and only on relations with data via the store prop.
+
 ```js
-// Returns all queryable entities
-const allQueryableEntities = world.query()
+const Likes = relation()
+
+const unsub = world.onAdd(Likes, (entity, target) => {
+  console.log(`Entity ${entity} likes ${target}`)
+})
 ```
 
 ### Change detection with `updateEach`
@@ -808,7 +860,7 @@ const positions = getStore(world, Position)
 
 A Koota query is a lot like a database query. Parameters define how to find entities and efficiently process them in batches. Queries are the primary way to update and transform your app state, similar to how you'd use SQL to filter and modify database records.
 
-#### Caching queries
+#### Defining queries
 
 Inline queries are great for readability and are optimized to be as fast as possible, but there is still some small overhead in hashing the query each time it is called.
 
@@ -820,13 +872,13 @@ function updateMovement(world) {
 }
 ```
 
-While this is not likely to be a bottleneck in your code compared to the actual update function, if you want to save these CPU cycles you can cache the query ahead of time and use the returned key. This will have the additional effect of creating the internal query immediately on a worlds, otherwise it will get created the first time it is run.
+While this is not likely to be a bottleneck in your code compared to the actual update function, if you want to save these CPU cycles you can cache the query ahead of time and use the returned ref. This will have the additional effect of creating the internal query immediately on all worlds, otherwise it will get created the first time it is run.
 
 ```js
 // The internal query is created immediately before it is invoked
-const movementQuery = cacheQuery(Position, Velocity)
+const movementQuery = defineQuery(Position, Velocity)
 
-// They query key is hashed ahead of time and we just use it
+// The query ref is used for fast array-based lookup
 function updateMovement(world) {
   world.query(movementQuery).updateEach(([pos, vel]) => {})
 }
@@ -834,7 +886,7 @@ function updateMovement(world) {
 
 #### Query all entities
 
-To get all queryable entities you simply query with no parameters.
+To get all queryable entities you simply query the world with no parameters.
 
 ```js
 const allEntities = world.query()
@@ -1014,13 +1066,51 @@ useTraitEffect(world, GameState, (state) => {
 })
 ```
 
+### `useTarget`
+
+Observes an entity, or world, for a relation and reactively returns the first target entity. Returns `undefined` if no target exists.
+
+```js
+const ChildOf = relation()
+
+function ParentDisplay({ entity }) {
+  // Returns the first target of the ChildOf relation
+  const parent = useTarget(entity, ChildOf)
+
+  if (!parent) return <div>No parent</div>
+
+  return <div>Parent: {parent.id()}</div>
+}
+```
+
+### `useTargets`
+
+Observes an entity, or world, for a relation and reactively returns all target entities as an array. Returns an empty array if no targets exist.
+
+```js
+const Contains = relation()
+
+function InventoryDisplay({ entity }) {
+  // Returns all targets of the Contains relation
+  const items = useTargets(entity, Contains)
+
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id()}>Item {item.id()}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
 ### `useActions`
 
-Returns actions bound to the world that is context. Use actions created by `createActions`.
+Returns actions bound to the world that is in context. Use actions created by `defineActions`.
 
 ```js
 // Create actions
-const actions = createActions((world) => ({
+const actions = defineActions((world) => ({
     spawnPlayer: () => world.spawn(IsPlayer).
     destroyAllPlayers: () => {
         world.query(IsPlayer).forEach((player) => {