stunk 1.2.3 → 1.2.5

package/README.md

@@ -73,30 +73,6 @@ count.set(10);
 // "Double count: 20"
 ```
 
-## Batch 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(() => {
-  nameChunk.set("AbdulAzeez");
-  ageChunk.set(31);
-}); // Only one notification will be sent to subscribers
-
-// Nested batches are also supported
-batch(() => {
-  firstName.set("Olanrewaju");
-  batch(() => {
-    age.set(29);
-  });
-}); // Only one notification will be sent to subscribers
-```
-
 ## State Selection
 
 Efficiently access and react to specific state parts:
@@ -120,57 +96,30 @@ nameChunk.subscribe((name) => console.log("Name changed:", name));
 nameChunk.set("Olamide"); // ❌ this will throw an error, because it is a readonly.
 ```
 
-## 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.
-
-```typescript
-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!"
-```
+## Batch Updates
 
-## Time Travel (Middleware)
+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 } from "stunk";
-import { withHistory } from "stunk/midddleware";
-
-const counterChunk = withHistory(chunk(0));
-
-counterChunk.set(1);
-counterChunk.set(2);
-
-counterChunk.undo(); // Goes back to 1
-counterChunk.undo(); // Goes back to 0
-
-counterChunk.redo(); // Goes forward to 1
-
-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.
-
-counterChunk.getHistory(); // Returns an array of all the values in the history.
+import { chunk, batch } from "stunk";
 
-counterChunk.clearHistory(); // Clears the history, keeping only the current value.
-```
+const nameChunk = chunk("Olamide");
+const ageChunk = chunk(30);
 
-**Example: Limiting History Size (Optional)**
-You can specify a max history size to prevent excessive memory usage.
+batch(() => {
+  nameChunk.set("AbdulAzeez");
+  ageChunk.set(31);
+}); // Only one notification will be sent to subscribers
 
-```ts
-const counter = withHistory(chunk(0), { maxHistory: 5 });
-// Only keeps the last 5 changes -- default is 100.
+// Nested batches are also supported
+batch(() => {
+  firstName.set("Olanrewaju");
+  batch(() => {
+    age.set(29);
+  });
+}); // Only one notification will be sent to subscribers
 ```
 
-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.
@@ -200,7 +149,7 @@ firstNameChunk.set("Ola");
 ageChunk.set(10);
 
 console.log(fullInfoChunk.get());
-// ✅ { fullName: "Jane Doe", isAdult: true }
+// ✅ { fullName: "Ola 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.
@@ -275,7 +224,61 @@ const filteredPostsChunk = computed(
 );
 ```
 
-## State Persistence
+## 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.
+
+```typescript
+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!"
+```
+
+## Time Travel (Middleware)
+
+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.
+
+```typescript
+import { chunk } from "stunk";
+import { withHistory } from "stunk/midddleware";
+
+const counterChunk = withHistory(chunk(0));
+
+counterChunk.set(1);
+counterChunk.set(2);
+
+counterChunk.undo(); // Goes back to 1
+counterChunk.undo(); // Goes back to 0
+
+counterChunk.redo(); // Goes forward to 1
+
+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.
+
+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.
+```
+
+This prevents the history from growing indefinitely and ensures efficient memory usage.
+
+
+## State Persistence (Middleware)
 
 Stunk provides a persistence middleware to automatically save state changes to storage (localStorage, sessionStorage, etc).
 
@@ -291,6 +294,27 @@ const counterChunk = withPersistence(chunk({ count: 0 }), {
 counterChunk.set({ count: 1 });
 ```
 
+Using Different Storage
+
+```typescript
+// Use sessionStorage instead of localStorage
+const sessionStorageChunk = withPersistence(baseChunk, {
+  key: "counter",
+  storage: sessionStorage,
+});
+```
+
+Custom Serialization
+
+```typescript
+// Add custom serialization/deserialization
+const encryptedChunk = withPersistence(baseChunk, {
+  key: "encrypted-data",
+  serialize: (value) => encrypt(JSON.stringify(value)),
+  deserialize: (value) => JSON.parse(decrypt(value)),
+});
+```
+
 ## 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.

package/dist/utils.js

@@ -12,6 +12,18 @@ export function isChunk(value) {
         typeof value.reset === 'function' &&
         typeof value.destroy === 'function';
 }
+export function once(fn) {
+    let called = false;
+    let result;
+    return () => {
+        if (!called) {
+            result = fn();
+            called = true;
+        }
+        return result;
+    };
+}
+;
 export function combineAsyncChunks(chunks) {
     // Create initial state with proper typing
     const initialData = Object.keys(chunks).reduce((acc, key) => {

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "stunk",
-  "version": "1.2.3",
-  "description": "Stunk - A lightweight, framework-agnostic state management library using chunk-based units for efficient state updates.",
+  "version": "1.2.5",
+  "description": "Stunk is a lightweight, framework-agnostic state management library for JavaScript and TypeScript. It uses chunk-based state units for efficient updates, reactivity, and performance optimization in React, Vue, Svelte, and Vanilla JS/TS applications.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/I-am-abdulazeez/stunk"
+  },
+  "homepage": "https://github.com/I-am-abdulazeez/stunk#readme",
+  "bugs": {
+    "url": "https://github.com/I-am-abdulazeez/stunk/issues"
+  },
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",
   "scripts": {
@@ -13,19 +21,33 @@
   "keywords": [
     "state-management",
     "atomic-state",
+    "chunk-based state",
     "framework-agnostic",
-    "stunk",
-    "state",
-    "chunk",
-    "react",
+    "reactive state library",
+    "frontend state management",
+    "JavaScript state management",
+    "TypeScript state management",
     "React state management",
     "Vue state management",
-    "management",
-    "TypeScript state management",
-    "reactive state library",
-    "frontend state management"
+    "Svelte state management",
+    "recoil alternative",
+    "jotai alternative",
+    "zustand alternative",
+    "lightweight state management",
+    "state container",
+    "reusable state",
+    "efficient state updates",
+    "performance optimization",
+    "stunk",
+    "chunk"
   ],
   "author": "AbdulAzeez",
+  "contributors": [
+    {
+      "name": "AbdulAzeez",
+      "url": "https://github.com/I-am-abdulazeez"
+    }
+  ],
   "license": "MIT",
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/utils.ts

@@ -18,6 +18,18 @@ export function isChunk<T>(value: any): value is Chunk<T> {
     typeof value.destroy === 'function';
 }
 
+export function once<T>(fn: () => T): () => T {
+  let called = false;
+  let result: T;
+  return () => {
+    if (!called) {
+      result = fn();
+      called = true;
+    }
+    return result;
+  };
+};
+
 export function combineAsyncChunks<T extends Record<string, AsyncChunk<any>>>(
   chunks: T
 ): Chunk<{