@biglogic/rgs 3.7.6 → 3.7.9

package/docs/chapters/10-local-first-sync.md

@@ -1,146 +1,146 @@
-# 🚀 Chapter 10: Local-First Sync Engine
-
-RGS now includes a powerful **Local-First Sync Engine** that makes your app work offline by default and automatically synchronize when connectivity is restored.
-
-## Why Local-First?
-
-Traditional apps require an internet connection to work. Local-First apps work immediately with local data and sync in the background when possible.
-
-### Benefits
-
-- **Instant Load** - No waiting for server responses
-- **Works Offline** - App functions without internet
-- **Better UX** - No loading spinners for data
-- **Conflict Resolution** - Smart merge strategies
-
-## Quick Start
-
-```typescript
-import { gstate, useSyncedState } from '@biglogic/rgs'
-
-// Create store with sync enabled
-const store = gstate({
-  todos: [],
-  user: null
-}, {
-  namespace: 'myapp',
-  sync: {
-    endpoint: 'https://api.example.com/sync',
-    // Use a getter function for secure token retrieval
-    authToken: () => localStorage.getItem('auth_token'),
-    autoSyncInterval: 30000,  // Sync every 30s
-    syncOnReconnect: true    // Auto-sync when back online
-  }
-})
-
-// Use in React components
-function TodoList() {
-  const [todos, setTodos] = useSyncedState('todos')
-
-  // Add todo - automatically queued for sync
-  const addTodo = (text) => {
-    setTodos([...todos, { id: Date.now(), text }])
-  }
-
-  return <div>{/* ... */}</div>
-}
-```
-
-## Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `endpoint` | `string` | required | Remote sync server URL |
-| `authToken` | `string` or `() => string \| null` | - | Authentication token or getter function for secure retrieval |
-| `strategy` | `string` | `'last-write-wins'` | Conflict resolution |
-| `autoSyncInterval` | `number` | `30000` | Auto-sync interval (ms) |
-| `syncOnReconnect` | `boolean` | `true` | Sync on network restore |
-| `debounceTime` | `number` | `1000` | Batch changes (ms) |
-| `maxRetries` | `number` | `3` | Failed sync retries |
-| `onConflict` | `function` | - | Custom conflict handler |
-| `onSync` | `function` | - | Sync completion callback |
-
-## Conflict Resolution Strategies
-
-### 1. Last-Write-Wins (Default)
-
-```typescript
-sync: { strategy: 'last-write-wins' }
-```
-Latest timestamp wins - simplest strategy.
-
-### 2. Server-Wins
-
-```typescript
-sync: { strategy: 'server-wins' }
-```
-Always prefer remote values - useful for read-heavy apps.
-
-### 3. Client-Wins
-
-```typescript
-sync: { strategy: 'client-wins' }
-```
-Always prefer local values - useful for write-heavy apps.
-
-### 4. Custom Merge
-
-```typescript
-sync: {
-  strategy: 'merge',
-  onConflict: (conflict) => {
-    // Custom logic for merging
-    return {
-      action: 'merge',
-      value: { /* merged result */ }
-    }
-  }
-}
-```
-
-## Hook API
-
-### useSyncedState
-
-```typescript
-const [value, setValue, syncState] = useSyncedState('key')
-
-// syncState contains:
-// - isOnline: boolean
-// - isSyncing: boolean
-// - pendingChanges: number
-// - conflicts: number
-```
-
-### useSyncStatus
-
-```typescript
-const status = useSyncStatus()
-// Global sync status across all stores
-```
-
-## Manual Sync Control
-
-```typescript
-// Force sync
-await store.plugins.sync.flush()
-
-// Get sync state
-const state = store.plugins.sync.getState()
-```
-
-## Integration with Persistence
-
-The Sync Engine works seamlessly with RGS's existing persistence layer:
-
-- **Local Storage** - Data persists locally first
-- **IndexedDB** - For larger datasets
-- **Cloud Sync** - Optional remote backup
-
-Your data survives browser refresh, works offline, and stays synchronized across devices.
-
-## Next Steps
-
-- Learn about [Security Architecture](09-security-architecture.md)
-- Explore [Plugin SDK](05-plugin-sdk.md)
-- Check [Migration Guide](08-migration-guide.md)
+# 🚀 Chapter 10: Local-First Sync Engine
+
+RGS now includes a powerful **Local-First Sync Engine** that makes your app work offline by default and automatically synchronize when connectivity is restored.
+
+## Why Local-First?
+
+Traditional apps require an internet connection to work. Local-First apps work immediately with local data and sync in the background when possible.
+
+### Benefits
+
+- **Instant Load** - No waiting for server responses
+- **Works Offline** - App functions without internet
+- **Better UX** - No loading spinners for data
+- **Conflict Resolution** - Smart merge strategies
+
+## Quick Start
+
+```typescript
+import { gstate, useSyncedState } from '@biglogic/rgs'
+
+// Create store with sync enabled
+const store = gstate({
+  todos: [],
+  user: null
+}, {
+  namespace: 'myapp',
+  sync: {
+    endpoint: 'https://api.example.com/sync',
+    // Use a getter function for secure token retrieval
+    authToken: () => localStorage.getItem('auth_token'),
+    autoSyncInterval: 30000,  // Sync every 30s
+    syncOnReconnect: true    // Auto-sync when back online
+  }
+})
+
+// Use in React components
+function TodoList() {
+  const [todos, setTodos] = useSyncedState('todos')
+
+  // Add todo - automatically queued for sync
+  const addTodo = (text) => {
+    setTodos([...todos, { id: Date.now(), text }])
+  }
+
+  return <div>{/* ... */}</div>
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `endpoint` | `string` | required | Remote sync server URL |
+| `authToken` | `string` or `() => string \| null` | - | Authentication token or getter function for secure retrieval |
+| `strategy` | `string` | `'last-write-wins'` | Conflict resolution |
+| `autoSyncInterval` | `number` | `30000` | Auto-sync interval (ms) |
+| `syncOnReconnect` | `boolean` | `true` | Sync on network restore |
+| `debounceTime` | `number` | `1000` | Batch changes (ms) |
+| `maxRetries` | `number` | `3` | Failed sync retries |
+| `onConflict` | `function` | - | Custom conflict handler |
+| `onSync` | `function` | - | Sync completion callback |
+
+## Conflict Resolution Strategies
+
+### 1. Last-Write-Wins (Default)
+
+```typescript
+sync: { strategy: 'last-write-wins' }
+```
+Latest timestamp wins - simplest strategy.
+
+### 2. Server-Wins
+
+```typescript
+sync: { strategy: 'server-wins' }
+```
+Always prefer remote values - useful for read-heavy apps.
+
+### 3. Client-Wins
+
+```typescript
+sync: { strategy: 'client-wins' }
+```
+Always prefer local values - useful for write-heavy apps.
+
+### 4. Custom Merge
+
+```typescript
+sync: {
+  strategy: 'merge',
+  onConflict: (conflict) => {
+    // Custom logic for merging
+    return {
+      action: 'merge',
+      value: { /* merged result */ }
+    }
+  }
+}
+```
+
+## Hook API
+
+### useSyncedState
+
+```typescript
+const [value, setValue, syncState] = useSyncedState('key')
+
+// syncState contains:
+// - isOnline: boolean
+// - isSyncing: boolean
+// - pendingChanges: number
+// - conflicts: number
+```
+
+### useSyncStatus
+
+```typescript
+const status = useSyncStatus()
+// Global sync status across all stores
+```
+
+## Manual Sync Control
+
+```typescript
+// Force sync
+await store.plugins.sync.flush()
+
+// Get sync state
+const state = store.plugins.sync.getState()
+```
+
+## Integration with Persistence
+
+The Sync Engine works seamlessly with RGS's existing persistence layer:
+
+- **Local Storage** - Data persists locally first
+- **IndexedDB** - For larger datasets
+- **Cloud Sync** - Optional remote backup
+
+Your data survives browser refresh, works offline, and stays synchronized across devices.
+
+## Next Steps
+
+- Learn about [Security Architecture](09-security-architecture.md)
+- Explore [Plugin SDK](05-plugin-sdk.md)
+- Check [Migration Guide](08-migration-guide.md)

package/docs/qa.md

@@ -1,47 +1,47 @@
-# 🚀 QA Release Checklist: Massive Change
-
-> **Release ID:** [Insert ID]
-> **Date:** 2026-02-19
-> **QA Lead:** [Name]
-
----
-
-### 1. 🔍 Impact Analysis & Setup
-- [ ] **Traceability Matrix:** Mapping new requirements to existing test cases.
-- [ ] **Impact Analysis:** Identifying "High-Risk" modules (e.g., DB, API, Payment Gateway).
-- [ ] **Staging Environment:** Verify alignment of config/data with Production.
-- [ ] **Smoke Test Suite:** Selection of 10-15 fundamental tests to validate build stability.
-
-### 2. 🛡️ Regression & Functional Testing
-- [ ] **Critical Regression:** Execution of automated tests on core flows (Business Critical).
-- [ ] **New Features:** Detailed validation according to acceptance criteria (AC).
-- [ ] **Edge Cases:** Testing on invalid inputs and boundary scenarios.
-- [ ] **Compatibility:** Testing on Browsers (Chrome, Safari, Firefox) and Mobile (iOS, Android).
-
-### 3. ⚙️ Technical Integrity & Performance
-- [ ] **Data Migration:** Verify that DB changes haven't corrupted existing records.
-- [ ] **API Contracts:** Verify that endpoints haven't introduced breaking changes.
-- [ ] **Performance Baseline:** Check response times compared to the previous version.
-- [ ] **Security Scan:** Basic check on permissions and OWASP vulnerabilities.
-
-### 4. 🏁 Release Readiness (Go/No-Go)
-- [ ] **UAT Sign-off:** Final approval from stakeholders.
-- [ ] **Rollback Plan:** Documented and ready recovery procedure.
-- [ ] **Feature Flags:** Verify that toggles are correctly configured on [LaunchDarkly](https://launchdarkly.com) or similar.
-- [ ] **Monitoring:** [Sentry](https://sentry.io) or [Datadog](https://www.datadoghq.com) dashboards ready for post-live monitoring.
-
----
-
-### 📊 Execution Report
-
-
-| Category | Total Tests | Passed | Failed | Blockers |
-| :--- | :---: | :---: | :---: | :---: |
-| **Smoke Test** | 0 | 0 | 0 | 0 |
-| **Regression** | 0 | 0 | 0 | 0 |
-| **New Features**| 0 | 0 | 0 | 0 |
-
----
-
-**Final Notes:**
-*Add any critical bugs found or observations on stability here.*
+# 🚀 QA Release Checklist: Massive Change
+
+> **Release ID:** [Insert ID]
+> **Date:** 2026-02-19
+> **QA Lead:** [Name]
+
+---
+
+### 1. 🔍 Impact Analysis & Setup
+- [ ] **Traceability Matrix:** Mapping new requirements to existing test cases.
+- [ ] **Impact Analysis:** Identifying "High-Risk" modules (e.g., DB, API, Payment Gateway).
+- [ ] **Staging Environment:** Verify alignment of config/data with Production.
+- [ ] **Smoke Test Suite:** Selection of 10-15 fundamental tests to validate build stability.
+
+### 2. 🛡️ Regression & Functional Testing
+- [ ] **Critical Regression:** Execution of automated tests on core flows (Business Critical).
+- [ ] **New Features:** Detailed validation according to acceptance criteria (AC).
+- [ ] **Edge Cases:** Testing on invalid inputs and boundary scenarios.
+- [ ] **Compatibility:** Testing on Browsers (Chrome, Safari, Firefox) and Mobile (iOS, Android).
+
+### 3. ⚙️ Technical Integrity & Performance
+- [ ] **Data Migration:** Verify that DB changes haven't corrupted existing records.
+- [ ] **API Contracts:** Verify that endpoints haven't introduced breaking changes.
+- [ ] **Performance Baseline:** Check response times compared to the previous version.
+- [ ] **Security Scan:** Basic check on permissions and OWASP vulnerabilities.
+
+### 4. 🏁 Release Readiness (Go/No-Go)
+- [ ] **UAT Sign-off:** Final approval from stakeholders.
+- [ ] **Rollback Plan:** Documented and ready recovery procedure.
+- [ ] **Feature Flags:** Verify that toggles are correctly configured on [LaunchDarkly](https://launchdarkly.com) or similar.
+- [ ] **Monitoring:** [Sentry](https://sentry.io) or [Datadog](https://www.datadoghq.com) dashboards ready for post-live monitoring.
+
+---
+
+### 📊 Execution Report
+
+
+| Category | Total Tests | Passed | Failed | Blockers |
+| :--- | :---: | :---: | :---: | :---: |
+| **Smoke Test** | 0 | 0 | 0 | 0 |
+| **Regression** | 0 | 0 | 0 | 0 |
+| **New Features**| 0 | 0 | 0 | 0 |
+
+---
+
+**Final Notes:**
+*Add any critical bugs found or observations on stability here.*

package/package.json

@@ -1,74 +1,91 @@
-{
-  "name": "@biglogic/rgs",
-  "version": "3.7.6",
-  "description": "Argis (RGS) - Reactive Global State: A react state everywhere made easy",
-  "type": "module",
-  "keywords": [
-    "rgs",
-    "gstate",
-    "state-management",
-    "react",
-    "enterprise",
-    "hooks",
-    "global-state",
-    "immer",
-    "biglogic",
-    "persistence",
-    "react-globo-state",
-    "argis"
-  ],
-  "homepage": "https://github.com/BigLogic-ca/rgs",
-  "bugs": {
-    "url": "https://github.com/BigLogic-ca/rgs/issues"
-  },
-  "license": "MIT",
-  "author": "Dario Passariello <dariopassariello@gmail.com>",
-  "contributors": [
-    {
-      "name": "Dario Passariello",
-      "email": "dariopassariello@gmail.com",
-      "url": "https://dario.passariello.ca/"
-    },
-    {
-      "name": "Valeria Cala Scaglitta",
-      "email": "valeriacalascaglitta@gmail.com"
-    }
-  ],
-  "funding": {
-    "type": "github",
-    "url": "https://github.com/BigLogic-ca/rgs"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/BigLogic-ca/rgs.git"
-  },
-  "main": "./index.js",
-  "types": "./index.d.ts",
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "scripts": {
-    "dev": "npm run build:watch",
-    "build": "node -e \"const fs=require('fs');if(fs.existsSync('./dist'))fs.rmSync('./dist',{recursive:true});\" && node ./esbuild.config.mjs && npx tsc -p tsconfig.json --emitDeclarationOnly",
-    "build:watch": "node ./esbuild.config.mjs --watch",
-    "build:extension": "cd vscode-extension && vsce package -o ../dist/rgs-extension.vsix",
-    "npm:pack": "npm run build && cd dist && npm pack",
-    "npm:publish": "npm run build && npm run build:extension && cd dist && npm publish --access=public",
-    "lint": "cd tests && npm run lint",
-    "tsc": "cd tests && tsc --noEmit",
-    "test": "cd tests && npm test"
-  },
-  "devDependencies": {
-    "@types/node": "^25.3.2",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "esbuild": "0.27.3",
-    "esbuild-node-externals": "1.20.1",
-    "esbuild-plugin-copy": "2.1.1",
-    "immer": "11.1.4",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "tslib": "^2.8.1",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "@biglogic/rgs",
+  "version": "3.7.9",
+  "license": "MIT",
+  "description": "Argis (RGS) - Reactive Global State: A react state everywhere made easy",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "typings": "./types/*",
+  "homepage": "https://github.com/BigLogic-ca/rgs",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "files": [
+    "**/*"
+  ],
+  "keywords": [
+    "rgs",
+    "gstate",
+    "state-management",
+    "react",
+    "enterprise",
+    "hooks",
+    "global-state",
+    "immer",
+    "biglogic",
+    "persistence",
+    "react-globo-state",
+    "argis"
+  ],
+  "copyright": "Dario Passariello",
+  "author": "Dario Passariello <dariopassariello@gmail.com>",
+  "contributors": [
+    {
+      "name": "Dario Passariello",
+      "email": "dariopassariello@gmail.com",
+      "url": "https://dario.passariello.ca/"
+    },
+    {
+      "name": "Valeria Cala Scaglitta",
+      "email": "valeriacalascaglitta@gmail.com"
+    }
+  ],
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/BigLogic-ca/rgs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BigLogic-ca/rgs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BigLogic-ca/rgs/issues"
+  },
+  "support": {
+    "name": "Dario Passariello",
+    "url": "https://github.com/passariello/",
+    "email": "dariopassariello@gmail.com"
+  },
+  "scripts": {
+    "dev": "npm run build:watch",
+    "build": "node -e \"const fs=require('fs');if(fs.existsSync('./dist'))fs.rmSync('./dist',{recursive:true});\" && node ./esbuild.config.mjs && npx tsc -p tsconfig.json --emitDeclarationOnly",
+    "build:watch": "node ./esbuild.config.mjs --watch",
+    "build:extension": "cd vscode-extension && vsce package -o ../dist/rgs-extension.vsix",
+    "npm:pack": "npm run build && cd dist && npm pack",
+    "npm:publish": "npm run build && npm run build:extension && cd dist && npm publish --access=public",
+    "lint": "cd tests && npm run lint",
+    "tsc": "cd tests && tsc --noEmit",
+    "test": "cd tests && npm test"
+  },
+  "dependencies": {
+    "immer": "11.1.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "0.27.3",
+    "esbuild-node-externals": "1.20.1",
+    "esbuild-plugin-copy": "2.1.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3"
+  }
+}