stunk 0.8.0 → 1.0.0

package/README.md

@@ -1,92 +1,62 @@
 # 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
+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.
 
 - **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.
 
 **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 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
 ```
 
-## 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 +73,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 +125,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 +261,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/computed.js

@@ -0,0 +1,63 @@
+import { isChunk } from "../utils";
+import { chunk } from "./core";
+export function computed(computeFn) {
+    // Track the currently executing computed function
+    let currentComputation = null;
+    // Set to track dependencies
+    const dependencies = new Set();
+    const trackingProxy = new Proxy({}, {
+        get(_, prop) {
+            if (currentComputation && prop === 'value') {
+                const chunkValue = this[prop];
+                if (isChunk(chunkValue)) {
+                    dependencies.add(chunkValue);
+                    return chunkValue.get();
+                }
+            }
+            return this[prop];
+        },
+    });
+    // Initial computation
+    let cachedValue;
+    let isDirty = true;
+    const computeValue = () => {
+        if (!isDirty)
+            return cachedValue;
+        // Reset dependencies
+        dependencies.clear();
+        // Set the current computation context
+        currentComputation = computeFn;
+        try {
+            // Compute with tracking
+            cachedValue = computeFn.call(trackingProxy);
+            isDirty = false;
+        }
+        finally {
+            // Clear the current computation context
+            currentComputation = null;
+        }
+        return cachedValue;
+    };
+    // Create the computed chunk
+    const computedChunk = chunk(computeValue());
+    // Subscribe to all detected dependencies
+    dependencies.forEach(dep => {
+        dep.subscribe(() => {
+            isDirty = true;
+            computedChunk.set(computeValue());
+        });
+    });
+    return {
+        ...computedChunk,
+        get: () => {
+            if (isDirty) {
+                return computeValue();
+            }
+            return cachedValue;
+        },
+        // Prevent direct setting
+        set: () => {
+            throw new Error('Cannot directly set a computed value');
+        }
+    };
+}

package/dist/core/core.js

@@ -1,3 +1,4 @@
+import { processMiddleware } from "../utils";
 let batchDepth = 0;
 const batchQueue = new Set();
 export function batch(callback) {
@@ -43,7 +44,6 @@ export function chunk(initialValue, middleware = []) {
     let value = initialValue;
     const subscribers = new Set();
     let isDirty = false;
-    const get = () => value;
     const notifySubscribers = () => {
         if (batchDepth > 0) {
             if (!isDirty) {
@@ -60,30 +60,22 @@ export function chunk(initialValue, middleware = []) {
             subscribers.forEach((subscriber) => subscriber(value));
         }
     };
+    const get = () => value;
     const set = (newValue) => {
-        if (newValue === null || newValue === undefined) {
-            throw new Error("Value cannot be null or undefined.");
+        const processedValue = processMiddleware(newValue, middleware);
+        if (processedValue !== value) {
+            value = processedValue;
+            notifySubscribers();
         }
-        let currentValue = newValue;
-        let index = 0;
-        while (index < middleware.length) {
-            const currentMiddleware = middleware[index];
-            let nextCalled = false;
-            let nextValue = null;
-            currentMiddleware(currentValue, (val) => {
-                nextCalled = true;
-                nextValue = val;
-            });
-            if (!nextCalled)
-                break;
-            if (nextValue === null || nextValue === undefined) {
-                throw new Error("Value cannot be null or undefined.");
-            }
-            currentValue = nextValue;
-            index++;
+    };
+    const update = (updater) => {
+        if (typeof updater !== 'function') {
+            throw new Error("Updater must be a function");
         }
-        if (currentValue !== value) {
-            value = currentValue;
+        const newValue = updater(value);
+        const processedValue = processMiddleware(newValue);
+        if (processedValue !== value) {
+            value = processedValue;
             notifySubscribers();
         }
     };
@@ -96,9 +88,7 @@ export function chunk(initialValue, middleware = []) {
         }
         subscribers.add(callback);
         callback(value);
-        return () => {
-            subscribers.delete(callback);
-        };
+        return () => subscribers.delete(callback);
     };
     const reset = () => {
         value = initialValue;
@@ -124,5 +114,5 @@ export function chunk(initialValue, middleware = []) {
         });
         return derivedChunk;
     };
-    return { get, set, subscribe, derive, reset, destroy };
+    return { get, set, update, subscribe, derive, reset, destroy };
 }

package/dist/core/types.js

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

package/dist/index.js

@@ -1,2 +1,3 @@
-export { chunk } from './core/core';
+export { chunk, batch, select } from './core/core';
+export { asyncChunk } from './core/asyncChunk';
 export * from "./middleware";

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