koota 0.5.0 → 0.5.2

package/README.md

@@ -364,6 +364,26 @@ world
   .updateEach(([position, velocity]) => {}, { changeDetection: 'always' })
 ```
 
+Changed detection shallowly compares the scalar values just like React. This means objects and arrays will only be detected as changed if a new object or array is committed to the store. While immutable state is a great design pattern, it creates memory pressure and reduces performance so instead you can mutate and manually flag that a changed has occured.
+
+```js
+// ❌ This change will not be detected since the array is mutated and will pass the comparison
+world.query(Inventory).updateEach(([inventory]) => {
+  inventory.items.push(item)
+})
+
+// ✅ This change will be detected since a new array is created and the comparison will fail
+world.query(Inventory).updateEach(([inventory]) => {
+  inventory.items = [...inventory.items, item]
+})
+
+// ✅ This change is manually flagged and we still get to mutate for performance
+world.query(Inventory).updateEach(([inventory], entity) => {
+  inventory.items.push(item)
+  entity.changed()
+})
+```
+
 ### World traits
 
 For global data like time, these can be traits added to the world. **World traits do not appear in queries.**
@@ -483,8 +503,8 @@ world.remove(Time)
 // Return boolean
 const result = world.has(Time)
 
-// Gets a snapshot instance of the trait
-// Return TraitInstance
+// Returns the trait record for the world
+// Return TraitRecord
 const time = world.get(Time)
 
 // Sets the trait and triggers a change event
@@ -539,8 +559,8 @@ entity.remove(Position)
 // Return boolean
 const result = entity.has(Position)
 
-// Gets a snapshot instance of the trait
-// Return TraitInstance
+// Gets the trait record for an entity
+// Return TraitRecord
 const position = entity.get(Position)
 
 // Sets the trait and triggers a change event
@@ -658,38 +678,63 @@ const store = [
 const Mesh = trait(() => new THREE.Mesh())
 ```
 
+#### Trait record
+
+The state of a given entity-trait pair is called a trait record and is like the row of a table in a database. When the trait store is SoA the record returned is a snapshot of the state while when it is AoS the record is a ref to the object inserted there.
+
+```js
+// SoA store
+const Position = trait({ x: 0, y: 0, z: 0 })
+entity.add(Position)
+// Returns a snapshot of the arrays
+const position = entity.get(Position)
+// position !== position2
+const position2 = entity.get(Position)
+
+// AoS store
+const Velocity = trait(() => ({ x: 0, y: 0, z: 0 }))
+entity.add(Velocity)
+// Returns a ref to the object inserted
+const velocity = entity.get(Velocity)
+// velocity === velocity2
+const velocity2 = entity.get(Velocity)
+```
+
+Use `TraitRecord` to type this state.
+
+```ts
+const PositionRecord = TraitRecord<typeof Position>
+```
+
 #### Typing traits
 
 Traits can have a schema type passed into its generic. This can be useful if the inferred type is not good enough.
 
-```js
+```ts
 type AttackerSchema = {
-  continueCombo: boolean | null,
-  currentStageIndex: number | null,
-  stages: Array<AttackStage> | null,
-  startedAt: number | null,
+  continueCombo: boolean | null
+  currentStageIndex: number | null
+  stages: Array<AttackStage> | null
+  startedAt: number | null
 }
 
-const Attacker =
-  trait <
-  AttackerSchema >
-  {
-    continueCombo: null,
-    currentStageIndex: null,
-    stages: null,
-    startedAt: null,
-  }
+const Attacker = trait<AttackerSchema>({
+  continueCombo: null,
+  currentStageIndex: null,
+  stages: null,
+  startedAt: null,
+})
 ```
 
 However, this will not work with interfaces without a workaround due to intended behavior in TypeScript: https://github.com/microsoft/TypeScript/issues/15300
 Interfaces can be used with `Pick` to convert the key signatures into something our type code can understand.
 
-```js
+```ts
 interface AttackerSchema {
-  continueCombo: boolean | null,
-  currentStageIndex: number | null,
-  stages: Array<AttackStage> | null,
-  startedAt: number | null,
+  continueCombo: boolean | null
+  currentStageIndex: number | null
+  stages: Array<AttackStage> | null
+  startedAt: number | null
 }
 
 // Pick is required to not get type errors
@@ -781,7 +826,7 @@ return (
 )
 ```
 
-### `usQueryFirst`
+### `useQueryFirst`
 
 Works like `useQuery` but only returns the first result. Can either be an entity of undefined.
 
@@ -870,7 +915,7 @@ return (
 
 ### `useTraitEffect`
 
-Subscribes a callback to a trait on an entity. This callback fires as an effect whenenver it is added, removed or changes value without rerendering.
+Subscribes a callback to a trait on an entity. This callback fires as an effect whenever it is added, removed or changes value without rerendering.
 
 ```js
 // Subscribe to position changes on an entity and update a ref without causing a rerender