@vived/core 2.0.1 → 2.0.2

package/src/Entities/README.md

@@ -0,0 +1,340 @@
+# Entities
+
+The Entities folder provides foundational classes for building reactive, observable data models. It includes the Observer pattern implementation and a suite of memoized wrapper classes for various data types.
+
+## Overview
+
+This module solves two key problems in reactive application development:
+
+1. **Change Notification** - Notify observers when data changes (Observer pattern)
+2. **Performance Optimization** - Only trigger callbacks when values actually change (memoization)
+
+## Core Components
+
+### Observer Pattern
+
+#### ObservableEntity
+
+Abstract base class implementing the Observer pattern. Extend this to make any entity observable.
+
+```typescript
+import { ObservableEntity } from "@vived/core";
+
+export class MyEntity extends ObservableEntity
+{
+	private _name: string = "";
+
+	get name(): string
+	{
+		return this._name;
+	}
+
+	set name(value: string)
+	{
+		this._name = value;
+		this.notify(); // Notify all observers
+	}
+}
+
+// Usage
+const entity = new MyEntity();
+entity.addObserver(() => console.log("Entity changed!"));
+entity.name = "New Name"; // Logs: "Entity changed!"
+```
+
+#### ObserverList
+
+Generic implementation of the Observer pattern with typed messages. Use this when you need to pass data to observers.
+
+```typescript
+import { ObserverList } from "@vived/core";
+
+const observers = new ObserverList<string>();
+
+observers.add((message) => console.log(`Received: ${message}`));
+observers.notify("Hello World"); // Logs: "Received: Hello World"
+
+// Check observer count
+console.log(observers.length); // 1
+
+// Clear all observers
+observers.clear();
+```
+
+### Memoized Wrappers
+
+Memoized classes wrap values and only trigger callbacks when the value actually changes. This prevents unnecessary re-renders and computations.
+
+#### MemoizedBoolean
+
+Wrapper for boolean values with change detection.
+
+```typescript
+import { MemoizedBoolean } from "@vived/core";
+
+const isVisible = new MemoizedBoolean(
+	false,
+	() => console.log("Visibility changed")
+);
+
+isVisible.val = true; // Logs: "Visibility changed"
+isVisible.val = true; // No callback - value didn't change
+isVisible.val = false; // Logs: "Visibility changed"
+
+// Set without triggering callback
+isVisible.setValQuietly(true);
+```
+
+#### MemoizedNumber
+
+Wrapper for numeric values with change detection.
+
+```typescript
+import { MemoizedNumber } from "@vived/core";
+
+const count = new MemoizedNumber(
+	0,
+	() => console.log("Count changed")
+);
+
+count.val = 5; // Logs: "Count changed"
+count.val = 5; // No callback - value didn't change
+```
+
+#### MemoizedString
+
+Wrapper for string values with change detection.
+
+```typescript
+import { MemoizedString } from "@vived/core";
+
+const title = new MemoizedString(
+	"Untitled",
+	() => console.log("Title changed")
+);
+
+title.val = "New Title"; // Logs: "Title changed"
+title.val = "New Title"; // No callback - value didn't change
+```
+
+#### MemoizedAngle
+
+Wrapper for Angle value objects with change detection.
+
+```typescript
+import { MemoizedAngle, Angle } from "@vived/core";
+
+const rotation = new MemoizedAngle(
+	Angle.FromDegrees(0),
+	() => console.log("Rotation changed")
+);
+
+rotation.val = Angle.FromDegrees(45);
+```
+
+#### MemoizedVector2
+
+Wrapper for 2D vector value objects with change detection.
+
+```typescript
+import { MemoizedVector2, Vector2 } from "@vived/core";
+
+const position = new MemoizedVector2(
+	Vector2.Zero(),
+	() => console.log("Position changed")
+);
+
+position.val = new Vector2(10, 20);
+```
+
+#### MemoizedVector3
+
+Wrapper for 3D vector value objects with change detection.
+
+```typescript
+import { MemoizedVector3, Vector3 } from "@vived/core";
+
+const position = new MemoizedVector3(
+	Vector3.Zero(),
+	() => console.log("Position changed")
+);
+
+position.val = new Vector3(10, 20, 30);
+```
+
+#### MemoizedQuaternion
+
+Wrapper for quaternion rotation value objects with change detection.
+
+```typescript
+import { MemoizedQuaternion, Quaternion } from "@vived/core";
+
+const rotation = new MemoizedQuaternion(
+	Quaternion.Identity(),
+	() => console.log("Rotation changed")
+);
+
+rotation.val = Quaternion.FromEuler(0, Math.PI / 2, 0);
+```
+
+#### MemoizedColor
+
+Wrapper for color value objects with change detection.
+
+```typescript
+import { MemoizedColor, Color } from "@vived/core";
+
+const backgroundColor = new MemoizedColor(
+	Color.White(),
+	() => console.log("Color changed")
+);
+
+backgroundColor.val = Color.FromRGB(255, 0, 0);
+```
+
+### Range-Constrained Values
+
+#### RangedNumber
+
+Numeric value that is automatically clamped to a specified range.
+
+```typescript
+import { RangedNumber } from "@vived/core";
+
+const volume = new RangedNumber(
+	{
+		min: 0,
+		max: 100,
+		initialValue: 50
+	},
+	() => console.log("Volume changed")
+);
+
+volume.val = 75; // Sets to 75
+volume.val = 150; // Clamped to 100
+volume.val = -10; // Clamped to 0
+
+console.log(volume.minValue); // 0
+console.log(volume.maxValue); // 100
+```
+
+## Common Patterns
+
+### Building Reactive Entities
+
+Combine memoized values within an observable entity:
+
+```typescript
+import { ObservableEntity, MemoizedString, MemoizedNumber } from "@vived/core";
+
+export class User extends ObservableEntity
+{
+	readonly name: MemoizedString;
+	readonly age: MemoizedNumber;
+
+	constructor(name: string, age: number)
+	{
+		super();
+		this.name = new MemoizedString(name, () => this.notify());
+		this.age = new MemoizedNumber(age, () => this.notify());
+	}
+}
+
+// Usage
+const user = new User("John", 30);
+user.addObserver(() => console.log("User updated"));
+
+user.name.val = "Jane"; // Triggers observer
+user.age.val = 31; // Triggers observer
+```
+
+### Silent Updates
+
+Use `setValQuietly()` when you need to update values without triggering side effects:
+
+```typescript
+const count = new MemoizedNumber(0, () => updateUI());
+
+// Update without triggering UI update
+count.setValQuietly(10);
+```
+
+### Managing Observers
+
+```typescript
+const entity = new MyEntity();
+
+// Add observer
+const observer = () => console.log("Changed");
+entity.addObserver(observer);
+
+// Remove specific observer
+entity.removeObserver(observer);
+
+// Using ObserverList directly
+const observers = new ObserverList<void>();
+observers.add(observer);
+observers.remove(observer);
+observers.clear(); // Remove all
+```
+
+## Design Principles
+
+### Memoization
+
+All memoized classes compare values before triggering callbacks:
+- **Primitives** (boolean, number, string) use strict equality (`===`)
+- **Value Objects** (Vector, Color, etc.) use type-specific equality methods
+- This prevents unnecessary callback execution and improves performance
+
+### Immutability Considerations
+
+Value objects (Vector3, Color, etc.) should be treated as immutable. Always create new instances rather than mutating existing ones:
+
+```typescript
+// Good
+position.val = new Vector3(position.val.x + 1, position.val.y, position.val.z);
+
+// Bad - mutation won't trigger change detection
+position.val.x += 1;
+```
+
+## Testing
+
+All memoized and observable classes include comprehensive test coverage demonstrating:
+- Initial value storage
+- Change detection
+- Callback triggering
+- Silent updates
+- Range clamping (for RangedNumber)
+
+Example test pattern:
+
+```typescript
+it("only triggers callback when value changes", () => {
+	const callback = jest.fn();
+	const memoized = new MemoizedNumber(5, callback);
+
+	memoized.val = 5; // No change
+	expect(callback).not.toBeCalled();
+
+	memoized.val = 10; // Changed
+	expect(callback).toBeCalledTimes(1);
+});
+```
+
+## Use Cases
+
+- **State Management** - Track application state with automatic change notifications
+- **View Models** - Build presentation models that notify views when data changes
+- **Form Inputs** - Validate and constrain user input with RangedNumber
+- **Animation** - Track animated values and trigger updates only when they change
+- **Configuration** - Manage settings with type-safe, observable properties
+- **Game Objects** - Track entity properties (position, rotation, color) with change detection
+
+## Performance Benefits
+
+- **Reduced Re-renders** - UI updates only when values actually change
+- **Efficient Validation** - Range constraints applied automatically
+- **Lazy Computation** - Callbacks only fire when necessary
+- **Memory Efficient** - Lightweight wrappers with minimal overhead