stunk 0.6.0 → 0.7.0

package/README.md

@@ -70,6 +70,25 @@ 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
+
+```ts
+const count = chunk(0);
+const callback = (newValue: number) => console.log("Updated value:", newValue);
+
+const unsubscribe = count.subscribe(callback);
+
+count.set(10); // Will log: "Updated value: 10"
+
+unsubscribe(); // Unsubscribe
+
+count.set(20); // Nothing will happen now, because you unsubscribed
+```
+
 ### 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.
@@ -91,26 +110,7 @@ count.set(10);
 // "Double count: 20"
 ```
 
-### 1.3. **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
-
-```ts
-const count = chunk(0);
-const callback = (newValue: number) => console.log("Updated value:", newValue);
-
-const unsubscribe = count.subscribe(callback);
-
-count.set(10); // Will log: "Updated value: 10"
-
-unsubscribe(); // Unsubscribe
-
-count.set(20); // Nothing will happen now, because you unsubscribed
-```
-
-### 1.4. **Batch Updates**
+### 1.3. **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.
 
@@ -166,7 +166,7 @@ The batch function ensures that:
 - Nested batches are handled correctly
 - Updates are processed even if an error occurs (using try/finally)
 
-### 1.5. **Middleware**
+### 1.4. **Middleware**
 
 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.
 
@@ -194,6 +194,50 @@ age.set(30); // Logs: "Setting value: 30"
 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
+
+```ts
+import { chunk } from "stunk";
+import { withHistory } from "stunk/middleware"; // Import the history middleware
+
+const counter = withHistory(chunk(0));
+
+counter.set(10);
+counter.set(20);
+
+console.log(counter.get()); // 20
+
+counter.undo(); // Go back one step
+console.log(counter.get()); // 10
+
+counter.redo(); // Go forward one step
+console.log(counter.get()); // 20
+```
+
+**Available Methods**
+
+| 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. |
+
+**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.
+```
+
+This prevents the history from growing indefinitely and ensures efficient memory usage.
+
 ## 2. **Atomic State Technique**
 
 The **Atomic State** technique is all about breaking down your state into small, manageable chunks. This allows you to:

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

@@ -14,6 +14,28 @@ 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/index.js

@@ -1,3 +1,2 @@
-export { chunk } from './core';
-export { logger } from "./middleware/logger";
-export { nonNegativeValidator } from "./middleware/validator";
+export { chunk } from './core/core';
+export * from "./middleware";

package/dist/middleware/history.js

@@ -0,0 +1,58 @@
+export function withHistory(baseChunk, options = {}) {
+    const { maxHistory = 100 } = options;
+    const history = [baseChunk.get()];
+    let currentIndex = 0;
+    let isHistoryAction = false;
+    const historyChunk = {
+        ...baseChunk,
+        set: (newValue) => {
+            if (isHistoryAction) {
+                baseChunk.set(newValue);
+                return;
+            }
+            // Remove any future history when setting a new value
+            history.splice(currentIndex + 1);
+            history.push(newValue);
+            // Limit history size
+            if (history.length > maxHistory) {
+                console.warn("History limit reached. Removing oldest entries.");
+                const removeCount = history.length - maxHistory;
+                history.splice(0, removeCount);
+                currentIndex = Math.max(0, currentIndex - removeCount);
+            }
+            currentIndex = history.length - 1;
+            baseChunk.set(newValue);
+        },
+        undo: () => {
+            if (!historyChunk.canUndo())
+                return;
+            isHistoryAction = true;
+            currentIndex--;
+            historyChunk.set(history[currentIndex]);
+            isHistoryAction = false;
+        },
+        redo: () => {
+            if (!historyChunk.canRedo())
+                return;
+            isHistoryAction = true;
+            currentIndex++;
+            historyChunk.set(history[currentIndex]);
+            isHistoryAction = false;
+        },
+        canUndo: () => currentIndex > 0,
+        canRedo: () => currentIndex < history.length - 1,
+        getHistory: () => [...history],
+        clearHistory: () => {
+            const currentValue = baseChunk.get();
+            history.length = 0;
+            history.push(currentValue);
+            currentIndex = 0;
+        },
+        // Override destroy to clean up history
+        destroy: () => {
+            history.length = 0;
+            baseChunk.destroy();
+        }
+    };
+    return historyChunk;
+}

package/dist/middleware/index.js

@@ -0,0 +1,3 @@
+export { logger } from "./logger";
+export { nonNegativeValidator } from "./validator";
+export { withHistory } from "./history";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stunk",
-  "version": "0.6.0",
+  "version": "0.7.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",

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

@@ -34,6 +34,32 @@ 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/index.ts

@@ -1,5 +1,4 @@
-export { chunk } from './core';
-export type { Chunk } from './core';
+export { chunk } from './core/core';
+export type { Chunk } from './core/core';
 
-export { logger } from "./middleware/logger";
-export { nonNegativeValidator } from "./middleware/validator";
+export * from "./middleware";

package/src/middleware/history.ts

@@ -0,0 +1,86 @@
+import { Chunk } from "../core/core";
+
+export interface ChunkWithHistory<T> extends Chunk<T> {
+  undo: () => void;
+  redo: () => void;
+  canUndo: () => boolean;
+  canRedo: () => boolean;
+  getHistory: () => T[];
+  clearHistory: () => void;
+}
+
+export function withHistory<T>(
+  baseChunk: Chunk<T>,
+  options: { maxHistory?: number } = {}
+): ChunkWithHistory<T> {
+  const { maxHistory = 100 } = options;
+  const history: T[] = [baseChunk.get()];
+  let currentIndex = 0;
+  let isHistoryAction = false;
+
+  const historyChunk: ChunkWithHistory<T> = {
+    ...baseChunk,
+
+    set: (newValue: T) => {
+      if (isHistoryAction) {
+        baseChunk.set(newValue);
+        return;
+      }
+
+      // Remove any future history when setting a new value
+      history.splice(currentIndex + 1);
+      history.push(newValue);
+
+      // Limit history size
+      if (history.length > maxHistory) {
+        console.warn("History limit reached. Removing oldest entries.");
+        const removeCount = history.length - maxHistory;
+        history.splice(0, removeCount);
+        currentIndex = Math.max(0, currentIndex - removeCount);
+      }
+
+      currentIndex = history.length - 1;
+      baseChunk.set(newValue);
+    },
+
+    undo: () => {
+      if (!historyChunk.canUndo()) return;
+
+      isHistoryAction = true;
+      currentIndex--;
+      historyChunk.set(history[currentIndex]);
+      isHistoryAction = false;
+    },
+
+    redo: () => {
+      if (!historyChunk.canRedo()) return;
+
+      isHistoryAction = true;
+      currentIndex++;
+      historyChunk.set(history[currentIndex]);
+      isHistoryAction = false;
+    },
+
+    canUndo: () => currentIndex > 0,
+
+    canRedo: () => currentIndex < history.length - 1,
+
+    getHistory: () => [...history],
+
+    clearHistory: () => {
+      const currentValue = baseChunk.get();
+      history.length = 0;
+      history.push(currentValue);
+      currentIndex = 0;
+    },
+
+    // Override destroy to clean up history
+    destroy: () => {
+      history.length = 0;
+      baseChunk.destroy();
+    }
+  }
+
+  return historyChunk;
+
+}

package/src/middleware/index.ts

@@ -0,0 +1,3 @@
+export { logger } from "./logger";
+export { nonNegativeValidator } from "./validator";
+export { withHistory } from "./history";

package/src/middleware/logger.ts

@@ -1,4 +1,4 @@
-import { Middleware } from "../core";
+import { Middleware } from "../core/core";
 
 export const logger: Middleware<any> = (value, next) => {
   console.log("Setting value:", value);

package/src/middleware/validator.ts

@@ -1,4 +1,4 @@
-import { Middleware } from "../core";
+import { Middleware } from "../core/core";
 
 export const nonNegativeValidator: Middleware<number> = (value, next) => {
   if (value < 0) {

package/tests/batch-chunk.test.ts

@@ -1,4 +1,4 @@
-import { chunk, batch } from '../src/core';
+import { chunk, batch } from '../src/core/core';
 
 
 describe('Chunk batch updates', () => {

package/tests/chunk.test.ts

@@ -1,4 +1,4 @@
-import { chunk } from "../src/core";
+import { chunk } from "../src/core/core";
 
 test("Chunk should get and set values correctly", () => {
   const chunky = chunk<number>(0);

package/tests/history.test.ts

@@ -0,0 +1,99 @@
+import { batch, chunk } from "../src/core/core";
+import { withHistory } from "../src/middleware/history";
+
+
+describe('Chunk with History', () => {
+  it('should maintain history of changes', () => {
+    const baseChunk = chunk(0);
+    const historyChunk = withHistory(baseChunk);
+
+    historyChunk.set(1);
+    historyChunk.set(2);
+    historyChunk.set(3);
+
+    expect(historyChunk.getHistory()).toEqual([0, 1, 2, 3]);
+  });
+
+  it('should handle undo and redo operations', () => {
+    const baseChunk = chunk(0);
+    const historyChunk = withHistory(baseChunk);
+    const callback = jest.fn();
+
+    historyChunk.subscribe(callback);
+    callback.mockClear(); // Clear initial subscription call
+
+    historyChunk.set(1);
+    historyChunk.set(2);
+
+    expect(historyChunk.get()).toBe(2);
+
+    historyChunk.undo();
+    expect(historyChunk.get()).toBe(1);
+
+    historyChunk.undo();
+    expect(historyChunk.get()).toBe(0);
+
+    historyChunk.redo();
+    expect(historyChunk.get()).toBe(1);
+
+    historyChunk.redo();
+    expect(historyChunk.get()).toBe(2);
+
+    expect(callback).toHaveBeenCalledTimes(6); // 2 sets + 2 undos + 2 redos
+  });
+
+  it('should handle branching history', () => {
+    const baseChunk = chunk(0);
+    const historyChunk = withHistory(baseChunk);
+
+    historyChunk.set(1);
+    historyChunk.set(2);
+    historyChunk.undo();
+    historyChunk.set(3); // This should create a new branch
+
+    expect(historyChunk.getHistory()).toEqual([0, 1, 3]);
+    expect(historyChunk.get()).toBe(3);
+  });
+
+  it('should respect maxHistory limit', () => {
+    const baseChunk = chunk(0);
+    const historyChunk = withHistory(baseChunk, { maxHistory: 3 });
+
+    historyChunk.set(1);
+    historyChunk.set(2);
+    historyChunk.set(3);
+    historyChunk.set(4);
+
+    expect(historyChunk.getHistory()).toEqual([2, 3, 4]);
+  });
+
+  it('should handle canUndo and canRedo correctly', () => {
+    const baseChunk = chunk(0);
+    const historyChunk = withHistory(baseChunk);
+
+    expect(historyChunk.canUndo()).toBe(false);
+    expect(historyChunk.canRedo()).toBe(false);
+
+    historyChunk.set(1);
+    expect(historyChunk.canUndo()).toBe(true);
+    expect(historyChunk.canRedo()).toBe(false);
+
+    historyChunk.undo();
+    expect(historyChunk.canUndo()).toBe(false);
+    expect(historyChunk.canRedo()).toBe(true);
+  });
+
+  it('should clear history properly', () => {
+    const baseChunk = chunk(0);
+    const historyChunk = withHistory(baseChunk);
+
+    historyChunk.set(1);
+    historyChunk.set(2);
+
+    historyChunk.clearHistory();
+
+    expect(historyChunk.getHistory()).toEqual([2]);
+    expect(historyChunk.canUndo()).toBe(false);
+    expect(historyChunk.canRedo()).toBe(false);
+  });
+});

package/tests/middleware.test.ts

@@ -1,4 +1,4 @@
-import { chunk } from "../src/core";
+import { chunk } from "../src/core/core";
 import { logger } from "../src/middleware/logger";
 import { nonNegativeValidator } from "../src/middleware/validator";
 

package/tests/select-chunk.test.ts

@@ -0,0 +1,132 @@
+import { chunk, select } from '../src/core/core';
+
+describe('select', () => {
+  it('should create a selector that initially returns the correct value', () => {
+    const source = chunk({ name: 'John', age: 25 });
+    const nameSelector = select(source, user => user.name);
+
+    expect(nameSelector.get()).toBe('John');
+  });
+
+  it('should update when selected value changes', () => {
+    const source = chunk({ name: 'John', age: 25 });
+    const nameSelector = select(source, user => user.name);
+
+    source.set({ name: 'Jane', age: 25 });
+    expect(nameSelector.get()).toBe('Jane');
+  });
+
+  it('should not notify subscribers when non-selected values change', () => {
+    const source = chunk({ name: 'John', age: 25 });
+    const nameSelector = select(source, user => user.name);
+
+    const subscriber = jest.fn();
+    nameSelector.subscribe(subscriber);
+
+    // Reset the mock to ignore initial call
+    subscriber.mockReset();
+
+    // Update age only
+    source.set({ name: 'John', age: 26 });
+
+    expect(subscriber).not.toHaveBeenCalled();
+  });
+
+  it('should notify subscribers when selected value changes', () => {
+    const source = chunk({ name: 'John', age: 25 });
+    const nameSelector = select(source, user => user.name);
+
+    const subscriber = jest.fn();
+    nameSelector.subscribe(subscriber);
+
+    // Reset the mock to ignore initial call
+    subscriber.mockReset();
+
+    source.set({ name: 'Jane', age: 25 });
+
+    expect(subscriber).toHaveBeenCalledTimes(1);
+    expect(subscriber).toHaveBeenCalledWith('Jane');
+  });
+
+  it('should prevent direct modifications to selector', () => {
+    const source = chunk({ name: 'John', age: 25 });
+    const nameSelector = select(source, user => user.name);
+
+    expect(() => {
+      nameSelector.set('Jane');
+    }).toThrow('Cannot set values directly on a selector');
+  });
+
+  it('should work with complex selectors', () => {
+    const source = chunk({ user: { profile: { name: 'John' } } });
+    const nameSelector = select(source, state => state.user.profile.name);
+
+    expect(nameSelector.get()).toBe('John');
+
+    source.set({ user: { profile: { name: 'Jane' } } });
+    expect(nameSelector.get()).toBe('Jane');
+  });
+
+  it('should handle array selectors', () => {
+    const source = chunk({ items: [1, 2, 3] });
+    const firstItemSelector = select(source, state => state.items[0]);
+
+    expect(firstItemSelector.get()).toBe(1);
+
+    source.set({ items: [4, 2, 3] });
+    expect(firstItemSelector.get()).toBe(4);
+  });
+
+  it('should work with computed values', () => {
+    const source = chunk({ numbers: [1, 2, 3, 4, 5] });
+    const sumSelector = select(source, state =>
+      state.numbers.reduce((sum, num) => sum + num, 0)
+    );
+
+    expect(sumSelector.get()).toBe(15);
+
+    source.set({ numbers: [1, 2, 3] });
+    expect(sumSelector.get()).toBe(6);
+  });
+
+  it('should properly clean up subscriptions on destroy', () => {
+    const source = chunk({ name: 'John', age: 25 });
+    const nameSelector = select(source, user => user.name);
+
+    const subscriber = jest.fn();
+    const unsubscribe = nameSelector.subscribe(subscriber);
+
+    // Reset mock to ignore initial call
+    subscriber.mockReset();
+
+    unsubscribe();
+    nameSelector.destroy();
+    source.set({ name: 'Jane', age: 25 });
+
+    expect(subscriber).not.toHaveBeenCalled();
+  });
+
+  it('should work with multiple independent selectors', () => {
+    const source = chunk({ name: 'John', age: 25 });
+    const nameSelector = select(source, user => user.name);
+    const ageSelector = select(source, user => user.age);
+
+    const nameSubscriber = jest.fn();
+    const ageSubscriber = jest.fn();
+
+    nameSelector.subscribe(nameSubscriber);
+    ageSelector.subscribe(ageSubscriber);
+
+    // Reset mocks to ignore initial calls
+    nameSubscriber.mockReset();
+    ageSubscriber.mockReset();
+
+    source.set({ name: 'John', age: 26 });
+    expect(nameSubscriber).not.toHaveBeenCalled();
+    expect(ageSubscriber).toHaveBeenCalledWith(26);
+
+    source.set({ name: 'Jane', age: 26 });
+    expect(nameSubscriber).toHaveBeenCalledWith('Jane');
+    expect(ageSubscriber).toHaveBeenCalledTimes(1); // Still from previous update
+  });
+});