feat(react): add React integration with automatic re-rendering ⚛️

- Add React middleware with useReactStateless hook
- Add React-specific build entry point and exports
- Add React peer dependency configuration
- Update documentation with React usage examples
- Bump version to 0.2.0 for React support

Author: NeaByteLab

README.md

@@ -5,7 +5,11 @@ A universal and lightweight state management library with a clean, stateless API
 ## 📦 Installation
 
 ```bash
+# Universal (works everywhere)
 npm install @neabyte/stateless-js
+
+# React (with automatic re-renders)
+npm install @neabyte/stateless-js react
 ```
 
 ## 🔧 Module Support
@@ -15,12 +19,14 @@ npm install @neabyte/stateless-js
 // CommonJS
 const { createStateless, useStateless } = require('@neabyte/stateless-js')
 
-// ESM (ES Modules)
+// React (automatic re-renders)
+import { useReactStateless } from '@neabyte/stateless-js/react'
+
+// Universal (works everywhere)
 import { createStateless, useStateless } from '@neabyte/stateless-js'
 
 // TypeScript types
 import type { StateSetter, StateValue } from '@neabyte/stateless-js'
-
 ```
 
 ### 🌐 Browser
@@ -38,7 +44,7 @@ import type { StateSetter, StateValue } from '@neabyte/stateless-js'
 
 ## 🚀 Usage
 
-### 📝 Basic Usage
+### 📝 Universal Usage
 
 ```typescript
 import { createStateless, useStateless } from '@neabyte/stateless-js'
@@ -52,19 +58,44 @@ setCount(current => current + 1)
 console.log(count.value) // 1
 ```
 
-### 🔄 Using Existing States
+### ⚛️ React Usage
 
 ```typescript
-// Create state
-const [setUser, user] = createStateless('user', { name: 'John', age: 25 })
+import { useReactStateless } from '@neabyte/stateless-js/react'
+
+function Counter() {
+  const [setCount, count] = useReactStateless('counter', 0)
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => setCount(c => c + 1)}>
+        Increment
+      </button>
+    </div>
+  )
+}
+```
+
+### 🔄 State Sharing (Universal & React)
 
-// Use existing state (reuses the same state)
+```typescript
+// Universal
+const [setUser, user] = createStateless('user', { name: 'John', age: 25 })
 const [setUser2, user2] = useStateless('user', { name: 'Default', age: 0 })
 console.log(user.value === user2.value) // true - same state
 
-// Both references update the same state
-setUser(current => ({ ...current, age: 26 }))
-console.log(user2.value.age) // 26
+// React - Multiple components share the same state
+function UserProfile() {
+  const [setUser, user] = useReactStateless('user', { name: 'John', age: 25 })
+  return <div>Name: {user.name}, Age: {user.age}</div>
+}
+
+function UserEditor() {
+  const [setUser, user] = useReactStateless('user', { name: 'Default', age: 0 })
+  return <button onClick={() => setUser(u => ({ ...u, age: u.age + 1 }))}>
+    Increase Age
+  </button>
+}
 ```
 
 ### 🎯 Different Data Types
@@ -120,27 +151,41 @@ try {
 
 ## 📚 API Reference
 
-### `createStateless<T>(id: StateId, initialState: T): StatelessReturn<T>`
+### Universal Functions
+
+#### `createStateless<T>(id: StateId, initialState: T): StatelessReturn<T>`
 
 Creates a new state with the given ID and initial value.
 
 - `id`: Unique identifier (string or number)
 - `initialState`: Initial value for the state
 - Returns: Tuple `[StateSetter<T>, StateValue<T>]`
 
-### `useStateless<T>(id: StateId, fallbackState: T): StatelessReturn<T>`
+#### `useStateless<T>(id: StateId, fallbackState: T): StatelessReturn<T>`
 
 Uses existing state if it exists, otherwise creates a new one.
 
 - `id`: Unique identifier (string or number)
 - `fallbackState`: Value to use if state doesn't exist
 - Returns: Tuple `[StateSetter<T>, StateValue<T>]`
 
-### `StateSetter<T>`
+### React Functions
+
+#### `useReactStateless<T>(id: StateId, initialValue: T): [StateSetter<T>, T]`
+
+React hook that provides automatic re-renders when state changes.
+
+- `id`: Unique identifier (string or number)
+- `initialValue`: Initial value for the state
+- Returns: Tuple `[StateSetter<T>, T]` (direct value, not StateValue object)
+
+### Types
+
+#### `StateSetter<T>`
 
 Function to update state: `(updater: StateUpdater<T>) => void`
 
-### `StateValue<T>`
+#### `StateValue<T>`
 
 Object with:
 - `value`: Current state value (readonly)

build.config.ts

@@ -13,7 +13,7 @@ import { resolve } from 'path'
  */
 export default defineBuildConfig({
   /** @type {string[]} Entry points for the build process */
-  entries: ['src/index'],
+  entries: ['src/index', 'src/react'],
   /** @type {boolean} Whether to generate TypeScript declaration files */
   declaration: true,
   /** @type {boolean} Whether to clean the output directory before building */
@@ -28,7 +28,9 @@ export default defineBuildConfig({
     /** @type {string} Alias for core directory */
     '@core': resolve(__dirname, 'src/core'),
     /** @type {string} Alias for interfaces directory */
-    '@interfaces': resolve(__dirname, 'src/interfaces')
+    '@interfaces': resolve(__dirname, 'src/interfaces'),
+    /** @type {string} Alias for middlewares directory */
+    '@middlewares': resolve(__dirname, 'src/middlewares')
   },
   rollup: {
     emitCJS: true,

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@neabyte/stateless-js",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A universal and lightweight state management library with a clean, stateless API",
   "type": "module",
   "main": "dist/index.cjs",
@@ -11,6 +11,11 @@
       "require": "./dist/index.cjs",
       "import": "./dist/index.mjs",
       "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "require": "./dist/react.cjs",
+      "import": "./dist/react.mjs",
+      "types": "./dist/react.d.ts"
     }
   },
   "scripts": {
@@ -54,6 +59,7 @@
   "devDependencies": {
     "@eslint/js": "^9.37.0",
     "@types/node": "^24.7.2",
+    "@types/react": "^19.2.2",
     "@typescript-eslint/eslint-plugin": "^8.46.0",
     "@typescript-eslint/parser": "^8.46.0",
     "eslint": "^9.37.0",
@@ -65,8 +71,13 @@
     "typescript": "^5.9.3",
     "unbuild": "^3.6.1"
   },
-  "engines": {
-    "node": ">=22.0.0"
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "files": [
     "dist/**/*",

package.json

@@ -0,0 +1,5 @@
+/**
+ * Re-export all middleware functions
+ * @description Re-export all middleware functions from their respective files.
+ */
+export * from '@middlewares/react/index'

src/middlewares/index.ts

@@ -0,0 +1,54 @@
+import type { StateSetter, StateValue } from '@interfaces/index'
+import { useEffect, useState } from 'react'
+import { useStateless } from '@root/index'
+
+/** Map storing React subscribers for each state ID */
+const reactSubscribers: Map<string, Set<() => void>> = new Map<string, Set<() => void>>()
+
+/**
+ * Notifies all React subscribers for a given state ID.
+ * @param id - State identifier to notify subscribers for
+ */
+function notifyReactSubscribers(id: string): void {
+  const subscribers: Set<() => void> | undefined = reactSubscribers.get(id)
+  if (subscribers) {
+    subscribers.forEach((callback: () => void): void => {
+      callback()
+    })
+  }
+}
+
+/**
+ * React hook for using stateless state with automatic re-rendering.
+ * @param id - Unique identifier for the state
+ * @param initialValue - Initial value for the state
+ * @returns Tuple containing state setter and current state value
+ */
+export function useReactStateless<T>(
+  id: string,
+  initialValue: T
+): [(updater: (current: T) => T) => void, T] {
+  const [, forceUpdate]: [Record<string, never>, (value: Record<string, never>) => void] = useState<
+    Record<string, never>
+  >({})
+  useEffect((): (() => void) => {
+    if (!reactSubscribers.has(id)) {
+      reactSubscribers.set(id, new Set<() => void>())
+    }
+    const subscriber: () => void = (): void => {
+      forceUpdate({})
+    }
+    reactSubscribers.get(id)?.add(subscriber)
+    return (): void => {
+      reactSubscribers.get(id)?.delete(subscriber)
+    }
+  }, [id])
+  const [setState, state]: [StateSetter<T>, StateValue<T>] = useStateless(id, initialValue)
+  const reactiveSetter: (updater: (current: T) => T) => void = (
+    updater: (current: T) => T
+  ): void => {
+    setState(updater)
+    notifyReactSubscribers(id)
+  }
+  return [reactiveSetter, state.value]
+}

src/middlewares/react/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export React-specific stateless functionality
+ * @description React hook for stateless state management
+ */
+export { useReactStateless } from '@middlewares/index'