Pulsy - A Lightweight State Management Library for React

Pulsy is a lightweight, flexible, and easy-to-use state management library for React that provides features such as persistence, middleware, memoization, computed and composed stores, time travel, and DevTools integration. It helps you efficiently manage global state in React applications without unnecessary complexity.

Features

• Global State Management: Manage state across components using a simple store API.
• Persistence: Automatically persist store data in localStorage or custom storage solutions.
• Middleware: Modify and handle store updates through middleware functions.
• Memoization: Avoid unnecessary renders by using memoized state values.
• Computed Stores: Derive and calculate state from existing stores.
• Composable Stores: Combine multiple stores into one store for modular state management.
• Time-Travel: Rewind and forward state changes.
• DevTools Integration: Track and debug state updates in development mode.

Installation

npm install pulsy
# or
yarn add pulsy

Basic Usage

Step 1: Configure Pulsy

Pulsy can be configured globally to enable DevTools, default memoization, persistence, and callback hooks for store creation and updates.

import { configurePulsy } from 'pulsy';

configurePulsy({
  enableDevTools: process.env.NODE_ENV === 'development',
  persist: true, // Globally enable persistence by default
  defaultMemoize: true, // Enable memoization for all stores by default
  onStoreCreate: (name, initialValue) => console.log(`Store "${name}" created! Initial value:`, initialValue),
  onStoreUpdate: (name, newValue) => console.log(`Store "${name}" updated! New value:`, newValue),
});

Step 2: Create a Store

To create a store, use the createStore function. A store holds the global state and can be used anywhere in your React application.

import { createStore } from 'pulsy';

// Create a store named 'counter' with an initial value of 0
createStore('counter', 0);

Step 3: Use the Store in a Component

Pulsy provides the usePulsy hook to access and update the store’s value in your React components. Let’s create a counter component:

import usePulsy from 'pulsy';

function CounterComponent() {
  const [count, setCount] = usePulsy('counter');

  const increment = () => setCount((prev) => prev   1);

  return (
    

      
Current Count: {count}
      Increment
    
  );
}

export default CounterComponent;

Persistence

Pulsy makes it easy to persist store values in localStorage or any other custom storage system. Simply pass the persist option when creating the store.

createStore('counter', 0, { persist: true });

The value of the counter store will now persist across page reloads.

Example: Using Custom Storage

You can also configure Pulsy to use custom storage, such as sessionStorage or any other storage engine that implements the Storage interface:

createStore('sessionCounter', 0, {
  persist: {
    storage: sessionStorage, // Use sessionStorage instead of localStorage
    serialize: (value) => JSON.stringify(value),
    deserialize: (value) => JSON.parse(value),
  },
});

This will store sessionCounter in sessionStorage.

Middleware

Middleware allows you to intercept and modify store updates before they are committed. You can add middleware when creating a store, or later using addMiddleware.

const loggingMiddleware = (nextValue, prevValue, storeName) => {
  console.log(`[${storeName}] changed from ${prevValue} to ${nextValue}`);
  return nextValue;
};

createStore('counter', 0, { middleware: [loggingMiddleware] });

In this example, the middleware logs each state change in the counter store.

Example: Asynchronous Middleware

Pulsy supports asynchronous middleware for handling asynchronous tasks like API calls:

const asyncMiddleware = async (nextValue, prevValue, storeName) => {
  console.log(`Fetching data before updating ${storeName}...`);
  const data = await fetch('https://api.example.com/data').then((res) => res.json());
  return nextValue   data.amount;
};

createStore('counter', 0, { middleware: [asyncMiddleware] });

In this example, the middleware fetches some data from an API before updating the store.

Time-Travel State Management

Pulsy allows you to manage state history using the useTimeTravel hook, giving you the ability to undo and redo state changes.

import { useTimeTravel } from 'pulsy';

function TimeTravelCounter() {
  const [count, setCount, undo, redo] = useTimeTravel('counter');

  return (
    

      
Count: {count}
       setCount(count   1)}>Increment
      Undo
      Redo
    
  );
}

Example: Display State History

You can access the full history of state changes using the historyRef provided by useTimeTravel:

function HistoryCounter() {
  const [count, setCount, undo, redo, history] = useTimeTravel('counter');

  return (
    

      
Count: {count}
       setCount(count   1)}>Increment
      Undo
      Redo
      
History: {history.join(', ')}
    
  );
}

Computed Stores

Computed stores derive their state from other stores. Pulsy allows you to create stores whose values are based on one or more other stores.

import { createComputedStore } from 'pulsy';

createComputedStore('doubleCounter', () => {
  const counter = getStoreValue('counter');
  return counter * 2;
}, ['counter']);

Here, doubleCounter is automatically updated whenever the counter store changes.

Example: Display Computed Store in a Component

You can now access the computed store just like a regular store:

function DoubleCounterComponent() {
  const [doubleCount] = usePulsy('doubleCounter');

  return (
    

      
Double Counter: {doubleCount}
    
  );
}

Composing Stores

Pulsy supports composing multiple stores into a single store. This is especially useful for managing complex state by grouping related pieces of state together.

import { composeStores } from 'pulsy';

const [getComposedStore, setComposedStore] = composeStores('userProfile', {
  username: 'userNameStore',
  age: 'ageStore',
});

const UserProfileComponent = () => {
  const userProfile = getComposedStore();

  return (
    

      
Username: {userProfile.username}
      
Age: {userProfile.age}
    
  );
};

Example: Updating Composed Stores

You can also update specific parts of a composed store using the setComposedStore function:

setComposedStore({
  username: 'newUsername',
});

Namespaced Stores

Pulsy allows you to create namespaced stores to keep related stores organized and avoid naming collisions in large applications.

import { createNamespacedStore } from 'pulsy';

// Create a namespaced store for user-related data
const useUserStore = createNamespacedStore('user');

function UserComponent() {
  const [username, setUsername] = useUserStore('username');

  return (
    

      
Username: {username}
       setUsername('newUsername')}>Update Username
    
  );
}

Here, all user-related stores (e.g., user:username, user:age) are grouped under the user namespace.

DevTools Integration

Pulsy integrates with browser DevTools to help track and debug store updates. When DevTools are enabled, you’ll see logs about store updates, state changes, and performance measurements in your console.

configurePulsy({
  enableDevTools: true, // Logs detailed store activity to the console
});

Pulsy logs helpful information such as when a store is created or updated, middleware execution, and time-travel actions in development mode.

Full Example: Managing User Profile with Persistence and Middleware

Let’s combine multiple Pulsy features into a single example.

import { createStore, usePulsy, configurePulsy } from 'pulsy';

// Global configuration
configurePulsy({
  enableDevTools: true,
  persist: true,
});

// Middleware to log store updates
const loggingMiddleware = (nextValue, prevValue, storeName) => {
  console.log(`Store ${storeName}

 updated from ${prevValue} to ${nextValue}`);
  return nextValue;
};

// Create a store for user profile
createStore('userProfile', {
  username: 'guest',
  age: 25,
}, { middleware: [loggingMiddleware], persist: true });

// Component to manage user profile
function UserProfileComponent() {
  const [userProfile, setUserProfile] = usePulsy('userProfile');

  const updateUsername = () => {
    setUserProfile((prevProfile) => ({
      ...prevProfile,
      username: 'newUsername',
    }));
  };

  return (
    

      
Username: {userProfile.username}
      
Age: {userProfile.age}
      Change Username
    
  );
}

export default UserProfileComponent;

In this example, the userProfile store is persisted, logged by middleware, and accessible via the usePulsy hook. The UserProfileComponent displays and updates the store in a simple UI.

Conclusion

Pulsy is a powerful and flexible state management library for React that provides out-of-the-box support for persistence, middleware, computed stores, time-travel, and DevTools. Its simple API and wide range of features make it suitable for both small and large-scale applications.