[](https://www.npmjs.com/package/x-view-model)
[](https://opensource.org/licenses/ISC)
[](https://www.typescriptlang.org/)
[](https://bundlephobia.com/package/x-view-model)
[](#contributing)
A lightweight, type-safe MVVM state management solution for React applications
## Why x-view-model?
x-view-model is designed to provide a simple yet powerful state management solution for React applications. It combines the best practices of MVVM pattern with modern React features:
- 🚀 **High Performance**: Optimized for minimal re-renders and efficient updates
- 💪 **Type Safety**: Full TypeScript support with comprehensive type inference
- 🎯 **MVVM Pattern**: Clean separation of concerns between view and business logic
- 🔄 **Reactive**: Automatic updates when state changes
- 🎨 **Computed Properties**: Derive values from state with automatic updates
- 🔍 **Deep Path Selection**: Subscribe to nested state changes efficiently
- 📦 **Lightweight**: Minimal bundle size (~13.5KB minified, ~5KB gzipped)
- 🛠 **Developer Experience**: Intuitive API with comprehensive tooling
- 🔄 **Smart Memory Management**: Automatic disposal through reference counting
## Why Choose x-view-model Over Other Solutions?
### 🏆 Superior TypeScript Support
Unlike other state management libraries that add TypeScript support as an afterthought, x-view-model is built with TypeScript from the ground up:
```typescript
// Full type inference for state and methods
const [state, send] = useViewModel(userVM, ["name", "email"]);
// Type-safe path selection
const [state] = useMemoizedViewModel(userVM, [
"profile.avatar",
"settings.theme",
] as const);
// Type-safe computed values
const [state] = useComputedViewModel(
userVM,
(state) => ({
fullName: `${state.firstName} ${state.lastName}`,
}),
["firstName", "lastName"]
);
```
### ⚡️ Unmatched Performance
x-view-model is designed for maximum performance:
- **Zero Dependencies**: No external dependencies means faster loading and smaller bundle size
- **Smart Updates**: Only re-renders components when their subscribed state changes
- **Efficient Path Selection**: Subscribe to specific state paths to minimize re-renders
- **Optimized Computations**: Computed values are cached and only recomputed when dependencies change
- **Tree-shakeable**: Only include the code you use in your final bundle
- **Smart Resource Management**: Automatic disposal of unused view models through reference counting
### 🎯 Clean Architecture
The MVVM pattern provides a clear separation of concerns:
```typescript
// View Model (Business Logic)
const userVM = registViewModel({
name: "",
email: "",
updateProfile(data) {
if (data.name) this.state.name = data.name;
if (data.email) this.state.email = data.email;
},
});
// View (UI)
function UserProfile() {
const [state, send] = useViewModel(userVM, ["name", "email"]);
return (
Name: {state.name}
Email: {state.email}
);
}
```
### 🔄 Seamless Async Support
Handle asynchronous operations with ease:
```typescript
const [state, send] = useViewModel(userVM, ["loading", "data"]);
// Event-based call
send("fetchData");
// Async call with return value
const result = await send("fetchData", {}, true);
// Type-safe error handling
try {
const data = await send("fetchData", {}, true);
} catch (error) {
// Handle error
}
```
### 📊 Performance Comparison
| Feature | x-view-model | Redux | MobX | Zustand |
| ------------------ | ------------ | ------ | -------- | -------- |
| Bundle Size | ~13.5KB | ~7KB | ~16KB | ~1KB |
| TypeScript Support | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Learning Curve | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| Performance | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Code Complexity | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| Async Support | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
## Installation
```bash
npm install x-view-model
# or using yarn
yarn add x-view-model
# or using pnpm
pnpm add x-view-model
```
## Quick Start
Here's a simple counter example to get you started:
```typescript
import { registViewModel, useViewModel } from "x-view-model";
// Define your view model interface
interface CounterViewModel {
count: number;
increment(): void;
decrement(): void;
}
// Create a view model
const counterVM = registViewModel(
{
count: 0,
increment() {
this.state.count += 1;
},
decrement() {
this.state.count -= 1;
},
},
{ name: "counter-view-model", deep: true }
);
// Use in your component
function Counter() {
// The second parameter ["count"] specifies which state properties to subscribe to
// This optimizes re-renders by only updating when these specific properties change
const { state, increment, decrement } = useViewModel(counterVM, ["count"]);
return (
Count: {state.count}
);
}
```
## Core Concepts
### View Models
View models encapsulate your application's business logic and state. They provide a clean separation between your UI and business logic:
```typescript
type UserState = {
name: string;
email: string;
firstName: string;
lastName: string;
profile: {
avatar: string;
};
settings: {
theme: "dark" | "light";
};
};
type UserAction = {
updateProfile(payload: { name?: string; email?: string }): void;
fetchUserData(payload: { userId: string }): Promise<{
id: string;
name: string;
email: string;
}>;
};
export type UserContext = UserState & UserAction;
const userVM = registViewModel(
{
name: "",
email: "",
firstName: "",
lastName: "",
profile: {
avatar: "",
},
settings: {
theme: "dark",
},
updateProfile(data: { name?: string; email?: string }) {
if (data.name) this.state.name = data.name;
if (data.email) this.state.email = data.email;
},
async fetchUserData(data: { userId: string }) {
// Simulate API call
return {
id: data.userId,
name: "John Doe",
email: "john@example.com",
};
},
},
{ name: "user-view-model", deep: true }
);
```
### Hooks
#### useViewModel
The basic hook for accessing view model state and methods:
```typescript
const [state, send] = useViewModel(userVM, ["name", "email"]);
// Send function usage examples:
// 1. Update profile (void return)
send("updateProfile", { name: "John Doe" }); // Event-based call
await send("updateProfile", { name: "John Doe" }, true); // Async call
// 2. Fetch data (with return value)
const userData = await send("fetchUserData", { userId: "123" }, true); // Returns user data
// userData will be: { id: "123", name: "John Doe", email: "john@example.com" }
/* The send function's behavior depends on the async parameter:
* - When async is false (default): Calls the method as an event and returns void
* - When async is true: Calls the method and returns its result
* - If the method returns a Promise, it will be unwrapped
* - If the method returns a value directly, that value will be returned
*/
```
#### useMemoizedViewModel
Optimized hook for selecting specific paths from your view model:
```typescript
const [state, send] = useMemoizedViewModel(userVM, [
"name",
"profile.avatar",
"settings.theme",
] as const);
/* useMemoizedViewModel only subscribes to and returns the specified state paths.
* In this example, the state object will only contain:
* - state.name
* - state.profile.avatar
* - state.settings.theme
* Other properties will not be included in the state object.
*/
```
#### useComputedViewModel
Create computed values from your view model state:
```typescript
const [state, send] = useComputedViewModel(
userVM,
(state) => ({
fullName: `${state.firstName} ${state.lastName}`,
}),
["firstName", "lastName"]
);
/* useComputedViewModel returns only the computed values when their dependencies change.
* In this example, when firstName or lastName changes, the state object will only contain:
* - state.fullName
* The computed value fullName will be automatically updated whenever firstName or lastName changes.
*/
```
## Advanced Usage
### Simple Form Example
Here's a simple form example demonstrating basic state management:
```typescript
type FormState = {
username: string;
email: string;
isValid: boolean;
};
type FormAction = {
updateField(payload: { field: keyof FormState; value: string }): void;
validateForm(): boolean;
};
type FormContext = FormState & FormAction;
const formVM = registViewModel({
username: "",
email: "",
isValid: false,
updateField({ field, value }) {
this.state[field] = value;
this.state.isValid = this.validateForm();
},
validateForm() {
return this.state.username.length > 0 && this.state.email.includes("@");
},
});
function FormComponent() {
const [state, send] = useViewModel(formVM, ["username", "email", "isValid"]);
return (
);
}
```
### Controller Pattern with Canvas
This example demonstrates how to use x-view-model with the controller pattern for handling complex DOM manipulations like Canvas:
```typescript
// types/canvas.ts
export interface CanvasState {
width: number;
height: number;
color: string;
lineWidth: number;
isDrawing: boolean;
points: Array<{ x: number; y: number }>;
}
// controllers/CanvasController.ts
export class CanvasController {
private ctx: CanvasRenderingContext2D | null = null;
constructor(private state: CanvasState) {}
setCanvas(canvas: HTMLCanvasElement) {
this.ctx = canvas.getContext("2d");
if (this.ctx) {
this.ctx.lineWidth = this.state.lineWidth;
this.ctx.strokeStyle = this.state.color;
this.ctx.lineCap = "round";
}
}
startDrawing(x: number, y: number) {
if (!this.ctx) return;
this.state.isDrawing = true;
this.state.points = [{ x, y }];
this.ctx.beginPath();
this.ctx.moveTo(x, y);
}
draw(x: number, y: number) {
if (!this.ctx || !this.state.isDrawing) return;
this.state.points.push({ x, y });
this.ctx.lineTo(x, y);
this.ctx.stroke();
}
stopDrawing() {
if (!this.ctx) return;
this.state.isDrawing = false;
this.ctx.closePath();
}
clearCanvas() {
if (!this.ctx) return;
this.ctx.clearRect(0, 0, this.state.width, this.state.height);
this.state.points = [];
}
setColor(color: string) {
this.state.color = color;
if (this.ctx) {
this.ctx.strokeStyle = color;
}
}
setLineWidth(width: number) {
this.state.lineWidth = width;
if (this.ctx) {
this.ctx.lineWidth = width;
}
}
}
// viewModels/canvasViewModel.ts
import { registViewModel } from "x-view-model";
import { CanvasController } from "../controllers/CanvasController";
import { CanvasState } from "../types/canvas";
const initialState: CanvasState = {
width: 800,
height: 600,
color: "#000000",
lineWidth: 2,
isDrawing: false,
points: [],
};
const controller = new CanvasController(initialState);
export const canvasViewModel = registViewModel(
initialState,
{
name: "canvas-view-model",
deep: true,
},
controller
);
// components/CanvasComponent.tsx
import React, { useRef, useEffect } from "react";
import { useViewModel } from "x-view-model";
import { canvasViewModel } from "../viewModels/canvasViewModel";
const CanvasComponent: React.FC = () => {
const canvasRef = useRef(null);
const [state, send, controller] = useViewModel(canvasViewModel, [
"color",
"lineWidth",
"width",
"height",
]);
useEffect(() => {
if (canvasRef.current) {
controller.setCanvas(canvasRef.current);
}
}, [controller]);
const handleMouseDown = (e: React.MouseEvent) => {
const rect = canvasRef.current?.getBoundingClientRect();
if (!rect) return;
const x = e.clientX - rect.left;
const y = e.clientY - rect.top;
controller.startDrawing(x, y);
};
return (