Pulsy - مكتبة إدارة حالة خفيفة الوزن لـ React

Pulsy هي مكتبة إدارة حالة خفيفة الوزن ومرنة وسهلة الاستخدام لـ React توفر ميزات مثل المثابرة والبرامج الوسيطة والحفظ والمخازن المحسوبة والمؤلفة والسفر عبر الزمن وتكامل DevTools. يساعدك على إدارة الحالة العالمية بكفاءة في تطبيقات React دون تعقيدات غير ضرورية.

سمات

• إدارة الحالة العالمية: إدارة الحالة عبر المكونات باستخدام واجهة برمجة تطبيقات متجر بسيطة.
• الثبات: الاحتفاظ تلقائيًا ببيانات التخزين في التخزين المحلي أو حلول التخزين المخصصة.
• البرامج الوسيطة: تعديل تحديثات المتجر والتعامل معها من خلال وظائف البرامج الوسيطة.
• الحفظ: تجنب العروض غير الضرورية باستخدام قيم الحالة المحفوظة.
• المتاجر المحسوبة: اشتقاق الحالة وحسابها من المتاجر الموجودة.
• المتاجر القابلة للتركيب: اجمع متاجر متعددة في متجر واحد لإدارة الحالة المعيارية.
• السفر عبر الزمن: إرجاع تغييرات الحالة وإعادة توجيهها.
• تكامل أدوات التطوير: تتبع تحديثات الحالة وتصحيح الأخطاء في وضع التطوير.

تثبيت

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: استخدم المتجر في أحد المكونات

يوفر Pulsy خطاف usePulsy للوصول إلى قيمة المتجر وتحديثها في مكونات React الخاصة بك. لنقم بإنشاء مكون عداد:

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 أو أي نظام تخزين مخصص آخر. ما عليك سوى تمرير خيار الاستمرار عند إنشاء المتجر.

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

ستستمر الآن قيمة المتجر المضاد عبر عمليات إعادة تحميل الصفحة.

مثال: استخدام التخزين المخصص

يمكنك أيضًا تكوين Pulsy لاستخدام وحدة تخزين مخصصة، مثل sessionStorage أو أي محرك تخزين آخر يقوم بتنفيذ واجهة التخزين:

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

سيؤدي هذا إلى تخزين عداد الجلسة في مساحة تخزين الجلسة.

الوسيطة

تسمح لك البرامج الوسيطة باعتراض تحديثات المتجر وتعديلها قبل الالتزام بها. يمكنك إضافة برمجيات وسيطة عند إنشاء متجر، أو لاحقًا باستخدام 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
    
  );
}

مثال: عرض تاريخ الحالة

يمكنك الوصول إلى السجل الكامل لتغييرات الحالة باستخدام HistoryRef المقدم من useTimeTravel:

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

مثال: تحديث المخازن المركبة

يمكنك أيضًا تحديث أجزاء معينة من المتجر المؤلف باستخدام وظيفة setComposeStore:

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

هنا، يتم تجميع جميع المتاجر ذات الصلة بالمستخدم (على سبيل المثال، المستخدم: اسم المستخدم، المستخدم: العمر) ضمن مساحة اسم المستخدم.

تكامل أدوات التطوير

يتكامل Pulsy مع أدوات تطوير المتصفح للمساعدة في تتبع تحديثات المتجر وتصحيحها. عند تمكين 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 المتجر ويحدثه في واجهة مستخدم بسيطة.

خاتمة

Pulsy هي مكتبة إدارة حالة قوية ومرنة لـ React توفر دعمًا جاهزًا للاستمرارية والبرامج الوسيطة والمتاجر المحسوبة والسفر عبر الزمن وأدوات التطوير. واجهة برمجة التطبيقات البسيطة ومجموعة واسعة من الميزات تجعلها مناسبة لكل من التطبيقات الصغيرة والكبيرة الحجم.