🔖 version bump

Author: krispya

packages/publish/README.md

@@ -217,6 +217,35 @@ const containsAnything = world.query(Contains('*')) // Returns [inventory, chest
 const relatesToGold = world.query(Wildcard(gold)) // Returns [inventory, chest, dwarf]
 ```
 
+#### Removing relationships
+
+A relationship targets a specific entity, so we need to likewise remove relationships with specific entities.
+
+```js
+// Add a specific relation
+player.add(Likes(apple))
+player.add(Likes(banana))
+
+// Remove that same relation
+player.remove(Likes(apple))
+
+player.has(apple) // false
+player.has(banana) // true
+```
+
+However, a wildcard can be used to remove all relationships of a kind — for all targets — from an entity.
+
+```js
+player.add(Likes(apple))
+player.add(Likes(banana))
+
+// Remove all Likes relations
+player.remove(Likes('*'))
+
+player.has(apple) // false
+player.has(banana) // false
+```
+
 ### Query modifiers
 
 Modifiers are used to filter query results enabling powerful patterns. All modifiers can be mixed together.
@@ -550,30 +579,35 @@ const { entityId, generation, worldId } = unpackEntity(entity)
 
 ### Trait
 
-A trait is a specific block of data. They are added to entities to build up its overall data signature. If you are familiar with ECS, it is our version of a component. It is called a trait instead to not get confused with React or web components.
+Traits are self-contained slices of data you attach to an entity to define its state. They serve the same purpose as components in a traditional ECS. We call them traits to avoid confusion with React or web components.
 
 A trait can be created with a schema that describes the kind of data it will hold.
 
 ```js
 const Position = trait({ x: 0, y: 0, z: 0 })
 ```
 
-In cases where the data needs to be initialized for each instance of the trait created, a callback can be passed in to be used a as a lazy initializer.
+A schema supports primitive values with **no** nested objects or arrays. In cases where the data needs to initialized for each instance of the trait, or complex structures are required, a callback initializer can be used.
 
 ```js
-// ❌ The items array will be shared between every instance of this trait
+// ❌ Arrays and objects are not allowed in trait schemas
 const Inventory = trait({
   items: [],
+  vec3: { x: 0, y: 0, z: 0}
   max: 10,
 })
 
-// ✅ With a lazy initializer, each instance will now get its own array
+// ✅ Use a callback initializer for arrays and objects
 const Inventory = trait({
   items: () => [],
+  vec3: () => ({ x: 0, y: 0, z: 0})
   max: 10,
 })
 ```
 
+> ℹ️ **Why not support nested schemas?**<br>
+> It looks obvious to support nested stores, but doing so makes algorithms that work with the data exponentially more complex. If all data can be assumed scalar then any operation is guaranteed to be the simplest and fastest algorithm possible. This is called the First Normal Form in relational database theory. [You can read more here](https://www.dataorienteddesign.com/dodbook/node3.html#SECTION00340000000000000000).
+
 Sometimes a trait only has one field that points to an object instance. In cases like this, it is useful to skip the schema and use a callback directly in the trait.
 
 ```js

packages/publish/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "koota",
-	"version": "0.4.4",
+	"version": "0.5.0",
 	"description": "🌎 Performant real-time state management for React and TypeScript",
 	"license": "ISC",
 	"type": "module",

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

@@ -12,8 +12,8 @@ import {
 
 const Position = trait({ x: 0, y: 0 });
 const IsActive = trait();
-const Foo = trait({});
-const Bar = trait({});
+const Foo = trait();
+const Bar = trait();
 
 describe('Query modifiers', () => {
 	const world = createWorld();

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

@@ -4,8 +4,8 @@ import { $internal, cacheQuery, createWorld, IsExcluded, Not, Or, trait } from '
 const Position = trait({ x: 0, y: 0 });
 const Name = trait({ name: 'name' });
 const IsActive = trait();
-const Foo = trait({});
-const Bar = trait({});
+const Foo = trait();
+const Bar = trait();
 
 describe('Query', () => {
 	const world = createWorld();

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

@@ -57,6 +57,12 @@ describe('Relation', () => {
 		expect(target).toBe(player);
 		expect(goblin.has(Targeting(player))).toBe(true);
 		expect(goblin.has(Targeting(guard))).toBe(false);
+
+		// Remove the target and check if the target is removed
+		goblin.remove(Targeting(player));
+		target = goblin.targetFor(Targeting);
+
+		expect(target).toBe(undefined);
 	});
 
 	it('should auto remove target and its descendants', () => {
@@ -210,4 +216,20 @@ describe('Relation', () => {
 		expect(world.has(apple)).toBe(true);
 		expect(world.has(cherry)).toBe(true);
 	});
+
+	it('should remove all relations with a wildcard', () => {
+		const Likes = relation();
+
+		const person = world.spawn();
+		const apple = world.spawn();
+		const banana = world.spawn();
+
+		person.add(Likes(apple));
+		person.add(Likes(banana));
+
+		person.remove(Likes('*'));
+
+		expect(person.has(Likes(apple))).toBe(false);
+		expect(person.has(Likes(banana))).toBe(false);
+	});
 });

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

@@ -29,6 +29,13 @@ describe('Trait', () => {
 		expect(typeof Test === 'function').toBe(true);
 	});
 
+	it('should throw an error if the schema contains an object or array', () => {
+		// @ts-expect-error - we want to test the error case
+		expect(() => trait({ object: { a: 1, b: 2 } })).toThrow();
+		// @ts-expect-error - we want to test the error case
+		expect(() => trait({ array: [1, 2, 3] })).toThrow();
+	});
+
 	it('should add and remove traits to an entity', () => {
 		const entity = world.spawn();
 

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

@@ -92,6 +92,24 @@ describe('World', () => {
 		expect(world.has(Time)).toBe(false);
 	});
 
+	it('should set singletons', () => {
+		const Test = trait({ last: 0, delta: 0 });
+		const world = createWorld(Test);
+
+		world.set(Test, { last: 1, delta: 1 });
+
+		expect(world.get(Test)!.last).toBe(1);
+		expect(world.get(Test)!.delta).toBe(1);
+
+		// Use callbacks to set.
+		world.set(Test, (prev) => {
+			return { last: prev.last + 1, delta: prev.delta + 1 };
+		});
+
+		expect(world.get(Test)!.last).toBe(2);
+		expect(world.get(Test)!.delta).toBe(2);
+	});
+
 	it('should observe traits', () => {
 		const TimeOfDay = trait({ hour: 0 });
 		const world = createWorld(TimeOfDay);