stunk 0.7.0 → 0.9.0

package/README.md

@@ -1,101 +1,62 @@
 # Stunk
 
-**Stunk** is a **framework-agnostic** state management library that helps you manage your application's state in a clean and simple way. It uses a technique called **Atomic State**, breaking down state into smaller **chunks** that are easy to update, subscribe to, and manage.
-
----
-
-## 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.
 
-### Why Stunk
-
-- lightweight, framework-agnostic state management.
-- granular control over state updates and subscriptions.
-- modular and composable state architecture.
+## 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 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
 
-You can install **Stunk** from NPM:
-
 ```bash
 npm install stunk
+# or
+yarn add stunk
 ```
 
-## 1 Features
+## Basic Usage
 
-### 1.0 **Chunks**
+A **chunk** is a small container of state. It holds a value, and you can do some stuffs with it:
 
-A **chunk** is a small container of state. It holds a value, and you can do three things with it:
-
-- **Get** the current value of the chunk
-- **Set** a new value for the chunk
-- **Subscribe** to the chunk to get notified whenever the value changes
-
-### Usage:
-
-```ts
+```typescript
 import { chunk } from "stunk";
 
-const count = chunk(0);
-
-console.log(count.get()); // 0
-
-count.set(5);
-
-console.log(count.get()); // 5
-```
-
-### 1.1. **Subscription**
-
-You can **subscribe** to a **chunk**. This means you get notified whenever the value inside the chunk changes. This is super useful for updating your app automatically when **state** changes.
-
-### Usage
-
-```ts
-const count = chunk(0);
-const callback = (newValue: number) => console.log("Updated value:", newValue);
-
-count.subscribe(callback);
-
-count.set(10); // Will log: "Updated value: 10"
-```
-
-### 1.1.0. **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..** Well, would you wanna do that? 😂
-
-### Usage
+// Create a simple counter
+const counterChunk = chunk(0);
 
-```ts
-const count = chunk(0);
-const callback = (newValue: number) => console.log("Updated value:", newValue);
-
-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();
 ```
 
-### 1.2. **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.
+## Deriving New Chunks
 
-### Usage
+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.
 
-```ts
+```typescript
 const count = chunk(5);
 
 // Create a derived chunk that doubles the count
@@ -110,138 +71,238 @@ count.set(10);
 // "Double count: 20"
 ```
 
-### 1.3. **Batch Updates**
+## Batch Updates
 
-Batch updates allow you to 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.
+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.
 
-### Usage
-
-```ts
+```typescript
 import { chunk, batch } from "stunk";
 
-const firstName = chunk("John");
-const lastName = chunk("Doe");
-const age = chunk(25);
+const nameChunk = chunk("Olamide");
+const ageChunk = chunk(30);
 
-// Subscribe to changes
-firstName.subscribe((name) => console.log("First name changed:", name));
-lastName.subscribe((name) => console.log("Last name changed:", name));
-age.subscribe((age) => console.log("Age changed:", age));
-
-// Without batch - triggers three separate updates
-firstName.set("Jane"); // Logs immediately
-lastName.set("Smith"); // Logs immediately
-age.set(26); // Logs immediately
-
-// With batch - triggers only one update per chunk at the end
 batch(() => {
-  firstName.set("Jane"); // Doesn't log yet
-  lastName.set("Smith"); // Doesn't log yet
-  age.set(26); // Doesn't log yet
-}); // All logs happen here at once
+  nameChunk.set("AbdulAzeez");
+  ageChunk.set(31);
+}); // Only one notification will be sent to subscribers
 
 // Nested batches are also supported
 batch(() => {
-  firstName.set("Jane");
+  firstName.set("Olanrewaju");
   batch(() => {
-    lastName.set("Smith");
-    age.set(26);
+    age.set(29);
   });
-});
+}); // Only one notification will be sent to subscribers
 ```
 
-Looks intresting right? There's more!
-
-Batching is particularly useful when:
-
-- Updating multiple related pieces of state at once
-- Performing form updates
-- Handling complex state transitions
-- Optimizing performance in data-heavy applications
+## State Selection
 
-The batch function ensures that:
+Efficiently access and react to specific state parts:
 
-- All updates within the batch are processed together
-- Subscribers are notified only once with the final value
-- Nested batches are handled correctly
-- Updates are processed even if an error occurs (using try/finally)
+```typescript
+import { chunk, select } from "stunk";
 
-### 1.4. **Middleware**
+const userChunk = chunk({
+  name: "Olamide",
+  age: 30,
+  email: "olamide@example.com",
+});
 
-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.
+// Select specific properties -readonly
+const nameChunk = select(userChunk, (state) => state.name);
+const ageChunk = select(userChunk, (state) => state.age);
 
-A middleware is a function with the following structure:
+nameChunk.subscribe((name) => console.log("Name changed:", name));
+// will only re-render if the selected part change.
 
-```ts
-export type Middleware<T> = (value: T, next: (newValue: T) => void) => void;
+nameChunk.set("Olamide"); // ❌ this will throw an error, because it is a readonly.
 ```
 
-- 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.
+## Middleware
 
-### Usage
+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.
 
-```ts
+```typescript
 import { chunk } from "stunk";
-import { logger } from "stunk/middleware"; // native to stunk
-import { nonNegativeValidator } from "stunk/middleware"; // native to stunk
-// You can also create yours and pass it []
+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!"
 ```
 
-### 1.4.1. Middleware: Undo & Redo (withHistory)
-
-The **withHistory** middleware extends a chunk to support undo and redo functionality. This allows you to navigate back and forth between previous **states**, making it useful for implementing features like **undo/redo**, form history, and state time travel.
-
-### Usage
+## Time Travel (Middleware)
 
-```ts
+```typescript
 import { chunk } from "stunk";
-import { withHistory } from "stunk/middleware"; // Import the history middleware
+import { withHistory } from "stunk/midddleware";
 
-const counter = withHistory(chunk(0));
+const counterChunk = withHistory(chunk(0));
 
-counter.set(10);
-counter.set(20);
+counterChunk.set(1);
+counterChunk.set(2);
 
-console.log(counter.get()); // 20
+counterChunk.undo(); // Goes back to 1
+counterChunk.undo(); // Goes back to 0
 
-counter.undo(); // Go back one step
-console.log(counter.get()); // 10
+counterChunk.redo(); // Goes forward to 1
 
-counter.redo(); // Go forward one step
-console.log(counter.get()); // 20
-```
+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.
 
-**Available Methods**
+counterChunk.getHistory(); // Returns an array of all the values in the history.
 
-| Method           | Description                                                 |
-| ---------------- | ----------------------------------------------------------- |
-| `undo()`         | Reverts to the previous state (if available).               |
-| `redo()`         | Moves forward to the next state (if available).             |
-| `canUndo()`      | Returns `true` if there are past states available.          |
-| `canRedo()`      | Returns `true` if there are future states available.        |
-| `getHistory()`   | Returns an `array` of all past states.                      |
-| `clearHistory()` | Clears all stored history and keeps only the current state. |
+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.
 
-## 2. **Atomic State Technique**
+## 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
+
+### 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>`
+
+### Types
+
+```typescript
+interface Chunk<T> {
+  get(): T;
+  set(value: T): void;
+  subscribe(callback: (value: T) => void): () => void;
+  derive<D>(fn: (value: T) => D): Chunk<D>;
+  reset(): void;
+  destroy(): void;
+}
+```
+
+```typescript
+interface AsyncState<T> {
+  loading: boolean;
+  error: Error | null;
+  data: T | null;
+}
+```
+
+```typescript
+interface AsyncChunk<T> extends Chunk<AsyncState<T>> {
+  reload(): Promise<void>;
+  mutate(mutator: (currentData: T | null) => T): void;
+}
+```
+
+```typescript
+interface ChunkWithHistory<T> extends Chunk<T> {
+  undo: () => void;
+  redo: () => void;
+  canUndo: () => boolean;
+  canRedo: () => boolean;
+  getHistory: () => T[];
+  clearHistory: () => void;
+}
+```
+
+```typescript
+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
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-The **Atomic State** technique is all about breaking down your state into small, manageable chunks. This allows you to:
+## License
 
-- Keep state changes focused and efficient
-- Update only the parts of your app that need to change
-- Easily manage and subscribe to state changes
+This is licence under MIT

package/dist/core/asyncChunk.js

@@ -0,0 +1,46 @@
+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.7.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 })));
+  });
+});