Documentation

Zenty Documentation

The powerful Zustand-based library that simplifies CRUD operations with elegant state management

Installation

Get started with Zenty in seconds

npm

npm install zenty zustand

yarn

yarn add zenty zustand

pnpm

pnpm add zenty zustand

Quick Start

Get up and running with Zenty in under 2 minutes

Managing Collections with createEntitiesStore

ProductList.tsx

import { createEntitiesStore } from 'zenty';

interface Product {
  id: string;
  name: string;
  price: number;
  category: string;
}

// Create a store for managing products
const useProductStore = createEntitiesStore<Product>();

// Use in your React component
function ProductList() {
  const { 
    entities,
    loading,
    error,
    add,
    update,
    delete: deleteProduct 
  } = useProductStore();

  const handleAddProduct = () => {
    add({
      id: crypto.randomUUID(),
      name: 'New Product',
      price: 29.99,
      category: 'Electronics'
    });
  };

  return (
    <div>
      {loading && <p>Loading...</p>}
      {error && <p>Error: {error}</p>}
      
      <button onClick={handleAddProduct}>Add Product</button>
      
      {entities.map(product => (
        <div key={product.id}>
          <h3>{product.name}</h3>
          <p>Price: ${product.price}</p>
          <button onClick={() => deleteProduct(product.id)}>
            Delete
          </button>
        </div>
      ))}
    </div>
  );
}

Managing Single Entities with createEntityStore

UserProfile.tsx

import { createEntityStore } from 'zenty';

interface User {
  id: string;
  name: string;
  email: string;
  preferences: {
    theme: 'light' | 'dark';
    notifications: boolean;
  };
}

// Create a store for managing a single user
const useUserStore = createEntityStore<User>({
  deepMerge: true // Enable deep merging for nested objects
});

function UserProfile() {
  const { entity: user, loading, set, update } = useUserStore();

  const updateTheme = (theme: 'light' | 'dark') => {
    update({
      preferences: {
        theme
      }
    });
  };

  return (
    <div>
      {user && (
        <div>
          <h2>{user.name}</h2>
          <p>{user.email}</p>
          <button onClick={() => updateTheme('dark')}>
            Switch to Dark Mode
          </button>
        </div>
      )}
    </div>
  );
}

That's it! You now have a fully functional store with CRUD operations, loading states, error handling, and TypeScript support.

API Reference

Complete reference for all Zenty functions and methods

createEntitiesStore<T>()

Collections

Creates a Zustand store for managing collections of entities with built-in CRUD operations.

Signature

// For entities with 'id' field
function createEntitiesStore<T extends { id: string | number }>(
  options?: EntitiesStoreOptions<T, 'id'>
): UseBoundStore<StoreApi<EntitiesState<T, 'id'> & EntitiesActions<T, 'id'>>>;

// For entities with custom ID field
function createEntitiesStore<T, K extends keyof T>(
  options: EntitiesStoreOptions<T, K>
): UseBoundStore<StoreApi<EntitiesState<T, K> & EntitiesActions<T, K>>>;

Options

interface EntitiesStoreOptions<T, K extends keyof T> {
  idKey: K;                    // Which field is the unique identifier
  initialState?: T[];          // Initial list of entities (defaults to [])
  
  // Optional custom implementations for each action
  add?: (item: T, state: EntitiesState<T, K>) => T[];
  addMany?: (items: T[], state: EntitiesState<T, K>) => T[];
  update?: (uid: T[K], patch: Partial<T>, state: EntitiesState<T, K>) => T[];
  updateMany?: (patches: (Pick<T, K> & Partial<T>)[], state: EntitiesState<T, K>) => T[];
  delete?: (uid: T[K], state: EntitiesState<T, K>) => T[];
  deleteMany?: (uids: T[K][], state: EntitiesState<T, K>) => T[];
}

State Properties

interface EntitiesState<T, K extends keyof T> {
  entities: T[];           // Array of entities
  loaded: boolean;         // Whether data has been loaded
  loading: boolean;        // Whether an operation is in progress
  error: string | null;    // Error message if any
}

Actions

interface EntitiesActions<T, K extends keyof T> {
  // CRUD Operations
  add: (item: T) => void;
  addMany: (items: T[]) => void;
  update: (uid: T[K], patch: Partial<T>) => void;
  updateMany: (patches: (Pick<T, K> & Partial<T>)[]) => void;
  delete: (uid: T[K]) => void;
  deleteMany: (uids: T[K][]) => void;
  
  // Utility Functions
  clear: () => void;
  find: (uid: T[K]) => T | undefined;
  has: (uid: T[K]) => boolean;
  replaceAll: (items: T[]) => void;
  
  // State Helpers
  setError: (error: string | null) => void;
  setLoading: (loading: boolean) => void;
}

createEntityStore<T>()

Single Entity

Creates a Zustand store for managing a single entity with set, update, and clear operations.

Signature

function createEntityStore<T>(
  options?: EntityStoreOptions<T>
): UseBoundStore<StoreApi<EntityState<T> & EntityActions<T>>>;

Options & State

interface EntityStoreOptions<T> {
  initialState?: T | null;  // Initial entity state
  deepMerge?: boolean;      // Whether updates should deep merge
}

interface EntityState<T> {
  entity: T | null;         // The entity or null
  loaded: boolean;          // Whether entity has been loaded
  loading: boolean;         // Whether an operation is in progress
  error: string | null;     // Error message if any
}

Actions

interface EntityActions<T> {
  set: (entity: T) => void;                    // Set the entire entity
  update: (updated: Partial<T>) => void;       // Update parts of the entity
  clear: () => void;                           // Clear the entity
  setError: (error: string | null) => void;    // Set error state
  setLoading: (loading: boolean) => void;      // Set loading state
}

Advanced Examples

Real-world usage patterns and advanced features

Custom ID Field

custom-id-field.ts

interface User {
  userId: string;
  name: string;
  email: string;
}

const useUserStore = createEntitiesStore<User, 'userId'>({
  idKey: 'userId',
  initialState: [
    { userId: '1', name: 'John', email: 'john@example.com' }
  ]
});

Custom CRUD Operations

custom-crud.ts

const useProductStore = createEntitiesStore<Product>({
  // Custom add logic with validation
  add: (item, state) => {
    if (state.entities.some(p => p.name === item.name)) {
      throw new Error('Product name must be unique');
    }
    return [...state.entities, { ...item, createdAt: new Date() }];
  },
  
  // Custom delete with soft delete
  delete: (id, state) => {
    return state.entities.map(p => 
      p.id === id ? { ...p, deleted: true } : p
    );
  }
});

Deep Merging

deep-merge.ts

interface Settings {
  ui: {
    theme: string;
    language: string;
  };
  notifications: {
    email: boolean;
    push: boolean;
  };
}

const useSettingsStore = createEntityStore<Settings>({
  deepMerge: true,
  initialState: {
    ui: { theme: 'light', language: 'en' },
    notifications: { email: true, push: false }
  }
});

// This will only update the theme, keeping language intact
const { update } = useSettingsStore();
update({ ui: { theme: 'dark' } });

Async Operations

async-operations.ts

const useProductStore = createEntitiesStore<Product>();

async function fetchProducts() {
  const { setLoading, setError, replaceAll } = useProductStore.getState();
  
  try {
    setLoading(true);
    const response = await fetch('/api/products');
    const products = await response.json();
    replaceAll(products);
  } catch (error) {
    setError(error.message);
  } finally {
    setLoading(false);
  }
}

async function createProduct(product: Omit<Product, 'id'>) {
  const { setLoading, setError, add } = useProductStore.getState();
  
  try {
    setLoading(true);
    const response = await fetch('/api/products', {
      method: 'POST',
      body: JSON.stringify(product)
    });
    const newProduct = await response.json();
    add(newProduct);
  } catch (error) {
    setError(error.message);
  } finally {
    setLoading(false);
  }
}

Real-World Example: Complete Todo App

See how easy it is to build a complete todo application with Zenty - just a few lines of code!

This example shows a complete todo app with categories, filtering, and persistence - all powered by Zenty's simple API.

Define Your Types

types/todo.ts

// types/todo.ts
interface Todo {
  id: number;
  title: string;
  completed: boolean;
  category: 'work' | 'personal' | 'shopping';
  priority: 'low' | 'medium' | 'high';
  dueDate?: Date;
  createdAt: Date;
}

interface TodoFilters {
  category: string;
  showCompleted: boolean;
  priority: string;
}

Create Your Stores (2 lines!)

stores/todo.ts

// stores/todo.ts
import { createEntitiesStore, createEntityStore } from 'zenty';

// All todos with full CRUD operations
export const useTodoStore = createEntitiesStore<Todo>();

// Filter settings
export const useFilterStore = createEntityStore<TodoFilters>({
  initialState: {
    category: 'all',
    showCompleted: true,
    priority: 'all'
  }
});

Build Your Todo App Component

components/TodoApp.tsx

// components/TodoApp.tsx
import { useTodoStore, useFilterStore } from '@/stores/todo';

export function TodoApp() {
  const { 
    entities: todos,
    add,
    update,
    delete: deleteTodo,
    loading,
    error 
  } = useTodoStore();
  
  const { 
    entity: filters,
    update: updateFilters 
  } = useFilterStore();

  // Add new todo
  const handleAddTodo = (title: string, category: Todo['category']) => {
    add({
      id: Date.now(),
      title,
      completed: false,
      category,
      priority: 'medium',
      createdAt: new Date()
    });
  };

  // Toggle completion
  const handleToggleComplete = (id: number) => {
    const todo = todos.find(t => t.id === id);
    if (todo) {
      update(id, { completed: !todo.completed });
    }
  };

  // Filter todos based on current filters
  const filteredTodos = todos.filter(todo => {
    if (filters.category !== 'all' && todo.category !== filters.category) return false;
    if (!filters.showCompleted && todo.completed) return false;
    if (filters.priority !== 'all' && todo.priority !== filters.priority) return false;
    return true;
  });

  // Statistics
  const stats = {
    total: todos.length,
    completed: todos.filter(t => t.completed).length,
    pending: todos.filter(t => !t.completed).length,
    highPriority: todos.filter(t => t.priority === 'high' && !t.completed).length
  };

  return (
    <div className="max-w-4xl mx-auto p-6">
      <header className="mb-8">
        <h1 className="text-3xl font-bold mb-2">My Todo App</h1>
        <div className="flex gap-4 text-sm text-muted-foreground">
          <span>Total: {stats.total}</span>
          <span>Completed: {stats.completed}</span>
          <span>Pending: {stats.pending}</span>
          <span className="text-red-500">High Priority: {stats.highPriority}</span>
        </div>
      </header>

      {/* Add Todo Form */}
      <TodoForm onAdd={handleAddTodo} />

      {/* Filters */}
      <TodoFilters 
        filters={filters}
        onUpdateFilters={updateFilters}
      />

      {/* Todo List */}
      {loading && <div>Loading todos...</div>}
      {error && <div className="text-red-500">Error: {error}</div>}
      
      <div className="space-y-2">
        {filteredTodos.map(todo => (
          <div key={todo.id} className="flex items-center gap-3 p-3 border rounded">
            <input
              type="checkbox"
              checked={todo.completed}
              onChange={() => handleToggleComplete(todo.id)}
            />
            <span className={todo.completed ? 'line-through' : ''}>
              {todo.title}
            </span>
            <button 
              onClick={() => deleteTodo(todo.id)}
              className="ml-auto text-red-500"
            >
              Delete
            </button>
          </div>
        ))}
      </div>

      {filteredTodos.length === 0 && (
        <div className="text-center py-12 text-muted-foreground">
          No todos found. Add some tasks to get started!
        </div>
      )}
    </div>
  );
}

What You Get With Zenty

• Complete CRUD operations in 2 lines of code
• Automatic state management (loading, error, loaded)
• Built-in filtering and search capabilities
• Type-safe operations with full TypeScript support
• Optimistic updates and error handling
• Zero boilerplate - just focus on your UI

Advanced Features Available

• Bulk operations (addMany, updateMany, deleteMany)
• Advanced search with find() and has() methods
• State persistence with localStorage integration
• Real-time updates and synchronization
• Custom validation and error handling
• Performance optimizations built-in

Result: A complete, production-ready todo application with just ~100 lines of code instead of 500+ lines with traditional state management!

Best Practices

Recommended patterns and practices for using Zenty effectively

1Entity Design

Design your entities with clear, consistent ID fields and optional properties.

// ✅ Good: Clear ID field, optional properties
interface Product {
  id: number          // Required, unique identifier
  name: string        // Required fields
  price?: number      // Optional fields with ?
  category?: string
  createdAt?: Date
}

// ❌ Avoid: Unclear ID field, all required
interface Product {
  productId: string   // Unclear naming
  name: string
  price: number       // Should be optional
  category: string    // Should be optional
}

2Error Handling

Always handle loading and error states in your components.

function ProductList() {
  const { entities, loading, error, setError } = useProductStore()

  // ✅ Handle all states
  if (loading) return <LoadingSpinner />
  if (error) return <ErrorMessage error={error} onDismiss={() => setError(null)} />
  if (entities.length === 0) return <EmptyState />

  return (
    <div>
      {entities.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  )
}

3Async Operations

Use the built-in loading states for async operations.

async function fetchAndAddProducts() {
  const { addMany, setLoading, setError } = useProductStore()
  
  try {
    setLoading(true)
    setError(null)
    const response = await fetch('/api/products')
    const products = await response.json()
    addMany(products)
  } catch (error) {
    setError('Failed to fetch products')
  } finally {
    setLoading(false)
  }
}

4Store Organization

Organize your stores in separate files for better maintainability.

// stores/products.ts
export const useProductStore = createEntitiesStore<Product>()

// stores/users.ts  
export const useUserStore = createEntitiesStore<User>()

// stores/settings.ts
export const useSettingsStore = createEntityStore<Settings>({
  initialState: { theme: 'light', notifications: true }
})

// stores/index.ts
export * from './products'
export * from './users'
export * from './settings'

Migration Guide

How to migrate from traditional Zustand to Zenty

Migration is straightforward and can be done incrementally. You can use Zenty alongside existing Zustand stores.

Step-by-Step Migration:

Install Zenty

npm install zenty

Replace your existing store

❌ Before (50+ lines)

const useProductStore = create((set) => ({
  products: [],
  loading: false,
  error: null,
  addProduct: (product) => set((state) => ({
    products: [...state.products, product]
  })),
  updateProduct: (id, updates) => set((state) => ({
    products: state.products.map(p => 
      p.id === id ? { ...p, ...updates } : p
    )
  })),
  deleteProduct: (id) => set((state) => ({
    products: state.products.filter(p => p.id !== id)
  })),
  // ... 40+ more lines
}))

✅ After (1 line)

const useProductStore = createEntitiesStore<Product>()

Update your component usage

// Before
const { products, addProduct, loading } = useProductStore()

// After (same destructuring, different method names)
const { entities: products, add: addProduct, loading } = useProductStore()

Test and deploy

Your app should work exactly the same, but with less code and more features!

Support & Resources

Get help and stay updated with Zenty

Community & Support

GitHub Repository Report Issues

Package Information

npm Package Discussions