pulsy - react 的轻量级状态管理库

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

特征

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

安装

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<number>('counter');

  const increment = () => setcount((prev) => prev + 1);

  return (
    <div>
      <p>current count: {count}</p>
      <button onclick={increment}>increment</button>
    </div>
  );
}

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<number>('counter');

  return (
    <div>
      <p>count: {count}</p>
      <button onclick={() => setcount(count + 1)}>increment</button>
      <button onclick={undo}>undo</button>
      <button onclick={redo}>redo</button>
    </div>
  );
}

示例：显示状态历史记录

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

function historycounter() {
  const [count, setcount, undo, redo, history] = usetimetravel<number>('counter');

  return (
    <div>
      <p>count: {count}</p>
      <button onclick={() => setcount(count + 1)}>increment</button>
      <button onclick={undo}>undo</button>
      <button onclick={redo}>redo</button>
      <p>history: {history.join(', ')}</p>
    </div>
  );
}

---

计算存储

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

import { createcomputedstore } from 'pulsy';

createcomputedstore('doublecounter', () => {
  const counter = getstorevalue<number>('counter');
  return counter * 2;
}, ['counter']);

这里，每当计数器存储发生变化时，doublecounter 就会自动更新。

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

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

function doublecountercomponent() {
  const [doublecount] = usepulsy<number>('doublecounter');

  return (
    <div>
      <p>double counter: {doublecount}</p>
    </div>
  );
}

---

组合商店

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

import { composestores } from 'pulsy';

const [getcomposedstore, setcomposedstore] = composestores('userprofile', {
  username: 'usernamestore',
  age: 'agestore',
});

const userprofilecomponent = () => {
  const userprofile = getcomposedstore();

  return (
    <div>
      <p>username: {userprofile.username}</p>
      <p>age: {userprofile.age}</p>
    </div>
  );
};

示例：更新组合存储

您还可以使用 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<string>('username');

  return (
    <div>
      <p>username: {username}</p>
      <button onclick={() => setusername('newusername')}>update username</button>
    </div>
  );
}

这里，所有与用户相关的存储（例如，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 (
    <div>
      <p>Username: {userProfile.username}</p>
      <p>Age: {userProfile.age}</p>
      <button onClick={updateUsername}>Change Username</button>
    </div>
  );
}

export default UserProfileComponent;

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

---

结论

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