@quanta-lib/q-state 1.0.1

package/README.md

@@ -0,0 +1,167 @@
+# Q-State
+
+A lightweight React state management library using `useSyncExternalStore` with optional localStorage caching and value transformation.
+
+## Installation
+
+```bash
+npm install @quanta-lib/q-state
+
+## Features
+
+- **Type-safe state management** - Full TypeScript support with generic types
+- **useSyncExternalStore** - Uses React's built-in concurrent-safe subscription mechanism
+- **Value transformation** - Transform values during updates with custom transformer functions
+- **LocalStorage caching** - Persist state to localStorage with optional caching
+- **Lightweight** - Minimal dependencies, no context providers needed
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { Q_StateEngine } from "@q-state/core"
+
+const qstate = new Q_StateEngine({
+  count: 0,
+  name: 'Amarix'
+})
+
+export function App() {
+  const [count] = qstate.useQuantaState('count')
+  const [name] = qstate.useQuantaState('name')
+
+  return (
+    <>
+      <h1>Counter App</h1>
+      <p>Name: {name}</p>
+      <p>Count: {count}</p>
+      <button onClick={() => qstate.updateValue('count', (prev) => prev + 1)}>
+        Increment
+      </button>
+    </>
+  )
+}
+```
+
+### With Value Transformer
+
+Transform values automatically when updating state:
+
+```typescript
+const qstate = new Q_StateEngine({
+  name: 'Amarix'
+}, {
+  // Transformer function runs after updateValue
+  name: (raw) => {
+    console.log(raw) // Logs the new value
+    return raw.toUpperCase() // Transform to uppercase
+  }
+})
+
+// When updating name, the transformer will be applied
+qstate.updateValue('name', () => 'hello') // Stores 'HELLO'
+```
+
+### With LocalStorage Caching
+
+Enable caching to persist state across page reloads:
+
+```typescript
+const qstate = new Q_StateEngine({
+  count: 0,
+  name: 'Amarix'
+}, {
+  name: (raw) => console.log(raw)
+}, {
+  cache: true // Enable localStorage caching
+})
+```
+
+### Nested Updates
+
+You can update multiple state values in a single update function:
+
+```typescript
+<button onClick={() => qstate.updateValue('name', () => {
+  qstate.updateValue('count', () => 5) // Nested update
+  return 'helo :3'
+})}>
+  Update Name
+</button>
+```
+
+## API
+
+### Constructor
+
+```typescript
+new Q_StateEngine<T, O>(state: T, transformer?: O, option?: OptionRecord)
+```
+
+- **state** (T): Initial state object with type safety
+- **transformer** (O, optional): Record of transformer functions for specific keys
+- **option** (OptionRecord, optional): Configuration options
+  - `cache`: Enable localStorage caching (default: false)
+
+### Methods
+
+#### `updateValue(key, func)`
+
+Updates a state value using an updater function.
+
+```typescript
+qstate.updateValue('count', (prev) => prev + 1)
+```
+
+- **key**: The state key to update
+- **func**: Updater function that receives the current value and returns the new value
+
+#### `useQuantaState(key)`
+
+React hook for subscribing to state changes.
+
+```typescript
+const [value] = qstate.useQuantaState('key')
+```
+
+Returns a tuple with the current value. The component re-renders when the specified key changes.
+
+## TypeScript
+
+The library provides full type safety:
+
+```typescript
+interface AppState {
+  count: number
+  name: string
+  items: string[]
+}
+
+const qstate = new Q_StateEngine<AppState>({
+  count: 0,
+  name: '',
+  items: []
+})
+
+// Type-safe updates
+qstate.updateValue('count', (prev) => prev + 1) // ✓
+qstate.updateValue('name', () => 'Hello')      // ✓
+qstate.updateValue('items', (prev) => [...prev, 'new']) // ✓
+```
+
+## How It Works
+
+1. **State Storage**: State is stored in a private object within the Q_StateEngine instance
+2. **Subscription**: Uses React's `useSyncExternalStore` for concurrent-safe subscriptions
+3. **Updates**: When `updateValue` is called, it:
+   - Executes the updater function with the current value
+   - Runs the transformer function (if defined)
+   - Updates the internal state
+   - Persists to localStorage (if caching enabled)
+   - Notifies all subscribers
+4. **Caching**: On initial render, checks localStorage for cached values and hydrates state
+
+## License
+
+MIT

package/dist/Q-State-Engine.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Q_StateEngine = void 0;
+var react_1 = require("react");
+var Q_StateEngine = /** @class */ (function () {
+    function Q_StateEngine(state, transformer, option) {
+        var _this = this;
+        this.subsribe = function (cb) {
+            _this.listener.add(cb);
+            return function () { return _this.listener.delete(cb); };
+        };
+        this.updateValue = function (key, func) {
+            var _a;
+            var executeFunc = func(_this.obj[key]);
+            var transformData = (_this.transformer && _this.transformer[key])
+                ? _this.transformer[key](executeFunc)
+                : executeFunc;
+            // Kita ambil saja data hasil update jika data dari layer transformer nya undefined
+            var finalData = transformData !== null && transformData !== void 0 ? transformData : executeFunc;
+            _this.obj[key] = finalData;
+            if ((_a = _this.option) === null || _a === void 0 ? void 0 : _a.cache)
+                localStorage.setItem(key, JSON.stringify(_this.obj[key]));
+            _this.listener.forEach(function (cb) { return cb(); });
+        };
+        this.useQuantaState = function (key) {
+            var getCurr = function () {
+                var _a;
+                if (((_a = _this.option) === null || _a === void 0 ? void 0 : _a.cache) && typeof window !== "undefined") {
+                    var getcache = localStorage.getItem(key);
+                    if (getcache !== null && getcache !== 'undefined') {
+                        var dataFromCache = '';
+                        try {
+                            dataFromCache = JSON.parse(getcache);
+                        }
+                        catch (_b) {
+                            dataFromCache = _this.obj[key];
+                        }
+                        if (dataFromCache !== _this.obj[key]) {
+                            _this.obj[key] = dataFromCache;
+                        }
+                    }
+                }
+                return _this.obj[key];
+            };
+            var syncSpecificData = (0, react_1.useSyncExternalStore)(_this.subsribe, getCurr);
+            return [syncSpecificData];
+        };
+        this.obj = state;
+        this.transformer = transformer;
+        this.listener = new Set();
+        this.option = option;
+    }
+    return Q_StateEngine;
+}());
+exports.Q_StateEngine = Q_StateEngine;

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@quanta-lib/q-state",
+  "version": "1.0.1",
+  "description": "A lightweight React state management library using `useSyncExternalStore` with optional localStorage caching and value transformation.",
+  "main": "dist/Q-State-Engine.js",
+  "types": "src/Q-State-Engine.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "state management",
+    "global state",
+    "quanta",
+    "state"
+  ],
+  "author": "quanta-lib",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Q-State-Engine.ts

@@ -0,0 +1,64 @@
+import { useSyncExternalStore } from "react"
+
+interface OptionRecord {
+  cache: boolean
+}
+
+export class Q_StateEngine
+  <T extends Record<string, any>, 
+  O extends Partial<Record<keyof T, (raw: any) => any>>> 
+{
+  private listener: Set<() => void>
+  private obj: T // Type-safe Map sesuai skema T
+  private transformer: O
+  private option?: OptionRecord
+
+  constructor(state: T, transformer?: O, option?: OptionRecord) {
+      this.obj = state
+      this.transformer = transformer as any
+      this.listener = new Set()
+      this.option = option
+  }
+
+  private subsribe = (cb: any) => {
+      this.listener.add(cb)
+      return () => this.listener.delete(cb)
+  }
+
+  updateValue = <K extends keyof T>(key: K, func: (prev: T[K]) => T[K]) => {
+      const executeFunc = func(this.obj[key])
+      const transformData = (this.transformer && this.transformer[key]) 
+        ? this.transformer[key](executeFunc) 
+        : executeFunc
+      // Kita ambil saja data hasil update jika data dari layer transformer nya undefined
+      const finalData = transformData ?? executeFunc      
+      this.obj[key] = finalData
+      if(this.option?.cache) localStorage.setItem(key as string, JSON.stringify(this.obj[key]))
+      this.listener.forEach(cb => cb())
+  }
+
+useQuantaState = <K extends keyof T>(key: K): [T[K]] => {
+    const getCurr = () => {
+      if (this.option?.cache && typeof window !== "undefined") {
+        const getcache = localStorage.getItem(key as string)
+        if (getcache !== null && getcache !== 'undefined') {
+          let dataFromCache = ''
+            try {
+              dataFromCache = JSON.parse(getcache)
+            } catch {
+              dataFromCache = this.obj[key]
+            }
+          if (dataFromCache !== this.obj[key]) {
+            this.obj[key] = dataFromCache as any
+          }
+        }
+      }
+      return this.obj[key]
+    }
+    const syncSpecificData = useSyncExternalStore(
+      this.subsribe,
+      getCurr
+    )
+    return [syncSpecificData]
+  }
+}