@vived/core

Core Components for VIVED Apps and Hosts

Overview

@vived/core provides a comprehensive architecture framework for building scalable, maintainable applications using Clean Architecture principles. The library combines a component-based architecture (AppObject pattern) with reactive entities, immutable value objects, and utility functions optimized for 3D graphics and interactive applications.

Installation

npm install @vived/core

Documentation

This package includes comprehensive documentation for each module:

• AppObject Architecture - Component-based architecture pattern with entities, use cases, presentation managers, views, and controllers
• DomainFactories - Multi-phase initialization system for organizing domain components
• Entities - Observable entities with memoized properties for automatic change detection
• ValueObjects - Immutable mathematical primitives for 3D graphics and geometry
• Utilities - Helper functions for animations, colors, conversions, and file operations
• Types - TypeScript interfaces for adapters and application boundaries
• ExampleFeature - Complete reference implementation demonstrating best practices

Quick Start

AppObject Architecture

The core architecture follows Clean Architecture dependency rules with a component-based design:

import { makeAppObjectRepo } from "@vived/core";

// Create the application repository
const appObjects = makeAppObjectRepo();

// Create an AppObject
const myObject = appObjects.getOrCreate("myObject");

// Add components to it
const entity = makeMyEntity(myObject);
const useCase = makeMyUseCase(myObject);
const presentationManager = makeMyPM(myObject);

Key Components:

• Entities - Store and manage domain data with automatic change notifications
• Use Cases - Implement business logic and operations
• Presentation Managers - Transform entity data into view models for UI
• Controllers - Provide simplified APIs for UI interactions
• Adapters - Connect UI frameworks (React, Vue, etc.) to presentation managers

Domain Factories

Organize features using domain factories with phased initialization:

import { makeDomainFactoryRepo } from "@vived/core";

// Create domain factory repository
const domainFactoryRepo = makeDomainFactoryRepo(appObjects);

// Create your feature factories
new MyFeatureDomainFactory(appObjects.getOrCreate("MyFeature"));

// Initialize all features in proper order
domainFactoryRepo.setupDomain();

Reactive Entities

Build reactive data models with automatic change detection:

import { MemoizedString, MemoizedNumber, ObservableEntity } from "@vived/core";

class UserEntity extends ObservableEntity
{
	private nameProperty = new MemoizedString("", () => this.notify());
	private ageProperty = new MemoizedNumber(0, () => this.notify());
	
	get name() { return this.nameProperty.val; }
	set name(value: string) { this.nameProperty.val = value; }
	
	get age() { return this.ageProperty.val; }
	set age(value: number) { this.ageProperty.val = value; }
}

// Changes automatically notify observers
const user = new UserEntity();
user.addObserver(() => console.log("User changed!"));
user.name = "John"; // Triggers notification

Value Objects for 3D Graphics

Work with immutable mathematical primitives:

import { Vector3, Quaternion, Matrix, Color } from "@vived/core";

// Vector operations
const position = new Vector3(10, 20, 30);
const direction = Vector3.Forward();
const sum = Vector3.Add(position, direction);

// Rotations with quaternions
const rotation = Quaternion.FromYawPitchRoll(
	Angle.FromDegrees(45),
	Angle.FromDegrees(0),
	Angle.FromDegrees(0)
);

// Transformation matrices
const transform = Matrix.Translation(position);
const rotationMatrix = Matrix.FromQuaternion(rotation);

// Colors
const red = Color.RGB(255, 0, 0);
const transparent = Color.RGBA(0, 0, 0, 128);
const named = Color.X11("CornflowerBlue");

Animation Utilities

Create smooth animations with easing functions:

import { LerpNumber, quintInOut } from "@vived/core";

const lerper = new LerpNumber();

// Animate a value from 0 to 100 over 2 seconds
await lerper.lerp({
	start: 0,
	end: 100,
	durationMS: 2000,
	ease: quintInOut,
	update: (value) => {
		element.style.opacity = value / 100;
	},
	onComplete: () => {
		console.log("Animation complete!");
	}
});

UI Integration with Adapters

Connect your UI framework to the architecture:

import { useEffect, useState } from "react";
import { myFeatureAdapter } from "@vived/core";

function MyComponent({ id, appObjects })
{
	const [viewModel, setViewModel] = useState(myFeatureAdapter.defaultVM);
	
	useEffect(() => {
		// Subscribe to updates
		myFeatureAdapter.subscribe(id, appObjects, setViewModel);
		
		// Cleanup on unmount
		return () => {
			myFeatureAdapter.unsubscribe(id, appObjects, setViewModel);
		};
	}, [id]);
	
	return <div>{viewModel.someProperty}</div>;
}

Package Contents

Architecture Components

• AppObject System - Component container pattern with dependency injection
• Entity System - Observable entities with memoized properties
• Repository Pattern - Manage collections of entities
• Use Cases - Business logic layer
• Presentation Managers - View model transformation layer
• Controllers - Simplified UI interaction APIs
• Adapters - Framework-agnostic UI integration

Value Objects

Vectors & Geometry:

• Vector2, Vector3 - 2D and 3D vectors with full operations
• Quaternion - 3D rotation representation
• Matrix - 4x4 transformation matrices
• Angle - Type-safe angle conversions
• Rectangle - 2D rectangular bounds
• LineSegment2D - 2D line segment operations
• ParametricLine - 3D parametric line representation
• ParametricPlane - 3D plane representation

Graphics:

• Color - RGBA color with hex and X11 color support

Versioning:

• Version - Semantic version parsing and comparison

Utilities

Animation:

• LerpNumber - Smooth numeric interpolation
• Easing functions - 20+ easing functions (quad, cubic, quart, quint, sin, expo, circ)
• interpolateNumber - Basic numeric interpolation

Color:

• addAlphaToHex - Add transparency to hex colors
• alphaToHex - Convert alpha values to hex

Conversion:

• degreesToRadians - Angle conversion
• Length converters - Inches/feet to meters and vice versa

File Operations:

• downloadFile - Trigger browser downloads
• generateUniqueID - UUID v4 generation

Types

• PmAdapter - Interface for connecting UI to presentation managers
• SingletonPmAdapter - Interface for singleton presentation managers
• EaseFn - Type definition for easing functions
• AppBoundary - Application embedding interfaces

Architecture Principles

Clean Architecture

The library enforces dependency rules where inner layers never depend on outer layers:

UI Layer
    ↓
Adapters & Controllers
    ↓
Presentation Managers
    ↓
Use Cases
    ↓
Entities

Component-Based Design

Everything is a component attached to an AppObject:

• Promotes composition over inheritance
• Enables dependency injection
• Facilitates testing with mock components
• Supports both instance and singleton patterns

Reactive by Default

Entities notify observers when they change:

• Automatic UI updates
• No manual refresh logic needed
• Performance optimized with memoization

Immutable Value Objects

Mathematical primitives are immutable:

• Thread-safe operations
• Predictable behavior
• Easy to reason about
• Optimal for 3D graphics pipelines

Example Feature

See ExampleFeature for a complete, production-ready reference implementation showing:

• Feature folder structure
• Entity, Use Case, and PM implementation
• Controller and Adapter patterns
• React integration examples
• Testing strategies
• Factory-based initialization

Use Cases

• 3D Graphics Applications - WebGL, Three.js, Babylon.js applications
• VR/AR Experiences - Interactive virtual environments
• Data Visualization - Charts, graphs, and interactive dashboards
• Game Development - Game engines and interactive experiences
• Educational Software - Interactive learning applications
• Configuration Tools - Complex application settings and preferences

TypeScript Support

Fully typed with TypeScript definitions included. Supports both ESM and CommonJS:

{
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js",
      "types": "./dist/types/index.d.ts"
    }
  }
}

Contributing

This is a foundational library for VIVED applications. For detailed architecture decisions and patterns, refer to the comprehensive documentation in each module's README.

License

ISC