stunk 2.0.0 → 2.2.0

package/LICENSE

@@ -1,27 +1,27 @@
----
-
-### **`LICENSE`**
-
-```text
-MIT License
-
-Copyright (c) 2025 AbdulAzeez
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
+---
+
+### **`LICENSE`**
+
+```text
+MIT License
+
+Copyright (c) 2025 AbdulAzeez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/README.md

@@ -1,43 +1,43 @@
-# Stunk
-
-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")
-
-**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/)
-
-## 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
+# 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/)
+
+## 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

package/dist/src/core/asyncChunk.d.ts

@@ -0,0 +1,28 @@
+import { Chunk } from "./core";
+import { AsyncChunkOpt } from "./types";
+export interface AsyncState<T, E extends Error> {
+    loading: boolean;
+    error: E | null;
+    data: T | null;
+}
+export interface AsyncChunk<T, E extends Error = Error> extends Chunk<AsyncState<T, E>> {
+    /**
+     * 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;
+}
+/**
+ * Creates an async chunk that handles loading, error, and retry logic.
+ * @param fetcher The async function to fetch data.
+ * @param options Configuration options for the async chunk.
+ * @returns An async chunk instance.
+ */
+export declare function asyncChunk<T, E extends Error = Error>(fetcher: () => Promise<T>, options?: AsyncChunkOpt<T, E>): AsyncChunk<T, E>;

package/dist/{core → src/core}/asyncChunk.js

@@ -1,4 +1,10 @@
 import { chunk } from "./core";
+/**
+ * Creates an async chunk that handles loading, error, and retry logic.
+ * @param fetcher The async function to fetch data.
+ * @param options Configuration options for the async chunk.
+ * @returns An async chunk instance.
+ */
 export function asyncChunk(fetcher, options = {}) {
     const { initialData = null, onError, retryCount = 0, retryDelay = 1000, } = options;
     const initialState = {
@@ -18,14 +24,12 @@ export function asyncChunk(fetcher, options = {}) {
                 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 });
+            baseChunk.set({ loading: false, error: error, data: baseChunk.get().data });
             if (onError) {
-                onError(errorObj);
+                onError(error);
             }
         }
     };
-    // Initial fetch
     fetchData();
     const asyncChunkInstance = {
         ...baseChunk,

package/dist/{core → src/core}/computed.d.ts

@@ -4,7 +4,12 @@ export type DependencyValues<T extends Chunk<any>[]> = {
     [K in keyof T]: T[K] extends Chunk<any> ? ChunkValue<T[K]> : never;
 };
 export interface Computed<T> extends Chunk<T> {
+    /**
+    * Checks if the computed value needs to be recalculated due to dependency changes.
+    * @returns True if the computed value is dirty, false otherwise.
+    */
     isDirty: () => boolean;
+    /** Manually forces recalculation of the computed value from its dependencies. */
     recompute: () => void;
 }
 export declare function computed<TDeps extends Chunk<any>[], TResult>(dependencies: [...TDeps], computeFn: (...args: DependencyValues<TDeps>) => TResult): Computed<TResult>;

package/dist/src/core/computed.js

@@ -0,0 +1,58 @@
+import { chunk } from "./core";
+import { shallowEqual } from "../utils";
+export function computed(dependencies, computeFn) {
+    const dependencyValues = dependencies.map(dep => dep.get());
+    let cachedValue = computeFn(...dependencyValues);
+    const computedChunk = chunk(cachedValue);
+    const originalSet = computedChunk.set;
+    let isDirty = false;
+    // Direct synchronous recomputation
+    const recompute = () => {
+        let hasChanges = false;
+        for (let i = 0; i < dependencies.length; i++) {
+            const newValue = dependencies[i].get();
+            if (newValue !== dependencyValues[i]) {
+                dependencyValues[i] = newValue;
+                hasChanges = true;
+            }
+        }
+        if (hasChanges) {
+            const newValue = computeFn(...dependencyValues);
+            // Fast path for primitives only. Avoids shallowEqual for performance.
+            if (newValue !== cachedValue) {
+                // Only use shallowEqual for objects when needed
+                if (typeof newValue !== 'object' || typeof cachedValue !== 'object' || !shallowEqual(newValue, cachedValue)) {
+                    cachedValue = newValue;
+                    originalSet(newValue);
+                }
+            }
+            isDirty = false;
+        }
+    };
+    const unsubs = dependencies.map(dep => dep.subscribe(() => {
+        isDirty = true;
+        recompute();
+    }));
+    return {
+        ...computedChunk,
+        get: () => {
+            if (isDirty)
+                recompute();
+            return cachedValue;
+        },
+        recompute,
+        isDirty: () => isDirty,
+        set: () => { throw new Error('Cannot set values directly on computed. Modify the source chunk instead.'); },
+        reset: () => {
+            dependencies.forEach(dep => {
+                if (typeof dep.reset === 'function') {
+                    dep.reset();
+                }
+            });
+            isDirty = true;
+            recompute();
+            return cachedValue;
+        },
+        destroy: () => { unsubs.forEach(unsub => unsub()); computedChunk.destroy?.(); }
+    };
+}

package/dist/{core → src/core}/core.d.ts

@@ -14,5 +14,9 @@ export interface Chunk<T> {
     /** Destroy the chunk and all its subscribers. */
     destroy: () => void;
 }
+/**
+ * Batch multiple chunk updates into a single re-render.
+ * Useful for updating multiple chunks at once without causing multiple re-renders.
+ */
 export declare function batch(callback: () => void): void;
 export declare function chunk<T>(initialValue: T, middleware?: Middleware<T>[]): Chunk<T>;

package/dist/{core → src/core}/core.js

@@ -1,17 +1,28 @@
 import { processMiddleware } from "../utils";
-let batchDepth = 0;
-const batchQueue = new Set();
+let isBatching = false;
+const dirtyChunks = new Set();
+const chunkRegistry = new Map();
+let chunkIdCounter = 0;
+/**
+ * Batch multiple chunk updates into a single re-render.
+ * Useful for updating multiple chunks at once without causing multiple re-renders.
+ */
 export function batch(callback) {
-    batchDepth++;
+    const wasBatchingBefore = isBatching;
+    isBatching = true;
     try {
         callback();
     }
     finally {
-        batchDepth--;
-        if (batchDepth === 0) {
-            // Execute all queued updates
-            batchQueue.forEach(update => update());
-            batchQueue.clear();
+        if (!wasBatchingBefore) {
+            isBatching = false;
+            const chunks = Array.from(dirtyChunks); // Snapshot to avoid mutation issues
+            dirtyChunks.clear(); // Clear early to prevent re-adds
+            chunks.forEach(id => {
+                const chunk = chunkRegistry.get(id);
+                if (chunk)
+                    chunk.notify();
+            });
         }
     }
 }
@@ -21,32 +32,28 @@ export function chunk(initialValue, middleware = []) {
     }
     let value = initialValue;
     const subscribers = new Set();
-    let isDirty = false;
+    const chunkId = chunkIdCounter++;
+    const notify = () => {
+        subscribers.forEach(subscriber => subscriber(value));
+    };
+    chunkRegistry.set(chunkId, { notify });
     const notifySubscribers = () => {
-        if (batchDepth > 0) {
-            if (!isDirty) {
-                isDirty = true;
-                batchQueue.add(() => {
-                    if (isDirty) {
-                        subscribers.forEach((subscriber) => subscriber(value));
-                        isDirty = false;
-                    }
-                });
-            }
+        if (subscribers.size === 0)
+            return; // Skip if no subscribers
+        if (isBatching) {
+            dirtyChunks.add(chunkId);
         }
         else {
-            subscribers.forEach((subscriber) => subscriber(value));
+            notify();
         }
     };
     const get = () => value;
     const set = (newValueOrUpdater) => {
         let newValue;
         if (typeof newValueOrUpdater === 'function') {
-            // Handle updater function
             newValue = newValueOrUpdater(value);
         }
         else {
-            // Handle direct value assignment
             newValue = newValueOrUpdater;
         }
         const processedValue = processMiddleware(newValue, middleware);
@@ -59,35 +66,36 @@ export function chunk(initialValue, middleware = []) {
         if (typeof callback !== "function") {
             throw new Error("Callback must be a function.");
         }
-        if (subscribers.has(callback)) {
-            console.warn("Callback is already subscribed. This may lead to duplicate updates.");
-        }
         subscribers.add(callback);
         callback(value);
         return () => subscribers.delete(callback);
     };
     const reset = () => {
         value = initialValue;
-        subscribers.forEach((subscriber) => subscriber(value));
+        notifySubscribers();
     };
     const destroy = () => {
-        if (subscribers.size > 0) {
-            console.warn("Destroying chunk with active subscribers. This may lead to memory leaks.");
-        }
-        // Just clear subscribers without calling unsubscribe
         subscribers.clear();
         value = initialValue;
+        dirtyChunks.delete(chunkId);
+        chunkRegistry.delete(chunkId);
     };
     const derive = (fn) => {
         if (typeof fn !== "function") {
             throw new Error("Derive function must be a function.");
         }
-        const derivedValue = fn(value);
-        const derivedChunk = chunk(derivedValue);
-        subscribe(() => {
+        const initialDerivedValue = fn(value);
+        const derivedChunk = chunk(initialDerivedValue);
+        const unsubscribe = subscribe(() => {
             const newDerivedValue = fn(value);
             derivedChunk.set(newDerivedValue);
         });
+        // Add a cleanup method to the derived chunk
+        const originalDestroy = derivedChunk.destroy;
+        derivedChunk.destroy = () => {
+            unsubscribe();
+            originalDestroy();
+        };
         return derivedChunk;
     };
     return { get, set, subscribe, derive, reset, destroy };

package/dist/src/core/selector.d.ts

@@ -0,0 +1,17 @@
+import { Chunk } from "./core";
+export interface SelectOptions {
+    /**
+     * Configuration options for selector functions.
+     * @property {boolean} [useShallowEqual] - When true, performs a shallow equality check
+     * on the derived selector results to prevent unnecessary updates.
+     */
+    useShallowEqual?: boolean;
+}
+/**
+ * Creates a derived read-only chunk based on a selector function.
+ * @param sourceChunk The source chunk to derive from.
+ * @param selector A function that extracts part of the source value.
+ * @param options Optional settings for shallow equality comparison.
+ * @returns A read-only derived chunk.
+ */
+export declare function select<T, S>(sourceChunk: Chunk<T>, selector: (value: T) => S, options?: SelectOptions): Chunk<S>;

package/dist/src/core/selector.js

@@ -0,0 +1,45 @@
+import { shallowEqual } from "../utils";
+import { chunk } from "./core";
+/**
+ * Creates a derived read-only chunk based on a selector function.
+ * @param sourceChunk The source chunk to derive from.
+ * @param selector A function that extracts part of the source value.
+ * @param options Optional settings for shallow equality comparison.
+ * @returns A read-only derived chunk.
+ */
+export function select(sourceChunk, selector, options = {}) {
+    const { useShallowEqual = false } = options;
+    let prevSourceValue = sourceChunk.get();
+    let currentResult = selector(prevSourceValue);
+    const derivedChunk = chunk(currentResult);
+    const update = () => {
+        const newSourceValue = sourceChunk.get();
+        const newResult = selector(newSourceValue);
+        // Always update the reference to source value
+        prevSourceValue = newSourceValue;
+        // Check if the result has changed
+        const resultChanged = useShallowEqual
+            ? !shallowEqual(newResult, currentResult)
+            : newResult !== currentResult;
+        if (resultChanged) {
+            currentResult = newResult;
+            derivedChunk.set(newResult);
+        }
+    };
+    const unsubscribe = sourceChunk.subscribe(update);
+    return {
+        get: () => derivedChunk.get(),
+        set: () => {
+            throw new Error('Cannot set values directly on a selector. Modify the source chunk instead.');
+        },
+        subscribe: derivedChunk.subscribe,
+        derive: (fn) => select(derivedChunk, fn, options), // Pass options to nested selectors
+        reset: () => {
+            throw new Error('Cannot reset a selector chunk. Reset the source chunk instead.');
+        },
+        destroy: () => {
+            unsubscribe();
+            derivedChunk.destroy();
+        }
+    };
+}

package/dist/{core → src/core}/types.d.ts

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

package/dist/{use-react → src/use-react}/hooks/useAsyncChunk.d.ts

@@ -3,11 +3,11 @@ import { AsyncChunk, AsyncState } from "../../core/asyncChunk";
  * A hook that handles asynchronous state with built-in reactivity.
  * Provides loading, error, and data states.
  */
-export declare function useAsyncChunk<T>(asyncChunk: AsyncChunk<T>): {
-    state: AsyncState<T>;
+export declare function useAsyncChunk<T, E extends Error>(asyncChunk: AsyncChunk<T, E>): {
+    state: AsyncState<T, E>;
     data: T | null;
     loading: boolean;
-    error: Error | null;
+    error: E | null;
     reload: () => Promise<void>;
     mutate: (mutator: (currentData: T | null) => T) => void;
     reset: () => void;

package/dist/{use-react → src/use-react}/hooks/useAsyncChunk.js

@@ -22,6 +22,6 @@ export function useAsyncChunk(asyncChunk) {
         error,
         reload,
         mutate,
-        reset
+        reset,
     };
 }

package/dist/{use-react → src/use-react}/hooks/useDerive.js

@@ -1,11 +1,17 @@
-import { useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { useChunk } from "./useChunk";
 /**
  * A hook for creating a read-only derived value from a chunk.
  * Ensures reactivity and updates when the source chunk changes.
  */
 export function useDerive(chunk, fn) {
-    const derivedChunk = useMemo(() => chunk.derive(fn), [chunk, fn]);
+    const fnRef = useRef(fn);
+    useEffect(() => {
+        fnRef.current = fn;
+    }, [fn]);
+    const derivedChunk = useMemo(() => {
+        return chunk.derive((value) => fnRef.current(value));
+    }, [chunk]);
     const [derivedValue] = useChunk(derivedChunk);
     return derivedValue;
 }

package/dist/{utils.d.ts → src/utils.d.ts}

@@ -12,3 +12,4 @@ export declare function combineAsyncChunks<T extends Record<string, AsyncChunk<a
     };
 }>;
 export declare function processMiddleware<T>(initialValue: T, middleware?: Middleware<T>[]): T;
+export declare function shallowEqual<T>(a: T, b: T): boolean;

package/dist/{utils.js → src/utils.js}

@@ -77,3 +77,37 @@ export function processMiddleware(initialValue, middleware = []) {
     }
     return currentValue;
 }
+export function shallowEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (!a || !b || typeof a !== typeof b) {
+        return false;
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (typeof a === 'object' && typeof b === 'object') {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length) {
+            return false;
+        }
+        for (const key of keysA) {
+            if (!Object.prototype.hasOwnProperty.call(b, key) || a[key] !== b[key]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    // For primitive types, return false. Strict equality already handled by initial check
+    return false;
+}

package/dist/tests/async-chunk.test.d.ts

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