stunk 0.3.0 → 0.7.0

package/README.md

@@ -1,18 +1,27 @@
 # Stunk
 
-**Stunk** is a framework-agnostic state management library implementing the **Atomic State technique**, utilizing chunk-based units for efficient state management. Whether you're building applications in plain JavaScript/TypeScript, React, Vue, Svelte, or any other modern framework, **Stunk** can seamlessly fit into your project.
+**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.
 
-## Features
+## 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.
 
-- **Framework-agnostic**: Use it in any JavaScript/TypeScript application, regardless of framework.
-- **Atomic State technique**: Implements state management using atomic units (chunks) that are discrete and easily manageable.
-- **TypeScript support**: Fully typed for better developer experience and type safety.
-- **Easy to use**: Simple API for creating, getting, and updating state.
+### Why Stunk
+
+- lightweight, framework-agnostic state management.
+- granular control over state updates and subscriptions.
+- modular and composable state architecture.
+
+---
 
 ## Installation
 
@@ -21,3 +30,218 @@ You can install **Stunk** from NPM:
 ```bash
 npm install stunk
 ```
+
+## 1 Features
+
+### 1.0 **Chunks**
+
+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
+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
+
+```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.
+
+### Usage
+
+```ts
+const count = chunk(5);
+
+// Create a derived chunk that doubles the count
+const doubleCount = count.derive((value) => value * 2);
+
+count.subscribe((newValue) => console.log("Count:", newValue));
+doubleCount.subscribe((newValue) => console.log("Double count:", newValue));
+
+count.set(10);
+// Will log:
+// "Count: 10"
+// "Double count: 20"
+```
+
+### 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.
+
+### Usage
+
+```ts
+import { chunk, batch } from "stunk";
+
+const firstName = chunk("John");
+const lastName = chunk("Doe");
+const age = chunk(25);
+
+// 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
+
+// Nested batches are also supported
+batch(() => {
+  firstName.set("Jane");
+  batch(() => {
+    lastName.set("Smith");
+    age.set(26);
+  });
+});
+```
+
+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
+
+The batch function ensures that:
+
+- 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)
+
+### 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.
+
+A middleware is a function with the following structure:
+
+```ts
+export type Middleware<T> = (value: T, next: (newValue: T) => void) => void;
+```
+
+- 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.
+
+### Usage
+
+```ts
+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 []
+
+// 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!"
+```
+
+### 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:
+
+- Keep state changes focused and efficient
+- Update only the parts of your app that need to change
+- Easily manage and subscribe to state changes

package/dist/core/core.js

@@ -0,0 +1,128 @@
+let batchDepth = 0;
+const batchQueue = new Set();
+export function batch(callback) {
+    batchDepth++;
+    try {
+        callback();
+    }
+    finally {
+        batchDepth--;
+        if (batchDepth === 0) {
+            // Execute all queued updates
+            batchQueue.forEach(update => update());
+            batchQueue.clear();
+        }
+    }
+}
+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.");
+    }
+    let value = initialValue;
+    const subscribers = new Set();
+    let isDirty = false;
+    const get = () => value;
+    const notifySubscribers = () => {
+        if (batchDepth > 0) {
+            if (!isDirty) {
+                isDirty = true;
+                batchQueue.add(() => {
+                    if (isDirty) {
+                        subscribers.forEach((subscriber) => subscriber(value));
+                        isDirty = false;
+                    }
+                });
+            }
+        }
+        else {
+            subscribers.forEach((subscriber) => subscriber(value));
+        }
+    };
+    const set = (newValue) => {
+        if (newValue === null || newValue === undefined) {
+            throw new Error("Value cannot be null or undefined.");
+        }
+        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++;
+        }
+        if (currentValue !== value) {
+            value = currentValue;
+            notifySubscribers();
+        }
+    };
+    const subscribe = (callback) => {
+        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));
+    };
+    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;
+    };
+    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 newDerivedValue = fn(value);
+            derivedChunk.set(newDerivedValue);
+        });
+        return derivedChunk;
+    };
+    return { get, set, subscribe, derive, reset, destroy };
+}

package/dist/index.js

@@ -1,2 +1,2 @@
-// src/index.ts
-export { createChunk } from './core';
+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/dist/middleware/logger.js

@@ -0,0 +1,4 @@
+export const logger = (value, next) => {
+    console.log("Setting value:", value);
+    next(value);
+};

package/dist/middleware/validator.js

@@ -0,0 +1,6 @@
+export const nonNegativeValidator = (value, next) => {
+    if (value < 0) {
+        throw new Error("Value must be non-negative!");
+    }
+    next(value); // If validation passes, proceed with the update
+};

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "stunk",
-  "version": "0.3.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",
   "scripts": {
     "build": "tsc",
-    "test": "jest",
+    "test": "jest --runInBand",
     "prepare": "npm run build"
   },
   "keywords": [
     "state-management",
     "atomic-state",
     "framework-agnostic",
-    "dàrá"
+    "stunk",
+    "state",
+    "chunk"
   ],
   "author": "AbdulAzeez",
   "license": "MIT",

package/src/core/core.ts

@@ -0,0 +1,170 @@
+export type Subscriber<T> = (newValue: T) => void;
+export type Middleware<T> = (value: T, next: (newValue: T) => void) => void;
+
+export interface Chunk<T> {
+  /** Get the current value of the chunk. */
+  get: () => T;
+  /** Set a new value for the chunk. */
+  set: (value: T) => void;
+  /** Subscribe to changes in the chunk. Returns an unsubscribe function. */
+  subscribe: (callback: Subscriber<T>) => () => void;
+  /** Create a derived chunk based on this chunk's value. */
+  derive: <D>(fn: (value: T) => D) => Chunk<D>;
+  /** Reset the chunk to its initial value. */
+  reset: () => void;
+  /** Destroy the chunk and all its subscribers. */
+  destroy: () => void;
+}
+
+let batchDepth = 0;
+const batchQueue = new Set<() => void>();
+
+export function batch(callback: () => void) {
+  batchDepth++;
+  try {
+    callback();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) {
+      // Execute all queued updates
+      batchQueue.forEach(update => update());
+      batchQueue.clear();
+    }
+  }
+}
+
+
+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.");
+  }
+
+  let value = initialValue;
+  const subscribers = new Set<Subscriber<T>>();
+  let isDirty = false;
+
+  const get = () => value;
+
+  const notifySubscribers = () => {
+    if (batchDepth > 0) {
+      if (!isDirty) {
+        isDirty = true;
+        batchQueue.add(() => {
+          if (isDirty) {
+            subscribers.forEach((subscriber) => subscriber(value));
+            isDirty = false;
+          }
+        });
+      }
+    } else {
+      subscribers.forEach((subscriber) => subscriber(value));
+    }
+  }
+
+  const set = (newValue: T) => {
+    if (newValue === null || newValue === undefined) {
+      throw new Error("Value cannot be null or undefined.");
+    }
+
+    let currentValue = newValue;
+    let index = 0;
+
+    while (index < middleware.length) {
+      const currentMiddleware = middleware[index];
+      let nextCalled = false;
+      let nextValue: T | null = 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++;
+    }
+
+    if (currentValue !== value) {
+      value = currentValue;
+      notifySubscribers();
+    }
+  };
+
+  const subscribe = (callback: Subscriber<T>) => {
+    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));
+  };
+
+  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;
+  };
+
+
+  const derive = <D>(fn: (value: T) => D) => {
+    if (typeof fn !== "function") {
+      throw new Error("Derive function must be a function.");
+    }
+    const derivedValue = fn(value);
+    const derivedChunk = chunk(derivedValue);
+
+    subscribe(() => {
+      const newDerivedValue = fn(value);
+      derivedChunk.set(newDerivedValue);
+    });
+
+    return derivedChunk;
+  };
+
+  return { get, set, subscribe, derive, reset, destroy };
+}

package/src/index.ts

@@ -1,4 +1,4 @@
-// src/index.ts
+export { chunk } from './core/core';
+export type { Chunk } from './core/core';
 
-export { createChunk } from './core';
-export type { Chunk } from './core';
+export * from "./middleware";