@vived/core 2.0.0 → 2.0.2

package/src/DomainFactories/README.md

@@ -0,0 +1,154 @@
+# DomainFactories
+
+The DomainFactories feature provides a structured approach for organizing and initializing application domains. It enforces a multi-phase setup sequence that ensures dependencies are properly resolved across different architectural layers.
+
+## Overview
+
+A domain factory is responsible for setting up all components within a specific domain or feature of your application. The setup is orchestrated through a four-phase process:
+
+1. **Entities** - Data models and repositories
+2. **Use Cases (UCs)** - Business logic that operates on entities
+3. **Presentation Managers (PMs)** - View models that transform entity data
+4. **Final Setup** - Any remaining initialization after all components are ready
+
+This phased approach ensures that components can depend on earlier phases being complete, both within a domain and across different domains.
+
+## Core Components
+
+### DomainFactory
+
+Abstract base class that all domain factories must extend. Each concrete factory must implement four setup methods:
+
+- `setupEntities()` - Initialize data models and repositories
+- `setupUCs()` - Initialize business logic components
+- `setupPMs()` - Initialize presentation layer components
+- `finalSetup()` - Perform final initialization
+
+Domain factories automatically register themselves with the `DomainFactoryRepo` upon construction.
+
+### DomainFactoryRepo
+
+Singleton repository that manages all domain factories and orchestrates their initialization. It provides:
+
+- **Phase coordination** - Executes setup phases across all factories in the correct order
+- **Factory lookup** - Retrieve factories by name using `getByName()`
+- **Global access** - Singleton accessible via `DomainFactoryRepo.get(appObjects)`
+
+## Usage
+
+### Creating a Domain Factory
+
+```typescript
+import { DomainFactory } from "@vived/core";
+import { AppObject } from "@vived/core";
+
+export class MyFeatureDomainFactory extends DomainFactory
+{
+	readonly factoryName = "MyFeatureDomainFactory";
+
+	setupEntities(): void
+	{
+		// Create and configure entities and repositories
+		// Example: new MyEntityRepo(this.appObjects.getOrCreate("MyEntityRepo"));
+	}
+
+	setupUCs(): void
+	{
+		// Create and configure use cases
+		// Example: new MyUseCase(this.appObjects.getOrCreate("MyUseCase"));
+	}
+
+	setupPMs(): void
+	{
+		// Create and configure presentation managers
+		// Example: new MyPM(this.appObjects.getOrCreate("MyPM"));
+	}
+
+	finalSetup(): void
+	{
+		// Perform any final initialization
+		// Example: Subscribe to events, configure cross-domain dependencies
+	}
+
+	constructor(appObject: AppObject)
+	{
+		super(appObject);
+	}
+}
+```
+
+### Initializing the Domain Layer
+
+```typescript
+import { makeAppObjectRepo, makeDomainFactoryRepo } from "@vived/core";
+import { MyFeatureDomainFactory } from "./MyFeatureDomainFactory";
+import { AnotherFeatureDomainFactory } from "./AnotherFeatureDomainFactory";
+
+// Create the application object repository
+const appObjects = makeAppObjectRepo();
+
+// Create the domain factory repository
+const domainFactoryRepo = makeDomainFactoryRepo(appObjects);
+
+// Instantiate your domain factories (they auto-register)
+new MyFeatureDomainFactory(appObjects.getOrCreate("MyFeatureDomainFactory"));
+new AnotherFeatureDomainFactory(appObjects.getOrCreate("AnotherFeatureDomainFactory"));
+
+// Execute the complete domain setup in proper sequence
+domainFactoryRepo.setupDomain();
+```
+
+### Accessing a Domain Factory
+
+```typescript
+// Retrieve a specific domain factory by name
+const myFactory = domainFactoryRepo.getByName("MyFeatureDomainFactory");
+
+// Access the singleton repo from anywhere
+const repo = DomainFactoryRepo.get(appObjects);
+```
+
+## Setup Sequence
+
+When `setupDomain()` is called, the repository executes phases in this order:
+
+1. All factories execute `setupEntities()`
+2. All factories execute `setupUCs()`
+3. All factories execute `setupPMs()`
+4. All factories execute `finalSetup()`
+
+This ensures that if Factory B's use cases depend on Factory A's entities, those entities will already be initialized.
+
+## Testing
+
+The `MockDomainFactory` class provides a test double with Jest mock functions for all setup methods:
+
+```typescript
+import { MockDomainFactory } from "@vived/core";
+import { makeAppObjectRepo } from "@vived/core";
+
+const appObjects = makeAppObjectRepo();
+const mockFactory = new MockDomainFactory(appObjects.getOrCreate("test"));
+
+// Verify setup methods are called
+expect(mockFactory.setupEntities).toHaveBeenCalled();
+
+// Check call order
+expect(mockFactory.setupEntities).toHaveBeenCalledBefore(mockFactory.setupUCs);
+```
+
+## Best Practices
+
+- **Keep factories focused** - Each factory should manage a single domain or feature
+- **Use meaningful names** - Set `factoryName` to something descriptive for easy retrieval
+- **Respect phase boundaries** - Don't access components from later phases during earlier phases
+- **Avoid cross-phase dependencies** - Entities shouldn't depend on UCs, UCs shouldn't depend on PMs
+- **Use finalSetup sparingly** - Most initialization should happen in the appropriate phase
+
+## Architecture Benefits
+
+- **Dependency management** - Clear initialization order prevents "component not found" errors
+- **Modularity** - Each domain is self-contained in its own factory
+- **Testability** - Mock factories enable isolated testing of the orchestration logic
+- **Scalability** - Easy to add new domains without modifying existing code
+- **Maintainability** - Clear structure makes it obvious where components should be initialized

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