@biglogic/rgs 3.5.1 → 3.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +323 -304
- package/package.json +5 -5
- package/rgs-extension.vsix +0 -0
package/README.md
CHANGED
|
@@ -1,304 +1,323 @@
|
|
|
1
|
-
# Argis (RGS) - Reactive Global State
|
|
2
|
-
|
|
3
|
-
> "The Magnetar" **Atomic Precision. Immutable Safety. Zen Simplicity.**
|
|
4
|
-
> The most powerful state management engine for React. Built for those who demand industrial-grade reliability with a zero-boilerplate experience.
|
|
5
|
-
|
|
6
|
-
[](https://opensource.org/licenses/MIT)
|
|
7
|
-
[](https://npmjs.org/package/@biglogic/rgs)
|
|
8
|
-
[](https://npmjs.org/package/@biglogic/rgs)
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
 - Reactive Global State
|
|
2
|
+
|
|
3
|
+
> "The Magnetar" **Atomic Precision. Immutable Safety. Zen Simplicity.**
|
|
4
|
+
> The most powerful state management engine for React. Built for those who demand industrial-grade reliability with a zero-boilerplate experience.
|
|
5
|
+
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
[](https://npmjs.org/package/@biglogic/rgs)
|
|
8
|
+
[](https://npmjs.org/package/@biglogic/rgs)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
<!-- [](https://a51.gitbook.io/rgs) -->
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 🌟 Why Magnetar?
|
|
27
|
+
|
|
28
|
+
We took the simplicity of **Reactive Global State (RGS)** and fused it with the architecture of a **High-Performance Kernel**. It's the only library that gives you:
|
|
29
|
+
|
|
30
|
+
- **💎 Absolute Immutability**: Powered by **Immer**. No more manual spreads. State is frozen by default.
|
|
31
|
+
- **🛡️ Industrial-Grade Safety**: Deep Proxy guards that throw `Forbidden Mutation` errors if you try to bypass the kernel.
|
|
32
|
+
- **🔌 Enterprise Ecosystem**: A real plugin architecture with 10+ official modules (Sync, Storage, DevTools, etc.).
|
|
33
|
+
- **⚛️ Power on Demand**: Advanced async and persistence tools isolated in the `advanced` export.
|
|
34
|
+
- **🏗️ Stellar Architecture**: Zero circular dependencies. Modular, clean, and 100% type-safe.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## gState vs useState
|
|
39
|
+
|
|
40
|
+
| Feature | useState | gState |
|
|
41
|
+
|---------|----------|--------|
|
|
42
|
+
| **Global state across components** | ❌ Need Context/props | ✅ Automatic sharing |
|
|
43
|
+
| **Provider wrapper** | ❌ Required | ✅ Not needed |
|
|
44
|
+
| **Persistence (localStorage)** | ❌ Manual | ✅ Built-in |
|
|
45
|
+
| **Data encryption** | ❌ | ✅ AES-256-GCM |
|
|
46
|
+
| **Multiple namespaces/stores** | ❌ | ✅ |
|
|
47
|
+
| **Plugins (Immer, Undo/Redo)** | ❌ | ✅ |
|
|
48
|
+
| **Audit logging** | ❌ | ✅ |
|
|
49
|
+
| **RBAC/GDPR consent** | ❌ | ✅ |
|
|
50
|
+
| **SSR/Hydration** | ❌ Manual | ✅ Automatic |
|
|
51
|
+
| **Computed values** | ❌ | ✅ |
|
|
52
|
+
|
|
53
|
+
### When to use what?
|
|
54
|
+
|
|
55
|
+
- **useState**: Local UI, single component, temporary state
|
|
56
|
+
- **gState**:
|
|
57
|
+
- Shared state across multiple components
|
|
58
|
+
- Persistent data (preferences, cart, authentication)
|
|
59
|
+
- Sensitive data (encryption)
|
|
60
|
+
- Advanced features (undo/redo, snapshots)
|
|
61
|
+
- Enterprise (audit, RBAC, GDPR)
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## ⚔️ The Arena: RGS vs The World
|
|
66
|
+
|
|
67
|
+
|Feature|**RGS (Argis)**|Zustand|Redux Toolkit|Recoil|
|
|
68
|
+
|:---|:---|:---|:---|:---|
|
|
69
|
+
| **Philosophy** | **Zen State** | Minimalist | Enterprise Flux | Atomic |
|
|
70
|
+
| **API Surface** | **1 Function** | Simple | Complex | Complex |
|
|
71
|
+
| **Mutations** | **Magic (Immer)** | Manual Spreads | Magic (Immer) | Manual |
|
|
72
|
+
| **Selectors** | ✅ **Type-Safe** | ✅ Functional | ✅ Functional | ⚠️ Selectors |
|
|
73
|
+
| **Security** | 🛡️ **AES-256 + RBAC** | ❌ None | ❌ Ecosystem | ❌ None |
|
|
74
|
+
| **Persistence** | 💾 **First-class** | 🔌 Middleware | 🔌 Middleware | 🔌 Effects |
|
|
75
|
+
| **Async** | ✅ **Atomic** | ✅ Async/Await | ✅ Thunks | ✅ Suspense |
|
|
76
|
+
| **Bundle Size** | **~2kB** | ~1kB | >10kB | >20kB |
|
|
77
|
+
|
|
78
|
+
> **RGS** is the only library on the market that treats **Security** and **Persistence** as first-class citizens.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
### Installation
|
|
83
|
+
|
|
84
|
+
```shell
|
|
85
|
+
npm install @biglogic/rgs
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
### Examples and guide
|
|
91
|
+
|
|
92
|
+
**[github.com/BigLogic-ca/rgs](https://github.com/BigLogic-ca/rgs)**
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 🏗️ Architecture
|
|
97
|
+
|
|
98
|
+
```mermaid
|
|
99
|
+
graph TB
|
|
100
|
+
subgraph API
|
|
101
|
+
A[gstate] --> D[IStore]
|
|
102
|
+
B[useStore] --> D
|
|
103
|
+
C[createStore] --> D
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
D --> E[Storage Adapter]
|
|
107
|
+
D --> F[Immer Proxy]
|
|
108
|
+
D --> G[Plugins]
|
|
109
|
+
D --> H[Security]
|
|
110
|
+
D --> I[Async Store]
|
|
111
|
+
|
|
112
|
+
E --> J[local]
|
|
113
|
+
E --> K[session]
|
|
114
|
+
E --> L[memory]
|
|
115
|
+
|
|
116
|
+
G --> M[UndoRedo]
|
|
117
|
+
G --> N[Sync]
|
|
118
|
+
G --> O[Schema]
|
|
119
|
+
G --> P[Analytics]
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Core Components
|
|
123
|
+
|
|
124
|
+
| Component | Description |
|
|
125
|
+
|-----------|-------------|
|
|
126
|
+
| **gstate()** | Creates store + hook in one line |
|
|
127
|
+
| **useStore()** | React hook for subscribing to state |
|
|
128
|
+
| **createStore()** | Classic store factory |
|
|
129
|
+
| **IStore** | Core interface with get/set/subscribe |
|
|
130
|
+
| **StorageAdapters** | local, session, memory persistence |
|
|
131
|
+
| **Plugins** | Immer, Undo/Redo, Sync, Schema, etc. |
|
|
132
|
+
| **Security** | Encryption, RBAC, GDPR consent |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Requirements
|
|
137
|
+
|
|
138
|
+
- **React 16.8+** (for hooks support)
|
|
139
|
+
- **React DOM**
|
|
140
|
+
|
|
141
|
+
## ⚡ Zero-Boilerplate Quickstart
|
|
142
|
+
|
|
143
|
+
### Path A: The Zen Way (Modular)
|
|
144
|
+
|
|
145
|
+
Best for modern applications. Clean imports, zero global pollution, **Type-Safe**.
|
|
146
|
+
|
|
147
|
+
```tsx
|
|
148
|
+
import { gstate } from '@biglogic/rgs'
|
|
149
|
+
|
|
150
|
+
// 1. Create a typed store hook
|
|
151
|
+
const useCounter = gstate({ count: 0, user: { name: 'Alice' } })
|
|
152
|
+
|
|
153
|
+
// 2. Use with Type-Safe Selectors (Preferred)
|
|
154
|
+
const count = useCounter(state => state.count)
|
|
155
|
+
const userName = useCounter(state => state.user.name)
|
|
156
|
+
|
|
157
|
+
// OR use string keys (Legacy)
|
|
158
|
+
const [count, setCount] = useCounter('count')
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Path B: The Classic Way (Global)
|
|
162
|
+
|
|
163
|
+
Best for shared state across the entire application.
|
|
164
|
+
|
|
165
|
+
```tsx
|
|
166
|
+
// 1. Initialize once
|
|
167
|
+
import { initState, useStore } from '@biglogic/rgs'
|
|
168
|
+
initState({ namespace: 'app' })
|
|
169
|
+
|
|
170
|
+
// 2. Use anywhere
|
|
171
|
+
const [user, setUser] = useStore('user')
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## 📚 Quick Examples
|
|
177
|
+
|
|
178
|
+
```tsx
|
|
179
|
+
const store = gstate({ theme: 'dark' }, "my-app")
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Encryption
|
|
183
|
+
|
|
184
|
+
```tsx
|
|
185
|
+
const secureStore = gstate({ token: 'xxx' }, { encoded: true })
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Undo/Redo
|
|
189
|
+
|
|
190
|
+
```tsx
|
|
191
|
+
const store = gstate({ count: 0 })
|
|
192
|
+
store._addPlugin(undoRedoPlugin({ limit: 50 }))
|
|
193
|
+
|
|
194
|
+
store.undo()
|
|
195
|
+
store.redo()
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Cross-Tab Sync
|
|
199
|
+
|
|
200
|
+
```tsx
|
|
201
|
+
const store = gstate({ theme: 'light' })
|
|
202
|
+
store._addPlugin(syncPlugin({ channelName: 'my-app' }))
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
```tsx
|
|
206
|
+
const store = gstate({ firstName: 'John', lastName: 'Doe' })
|
|
207
|
+
store.compute('fullName', (get) => `${get('firstName')} ${get('lastName')}`)
|
|
208
|
+
|
|
209
|
+
const [fullName] = store('fullName') // "John Doe"
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### Error Handling with onError
|
|
213
|
+
|
|
214
|
+
Handle errors gracefully with the `onError` callback - perfect for production apps:
|
|
215
|
+
|
|
216
|
+
```tsx
|
|
217
|
+
const store = gstate({ data: null }, {
|
|
218
|
+
onError: (error, context) => {
|
|
219
|
+
console.error(`Error in ${context.operation}:`, error.message)
|
|
220
|
+
// Send to error tracking service (Sentry, etc.)
|
|
221
|
+
}
|
|
222
|
+
})
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Size Limits (maxObjectSize & maxTotalSize)
|
|
226
|
+
|
|
227
|
+
Protect your app from memory issues with automatic size warnings:
|
|
228
|
+
|
|
229
|
+
```tsx
|
|
230
|
+
const store = gstate({ data: {} }, {
|
|
231
|
+
// Warn if single value exceeds 5MB (Default is 0/Disabled for performance)
|
|
232
|
+
maxObjectSize: 5 * 1024 * 1024,
|
|
233
|
+
// Warn if total store exceeds 50MB (Default is 0/Disabled)
|
|
234
|
+
maxTotalSize: 50 * 1024 * 1024
|
|
235
|
+
})
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## Multiple Stores
|
|
241
|
+
|
|
242
|
+
You can create multiple independent stores using namespaces:
|
|
243
|
+
|
|
244
|
+
```tsx
|
|
245
|
+
// Option 1: gstate with namespace
|
|
246
|
+
const userStore = gstate({ name: 'John' }, { namespace: 'users' })
|
|
247
|
+
const appStore = gstate({ theme: 'dark' }, { namespace: 'app' })
|
|
248
|
+
|
|
249
|
+
// In components - same key, different stores
|
|
250
|
+
const [name] = userStore('name') // 'John'
|
|
251
|
+
const [theme] = appStore('theme') // 'dark'
|
|
252
|
+
|
|
253
|
+
// Option 2: initState + useStore (global default store)
|
|
254
|
+
initState({ namespace: 'global' })
|
|
255
|
+
const [value, setValue] = useStore('key')
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
**Tip**: Keys are unique per-namespace, so you can use the same key name in different stores.
|
|
259
|
+
|
|
260
|
+
## 🚀 Advanced Superpowers
|
|
261
|
+
|
|
262
|
+
### 🔌 Official Plugin Ecosystem
|
|
263
|
+
|
|
264
|
+
Extend the core functionality dynamically with specialized modules.
|
|
265
|
+
|
|
266
|
+
1. **ImmerPlugin**: Adds `setWithProduce` for functional updates.
|
|
267
|
+
2. **UndoRedoPlugin**: Multi-level history management.
|
|
268
|
+
3. **PersistencePlugin**: Advanced storage with custom serialization.
|
|
269
|
+
4. **SyncPlugin**: Cross-tab state synchronization via BroadcastChannel.
|
|
270
|
+
5. **SchemaPlugin**: Runtime validation (perfect for Zod).
|
|
271
|
+
6. **DevToolsPlugin**: Redux DevTools integration.
|
|
272
|
+
7. **TTLPlugin**: Time-to-live management.
|
|
273
|
+
8. **AnalyticsPlugin**: Tracking bridge for metrics.
|
|
274
|
+
9. **SnapshotPlugin**: Manual state checkpointing.
|
|
275
|
+
10. **GuardPlugin**: Data transformation layer.
|
|
276
|
+
|
|
277
|
+
```typescript
|
|
278
|
+
import { createStore, PersistencePlugin, undoRedoPlugin } from '@biglogic/rgs'
|
|
279
|
+
|
|
280
|
+
const store = createStore()
|
|
281
|
+
store._addPlugin(PersistencePlugin({ storage: 'localStorage' }))
|
|
282
|
+
store._addPlugin(undoRedoPlugin({ limit: 50 }))
|
|
283
|
+
|
|
284
|
+
// Undo like a pro
|
|
285
|
+
store.undo()
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
### 🔬 Power Tools (Import from `rgs/advanced`)
|
|
289
|
+
|
|
290
|
+
Need the heavy artillery? We've got you covered.
|
|
291
|
+
|
|
292
|
+
- `createAsyncStore(fetcher)`: Atomic async state management.
|
|
293
|
+
- `StorageAdapters`: High-level interfaces for any storage engine.
|
|
294
|
+
- `Middleware / IPlugin`: Build your own extensions.
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
## 🛡️ Quality & Testing
|
|
299
|
+
|
|
300
|
+
RGS is built with an obsession for reliability. Our test suite covers multiple layers to ensure zero-regressions:
|
|
301
|
+
|
|
302
|
+
- **Unit Tests (Jest)**: 100+ tests covering core logic, stores, and hooks.
|
|
303
|
+
- **E2E Tests (Playwright)**: Real-world browser testing for cross-tab synchronization and Web Crypto API.
|
|
304
|
+
- **Concurrency Testing**: Verification of race conditions in multi-tab environments.
|
|
305
|
+
|
|
306
|
+
```bash
|
|
307
|
+
# Run unit tests
|
|
308
|
+
npm run test
|
|
309
|
+
|
|
310
|
+
# Run E2E tests
|
|
311
|
+
npm run test:e2e
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
---
|
|
315
|
+
|
|
316
|
+
## 📄 License
|
|
317
|
+
|
|
318
|
+
MIT © [Dario Passariello](https://github.com/dpassariello)
|
|
319
|
+
|
|
320
|
+
---
|
|
321
|
+
|
|
322
|
+
**Designed for those who build the future.**
|
|
323
|
+
Made with ❤️ and a lot of caffe' espresso!
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@biglogic/rgs",
|
|
3
|
-
"version": "3.5.
|
|
3
|
+
"version": "3.5.2",
|
|
4
4
|
"description": "Argis (RGS) - Reactive Global State: A react state everywhere made easy",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"keywords": [
|
|
@@ -49,9 +49,6 @@
|
|
|
49
49
|
"npm:pack": "npm run build && cd dist && npm pack",
|
|
50
50
|
"npm:publish": "npm run build && npm run build:extension && cd dist && npm publish --access=public"
|
|
51
51
|
},
|
|
52
|
-
"dependencies": {
|
|
53
|
-
"immer": "^11.1.4"
|
|
54
|
-
},
|
|
55
52
|
"peerDependencies": {
|
|
56
53
|
"react": ">=16.8.0",
|
|
57
54
|
"react-dom": ">=16.8.0"
|
|
@@ -64,12 +61,15 @@
|
|
|
64
61
|
"optional": false
|
|
65
62
|
}
|
|
66
63
|
},
|
|
64
|
+
"dependencies": {
|
|
65
|
+
"immer": "^11.1.4"
|
|
66
|
+
},
|
|
67
67
|
"devDependencies": {
|
|
68
|
+
"memorio": "^2.2.1",
|
|
68
69
|
"@types/jest": "30.0.0",
|
|
69
70
|
"@types/node": "^25.3.0",
|
|
70
71
|
"@types/react": "^19.2.14",
|
|
71
72
|
"@types/react-dom": "^19.2.3",
|
|
72
|
-
"dphelper": "^2.6.4",
|
|
73
73
|
"esbuild": "^0.27.3",
|
|
74
74
|
"esbuild-plugin-copy": "^2.1.1",
|
|
75
75
|
"react": "^19.2.4",
|
package/rgs-extension.vsix
CHANGED
|
Binary file
|