https://github.com/ngdream/pulsy
Don't let state management stress you out. Let Pulsy take the pulse of your React app and keep things running smoothly.
https://github.com/ngdream/pulsy
pulsy reactjs redux state-management store store-management-system zustand
Last synced: 4 months ago
JSON representation
Don't let state management stress you out. Let Pulsy take the pulse of your React app and keep things running smoothly.
- Host: GitHub
- URL: https://github.com/ngdream/pulsy
- Owner: ngdream
- License: mit
- Created: 2024-08-24T22:25:55.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-01-16T20:19:36.000Z (5 months ago)
- Last Synced: 2025-02-02T05:31:29.157Z (4 months ago)
- Topics: pulsy, reactjs, redux, state-management, store, store-management-system, zustand
- Language: TypeScript
- Homepage:
- Size: 104 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
README
Here’s a comprehensive `README.md` for the Pulsy library with examples and explanations:
```markdown
# Pulsy
Pulsy is a modern state management library designed for simplicity and flexibility. It supports React hooks, middleware, persistence, computed stores, and time-travel debugging. Pulsy is lightweight yet powerful, making it an excellent choice for managing state in React applications.
## Features
- **React Integration:** Use Pulsy with React hooks for seamless state updates.
- **Middleware Support:** Intercept and customize state updates.
- **State Persistence:** Automatically save and restore state from storage.
- **Time-Travel Debugging:** Undo and redo state changes with ease.
- **Computed Stores:** Derive state based on other stores.
- **DevTools Compatibility:** Monitor and debug state changes effectively.
---
## Installation
Install Pulsy via npm or yarn:
```bash
npm install pulsy
# or
yarn add pulsy
```
---
## Getting Started
### Basic Example
Create and use a store in a React component:
```tsx
import { createStore, usePulsy } from "pulsy";
// Create a store
createStore("counter", 0);
function Counter() {
const [count, setCount] = usePulsy("counter");
return (
Count: {count}
setCount((prev) => prev + 1)}>Increment
);
}
```
### Middleware Example
Add middleware to log state changes:
```tsx
createStore("exampleStore", 0, {
middleware: [
(nextValue, prevValue, name) => {
console.log(`${name} changed from ${prevValue} to ${nextValue}`);
return nextValue;
},
],
});
```
### Persistence Example
Persist state with `localStorage`:
```tsx
createStore("persistentStore", { theme: "dark" }, {
persist: {
storage: localStorage,
version: 1,
migrate: (state, version) => {
if (version < 1) {
return { ...state, migrated: true };
}
return state;
},
},
});
```
### Time-Travel Debugging
Use undo and redo in your app:
```tsx
function CounterWithUndo() {
const [count, setCount, undo, redo, history] = useTimeTravel("counter");
return (
Count: {count}
setCount((prev) => prev + 1)}>Increment
Undo
Redo
History: {JSON.stringify(history)}
);
}
```
### Computed Stores
Create a store that derives its value from others:
```tsx
createStore("price", 100);
createStore("quantity", 2);
createComputedStore("totalCost", () => {
const price = getStoreValue("price");
const quantity = getStoreValue("quantity");
return price * quantity;
}, ["price", "quantity"]);
```
---
## API Reference
### Core Functions
#### `createStore`
Creates a new store.
```ts
function createStore(
name: string,
initialValue: T,
options?: {
persist?: boolean | PersistenceOptions;
middleware?: Middleware[];
memoize?: boolean;
}
): void;
```
#### `usePulsy`
React hook to access and update a store.
```ts
function usePulsy(name: string): [
T, // Current value
(newValue: T | ((prev: T) => T)) => Promise // Setter
];
```
#### `useTimeTravel`
Manage state with undo/redo support.
```ts
function useTimeTravel(name: string): [
T, // Current value
(newValue: T | ((prev: T) => T)) => Promise, // Setter
() => void, // Undo
() => void, // Redo
T[] // History
];
```
#### `createComputedStore`
Create a derived store.
```ts
function createComputedStore(
name: string,
computeFn: () => T,
dependencies: string[]
): void;
```
#### `configurePulsy`
Configure global settings for Pulsy.
```ts
function configurePulsy(config: PulsyConfig): void;
```
---
## Advanced Features
### Adding Middleware
Middleware functions can intercept and modify state updates.
```ts
addMiddleware("exampleStore", (nextValue, prevValue) => {
if (nextValue < 0) {
return 0; // Prevent negative values
}
return nextValue;
});
```
### Namespaced Stores
Use namespaces for modular state management.
```ts
const userNamespace = createNamespacedStore("user");
const setUser = userNamespace("info");
```
### Composing Stores
Combine multiple stores into one for centralized management.
```ts
composeStores("userProfile", {
name: "userName",
age: "userAge",
});
```
---
## Clearing Persisted Stores
Remove all persisted data:
```ts
clearPersistedStores(localStorage);
```
---
## Contributing
Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/your-repo/pulsy).
---
Pulsy simplifies state management while providing advanced features to enhance your development workflow. Try it today!
```
Let me know if there’s anything else you’d like to add or modify!