Beru

Beru is a small, simple, and type-safe state management solution for React and React Native. It offers efficient data persistence and seamless integration with various storage mechanisms. Designed to be lightweight and intuitive, Beru helps developers manage application state with ease and confidence.

Features

• Simple API: Straightforward and intuitive for quick setup and easy state management
• Type-safe: Leverages TypeScript to ensure reliable and error-resistant code
• Minimal Bundle Size: Optimized for performance with a tiny footprint
• No Dependencies: Zero external dependencies for maximum compatibility
• Selector Support: Efficient component re-renders by subscribing only to needed state
• Custom Equality: Control re-renders with custom equality comparisons for complex state
• Action Creators: Organize state updates with custom action functions
• Persistence: Optional state persistence with flexible storage options
• React & React Native: Works seamlessly in all React environments

Installation

Install Beru using npm:

npm install beru

Or using yarn:

yarn add beru

Usage

Store Example

import React from 'react';
import { create } from 'beru';

// Create a new instance of the store with initial state and actions
export const useCount = create({ count: 0 }).withActions(({ set, get }) => ({
  // Using get() to access current state
  increment: () => set({ count: get().count + 1 }),
  decrement: () => set({ count: get().count - 1 }),
  
  // Alternatively, using a function that receives the current state
  incrementAlt: () => set((state) => ({ count: state.count + 1 })),
  decrementAlt: () => set((state) => ({ count: state.count - 1 })),
}));

// Component using the entire store
const CounterComponent = () => {
  const { count, decrement, increment } = useCount();

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
      <button onClick={decrement}>Decrement</button>
    </div>
  );
};

// Component using a selector for state (prevents unnecessary re-renders)
const CountDisplayComponent = () => {
  const count = useCount((state) => state.count);
  return <p>Count: {count}</p>;
};

// Component using a selector for actions
const CountActionsComponent = () => {
  const { increment, decrement } = useCount((state) => ({
    increment: state.increment,
    decrement: state.decrement,
  }));

  return (
    <div>
      <button onClick={increment}>Increment</button>
      <button onClick={decrement}>Decrement</button>
    </div>
  );
};

Simple State Example

export const useDarkTheme = create(true);

const ThemeComponent = () => {
  const [isDark, setDark] = useDarkTheme();

  return (
    <div>
      <p>Current Theme: {isDark ? 'Dark' : 'Light'}</p>
      <button onClick={() => setDark(true)}>DARK</button>
      <button onClick={() => setDark(false)}>LIGHT</button>
      {/* Toggle using previous state */}
      <button onClick={() => setDark(prev => !prev)}>TOGGLE</button>
    </div>
  );
}

Persistence Example

import { create } from 'beru';
import { persist, setupHydrator } from 'beru/persistence';

// Create a store with persistence
const useSettings = persist(
  create({ 
    theme: 'light', 
    fontSize: 16, 
    notifications: true 
  }),
  {
    name: 'app-settings', // Storage key
    version: 1, // For migration purposes
    storage: localStorage, // Or any compatible storage
  }
);

// Create another persistent store
const useUserPrefs = persist(
  create({ language: 'en', currency: 'USD' }).withActions(({ set }) => ({
    setLanguage: (language) => set({ language }),
    setCurrency: (currency) => set({ currency }),
  })),
  {
    name: 'user-preferences',
    version: 1,
  }
);

// Setup hydration for both stores
const hydrateStores = setupHydrator([useSettings, useUserPrefs]);

// Use in your app's entry point
const App = () => {
  React.useEffect(() => {
    hydrateStores();
  }, []);
  
  // Your app components...
};

Combining Multiple Stores

import React from 'react';
import { create } from 'beru';

// User store
const useUser = create({ name: '', email: '' }).withActions(({ set }) => ({
  updateUser: (user) => set(user),
  clearUser: () => set({ name: '', email: '' }),
  // Using function update pattern
  updateName: (name) => set((state) => ({ ...state, name })),
}));

// Authentication store
const useAuth = create({ isLoggedIn: false, token: null }).withActions(({ set }) => ({
  login: (token) => set({ isLoggedIn: true, token }),
  logout: () => set({ isLoggedIn: false, token: null }),
}));

// Profile component using multiple stores
const ProfileComponent = () => {
  const { name, email } = useUser();
  const { isLoggedIn, logout } = useAuth();

  if (!isLoggedIn) {
    return <p>Please log in to view your profile</p>;
  }

  return (
    <div>
      <h2>User Profile</h2>
      <p>Name: {name}</p>
      <p>Email: {email}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
};

Async Actions

const useTodos = create({ todos: [], loading: false, error: null })
  .withActions(({ set, get }) => ({
    fetchTodos: async () => {
      set({ loading: true, error: null });
      try {
        const response = await fetch('https://api.example.com/todos');
        const todos = await response.json();
        set({ todos, loading: false });
      } catch (error) {
        set({ error: error.message, loading: false });
      }
    },
    addTodo: async (title) => {
      set({ loading: true, error: null });
      try {
        const response = await fetch('https://api.example.com/todos', {
          method: 'POST',
          body: JSON.stringify({ title, completed: false }),
          headers: { 'Content-Type': 'application/json' },
        });
        const newTodo = await response.json();
        
        // Using function update pattern with previous state
        set((state) => ({ 
          todos: [...state.todos, newTodo], 
          loading: false 
        }));
      } catch (error) {
        set({ error: error.message, loading: false });
      }
    },
    toggleTodo: async (id) => {
      // Function update pattern is ideal for updates based on current state
      set((state) => {
        const todo = state.todos.find(t => t.id === id);
        if (!todo) return state;
        
        return {
          ...state,
          todos: state.todos.map(t => 
            t.id === id ? { ...t, completed: !t.completed } : t
          )
        };
      });
    }
  }));

Advanced Persistence Configuration

Beru offers robust persistence capabilities through the persistence module:

import { persist } from 'beru/persistence';

const persistentStore = persist(yourStore, {
  // Required
  name: 'storage-key', // Unique identifier for storage
  
  // Optional with defaults
  debounceTime: 100, // Debounce time for writes (ms)
  version: 1, // State version for migrations
  storage: localStorage, // Storage provider (defaults to localStorage)
  
  // Optional transformation functions
  serialize: JSON.stringify, // Custom serialization
  deserialize: JSON.parse, // Custom deserialization
  
  // Optional state handling
  partial: (state) => state, // Select which parts to persist
  merge: (initialState, persistedState) => ({ ...initialState, ...persistedState }),
  migrate: (storedState, storedVersion) => {
    // Migration logic based on version
    if (storedVersion === 1) {
      return storedState; // Return current state
    }
    return null; // Return null to use initial state instead
  },
  
  // Other options
  skipHydrate: false, // Skip initial hydration
  onError: (type, error) => console.error(`${type} error:`, error),
});

API Reference

create(initialState)

Creates a new store with the provided initial state.

const useStore = create(initialState);

withActions(actionsCreator)

Adds actions to the store for updating state.

const useStore = create(initialState).withActions(({ set, get }) => ({
  // Set object directly
  action1: (payload) => set({ ...get(), ...payload }),
  
  // Set using function that receives previous state
  action2: () => set(prevState => ({ ...prevState, value: newValue })),
  
  // Set partial state (automatically merged)
  action3: (value) => set({ value })
}));

State Updates

Beru provides two ways to update state:

1. Direct object updates:

set({ count: 10 });

2. Function updates (when new state depends on previous state):

set(state => ({ count: state.count + 1 }));

Selectors

Use selectors to subscribe to specific parts of the state, preventing unnecessary re-renders.

// Subscribe to the entire state
const state = useStore();

// Subscribe to a specific value
const value = useStore(state => state.value);

// Subscribe to multiple values
const { value1, value2 } = useStore(state => ({
  value1: state.value1,
  value2: state.value2
}));

Custom Equality Comparison

For advanced use cases, you can provide a custom equality function as the second parameter to control when components re-render:

// Basic usage with custom equality
const count = useCount(
  (state) => state.count,
  (a, b) => a === b // Custom equality function
);

// Example: Deep comparison for complex objects
const user = useStore(
  (state) => state.user,
  (prevUser, nextUser) => {
    return prevUser.id === nextUser.id && 
           prevUser.name === nextUser.name &&
           prevUser.email === nextUser.email;
  }
);

// Example: Shallow comparison for arrays/objects
import { shallowEqual } from 'beru/utils'; // If available, or use custom implementation

const todos = useTodos(
  (state) => state.todos,
  shallowEqual
);

// Example: Custom comparison for specific use cases
const filteredItems = useStore(
  (state) => state.items.filter(item => item.isActive),
  (prevItems, nextItems) => {
    // Only re-render if the filtered results actually changed
    if (prevItems.length !== nextItems.length) return false;
    return prevItems.every((item, index) => item.id === nextItems[index].id);
  }
);

Selector Usage Patterns

// Pattern 1: Simple value selection
const count = useCount(state => state.count);

// Pattern 2: Multiple values with default equality
const { loading, error } = useStore(state => ({
  loading: state.loading,
  error: state.error
}));

// Pattern 3: Computed values with custom equality
const expensiveComputation = useStore(
  state => {
    // Some expensive computation based on state
    return state.items
      .filter(item => item.isVisible)
      .sort((a, b) => a.priority - b.priority)
      .slice(0, 10);
  },
  (prev, next) => {
    // Custom equality to prevent unnecessary recomputations
    return prev.length === next.length && 
           prev.every((item, i) => item.id === next[i].id);
  }
);

// Pattern 4: Actions with custom equality (rarely needed)
const actions = useStore(
  state => ({ increment: state.increment, decrement: state.decrement }),
  () => true // Actions typically don't change, so always equal
);

Persistence API

persist(store, config)

Enhances a store with persistence capabilities.

import { persist } from 'beru/persistence';

const persistentStore = persist(store, {
  name: 'unique-storage-key',
  // ...other options
});

setupHydrator(persistentStores)

Creates a function that hydrates multiple persistent stores at once.

import { setupHydrator } from 'beru/persistence';

const hydrateStores = setupHydrator([store1, store2, store3]);

// Call in your app's entry point
hydrateStores();

Persistent Store Methods

// Manually hydrate state from storage
await persistentStore.hydrate();

// Clear persisted state
await persistentStore.clear();

// Unsubscribe from persistence
persistentStore.dispose();

Contributing

We welcome contributions from the community! If you encounter any issues or have suggestions for improvement, please feel free to open an issue or submit a pull request on the Beru GitHub repository.

Support

If you find Beru helpful, consider supporting its development:

Your support helps maintain and improve Beru for the entire community.

License

This project is licensed under the MIT License.

Made with ❤️ by Alok Shete