stunk 1.0.1 → 1.2.3

package/README.md

@@ -171,6 +171,110 @@ const counter = withHistory(chunk(0), { maxHistory: 5 });
 
 This prevents the history from growing indefinitely and ensures efficient memory usage.
 
+## Computed
+
+Computed Chunks in Stunk allow you to create state derived from other chunks in a reactive way. Unlike derived chunks, computed chunks can depend on multiple sources, and they automatically recalculate when any of the source chunks change.
+
+- Multiple Dependencies: Can depend on multiple chunks.
+- Memoization: Only recalculates when dependencies change.
+- Type-Safe: Fully typed in TypeScript for safe data handling.
+- Reactive: Automatically updates subscribers when any dependency changes.
+
+```typescript
+import { chunk, computed } from "stunk";
+
+const firstNameChunk = chunk("John");
+const lastNameChunk = chunk("Doe");
+const ageChunk = chunk(30);
+// Create a computed chunk that depends on multiple sources
+
+const fullInfoChunk = computed(
+  [firstNameChunk, lastNameChunk, ageChunk],
+  (firstName, lastName, age) => ({
+    fullName: `${firstName} ${lastName}`,
+    isAdult: age >= 18,
+  })
+);
+
+firstNameChunk.set("Ola");
+ageChunk.set(10);
+
+console.log(fullInfoChunk.get());
+// ✅ { fullName: "Jane Doe", isAdult: true }
+```
+
+Computed chunks are ideal for scenarios where state depends on multiple sources or needs complex calculations. They ensure your application remains performant and maintainable.
+
+## Advanced Examples
+
+Form Validation Example
+
+```typescript
+// With derive - single field validation
+const emailChunk = chunk("user@example.com");
+const isValidEmailChunk = emailChunk.derive((email) =>
+  /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+);
+
+// With computed - full form validation
+const usernameChunk = chunk("john");
+const emailChunk = chunk("user@example.com");
+const passwordChunk = chunk("pass123");
+const confirmPasswordChunk = chunk("pass123");
+
+const formValidationChunk = computed(
+  [usernameChunk, emailChunk, passwordChunk, confirmPasswordChunk],
+  (username, email, password, confirmPass) => ({
+    isUsernameValid: username.length >= 3,
+    isEmailValid: /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email),
+    isPasswordValid: password.length >= 6,
+    doPasswordsMatch: password === confirmPass,
+    isFormValid:
+      username.length >= 3 &&
+      /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) &&
+      password.length >= 6 &&
+      password === confirmPass,
+  })
+);
+
+console.log(formValidationChunk.get());
+```
+
+Data Filtering Example
+
+```typescript
+// With derive - simple filter
+const postsChunk = chunk([
+  { id: 1, title: "Post 1", published: true },
+  { id: 2, title: "Post 2", published: false },
+]);
+
+const publishedPostsChunk = postsChunk.derive((posts) =>
+  posts.filter((post) => post.published)
+);
+
+// With computed - complex filtering with multiple conditions
+const postsChunk = chunk([
+  { id: 1, title: "Post 1", category: "tech", date: "2024-01-01" },
+]);
+const categoryFilterChunk = chunk("tech");
+const dateRangeChunk = chunk({ start: "2024-01-01", end: "2024-02-01" });
+const searchTermChunk = chunk("");
+
+const filteredPostsChunk = computed(
+  [postsChunk, categoryFilterChunk, dateRangeChunk, searchTermChunk],
+  (posts, category, dateRange, searchTerm) =>
+    posts.filter(
+      (post) =>
+        (!category || post.category === category) &&
+        (!dateRange ||
+          (post.date >= dateRange.start && post.date <= dateRange.end)) &&
+        (!searchTerm ||
+          post.title.toLowerCase().includes(searchTerm.toLowerCase()))
+    )
+);
+```
+
 ## State Persistence
 
 Stunk provides a persistence middleware to automatically save state changes to storage (localStorage, sessionStorage, etc).
@@ -189,6 +293,16 @@ counterChunk.set({ count: 1 });
 
 ## Async State
 
+Async Chunks in Stunk are designed to manage asynchronous state seamlessly. They handle loading, error, and data states automatically, making it easier to work with APIs and other asynchronous operations.
+
+Key Features
+
+- Built-in Loading and Error States: Automatically manages loading, error, and data properties.
+
+- Type-Safe: Fully typed in TypeScript, ensuring safe data handling.
+
+- Optimistic Updates: Update state optimistically and revert if needed.
+
 ```typescript
 import { asyncChunk } from "stunk";
 
@@ -198,6 +312,7 @@ type User = {
   email: string;
 };
 
+// Create an Async Chunk
 const user = asyncChunk<User>(async () => {
   const response = await fetch("/api/user");
   return response.json(); // TypeScript expects this to return User;
@@ -212,14 +327,24 @@ user.subscribe((state) => {
   }
 });
 
+// Subscribe to state changes
 user.subscribe(({ loading, error, data }) => {
   if (loading) console.log("Loading...");
   if (error) console.log("Error:", error);
   if (data) console.log("User:", data);
 });
+```
 
+**Reloading Data**
+
+```typescript
 // Reload data
 await user.reload();
+```
+
+**Optimistic Updates**
+
+```typescript
 
 // Optimistic update
 user.mutate((currentData) => ({

package/dist/core/computed.js

@@ -1,61 +1,40 @@
-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;
+export function computed(dependencies, computeFn) {
+    let isDirty = false; // Initialized to false
+    let cachedValue = computeFn(...dependencies.map(d => d.get()));
+    const recalculate = () => {
+        const values = dependencies.map(dep => dep.get());
+        cachedValue = computeFn(...values);
+        isDirty = false; // Reset to false after recomputation
+    };
+    const computedChunk = chunk(cachedValue);
+    const originalGet = computedChunk.get;
+    computedChunk.get = () => {
+        if (isDirty) {
+            recalculate();
+            computedChunk.set(cachedValue); // Update the chunk value after recomputation
         }
-        return cachedValue;
+        return cachedValue; // Return the cached value directly
     };
-    // Create the computed chunk
-    const computedChunk = chunk(computeValue());
-    // Subscribe to all detected dependencies
-    dependencies.forEach(dep => {
+    const lastValues = dependencies.map(dep => dep.get());
+    dependencies.forEach((dep, index) => {
         dep.subscribe(() => {
-            isDirty = true;
-            computedChunk.set(computeValue());
+            const newValue = dep.get();
+            if (newValue !== lastValues[index] && !isDirty) {
+                lastValues[index] = newValue;
+                isDirty = true;
+            }
         });
     });
     return {
         ...computedChunk,
-        get: () => {
+        isDirty: () => isDirty,
+        recompute: () => {
             if (isDirty) {
-                return computeValue();
+                recalculate();
+                computedChunk.set(cachedValue); // Update the chunk value after manual recomputation
             }
-            return cachedValue;
         },
-        // Prevent direct setting
         set: () => {
             throw new Error('Cannot directly set a computed value');
         }

package/dist/core/core.js

@@ -15,28 +15,6 @@ export function batch(callback) {
         }
     }
 }
-export function select(sourceChunk, selector) {
-    const initialValue = selector(sourceChunk.get());
-    const selectedChunk = chunk(initialValue);
-    let previousSelected = initialValue;
-    // Subscribe to source changes with equality checking
-    sourceChunk.subscribe((newValue) => {
-        const newSelected = selector(newValue);
-        // Only update if the selected value actually changed
-        if (!Object.is(newSelected, previousSelected)) {
-            previousSelected = newSelected;
-            selectedChunk.set(newSelected);
-        }
-    });
-    // Return read-only version of the chunk
-    return {
-        ...selectedChunk,
-        // Prevent setting values directly on the selector
-        set: () => {
-            throw new Error('Cannot set values directly on a selector. Modify the source chunk instead.');
-        }
-    };
-}
 export function chunk(initialValue, middleware = []) {
     if (initialValue === undefined || initialValue === null) {
         throw new Error("Initial value cannot be undefined or null.");

package/dist/core/selector.js

@@ -0,0 +1,23 @@
+import { chunk } from "./core";
+export function select(sourceChunk, selector) {
+    const initialValue = selector(sourceChunk.get());
+    const selectedChunk = chunk(initialValue);
+    let previousSelected = initialValue;
+    // Subscribe to source changes with equality checking
+    sourceChunk.subscribe((newValue) => {
+        const newSelected = selector(newValue);
+        // Only update if the selected value actually changed
+        if (!Object.is(newSelected, previousSelected)) {
+            previousSelected = newSelected;
+            selectedChunk.set(newSelected);
+        }
+    });
+    // Return read-only version of the chunk
+    return {
+        ...selectedChunk,
+        // Prevent setting values directly on the selector
+        set: () => {
+            throw new Error('Cannot set values directly on a selector. Modify the source chunk instead.');
+        }
+    };
+}

package/dist/index.js

@@ -1,4 +1,6 @@
-export { chunk, batch, select } from './core/core';
+export { chunk, batch } from './core/core';
 export { asyncChunk } from './core/asyncChunk';
 export { computed } from './core/computed';
+export { select } from './core/selector';
+export { combineAsyncChunks } from './utils';
 export * from "./middleware";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stunk",
-  "version": "1.0.1",
-  "description": "Stunk - A framework-agnostic state management library implementing the Atomic State technique, utilizing chunk-based units for efficient state management.",
+  "version": "1.2.3",
+  "description": "Stunk - A lightweight, framework-agnostic state management library using chunk-based units for efficient state updates.",
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",
   "scripts": {
@@ -20,7 +20,10 @@
     "react",
     "React state management",
     "Vue state management",
-    "management"
+    "management",
+    "TypeScript state management",
+    "reactive state library",
+    "frontend state management"
   ],
   "author": "AbdulAzeez",
   "license": "MIT",

package/src/core/computed.ts

@@ -1,75 +1,65 @@
-import { isChunk } from "../utils";
-import { chunk, Chunk } from "./core";
+import { Chunk, chunk, batch } from "./core";
 
-export function computed<T>(computeFn: () => T): Chunk<T> {
-  // Track the currently executing computed function
-  let currentComputation: (() => T) | null = null;
+// Helper type to extract the value type from a Chunk
+type ChunkValue<T> = T extends Chunk<infer U> ? U : never;
 
-  // Set to track dependencies
-  const dependencies = new Set<Chunk<any>>();
+// Helper type to transform an array of Chunks into an array of their value types
+type DependencyValues<T extends Chunk<any>[]> = {
+  [K in keyof T]: T[K] extends Chunk<any> ? ChunkValue<T[K]> : never;
+};
 
-  const trackingProxy = new Proxy({}, {
-    get(_, prop) {
-      if (currentComputation && prop === 'value') {
-        const chunkValue = (this as any)[prop];
-        if (isChunk(chunkValue)) {
-          dependencies.add(chunkValue);
-          return chunkValue.get();
-        }
-      }
-      return (this as any)[prop];
-    },
-  });
-
-  // Initial computation
-  let cachedValue: T;
-  let isDirty = true;
-
-  const computeValue = () => {
-    if (!isDirty) return cachedValue
+export interface Computed<T> extends Chunk<T> {
+  isDirty: () => boolean;
+  recompute: () => void;
+}
 
-    // Reset dependencies
-    dependencies.clear();
+export function computed<TDeps extends Chunk<any>[], TResult>(
+  dependencies: [...TDeps],
+  computeFn: (...args: DependencyValues<TDeps>) => TResult
+): Computed<TResult> {
+  let isDirty = false; // Initialized to false
+  let cachedValue: TResult = computeFn(...dependencies.map(d => d.get()) as DependencyValues<TDeps>);
 
-    // Set the current computation context
-    currentComputation = computeFn;
+  const recalculate = () => {
+    const values = dependencies.map(dep => dep.get()) as DependencyValues<TDeps>;
+    cachedValue = computeFn(...values);
+    isDirty = false; // Reset to false after recomputation
+  };
 
+  const computedChunk = chunk(cachedValue);
 
-    try {
-      // Compute with tracking
-      cachedValue = computeFn.call(trackingProxy);
-      isDirty = false;
-    } finally {
-      // Clear the current computation context
-      currentComputation = null;
+  const originalGet = computedChunk.get;
+  computedChunk.get = () => {
+    if (isDirty) {
+      recalculate();
+      computedChunk.set(cachedValue); // Update the chunk value after recomputation
     }
-    return cachedValue;
-
-  }
+    return cachedValue; // Return the cached value directly
+  };
 
-  // Create the computed chunk
-  const computedChunk = chunk(computeValue());
+  const lastValues = dependencies.map(dep => dep.get());
 
-  // Subscribe to all detected dependencies
-  dependencies.forEach(dep => {
+  dependencies.forEach((dep, index) => {
     dep.subscribe(() => {
-      isDirty = true;
-      computedChunk.set(computeValue());
+      const newValue = dep.get();
+      if (newValue !== lastValues[index] && !isDirty) {
+        lastValues[index] = newValue;
+        isDirty = true;
+      }
     });
   });
 
   return {
     ...computedChunk,
-    get: () => {
+    isDirty: () => isDirty,
+    recompute: () => {
       if (isDirty) {
-        return computeValue();
+        recalculate();
+        computedChunk.set(cachedValue); // Update the chunk value after manual recomputation
       }
-      return cachedValue;
     },
-    // Prevent direct setting
     set: () => {
       throw new Error('Cannot directly set a computed value');
     }
   };
-
 }

package/src/core/core.ts

@@ -37,32 +37,6 @@ export function batch(callback: () => void) {
   }
 }
 
-export function select<T, S>(sourceChunk: Chunk<T>, selector: (value: T) => S): Chunk<S> {
-  const initialValue = selector(sourceChunk.get());
-  const selectedChunk = chunk(initialValue);
-  let previousSelected = initialValue;
-
-  // Subscribe to source changes with equality checking
-  sourceChunk.subscribe((newValue) => {
-    const newSelected = selector(newValue);
-
-    // Only update if the selected value actually changed
-    if (!Object.is(newSelected, previousSelected)) {
-      previousSelected = newSelected;
-      selectedChunk.set(newSelected);
-    }
-  });
-
-  // Return read-only version of the chunk
-  return {
-    ...selectedChunk,
-    // Prevent setting values directly on the selector
-    set: () => {
-      throw new Error('Cannot set values directly on a selector. Modify the source chunk instead.');
-    }
-  };
-}
-
 export function chunk<T>(initialValue: T, middleware: Middleware<T>[] = []): Chunk<T> {
   if (initialValue === undefined || initialValue === null) {
     throw new Error("Initial value cannot be undefined or null.");

package/src/core/selector.ts

@@ -0,0 +1,27 @@
+import { chunk, Chunk } from "./core";
+
+export function select<T, S>(sourceChunk: Chunk<T>, selector: (value: T) => S): Chunk<S> {
+  const initialValue = selector(sourceChunk.get());
+  const selectedChunk = chunk(initialValue);
+  let previousSelected = initialValue;
+
+  // Subscribe to source changes with equality checking
+  sourceChunk.subscribe((newValue) => {
+    const newSelected = selector(newValue);
+
+    // Only update if the selected value actually changed
+    if (!Object.is(newSelected, previousSelected)) {
+      previousSelected = newSelected;
+      selectedChunk.set(newSelected);
+    }
+  });
+
+  // Return read-only version of the chunk
+  return {
+    ...selectedChunk,
+    // Prevent setting values directly on the selector
+    set: () => {
+      throw new Error('Cannot set values directly on a selector. Modify the source chunk instead.');
+    }
+  };
+}

package/src/index.ts

@@ -1,6 +1,10 @@
-export { chunk, batch, select } from './core/core';
-export { asyncChunk } from './core/asyncChunk'
-export { computed } from './core/computed'
+export { chunk, batch } from './core/core';
+export { asyncChunk } from './core/asyncChunk';
+export { computed } from './core/computed';
+export { select } from './core/selector'
+
+export { combineAsyncChunks } from './utils';
+
 export type { Chunk, Middleware } from './core/core';
 
 export * from "./middleware";

package/tests/computed.test.ts

@@ -0,0 +1,93 @@
+import { chunk } from '../src/core/core';
+import { computed } from '../src/core/computed';
+
+describe('computed', () => {
+  it('should compute the value based on dependencies', () => {
+    const num1 = chunk(2);
+    const num2 = chunk(3);
+
+    const sum = computed([num1, num2], (a, b) => a + b);
+
+    expect(sum.get()).toBe(5);
+  });
+
+  it('should recompute when a dependency changes', () => {
+    const num1 = chunk(4);
+    const num2 = chunk(5);
+
+    const product = computed([num1, num2], (a, b) => a * b);
+
+    expect(product.get()).toBe(20);
+
+    num1.set(10);
+
+    // Trigger recomputation
+    expect(product.get()).toBe(50);
+  });
+
+  it('should cache the computed value until a dependency changes', () => {
+    const num1 = chunk(1);
+    const num2 = chunk(2);
+
+    const sum = computed([num1, num2], (a, b) => a + b);
+
+    const initialValue = sum.get();
+    expect(initialValue).toBe(3);
+
+    num1.set(1); // Setting to the same value, should not trigger recompute
+    const cachedValue = sum.get();
+    expect(cachedValue).toBe(3); // Cached value should be returned
+  });
+
+  it('should mark as dirty when a dependency changes', () => {
+    const num1 = chunk(7);
+    const num2 = chunk(8);
+
+    const diff = computed([num1, num2], (a, b) => b - a);
+
+    expect(diff.isDirty()).toBe(false);
+
+    num2.set(10);
+
+    expect(diff.isDirty()).toBe(true);
+  });
+
+  it('should throw error when attempting to set computed value', () => {
+    const num1 = chunk(10);
+    const num2 = chunk(20);
+
+    const sum = computed([num1, num2], (a, b) => a + b);
+
+    expect(() => sum.set(100)).toThrow('Cannot directly set a computed value');
+  });
+
+  it('should manually recompute the value', () => {
+    const num1 = chunk(1);
+    const num2 = chunk(2);
+
+    const sum = computed([num1, num2], (a, b) => a + b);
+
+    expect(sum.get()).toBe(3);
+
+    num1.set(4);
+    expect(sum.isDirty()).toBe(true);
+
+    sum.recompute(); // Manually recompute
+    expect(sum.get()).toBe(6);
+    expect(sum.isDirty()).toBe(false);
+  });
+
+  it('should support multiple dependencies', () => {
+    const a = chunk(2);
+    const b = chunk(3);
+    const c = chunk(4);
+
+    const result = computed([a, b, c], (x, y, z) => x * y + z);
+
+    expect(result.get()).toBe(10);
+
+    b.set(5);
+
+    expect(result.get()).toBe(14);
+  });
+});

package/tests/history.test.ts

@@ -1,4 +1,4 @@
-import { batch, chunk } from "../src/core/core";
+import { chunk } from "../src/core/core";
 import { withHistory } from "../src/middleware/history";
 
 

package/tests/select-chunk.test.ts

@@ -1,4 +1,5 @@
-import { chunk, select } from '../src/core/core';
+import { chunk } from '../src/core/core';
+import { select } from '../src/core/selector'
 
 describe('select', () => {
   it('should create a selector that initially returns the correct value', () => {