stunk 0.8.0 → 0.9.0

package/README.md

@@ -1,92 +1,60 @@
 # Stunk
 
-A lightweight, framework-agnostic state management library using atomic state principles. Stunk breaks down state into manageable "chunks" for easy updates and subscriptions.
-
-## Pronunciation and Meaning
-
 - **Pronunciation**: _Stunk_ (A playful blend of "state" and "chunk")
-- **Meaning**: "Stunk" represents the combination of state management with chunk-based atomic units. The term captures the essence of atomic state management while using "chunk" to refer to these discrete units of state.
-
-## What is Stunk?
 
-Think of your application's state as a big jar of data. In traditional state management, you keep everything in one big jar, and every time you want to change something, you have to dig through the whole jar.
+A lightweight, reactive state management library for TypeScript/JavaScript applications. Stunk combines atomic state management with powerful features like middleware, time travel, and async state handling.
 
 **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
 
-<!-- - 🎯 Framework agnostic -->
-
-- 🔄 Reactive updates with efficient subscription system
-- 🎯 Granular state selection
-- ⏳ Built-in undo/redo/getHistory/clearHistory
-- 🔄 Batch updates for performance and nested batch updates
-- 🛠️ Extensible middleware
-- 🔍 Full TypeScript support
+- 🚀 **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 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
 ```
 
-## Quick Start
-
-```typescript
-import { chunk, select, batch } from "stunk";
-
-// Create a state chunk
-const counter = chunk(0);
-const userChunk = chunk({ name: "Olamide", age: 26 });
-
-// Select specific state - Selector
-const nameSelector = select(userChunk, (user) => user.name);
-
-// Subscribe to changes
-nameSelector.subscribe((name) => console.log("Name:", name));
-counter.subscribe((count) => console.log("Counter", counter));
-
-// Batch updates
-batch(() => {
-  userChunk.set({ name: "Olalekan", age: 27 }); // Doesn't log yet
-  counter.set(5); // Doesn't log yet
-}); // All logs happen here at once
-```
-
-## Core Concepts
-
-### Chunks
+## Basic Usage
 
-Basic unit of state with get/set/subscribe functionality:
+A **chunk** is a small container of state. It holds a value, and you can do some stuffs with it:
 
 ```typescript
-const counter = chunk(0);
-counter.subscribe((value) => console.log(value));
-counter.set(5);
-```
-
-## Unsubscribing
-
-You can **unsubscribe** from a **chunk**, which means you stop getting notifications when the **value changes**. You can do this by calling the function that's returned when you **subscribe..**
+import { chunk } from "stunk";
 
-### Usage
-
-```ts
-const count = chunk(0);
-const callback = (newValue: number) => console.log("Updated value:", newValue);
+// Create a simple counter
+const counterChunk = chunk(0);
 
-const unsubscribe = count.subscribe(callback);
+// Subscribe to changes
+counterChunk.subscribe((value) => {
+  console.log("Counter changed:", value);
+});
 
-count.set(10); // Will log: "Updated value: 10"
+// Update the value
+counterChunk.set(1);
 
-unsubscribe(); // Unsubscribe
+// Get current value
+const value = counterChunk.get(); // 1
 
-count.set(20); // Nothing will happen now, because you unsubscribed
+// Reset to initial value
+counterChunk.reset();
 ```
 
-### Deriving New Chunks
+## Deriving New Chunks
 
-With Stunk, you can create **derived chunks**. This means you can create a new **chunk** based on the value of another **chunk**. When the original **chunk** changes, the **derived chunk** will automatically update.
+With **Stunk**, you can create **derived chunks**. This means you can create a new **chunk** based on the value of another **chunk**.
+When the original **chunk** changes, the **derived chunk** will automatically update.
 
 ```typescript
 const count = chunk(5);
@@ -103,34 +71,51 @@ count.set(10);
 // "Double count: 20"
 ```
 
-### Batch Updates
+## Batch Updates
 
-Group multiple updates:
+Batch Update group multiple **state changes** together and notify **subscribers** only once at the end of the **batch**. This is particularly useful for **optimizing performance** when you need to **update multiple** chunks at the same time.
 
 ```typescript
+import { chunk, batch } from "stunk";
+
+const nameChunk = chunk("Olamide");
+const ageChunk = chunk(30);
+
 batch(() => {
-  chunk1.set(newValue1);
-  chunk2.set(newValue2);
-}); // Single notification
+  nameChunk.set("AbdulAzeez");
+  ageChunk.set(31);
+}); // Only one notification will be sent to subscribers
 
 // Nested batches are also supported
 batch(() => {
-  chunk1.set("Tunde");
+  firstName.set("Olanrewaju");
   batch(() => {
-    chunk1.set(26);
+    age.set(29);
   });
-});
+}); // Only one notification will be sent to subscribers
 ```
 
-### Selectors
+## State Selection
 
 Efficiently access and react to specific state parts:
 
 ```typescript
-// With selector - more specific, read-only
-const userChunk = chunk({ name: "Olamide", score: 100 });
-const scoreSelector = select(userChunk, (u) => u.score);
-// scoreSelector.set(200); // This would throw an error
+import { chunk, select } from "stunk";
+
+const userChunk = chunk({
+  name: "Olamide",
+  age: 30,
+  email: "olamide@example.com",
+});
+
+// Select specific properties -readonly
+const nameChunk = select(userChunk, (state) => state.name);
+const ageChunk = select(userChunk, (state) => state.age);
+
+nameChunk.subscribe((name) => console.log("Name changed:", name));
+// will only re-render if the selected part change.
+
+nameChunk.set("Olamide"); // ❌ this will throw an error, because it is a readonly.
 ```
 
 ## Middleware
@@ -138,46 +123,135 @@ const scoreSelector = select(userChunk, (u) => u.score);
 Middleware allows you to customize how values are set in a **chunk**. For example, you can add **logging**, **validation**, or any custom behavior when a chunk's value changes.
 
 ```typescript
-// You can also create yours and pass it []
+import { chunk } from "stunk";
+import { logger, nonNegativeValidator } from "stunk/middleware";
+
+// You can also create yours and pass it chunk as the second param
 
 // Use middleware for logging and validation
 const age = chunk(25, [logger, nonNegativeValidator]);
 
 age.set(30); // Logs: "Setting value: 30"
-age.set(-5); // Throws an error: "Value must be non-negative!"
+age.set(-5); // ❌ Throws an error: "Value must be non-negative!"
 ```
 
-### History (Undo/Redo) - Time Travel
+## Time Travel (Middleware)
 
 ```typescript
-const counter = withHistory(chunk(0));
+import { chunk } from "stunk";
+import { withHistory } from "stunk/midddleware";
+
+const counterChunk = withHistory(chunk(0));
+
+counterChunk.set(1);
+counterChunk.set(2);
 
-counter.set(10);
-counter.set(20);
+counterChunk.undo(); // Goes back to 1
+counterChunk.undo(); // Goes back to 0
 
-console.log(counter.get()); // 20
+counterChunk.redo(); // Goes forward to 1
 
-counter.undo(); // Go back one step
-console.log(counter.get()); // 10
+counterChunk.canUndo(); // Returns `true` if there is a previous state to revert to..
+counterChunk.canRedo(); // Returns `true` if there is a next state to move to.
 
-counter.redo(); // Go forward one step
-console.log(counter.get()); // 20
+counterChunk.getHistory(); // Returns an array of all the values in the history.
+
+counterChunk.clearHistory(); // Clears the history, keeping only the current value.
 ```
 
 **Example: Limiting History Size (Optional)**
 You can specify a max history size to prevent excessive memory usage.
 
 ```ts
-const counter = withHistory(chunk(0), { maxHistory: 5 }); // Only keeps the last 5 changes -- default is 100.
+const counter = withHistory(chunk(0), { maxHistory: 5 });
+// Only keeps the last 5 changes -- default is 100.
 ```
 
 This prevents the history from growing indefinitely and ensures efficient memory usage.
 
+## State Persistence
+
+Stunk provides a persistence middleware to automatically save state changes to storage (localStorage, sessionStorage, etc).
+
+```typescript
+import { chunk } from "stunk";
+import { withPersistence } from "stunk/middleware";
+
+const counterChunk = withPersistence(chunk({ count: 0 }), {
+  key: "counter-state",
+});
+
+// State automatically persists to localStorage
+counterChunk.set({ count: 1 });
+```
+
+## Async State
+
+```typescript
+import { asyncChunk } from "stunk";
+
+type User = {
+  id: number;
+  name: string;
+  email: string;
+};
+
+const user = asyncChunk<User>(async () => {
+  const response = await fetch("/api/user");
+  return response.json(); // TypeScript expects this to return User;
+});
+
+// Now userChunk is typed as AsyncChunk<User>, which means:
+user.subscribe((state) => {
+  if (state.data) {
+    // state.data is typed as User | null
+    console.log(state.data.name); // TypeScript knows 'name' exists
+    console.log(state.data.age); // ❌ TypeScript Error: Property 'age' does not exist
+  }
+});
+
+user.subscribe(({ loading, error, data }) => {
+  if (loading) console.log("Loading...");
+  if (error) console.log("Error:", error);
+  if (data) console.log("User:", data);
+});
+
+// Reload data
+await user.reload();
+
+// Optimistic update
+user.mutate((currentData) => ({
+  ...currentData,
+  name: "Fola",
+}));
+
+// The mutate function also enforces the User type
+user.mutate(currentUser => ({
+  id: currentUser?.id ?? 0,
+  name: "Olamide",
+  email: "olamide@gmail.com"
+  age: 70  // ❌ TypeScript Error: Object literal may only specify known properties
+}));
+```
+
 ## API Reference
 
-### `chunk<T>(initialValue: T, middleware?: Middleware<T>[])`
+### Core
+
+- `chunk<T>(initialValue: T): Chunk<T>`
+- `batch(fn: () => void): void`
+- `select<T, S>(sourceChunk: Chunk<T>, selector: (state: T) => S): Chunk<S>`
+<!-- - `asyncChunk<T>(fetcher: () => Promise<T>, options?): AsyncChunk<T>` -->
+
+### History
+
+- `withHistory<T>(chunk: Chunk<T>, options: { maxHistory?: number }): ChunkWithHistory<T>`
+
+### Persistance
+
+- `withPersistence<T>(baseChunk: Chunk<T>,options: PersistOptions<T>): Chunk<T>`
 
-Creates a new state chunk.
+### Types
 
 ```typescript
 interface Chunk<T> {
@@ -185,62 +259,50 @@ interface Chunk<T> {
   set(value: T): void;
   subscribe(callback: (value: T) => void): () => void;
   derive<D>(fn: (value: T) => D): Chunk<D>;
+  reset(): void;
   destroy(): void;
 }
 ```
 
-### `select<T, S>(sourceChunk: Chunk<T>, selector: (value: T) => S)`
-
-Creates an optimized selector.
-
 ```typescript
-// Returns a read-only chunk that updates only when selected value changes
-const selector = select(userChunk, (user) => user.name);
+interface AsyncState<T> {
+  loading: boolean;
+  error: Error | null;
+  data: T | null;
+}
 ```
 
-### `batch(callback: () => void)`
-
-Batches multiple updates.
-
 ```typescript
-batch(() => {
-  // Multiple updates here
-});
-
-batch(() => {
-  // Multiple updates here
-  batch(() => {
-    // Nested upddates here
-  });
-});
+interface AsyncChunk<T> extends Chunk<AsyncState<T>> {
+  reload(): Promise<void>;
+  mutate(mutator: (currentData: T | null) => T): void;
+}
 ```
 
-### `withHistory<T>(chunk: Chunk<T>, options?: { maxHistory?: number })`
-
-Adds undo/redo capabilities.
-
 ```typescript
 interface ChunkWithHistory<T> extends Chunk<T> {
-  undo(): void; // Reverts to the previous state (if available).
-  redo(): void; // Moves forward to the next state (if available).
-  canUndo(): boolean; // Returns `true` if there are past states available.
-  canRedo(): boolean; // Returns `true` if there are future states available.
-  getHistory(): T[]; // Returns an `array` of all past states.
-  clearHistory(): void; // Clears all stored history and keeps only the current state.
+  undo: () => void;
+  redo: () => void;
+  canUndo: () => boolean;
+  canRedo: () => boolean;
+  getHistory: () => T[];
+  clearHistory: () => void;
 }
 ```
 
-### `Middleware<T>`
-
-Custom state processing:
-
 ```typescript
-type Middleware<T> = (value: T, next: (newValue: T) => void) => void;
+interface PersistOptions<T> {
+  key: string; // Storage key
+  storage?: Storage; // Storage mechanism (default: localStorage)
+  serialize?: (value: T) => string; // Custom serializer
+  deserialize?: (value: string) => T; // Custom deserializer
+}
 ```
 
-- value: The value that is about to be set to the chunk.
-- next(value): A function you must call with the processed (or unaltered) value to continue the chain of middleware and eventually update the chunk's state.
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## License
 
-MIT
+This is licence under MIT

package/dist/core/asyncChunk.js

@@ -1 +1,46 @@
-"use strict";
+import { chunk } from "./core";
+export function asyncChunk(fetcher, options = {}) {
+    const { initialData = null, onError, retryCount = 0, retryDelay = 1000, } = options;
+    const initialState = {
+        loading: true,
+        error: null,
+        data: initialData,
+    };
+    const baseChunk = chunk(initialState);
+    const fetchData = async (retries = retryCount) => {
+        baseChunk.set({ ...baseChunk.get(), loading: true, error: null });
+        try {
+            const data = await fetcher();
+            baseChunk.set({ loading: false, error: null, data });
+        }
+        catch (error) {
+            if (retries > 0) {
+                await new Promise(resolve => setTimeout(resolve, retryDelay));
+                return fetchData(retries - 1);
+            }
+            const errorObj = error instanceof Error ? error : new Error(String(error));
+            baseChunk.set({ loading: false, error: errorObj, data: baseChunk.get().data });
+            if (onError) {
+                onError(errorObj);
+            }
+        }
+    };
+    // Initial fetch
+    fetchData();
+    const asyncChunkInstance = {
+        ...baseChunk,
+        reload: async () => {
+            await fetchData();
+        },
+        mutate: (mutator) => {
+            const currentState = baseChunk.get();
+            const newData = mutator(currentState.data);
+            baseChunk.set({ ...currentState, data: newData });
+        },
+        reset: () => {
+            baseChunk.set(initialState);
+            fetchData();
+        },
+    };
+    return asyncChunkInstance;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/middleware/index.js

@@ -1,3 +1,6 @@
+// Middleware passed to chunks
 export { logger } from "./logger";
 export { nonNegativeValidator } from "./validator";
+// Middleware used with chunks
 export { withHistory } from "./history";
+export { withPersistence } from './persistence';

package/dist/middleware/persistence.js

@@ -0,0 +1,25 @@
+export function withPersistence(baseChunk, options) {
+    const { key, storage = localStorage, serialize = JSON.stringify, deserialize = JSON.parse, } = options;
+    // Try to load initial state from storage
+    try {
+        const savedChunk = storage.getItem(key);
+        if (savedChunk) {
+            const parsed = deserialize(savedChunk);
+            baseChunk.set(parsed);
+        }
+    }
+    catch (error) {
+        console.error('Failed to load persisted state:', error);
+    }
+    // Save to storage
+    baseChunk.subscribe((newValue) => {
+        try {
+            const serialized = serialize(newValue);
+            storage.setItem(key, serialized);
+        }
+        catch (error) {
+            console.log('Failed to persist chunk', error);
+        }
+    });
+    return baseChunk;
+}

package/dist/utils.js

@@ -1,3 +1,33 @@
+import { chunk } from "./core/core";
 export function isValidChunkValue(value) {
     return value !== null && value !== undefined;
 }
+export function combineAsyncChunks(chunks) {
+    // Create initial state with proper typing
+    const initialData = Object.keys(chunks).reduce((acc, key) => {
+        acc[key] = null;
+        return acc;
+    }, {});
+    const initialState = {
+        loading: true,
+        error: null,
+        data: initialData
+    };
+    const combined = chunk(initialState);
+    Object.entries(chunks).forEach(([key, asyncChunk]) => {
+        asyncChunk.subscribe((state) => {
+            const currentState = combined.get();
+            combined.set({
+                loading: Object.values(chunks).some(chunk => chunk.get().loading),
+                error: Object.values(chunks)
+                    .map(chunk => chunk.get().error)
+                    .find(error => error !== null) || null,
+                data: {
+                    ...currentState.data,
+                    [key]: state.data
+                },
+            });
+        });
+    });
+    return combined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stunk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Stunk - A framework-agnostic state management library implementing the Atomic State technique, utilizing chunk-based units for efficient state management.",
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",
@@ -9,19 +9,25 @@
     "test": "jest --runInBand",
     "prepare": "npm run build"
   },
+  "testEnvironment": "jsdom",
   "keywords": [
     "state-management",
     "atomic-state",
     "framework-agnostic",
     "stunk",
     "state",
-    "chunk"
+    "chunk",
+    "react",
+    "React state management",
+    "Vue state management",
+    "management"
   ],
   "author": "AbdulAzeez",
   "license": "MIT",
   "devDependencies": {
     "@types/jest": "^29.5.14",
     "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "ts-jest": "^29.2.5",
     "typescript": "^5.0.0"
   }

package/src/core/asyncChunk.ts

@@ -0,0 +1,83 @@
+import { chunk, Chunk } from "./core";
+import { AsyncChunkOpt } from "./types";
+
+export interface AsyncState<T> {
+  loading: boolean;
+  error: Error | null;
+  data: T | null;
+}
+
+export interface AsyncChunk<T> extends Chunk<AsyncState<T>> {
+  /**
+   * Reload the data from the source.
+   */
+  reload: () => Promise<void>;
+  /**
+   * Mutate the data directly.
+   */
+  mutate: (mutator: (currentData: T | null) => T) => void;
+  /**
+   * Reset the state to the initial value.
+   */
+  reset: () => void;
+}
+
+export function asyncChunk<T>(fetcher: () => Promise<T>, options: AsyncChunkOpt<T> = {}): AsyncChunk<T> {
+  const {
+    initialData = null,
+    onError,
+    retryCount = 0,
+    retryDelay = 1000,
+  } = options;
+
+  const initialState: AsyncState<T> = {
+    loading: true,
+    error: null,
+    data: initialData,
+  };
+
+  const baseChunk = chunk(initialState);
+
+  const fetchData = async (retries = retryCount): Promise<void> => {
+    baseChunk.set({ ...baseChunk.get(), loading: true, error: null });
+
+    try {
+      const data = await fetcher();
+      baseChunk.set({ loading: false, error: null, data });
+    } catch (error) {
+      if (retries > 0) {
+        await new Promise(resolve => setTimeout(resolve, retryDelay));
+        return fetchData(retries - 1);
+      }
+
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      baseChunk.set({ loading: false, error: errorObj, data: baseChunk.get().data });
+
+      if (onError) {
+        onError(errorObj);
+      }
+
+    }
+  }
+
+  // Initial fetch
+  fetchData();
+
+  const asyncChunkInstance: AsyncChunk<T> = {
+    ...baseChunk,
+    reload: async () => {
+      await fetchData();
+    },
+    mutate: (mutator: (currentData: T | null) => T) => {
+      const currentState = baseChunk.get();
+      const newData = mutator(currentState.data);
+      baseChunk.set({ ...currentState, data: newData });
+    },
+    reset: () => {
+      baseChunk.set(initialState);
+      fetchData();
+    },
+  }
+
+  return asyncChunkInstance;
+}

package/src/core/types.ts

@@ -0,0 +1,17 @@
+import { AsyncChunk } from "./asyncChunk";
+
+export type AsyncChunkOpt<T> = {
+  initialData?: T | null;
+  onError?: (error: Error) => void;
+  retryCount?: number;
+  retryDelay?: number;
+}
+
+export type InferAsyncData<T> = T extends AsyncChunk<infer U> ? U : never;
+
+export type CombinedData<T> = { [K in keyof T]: InferAsyncData<T[K]> | null };
+export type CombinedState<T> = {
+  loading: boolean;
+  error: Error | null;
+  data: CombinedData<T>;
+};

package/src/middleware/history.ts

@@ -1,11 +1,29 @@
 import { Chunk } from "../core/core";
 
 export interface ChunkWithHistory<T> extends Chunk<T> {
+  /**
+ * Reverts to the previous state (if available).
+ */
   undo: () => void;
+  /**
+   * Moves to the next state (if available).
+   */
   redo: () => void;
+  /**
+   * Returns true if there is a previous state to revert to.
+   */
   canUndo: () => boolean;
+  /**
+   * Returns true if there is a next state to move to.
+   */
   canRedo: () => boolean;
+  /**
+   * Returns an array of all the values in the history.
+   */
   getHistory: () => T[];
+  /**
+   * Clears the history, keeping only the current value.
+   */
   clearHistory: () => void;
 }
 

package/src/middleware/index.ts

@@ -1,3 +1,7 @@
+// Middleware passed to chunks
 export { logger } from "./logger";
 export { nonNegativeValidator } from "./validator";
+
+// Middleware used with chunks
 export { withHistory } from "./history";
+export { withPersistence } from './persistence';

package/src/middleware/persistence.ts

@@ -0,0 +1,45 @@
+import { Chunk } from "../core/core";
+
+export interface PersistOptions<T> {
+  key: string;
+  storage?: Storage;
+  serialize?: (value: T) => string;
+  deserialize?: (value: string) => T;
+}
+
+export function withPersistence<T>(
+  baseChunk: Chunk<T>,
+  options: PersistOptions<T>
+): Chunk<T> {
+  const {
+    key,
+    storage = localStorage,
+    serialize = JSON.stringify,
+    deserialize = JSON.parse,
+  } = options;
+
+  // Try to load initial state from storage
+  try {
+    const savedChunk = storage.getItem(key);
+    if (savedChunk) {
+      const parsed = deserialize(savedChunk);
+      baseChunk.set(parsed)
+    }
+  } catch (error) {
+    console.error('Failed to load persisted state:', error);
+  }
+
+  // Save to storage
+  baseChunk.subscribe((newValue) => {
+    try {
+      const serialized = serialize(newValue);
+      storage.setItem(key, serialized);
+
+    } catch (error) {
+      console.log('Failed to persist chunk', error)
+    }
+  })
+
+  return baseChunk
+
+}

package/src/utils.ts

@@ -1,3 +1,49 @@
+import { chunk, Chunk } from "./core/core";
+
+import { AsyncChunk } from "./core/asyncChunk";
+import { CombinedData, CombinedState, InferAsyncData } from "./core/types";
+
 export function isValidChunkValue(value: any): boolean {
   return value !== null && value !== undefined;
 }
+
+export function combineAsyncChunks<T extends Record<string, AsyncChunk<any>>>(
+  chunks: T
+): Chunk<{
+  loading: boolean;
+  error: Error | null;
+  data: { [K in keyof T]: InferAsyncData<T[K]> | null };
+}> {
+  // Create initial state with proper typing
+  const initialData = Object.keys(chunks).reduce((acc, key) => {
+    acc[key as keyof T] = null;
+    return acc;
+  }, {} as CombinedData<T>);
+
+  const initialState: CombinedState<T> = {
+    loading: true,
+    error: null,
+    data: initialData
+  };
+
+  const combined = chunk(initialState);
+
+  Object.entries(chunks).forEach(([key, asyncChunk]) => {
+    asyncChunk.subscribe((state) => {
+      const currentState = combined.get();
+
+      combined.set({
+        loading: Object.values(chunks).some(chunk => chunk.get().loading),
+        error: Object.values(chunks)
+          .map(chunk => chunk.get().error)
+          .find(error => error !== null) || null,
+        data: {
+          ...currentState.data,
+          [key]: state.data
+        },
+      });
+    });
+  });
+
+  return combined;
+}

package/tests/async-chunk.test.ts

@@ -0,0 +1,215 @@
+import { asyncChunk } from '../src/core/asyncChunk';
+import { combineAsyncChunks } from '../src/utils';
+
+// Mock types for testing
+interface User {
+  id: number;
+  name: string;
+}
+
+interface Post {
+  id: number;
+  title: string;
+}
+
+describe('asyncChunk', () => {
+  // Helper to create a delayed response
+  const createDelayedResponse = <T>(data: T, delay = 50): Promise<T> => {
+    return new Promise((resolve) => setTimeout(() => resolve(data), delay));
+  };
+
+  it('should handle successful async operations', async () => {
+    const mockUser: User = { id: 1, name: 'Test User' };
+    const userChunk = asyncChunk<User>(async () => {
+      return createDelayedResponse(mockUser);
+    });
+
+    // Initial state
+    expect(userChunk.get()).toEqual({
+      loading: true,
+      error: null,
+      data: null
+    });
+
+    // Wait for async operation to complete
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // Check final state
+    expect(userChunk.get()).toEqual({
+      loading: false,
+      error: null,
+      data: mockUser
+    });
+  });
+
+  it('should handle errors', async () => {
+    const errorMessage = 'Failed to fetch';
+    const userChunk = asyncChunk<User>(async () => {
+      throw new Error(errorMessage);
+    });
+
+    // Wait for async operation to complete
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    const state = userChunk.get();
+    expect(state.loading).toBe(false);
+    expect(state.error?.message).toBe(errorMessage);
+    expect(state.data).toBe(null);
+  });
+
+  it('should handle retries', async () => {
+    let attempts = 0;
+    const mockUser: User = { id: 1, name: 'Test User' };
+
+    const userChunk = asyncChunk<User>(
+      async () => {
+        attempts++;
+        if (attempts < 3) {
+          throw new Error('Temporary error');
+        }
+        return mockUser;
+      },
+      { retryCount: 2, retryDelay: 50 }
+    );
+
+    // Wait for all retries to complete
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    expect(attempts).toBe(3);
+    expect(userChunk.get().data).toEqual(mockUser);
+  });
+
+  it('should support optimistic updates via mutate', () => {
+    const mockUser: User = { id: 1, name: 'Test User' };
+    const userChunk = asyncChunk<User>(async () => mockUser);
+
+    userChunk.mutate(current => ({
+      ...current!,
+      name: 'Updated Name'
+    }));
+
+    const state = userChunk.get();
+    expect(state.data?.name).toBe('Updated Name');
+  });
+
+  it('should reload data when requested', async () => {
+    let counter = 0;
+    const userChunk = asyncChunk<User>(async () => {
+      counter++;
+      return { id: counter, name: `User ${counter}` };
+    });
+
+    // Wait for initial load
+    await new Promise(resolve => setTimeout(resolve, 100));
+    expect(userChunk.get().data?.id).toBe(1);
+
+    // Trigger reload
+    await userChunk.reload();
+    expect(userChunk.get().data?.id).toBe(2);
+  });
+});
+
+describe('combineAsyncChunks', () => {
+  it('should combine multiple async chunks', async () => {
+    const mockUser: User = { id: 1, name: 'Test User' };
+    const mockPosts: Post[] = [
+      { id: 1, title: 'Post 1' },
+      { id: 2, title: 'Post 2' }
+    ];
+
+    const userChunk = asyncChunk<User>(async () => {
+      return createDelayedResponse(mockUser, 50);
+    });
+
+    const postsChunk = asyncChunk<Post[]>(async () => {
+      return createDelayedResponse(mockPosts, 100);
+    });
+
+    const combined = combineAsyncChunks({
+      user: userChunk,
+      posts: postsChunk
+    });
+
+    // Initial state
+    expect(combined.get()).toEqual({
+      loading: true,
+      error: null,
+      data: {
+        user: null,
+        posts: null
+      }
+    });
+
+    // Wait for all async operations to complete
+    await new Promise(resolve => setTimeout(resolve, 150));
+
+    // Check final state
+    expect(combined.get()).toEqual({
+      loading: false,
+      error: null,
+      data: {
+        user: mockUser,
+        posts: mockPosts
+      }
+    });
+  });
+
+  it('should handle errors in combined chunks', async () => {
+    const mockUser: User = { id: 1, name: 'Test User' };
+    const errorMessage = 'Failed to fetch posts';
+
+    const userChunk = asyncChunk<User>(async () => {
+      return createDelayedResponse(mockUser, 50);
+    });
+
+    const postsChunk = asyncChunk<Post[]>(async () => {
+      throw new Error(errorMessage);
+    });
+
+    const combined = combineAsyncChunks({
+      user: userChunk,
+      posts: postsChunk
+    });
+
+    // Wait for all operations to complete
+    await new Promise(resolve => setTimeout(resolve, 150));
+
+    const state = combined.get();
+    expect(state.loading).toBe(false);
+    expect(state.error?.message).toBe(errorMessage);
+    expect(state.data.user).toEqual(mockUser);
+    expect(state.data.posts).toBe(null);
+  });
+
+  it('should update loading state correctly', async () => {
+    const loadingStates: boolean[] = [];
+    const userChunk = asyncChunk<User>(async () => {
+      return createDelayedResponse({ id: 1, name: 'Test User' }, 50);
+    });
+
+    const postsChunk = asyncChunk<Post[]>(async () => {
+      return createDelayedResponse([], 100);
+    });
+
+    const combined = combineAsyncChunks({
+      user: userChunk,
+      posts: postsChunk
+    });
+
+    combined.subscribe(state => {
+      loadingStates.push(state.loading);
+    });
+
+    // Wait for all operations
+    await new Promise(resolve => setTimeout(resolve, 150));
+
+    // Should start with loading true and end with false
+    expect(loadingStates[0]).toBe(true);
+    expect(loadingStates[loadingStates.length - 1]).toBe(false);
+  });
+});
+
+// Helper function
+function createDelayedResponse<T>(data: T, delay = 50): Promise<T> {
+  return new Promise((resolve) => setTimeout(() => resolve(data), delay));
+}

package/tests/persist.test.ts

@@ -0,0 +1,57 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { chunk } from '../src/core/core';
+import { withPersistence } from "../src/middleware/persistence";
+
+describe('withPersistence', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    sessionStorage.clear();
+  });
+
+  it('should persist state to localStorage', () => {
+    const baseChunk = chunk({ count: 0 });
+    const persistedChunk = withPersistence(baseChunk, { key: 'test-key' });
+
+    persistedChunk.set({ count: 1 });
+    expect(JSON.parse(localStorage.getItem('test-key')!)).toEqual({ count: 1 });
+  });
+
+  it('should load persisted state on initialization', () => {
+    localStorage.setItem('test-key', JSON.stringify({ count: 5 }));
+
+    const baseChunk = chunk({ count: 0 });
+    const persistedChunk = withPersistence(baseChunk, { key: 'test-key' });
+
+    expect(persistedChunk.get()).toEqual({ count: 5 });
+  });
+
+  it('should use custom storage', () => {
+    const mockStorage = {
+      getItem: jest.fn(),
+      setItem: jest.fn(),
+    };
+
+    const baseChunk = chunk({ count: 0 });
+    withPersistence(baseChunk, {
+      key: 'test-key',
+      storage: mockStorage as unknown as Storage
+    });
+
+    expect(mockStorage.getItem).toHaveBeenCalledWith('test-key');
+  });
+
+  it('should use custom serializer/deserializer', () => {
+    const baseChunk = chunk({ count: 0 });
+    const persistedChunk = withPersistence(baseChunk, {
+      key: 'test-key',
+      serialize: value => btoa(JSON.stringify(value)),
+      deserialize: value => JSON.parse(atob(value))
+    });
+
+    persistedChunk.set({ count: 1 });
+    expect(localStorage.getItem('test-key')).toBe(btoa(JSON.stringify({ count: 1 })));
+  });
+});