Pulsy - React 的轻量级状态管理库

Pulsy 是一个轻量级、灵活且易于使用的 React 状态管理库，提供持久性、中间件、记忆、计算和组合存储、时间旅行和 DevTools 集成等功能。它可以帮助您有效地管理 React 应用程序中的全局状态，而无需不必要的复杂性。

特征

• 全局状态管理：使用简单的存储 API 管理跨组件的状态。
• 持久化：自动将存储数据持久化到localStorage或自定义存储解决方案中。
• 中间件：通过中间件功能修改和处理商店更新。
• 记忆化：通过使用记忆状态值避免不必要的渲染。
• 计算存储：从现有存储中导出并计算状态。
• 可组合存储：将多个存储合并为一个存储以进行模块化状态管理。
• 时间旅行：快退和快进状态变化。
• DevTools Integration：在开发模式下跟踪和调试状态更新。

安装

npm install pulsy
# or
yarn add pulsy

基本用法

第 1 步：配置 Pulsy

Pulsy 可以进行全局配置，以启用 DevTools、默认记忆、持久性和用于商店创建和更新的回调挂钩。

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),
});

第 2 步：创建商店

要创建商店，请使用 createStore 函数。存储保存全局状态，可以在 React 应用程序中的任何位置使用。

import { createStore } from 'pulsy';

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

第 3 步：在组件中使用 Store

Pulsy 提供了 usePulsy 钩子来访问和更新 React 组件中的 store 的值。让我们创建一个计数器组件：

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;

坚持

Pulsy 可以轻松地将存储值保存在 localStorage 或任何其他自定义存储系统中。只需在创建商店时传递 persist 选项即可。

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

计数器存储的值现在将在页面重新加载时保持不变。

示例：使用自定义存储

您还可以配置 Pulsy 使用自定义存储，例如 sessionStorage 或任何其他实现 Storage 接口的存储引擎：

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

这会将 sessionCounter 存储在 sessionStorage 中。

中间件

中间件允许您在提交存储更新之前拦截和修改它们。您可以在创建商店时添加中间件，或者稍后使用 addMiddleware.

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

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

在此示例中，中间件记录计数器存储中的每个状态更改。

示例：异步中间件

Pulsy 支持异步中间件来处理 API 调用等异步任务：

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] });

在此示例中，中间件在更新存储之前从 API 获取一些数据。

时间旅行状态管理

Pulsy 允许您使用 useTimeTravel 挂钩管理状态历史记录，使您能够撤消和重做状态更改。

import { useTimeTravel } from 'pulsy';

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

  return (
    

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

示例：显示状态历史记录

您可以使用useTimeTravel提供的historyRef访问状态更改的完整历史记录：

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

  return (
    

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

计算存储

计算存储从其他存储中获取其状态。 Pulsy 允许您创建其值基于一个或多个其他商店的商店。

import { createComputedStore } from 'pulsy';

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

这里，只要计数器存储发生变化，doubleCounter就会自动更新。

示例：显示组件中的计算存储

您现在可以像访问常规商店一样访问计算存储：

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

  return (
    

      
Double Counter: {doubleCount}
    
  );
}

组合商店

Pulsy 支持将多个商店合并为一个商店。这对于通过将相关状态片段分组在一起来管理复杂状态特别有用。

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}
    
  );
};

示例：更新组合存储

您还可以使用 setCompositedStore 函数更新组合存储的特定部分：

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

命名空间存储

Pulsy 允许您创建命名空间存储，以保持相关存储的组织性并避免大型应用程序中的命名冲突。

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
    
  );
}

这里，所有与用户相关的存储（例如，user:username、user:age）都分组在用户命名空间下。

开发工具集成

Pulsy 与浏览器 DevTools 集成，以帮助跟踪和调试商店更新。启用 DevTools 后，您将在控制台中看到有关商店更新、状态更改和性能测量的日志。

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

Pulsy 记录有用的信息，例如何时创建或更新商店、中间件执行以及开发模式下的时间旅行操作。

完整示例：使用持久性和中间件管理用户配置文件

让我们将多个 Pulsy 功能组合到一个示例中。

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;

在此示例中，userProfile 存储由中间件持久保存、记录，并可通过 usePulsy 挂钩访问。 UserProfileComponent 在简单的 UI 中显示和更新商店。

结论

Pulsy 是一个强大且灵活的 React 状态管理库，为持久性、中间件、计算存储、时间旅行和 DevTools 提供开箱即用的支持。其简单的 API 和广泛的功能使其适用于小型和大型应用程序。