https://github.com/I-am-abdulazeez/stunk
A framework-agnostic state management library that keeps your app’s state clean and simple. It uses a fine-grained state model, breaking state into independent, manageable chunks.
https://github.com/I-am-abdulazeez/stunk
angular client-state-management queflow react solid state-management svelte typescript vue zustand-alternative
Last synced: 9 days ago
JSON representation
A framework-agnostic state management library that keeps your app’s state clean and simple. It uses a fine-grained state model, breaking state into independent, manageable chunks.
- Host: GitHub
- URL: https://github.com/I-am-abdulazeez/stunk
- Owner: I-am-abdulazeez
- License: other
- Created: 2025-01-27T10:29:15.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-10-18T05:15:29.000Z (about 1 month ago)
- Last Synced: 2025-10-19T03:20:42.184Z (about 1 month ago)
- Topics: angular, client-state-management, queflow, react, solid, state-management, svelte, typescript, vue, zustand-alternative
- Language: TypeScript
- Homepage: https://stunk.vercel.app/
- Size: 389 KB
- Stars: 147
- Watchers: 1
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Roadmap: ROADMAP.md
Awesome Lists containing this project
- awesome-javascript - stunk - agnostic state management library that keeps your app’s state clean and simple. It uses a fine-grained state model, breaking state into independent, manageable chunks. (Reactive Programming / Runner)
- fucking-awesome-javascript - stunk - agnostic state management library that keeps your app’s state clean and simple. It uses a fine-grained state model, breaking state into independent, manageable chunks. (Reactive Programming / Runner)
- awesome-typescript - stunk - Lightweight, framework-agnostic state management library with atomic chunks for fine-grained reactivity, simple and applicable for any Typescript applications. (Built with TypeScript / Libraries)
README
# Stunk
Stunk is a lightweight, framework-agnostic state management library built on atomic state principles. It simplifies state management by breaking state into manageable "chunks", ensuring efficient updates and reactivity.
- **Pronunciation**: _Stunk_ (A playful blend of "state" and "chunk")
**Stunk** is like dividing your jar into many smaller containers, each holding a single piece of state. These smaller containers are called **chunks**. Each **chunk** can be updated and accessed easily, and any part of your app can subscribe to changes in a chunk so it gets updated automatically.
## Features
- 🚀 **Lightweight and Fast**: No dependencies, minimal overhead
- 🔄 **Reactive**: Automatic updates when state changes
- 📦 **Batch Updates**: Group multiple state updates together
- 🎯 **Atomic State Management**: Break down state into manageable chunks
- 🎭 **State Selection**: Select and derive specific parts of the state
- 🔄 **Async Support**: Handle async state with built-in loading and error states
- 🔌 **Middleware Support**: Extend functionality with custom middleware
- ⏱️ **Time Travel**: Undo/redo state changes
- 🔍 **Type-Safe**: Written in TypeScript with full type inference
## Installation
```bash
npm install stunk
# or
yarn add stunk
# or
pnpm install stunk
```
Read Docs:
[Stunk](https://stunk.vercel.app/)
## Creating a Chunk
```typescript
import { chunk } from "stunk";
// Create a chunk holding a number
const count = chunk(0);
// Create a chunk holding a string
const name = chunk("Stunky, chunky");
```
👉 [See full explanation in docs](https://stunk.vercel.app/chunk.html)
## Interacting with a Chunk
```typescript
// Get value
console.log(count.get()); // 0
// Set a new value
count.set(10);
// Update based on the previous value
count.set((prev) => prev + 1);
// Reset to the initial value
count.reset();
// Destroy the chunk and all its subscribers.
count.destroy();
```
👉 [See full explanation in docs](https://stunk.vercel.app/chunk.html)
## React via useChunk
The `useChunk` hook, enables components to reactively read and update state from a Chunk. The counter example below depicts
```typescript
import { chunk } from "stunk";
import { useChunk } from "stunk/react";
const count = chunk(0);
const Counter = () => {
const [value, set, reset] = useChunk(count);
return (
Count: {value}
set((prev) => prev + 1)}>Increment
reset()}>Reset
);
};
```
👉 [See full explanation in docs](https://stunk.vercel.app/useChunk.html)
## React via useDerive
Hook that lets you create a read-only derived state from a Chunk. It keeps the derived value reactive, automatically updating whenever the source Chunk changes.
```typescript
import { chunk } from "stunk";
import { useDerive } from "stunk/react";
const count = chunk(0);
const DoubledCount = () => {
const double = useDerive(count, (value) => value * 2);
return
Double: {double}
;
};
```
👉 [See full explanation in docs](https://stunk.vercel.app/useDerive.html)
## React via useComputed
Hook that derives a computed value from one or more Chunks. It automatically re-evaluates whenever any of its dependencies change, ensuring efficient and reactive updates.
```typescript
import { chunk } from "stunk";
import { useComputed } from "stunk/react";
const count = chunk(2);
const multiplier = chunk(3);
const ComputedExample = () => {
const product = useComputed([count, multiplier], (c, m) => c * m);
return
Product: {product}
;
};
```
👉 [See full explanation in docs](https://stunk.vercel.app/useComputed.html)
## React via useAsyncChunk
Hook that manages that manages asynchronous state. It offers built-in reactivity, handling loading, error, and data states, ensuring the UI stays in sync with asynchronous operations.
```typescript
import { asyncChunk } from "stunk";
import { useAsyncChunk } from "stunk/react";
const fetchUser = asyncChunk(async () => {
const res = await fetch("https://jsonplaceholder.typicode.com/users/1");
return res.json();
});
const UserProfile = () => {
const { data, loading, error, reload } = useAsyncChunk(fetchUser);
if (loading) return
Loading...
;
if (error) return Error: {error.message}
;
return (
{data.name}
{data.email}
Reload
);
};
```
👉 [See full explanation in docs](https://stunk.vercel.app/useAysncChunk.html)
## React via useChunkValue
Hook that subscribes to a Chunk and returns its current value. It is useful for read-only components that don’t need to modify the state.
```typescript
import { chunk } from "stunk";
import { useChunkValue } from "stunk/react";
const count = chunk(0);
const CounterDisplay = () => {
const value = useChunkValue(count);
return
Count: {value}
;
};
```
👉 [See full explanation in docs](https://stunk.vercel.app/read-only-values.html)
Live Examples:
👉 [Visit](https://stunk-examples.vercel.app/)
Coding Examples:
👉 [Visit](https://stunk.vercel.app/examples.html)
Further Examples:
👉 [Visit](https://github.com/I-am-abdulazeez/stunk-examples/)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
[Pull Request](https://github.com/I-am-abdulazeez/stunk/pulls)
## License
This is licence under MIT