@vived/core 2.0.0 → 2.0.2

package/src/ExampleFeature/README.md

@@ -0,0 +1,804 @@
+# ExampleFeature
+
+The ExampleFeature folder provides a complete, working example of how to implement a domain feature using the AppObject architecture and Clean Code dependency rules. This example demonstrates the proper structure, patterns, and practices for building maintainable, testable features.
+
+## Overview
+
+This feature demonstrates:
+- **Clean Architecture layers** - Entities, Use Cases, Presentation Managers, Controllers, and Adapters
+- **AppObject pattern** - Component-based architecture with dependency injection
+- **Singleton vs Instance patterns** - When to use global vs per-instance components
+- **Observable pattern** - Automatic UI updates when data changes
+- **Domain-driven design** - Organized by feature, not by technical layer
+- **Test-driven development** - Comprehensive test coverage for all components
+
+## Architecture Layers
+
+### Dependency Flow (Clean Architecture)
+
+```
+UI Layer (React/Vue/etc.)
+    ↓ (depends on)
+Adapters Layer
+    ↓ (depends on)
+Controllers Layer
+    ↓ (depends on)
+Presentation Managers (PMs)
+    ↓ (depends on)
+Use Cases (UCs)
+    ↓ (depends on)
+Entities Layer
+```
+
+**Key Rule:** Dependencies only flow inward. Inner layers never depend on outer layers.
+
+## Folder Structure
+
+```
+ExampleFeature/
+├── index.ts          # Barrel file exporting all controllers and adapters
+├── Entities/         # Domain models (innermost layer)
+├── UCs/             # Business logic (Use Cases)
+├── PMs/             # Presentation logic (View Models)
+├── Controllers/     # Simplified API for UI
+├── Adapters/        # UI framework integration
+├── Factory/         # Domain initialization
+└── Mocks/           # Test doubles
+```
+
+**Note:** The root `index.ts` barrel file exports all controllers and adapters, providing a single import point for consuming code.
+
+## Layer-by-Layer Guide
+
+### 1. Entities Layer
+
+Entities store and manage domain data, tracking state changes and notifying observers.
+
+**ExampleEntity.ts** - Instance-based entity (multiple instances possible):
+
+```typescript
+import { AppObject, AppObjectEntity } from "@vived/core";
+import { MemoizedString } from "@vived/core";
+
+export abstract class ExampleEntity extends AppObjectEntity
+{
+	static readonly type = "ExampleEntityType";
+	
+	abstract get aStringProperty(): string;
+	abstract set aStringProperty(val: string);
+	
+	static getById(id: string, appObjects: AppObjectRepo): ExampleEntity | undefined
+	{
+		return appObjects.get(id)?.getComponent<ExampleEntity>(this.type);
+	}
+}
+
+export function makeExampleEntity(appObject: AppObject): ExampleEntity
+{
+	return new ExampleEntityImp(appObject);
+}
+
+class ExampleEntityImp extends ExampleEntity
+{
+	private memoizedString = new MemoizedString("", this.notifyOnChange);
+	
+	get aStringProperty()
+	{
+		return this.memoizedString.val;
+	}
+	
+	set aStringProperty(val: string)
+	{
+		this.memoizedString.val = val; // Automatically notifies observers
+	}
+	
+	constructor(appObject: AppObject)
+	{
+		super(appObject, ExampleEntity.type);
+	}
+}
+```
+
+**ExampleSingletonEntity.ts** - Singleton entity (only one instance globally):
+
+```typescript
+import { AppObjectSingletonEntity, getSingletonComponent } from "@vived/core";
+import { MemoizedBoolean } from "@vived/core";
+
+export abstract class SingletonEntityExample extends AppObjectSingletonEntity
+{
+	static readonly type = "SingletonEntityExampleType";
+	
+	abstract get aBoolProperty(): boolean;
+	abstract set aBoolProperty(val: boolean);
+	
+	static get(appObjects: AppObjectRepo): SingletonEntityExample | undefined
+	{
+		return getSingletonComponent(SingletonEntityExample.type, appObjects);
+	}
+}
+
+class SingletonEntityExampleImp extends SingletonEntityExample
+{
+	private memoizedBoolean = new MemoizedBoolean(false, this.notifyOnChange);
+	
+	get aBoolProperty()
+	{
+		return this.memoizedBoolean.val;
+	}
+	
+	set aBoolProperty(val: boolean)
+	{
+		this.memoizedBoolean.val = val;
+	}
+	
+	constructor(appObject: AppObject)
+	{
+		super(appObject, SingletonEntityExample.type);
+	}
+}
+```
+
+**ExampleRepo.ts** - Repository for managing collections:
+
+```typescript
+import { AppObjectEntityRepo } from "@vived/core";
+
+export abstract class ExampleRepo extends AppObjectEntityRepo<ExampleEntity>
+{
+	static readonly type = "ExampleRepoType";
+	abstract deleteExampleEntity(id: string): void;
+}
+
+class ExampleRepoImp extends ExampleRepo
+{
+	entityFactory(appObject: AppObject): ExampleEntity
+	{
+		return makeExampleEntity(appObject);
+	}
+	
+	deleteExampleEntity(id: string): void
+	{
+		this.remove(id);
+	}
+	
+	constructor(appObject: AppObject)
+	{
+		super(appObject, ExampleRepo.type);
+	}
+}
+```
+
+**Key Concepts:**
+- Use `MemoizedString`, `MemoizedBoolean`, etc. for automatic change detection
+- Extend `AppObjectEntity` for instance-based entities
+- Extend `AppObjectSingletonEntity` for global entities
+- Use repositories to manage collections of entities
+
+### 2. Use Cases (UCs) Layer
+
+UCs encapsulate business logic and operations that modify entities.
+
+**EditExampleStringUC.ts** - Instance-based UC:
+
+```typescript
+import { AppObjectUC } from "@vived/core";
+
+export abstract class EditExampleStringUC extends AppObjectUC
+{
+	static readonly type = "EditExampleStringUCType";
+	abstract editExampleString(text: string): void;
+	
+	static getById(id: string, appObjects: AppObjectRepo): EditExampleStringUC | undefined
+	{
+		return appObjects.get(id)?.getComponent<EditExampleStringUC>(this.type);
+	}
+}
+
+class EditSlideTextUCImp extends EditExampleStringUC
+{
+	private get exampleEntity()
+	{
+		return this.getCachedLocalComponent<ExampleEntity>(ExampleEntity.type);
+	}
+	
+	editExampleString = (text: string) => {
+		this.exampleEntity.aStringProperty = text;
+	};
+	
+	constructor(appObject: AppObject)
+	{
+		super(appObject, EditExampleStringUC.type);
+	}
+}
+```
+
+**ToggleExampleBooleanUC.ts** - Singleton UC:
+
+```typescript
+import { AppObjectSingletonUC, getSingletonComponent } from "@vived/core";
+
+export abstract class ToggleExampleBooleanUC extends AppObjectSingletonUC
+{
+	static readonly type = "ToggleExampleBooleanUCType";
+	abstract toggleExampleBoolean(): void;
+	
+	static get(appObjects: AppObjectRepo): ToggleExampleBooleanUC | undefined
+	{
+		return getSingletonComponent(ToggleExampleBooleanUC.type, appObjects);
+	}
+}
+
+class ToggleExampleBooleanUCImp extends ToggleExampleBooleanUC
+{
+	private get singletonEntityExample()
+	{
+		return this.getCachedSingleton<SingletonEntityExample>(
+			SingletonEntityExample.type
+		);
+	}
+	
+	toggleExampleBoolean = () => {
+		this.singletonEntityExample.aBoolProperty = 
+			!this.singletonEntityExample.aBoolProperty;
+	};
+	
+	constructor(appObject: AppObject)
+	{
+		super(appObject, ToggleExampleBooleanUC.type);
+	}
+}
+```
+
+**Key Concepts:**
+- UCs contain business logic, not presentation logic
+- Use `getCachedLocalComponent()` for components on the same AppObject
+- Use `getCachedSingleton()` for singleton components
+- Methods should be named after the action they perform
+
+### 3. Presentation Managers (PMs) Layer
+
+PMs transform entity data into view models for the UI.
+
+**ExamplePM.ts** - Instance-based PM:
+
+```typescript
+import { AppObjectPM } from "@vived/core";
+
+export abstract class ExamplePM extends AppObjectPM<string>
+{
+	static readonly type = "ExamplePMType";
+	
+	static getById(id: string, appObjects: AppObjectRepo): ExamplePM | undefined
+	{
+		return appObjects.get(id)?.getComponent<ExamplePM>(ExamplePM.type);
+	}
+}
+
+class ExamplePMImp extends ExamplePM
+{
+	readonly defaultVM = "";
+	
+	private get exampleEntity()
+	{
+		return this.getCachedLocalComponent<ExampleEntity>(ExampleEntity.type);
+	}
+	
+	vmsAreEqual(a: string, b: string): boolean
+	{
+		return a === b;
+	}
+	
+	formVM = () => {
+		// Transform entity data into view model
+		this.doUpdateView(this.exampleEntity.aStringProperty);
+	};
+	
+	constructor(appObject: AppObject)
+	{
+		super(appObject, ExamplePM.type);
+		this.observeEntity(this.exampleEntity); // Subscribe to changes
+		this.formVM(); // Initial view model
+	}
+}
+```
+
+**ExampleSingletonPM.ts** - Singleton PM:
+
+```typescript
+import { AppObjectSingletonPM, getSingletonComponent } from "@vived/core";
+
+export interface ExampleVM
+{
+	aBoolProperty: boolean;
+}
+
+export abstract class ExampleSingletonPM extends AppObjectSingletonPM<ExampleVM>
+{
+	static readonly type = "ExampleSingletonPMType";
+	
+	static get(appObjects: AppObjectRepo): ExampleSingletonPM | undefined
+	{
+		return getSingletonComponent(ExampleSingletonPM.type, appObjects);
+	}
+}
+
+export const defaultExampleVM: ExampleVM = {
+	aBoolProperty: true
+};
+
+class ExampleSingletonPMImp extends ExampleSingletonPM
+{
+	private get exampleEntity()
+	{
+		return this.getCachedSingleton<SingletonEntityExample>(
+			SingletonEntityExample.type
+		);
+	}
+	
+	formVM = () => {
+		const vm: ExampleVM = {
+			aBoolProperty: this.exampleEntity.aBoolProperty
+		};
+		this.doUpdateView(vm);
+	};
+	
+	vmsAreEqual(a: ExampleVM, b: ExampleVM): boolean
+	{
+		return a.aBoolProperty === b.aBoolProperty;
+	}
+	
+	constructor(appObject: AppObject)
+	{
+		super(appObject, ExampleSingletonPM.type);
+		this.observeEntity(this.exampleEntity);
+		this.formVM();
+	}
+}
+```
+
+**Key Concepts:**
+- PMs observe entities and call `formVM()` when they change
+- Define view model interfaces for complex data structures
+- Implement `vmsAreEqual()` to prevent unnecessary UI updates
+- Call `doUpdateView()` to notify UI components
+
+### 4. Controllers Layer
+
+Controllers provide a simplified API for UI components.
+
+**setExampleText.ts** - Instance-based controller:
+
+```typescript
+import { AppObjectRepo } from "@vived/core";
+import { EditExampleStringUC } from "../UCs/EditExampleStringUC";
+
+export function setExampleText(
+	text: string,
+	id: string,
+	appObjects: AppObjectRepo
+)
+{
+	const uc = EditExampleStringUC.getById(id, appObjects);
+	
+	if (!uc)
+	{
+		appObjects.submitWarning(
+			"setExampleText",
+			"Unable to find EditExampleStringUC"
+		);
+		return;
+	}
+	
+	uc.editExampleString(text);
+}
+```
+
+**toggleExampleBoolean.ts** - Singleton controller:
+
+```typescript
+import { AppObjectRepo } from "@vived/core";
+import { ToggleExampleBooleanUC } from "../UCs/ToggleExampleBooleanUC";
+
+export function toggleExampleBoolean(appObjects: AppObjectRepo)
+{
+	const uc = ToggleExampleBooleanUC.get(appObjects);
+	
+	if (!uc)
+	{
+		appObjects.submitWarning(
+			"toggleExampleBoolean",
+			"Unable to find ToggleExampleBooleanUC"
+		);
+		return;
+	}
+	
+	uc.toggleExampleBoolean();
+}
+```
+
+**Key Concepts:**
+- Controllers are simple functions, not classes
+- They find the appropriate UC and call its methods
+- They handle errors gracefully with warnings
+- They simplify the API for UI components
+
+### 5. Adapters Layer
+
+Adapters connect UI frameworks to PMs.
+
+**examplePmAdapter.ts** - Instance-based adapter:
+
+```typescript
+import { PmAdapter } from "@vived/core";
+import { ExamplePM } from "../PMs/ExamplePM";
+
+export const examplePmAdapter: PmAdapter<string> = {
+	defaultVM: "",
+	
+	subscribe: (id: string, appObjects: AppObjectRepo, setVM: (vm: string) => void) => {
+		if (!id) return;
+		
+		const pm = ExamplePM.getById(id, appObjects);
+		if (!pm)
+		{
+			appObjects.submitWarning("examplePmAdapter", "Unable to find ExamplePM");
+			return;
+		}
+		
+		pm.addView(setVM);
+	},
+	
+	unsubscribe: (id: string, appObjects: AppObjectRepo, setVM: (vm: string) => void) => {
+		ExamplePM.getById(id, appObjects)?.removeView(setVM);
+	}
+};
+```
+
+**exampleSingletonPmAdapter.ts** - Singleton adapter:
+
+```typescript
+import { SingletonPmAdapter } from "@vived/core";
+import { ExampleSingletonPM, ExampleVM, defaultExampleVM } from "../PMs/ExampleSingletonPM";
+
+export const exampleSingletonPmAdapter: SingletonPmAdapter<ExampleVM> = {
+	defaultVM: defaultExampleVM,
+	
+	subscribe: (appObjects: AppObjectRepo, setVM: (vm: ExampleVM) => void) => {
+		const pm = ExampleSingletonPM.get(appObjects);
+		if (!pm)
+		{
+			appObjects.submitWarning(
+				"exampleSingletonPmAdapter",
+				"Unable to find ExampleSingletonPM"
+			);
+			return;
+		}
+		
+		pm.addView(setVM);
+	},
+	
+	unsubscribe: (appObjects: AppObjectRepo, setVM: (vm: ExampleVM) => void) => {
+		ExampleSingletonPM.get(appObjects)?.removeView(setVM);
+	}
+};
+```
+
+**Key Concepts:**
+- Adapters implement `PmAdapter<VM>` or `SingletonPmAdapter<VM>`
+- They provide a `defaultVM` for initial rendering
+- They handle subscription and unsubscription lifecycle
+
+### 6. Factory
+
+The factory initializes all components in the correct order.
+
+**ExampleFeatureFactory.ts**:
+
+```typescript
+import { DomainFactory } from "@vived/core";
+
+export class ExampleFeatureFactory extends DomainFactory
+{
+	factoryName = "ExampleFeatureFactory";
+	
+	setupEntities(): void
+	{
+		// Create singleton entities
+		makeSingletonEntityExample(this.appObject);
+	}
+	
+	setupUCs(): void
+	{
+		// Create use cases
+		makeToggleExampleBooleanUC(this.appObject);
+	}
+	
+	setupPMs(): void
+	{
+		// Create presentation managers
+		makeExampleSingletonPM(this.appObject);
+	}
+	
+	finalSetup(): void
+	{
+		// Any final initialization
+	}
+}
+
+export function makeExampleFeatureFactory(appObjects: AppObjectRepo)
+{
+	const appObject = appObjects.getOrCreate("ExampleFeature");
+	return new ExampleFeatureFactory(appObject);
+}
+```
+
+**Key Concepts:**
+- Factories initialize components in order: Entities → UCs → PMs → Final
+- This ensures dependencies are available when needed
+- Each feature has its own factory
+
+## React Integration Example
+
+### Using Instance-Based Components
+
+```typescript
+import { useEffect, useState } from "react";
+import { examplePmAdapter, setExampleText } from "../ExampleFeature";
+
+function ExampleTextInput({ id, appObjects })
+{
+	const [viewModel, setViewModel] = useState(examplePmAdapter.defaultVM);
+	
+	useEffect(() => {
+		// Subscribe to PM updates
+		examplePmAdapter.subscribe(id, appObjects, setViewModel);
+		
+		// Cleanup on unmount
+		return () => {
+			examplePmAdapter.unsubscribe(id, appObjects, setViewModel);
+		};
+	}, [id]);
+	
+	const handleChange = (e) => {
+		setExampleText(e.target.value, id, appObjects);
+	};
+	
+	return (
+		<input
+			type="text"
+			value={viewModel}
+			onChange={handleChange}
+		/>
+	);
+}
+```
+
+### Using Singleton Components
+
+```typescript
+import { useEffect, useState } from "react";
+import { exampleSingletonPmAdapter } from "../Adapters";
+import { toggleExampleBoolean } fr, toggleExampleBoolean } from "../ExampleFeature
+function ExampleToggle({ appObjects })
+{
+	const [viewModel, setViewModel] = useState(
+		exampleSingletonPmAdapter.defaultVM
+	);
+	
+	useEffect(() => {
+		// Subscribe to singleton PM updates (no ID needed)
+		exampleSingletonPmAdapter.subscribe(appObjects, setViewModel);
+		
+		// Cleanup on unmount
+		return () => {
+			exampleSingletonPmAdapter.unsubscribe(appObjects, setViewModel);
+		};
+	}, []);
+	
+	const handleToggle = () => {
+		toggleExampleBoolean(appObjects);
+	};
+	
+	return (
+		<div>
+			<p>Boolean value: {viewModel.aBoolProperty ? "True" : "False"}</p>
+			<button onClick={handleToggle}>Toggle</button>
+		</div>
+	);
+}
+```
+
+## Testing Examples
+
+### Testing Entities
+
+```typescript
+describe("ExampleEntity", () => {
+	it("notifies observers when property changes", () => {
+		const appObject = appObjects.getOrCreate("test");
+		const entity = makeExampleEntity(appObject);
+		const observer = jest.fn();
+		
+		entity.addObserver(observer);
+		entity.aStringProperty = "new value";
+		
+		expect(observer).toHaveBeenCalled();
+	});
+});
+```
+
+### Testing Use Cases
+
+```typescript
+describe("EditExampleStringUC", () => {
+	it("updates entity string property", () => {
+		const appObject = appObjects.getOrCreate("test");
+		const entity = makeExampleEntity(appObject);
+		const uc = makeEditSlideTextUC(appObject);
+		
+		uc.editExampleString("test text");
+		
+		expect(entity.aStringProperty).toBe("test text");
+	});
+});
+```
+
+### Testing Presentation Managers
+
+```typescript
+describe("ExamplePM", () => {
+	it("provides updated view model when entity changes", () => {
+		const appObject = appObjects.getOrCreate("test");
+		const entity = makeExampleEntity(appObject);
+		const pm = makeExamplePM(appObject);
+		const viewCallback = jest.fn();
+		
+		pm.addView(viewCallback);
+		entity.aStringProperty = "new value";
+		
+		expect(viewCallback).toHaveBeenCalledWith("new value");
+	});
+});
+```
+
+## Design Patterns Used
+
+### 1. Clean Architecture
+- Dependency inversion: inner layers don't depend on outer layers
+- Separation of concerns: each layer has a specific responsibility
+
+### 2. Observer Pattern
+- Entities notify observers when they change
+- PMs observe entities and update views
+- UI components observe PMs and update themselves
+
+### 3. Repository Pattern
+- Repositories manage collections of entities
+- Provide creation, retrieval, and deletion operations
+
+### 4. Factory Pattern
+- Factories create and initialize domain components
+- Ensure proper setup order and dependencies
+
+### 5. Adapter Pattern
+- Adapters connect UI frameworks to the application
+- Provide framework-agnostic integration
+
+## Best Practices
+
+### When to Use Singleton vs Instance
+
+**Use Singleton When:**
+- Only one instance needed globally (e.g., app settings, user session)
+- Accessed from multiple unrelated parts of the app
+- Represents global application state
+
+**Use Instance When:**
+- Multiple instances needed (e.g., multiple items in a list)
+- Each instance has its own data and lifecycle
+- Represents domain objects with identity
+
+### Component Organization
+
+```typescript
+// ✅ Good: Abstract class + Factory + Private implementation
+export abstract class MyEntity extends AppObjectEntity { }
+export function makeMyEntity(appObject: AppObject): MyEntity { }
+class MyEntityImp extends MyEntity { }
+
+// ❌ Bad: Public implementation class
+export class MyEntity extends AppObjectEntity { }
+```
+
+### Dependency Access
+
+```typescript
+// ✅ Good: Use cached getters
+private get myEntity()
+{
+	return this.getCachedLocalComponent<MyEntity>(MyEntity.type);
+}
+
+// ❌ Bad: Repeated lookups
+myMethod()
+{
+	const entity = this.appObject.getComponent<MyEntity>(MyEntity.type);
+}
+```
+
+### Error Handling
+
+```typescript
+// ✅ Good: Graceful error handling with warnings
+if (!uc)
+{
+	appObjects.submitWarning("controllerName", "UC not found");
+	return;
+}
+
+// ❌ Bad: Throwing errors or failing silently
+uc.doSomething(); // Crashes if uc is undefined
+```
+
+## Common Pitfalls to Avoid
+
+1. **Violating dependency rules** - Don't make entities depend on UCs or PMs
+2. **Forgetting to observe entities** - PMs won't update if they don't observe entities
+3. **Not implementing vmsAreEqual()** - Can cause unnecessary UI re-renders
+4. **Memory leaks** - Always unsubscribe views when components unmount
+5. **Missing error handling** - Always check if components exist before using them
+
+## Barrel File (index.ts)
+
+The ExampleFeature includes a root barrel file that exports all controllers and adapters. This provides a single import point and clear public API:
+
+**ExampleFeature/index.ts:**
+```typescript
+// Controllers
+export * from "./Controllers/setExampleText";
+export * from "./Controllers/toggleExampleBoolean";
+
+// Adapters
+export * from "./Adapters/examplePmAdapter";
+export * from "./Adapters/exampleSingletonPmAdapter";
+```
+
+**Benefits:**
+- Single import statement for all feature exports
+- Clear public API surface for the entire feature
+- Easier refactoring (internal structure can change without affecting consumers)
+- Better code organization and encapsulation
+
+**Usage:**
+```typescript
+// ✅ Good: Import from feature barrel file
+import { 
+  setExampleText, 
+  toggleExampleBoolean,
+  examplePmAdapter,
+  exampleSingletonPmAdapter 
+} from "../ExampleFeature";
+
+// ❌ Avoid: Direct file imports
+import { setExampleText } from "../ExampleFeature/Controllers/setExampleText";
+import { examplePmAdapter } from "../ExampleFeature/Adapters/examplePmAdapter";
+```
+
+## Creating Your Own Feature
+
+Follow these steps to create a new feature based on this example:
+
+1. **Create folder structure** matching ExampleFeature
+2. **Define entities** representing your domain data
+3. **Create repositories** if managing collections
+4. **Implement use cases** for business operations
+5. **Build presentation managers** to transform data for UI
+6. **Add controllers** to simplify the API
+7. **Create adapters** for UI framework integration
+8. **Add root barrel file** (`index.ts`) exporting all controllers and adapters
+9. **Write factory** to initialize everything
+10. **Add tests** for all components
+11. **Integrate** into your application via DomainFactoryRepo
+
+This example provides a complete, production-ready pattern for building scalable, maintainable features using Clean Architecture principles.